Catalina release 5.4 is a full release. You can install this over an existing version of Catalina, but it is recommended that you instead uninstall any previous Catalina release before installing, or install this release to a different location. The following sections list the changes that have been made since the recent releases of Catalina. If you have not used a previous release of Catalina, you can skip the rest of this README and instead go straight to the Catalina tutorial documents. If you prefer using a command line, start with "Getting Started with Catalina" If you prefer using an Integrated Development Environment, start with: "Getting Started with the Catalina Geany IDE" RELEASE 5.4 New Functionality ----------------- 1. Roger Loh's 16 Bit PSRAM driver has been added as a Catalina plugin. It is supported on the Propeller 2 only. It is enabled by linking with the new psram library (i.e. adding -lpsram to the Catalina command). An example of its use has been added in "demos\examples\ex_psram.c". The configuration parameters for the driver must be specified in the platform files in the target_p2 directory, such as P2_EDGE.inc. You would compile the PSRAM example program with a command like: catalina -p2 -lc -lpsram -C P2_EDGE ex_psram.c The only tested platform is the P2 EDGE, and like the driver itself, Catalina's support for it should be considered a beta version until further notice. 2. As a demonstration of the use of the PSRAM plugin, Lua now has the option to store code in PSRAM on those platforms that support it, such as the P2 EDGE. This allows larger Lua programs to be executed at the cost of a slight speed reduction. Supported on the Propeller 2 only. To enable the use of PSRAM in Lua, specify ENABLE_PSRAM to the Catalyst or Lua build_all scripts. For example: build_all P2_EDGE SIMPLE VT100 ENABLE_PSRAM Note that PSRAM is supported only by the Lua execution engine (luax) which executes compiled Lua programs, and not for the interactive version (lua) that executes text programs or the Multiprocessing version (mlua or mluax). So if ENABLE_PSRAM is specified, only luax will be built. This means you may need to build Lua twice - once to build the lua programs that do not use PSRAM, and then again to build luax (only) to use PSRAM. For example, to compile Lua in directory "demos\catalyst\lua-5.4.4" and put the executables in "demos\catalyst\bin" and call the PSRAM version luaxp rather than overwrite the standard luax binary, you might use commands such as: cd demos\catalyst\lua-5.4.4 build_all P2_EDGE SIMPLE VT100 copy src\*.bin ..\bin\ build_all P2_EDGE SIMPLE VT100 ENABLE_PSRAM copy src\luax.bin ..\bin\luaxp.bin Note that specifying ENABLE_PSRAM is applicable only when using the Catalyst and Lua build_all scripts and Makefiles - it is not a general Catalina symbol that can be used on the Catalina command-line to enable PSRAM in other cases (which is done via the usual mechanism of linking the program with the psram library - i.e. adding -lpsram to the catalina command). Finally, note that for small Lua programs, the Hub RAM usage of the PSRAM version may not be much smaller than that of the non-PSRAM version - it may even be larger. This is not only because of the additional PSRAM support code required, it is also because the PSRAM version allocates a fixed amount of Hub RAM on startup to use as a PSRAM cache, and for small Lua programs the cache may be larger than the program being loaded. However, the amount of Hub RAM used for Lua code will never increase beyond the cache size no matter how big the program code gets. 3. Catalyst on the Propeller 1 can now use the HIRES_VGA option. However, Hub RAM limitations mean that Catalyst itself needs to be built as an EEPROM program, and some of the Catalyst utilities may only work if they are built as LARGE programs. This means that while Catalyst itself will work in HIRES_VGA mode on all platforms, some utilities (such as cp & mv) may only work in HIRES_VGA mode on platforms with XMM RAM. Alternatively, you might build Catalyst itself in HIRES_VGA mode, but the utilities in LORES_VGA mode. To facilitate this, two new options have been added that can be used with the Catalyst build_all scripts: EEPROM_CATALYST specifies that the Catalyst binary should be built as an EEPROM program. LARGE_UTILITIES specifies that the Catalyst utilities should be built as LARGE programs. Whether you need to specify one or both of these options can depend on the other options used. For instance, if you need to use the cache to access XMM RAM, then you will generally need to use both of these options to build Catalyst in HIRES_VGA mode. For example, here is how you might build Catalyst to use HIRES_VGA on the C3: build_all C3 FLASH CACHED_1K HIRES_VGA EEPROM_CATALYST LARGE_UTILITIES When you build Catalyst to use LORES_VGA or HIRES_TV HMI option, you may also find that catalyst.binary exceeds the size of Hub RAM and in that case you can specify the EEPROM_CATALYST option, but you may not need the LARGE_UTILITIES option - e.g: build_all C3 FLASH CACHED_1K HIRES_TV EEPROM_CATALYST Note that to program Catalyst into EEPROM when the CATALYST_EEPROM option is used, you will need to run the build_utilities script to build the EEPROM loader, and then use that with payload. For example, to build and load Catalyst to use HIRES_VGA on the C3, you might use commands like: cd demos\catalyst build_all C3 FLASH CACHED_1K HIRES_VGA EEPROM_CATALYST LARGE_UTILITIES build_utilities payload -o1 EEPROM ..\bin\catalyst.bin Note that these new options are applicable only when using the Catalyst build_all scripts and Makefiles - they are not Catalina symbol that can be used in other circumstances (i.e. specifying -C EEPROM_CATALYST when compiling catalyst.c manually will not have any effect. It is the Makefile that intercepts this symbol and instead uses -C EEPROM, but only when building catalyst.binary). 4. The Catalyst ONCE capability (i.e. to execute a command once on reboot) has been extended to execute MORE than one command. If enabled when building Catalyst (by setting both ENABLE_ONCE and ENABLE_MORE to 1) then the file (EXECONCE.TXT by default) can contain more than one command. The commands in the file will be executed in sequence on successive reboots. The Lua "execute" function can be used to easily add multiple commands to the file, one per line. For example, if the MORE capability is enabled, the Lua statement: propeller.execute("vi abc\n vi def") will cause the propeller to first reboot and execute the command "vi abc", and then when vi exits, the propeller will reboot and execute the command "vi def". This also allows a very basic scripting capability to be implemented. For example, if you have a file called commands.txt which contains all the commands you want executed, then executing the command: cp command.txt execonce.txt at the Catalyst prompt, or executing the Lua statement: propeller.execute("cp command.txt execonce.txt") will cause all the commands in the file to be executed in sequence. Note that this capability is enabled by default on the Propeller 2, and on the Propeller 1 unless the HIRES_VGA HMI option is used, because there is not enough Hub RAM available. If you want to enable it, you may need to disable something else, such as the capability to allow Lua commands to be executed directly from the command line (note that you can still execute them by specifying them as parameters to Lua - e.g. by entering a command like "lua list.lua" instead of just "list"). This can be disabled by editing "demos\catalyst\core\catalyst.h" and rebuilding Catalyst. 5. The internal cat, dir and help commands have been removed from Catalyst. The help and cat commands are now always external. The dir command has simply been dropped since the ls command is far more capable. However, if you prefer typing "dir" to "ls", then just make a copy of "ls.bin" called "dir.bin" - i.e: cp ls.bin dir.bin 6. Added a new Lua demo called "wild.lua" that can be used to add wildcard capability to a Catalyst command that accepts multiple file names. For example, if the command specified in wild.lua is "vi" (which it is by default) then luac -o xvi.lux wild.lua will create a command "xvi" which can then be used on the command line to invoke vi on multiple files - e.g: xvi ex*.lua will execute vi on all the Lua example files. 7. The length of a Catalyst command line has been increased to 300 characters on the Propeller 1, and 1200 characters on the Propeller 2. Hub RAM is limited on the Propeller 1, but 300 is enough to accommodate 24 MSDOS 8.3 filenames, which could be generated when using wildcards, and 1200 is the maximum that CogStore can store. This maximises the potential usefulness of the wildcard functionality added in the last few releases. 8. A new "getrand()" function has been added to the C library. It is defined in "propeller.h" and is implemented on both the Propeller 1 and the Propeller 2 (but differently - see below). A program that demonstrates the use of the function has been added in "demos\examples\ex_random.c" On the Propeller 1, the first time this function is called it calls srand() with the current CNT value and is therefore best called after some user input or other random source of delay. It then returns the result of 3 combined calls to rand() to make up 32 random bits (rand itself only returns 15 bits). On the Propeller 2, the first time this function is called it calls srand() with the result of the GETRND opcode, and also returns that value. Thereafter it just returns the result of the GETRND opcode. This means you can either use just this function, or use this function once to generate a seed for srand() and thereafter use rand(), which is what most traditional C programs would typically do. Note that rand() only returns a value between 0 and RAND_MAX (inclusive) (i.e. 0 .. 32727 on the Propeller) whereas getrand() returns 32 bits. To simulate rand() using getrand(), use an expression like: (getrand() % (RAND_MAX + 1)) 9. On the P2_EDGE, the base pin for VGA has been changed to 0 (was 32), and the base pin for USB has been changed to 8 (was 40). This makes it possible to use the P2-ES VGA and USB accessory boards with Catalina on the P2_EDGE. The base pins can be edited if required in the file P2_EDGE.inc in the target_p2 folder. Other Changes ------------- 1. Fixed a bug in Catalina's code generator that meant statements like "x = x op y", where x was a complex lvalue (e.g. an element of an array) and op was + or - could cause the compilation to fail. Affected both the Propeller 1 and Propeller 2. 2. Fixed a bug in p2asm, which was not correctly processing a count of zero in BYTE, WORD or LONG statements - e.g: pad LONG 0[COUNT] ' should not generate any data if COUNT is zero Affected the Propeller 2 only. 3. Fixed a bug in p2asm, which did not understand the "!" operator (which should be interpreted as bitwise "NOT") - e.g: MOV r0,##!$21524110 ' should put $DEADBEEF into r0 Affected the Propeller 2 only. 4. Multi-Processing Lua example 12 (ex12.lua) has been reduced from using 5 factories (i.e. cogs) to 4. 5 cogs were not always available, depending on which HMI plugins that were loaded. Affected the Propeller 2 only. 5. Lua example list.lua was using the wrong value for the DOSFS "archived" file attribute. Affected both the Propeller 1 and Propeller 2. 6. Catalyst was supposed to be able to accept up to 24 command line arguments but in fact CogStore would only correctly process the first 12. Affected both the Propeller 1 and the Propeller 2. 7. Fixed an issue in some Makefiles intepreting the "-p2" flag when it was specified via the CATALINA_OPTIONS environment variable (which is mostly used by the Geany IDE to pass options to the Makefile). Affected the Propeller 2 only. 8. The Propeller 2 "Catalina_platforms.inc" configuration file was getting a bit unwieldy, so the platform constants have now been split into a separate file for each platform. The Catalina_platforms.inc file still exists but it now just includes one of the following include files to define the platform constants: P2_EVAL.inc P2_EDGE.inc P2D2.inc P2_CUSTOM.inc These are all in the target_p2 directory. The default if no platform is specified is to use P2_EVAL.inc, but this can be changed by editing Catalina_platforms.inc. 9. Lua 5.1.5, which was deprecated in previous releases, has been removed altogether from this release. 10. Some of the Catalyst demo programs were either not specifying NO_MOUSE, or were using -lmb when they could have used -lma. In most cases this was fine, but it meant some were using additional cogs unnecessarily, which prevented them running in HIRES_VGA mode (which takes one more cog than the other HMI options on the Propeller 1). Affected the Propeller 1 only. 11. On the Propeller 1, enabling the CLOCK no longer requires an extra cog when the SD card plugin is also loaded. This was the case in early Catalina releases, but it has not been the case since the new SD card plugin was adopted, due to lack of code space in the newer plugin. This has been fixed by adding a new (smaller) clock service and shifting most of the time calculations to the C library instead. Support for the old SD card plugin (which could be enabled by defining the Catalina symbol OLD_SD) has therefore been dropped, because that was the only reason it was still included. The new clock service has been added on both the Propeller 1 and the Propeller 2 for consistency, even though it was not necessary on the Propeller 2 because its SD plugin does have sufficient space to implement the old clock services. You can force the inclusion of a separate clock plugin even when the SD Card plugin is loaded by specifying the Catalina symbol SEPARATE_CLOCK. This would be necessary if you have a custom CLOCK plugin (e.g. one that uses a hardware clock). 12. The Catalina optimizer was still assuming it could use the Homespun spin compiler, which is no longer included with Catalina. It has been modified to use Spinnaker/OpenSpin in all cases. 13. The Lua demo programs and examples now pause before terminating, so that if they are used with a non-serial HMI option (such as VGA) the output is not lost before it can be read (Catalyst clears the screen when the program terminates). 14. The Propeller Memory Card (PMC) had a timing issue which may have caused the card initialization to fail. Added NOPs to extend the clock pulses. Affected the Propeller 1 only. 15. If you chose not to copy the utilities to the Catalina bin directory, the build_utilities script said it would build the utilities in the "current" folder, but what it meant was the "utilities" folder, assuming that was where it was executed. In fact it can be executed in any directory, but will always either leave the utilities in the utilities folder or copy them to the bin directory. The text has been updated. Affected the Propeller 1 only. RELEASE 5.3.1 New Functionality ----------------- 1. Catalyst now understands ".lux" as a filename extension, as well as ".lua". Catalyst assumes ".lux" represents a compiled Lua script, whereas ".lua" can represent either a compiled or a non-compiled Lua script. By default, files with a ".lux" extension will be executed with LUAX.BIN and files with a ".lua" extension will be executed with LUA.BIN. If no extension is specified on the command line and files with both extensions exist, ".lux" will be used. 2. There is now a Propeller 2 version of the Catalyst Spin demo that shows how to use Catalyst command-line arguments in Spin2 files. It is in the folder demos/catalyst/demo and called Demo.spin2. Other Changes ------------- 1. Fixed a race condition in the SD Card plugin, which meant that it could fail when a sequence of SD Card operations was performed at a specific rate. Affected the Propeller 2 only. 2. The demo program ex_time.c was not clearing the daylight savings flag when setting the time, which meant that when the time was retrieved, the hour would sometimes be one hour different than what was set. Affected both the Propeller 1 and Propeller 2. 3. Dumbo Basic was not flushing its output buffers, so prompts and input was not appearing in some cases when executing input statements until an end-of-line character was entered. RELEASE 5.3 New Functionality ----------------- 1. The Catalyst utilities cp, mv, rm, ls and cat now ignore volume id entries, except that the ls utility will still include them when long or very long listing output is specified. 2. Catalyst now has the ability to execute a once-only command on startup. This is similar to the existing AUTOEXEC.TXT file processing when the AUTODELETE option was also enabled. The AUTOEXEC.TXT and AUTODELETE functionality has been retained, but AUTODELETE is not enabled by default, which means that normally the AUTOEXEC.TXT is executed on every Propeller reboot. The new once-only execution functionality overrides this if the file EXECONCE.TXT exists. If it does then it will be executed and also deleted. This new functionality is used by the Lua propeller module "execute" function, described in point 3 below. It requires that the SD Card be writable. 3. The Lua propeller module now includes new propeller-specific functions. Lua analogues of the C DOSFS wildcard/globbing functions: mount() scan(function, directory, filename) The filename can include wildcards. See the Catalyst Reference Manual for details, and see list.lua for an example of using these functions. A Lua function to execute any Catalyst command (reboots the Propeller): execute(command, filename) For example: propeller.execute("list *.bas") The first parameter is the command (which may include parameters), and the second (optional) parameter is the file name to write this command to. This defaults to "EXECONCE.TXT", which means the command will only be executed once, but it can be used to write the command to any file. For instance: propeller.execute("lua", "AUTOEXEC.TXT") will cause the Propeller to execute "lua" on each reboot. To disable this from within Lua, just delete the file by executing a Lua command like: os.remove("AUTOEXEC.TXT") Lua analogues of the keyboard HMI functions: k_get, k_wait, k_new, k_ready, k_clear Lua analogues of the screen HMI functions: t_geometry, t_mode, t_setpos, t_getpos, t_scroll, t_color, t_color_fg, t_color_bg Lua analogues of the mouse HMI functions: m_button, m_abs_x, m_abs_y, m_delta_x, m_delta_y, m_reset, m_bound_limits, m_bound_scales, m_bound_x, m_bound_y Each of these HMI functions accepts the same parameters and returns the same values as their C counterparts. See the Catalina Reference Manual for details. Note that to save space, the mouse functions will not be included if the Catalina symbol NO_MOUSE is defined when Lua is compiled (which it will be if you use the "build_all" scripts to build Lua - to change this you can edit the file Makefile.Catalina to remove the "-C NO_MOUSE" option). You can detect whether mouse functions have been included from within Lua itself by testing if any of them are nil, such as: if (propeller.m_button) then -- mouse functions have been included else -- no mouse functions end 4. Catalyst will now try to execute commands as Lua scripts, in addition to just executing binary files. The order of priority for Catalyst command execution is now: 1. As a built-in command (e.g. "dir") 2. As a Lua script, adding a ".lua" extension if none is specified 3. As a binary file, using the command as the file name 4. As a binary file, adding the following extensions (in this order if the command does not specify an extension): .BIN .BIX (propeller 2 only) .XMM .SMM .LMM Note that all command types accept command line arguments, including Lua scripts. Several example Lua scripts are included: list.lua - a simple directory listing program (similar to Unix "ls"). find.lua - a simple file searching program (similar to Unix "find"). freq.lua - a simple word frequency counting program. You invoke Lua scripts from the Catalyst command line just like any other command. For example: list <-- list file details of all files list *.lua <-- list file details of Lua files find *.bas PRINT <-- find PRINT statements in all BASIC files freq *.txt <-- count word frequency in all text files Note that Lua scripts can be compiled to improve load and execution times, but they should still have the extension ".lua". As a consequence of this, the Lua versions of the Super Star Trek demo programs have changed name, so that executing the command "sst" at the Catalyst prompt will still invoke the C version ("sst.bin") rather than now executing the Lua version (which used to be called "sst.lua"): sst.lua --> now called star.lua sst-tos.lua --> now called star-tos.lua 5. The Propeller 2 Catalina command line argument processing has been modified to match that of the Propeller 1. On startup, all Catalina programs check if CogStore is running. If it is, the program fetches any arguments stored in it. Previously on the Propeller 2, if CogStore was not running then Catalina would set argc to zero and argv[0] to NULL - but some C programs expect argc to always be at least 1, so now if CogStore is not running argc will be set to 1 and argv[0] will point to a string with the value "null" (since without CogStore the real program name is not available). This functionality was already implemented on the Propeller 1. 6. The wildcard/globbing doDir() function in storage.h and storage.c has been extended to make it more useful - it now calls the file processing function with the file size and the DOSFS file attributes of each file in addition to the file name. One advantage of this is that programs that use doDir() do not need to use DOSFS functions to retrieve the file attributes themselves, and therefore only need to use standard C stdio file functions. 7. The build_catalyst script now detects whether it is being run in the current directory. If so, it builds catalyst in this directory, otherwise it builds it in the demos\catalyst folder in the Catalina installation tree (as it did in previous releases). The purpose of this is that if you copy the Catalyst folder to your own local user directory, you can build Catalyst locally and do not need to have write permission for the Catalina installation tree. Note that the build_all script already supported local builds, it was only the build_catalyst script that did not. 8. The build_utilities script now detects whether it is being run in the current directory. If so, it builds the utilities in this directory, otherwise it builds them in the utilities folder in the Catalina installation tree (as it did in previous releases). The purpose of this is that if you copy the utilities folder to your own local user directory, you can build the utilities locally and do not need to have write permission for the Catalina installation tree. Also, the build_utilities script has been modified to prompt whether the utilities binaries should also be copied to Catalina's bin directory, or simply left in the current directory. Copying the utilities to Catalina's bin directory is convenient since payload looks for them there if it does not find them in the current directory, but it requires write permission to the Catalina installation tree. If you do not have this permission, you can now copy the utilities folder to your own user directory, build the utilities there, then copy the binaries to each directory from which programs will be loaded - which may actually be a better solution if you have multiple Propeller platforms or configurations which need different versions of the utilities. Note that the utilities are required only for Propeller 1 platforms - there are currently none needed for any of the supported Propeller 2 platforms. 9. The build_all script in the utilities folder has been removed (it was deprecated quite a few releases ago). Use the build_utilities script instead. The main difference is that build_all used to build binaries for all CPUs of multi-CPU platforms (such as the TRIBLADEPROP) whereas the build_utilities script has to be re-run for each CPU. Other Changes ------------- 1. Implemented a workaround for an OpenSpin/Spinnaker bug that meant compiling Spin programs with too many short symbol names could fail unexpectedly. The current workaround is to simply use longer symbol names. Affected only Propeller 1 programs that used the Catalina Optimizer (which may generate many additional symbol names). 2. Fixed a typo in the DOSFS demo program that prevented it from compiling. 3. Updated the version of Lua used in payload and blackbox to Lua 5.4.4, which is the current version. Lua 5.1.5 is still included as a Catalyst demo program, but is no longer compiled by default (Lua 5.4.4 is now used everywhere) and Lua 5.1.5 is now deprecated and may be removed from a future release. 4. Since Lua is now compiled in COMPACT mode by default, the pre-compiled P2 demo versions of Catalyst (in P2_EVAL.ZIP and P2_VGA.ZIP) are now compiled in NATIVE mode, which improves execution speed, but at the expense of larger executables for some of the demo programs. If this is a problem, simply recompile Catalyst, specifying COMPACT mode as one of the parameters to the "build_all" script. 5. Updated the notes about compiling Catalyst - a memory model should only be specified as an argument to the "build_all" script when compiling for the Propeller 2, not for the Propeller 1. RELEASE 5.2 New Functionality ----------------- 1. Added a new inline pasm demo ("test_inline_pasm_5.c") to demonstrate how to CALL an inline PASM function from within an inline PASM function in a COMPACT program. 2. Updated the validation suite. Now logs more details to make it easier to identify what failed, and also added "short" scripts to do faster validation. 3. Updated the file 'globbing' demo (in folder "demos\globbing"). Tidied it up, fixed a few bugs and it now uses the correct DOS filename syntax, prints the filenames properly, and is now correctly case insensitive in all cases. The listDir() function has been re-written to be an instance of a new generic doDir() function, which calls a specified function on each matching filename. 4. Wildcard matching ('globbing') has been added to many of the Catalyst utilities. You can now specify wildcard expressions like *.bin or [a-g]*.b?? - see "glob.c" for details. The options and syntax of the utilities have not changed, except for 'ls' (see 5 below). The commands affected are: ls - list files and/or directories rm - delete files or directories cp - copy files mv - move files cat - concatenate and print files For example, you can now say things like: ls *.bin *.dat mv [a-f]*.bin bin rm ???.dat cat *.txt Note that wildcards can only be used in the file name part of a path, not in the directory part, so you cannot specify an argument like "/b??/*.*". For arguments that may be interpreted as files or directories, adding a trailing "/" ensures they will be treated as directories. For example: ls bin -- list just the entry "bin" (if it exists) ls bin/ -- list the contents of directory "bin" (if it exists) Note that the built-in "dir" command does not accept wildcards because there is not enough space to do so. The same is true of the "cat" command when it is compiled as a Catalyst build-in command (it is normally compiled as an external command). 5. The Catalyst "ls" command now uses a short listing format (similar to that used by Unix or the built-in "dir" command) by default. The previous default listing format can be specified using the "-l" option, and the previous long listing format (which used to be specified by "-l") must now be specified by "-l -l" or "-ll". Also fixed interactive mode, which was not working in some cases. 6. The Catalyst "cp", "mv" and "rm" commands now accept 'a' or 'A' (for "all") at the interactive prompt, to indicate that the command should assume "yes" for all subsequent files. 7. The catalyst "build_all" script now does "clean_all" before building, to ensure there are no binaries left from previous builds. Other Changes ------------- 1. Updated the file "catalina_compact.inc" in the target and target_p2 directories to add more notes about writing inline PASM in COMPACT programs. 2. The tiny library had a version of the C stdio function gets(). This prevented programs that used gets() from linking with the tiny library, because it ended up being multiply defined. The version in the tiny library has been renamed tiny_gets() in this library, but like the other tiny functions (i.e. tiny_printf() etc) it will be used automatically if a program is linked with the tiny library. Affected the Propeller 1 and Propeller 2. 3. Fixed a bug in the Propeller 1 SD Card plugin - multiple block writes must not be used on platforms that must disable the SD Card to use XMM RAM (e.g. because they share pins). Affected the Propeller 1 only. 4. Fixed a bug in Catalina's "unmanaged" file close function which meant that only a limited number of files could ever be opened. Did not affect the normal stdio open/close functions, but it affected the Catalyst "cat" command, which uses the unmanaged versions of open/close to save space. 5. Catalyst's example basic files are now all Unix format, not DOS format. This makes no difference to their functionality, but makes them easier to edit usng "vi" or list using "cat". 6. Fixed a bug in DOSFS which affected the ability to delete files with zero length (e.g. using the Catalyst "rm" command) - doing so may have corrupted the file system. RELEASE 5.1.2 New Functionality ----------------- 1. The path that Lua uses to search for modules has changed. The old path was the one used on Windows, which was not appropriate for the Propeller. The path is now: "?.lua;?/init.lua;lua/?.lua;lua/?/init.lua" This means that (for example) if you say "require 'm'" then Lua will search for "m.lua", "m/init.lua", "lua/m.lua" and "lua/m/init.lua" in that order. 2. The Lua demos sst.lua and sst-tos.lua now use "propeller.sbrk()" instead of "threads.sbrk()", which means the mem command (which displays the top of the C heap) now works when the program is run under both lua and mlua. Other Changes ------------- 1. Fixed a bug in the threads library, which prevented some multithreaded programs from compiling. Affected only Propeller 1 programs which were compiled in LMM TINY mode. 2. Eliminated the file minit.c from Lua. This was a temporary replacement for the Lua file linit.c which included the threads module. Now linit.c will include the "threads" module if LUA_THREADS is defined in the file luaconf.h. For completeness, there is also a corresponding LUA_PROPELLER that is used to specify that the "propeller" module be included. This is more in keeping with the way Lua normally defines compile-time options, eliminates the need to have the extra file, and it also means that when compiling the executables (e.g. lua and mlua or luax and mluax) under Catalina, Catalina can automatically detect the compile options and include the correct modules. But if you compile mlua or mluax using gcc and posix threads, you will now need to explicitly define LUA_THREADS in luaconf.h to include the "threads" module. 3. Fixed a bug that meant the Lua "propeller" module would not compile using any compiler other than Catalina. Although it is only functional when compiled using Catalina, it should still have compiled using other compilers (such as gcc). 4. The number of threads the "test_maximum_threads.c" demo program creates has been reduced to 145, since at 150 there are some plugin combinations that do not have enough free Hub RAM to support 150 threads. Affected the Propeller 1 only. 5. The build_all scripts and Makefiles now always build Lua in COMPACT mode on the Propeller 2, because NATIVE mode does not leave enough Hub RAM for the various demo programs. RELEASE 5.1.1 New Functionality ----------------- 1. Added a new demo folder ("xeprom") containing programs that demonstrate how to read from the EEPROM from XEPROM XMM programs. In such programs, the EEPROM cannot be read independently (e.g. using an I2C driver) because it is constantly in use by the cache. This applies only to the Propeller 1, and requires a platform with an EEPROM larger than 32k, such as a FLIP, a C3 or a HYDRA. Other Changes ------------- 1. Fixed a bug that meant the -e command line switch to Catalina, which is used to specify that a ".eeprom" file be generated instead of a ".binary" file did not work correctly in some instances. In particular, it could not be used in conjunction with the -C XEPROM option. This affected the Propeller 1 only, and only Catalina version 4.9.3 or later. 2. The catalina_clean utility script had not been updated recently, and would miss cleaning some directories when the optional "all" parameter was specified. RELEASE 5.1 New Functionality ----------------- 1. Decoding the CATALINA_DEFINE environment variable was taking place AFTER the symbols to specify the clock frequency were defined, so the Catalina symbols MHZ_220, MHZ_260 & MHZ_300 only worked when specified on the command line, and had no effect if specified using CATALINA_DEFINE. 2. Added MHZ_200 as a Catalina symbol, to make it easier to build Catalyst using 200Mhz on the Propeller 2. Note that the Propeller 2 reference manual, the tutorial Getting Started with Catalina and the documentation in the Propeller 2 VGA plugin source file all mistakenly referred to MHZ_200 when they should have referred to the existing MHZ_220 symbol. All these documents have now been updated. 3. The Lua "propeller" module has had the functions sleep, msleep and sbrk added. These functions are the same as the ones in the "threads" module, but are handy when the propeller module is used in a non-threaded Lua program. 4. The Lua "threads" and "propeller" modules now accepts a string parameter. If "lua" is specified, these functions return the version of Lua. Otherwise they return the version of the module 5. Lua versions of the classic Star Trek game (sst.lua and sst-tos.lua) are now included as Lua test programs. 6. A change was made to the gettoken procedure in Dumbo Basic 1.0, which was introduced in Catalina release 4.7. This change led to a syntax error when executing TREK15.BAS. This change has been reverted in Dumbo Basic 1.1, but if this breaks any existing basic code, it can be re-implemented by modifying the file basic.c and changing the #define of NEW_GETTOKEN to 1. 7. When compiled for the Propeller, Dumbo Basic now has a delay on exit of 100ms to allow time for any pending output to be printed. This prevents error messages or final program output from being truncated. Other Changes ------------- 1. The command-line options to set the clock frequency (-f, -F and -E) were fully implemented, but not described in the documentation. These options apply to the Propeller 2 only. 2. On the Propeller 2, it is now recommended that Catalyst be compiled using a 200Mhz clock speed. This is a work-around for an obscure bug which only seems to affect some programs loaded from the SD card and which use a clock speed of 180Mhz. 3. A bug in the SD Card plugin was preventing programs being able to write to some SD cards (reading was ok). This affected the Propeller 2 only. RELEASE 5.0.3 New Functionality ----------------- 1. The default version of Lua (e.g. built by the Catalyst build_all scripts) is now Lua 5.4.4. However, Lua 5.1.5 is still included and can be built manually if required. 2. The Lua threads module has a new version() function which returns the LUA_VERSION_NUM associated with the Lua version. The main use for this is to allow for changes made in Lua between versions, such as the changes to the garbage collection options in various Lua releases. The possible return values are: 501 - Lua Version 5.1.x 502 - Lua version 5.3.x 503 - Lua version 5.3.x 504 - Lua version 5.4.x Other Changes ------------- 1. From version 5.2 onwards, Lua no longer "requires" the coroutines module by default, so the Lua threads module now does this explicitly. 2. Some functions in the threads module were returning floating point values when the value was really an integer. Lua versions 5.2 and earlier only supported floating point values, so this was the only option. From version 5.3 onwards, Lua supports integers as well as floating point values, and in some cases it is more appropriate for the function to return an integer. 3. For consistency with the threads.factories() function, threads.workers() now returns the current number of workers. However, note that if this function is used to CHANGE the number of workers then the value returned may be anywhere between the old number of workers and the new number. This function merely requests a new number of workers - actually creating or destroys the workers may not happen immediately. 4. The Makefile for Lua-5.4.4 had not been updated to build Multi-processing Lua on Windows or Linux. 5. The document "Lua on the Propeller 2 with Catalina" has been updated to note a limitation of using coroutine.yield(), or the put and get message passing functions - i.e. that you cannot hold a mutex locked while you use these functions. RELEASE 5.0.2 New Functionality ----------------- This release contains no new functionality. Other Changes ------------- 1. Fixed a bug in the Lua threads module when sending and receiving messages. The program could lock up under certain circumstances. Since the Lua threads module is only supported on the Propeller 2, this affected the Propeller 2 only. 2. Multi-threaded Lua examples 4 has been updated to eliminate a race condition. 3. Multi-threaded Lua example 8 has been updated to make it more evident the example is using preemptive multi-tasking. 4. Multi-threaded Lua examples 11 and 12 have been added to demonstrate interactions between co-routines and threads. 5. The document "Lua on the Propeller 2 with Catalina" has been updated to reflect the above changes. Also, some terminology issues have been clarified. RELEASE 5.0.1 New Functionality ----------------- 1. Modified various Catalyst commands to allow combined command-line options - e.g. -dh now means the same as -d -h Other Changes ------------- 1. Fixed a bug in the DOSFS file system which allowed a file to be opened as a directory using the DFS_OPENDIR option to DFS_OpenFile instead of returning that a directory of that name did not exist. This confused the Catalyst cp command when copying files into a directory. 2. Fixed a bug in the Catalyst rm command that prevented recursive file deletions. 3. Fixed a bug in the Lua threads module that prevented the number of factories being reduced. Also, the Lua threads module documentation has been updated to reflect the fact that reducing the number of factories now necessarily terminates all workers first (they are restarted after the number of factories has been reduced) and that this should therefore only be done from the main thread and when that thread is executing on factory 1. 4. Modified Lua to zero all newly allocated blocks of memory. Lua seems to assume all new blocks of memory will be initialized to zero, which is not actually guaranteed by C, so this led to some Lua programs behaving unexpectedly. While this fix resolves the issue, it does so at a small run-time cost, so further investigation is required. Multi-threaded Lua example 9 was badly affected by this issue and has been updated. The Lua threads module documentation has also been updated. RELEASE 5.0 New Functionality ----------------- 1. The standard C memory management functions (i.e. malloc, realloc, calloc, free) and a new system break function (sbrk) are now all thread safe. For details, see the "Multi-processing, Locks and Memory Management" section in the Catalina Reference Manual. 2. Catalina's dynamic memory management has been modified to make it less prone to running out of memory when lots of small randomly sized chunks of memory are allocated, freed or re-allocated. For details, see the "Multi-processing, Locks and Memory Management" section in the Catalina Reference Manual. 3. A new function has been added that can be used to assign one or more locks to protect services offered by plugins in multi-cog or multi-thread programs. For details, see the "Multi-processing, Locks and Memory Management" section in the Catalina Reference Manual. 4. An example of a public domain itoa function has been added to the folder demos\examples - it is called ex_itoa.c. The itoa function is also used in the new demo program test_thread_malloc.c (as an alternative to using sprintf, which can make the program too large for the Propeller 1). 5. Catalina used to use 4 bits for the lock in the service registry. The Propeller 1 only had 8 locks, so this was sufficient to represent all possible locks plus a bit to indicate "no lock". But the Propeller 2 has 16 locks, so Catalina must now use 5 bits for the lock. To make space for the extra bit, the number of bits used to hold the cog-specific service code has been reduced from 8 to 7. This still allows up to 127 services, but less than 40 such services are implemented even by the most complex plugins (the HMI plugins), so this is unlikely to be a problem. If it becomes so, the size of each service entry can simply be increased from a 16 bit word to a 32 bit long. Although this change is only required for the Propeller 2, to keep the library functions consistent, it has been made on the Propeller 1 as well. 6. The speed of the p2asm assembler has been improved - it is now approximately twice as fast. I am still not sure why it is so slow on Windows compared to Linux, where exactly the same code executes about 10 times faster on the same machine. 7. If a baud rate is not specified and a file with a ".bin" extension is loaded, payload now assumes it is loading a Propeller 2 and sets the baud rate to 230400. This can be overridden by specifying a baud rate either on the command line or via the PAYLOAD_BAUD environment variable. 8. Windows 10 has a bug in the Command-Line interpreter. When loading a program using payload, it crashes (taking payload down with it) if the Wndows option "Wrap Text Output on Resize" option is not set in the Layout Options (in the Properties dialog box). This can leave a payload task executing in the background which needs to be terminated manually (e.g. using Task Manager) in order to release the USB port. 9. The translation of outgoing CR to LF has been disabled in the payload interactive terminal mode by default, but mode 16 has been added to restore the original behaviour if needed. The translation was preventing the use of payload to interact with TAQOZ and the P2 Monitor - the correct mode to use for these is now -q1. For instance, if you have a Propeller 2 connected to port X, you can communicate with TAQOZ by entering a command like: payload -i -q1 -pX Then reset the Propeller 2 and enter the usual TAQOZ entry sequence (i.e. '>' SPACE ESC) or P2 monitor entry sequence ('>' SPACE CTRL-D) 10. Catalina now supports a "thin" binding to Posix threads. See the "Posix threads (pthreads) support" section in the Catalina Reference Manual. 11. Lua module "threads" adds multi-threading capabilities to Lua (for the Propeller 2 only). The document "Lua on the Propeller 2 with Catalina" describes this new functionality in detail. 12. The interactive versions of Lua (and Multi-threaded Lua) now support trivial line editing (e.g. backspace is now recognized). 13. Catalina now supports setpin(), getpin() and togglepin() for both the Propeller 1 and 2. These are defined in propeller.h: setpin(pin, value) - sets pin to output and sets value setpin(pin) - sets pin to input and gets value togglepin(pin) - sets pin to input and toggles value These functions are also provided in the Lua propeller module, described in The document "Lua on the Propeller 2 with Catalina". Other Changes ------------- 1. Support for the dual-CPU MORPHEUS platform has been dropped. The Morpheus was supported up to Catalina 4.9.6. The Morpheus required special complex build scripts, and some of the large demo programs would not run because of the unique and expensive (in terms of cogs) VGA driver it required. Also, many of the demo programs required both CPUs to run at all since the keyboard and mouse was on one CPU but the VGA hardware was on the other. This limited the usefulness of having dual CPUs. The Morpheus-specific scripts and drivers from that release may contine to work in subsequent releases, but installing, testing and maintaining them is now up to the user. They will no longer be routinely included as part of each Catalina release. Support for the simpler three-CPU TRIBLADEPROP will remain, primarily as an example of how to support multi-CPU Propeller systems, which typically require the use of multi-stage loaders and proxy HMI drivers. 2. Changes to the Catalina Optimizer to allow it to recognize more code that can be optimized. Generally only affected hand-coded PASM, where the spacing in the code did not match exactly what the Catalina code generator would produce (e.g. if you used tabs as a separator instead of spaces). 3. Make it more explicit in the documentation that the integer-only version of the C standard library (libci) does not include support for sprintf() or vsprintf() - if these functions are required, use one of the other libraries (e.g. libc). This is to keep libci as small as possible. 4. Fixed some instances where the C library stdio was not re-entrant, and hence not thread safe or multi-cog safe. 5. The Catalina HMI function t_float() was not re-entrant, and hence not thread safe or multi-cog safe. 6. Use dynamic io buffers for stdio (previously, Catalina used static io buffers which was more efficient but not multi-cog safe or thread safe). 7. Minor changes to the include files propeller.h, propeller2.h and catalina_cog.h - it is now possible to include any or all of them, and in any order on both the Propeller 1 and 2 and they should not interfere. (but of course, propeller2.h defines functions that may not be available on the Propeller 1, and vice-versa). There have been some changes to the function definitions in these files (not to the functions themselves) that could conceivably cause issues for programs that relied on specific definitions. 8. There was an error in the Makefile in the demos\p2 directory that prevented some of the demo programs building. 9. The reference manual documentation for _lockset (etc) has been updated, as both the Propeller 1 and 2 reference manuals had gotten out of sync with the actual software. 10. The various reference manual sections dealing with Multi-Processor support (i.e. multi-cog, multi-threading and multi-model) have been combined and extended. 11. Fixed a bug in DOSFS that led to the Catalyst "rm" command thinking a file to be deleted was a directory when in fact it simply didn't exist. 12. Fixed a bug in xvi (aka vi) which meant that if a yank or delete command was the first thing attempted, it may have given a spurious "Not enough memory to perform delete" error. 13. Fixed an issue in some of the build_all scripts that would not detect a Propeller 2 if it was specified using CATALINA_DEFINE instead of on the command line. Now, a P2 is assumed if the first 2 characters of the first parameter to the build_all script are "P2" OR the first two characters in the CATALINA_DEFINE environment variable are "P2" 14. Noted an issue with the Multi-Processor support, which is now documented in the Reference manual: If a program dynamically loads C code to execute on another cog, and that code uses floating point, then it will fail UNLESS the main program loads a floating point co-processor - i.e. UNLESS the main program is linked with -lma, -lmb or -lmc. If it is instead linked with just -lm, or not linked with a floating point library at all, then the main program will not load the floating point co-processor cog that the dynamically loaded kernel requires. This applies to ALL Catalina releases. 15. On Linux, expecually when using Gnome Terminal, you may need to set your terminal preferences to get the backspace and delete keys working correctly. This can affect the ability for using CTRL-D to send an EOT to your application or to exit payload (if CTRL-D does not exit payload try using CTRL-C). Use the menu command Edit->Preferences and select the Compatibilily tab for your profile (which will be called "Unnamed" if you have not created any specific profile, set the following options: Backspace key generates: Control-H Delete key generates : Automatic You can create a new profile called Catalina with these settings to make it easier to switch profiles if you also need other values for these settings.