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

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.

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_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.

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.


Definition at line 107 of file platform/bootloader/api/btl_interface.h

Function Documentation#

bootloader_getInfo#

void bootloader_getInfo (BootloaderInformation_t * info)

Get information about the bootloader on this device.

Parameters
[out]info

Pointer to the bootloader information struct.

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


Definition at line 527 of file platform/bootloader/api/btl_interface.h

bootloader_init#

int32_t bootloader_init (void )

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

Parameters
N/A

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

Returns


Definition at line 537 of file platform/bootloader/api/btl_interface.h

bootloader_deinit#

int32_t bootloader_deinit (void )

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

Parameters
N/A

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

Returns


Definition at line 548 of file platform/bootloader/api/btl_interface.h

bootloader_rebootAndInstall#

void bootloader_rebootAndInstall (void )

Reboot into the bootloader to perform an install.

Parameters
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.


Definition at line 559 of file platform/bootloader/api/btl_interface.h

bootloader_verifyApplication#

bool bootloader_verifyApplication (uint32_t startAddress)

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

Parameters
[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.


Definition at line 587 of file platform/bootloader/api/btl_interface.h

bootloader_secureBootEnforced#

bool bootloader_secureBootEnforced (void )

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

Parameters
N/A

Returns

  • True if signature verification is enforced, else false.


Definition at line 595 of file platform/bootloader/api/btl_interface.h

bootloader_getUpgradeLocation#

bool bootloader_getUpgradeLocation (uint32_t * location)

Get base address of the bootloader upgrade image.

Parameters
[out]location

the base address of bootloader upgrade image.

Returns

  • Returns true if the location was found.


Definition at line 604 of file platform/bootloader/api/btl_interface.h

bootloader_remainingApplicationUpgrades#

uint32_t bootloader_remainingApplicationUpgrades (void )

Count the total remaining number of application upgrades.

Parameters
N/A

Returns

  • remaining number of application upgrades.


Definition at line 673 of file platform/bootloader/api/btl_interface.h

bootloader_getResetReason#

BootloaderResetCause_t bootloader_getResetReason (void )

Get reset cause of the bootloader.

Parameters
N/A

Returns

  • Reset cause of the bootloader.


Definition at line 692 of file platform/bootloader/api/btl_interface.h

bootloader_pointerValid#

bool bootloader_pointerValid (const void * ptr)

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

Parameters
[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.


Definition at line 745 of file platform/bootloader/api/btl_interface.h