Over a million developers have joined DZone.

Binary Files for the mbed Bootloader with Eclipse and GNU ARM Eclipse Plugins

DZone's Guide to

Binary Files for the mbed Bootloader with Eclipse and GNU ARM Eclipse Plugins

· Performance Zone
Free Resource

The existing OpenSDAv1 (see “OpenSDA on the Freedom KL25Z Board“) bootloader is using the industry standard Motorola S-Record (S19) Files. However, new FRDM-K64F board (see “FTF: FRDM-K64F, Kinetis Design Studio and Kinetis SDK“) has OpenSDAv2 on it, which is an mbed bootloader. So how to create files with an IDE other than mbed for that bootloader which is present on the FRDM-K64F board by default? Well, creating binary files is one thing, but to have it working with the mbed bootloader is another challenge.

mbed Bootloader and Binary Files

The mbed firmware running on the Kinetis K20 of the FRDM-K64F board has three functions:

  1. Debug Interface as USB HID device implementing CMSIS-DAP
  2. Serial-to-USB bridge (unfortunately it is *not* a USB CDC device class, so it requires a proprietary mbed USB driver for this).
  3. MSD (Mass Storage Device) USB Bootloader.

It is interesting to see that the Debug interface is using a USB HID (Human Interface Device Class). So for the host this looks like a keyboard or a mouse (which are HID devices too). The advantage of this approach is that no drivers are needed on the host. However, the HID interface is very slow compared to other device classes (well, a keyboard or a mouse does not have to be really fast), so this probably explains why the mbed debug interface speed is somewhat ok, but not as fast as e.g. a P&E Multilink or Segger J-Link?

The 3rd function is of interest here: the mbed OpenSDAv2 firmware looks like a USB memory (stick) device where I can copy files to it, and it will program the target processor. This functionality exists in the OpenSDAv1 firmware for other boards too (e.g. FRDM-KL25Z).

While the OpenSDAv1 firmware accepts Motorola S19 files, for strange reasons the mbed MSD bootloader only accepts binary (*.BIN) files.

I very much prefer the standard S19 files, as they are easily generated by any tools, and there are many tools to convert/deal/change S19 files. It is not clear to me why the mbed bootloader only accepts BIN files: the S19 files are industry standard, easy to generate and handle. Yes, S19 files use two bytes for every code byte because it is an ASCII format. That would make a difference if the connection speed to the bootloader would be limited, but this is not the case with OpenSDAv2: I mean USB is not a ‘few bytes per second’ communication protocol where a binary protocol would make sense?

Creating Binary Files with GNU ARM Eclipse Plugins

Both my Eclipse Kepler (see “GNU Additional Tools: Create Flash Image, Print Size and Extended Listing Options“) and as well KDS include the GNU ARM Eclipse plugins. CodeWarrior has a somewhat older/similar plugin too, see “S-Record Generation with gcc for ARM/Kinetis” how to create S19/binary files with CodeWarrior.

To generate a binary file for the mbed MSD bootloader, go to the project settings (menu Project > Properties), and to the Toolchains Tab under C/C++ Build > Settings:

Enable ‘Create flash image’ and press the ‘Apply’ button.

Then switch to the ‘Tool Settings’ tab, go to the General settings of ‘Cross ARM GNU Create Flash Image’ and choose ‘Raw binary’:

Press ‘Ok’ and build your project. The binary file will be created in the project output folder:

Bugs in mbed Bootloader?

So far so good, if there would not be a bug in the mbed MSD bootloader. There are two issues associated with the mbed MSD bootloader I’m aware of (and I have lost a lot of time finding out the problem. It is especially bad as it might brick your board, and it might be hard to recover the board, see “Recovering FRDM-K64F mbed Board”.

  1. The board get bricked if the binary file has all the flash security bits set to 0xFF, or if the flash configuration fields are missing/not set in the application. See “How (not) to Secure my Microcontroller” on this issue.
  2. Even if the NV_FSEC Backdoor Key Security field of the flash configuration is configured propery, the mbed bootloader will screw up the board.

Note that the two above issues are *not* present if using OpenSDAv1, P&E Multilink or Segger J-Link (for me yet another good reason to spend little money a good piece of debug probe compared to waste a lot of time …).

KEYEN FSEC Settings: Backdoor Key Security Enable

The issue is with the KEYEN (2 bits) in the FSEC (Flash Security) settings. The K64F reference manual documents it like this:

0b00, 0b01 and 0b11 settings disable the backdoor keys, and 01 is the preferred way. However, somehow the mbed bootloader only seems to accept 0b11. Somehow the mbed library uses 0b11, but if you are using other libraries/tool chains or Processor Expert, then very likely the default value 0b01 is used, which then bricks my FRDM-K64F board.

This can be easily reproduced with a small example. In the example startup code below used with the Kinetis SDK, the flash configuration settings are configured after the vector table:

If the last word is 0xFFFFFF7E, this will brick your board, while 0xFFFFFFFE works fine. Both values shall work the same according to the Freescale reference manual.

Same problem if I’m using Processor Expert and want to load that generated binary file with the mbed MSD bootloader:

That (correct) 0x7EU value bricks the board. The workaround is to use 0xFEU instead (see “Disable my Code Generation” how to change the code manually).

I have submitted that problem, so hopefully it will be addressed by an update of the mbed bootloader. Until then, at least to know one reason which bricks the board is better than not knowing.


The mbed MSD bootloader requires binary (.BIN) files. Generating binary files is very well possible with GNU tools and easy with the GNU ARM Eclipse build plugins (see http://gnuarmeclipse.livius.net/blog/). The current mbed bootloader has an issue with the FSEC security bits: if they are not set the way the bootloader expects them, it will brick the board. Ways how to recover the board are discussed in “Recovering FRDM-K64F mbed Board“. I admit that this problem does not occur if you are inside the ‘mbed system’: but I hope that mbed will get to a point that it will be easier to be used with ‘offline’ tools too. I looking forward to that.

Happy Bootloading!

Published at DZone with permission of Erich Styger, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}