Freescale S08JS SDCC Tutorial

Step by step guide to program the Freescale S08JS MCU in C using exclusively GPL tools. This tutorial uses SDCC, Make and SRecord to generate S08 binaries and flashjs to program the flash.

Pre-requisites

• SDCC C compiler
• SRecord
• flashjs

Creating S08JS Header File

Unfortunately the current SDCC distribution does not include a header file specific to the S08JS. The headers from codewarrior cannot be used directly as they use extensions specific to the HiSoft compiler.
It is possible to modify the codewarrior header file to SDCC for personal use but the codewarrior license terms forbids the redistribution of such file. We are actively working with Freescale to resolve the licensing issue to allow redistribution of the modified headers in the SDCC package.

Compiling & Linking

SDCC assumes a generic HC08 target. The memory map of the S08JS has some differences that need to be addressed by providing additional flags to both the compile and the link stage.
For the compile stage:
sdcc -c -mhc08 --stack-loc 0x027F main.c
besides the obvious -mhc08 to instruct the compiler to compile for Freescale HC08 architecture instead of the default 8051, it is necessary to add the --stack-loc to specify where the stack should be placed in memory (this flag is only required when compiling the file containing main() but it does not hurt to use it when compiling other files).

For the link stage:
sdcc -o example.out -mhc08 --data-loc 0x80 --xram-loc 0x0100 --xram-size 0x0180 \
--code-loc 0xC400 --code-size 0x3c00 main.rel file1.rel file2.rel
the options specify the start location of free zero page RAM (--data-loc), the start and size of other RAM (--xram-loc and --xram-size) and the start and size of the program flash (--code-loc and --code-size).
The flash on S08JS16 starts at 0xc000 (not 0xC400 as specified above), but the first 1K is usually used to store configuration parameters (EEPROM emulation) so it should not contain any generated code.
For S08JS8 code location and code size should be changed to 0xE400 and 0x1C00 respectively.

Generating the CRC

Directly flashing the resulting file from above will not work as the ROM bootloader in the S08JS series will refuse to execute from flash unless a correct CRC16 is stored at location 0xFFB8-0xFFB9.
A simple way to overcome this issue is to set the CRC bypass byte in the flash by adding the following line to any of the compiled files:
const unsigned char __at 0xffba byp = 0x00;

A more elegant solution is to compute the correct CRC and place in the S-Record file before flashing it.
For S08JS16 the correct CRC can be generated using srec_cat (part of the SRecord package):
srec_cat '(' example.out -fill 0xff 0x0000 0xffff -crop 0xc400 0xffae 0xffc0 0x10000 \
-generate 0x100 0x102 --b-e-constant 0x1b9d 2 ')' \
-big_endian_crc16 0xffb8 -xmodem -crop 0xffb8 0xffba -o example.crc 2>/dev/null
For S08JS8 it is necessary to change the 0xc400 to 0xe400 in the crop parameters.
The line is relatively complex because of the non-standard CRC seed used by the S08JS bootloader and limitation in srec_cat in specifying an arbitrary seed.
After the generation of the CRC it is easy to add it to the original code using srec_cat again:
srec_cat -Header Example_Firmware example.out example.crc -o example.s19 2>/dev/null
The above line generates a S-Record file ready to be flashed.

Flashing

A standard BDM tool can be used to flash the file generated by the previous step.
If a BDM tool is not available, it is possible to use the S08JS ROM bootloader to upload the firmware using the USB interface. The S08JS will execute the bootloader code if the flash is blank or corrupt or if the BLMS# pin is pulled to GND during power on.
Once the MCU is running the bootloader code it can be flashed using the Freescale GUI for windows or using flashjs:
gorlik@tux4:~$ flashjs m
JS16 MCU Detected (index 1)
Mass erase successfull
gorlik@tux4:~$ flashjs p example.s19
JS16 MCU Detected (index 1)
firmware: Example_Firmware
........
gorlik@tux4:~$ flashjs c
JS16 MCU Detected (index 1)
CRC check OK
gorlik@tux4:~$ flashjs x
JS16 MCU Detected (index 1)

Downloads

A simple interrupt based blinky demo application configured for the gglabs ujs board is available in the attachments section.
It should be very easy to configure the demo for other boards.

Possible Improvements

• SDCC currently generates only HC08 opcodes and does not support any of the S08 specific enhancements. Adding this support will improve code density and executing speed of the compiled firmware.
• CRC generation is a ugly hack. Adding CRC seed capability to SRecord would make it much cleaner.
• There is no free debugger available for the S08.