Configuring the Gecko Bootloader#

Configuring Storage#

Gecko Bootloaders configured as application bootloaders must include an API to store and access image files. This API is based on the concept of storage slots, where each slot has a predefined size and location in memory and can be used to store a single upgrade image. Slots are configured in the Bootloader Storage Slot Setup component.

When multiple storage slots are configured, a bootload list is used to indicate the order in which the bootloader should access slots to find upgrade images. If multiple storage slots are supported, the application should write the bootload list by calling bootloader_setImageToBootload before rebooting into the bootloader to initiate a firmware upgrade process. The bootloader attempts to verify the images in these storage slots in sequence and applies the first image to pass verification. If only a single storage slot is supported, the bootloader uses this slot implicitly. A maximum of three slots may be configured in the Bootloader Storage Slot Setup component.

SPI Flash Storage Configuration#

When configuring a Gecko Bootloader to obtain images from SPI flash, modify the following.

The base address of the storage area should be configured in the Common Storage component. This is the address at which the bootloader places the bootload list, if more than one storage slot is configured. In the default configuration, this address is set to 0. If only a single storage slot is configured, the bootload list is not used, so configuring it may be omitted.

The location and size of the storage slots can be configured using the Bootloader Storage Slot Setup component (supports a maximum of three configurable storage slots). The addresses input here are absolute addresses (they are not offsets from the base address). If more than a single slot is configured, space must be reserved between the base address as configured in the Common Storage component and the first storage slot configured in the Bootloader Storage Slot Setup component. Enough space to fit two copies of the bootload list must be reserved. These two copies need to reside on different flash pages, to provide redundancy in case of power loss during writing. Two full flash pages therefore need to be reserved. In the default example application, a SPI flash part with 4 kB flash sectors is used. This means that 8 kB must be reserved before the first storage slot. The following figure illustrates how the storage area can be partitioned, where the numbers in the top row represent the starting addresses.

Internal Storage Configuration#

When configuring a Gecko Bootloader to obtain images from internal flash, modify the following.

The base address of the storage area should be configured in the Common Storage component. This is the address at which the bootloader will place the prioritized list of storage slots to attempt to bootload from, if more than one storage slot is configured. In the default configuration, only a single storage slot is configured, so this value is set to 0, and isn’t used. If more than one storage slot is configured, this value needs to be configured too.

The location and size of the storage slots can be configured using the Bootloader Storage Slot Setup Component (supports a maximum of three configurable storage slots). The addresses input here are absolute addresses (they are not offsets from the base address). If more than a single slot is configured, enough space must be reserved between the base address as configured in the Common Storage component and the first storage slot configured in the Bootloader Storage Slot Setup component. Enough space to fit two copies of the bootload list must be reserved. These two copies need to reside on different flash pages, to provide redundancy in case of power loss during writing. Two full flash pages therefore need to be reserved. The following figure illustrates how the storage area can be partitioned.

Note: The storage area partitioning in the example for two storage slots above does not take any NVM system into account. If using an NVM system like SimEE or PS Store, take care to place and size the storage area in such a way that bootloader storage does not overlap with NVM.

Compressed Upgrade Images#

The Gecko Bootloader optionally supports compressed GBL files. In a compressed GBL file, only the application upgrade data is compressed, any metadata and bootloader upgrade data (if present) stay uncompressed. This means that a compressed GBL file is identical to a normal (uncompressed) GBL file, except that the GBL Programming Tag containing the application upgrade image (as described in UG103.6: Bootloader Fundamentals) has been replaced by a GBL LZ4 Compressed Programming Tag or GBL LZMA Compressed Programming Tag. Signature and encryption operations on a compressed GBL work identically to on an uncompressed GBL.

To be able to use compressed upgrade images, a decompressor for the relevant compression algorithm must be added to the Gecko bootloader. The following table shows which compression algorithms are supported by the Gecko Bootloader, and which Bootloader component should be added to enable the feature. The table also shows how much space the decompressor takes up in the bootloader, and how big of a size reduction to expect for the compressed application upgrade image. Be aware of the bootloader size requirement. The bootloader space might be too small to fit the decompressors, depending on the device and enabled components.

It is important to note that the compressed GBL file stays compressed while being transferred to the device, and while it is stored in the upgrade area. It is decompressed by the bootloader when the upgrade is applied. This means that the running application in main flash will be identical to one that was installed using an uncompressed (normal) GBL file.

Compressed GBL files can only be decompressed by the bootloader when running standalone, not through the Application Interface. This means that upgrade image verification performed by the application prior to reboot will not attempt to decompress the application upgrade, it will only verify the signature of the compressed payload. After rebooting into the bootloader, it will decompress the image as part of the upgrade process.

Note: The above means that Bluetooth in-place application upgrades cannot be compressed, as they are processed by the Bluetooth Supervisor or AppLoader using functionality in the bootloader through the Application Interface. Supervisor/stack and AppLoader updates can be compressed, but the user application cannot.

LZMA Compression Settings#

LZMA decompression is only supported for images compressed with certain compression settings. Simplicity Commander automatically uses these settings when using the commander gbl create --compress lzma command.

• Probability model counters: lp + lc <= 2. Simplicity Commander uses lp=1, lc=1.

• Dictionary size no greater than 8 kB. Simplicity Commander uses 8 kB.

Together, these settings cause the decompressor to require 18 kB of RAM for decompression – 10 kB for the counters and 8 kB for the dictionary.

The GBL LZMA Compressed Programming Tag contains a full LZMA file, containing the LZMA header, raw stream, and end mark. The Gecko bootloader only supports decompressing payloads that contain the end mark as the last 8 bytes of the compressed stream.

Bootloader Example Configurations#

The following sections describe the key configuration options for the example bootloader applications.

Note: Security features are disabled for all example configurations. In development, Silicon Labs strongly recommends enabling security features to prevent unauthorized parties from uploading untrusted program code. See section Using Application Image Security Features to learn how to configure the security features of the Gecko Bootloader.

UART XMODEM Bootloader#

Standalone bootloader for EFM32 and EFR32 devices running the EmberZNet PRO and Silicon Labs Connect protocol stacks, using XMODEM-CRC over UART.

In this configuration, the UART XMODEM communication component, XMODEM Parser component, and Bootloader UART Driver component are installed. For the example application to run on a custom board, the GPIO ports and pins used for UART need to be configured in the Bootloader UART Driver component. Here, Hardware Flow Control can be enabled or disabled, and the baud rate and pinout can be configured.

The GPIO activation component is also installed by default, allowing bootloader entry into firmware upgrade mode by activating a GPIO through reset. The GPIO pin used can be configured here. This component can be uninstalled if this functionality is not desired.

BGAPI UART DFU Bootloader#

Standalone bootloader for the Bluetooth protocol stack, using the BGAPI protocol for UART DFU. This bootloader should be used for all NCP-mode Bluetooth applications.

In this configuration, the BGAPI UART DFU communication component and Bootloader UART Driver component are installed. For the example application to run on a custom board, the GPIO ports and pins used for UART need to be configured in the Bootloader UART Driver component. Here, Hardware Flow Control can be enabled or disabled, and the baud rate and pinout can be configured.

The GPIO activation component is also installed by default, allowing bootloader entry by activating a GPIO through reset. The GPIO pin used can be configured here. This component can be uninstalled if this functionality is not desired.

EZSP SPI Bootloader#

Standalone bootloader for EmberZNet PRO and Silicon Labs Connect protocol stacks using EZSP for SPI.

In this configuration, the EZSP-SPI communication component, XMODEM Parser component, and Bootloader SPI Peripheral Driver component are installed. For the example application to run on a custom board, the GPIO ports and pins used for SPI and EZSP signaling need to be configured in the Bootloader SPI Peripheral Driver and EZSP-SPI components, respectively.

The EZSP GPIO activation component is also installed by default, allowing bootloader entry into firmware upgrade mode by activating a GPIO through reset. The GPIO pin used can be configured here. This component can be uninstalled if this functionality is not desired.

Bluetooth AppLoader OTA DFU Bootloader#

Standalone bootloader for the Bluetooth protocol stack, using Bluetooth for Over-The-Air DFU.

In this configuration, the Bluetooth AppLoader communication component is installed.

SPI Flash Storage Bootloader#

Application bootloader for all wireless protocol stacks, using an external SPI flash to store upgrade images received over the air by the application.

In this configuration, the SPI Flash Storage and Common Storage components, as well as the Bootloader SPI Controller Driver component, are installed. For the example application to run on a custom board, the GPIO ports and pins used for SPI communication with the external flash need to be configured in the Bootloader SPI Controller Driver component, and the type of SPI flash needs to be configured in the SPI Flash Storage component. The base address of the storage area can be configured in the Common Storage component. The location and size of the storage slots themselves can be configured using the Bootloader Storage Slot Setup component (supports up to three configurable storage slots).

The SPI Flash storage bootloader provides customizable callback functions, which can be found in bootloader-callback-stubs.c. The callback functions storage_customInit and storage_customShutdown, for example, can be used for custom hardware setups. Those callback functions can be interfaced from the applications using the bootloader interface functions such as bootloader_init and bootloader_deinit from api/btl_interface.h.

Currently, Silicon Labs supports the following SPI Flash storage bootloaders:

1. SPI Flash storage bootloader (multiple images)

2. SPI Flash storage bootloader (single image)

3. SPI Flash storage bootloader (single image with slot size of 1MB). Note: This bootloader should only be used for systems with an external SPI Flash size >= 1 MB.

SPI Flash Storage Bootloader SFDP#

Application bootloader for all wireless protocol stacks, using an external SPI flash to store upgrade images received over the air by the application.

In this configuration, the SPI Flash Storage SFDP and Common Storage components, as well as the Bootloader SPI Controller Driver component, are installed. For the example application to run on a custom board, the GPIO ports and pins used for SPI communication with the external flash need to be configured in the Bootloader SPI Controller Driver component. The type of SPI flash is detected at runtime. The base address of the storage area can be configured in the Common Storage component. The location and size of the storage slots themselves can be configured using the Bootloader Storage Slot Setup component (supports up to three configurable storage slots).

The SPI Flash storage bootloader SFDP provides customizable callback functions, which can be found in bootloader-callback-stubs.c. The callback functions storage_customInit and storage_customShutdown, for example, can be used for custom hardware setups. Those callback functions can be interfaced from the applications using the bootloader interface functions such as bootloader_init and bootloader_deinit from api/btl_interface.h.

Internal Storage Bootloader#

Application bootloader for all wireless protocol stacks, using internal flash to store upgrade images received over the air by the application.

Multiple examples are provided, including configurations for 512 kB flash memory devices like EFR32xG13, 1024 kB flash memory devices like EFR32xG12, and 2048 kB flash memory devices like EFM32GG11. The storage layout should be modified before running the bootloader on any other devices. In this configuration, the internal flash and common storage components are installed. The base address of the storage area is configured in the Common Storage component. The location and size of the storage slots can be configured using the Bootloader Storage Slot Setup component (provides up to three configurable storage slots). Default example applications are provided with configurations for both single storage slot and multiple storage slots.

The default storage slot configurations provided by the Gecko Bootloader must be configured to match the use-case-specific application configurations.

Table: Internal Storage Bootloader Default Storage Configurations

Image Acquisition Application Example Configuration#

These examples illustrate applications that acquire and store a GBL upload image for an application bootloader. For the running bootloader to accept an application upgrade, the new application version must be higher than the existing version. The version number can be set in Appbuilder by defining the macro “APP_PROPERTIES_VERSION” in the Additional Macros field on the Other tab.

Setting a Version Number#

To distinguish between different builds of the Gecko Bootloader, it is useful to set a version number. To perform a bootloader upgrade, not only must the running bootloader pass its integrity checks (see section Downloading and Applying a Bootloader GBL Upgrade File), but the bootloader upgrade image must also have a higher version number than the running bootloader image. A version number can be set using Simplicity Studio by configuring the Bootloader Version Main Customer option of the Bootloader Core component. This macro will be picked up by the config file btl_config.h, where it is combined with the version number of the Gecko Bootloader files provided by Silicon Labs.

Placing Bootloader in Main Flash#

For device families xG13 and xG14, the entire main stage bootloader might not fit into the bootloader flash if the user installs some extra components. In such scenarios, the main stage bootloader can be placed in the main flash by installing the Bootloader in Main Flash core component. This component internally provides a MACRO named MAIN_BOOTLOADER_IN_MAIN_FLASH which is used to set the appropriate address required to place the main bootloader in main flash. The MACRO is used to generate the linker file from the common linker template with the appropriate addresses to place the main stage bootloader in the main flash.

Hardware Configuration#

The Gecko Bootloader uses the Pin Tool for configuration of pinout and other hardware-related settings. When Pin Tool configuration is available for a bootloader component, the relevant settings are shown in the Component Editor for that component.

The standalone Pin Tool User Interface can also be used to configure settings for Gecko Bootloader if desired.

While the Pin Tool provides configuration for many different peripherals, the Gecko Bootloader uses only the following Pin Tool modules:

• SERIAL is used by the UART Driver component to configure baud rate, flow control mode and pinout.

• VCOM is used by the UART Driver component to enable the serial interface if necessary (only on Silicon Labs Wireless Starter Kits).

• EXTFLASH is used by the SPI Driver to configure frequency and pinout.

• SPINCP is used by the SPI Slave Driver to configure pinout.

• BTL_BUTTON is used by the GPIO Activation component.

• CMU HFXO frequency setting is used by the delay driver to calibrate timing if the core is running from the HFXO.

Other settings, like CMU oscillator configuration or DCDC configuration, are not taken into consideration by the default bootloader code. If using these configuration settings is desired, the required code must be added in btl_main.c.

Note: While the delay driver uses the HFXO frequency setting from Pin Tool, the HFXO enable setting is not used to initialize the HFXO on startup. This setting is only used when calling the bootloader through the Application Interface (see section Gecko Bootloader and TrustZone), and the application has switched to the HFXO prior to calling the Bootloader Application Interface API.

Size Requirements for Different Bootloader Configurations for Series 1 Devices#

Enabling different configuration options for the Gecko Bootloader changes the size of the resulting image. The following table shows a list of example bootloader configurations and the resulting approximate size of the main bootloader. Note that any size above 14 kB will be too large to fit in the bootloader area of flash of EFR32xG13, and that any size above 16 kB will be too large to fit in the bootloader area of flash on EFR32xG14 and EFM32TG11. This table was last updated for Gecko SDK Suite 4.0 (Gecko Bootloader 2.0), and no guarantees are made that a configuration of a specific size with one SDK version will maintain that size in future releases.

Table: Bootloader Size Requirements