Common Application Interface
Application Interface

Description

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

Modules

Reset Information
Passing information when resetting into and out of the bootloader.

Data Structures

struct BareBootTable_t
Bare boot table. Can be mapped on top of vector table to access contents.
struct BootloaderInformation_t
Information about the current bootloader.
struct BootloaderHeader_t
Common header for bootloader tables.
struct FirstBootloaderTable_t
Address table for the First Stage Bootloader.
struct MainBootloaderTable_t
Address table for the Main Bootloader.

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_EBL (1 << 5)
Bootloader has the capability of parsing EBL files.
#define BOOTLOADER_CAPABILITY_EBL_SIGNATURE (1 << 6)
Bootloader has the capability of parsing signed EBL files.
#define BOOTLOADER_CAPABILITY_EBL_ENCRYPTION (1 << 7)
Bootloader has the capability of parsing encrypted EBL 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_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_MAGIC_FIRST_STAGE (0xB00710ADUL)
Magic word indicating first stage bootloader table.
#define BOOTLOADER_MAGIC_MAIN (0x5ECDB007UL)
Magic word indicating main bootloader table.
#define firstBootloaderTable
Pointer to first stage bootloader table.
#define mainBootloaderTable
Pointer to main bootloader table.

Enumerations

enum BootloaderType_t {
NO_BOOTLOADER = 0,
SL_BOOTLOADER = 1
}
Type of bootloader.

Functions

void bootloader_getInfo ( BootloaderInformation_t *info)
int32_t bootloader_init (void)
int32_t bootloader_deinit (void)
void bootloader_rebootAndInstall (void)
bool bootloader_verifyApplication (uint32_t startAddress)
bool bootloader_secureBootEnforced (void)
uint32_t bootloader_remainingApplicationUpgrades (void)
__STATIC_INLINE bool bootloader_pointerToFirstStageValid (const void *ptr)
__STATIC_INLINE bool bootloader_pointerValid (const void *ptr)

Macro Definition Documentation

#define firstBootloaderTable
Value:
(*( FirstBootloaderTable_t **) \
(BTL_FIRST_BOOTLOADER_TABLE_BASE))
FirstBootloaderTable_t
Address table for the First Stage Bootloader.
Definition: btl_interface.h:104

Pointer to first stage bootloader table.

Definition at line 320 of file btl_interface.h .

#define mainBootloaderTable
Value:
(*( MainBootloaderTable_t **) \
(BTL_MAIN_BOOTLOADER_TABLE_BASE))
MainBootloaderTable_t
Address table for the Main Bootloader.
Definition: btl_interface.h:114

Pointer to main bootloader table.

Definition at line 324 of file btl_interface.h .

Enumeration Type Documentation

enum BootloaderType_t

Type of bootloader.

Enumerator
NO_BOOTLOADER

No bootloader present.

SL_BOOTLOADER

Bootloader is a Silicon Labs bootloader.

Definition at line 76 of file btl_interface.h .

Function Documentation

void bootloader_getInfo ( BootloaderInformation_t * info )

Get information about the bootloader on this device.

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

Parameters
[out] info Pointer to the bootloader information struct.
int32_t bootloader_init ( void )

Initialize components of the bootloader so the app can use the interface. 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.
int32_t bootloader_deinit ( void )

De-initialize components of the bootloader that were previously initialized. 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.
void bootloader_rebootAndInstall ( void )

Reboot into the bootloader to install something.

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

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

bool bootloader_verifyApplication ( uint32_t startAddress )

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

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.

Parameters
[in] startAddress Starting address of the application.
Returns
True if the application is valid, else false.
bool bootloader_secureBootEnforced ( void )

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

Returns
True if signature verification is enforced, else false.
uint32_t bootloader_remainingApplicationUpgrades ( void )

Count the total remaining number of application upgrades.

Returns
remaining number of application upgrades.
__STATIC_INLINE bool bootloader_pointerToFirstStageValid ( const void * ptr )

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

This function can be used to check pointers to bootloader jump tables.

Parameters
[in] ptr The pointer to check
Returns
True if the pointer points to the bootloader first stage, false if not.

Definition at line 440 of file btl_interface.h .

__STATIC_INLINE bool bootloader_pointerValid ( const void * ptr )

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

This function can be used to check pointers to bootloader jump tables.

Parameters
[in] ptr The pointer to check
Returns
True if the pointer points into the bootloader main stage, false if not.

Definition at line 476 of file btl_interface.h .