Common Application Interface#

Generic application interface available on all versions of the bootloader, regardless of the available components.

Note

These Bootloader APIs are not reentrant and should be wrapped in critical section where needed.

Modules#

BareBootTable_t

BootloaderInformation_t

BootloaderHeader_t

FirstBootloaderTable_t

MainBootloaderTable_t

gpio_em4_header_t

gpio_em4_retention_t

gpio_em4_retention_config_t

Reset Information

Enumerations#

enum

BootloaderType_t {

NO_BOOTLOADER = 0

SL_BOOTLOADER = 1

}

Bootloader interface APIs are trust zone aware.

Functions#

void

bootloader_getInfo(BootloaderInformation_t *info)

Get information about the bootloader on this device.

int32_t

bootloader_init(void)

Initialize components of the bootloader so the app can use the interface.

int32_t

bootloader_deinit(void)

De-initialize components of the bootloader that were previously initialized.

void

bootloader_rebootAndInstall(void)

Reboot into the bootloader to perform an install.

bool

bootloader_verifyApplication(uint32_t startAddress)

Verify the application image stored in the Flash memory starting at the address startAddress.

bool

bootloader_secureBootEnforced(void)

Check whether signature verification on the application image in internal flash is enforced before every boot.

bool

bootloader_getUpgradeLocation(uint32_t *location)

Get base address of the bootloader upgrade image.

uint32_t

bootloader_remainingApplicationUpgrades(void)

Count the total remaining number of application upgrades.

BootloaderResetCause_t

bootloader_getResetReason(void)

Get reset cause of the bootloader.

bool

bootloader_pointerValid(const void *ptr)

Check if a pointer is valid and if it points to the bootloader main stage.

bool

verifyAddressRange(uint32_t address, uint32_t length)

Checks if a memory region is within the valid flash address range.

bool

verifyErased(uint32_t address, uint32_t length)

Checks if a memory region is erased (all bits set to 1).

int32_t

bootloader_rebootAndInstallWithGpioRetention(const gpio_em4_retention_t *pins, uint8_t num_pins, bool auto_configure_wakeup)

Reboots the system with GPIO retention and enters EM4 sleep mode.

Macros#

#define

BOOTLOADER_VERSION_MAJOR_SHIFT (24U)

Bootloader version major version shift value.

#define

BOOTLOADER_VERSION_MINOR_SHIFT (16U)

Bootloader version minor version shift value.

#define

BOOTLOADER_VERSION_MAJOR_MASK (0xFF000000U)

Bootloader version major version mask.

#define

BOOTLOADER_VERSION_MINOR_MASK (0x00FF0000U)

Bootloader version minor version mask.

#define

BOOTLOADER_CAPABILITY_ENFORCE_UPGRADE_SIGNATURE (1 << 0)

Bootloader enforces signed application upgrade images.

#define

BOOTLOADER_CAPABILITY_ENFORCE_UPGRADE_ENCRYPTION (1 << 1)

Bootloader enforces encrypted application upgrade images.

#define

BOOTLOADER_CAPABILITY_ENFORCE_SECURE_BOOT (1 << 2)

Bootloader enforces signature verification of the application image before every boot.

#define

BOOTLOADER_CAPABILITY_BOOTLOADER_UPGRADE (1 << 4)

Bootloader has the capability of being upgraded.

#define

BOOTLOADER_CAPABILITY_GBL (1 << 5)

Bootloader has the capability of parsing GBL files.

#define

BOOTLOADER_CAPABILITY_GBL_SIGNATURE (1 << 6)

Bootloader has the capability of parsing signed GBL files.

#define

BOOTLOADER_CAPABILITY_GBL_ENCRYPTION (1 << 7)

Bootloader has the capability of parsing encrypted GBL files.

#define

BOOTLOADER_CAPABILITY_ENFORCE_CERTIFICATE_SECURE_BOOT (1 << 8)

Bootloader enforces signature verification of the application image before every boot using certificate.

#define

BOOTLOADER_CAPABILITY_ROLLBACK_PROTECTION (1 << 9)

Bootloader has the capability of application rollback protection.

#define

BOOTLOADER_CAPABILITY_PERIPHERAL_LIST (1 << 10)

Bootloader has the capability to check the peripherals in use.

#define

BOOTLOADER_CAPABILITY_STORAGE (1 << 16)

Bootloader has the capability of storing data in an internal or external storage medium.

#define

BOOTLOADER_CAPABILITY_COMMUNICATION (1 << 20)

Bootloader has the capability of communicating with host processors using a communication interface.

#define

BOOTLOADER_CAPABILITY_EM4_GPIO_RETENTION (1 << 21)

The bootloader supports EM4 GPIO retention.

#define

BOOTLOADER_MAGIC_FIRST_STAGE (0xB00710ADUL)

Magic word indicating first stage bootloader table.

#define

BOOTLOADER_MAGIC_MAIN (0x5ECDB007UL)

Magic word indicating main bootloader table.

#define

mainBootloaderTable undefined

Pointer to main bootloader table.

#define

MAX_EM4_RETAINED_PINS 16

#define

BURTC_WAKEUP_CYCLES 2

#define

BURAM_SIGNATURE_VALID 0x5

#define

BURAM_RESET_COUNTER_SIGNATURE 0xA

#define

BURAM_RESET_COUNTER_MAX 3

#define

BURAM_RESET_REASON_GO 0x1u

Normal application boot.

#define

BURAM_RESET_REASON_BOOTLOAD 0x2u

Application requested that bootloader runs.

#define

BURAM_RESET_REASON_BADIMAGE 0x3u

Bootloader detected bad upgrade image.

#define

BURAM_RESET_REASON_BADAPP 0x4u

Bootloader detected bad application.

#define

BURAM_RESET_REASON_FATAL 0x5u

Bootloader detected a fatal error.

Enumeration Documentation#

BootloaderType_t#

BootloaderType_t

Bootloader interface APIs are trust zone aware.

Type of bootloader

Enumerator
NO_BOOTLOADER	No bootloader present.
SL_BOOTLOADER	Bootloader is a Silicon Labs bootloader.

Function Documentation#

bootloader_getInfo#

void bootloader_getInfo (BootloaderInformation_t * info)

Get information about the bootloader on this device.

Parameters

Type	Direction	Argument Name	Description
BootloaderInformation_t *	[out]	info	Pointer to the bootloader information struct.

The returned information is fetched from the main bootloader information table.

bootloader_init#

int32_t bootloader_init (void )

Initialize components of the bootloader so the app can use the interface.

Parameters

Type	Direction	Argument Name	Description
void	N/A

This typically includes initializing serial peripherals for communication with external SPI flashes, and so on.

Returns

Error code. BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_INIT_BASE range.

bootloader_deinit#

int32_t bootloader_deinit (void )

De-initialize components of the bootloader that were previously initialized.

Parameters

Type	Direction	Argument Name	Description
void	N/A

This typically includes powering down external SPI flashes and de-initializing the serial peripheral used for communication with the external flash.

Returns

Error code. BOOTLOADER_OK on success, else error code in BOOTLOADER_ERROR_INIT_BASE range.

bootloader_rebootAndInstall#

void bootloader_rebootAndInstall (void )

Reboot into the bootloader to perform an install.

Parameters

Type	Direction	Argument Name	Description
void	N/A

If there is a storage component and a slot is marked for bootload, install the image in that slot after verifying it.

If a communication component is present, open the communication channel and receive an image to be installed.

bootloader_verifyApplication#

bool bootloader_verifyApplication (uint32_t startAddress)

Verify the application image stored in the Flash memory starting at the address startAddress.

Parameters

Type	Direction	Argument Name	Description
uint32_t	[in]	startAddress	Starting address of the application.

If the secure boot is enforced, the function will only return true if the cryptographic signature of the application is valid. Otherwise, the application is verified according to the signature type defined in the ApplicationProperties_t structure embedded in the application. Silicon Labs wireless stacks include a declaration of this structure. However, applications not using a full wireless stack may need to instantiate the structure.

Examples of results when the secure boot is not enforced:

App has no signature: Valid if initial stack pointer and program counter have reasonable values.
App has CRC checksum: Valid if checksum is valid.
App has ECDSA signature: Valid if ECDSA signature is valid.

When secure boot is enforced, only ECDSA signed applications with a valid signature are considered valid.

Returns

True if the application is valid, else false.

bootloader_secureBootEnforced#

bool bootloader_secureBootEnforced (void )

Check whether signature verification on the application image in internal flash is enforced before every boot.

Parameters

Type	Direction	Argument Name	Description
void	N/A

Returns

True if signature verification is enforced, else false.

bootloader_getUpgradeLocation#

bool bootloader_getUpgradeLocation (uint32_t * location)

Get base address of the bootloader upgrade image.

Parameters

Type	Direction	Argument Name	Description
uint32_t *	[out]	location	the base address of bootloader upgrade image.

Returns

Returns true if the location was found.

bootloader_remainingApplicationUpgrades#

uint32_t bootloader_remainingApplicationUpgrades (void )

Count the total remaining number of application upgrades.

Parameters

Type	Direction	Argument Name	Description
void	N/A

Returns

remaining number of application upgrades.

bootloader_getResetReason#

BootloaderResetCause_t bootloader_getResetReason (void )

Get reset cause of the bootloader.

Parameters

Type	Direction	Argument Name	Description
void	N/A

Returns

Reset cause of the bootloader.

bootloader_pointerValid#

bool bootloader_pointerValid (const void * ptr)

Check if a pointer is valid and if it points to the bootloader main stage.

Parameters

Type	Direction	Argument Name	Description
const void *	[in]	ptr	The pointer to check

This function checks pointers to bootloader jump tables.

Returns

True if the pointer points into the bootloader main stage, false if not.

verifyAddressRange#

bool verifyAddressRange (uint32_t address, uint32_t length)

Checks if a memory region is within the valid flash address range.

Parameters

Type	Direction	Argument Name	Description
uint32_t	N/A	address	The starting address of the memory region to check.
uint32_t	N/A	length	The length (in bytes) of the memory region to check.

This function verifies that the specified address and length are within the bounds of the device's flash memory region, defined by FLASH_BASE and FLASH_SIZE.

Returns

true if the region is fully within the flash memory range, false otherwise.

verifyErased#

bool verifyErased (uint32_t address, uint32_t length)

Checks if a memory region is erased (all bits set to 1).

Parameters

Type	Direction	Argument Name	Description
uint32_t	N/A	address	The starting address of the memory region to check.
uint32_t	N/A	length	The length (in bytes) of the memory region to check. Must be a multiple of 4.

This function iterates over the specified memory region and checks if every 32-bit word is equal to 0xFFFFFFFF, which indicates an erased state in flash memory.

Returns

true if all 32-bit words in the region are erased (0xFFFFFFFF), false otherwise.

bootloader_rebootAndInstallWithGpioRetention#

int32_t bootloader_rebootAndInstallWithGpioRetention (const gpio_em4_retention_t * pins, uint8_t num_pins, bool auto_configure_wakeup)

Reboots the system with GPIO retention and enters EM4 sleep mode.

Parameters

Type	Direction	Argument Name	Description
const gpio_em4_retention_t *	[in]	pins	Pointer to array of GPIO pin configurations to retain
uint8_t	[in]	num_pins	Number of pins to retain (range: 1 to MAX_EM4_RETAINED_PINS)
bool	[in]	auto_configure_wakeup	Wakeup configuration flag (true: BURTC wakeup, false: direct EM4 entry)

This function implements a complete EM4 GPIO retention workflow by:

Validating the provided GPIO configuration parameters
Persisting GPIO configurations to BURAM for retention across EM4 cycles
Entering EM4 sleep mode with configurable wakeup behavior

The wakeup mechanism is controlled by the auto_configure_wakeup parameter:

When true: BURTC is configured for scheduled wakeup before entering EM4
When false: EM4 is entered directly, allowing the application to handle wakeup configuration

Returns

On success, this function transitions the system to EM4 sleep mode and does not return
- BOOTLOADER_ERROR_GPIO_RETENTION_INVALID: Invalid parameters or EM4 GPIO retention not available
- Other error codes from btl_em4GpioRetentionConfigSave() on GPIO retention save failure