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

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

int32_t

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

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

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

Count the total remaining number of application upgrades.

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 version shift value.

#define

Bootloader version minor version shift value.

#define

Bootloader version major version mask.

#define

Bootloader version minor version mask.

#define

Bootloader enforces signed application upgrade images.

#define

Bootloader enforces encrypted application upgrade images.

#define

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

#define

Bootloader has the capability of being upgraded.

#define

Bootloader has the capability of parsing GBL files.

#define

Bootloader has the capability of parsing signed GBL files.

#define

Bootloader has the capability of parsing encrypted GBL files.

#define

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

#define

Bootloader has the capability of application rollback protection.

#define

Bootloader has the capability to check the peripherals in use.

#define

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

#define

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

#define

Magic word indicating first stage bootloader table.

#define
BOOTLOADER_MAGIC_MAIN (0x5ECDB007UL)

Magic word indicating main bootloader table.

#define

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 512 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 522 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 533 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 544 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 572 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 580 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 589 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 658 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 677 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 730 of file platform/bootloader/api/btl_interface.h

Macro Definition Documentation#

BOOTLOADER_VERSION_MAJOR_SHIFT#

#define BOOTLOADER_VERSION_MAJOR_SHIFT
Value:
(24U)

Bootloader version major version shift value.


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

BOOTLOADER_VERSION_MINOR_SHIFT#

#define BOOTLOADER_VERSION_MINOR_SHIFT
Value:
(16U)

Bootloader version minor version shift value.


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

BOOTLOADER_VERSION_MAJOR_MASK#

#define BOOTLOADER_VERSION_MAJOR_MASK
Value:
(0xFF000000U)

Bootloader version major version mask.


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

BOOTLOADER_VERSION_MINOR_MASK#

#define BOOTLOADER_VERSION_MINOR_MASK
Value:
(0x00FF0000U)

Bootloader version minor version mask.


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

BOOTLOADER_CAPABILITY_ENFORCE_UPGRADE_SIGNATURE#

#define BOOTLOADER_CAPABILITY_ENFORCE_UPGRADE_SIGNATURE
Value:
(1 << 0)

Bootloader enforces signed application upgrade images.


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

BOOTLOADER_CAPABILITY_ENFORCE_UPGRADE_ENCRYPTION#

#define BOOTLOADER_CAPABILITY_ENFORCE_UPGRADE_ENCRYPTION
Value:
(1 << 1)

Bootloader enforces encrypted application upgrade images.


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

BOOTLOADER_CAPABILITY_ENFORCE_SECURE_BOOT#

#define BOOTLOADER_CAPABILITY_ENFORCE_SECURE_BOOT
Value:
(1 << 2)

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


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

BOOTLOADER_CAPABILITY_BOOTLOADER_UPGRADE#

#define BOOTLOADER_CAPABILITY_BOOTLOADER_UPGRADE
Value:
(1 << 4)

Bootloader has the capability of being upgraded.


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

BOOTLOADER_CAPABILITY_GBL#

#define BOOTLOADER_CAPABILITY_GBL
Value:
(1 << 5)

Bootloader has the capability of parsing GBL files.


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

BOOTLOADER_CAPABILITY_GBL_SIGNATURE#

#define BOOTLOADER_CAPABILITY_GBL_SIGNATURE
Value:
(1 << 6)

Bootloader has the capability of parsing signed GBL files.


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

BOOTLOADER_CAPABILITY_GBL_ENCRYPTION#

#define BOOTLOADER_CAPABILITY_GBL_ENCRYPTION
Value:
(1 << 7)

Bootloader has the capability of parsing encrypted GBL files.


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

BOOTLOADER_CAPABILITY_ENFORCE_CERTIFICATE_SECURE_BOOT#

#define BOOTLOADER_CAPABILITY_ENFORCE_CERTIFICATE_SECURE_BOOT
Value:
(1 << 8)

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


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

BOOTLOADER_CAPABILITY_ROLLBACK_PROTECTION#

#define BOOTLOADER_CAPABILITY_ROLLBACK_PROTECTION
Value:
(1 << 9)

Bootloader has the capability of application rollback protection.


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

BOOTLOADER_CAPABILITY_PERIPHERAL_LIST#

#define BOOTLOADER_CAPABILITY_PERIPHERAL_LIST
Value:
(1 << 10)

Bootloader has the capability to check the peripherals in use.


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

BOOTLOADER_CAPABILITY_STORAGE#

#define BOOTLOADER_CAPABILITY_STORAGE
Value:
(1 << 16)

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


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

BOOTLOADER_CAPABILITY_COMMUNICATION#

#define BOOTLOADER_CAPABILITY_COMMUNICATION
Value:
(1 << 20)

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


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

BOOTLOADER_MAGIC_FIRST_STAGE#

#define BOOTLOADER_MAGIC_FIRST_STAGE
Value:
(0xB00710ADUL)

Magic word indicating first stage bootloader table.


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

BOOTLOADER_MAGIC_MAIN#

#define BOOTLOADER_MAGIC_MAIN
Value:
(0x5ECDB007UL)

Magic word indicating main bootloader table.


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

mainBootloaderTable#

#define mainBootloaderTable
Value:
(*(MainBootloaderTable_t **) \
(BTL_MAIN_BOOTLOADER_TABLE_BASE))

Pointer to main bootloader table.


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