Using the Gecko Application Bootloader#

Acquiring a New Image#

The application bootloader relies on application code to obtain new code images. The bootloader itself only knows how to read a GBL image stored in the download space and copy the relevant portions to the main flash block. This approach means that the application developer is free to acquire the new code image in any way that makes sense (serial, OTA, and so on).

Typically, application developers choose to acquire the new code image over-the-air (OTA) since this is readily available on all devices. The acquisition of a new image in Connect is covered extensively in the Connect Users Guide, UG435.

Performing an Application Upgrade#

The application and the bootloader have limited indirect contact. Their only interaction is through passing non-volatile data across module reboots.

Once the application decides to install a new image saved in the download space it calls the Ember HAL API halAppBootloaderInstallNewImage(). This call indicates to the bootloader that it should attempt to perform a firmware upgrade from storage slot 0, and reboots the device. This API is backwards-compatible with the legacy Ember bootloader. If performing a firmware upgrade from a different storage slot than slot 0 is desired, the Gecko Bootloader API should be used instead, by calling bootloader_setBootloadList(). If the bootloader fails to install the new image, it sets the reset cause to RESET_BOOTLOADER_BADIMAGE and resets the module. Upon startup, the application should read the reset cause with halGetExtendedResetInfo(). If the reset cause is set to RESET_BOOTLOADER_BADIMAGE, the application knows the install process failed and can attempt to obtain a new image. A printable error string can be acquired from calling halGetExtendedResetString(). Under normal circumstances, the application bootloader does not print anything on the serial line.

External Storage Application Bootloader#

See UG266: Silicon Labs Gecko Bootloader User’s Guide for information about memory configuration for external storage bootloaders.

Application bootloaders typically use an external device to store the downloaded application image. This device can be accessed over either an I2C or SPI serial interface. Refer to UG266: Silicon Labs Gecko Bootloader User’s Guide for a list of supported Dataflash/EEPROM devices. It is important to select a device whose size is at least the size of your flash in order to fit the application being bootloaded.

The default recommendation for external SPI serial flash is the MX25R, as this is available in standard and smaller packages, is supported by standard drivers, and has very low software-enabled sleep current without the need for an external shutdown control circuit. Most radio boards from Silicon Labs are populated with the MX25R8035F for evaluation purposes. In general, customers should use parts that have low sleep current, don't require external shutdown control circuitry, and have software shutdown control. When using components with high idle/sleep current and no software shutdown control, an external shutdown control circuit is recommended to reduce sleep current.

For EFR32xG1, only the serial dataflash option is available; no internal storage application bootloader is presently offered.

Note: Some of these chips have compatible pinouts with others, but there are several incompatible variations. Contact Silicon Labs for details on connecting I2C or other SPI dataflash chips to an EFR32.

Read-Modify-Write pertains to a feature of certain dataflash chips that their corresponding driver exposes, and that is exploited by the bootloader library. Chips without this feature require a page erase to be performed before writing to that page, which precludes random-access writes by an application.

Internal Storage Application Bootloader#

The internal storage bootloader is essentially an application bootloader with a data flash driver that uses a portion of the on-chip flash for image storage instead of an external storage chip. See UG266: Gecko Bootloader User’s Guide for information about memory configuration for internal storage.

If you don’t modify the flash layout of your application, the NVMv3 token storage is at the end of the flash memory. By default, our internal storage bootloader sets up a slot that protects at least the default 36k of token storage (48k on some parts). This configuration however has some drawbacks:

• You might want to optimize your storage space, and use a smaller NVMv3 token storage, in which case the bootloader protects more than what it needs to.

• Apart from the size outputs of the compiler, you won’t get notified if you run out of flash space. If you program the device directly, not through the bootloader, you are allowed to overlap your application with OTA storage, which will cause failure the first time you erase the OTA storage (depicted in the middle below)

To avoid these problems, you can modify your main application’s memory allocation in the memory editor. For example, a typical application will use half, or a bit more than half, of the flash for the application and NVMv3, while the remainder can be used as OTA storage. The OTA storage can be smaller, because it doesn’t include the NVMv3 and because bootloader can be configured to use compressed images.

Finally, you should configure the bootloader project’s Bootloader Storage Slot Setup component to utilize the space you protected from your application:

Note: On EFR32xG1 and Series 2 devices, the application is offset by 16 kB to accommodate the bootloader at the bottom of main flash. On other EFR32 Series 1 devices, the Gecko Bootloader resides in the Bootloader flash region outside of main flash block.