Catalina release 3.1 is a full release. You should delete any previous Catalina release before installing, or install release 3.1 to a different location. If you are installing under Linux, you should execute the following command to set your permissions correctly after installing (this command is a script in the Catalina bin directory): Set_Linux_Permissions The following changes have been made since release 3.0 of Catalina. If you have not used a previous release of Catalina, you can ignore this list: RELEASE 3.1 1. Fixed a bug in the SMALL memory model on the C3 (same bug as was fixed in 3.0.3 - the fix was lost in release 3.0.4!). 2. Simplified the "standard" target package. Turned all the plugin selection include files into SPIN objects to make the logic of the plugin load process easier to understand. Removed the include files containing the kernel and loader selection logic, as they hid some of the differences between targets, which also made the logic harder to understand. 3. Removed the duplication of HMI plugins - now there is only one HMI plugin for each screen type, and not a separate for omitting the mouse and/or keyboard drivers. 4. The POD assembly language debugger is now enabled by compiling using the target "pod" rather than "debug" - this is to avoid confusion between the blackcat/blackbox and pod debug support files. For example, to use pod to debug hello_world.c, you would now use a command like: catalina hello_world.c -lci -t pod -D NO_ARGS -D NO_FLOAT Note that POD still requires the use of PropTerm, with the terminal set to 40 characters by 30 rows. The program to be debugged should be uploaded using PropTerminal, and should not itself use the serial port. 5. Added a "basic" target package. The basic package supports only one platform, and no HMI drivers. It is intended for very deeply embedded applications where HMI drivers are not required, or a user prefers to add their own HMI drivers. 6. Removed the RESERVE_COG support. This also complicated the logic in many target files, and the main purpose of this functionality (to prevent a cog being initialized during the load process so that SDRAM could be used as XMM RAM) was implemented in the Caching XMM driver instead. 7. Added some notes about MinGW and Windows 7 in the README.Win7 file. For various reasons, Windows 7 does not socialize well with MinGW. 8. Add ".exe" to the references to catalina and catbind in the various Catalyst demo program makefiles. This seems to be required to allow MinGW to execute the programs correctly under Windows 7. This is a known issue, and is probably a Windows security "feature". 9. The MORPHEUS demo program to test the file system was incorrectly being built for CPU #2 instead of CPU #1 in the tutorial. 10. Fixed a bug on Linux where the libcix library was not being built correctly. 11. Renamed the "custom" target directory to "simple" (and moved "custom_demos" to "demos\simple") to avoid any confusion between the "custom" target package and the CUSTOM target (which is a target within the standard target package). The two have nothing to do with each other! 12. Moved the RAM_Test programs to the utilities directory. They can be built using the command "build_ram_test" in that directory. RELEASE 3.0.4: 1. Added improved spinc utility, which allows the execution of Spin programs as well as just PASM programs. For details on the many new spinc options, execute the command spinc -h RELEASE 3.0.3: 1. Completely New Code::Blocks integration specifically for Code::Blocks 10.05. A new Compiler plugin that supports Catalina has been included, plus a new Catalina Project Wizard, and wrapper functions to allow Catalina utilities to be invoked from the Code::Blocks tools menu. 2. Added the "build_utilities" batch file, which interactively guides users through the options required when building the "utilities" folder. 3. Make catbind use the same algorithm as LCC to determine a directory to use for temporary files. Like LCC, the default directory can be overridden by setting the CATALINA_TEMPDIR environment variable. This should make it possible to use Catalina when logged in as a user without Administrative rights under Windows 7. However, it is still necessary to disable the VirtualCopy feature of Windows 7 - see the file README.Win7 4. Fix a problem in catalina_env.bat under Windows 7. 5. Minor changes to some build_all scripts and makefiles. Catalina now assumes MinGW and MSYS are installed, and will use the versions of programs (e.g. make, bison, flex) that come with MinGW. Make sure you set your path variable appropriately when building Catalina - for example, if MinGW and MSYS are installed in "C:\MinGW" you would need to do the following: set PATH=C:\MinGW\bin;C:\MinGW\mingw32\bin;C:\MinGW\msys\1.0\bin;%PATH% 6. Fixed a problem with payload failing to load XMM.binary from the bin directory. 7. Change in terminology - payload now says "download" instead of "upload" 8. Fixed a bug that occurred when using the -lmb option which left the symbol Float_B undefined. 9. Fixed a bug with the SMALL memory model on FLASH platforms (such as the C3) that led to programs not having their data segments incorrectly initialized. RELEASE 3.0.2: 1. Fix a bug in the plugin search algorithm used in the XMM kernel which meant the search stopped when the plugin type was 8 instead of when it reached cog number 8! This meant that plugin type 8 (allocated to the DUM plugin) could never found in XMM programs. 2. Fixed some typos in the definition of the waitpne and waitpeq macros in the header file catalina_icc.h RELEASE 3.0.1: 1. Fix a bug in the HUB Flash loader (used on the C3 and Morpheus) which meant the read/write sectors were not being correctly copied from Flash to SPI RAM. This caused mysterious failures such as the SD card file system not working correctly. 2. The default behavior when programming SPI FLASH (e.g. on the C3 and the Morpheus platforms) is now to erase each 4k block just before programming (instead of initially doing a full chip erase). The previous behavior can be reinstated by defining the symbol CHIP_ERASE when compiling (e.g. when compiling the utilities or Catalyst folders). One result of this is that when using Payload to load a program on the C3, it is no longer necessary to extend the payload timeout by adding an option like '-t 1000' to the command. Another benefit is that loading programs into SPI FLASH is faster when using both Payload and the Catalyst loader. 3. Added ERASE_CHECK and WRITE_CHECK options to the caching SPI driver. These options can help improve reliability when programming the SPI FLASH (e.g. on the C3 or Morpheus). Note that ERASE_CHECK is only applied to the whole flash chip erase, not the block erase. Only the WRITE_CHECK is enabled by default, since it does not take much time (the erase check, on the other hand, can take around 15 seconds!). To enable the erase check, define the symbol ERASE_CHECK when compiling (e.g. when compiling the utilities or Catalyst folders). Doing so may require even longer timeouts when using Payload (e.g. -t 4000). 4. The library functions _register_plugin and _unregister_plugin now mask the cog id to 3 bits, to eliminate the chance of overwriting memory beyond the end of the registry. However, note that this does mean specifying something like cog 9 will actually register or unregister cog 1! 5. Add a ZERO_RAM option to the RAM test program. Compiling the RAM test with the symbol ZERO_RAM defined will cause the RAM test to zero all read/write XMM RAM before performing the test (and it will also disable the initial display of the XMM RAM). The ability to zero all XMM RAM (which can be done simply by starting the RAM test but not proceeding to perform any tests) is useful in diagnosing some program bugs or load problems. 6. Added an option to the RAM tester to display FLASH only on startup (define the symbol PRINT_FLASH_ONLY), and another to print continuously until a key is pressed (define the symbol PRINT_CONTINUOUS). This is handy for dumping the entire contents of Flash (save it by using a PC terminal emulator and saving the terminal buffer contents) when debugging loader problems. 7. Added C3 as a platform (and also various new options) to the messages displayed by various "build_all" batch files. 8. Added a new script to the bin directory (Set_Linux_Permissions) to set the permissions of all Catalina files in a Linux installation. The following changes were made in release 3.0 of Catalina: RELEASE 3.0: 1. Added functionality to payload to also look in the Catalina binary directory for files to load into the propeller. Also, upgraded the build scripts in the utilities directory to copy the binary files generated to the binary directory. The effect of this is that it is no longer necessary to specify the full path name to the XMM.binary loader (or the other payload utilities such as the mouse port loaders) or copy them to your current working directory each time you need them. For example, to upload an XMM program, you can now simply say (from any directory): payload XMM program Just make sure you have previously built the utilities for the correct platform! 2. Added -m (max retries) option to payload. 3. Fixed a bug with setjmp()/longjmp(). in LMM and XMM small mode these functions worked on some platforms but not others. In XMM LARGE mode these functions failed on all platforms. 4. Added a CACHED XMM driver for use with SPI RAM and SPI FLASH. The caching XMM driver can be used on any platform by defining one of the following symbols on the command line: CACHED_1K - use a 1k cache CACHED_2K - use a 2k cache CACHED_4K - use a 4k cache CACHED_8K - use a 8k cache CACHED - use a default size (8K) cache For example: catalina hello_world.c -lc -D CACHED Note that the caching XMM driver requires sufficient free hub memory according to the size of the cache, and also an extra cog. Also, the caching XMM driver is only generally faster on platforms that use SPI RAM or SPI FLASH - on other platforms the caching driver may only be slightly faster, or may even be substantially slower! The caching XMM driver is primarily intended for platforms such as the C3 or Morpheus CPU 2, which only have serial SPI RAM or SPI FLASH available for use as XMM RAM. Note that when a program which uses the caching driver is loaded by Catalyst, and Catalyst itself has been compiled to use the cache, then the cache size used for Catalyst MUST BE THE SAME as that used by the program being run. However, Unless dynamic RAM is in use (which requires constant refresh to retain it's contents) then it is perfectly ok for Catalyst to be compiled to WITHOUT the caching XMM driver but still be used to load programs which do - it is only when both Catalyst and the program to be loaded use the cache that IT MUST BE THE SAME SIZE! But if Catalyst has been compiled to use the cache, then so must all the XMM programs that are to be loaded. To summarize, here are the possibilities (assuming static RAM): Catalyst Uses Cache XMM Applications =================== ================ Yes MUST use same size cache No May use a cache of any size, or no cache When dynamic RAM is in use then both Catalyst and all XMM applications MUST use a cache, and this cache MUST be the same size. Failure to abide by these rules may result in programs that appear to load successfully, but fail to run correctly. 5. Added two new layouts intended for use on platforms with SPI FLASH (e.g. on the C3 and the Morpheus platform) - layout 3 and layout 4. Note that both of these layouts require the use of the CACHED XMM driver. Layout 3 - similar to layout 5, but the read-only segments (code and cnst) are in SPI FLASH, and the read/write segments (init & data) are in SPI RAM. Layout 4 - similar to layout 2, but the read-only code segment is in SPI Flash, and all the data segments (cnst, init & data) are in Hub RAM (SPI RAM is not used in this mode). These layouts can be modified slightly by using the -P and -R command line options: -R sets the base address of the Read-Only segments. It should be set to the base address of the SPI Flash. -P Sets the base of the Read/Write segments. It should be set to the base address of the SPI RAM. 6. Added a new Flash_Boot utility, to boot programs already loaded into SPI Flash. Note that when compiling the utilities, you should now specify ALL the plugins you want - only plugins specified will be loaded by the Flash_Boot utility. For example, if you want the Flash_Boot program to load an SD Card driver, a CLOCK driver and use the HIRES_vGA HMI but not load a mouse, you would compile the utilities using a command like: build_all C3 CACHED SD CLOCK HIRES_VGA NO_MOUSE To run a program loaded into SPI Flash on Propeller reset, you can program the Flash_Boot binary into EEPROM. You can also recompile the Flash_Boot program with different drivers - this might (for example) enable you to run the program in SPI Flash with either a TV driver or a VGA driver. Note that the program in Flash will NOT be aware of whether or not the caching driver is in use, or of the size of the cache. This means that the same program can be executed with different cache options. 7. Removed the Catalina_XMM_SD_Loader (& the Generic_SD_Loader). These were deprecated in previous releases, and have now been completely replaced by the Catalyst_SMM_SD_Loader (& Catalyst). 8. Tidied up the XMM routines in the Kernel - they were not working exactly as the documentation indicated - now they do. 9. Added a Flash test to the RAM_Test program. This is currently only enabled for the CACHED XMM driver. It simply displays the EEPROM, erases it and displays it again, then writes to it and displays it again. Also tidied up the programs user interface. 10. All HMI plugins now default to ANSI complaint interpretation of the control characters BS, HT, VT, CR, LF & FF (BEL is still ignored) on output. If you have a program that depends on the prior (i.e. non-ANSI) behavior, you can define the symbol NON_ANSI_HMI. This can be done on the command line at run time. You may also need to define the symbol CR_ON_LF (see below). The default behavior of all HMI plugins is now to translate a CR on input to an LF. Previously, this was done in the C library, but this meant it could not be disabled easily. Now it can be disabled in the HMI plugins themselves at compile time by defining the symbol NO_CR_TO_LF on the command line. Finally, some Windows terminal emulators need LF in the output translated to CRLF - this can now enabled at compile time by defining the symbol CR_ON_LF on the command line. For example, to use the othello program with a Windows terminal emulator that expects to see CRLF as the line terminator (and which cannot be configured to do this automatically) you can use a command like: catalina -lci othello.c -D PC -D CR_ON_LF 11. Disable Catalyst banner output if executing the 'autoexec' command. 12. Register all driver cogs. Previously the main HMI cog was registered, but the underlying driver cogs for keyboard, mouse and screen, or the proxy client driver, were not individually registered. Now they are. 13. Added some macros to make accessing the registry easier. See the include file catalina_plugin.h for details, or the demo program test_plugin_names.c for an example of their use. 14. Fixed a bug in the initialization of the SD card driver. Now it retries if the first initialization did not succeed. Affected some platforms but not others - possibly depending on the type of SC card used. 15. Fixed a bug in Catalyst that meant some commands were not being passed their arguments correctly. 16. Under DOS, Catalyst will now not build unless "make" is in the path. Previously, Catalyst itself would build but many of the demo programs would not (but with little indication of failure). 17. The Generic SIO Loaders now cannot display progress on the screen of the CPU doing the loading (due to lack of space). Now the progress can only displayed on the screen of the CPU being loaded - this is enabled by default when loading programs to Morpheus CPU 2 and TriBladeProp CPU 1. This can be disabled by removing the -D DISPLAY_LOAD command line option in the build_all script in the utilities folder. Disabling it enables slightly larger programs to be loaded, and may also speed up the load time - but there is no visible indication that the load is progressing. 18. Fixed a bug where the keyboard was not initialized prior to program start. This could result in one or more spurious characters being received on startup. This was particularly evident when using the proxy drivers on a multi-CPU Propeller system (such as the TriBladeProp). 19. Fixed several problems in the tutorial and programs designed to demonstrate the proxy drivers on both the TriBladeProp and the Morpheus platform. The proxy driver tutorial programs now work as the stated in the Getting Started with Catalina document. 20. Now accept defining the symbols TINY, SMALL and LARGE on the command line to specify the memory model. In conjunction with the existing symbols SDCARD, EEPROM and FLASH, these symbols now allow all the supported layouts to be specified as an alternative to using the -x option (which is retained as a shortcut, and also for compatibility purposes).