Clone this wiki locally
This tool chain is based on the following specific versions:
The master Makefile will download the appropriate archives then patch and build the assembler, linker, compiler and associated utilities. At present there is a problem if this is done on a 64 bit platform as the cross compiler will output 64 bit values which are unacceptable on the 32 bit MCU. The recommendation is to use a 32 bit Linux host or a chrooted 32 bit Linux system to build the compiler.
There is documentation in the source repository to show how to do this using schroot.
As mentioned above there is a master Makefile that is used to build all parts of the system; the most important targets can be listed by:
The mahatma target builds the main wiki reader application program in samo-lib/mahatma.elf. This is copied to an SD card as KERNEL.ELF along with the data files created by the index, parse, render and combine targets from the source XML files. The boot sequence described below will run this program.
The code for the bootstrap is contained in the samo-lib/mbr directory and consists of a 512 byte boot loader and several overlay applications. The MCU is configured to boot from its SPI port, upon reset the internal ROM on the MCU chip will configure the SPI port and issue a standard read command to retrieve bytes 1..512 from the SPI FLASH ROM and store in bytes 0..255 of its internal 8kB SRAM. This program (mbr.c) is a simple overlay loader and treats the 64kB FLASH ROM a 8 * 8kB partitions. This loader will load starting at offset 0×300 in the partition to internal ram at 0×200. Control is transferred to 0×200 to run the overlay and the return value of the overlay indicates which partition (0..7) to run next. The bootstrap code is installed during production testing but could be reflashed later if required.
This overlay loading allows a larger program than would fit in the 8kB internal SRAM. The SDRAM has not been initialized at this point so it cannot be used to run the initial program.
Overlay 0 (menu.c)
This will display the splash screen (or low battery screen) and check for serial console response. If no console responds, then load overlay 1 passing it a code base on any function keys pressed. If a console responds then scan partitions 1..7 and display any menu entries they contain. Menu entries starting at offset zero in the partitions are displayed on the console and assigned a single letter sending that letter allows the corresponding program to be run.
Overlay 1 (fileloader.c)
This will load one of three files from the SD card depending on the code it receives from the menu program A the time of writing these are:
- no buttons pressed loads KERNEL.ELF – This is the normal situation
- search pressed loads FORTH.ELF
- history pressed loads CALC.ELF
These will contains various test programs used during production and hardware development.They consist of LCD, Function Key and Memory (SDRAM) tests. These can only be accessed from the console menu. The console port can be accessed without opening the case by removing a seal from inside the battery compartment; this port also can be used with the host-tools/flash07 a program written in "Python"http://www.python.org to reprogram the FLASH ROM.
The normal situation is for the boot sequence above to load the KERNEL.ELF program into the SDRAM. This program is written in C and compiled with the cross compiler described above. It is made up from the following low-level parts in samo-lib:
- mahatma – the startup code
- drivers – low-level drivers for Capacitive Touch Panel, Function Keys, SPI etc.
- fatfs – an implementation of FAT32 from elm-chan.org
The high level application is in the wiki-app directory
Once the application is loaded it has full access to the system, the boot loader in the internal 8kB SRAM is overwritten and the SPI is switched to the SD card interface, and no further use is made of the the FLASH ROM or any of the boot code. The application uses the internal SRAM to store the suspend routine, which allows the SDRAM to remain in low power mode as much as possible to conserve the battery.
This means that any correctly cross-compiled application name KERNEL.ELF will be loaded an run without needing to update the FLASH, only a change of SD card containing it and its associated data files.
There are some test programs also included on the standard SD card these come from the samo-lib/forth directory. The Forth interpreter is written in Forth and cross compiled using "gforth"http://www.gnu.org/software/gforth/ using a meta-compiler included in the samo-lib/forth directory. The test programs are all included in source form and are compiled by the FORTH.ELF program directly on the device. A simple touch menu is included to select one of these programs, this lists up to a maximum of one screen full of *.4MU.
The *.4MU files usually just contain a few ‘include filename.4th’ lines followed by the word to run.
Most of the actual Forth code is contained in various *.4TH files; the reason to do this is so that one or more *.4TH files can be shared by several different *.4MU programs. There is nothing special about any of these files they are plain ASCII text and can be modified with any suitable plain text editor.
For a simple example look at these two files:
These form a simple line drawing example and show how to construct a basic event loop waiting for CTP touches or key events.
The calc program in this menu is the source code form of the CALC.ELF that is also on the standard SD card.
The forth interpreter also supports the console port and can be used interactively via this port, this is used to support scripted testing during production. The test programs can also be run to verify the hardware of the complete device.