The pre-release version of the Harmony cart is now finished and is being sold at the Portland RetroGaming Expo. I expect that the bug reports and feature requests will start arriving soon! Before they do, I though I would write a little more about how the Harmony driver software works.
The Harmony driver is written using a mix of C and ARM assembly language. The ARM assembly is used for the performance critical stuff, like feeding the Atari with instructions, while the C code is used for slower stuff, like reading from the SD card. I used the free GNU ARM cross-compiling tools under Linux to write the code. This produces a binary file, which can then be downloaded and run on the Harmony cart. Debugging was done through a serial port using the Olimex development board, rather than the actual Harmony cart.
The main challenge of programming the Harmony driver was fitting everything into memory. The Harmony has three kinds of memory, each of which has advantages and disadvantages:
- 8KB SRAM memory - this is the fastest kind of memory (1 cycle per access). The contents are lost when the power is switched off, just like normal computer RAM.
- 32KB Flash memory - this memory is much slower than SRAM (4 cycles per access). Code can be executed from Flash memory, but it can only be written in 4KB chunks. The contents of the Flash memory are preserved when the cart is powered off.
- 512KB EEPROM memory - this is the largest and slowest of the memory types. Code cannot be run direct from the EEPROM, and the memory can only be loaded and stored in blocks of 512 bytes. The contents of the EEPROM are preserved until erased.
The SRAM and Flash memory is actually part of the LPC2103 ARM microprocessor, while the EEPROM is a separate device, wired up to the ARM chip via the SPI bus. The SD card is also connected over the SPI bus, and a pair of chip select wires are used to select between the SD card and EEPROM. For safety, the EEPROM is kept write-protected during driver execution to prevent accidental overwriting.
The complete driver code is stored in the EEPROM memory and is approximately 100KB in size. The driver code is executed using from the SRAM memory, and the game is loaded from the SD card into the Flash memory region. The SRAM is only 8KB and so this requires a rather difficult juggling act to fit everything in. The driver is split into lots of separate parts (between 4KB and 6KB each), and each part is loaded separately into SRAM as required.
When the Harmony cart is powered on, it starts executing code at the beginning of the Flash memory. A small 1KB bootloader script is always kept in the Flash memory to set things up. The following steps are then required to load and execute a game off the SD card:
- The bootloader initialises the Harmony cart and stalls the Atari console.
- The first 6KB of the driver code is copied from the EEPROM into SRAM.
- The driver code begins executing and copies the Atari menu system (4KB) from the EEPROM into Flash memory.
- The SD card is initialised and scanned for files.
- The first 10 directory entries are copied from the SD card into SRAM.
- The Atari is resumed and fed the menu system from the Harmony flash memory.
- The user selects the game to be loaded from the menu (this may involve returning to the driver to load more directory entries).
- The Atari is stalled again and the driver loads the game from the SD card into flash (overwriting the menu system).
- The bankswitching detection code is loaded from the EEPROM into SRAM (overwriting the driver).
- The game type is automatically detected.
- The bankswitching code that corresponds to the game type is loaded from the EEPROM into SRAM (overwriting the detection code).
- The Atari is resumed and the game begins ...
If the game is 32KB in size, then there is not enough space in the Flash memory, as the 1KB bootloader must always be stored in Flash. For 32KB games, the last 1KB of the game is loaded in SRAM, overwriting part of the driver.
I will post more details about the driver in another entry. I'm not sure if the driver code is going to be made public yet. It works nicely at the moment, but there is definitely scope for improvement. The menu system has recently been updated by Thomas and now looks even better.
I'm hoping that the Harmony cart will be a big success. A lot of people have put a lot of effort into the cart (see the credits above), and it has taken around a year of development effort. It should make home-brew game development on the Atari 2600 much easier, and it will make it possible for everyone to keep and play a large library of Atari 2600 games.