Silicon Labs UG266, EFR32, EFM32 User Manual
UG266: Silicon Labs Gecko Bootloader
User’s Guide
This document describes the high-level implementation of the Silicon Labs Gecko Bootloader for EFM32 and EFR32 Series 1 and
Series 2 microcontrollers, SoCs (System on Chips) and NCPs
(Network Co-Processors), and provides information on different
aspects of configuring the Gecko Bootloader. If you are not familiar with the basic principles of performing a firmware upgrade or
want more information about upgrade image files, refer to
UG103.6: Bootloader Fundamentals. For more information on using the Gecko Bootloader with different wireless stacks, see the
following:
• AN1084: Using the Gecko Bootloader with EmberZNet
• UG235.06: Bootloading and OTA with Silicon Labs Connect v2.x
• UG435.06: Bootloading and OTA with Silicon Labs Connect v3.x
• AN1086: Using the Gecko Bootloader with Silicon Labs Bluetooth Applications
KEY POINTS
• Describes the Gecko Bootloader
components.
• Summarizes how the Gecko Bootloader
performs application upgrades and
bootloader upgrades.
• Reviews how to create customized
bootloaders in Simplicity Studio.
• Discusses the key configuration changes
for various bootloader types.
• Describes Gecko Bootloader security
features and discusses how to use them.
For more information on Series 2 device security, see:
• AN1218: Series 2 Secure Boot with RTSL
• AN1190: EFR32xG21 Secure Debug
• AN1222: Production Programming of Series 2 Devices
For more information on security using Series 2 devices with Secure Vault, see:
• AN1247: Anti-Tamper Protection Configuration and Use
• AN1268: Authenticating Silicon Labs Devices using Device Certificates
• AN1271: Secure Key Storage
silabs.com | Building a more connected world. Rev. 1.6
Table of Contents
1. Overview .................................4
1.1 Core .................................5
1.1.1 Shared Memory ............................6
1.2 Drivers.................................6
1.3 Plugins ................................6
1.3.1 Communication ............................7
1.3.2 Compression .............................7
1.3.3 Debug ...............................7
1.3.4 GPIO Activation ............................7
1.3.5 Security ...............................7
1.3.6 Storage ...............................8
2. Gecko Bootloader File Format .........................9
2.1 File Structures ..............................9
2.2 Plaintext Tag Description ..........................10
2.3 Encrypted Tag Descriptions .........................11
3. Gecko Bootloader Operation - Application Upgrade ................12
3.1 Standalone Bootloader Operation .......................12
3.1.1 Rebooting Into the Bootloader .......................12
3.1.2 Downloading and Applying a GBL Upgrade File .................12
3.1.3 Booting Into the Application ........................13
3.1.4 Error handling .............................13
3.2 Application Bootloader Operation ........................14
3.2.1 Downloading and Storing a GBL Upgrade Image File ...............15
3.2.2 Rebooting and Applying a GBL Upgrade File ..................15
3.2.3 Booting Into the Application ........................15
4. Gecko Bootloader Operation - Bootloader Upgrade ................16
4.1 Bootloader Upgrade on Bootloaders With Communication Interface (Standalone Bootloaders) ...16
4.1.1 Downloading and Applying a Bootloader GBL Upgrade File .............17
4.1.2 Upgrading Bootloaders Without Secure Boot to Bootloaders With Secure Boot .......17
4.1.3 Enabling Secure Boot RTSL on Series 2 Devices .................18
4.1.4 Downloading and Applying an Application GBL Upgrade File .............18
4.2 Bootloader Upgrade on Application Bootloaders With Storage ..............19
4.2.1 Storage Space Size Configuration ......................20
4.2.2 Upgrading Bootloaders without Secure Boot to Bootloaders with Secure Boot .......20
4.2.3 Enabling Secure Boot RTSL on Series 2 Devices .................21
5. Gecko Bootloader Operation - Secure Element Upgrade ..............22
5.1 Secure Element Upgrade on Bootloaders with Communication Interface (Standalone Bootloaders) .23
5.1.1 Downloading and Applying a Secure Element GBL Upgrade File............24
5.1.2 Downloading and Applying an Application GBL Upgrade File .............24
5.2 Secure Element Upgrade on Application Bootloaders with Storage ............25
silabs.com
| Building a more connected world. Rev. 1.6 | 2
5.2.1 Storage Space Size Configuration ......................25
6. Getting Started with the Gecko Bootloader ...................26
7. Configuring the Gecko Bootloader ......................29
7.1 Configuring Storage ............................29
7.1.1 SPI Flash Storage Configuration ......................29
7.1.2 Internal Storage Configuration .......................30
7.2 Compressed Upgrade Images .........................31
7.2.1 LZMA Compression Settings ........................31
7.3 Bootloader Example Configurations .......................31
7.3.1 UART XMODEM Bootloader ........................32
7.3.2 BGAPI UART DFU Bootloader .......................32
7.3.3 EZSP SPI Bootloader ..........................32
7.3.4 SPI Flash Storage Bootloader .......................32
7.3.5 Internal Storage Bootloader ........................33
7.4 Image Acquisition Application Example Configuration .................33
7.4.1 USB Device Loader ...........................33
7.4.2 USB Host Loader............................34
7.5 Setting a Version Number ..........................34
7.6 Hardware Configuration ...........................35
7.7 Size Requirements for Different Bootloader Configurations for Series 1 Devices ........36
8. Simplicity Commander and the Gecko Bootloader ................37
8.1 Creating GBL Files Using Simplicity Commander ..................37
9. Gecko Bootloader Security Features .....................38
9.1 About Bootloader Image Security ........................38
9.2 About Application Image Security........................38
9.2.1 Secure Boot Procedure .........................39
9.2.2 Secure Firmware Upgrade ........................42
9.3 Using Application Image Security Features ....................42
9.3.1 Generating Keys ............................43
9.3.2 Signing an Application Image for Secure Boot ..................43
9.3.3 Creating a Signed and Encrypted GBL Upgrade Image File From an Application ......44
9.4 System Security Considerations ........................44
9.4.1 Key Storage .............................44
9.4.2 Write-Protecting the Bootloader .......................45
9.4.3 Write-Protecting the Application .......................45
9.4.4 Debug Access.............................45
10. Application Interface ...........................46
10.1 Application Properties ...........................46
10.2 Error Codes ..............................47
silabs.com
| Building a more connected world. Rev. 1.6 | 3
UG266: Silicon Labs Gecko Bootloader User’s Guide
Overview
1. Overview
The Silicon Labs Gecko Bootloader is a common bootloader for all the newer MCUs and wireless MCUs from Silicon Labs. The Gecko
Bootloader can be configured to perform a variety of functions, from device initialization to firmware upgrades. Key features of the bootloader are:
• Useable across Silicon Labs Gecko microcontroller and wireless microcontroller families
• In-field upgradeable
• Configurable
• Enhanced security features, including:
• Secure Boot: When Secure Boot is enabled, the bootloader enforces cryptographic signature verification of the application image
on every boot, using asymmetric cryptography. This ensures that the application was created and signed by a trusted party.
• Signed upgrade image file: The Gecko Bootloader supports enforcing cryptographic signature verification of the upgrade image
file. This allows the bootloader and application to verify that the application or bootloader upgrade comes from a trusted source
before starting the upgrade process, ensuring that the image file was created and signed by a trusted party.
• Encrypted upgrade image file: The image file can also be encrypted to prevent eavesdroppers from acquiring the plaintext firmware image.
The Gecko Bootloader uses a proprietary format for its upgrade images, called GBL (Gecko Bootloader file). These files have the file
extension “.gbl”. See section 2. Gecko Bootloader File Format for more details.
On Series 1 devices, the Gecko Bootloader has a two-stage design, first stage and main stage, where a minimal first stage bootloader
is used to upgrade the main bootloader. The first stage bootloader only contains functionality to read from and write to fixed addresses
in internal flash. To perform a main bootloader upgrade, the running main bootloader verifies the integrity and authenticity of the bootloader upgrade image file. The running main bootloader then writes the upgrade image to a fixed location in internal flash and issues a
reboot into the first stage bootloader. The first stage bootloader verifies the integrity of the main bootloader firmware upgrade image, by
computing a CRC32 checksum before copying the upgrade image to the main bootloader location.
On Series 2 devices, the Gecko bootloader consists only of the main stage bootloader. The main bootloader is upgradable through the
Secure Element. The secure element may be hardware-based, or virtual. Throughout this document, the following conventions will be
used.
• SE - Hardware Secure Element
• VSE - Virtual Secure Element
• Secure Element - Either type, in general.
The Secure Element provides functionality to install an image to address 0x0 in internal flash, by copying from a configurable location in
internal flash. This makes it possible to have a 2-stage design, where the main bootloader is not present. However, the presence of a
main bootloader is assumed throughout this document.
To perform a main bootloader upgrade, the running main bootloader verifies the integrity and authenticity of the bootloader upgrade
image file. The running main bootloader then writes the upgrade image to the upgrade location in flash and requests that the Secure
Element installs it. On some devices, the Secure Element is also capable of verifying the authenticity of the main bootloader update
image against a root of trust. The Secure Element itself is upgradable using the same mechanism. See 5. Gecko Bootloader Operation
- Secure Element Upgrade for more details.
The main bootloader consists of a common core, drivers, and a set of plugins that give the bootloader specific capabilities. The common bootloader core is delivered as a precompiled library, while the plugins are delivered as source code. The common bootloader
core contains functionality to parse GBL files and flash their contents to the device.
The Gecko Bootloader can be configured to perform firmware upgrades in standalone mode (also called a standalone bootloader) or in
application mode (also called an application bootloader), depending on the plugin configuration. Plugins can be enabled and configured
through the Simplicity Studio IDE.
A standalone bootloader uses a communications channel to get a firmware upgrade image. NCP (network co-processor) devices always use standalone bootloaders. Standalone bootloaders perform firmware image upgrades in a single-stage process that allows the
application image to be placed into flash memory, overwriting the existing application image, without the participation of the application
itself. In general, the only time that the application interacts with a standalone bootloader is when it requests to reboot into the bootloader. Once the bootloader is running, it receives packets containing the firmware upgrade image by a physical connection such as UART
or SPI. To function as a standalone bootloader, a plugin providing a communication interface such as UART or SPI must be configured.
An application bootloader relies on the application to acquire the firmware upgrade image. The application bootloader performs a firmware image upgrade by writing the firmware upgrade image to a region of flash memory referred to as the download space. The application transfers the firmware upgrade image to the download space in any way that is convenient (UART, over-the-air, Ethernet, USB,
and so on). The download space is either an external memory device such as an EEPROM or dataflash or a section of the device’s
internal flash. The Gecko Bootloader can partition the download space into multiple storage slots, and store multiple firmware upgrade
silabs.com | Building a more connected world. Rev. 1.6 | 4
UG266: Silicon Labs Gecko Bootloader User’s Guide
Overview
images simultaneously. To function as an application bootloader, a plugin providing a bootloader storage implementation has to be
configured.
Silicon Labs provides example bootloaders that come with a preconfigured set of plugins for configuration in either standalone or application mode, as described in section 7. Configuring the Gecko Bootloader. The Silicon Labs Gecko SDK Suite also includes precompiled bootloader images for several different EFR32 devices. As of this writing the images shown in the following table are provided.
Note: The bootloader security features are not enabled in these precompiled images.
Table 1.1. Prebuilt Bootloader Images
Use Wireless Stack Image Name Mode Interface
SoC EmberZNet PRO SPI Flash Storage Bootloader Application SPI Serial Flash
SoC Bluetooth Bluetooth In-Place OTA DFU
Bootloader
Application OTA/internal
flash
NCP EmberZNet PRO UART XMODEM Bootloader Standalone UART (EZSP)
NCP Bluetooth BGAPI UART DFU Bootloader Standalone UART (BGAPI)
Note that on devices with a dedicated bootloader area (EFR32xG12 and later Series 1 devices), if the device is configured to boot to
the bootloader area (that is, if bit 1 of the Config Lock Word 0 CLW0[1] is set), an image always has to be present in the bootloader
area. The device is factory-programmed with a dummy bootloader that simply jumps directly to the application in main flash. This
means that when flashing a bootloader to a device with a dedicated bootloader area, this dummy bootloader is replaced. If later during
development using the bootloader is no longer desired, CLW0[1] has to be cleared or the dummy bootloader needs to be re-flashed.
Platform-specific prebuilt dummy bootloader images are located in ./platform/bootloader/util/bin/. Note that since the dummy bootloader
only consists of a few instructions and doesn't pad out the remainder of the bootloader area, only the first flash page (where the firststage bootloader resides) is overwritten, so the main stage bootloader would likely remain intact after programming the dummy bootloader. If desired, the rest of the flash pages in the bootloader area can then be erased separately.
On devices that do not have a dedicated bootloader area (EFR32xG1 and EFR32 Series 2), a dummy bootloader is not needed.
The following sections provide an overview of the Gecko Bootloader common core, drivers, and plugins. For details, including details on
error codes and conditions, see the Gecko Bootloader API Reference, shipped with the SDK in the platform/bootloader/documentation
folder.
The bootloader area can be fully erased using the commander device pageerase --region @bootloader command with Simplicity
Commander. In this state, the device will not boot until CLW0[1] is cleared or the dummy bootloader is flashed. Read more about how
to use Simplicity Commander with Gecko bootloader in section 8. Simplicity Commander and the Gecko Bootloader.
1.1 Core
The bootloader core contains the bootloader’s main functions. It also contains functionality to write to the internal flash, an image parser
to parse and act upon the contents of GBL upgrade files, and functionality to boot the application in main flash.
The image parser can also optionally support the legacy Ember Bootloader (EBL) file format, but none of the security features offered
by the Gecko Bootloader are supported if support for legacy EBL files is enabled.
A version of the GBL image parser without support for encrypted upgrade images is also available. This version can be used in flash
space constrained bootloader applications where encryption of the upgrade image is not required.
silabs.com | Building a more connected world. Rev. 1.6 | 5
UG266: Silicon Labs Gecko Bootloader User’s Guide
Overview
1.1.1 Shared Memory
In order to exchange information between the bootloader and application, a section of SRAM is used. The contents of SRAM are preserved through a software reset, making the SRAM suitable as a communication channel between bootloader and application.
The shared memory has a size of 4 bytes, and is located at the first address of SRAM, 0x20000000. It is used to store a single word
containing the reason for a reset. The structure of the reset cause word is defined in the Reset Information part of the Application Interface, in the file btl_reset_info.h, as 16 bits containing the reason, and 16 bits of signature indicating if the word is valid or not. If the
signature reads 0xF00F, the reset reason is valid.
All 16-bit reset reasons used by Silicon Labs have the most significant bit set to zero. If custom reset reasons are desired, it is recommended to set the most significant bit in order to avoid conflicting definitions.
In addition to the reset causes defined in the Reset Information documentation, the bootloader will enter firmware upgrade mode if the
shared memory contains the value 0x00000001. This value is supported for compatibility with certain legacy Bluetooth applications.
1.2 Drivers
Different applications of firmware upgrade require different hardware drivers for use by the other components of the bootloader.
Driver modules include:
• Delay: Simple delay routines for use with plugins that require small delays or timeouts.
• SPI: Simple, blocking SPI master implementation for communication with external devices such as SPI flashes.
• SPI Slave: Flexible SPI Slave driver implementation for use in communication plugins implementing SPI protocols. This driver supports both blocking and non-blocking operation, with DMA (Direct Memory Access) backing the background transfers to support nonblocking operation.
• UART: Flexible serial UART driver implementation for use in communication plugins implementing UART protocols. This driver supports both blocking and non-blocking operation, with DMA backing the background transfers to support non-blocking operation. Additionally, support for hardware flow control (RTS/CTS) is included.
1.3 Plugins
All parts of the bootloader that are either optional or that may be exchanged for different configurations are implemented as plugins.
Each plugin has a generic header file, and one or more implementations. Plugins include:
• Communication
• UART: XMODEM
• UART: BGAPI
• SPI: EZSP
• Compression
• Debug
• GPIO Activation
• Security
• Storage
• Internal flash
• External SPI flash
silabs.com | Building a more connected world. Rev. 1.6 | 6
UG266: Silicon Labs Gecko Bootloader User’s Guide
Overview
1.3.1 Communication
The Communication plugins provide an interface for implementing communication with a host device, such as a computer or a microcontroller. Several plugins implement the communication interface, using different transports and protocols.
• BGAPI UART DFU: By enabling the BGAPI communication plugin, the bootloader communication interface implements the UART
DFU protocol using BGAPI commands. This plugin makes the bootloader compatible with the legacy UART bootloader that was previously released with the Silicon Labs Bluetooth SDK versions 2.0.0-2.1.1 See AN1053: Bluetooth® Device Firmware Update over
UART for EFR32xG1 and BGM11x Series Products for more information about this legacy bootloader.
• EZSP-SPI: By enabling the EZSP-SPI communication plugin, the bootloader communication interface implements the EZSP protocol over SPI. This plugin makes the bootloader compatible with the legacy ezsp-spi-bootloader that was previously released with the
EmberZNet wireless stack. See AN760: Using the Ember Standalone Bootloader for more information about legacy Ember standalone bootloaders.
• UART XMODEM: By enabling the UART XMODEM communication plugin, the bootloader communication interface implements the
XMODEM-CRC protocol over UART. This plugin makes the bootloader compatible with the legacy serial-uart-bootloader that was
previously released with the EmberZNet wireless stack. See AN760: Using the Ember Standalone Bootloader for more information
about legacy Ember standalone bootloaders.
1.3.2 Compression
The Compression plugins provide capability for the bootloader GBL file parser to handle compressed GBL upgrade images. Each compression plugin provides support for one (de)compression algorithm. At the time of writing, decompression of data compressed with the
LZ4 and LZMA algorithms is supported, through the GBL Compression (LZ4) and GBL Compression (LZMA) plugins.
1.3.3 Debug
This plugin provides the bootloader with support for debugging output. If the plugin is configured to enable debug prints, short debug
messages will be printed over Serial Wire Output (SWO), which can be accessed in multiple ways, including using Simplicity
Commander, and by connecting to port 4900 of the Wireless Starter Kit TCP/IP interface.
To turn on debug prints, enable the Debug plugin and select Debug prints. Select Debug asserts to enable assertions in the source
code.
On Series 1 devices, also select the GPIO peripheral in the Hardware Configurator.
1.3.4 GPIO Activation
This plugin provides functionality to enter firmware upgrade mode automatically after reset if a GPIO pin is active during boot. The
GPIO pin location and polarity are configurable.
• GPIO: By enabling the GPIO activation plugin, the firmware upgrade mode can be activated by the push buttons.
• EZSP GPIO: The EZSP communication protocol over SPI can be used together with this plugin. By enabling the EZSP GPIO plugin,
the firmware upgrade mode can be entered by activating the nWake pin.
1.3.5 Security
Security plugins provide implementations of cryptographic operations as well as functionality to compute checksums and to read cryptographic keys from manufacturing tokens.
Modules include:
• AES: AES decryption functionality
• CRC16: CRC16 functionality
• CRC32: CRC32 functionality
• ECDSA: ECDSA signature verification functionality
• SHA-256: SHA-256 digest functionality
silabs.com | Building a more connected world. Rev. 1.6 | 7
UG266: Silicon Labs Gecko Bootloader User’s Guide
Overview
1.3.6 Storage
These plugins provide the bootloader with multiple storage options for SoCs. All storage implementations have to provide an API to
access image files to be upgraded. This API is based on the concept of dividing the download space into storage slots, where each slot
has a predefined size and location in memory and can be used to store a single upgrade image. Some storage implementations also
support a raw storage API to access the underlying storage medium. This can be used by applications to store other data in parts of the
storage medium that are not used for storing firmware upgrade images. Implementations include:
• Internal Flash: The internal flash storage implementation uses the internal flash of the device for upgrade image storage. Note that
this storage area is only a download space and is separate from the portion of internal flash used to hold the active application code.
• SPI Flash: The SPI flash storage implementation supports a variety of SPI flash parts. The subset of devices supported can be configured at compile time using the checkboxes found in the plugin options area for the SPI Flash Storage plugin in AppBuilder’s Bootloader framework. (The default configuration if no checkboxes are selected is to include drivers for all supported parts.) Including
support for multiple devices requires more flash space in the bootloader. The SPI flash storage implementation does not support any
write protection functionality. Supported SPI flash parts are shown in the following table.
Note: The low power devices are recommended for battery-operated applications. Use of the other listed devices will decrease battery life due to higher quiescent current, but this can be mitigated with external shutdown FET circuitry if desired.
Table 1.2. Supported Serial Dataflash/EEPROM External Memory Parts
Manufacturer Part Number Size (kB) Quiescent Current (µA Typical)*
Macronix MX25R8035F (low power) 1024 0.007
Macronix MX25R6435SF (low power) 8192 0.007
Spansion S25FL208K 1024 15
Winbond W25X20BVSNIG (W25X20CVSNJG for high- temperature support) 256 1
Winbond W25Q80BVSNIG (W25Q80BVSNJG for high- temperature support) 1024 1
Macronix MX25L2006EM1I-12G (MX25L2006EM1R-12G for high-temperature
256 2
support)
Macronix MX25L4006E 512 2
Macronix MX25L8006EM1I-12G (MX25L8006EM1R-12G for high-temperature
1024 2
support)
Macronix MX25L1606E 2048 2
Macronix MX25U1635E (2V) 2048 2
Atmel/Adesto AT25DF041A 512 15
Atmel/Adesto AT25DF081A 1024 5
Atmel/Adesto AT25SF041 512 2
Micron (Numonyx) M25P20 256 1
Micron (Numonyx) M25P40 512 1
Micron (Numonyx) M25P80 1024 1
Micron (Numonyx) M25P16 2048 1
ISSI IS25LQ025B 32 8
ISSI IS25LQ512B 64 8
ISSI IS25LQ010B 126 8
ISSI IS25LQ020B 256 8
ISSI IS25LQ040B 512 8
* Quiescent current values are as of December 2017; check the latest part specifications for any changes.
silabs.com | Building a more connected world. Rev. 1.6 | 8
UG266: Silicon Labs Gecko Bootloader User’s Guide
Gecko Bootloader File Format
2. Gecko Bootloader File Format
The GBL file format is used by the Gecko Bootloader. File formats described in this section are generated by Simplicity Commander
commands. For more information, see UG162: Simplicity Commander Reference Guide.
2.1 File Structures
The GBL file format is composed of a number of tags that indicate a format of the subsequent data and the length of the entire tag. The
format of a tag is as follows:
Tag ID Tag Length Tag Payload
4 bytes 4 bytes Variable (according to tag length)
silabs.com | Building a more connected world. Rev. 1.6 | 9
UG266: Silicon Labs Gecko Bootloader User’s Guide
Gecko Bootloader File Format
2.2 Plaintext Tag Description
Tag Name ID Description
GBL Header Tag 0x03A617EB This must be the first tag in the file. The
header tag contains the version number of
the GBL file specification, and flags indicating the type of GBL file – whether it is signed or encrypted.
GBL Application Info Tag 0xF40A0AF4 This tag contains information about the ap-
plication update image that is contained in
this GBL file
GBL SE Upgrade Tag 0x5EA617EB This tag contains a complete encrypted Se-
cure Element update image. Only applicable on Series 2 devices.
GBL Bootloader Tag 0xF50909F5 This tag contains a complete bootloader
update image.
GBL Program Data Tag 0xFE0101FE / 0xFD0303FD This tag contains information about what
application data to program at a specific
address into the main flash memory.
GBL Program LZ4 Compressed Data Tag 0xFD0505FD This tag contains LZ4 compressed informa-
tion about what application data to program
at a specific address into the main flash
memory.
GBL Program LZMA Compressed Data
Tag
0xFD0707FD This tag contains LZMA compressed infor-
mation about what application data to program at a specific address into the main
flash memory.
GBL Metadata Tag 0xF60808F6 This tag contains metadata that the boot-
loader does not parse, but can be returned
to the application through a callback.
GBL Certificate Tag 0xF30B0BF3 This tag contains a certificate that will be
used to verify the authenticity of the GBL
file.
GBL Signature Tag 0xF70A0AF7 This tag contains the ECDSA-P256 signa-
ture of all preceding data in the file.
GBL End Tag 0xFC0404FC This tag indicates the end of the GBL file. It
contains a 32-bit CRC for the entire file as
an integrity check. The CRC is a non-cryptographic check. This must be the last tag.
The allowed sequence of GBL tags in a GBL file is shown in the following figure.
Figure 2.1. GBL Tag Sequence
silabs.com | Building a more connected world. Rev. 1.6 | 10
UG266: Silicon Labs Gecko Bootloader User’s Guide
Gecko Bootloader File Format
2.3 Encrypted Tag Descriptions
The encrypted GBL file format is similar to the unencrypted version. It introduces a number of new tags.
Tag Name ID Description
GBL Header Tag 0x03A617EB The GBL header is the same as for a plain-
text GBL file, but the flag indicating that the
GBL file is encrypted must be set.
GBL Encryption Init Header 0xFA0606FA This contains information about the image
encryption such as the Nonce and the
amount of encrypted data.
GBL Encrypted Program Data 0xF90707F9 This contains an encrypted payload con-
taining a plaintext GBL tag, one of Application Info, Bootoader, Metadata or Program
Data. The data is encrypted using AESCTR-128.
The allowed sequence of GBL tags in an encrypted GBL file is shown in the following figure.
Figure 2.2. Encrypted GBL Tag Sequence
silabs.com | Building a more connected world. Rev. 1.6 | 11
UG266: Silicon Labs Gecko Bootloader User’s Guide
Gecko Bootloader Operation - Application Upgrade
3. Gecko Bootloader Operation - Application Upgrade
This section summarizes Gecko Bootloader operation for updating application firmware, first if the Gecko Bootloader is configured in
standalone mode and then if it is configured in application mode. Section 4. Gecko Bootloader Operation - Bootloader Upgrade provides the same information for updating the bootloader firmware.
The figures that illustrate Gecko Bootloader operation in this section do not provide information about the bootloader memory layouts
for different devices. For more details refer to the section "Memory Space for Bootloading" in UG103.6: Bootloader Fundamentals.
3.1 Standalone Bootloader Operation
Standalone bootloader operation is illustrated in the following figure:
Figure 3.1. Standalone Bootloader Operation
1. The device reboots into the bootloader.
2. A GBL file containing an application image is transmitted from the host to the device. If image encryption is enabled in the main
stage bootloader and the image is encrypted, decryption is performed during the process of receiving and parsing the GBL file.
3. The bootloader applies the application upgrade from the GBL upgrade file on-the-fly. If image authentication is enabled in the main
stage bootloader and the GBL file contains a signature, the authenticity of the image is verified before completing the process.
4. The device boots into the application. Application upgrade is complete.
3.1.1 Rebooting Into the Bootloader
The Gecko Bootloader supports multiple mechanisms for triggering the bootloader. If the GPIO Activation plugin is enabled, the host
device can keep this pin low/high (depending on configuration) through reset to make the device enter the bootloader. The bootloader
can also be entered through software. The bootloader_rebootAndInstall API first signals to the bootloader that it should enter firmware upgrade mode by writing a command to the shared memory location at the bottom of SRAM, and then performs a software reset.
If the bootloader finds the correct command in shared memory upon boot, it will enter firmware upgrade mode instead of booting the
existing application.
3.1.2 Downloading and Applying a GBL Upgrade File
When the bootloader enters firmware upgrade mode, it enters a receive loop waiting for data from the host device. The specifics of the
receive loop depend on the protocol. Received packets are passed to the image parser, a state machine that parses the data and returns a callback containing any data that should be acted upon. The bootloader core implements this callback, and flashes the data to
internal flash at the address specified. If GBL file authentication or encryption is enabled, the image parser will enforce this, and abort
the image upgrade.
The bootloader prevents a newly uploaded image from being bootable by holding back parts of the application vector table until the
GBL file CRC and GBL signature (if required) have been verified.
silabs.com | Building a more connected world. Rev. 1.6 | 12
UG266: Silicon Labs Gecko Bootloader User’s Guide
Gecko Bootloader Operation - Application Upgrade
3.1.3 Booting Into the Application
When an application upgrade is completed, the bootloader triggers a reboot with a message in shared memory at the bottom of SRAM
signaling that an application upgrade has been successfully completed. The application can use this reset information to learn that an
application upgrade was just performed.
Before jumping to the main application, the bootloader verifies that the application is ready to run. This includes verifying that the Program Counter of the application is valid, and, optionally if Secure Boot is enabled, that the application passes signature verification.
3.1.4 Error handling
If the application upgrade is interrupted at any time, the device will be without a working application. The bootloader then resets the
device, and re-enters firmware upgrade mode. The host device can easily restart the application upgrade process, to try loading the
upgrade image again.
silabs.com | Building a more connected world. Rev. 1.6 | 13
UG266: Silicon Labs Gecko Bootloader User’s Guide
Gecko Bootloader Operation - Application Upgrade
3.2 Application Bootloader Operation
The following figure illustrates the application bootloader operation both for a single image/single storage slot, and multiple images/
multiple storage slots.
Figure 3.2. Application Bootloader Operation: Single Storage Slot
Figure 3.3. Application Bootloader Operation: Multiple Storage Slots
1. A GBL file is downloaded onto the storage medium of the device (internal flash or external dataflash), as described below, and the
presence of an upgrade image is indicated.
2. The device reboots into the bootloader, and the bootloader enters firmware upgrade mode.
3. The bootloader applies the application upgrade from the GBL upgrade file.
4. The device boots into the application. Application upgrade is complete.
silabs.com | Building a more connected world. Rev. 1.6 | 14
UG266: Silicon Labs Gecko Bootloader User’s Guide
Gecko Bootloader Operation - Application Upgrade
3.2.1 Downloading and Storing a GBL Upgrade Image File
To prepare for receiving an upgrade image, the application finds an available storage slot, or erases an existing one using
bootloader_eraseStorage. If the bootloader only supports a single storage slot, a value of 0 should be used for the slot ID.
The application then receives a GBL file using an applicable protocol, such as Ethernet, USB, Zigbee, OpenThread or Bluetooth, and
stores it in the slot by calling bootloader_writeStorage.
When download is complete, the application can optionally verify the integrity of the GBL file by calling bootloader_verifyImage. This
is also done by the bootloader before applying the image, but can be done from the application in order to avoid rebooting into the
bootloader if the received image was corrupt.
If multiple storage slots are supported, the application should write a bootload list by calling bootloader_setImageToBootload. The list
is written to the two bootload info pages as shown in the second figure in section 3.2 Application Bootloader Operation. The bootload
list is a prioritized list of slots indicating the order the bootloader should use when attempting to perform a firmware upgrade. 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 treats the entire download space as a single storage slot.
3.2.2 Rebooting and Applying a GBL Upgrade File
The bootloader can be entered through software. The bootloader_rebootAndInstall API signals to the bootloader that it should enter firmware upgrade mode by writing a command to the shared memory location at the bottom of SRAM, and then performs a software
reset. If the bootloader finds the correct command in shared memory upon boot, it enters firmware upgrade mode instead of booting the
existing application.
The bootloader iterates over the list of storage slots marked for bootload and attempts to verify the image stored in each. Once it finds a
valid GBL upgrade file, firmware upgrade is attempted from this GBL file. If the upgrade fails, the bootloader moves to the next image in
the list. If no images pass verification, the bootloader reboots back into the existing application with a message in the shared memory
location in SRAM indicating that no good upgrade images were found.
3.2.3 Booting Into the Application
When an application upgrade is completed, the bootloader triggers a reboot with a message in shared memory at the bottom of SRAM
signaling that an application upgrade has been successfully completed. The application can use this reset information to learn that an
application upgrade was just performed.
Before jumping to the main application, the bootloader verifies that the application is ready to run. This includes verifying that the Program Counter of the application is valid and optionally, if Secure Boot is enabled, that the application passes signature verification.
silabs.com | Building a more connected world. Rev. 1.6 | 15
Loading...