This application note was already officially released. Please, download it from:
AN12086 Simple Serial Bootloader for S12Z
1. Introduction
This application note covers the operation and use of a simple serial Bootloader for the S12Z microcontroller families.
The Bootloader can be a convenient way to support programming during production or “in-system”, where support for the dedicated HCS12 Background Debug interface (BDM) may not be available. Users must pre-program the S12Z MCU with the Bootloader during production or at a programming vendor.
The Bootloader should reside in the MCU for further use.
This Bootloader implementation allows User Application software to be downloaded into the MCU flash and EEPROM memory using the SCI serial interface. The Bootloader may be also configured for self-update similar way as a User Application software update.
This Bootloader is originally based on AN4258 Serial Bootloader for S12(X) Microcontrollers Based on 180 nm Technology with several modifications and improvements.
The Bootloader described in this document is only an example and comes with no guarantees and no direct support.
2. Bootloader Overview
The software architecture consists of two independent software projects:
- Bootloader Project
- User Application Project
For avoiding compatibility issues between these projects, the minimum interface points must be kept.
The switching between Bootloader and User Application codes is managed through MCU reset. So, the Bootloader and application are not limited by write-once registers.
The Bootloader Project itself contain small user-defined dispatcher code which is executed directly after MCU reset and decide whether Bootloader or User Application will be executed as next.
Figure 1 Software Architecture
2.1. Hardware Compatibility
The Bootloader is written for S12Z derivatives (S12ZVM, S12ZVMB, S12ZVMA, S12ZVC, S12ZVL, S12ZVH, S12ZVHY and S12ZVFP).
The Bootloader for S12Z microcontrollers is not optimized for the smallest derivatives. Therefore, S12ZVL8 derivative (only 512B RAM) is not supported and only some of derivatives (with 4kB or more RAM) supports Bootloader self-update feature (rewritable).
2.2. Dispatcher code
The Dispatcher code is executed right after MCU reset. It just temporary initializes stack (write stack pointer) and directly executes user code for testing conditions whether Bootloader code should be executed or not. The most typical testing conditions for Bootloader presents:
- pushed button
- some specific value in the EEPROM memory
- waiting loop for command via the communication interface
If User Application code is already loaded and Bootloader was not selected, the User Application is automatically started.
2.3. Serial interface
All S12Z microcontrollers include an on-chip serial communication interface.
Notice that the RS-232 or USB to TTL level shifter is necessary to communicate with PC. Optionally, the virtual COM port at OSBDM interface may be used.
By default, the serial communication is set to format:
- 8-data bit
- one start bit
- one stop bit
- no parity
- Xon / Xoff flow control
Default baud rate is configured in Config.h file. The baud rate can be changed via the Bootloader’s menu to 38400, 57600, or 115200 bps.
The Bootloader implementation currently assumes using just one of SCI channels. However, this may be changed by Bootloader code modification. The same approach may be used for a different type of channel implementation like CAN or LIN.
2.4. PC software interface
A general terminal emulation program like Microsoft HyperTerminal, Tera Term, RealTerm or similar software can be used on a PC to communicate with a microcontroller. A terminal emulation program must support communications over serial COM ports, Xon / Xoff flow control, and it must be able to send a text file.
3. Functional Description
The operation of the Bootloader is straightforward. This section describes only the most important and specific points.
Figure 2 Memory map
3.1. Bootloader Project Folders
The C language codes and appropriate header files are located in Sources and Project_Header folders.
The exception is Dispatcher.c and start12z.c files located in Project_Settings\Startup_Code folder.
The linker file is located in Project_Settings\Linker_Files folder.
The FLASH folder contain generated files like elf, map or s19 files.
The SRecCvt folder contains a SRecCvt.exe tool for re-formating generated S-record file.
The content of Documentation folder should help you in guide how to use this Bootloader.
Figure 3 Bootloader Project Folders
3.2. Bootloader Configuration
The most of the Bootloader configuration settings are collected in Config.h file.
If the modified Bootloader will use any derivative specific registers, the mc9s12zvl128.h and mc9s12zvl128.c files should be replaced with appropriate files from CodeWarrior folders:
"c:\Freescale\CW MCU v10.7\MCU\lib\wizard_data\S12Z\DataBase\device\include\.." and
"c:\Freescale\CW MCU v10.7\MCU\lib\wizard_data\S12Z\DataBase\device\src\.."
And followed by modification of derivative.h file.
The Config.h contains settings for:
- Bootloader feature configuration
- Clock settings
- SCI module settings
- Dispatcher definitions
- MCU derivative configuration and addresses
- Flash Configuration Field configuration
The Bootloader-persistent.prm and Bootloader-rewritable.prm linker files contain definitions of Flash and RAM ranges for Bootloader. The appropriate linker file is selected by Build Configuration.
Figure 4 Build Configuration
3.2.1. Bootloader features
- SECURE_MCU: The MCU may be secured after Bootloader loading (default 0 = MCU unsecured)
- USE_BACKDOOR_KEY: The Flash Configuration Field may already contain Backdoor Key for temporary unsecure of MCU (default 0 = backdoor key 0xFFFF FFFF FFFF FFFF).
- WRITE_EEPROM: When enabled, the Bootloader menu offers an option for erasing EEPROM and program option will be able to program both Flash and EEPROM.
- BOOTLODER_REWRITABLE: When enabled, the Bootloader code is automatically loaded into RAM and allow unprotect, erase and program Bootloader Flash area. This variable is already defined differently in used Build Configurations. That allows us to keep BOOTLODER_REWRITABLE value and selected linker file synchronized.
3.2.2. Serial Channel
- The current S12Z MCU derivatives offer up to 2 SCI channels. The SCI_MODULE defines whether SCI0 or SCI1 will be used for Bootloader communication (default SCI1).
- The DEFAULT_BAUDRATE specifies default SCI baud rate for initial Bootloader menu display (default Baud9600: 9600bps). The baud rate can be changed via the Bootloader’s menu to 38400, 57600, or 115200 bps.
- The S12Z MCU derivatives offer routing options for SCI0, SCI1, and other peripherals channels. The BL_MODRR0 value defines MODRR0 value loaded by Bootloader code after a reset.
Note: The MODRR0 values may be written just once in normal mode and cannot be changed until next MCU reset.
3.2.3. Configure Dispatcher code
The default Dispatcher condition is based on the testing value of pin with push button.
The PUSH_BOTTON defines tested port and pin (default PTP_PTP1) while PB_ACTIVE_LEVEL defines active logic level – when the push button is pressed (default 0 = push button to GND with pull-up). The BL_REQUEST_ADD defines tested address (default 0x100000) while BL_REQUEST_VALUE defines active value for bootloader request key. When the memory content fits to the BL_REQUEST_VALUE, Bootloader code is executed (default "BOOT" in ASCII = 0x424F4F54).
3.2.4. Configure Derivative and addresses
- The FLASH_START_ADD, EEPROM_START_ADD, EEPROM_END_ADD defines MCU derivative memory ranges.
- The BOOTLOADER_START_ADD value is automatically obtained from linker file (ROM segment start).
- The Bootloader automatically move User Application reset vector to the APPLICATION_RESET_VEC_ADD address (default BOOTLOADER_START_ADD-4 = placed to the end of User Application flash area)
3.2.5. Configure Flash Configuration Field
- The bytes from BACKDOOR_KEY_0 to BACKDOOR_KEY_7 defines Backdoor Comparison Key (default "UNSECURE" = 0x554E534543555245 in ASCII).
- The bytes PROTECTION_OVERRIDE_KEY_H and PROTECTION_OVERRIDE_KEY_L defines Protection Override Comparison Key (default "AB" = 0x4142 in ASCII).
- The Bootloader code should be protected against unwanted erase/rewrite operations. Trying to alter data in any protected area in the P-Flash memory will result in a protection violation error and the FPVIOL bit will be set in the FSTAT register. Flash protection scheme allows protecting 2, 4, 8 or 16KB from upper range of Flash memory. The BL_FPROT defines FPROT value automatically loaded from Flash Configuration Field after reset (default 0xD7 = upper 8kB of P-Flash protected.).
- The BL_DFPROT defines DFPROT value automatically loaded from Flash Configuration Field after reset (default 0xFF = EEPROM unprotected).
- The initial configuration of COP watchdog and GDU (S12ZVM derivatives) is given by FOPT register value. The BL_FOPT defines FPROT value automatically loaded from Flash Configuration Field after reset (default 0xFF = COP is not active after reset).
3.2.6. Bootloader linker file
Since the preprocessor functionality is no longer supported directly in prm linker file, the Bootloader use two versions of linker file:
- Bootloader-persistent.prm
- Bootloader-rewritable.prm
The linker file selection is managed by two Build Configurations (Figure 4 Build Configuration).
3.3 Operation
The Bootloader handles reset vector. After reset, the Bootloader’s Dispatcher routine is called. As a first step, the Dispatcher initialize stack and reads the push button pin status. If the value of the pin is equal to the PB_ACTIVE_LEVEL, the Bootloader starts its operation. If the value of this pin is not equal to the PB_ACTIVE_LEVEL, the User Application’s reset vector is tested. If the reset vector of the User Application is not available (long word at address APPLICATION_RESET_VEC_ADD is in erased state = 0xFFFFFFFF) then the Bootloader is called anyway.
The User Application is called only when User Application reset vector is already programmed and the condition for Bootloader enter is not true. The user can rewrite this code to start the Bootloader or User Application upon another condition.
Note: Since this code is executed prior Bootloader/application startup code, the dispatcher code shouldn’t use any uninitialized global variables.
3.4. Interrupt vector
In the case when the User Application using interrupts, it is necessary to relocate the interrupt vector table using the IVBR register.
The Bootloader resides in the upper 4/8/16kB fixed block at the address defined by linker prm file. This area is had to be protected (configured in Config.h), so the User Application cannot rewrite a default location of the interrupt vector table at 0xFFFE10-0xFFFFFF. The advantage of this solution is that the Bootloader cannot be affected by a power failure that could occur when rewriting User Application interrupt and reset vectors.
The Bootloader automatically moves User Application’s reset vector from address 0xFFFFFD to the APPLICATION_RESET_VEC_ADD address = typically the end of User Application’s flash area. Since this moving is managed by the Bootloader, the whole phrase (by default from (BOOTLOADER_START_ADD-8) to BOOTLOADER_START_ADD) must be excluded from User Application’s linker usage and the same sector (512B) shouldn’t be used for User Application’s interrupt vector table.
4. User Guide
This section describes the step-by-step procedure to use the Bootloader.
4.1. Setup procedure for the Bootloader
- Open the Simple_Serial_Bootloader_for_S12Z project in CodeWarrior Development Studio for MCU. The Bootloader was tested in current versions v10.7.
- Select the Build Configuration as shown in Figure 4 Build Configuration. The Persistent Bootloader code option allows just update a User Application. The Bootloader Rewritable code option linker allows updating both User Application and Bootloader itself.
- Optionally edit appropriate linker file
- Optionally edit the Config.h header file per your target environment (required features, clocks, channels, derivative addresses, backdoor, and protection override keys).
- Optionally edit the c file with conditions for select User Application/Bootloader code execution.
4.2. Bootloader Guide
1. Compile the project and download the Bootloader to the MCU via BDM device.
Note: The correct derivative should be selected in debug configuration for successful complete MCU Flash erase and programming (Figure 5 Select derivative for Bootloader download).
Figure 5 Select derivative for Bootloader download
2. Open the Microsoft HyperTerminal or any other serial terminal utility (e.g. Realterm, Tera Term,…). Set the baud rate 9600 bps, 1 start bit, 8 data bits, 1 stop bit, and flow control Xon / Xoff.
3. Make sure there is a serial (USB to Serial) cable connection between the PC and the board.
4. Hold the PUSH_BOTTON pin low and reset the MCU.
5. The Bootloader is started and the following response is received in HyperTerminal. See Figure 6 Initial screen.
Figure 6 Initial screen
6. Type “a” to erase the flash memory. This is not necessary the first time because the flash has been already erased by the BDM device.
7. Type “b” to program the flash.
8. Now send the desired S-record as a text file — See Figure 7 Send Text File. Browse for S-record which is downloaded to the MCU. For testing purposes, use demo S-records that are attached to this application note. The S-records must have a specified format. Refer to chapter 3 How to write a User Application and to chapter 4.4 How to convert S-Record that will be downloaded by the Bootloader.
Figure 7 Send Text File
9. Confirm the dialog and the S-record are downloaded to the MCU. One printed star (*) means that one line of S-record has been programmed. See Figure 8 Download User Application.
Figure 8 Download User Application
Note: If User Application contains any EEPROM data, please erase EEPROM by typing “h” prior the step 7.
Note: If you want to reprogram Bootloader code, please use subsequently options “e” (it will ask you for entering protection override key), step “f” and step “g” instead steps 6 and 7.
4.3. How to write a User Application
You must ensure that the User Application does not interfere with Bootloader area defined by Bootloader linker file.
1. Create a new User Application project in CodeWarrior Development Studio for MCU.
2. Open the User Application project.prm file
3. Trim the high address of the segment ROM from the original to the (BOOTLOADER_START_ADD-8). For example, to the address 0xFFDFF7. This is because the area 0xFFDFF8–0xFFFFFF is occupied by the Bootloader and the area at address 0xFFDFF8–0xFFDFFF will be used for the User Application reset vector.
If interrupts are used:
4. Trim the low address of the segment ROM from the original to (the original address + 0x200). This area will be used for the relocated interrupt vector table.
Note: You may use any other Flash sector in User Application memory for that purpose except the last one (already used for the User Application reset vector).
Note: The generated CodeWarrior project doesn’t show warning about memory overlapping between linker and user object placement. This warning is disabled by default (Linker option -WmsgSd1912).
5. Create a vector table as shown in the attached demo applications and set the IVBR register accordingly. The IVBR sets the interrupt vector table base address. It contains 15 most significant bits from 24bit vector table address.
4.4. How to convert S-Record that will be downloaded by the Bootloader
The default S12Z MCU project generated by CW10 does not generate a file with s-records automatically.
1. Check option for generating S-Record file in User Application project settings per Figure 9 Generate S-Record file
The <YourProjectName>.sx file will be generated when you will build your project.
Figure 9 Generate S-Record file
For the simplifying, the Bootloader parser, only s-records with specific format are accepted. All records must be aligned to 32 bytes and the length of records must be 32 bytes.
2. Copy SRecCvt directory with SRecCvt.exe tool from Bootloader/Application Example project to your User Application project
3. Exter command “${ProjDirPath}/SRecCvt/sreccvt.exe -hc12 -m 100000 FFFFFF 32 -o ..\FLASH\\${BuildArtifactFileBaseName}.s19 ..\FLASH\\${BuildArtifactFileBaseName}.sx” as post build step into User Application project settings per Figure 10 Adding Post-build step.
Figure 10 Adding Post-build step
This command will load S-Records from your <YourProjectName>.sx file and create new <YourProjectName>.s19 file with reformatted S-Records when you build your project.
Note: The complete SRecCvt utility may be downloaded from NXP web pages. Unfortunately, the graphical user interface doesn’t support directly S12Z derivatives. Therefore we use this tool in command line mode.
4.5. How to merge the User Application and Bootloader
The User Application can be developed independently, that is without the Bootloader. The User Application can be loaded into the microcontroller and can be debugged directly via the BDM device. However, for production purposes, it is worth merging the User Application and Bootloader together, so it can be downloaded into the microcontroller all at once as a single S-Record file.
This is a recommended procedure:
1. Open the User Application that was created as per chapter 3, "How to write a User Application" in the CodeWarrior Development Studio for MCU.
2. Replace a User Application reset vector in Project.prm file from default address to the address (BOOTLOADER_START_ADD-3), so the Bootloader can use this vector for start User Application. For example:
//VECTOR 0 _Startup
VECTOR ADDRESS 0xFFDFFD _Startup
3. Copy the ready-mades19 file to ..\user_application_project\FLASH directory.
Note: the s-record file can be renamed for example to the bootloader.s19.
4. Link this file to the User Application be using command at the beginning of Project.prm:
HEXFILE Simple_Serial_Bootloader_for_S12Z.s19
5. Build the project. The final S-Record is ready to be downloaded into the microcontroller by the BDM interface.
5. Testing
The Bootloader and example application were tested on evaluation boards:
- DEVKIT-ZVL128
- S12ZVMC256EVB
- S12ZVM32EVB
- S12ZVM-MINIBRD
6. Content of Zip file
All mentioned projects and utilities can be found in a zip file associated with this application note:
- Simple_Serial_Bootloader_for_S12Z — Bootloader project for S12Z microcontrollers.
- Application_Example_for_SSBZ — Projects that show how to write User Applications.
- Converted_srecords — S-Records was taken from Bootloader and Application Example that has been converted by the SRecCvt utility (*.s19 file extension). These S-Record files can be downloaded into the MCU by the Bootloader.
- SRecCvt — Utility for S-Record files converting.
7. Reference
- AN4258 AN4258SW: Serial Bootloader for S12(X) Microcontrollers Based on 180 nm Technology Rev 0. February 2011.
- S12Z Protection Override
- S12Z constant, variable, code allocation in CodeWarrior
- S12Z Interrupt catcher for unexpected interrupts
- S12Z Flash example code
- S12Z EEPROM example code
I hope it help you. Please let me know when you find any error or if something missing in this document.
Radek Sestak
