Common Application InterfaceApplication Interface
Description
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 |
|
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_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 | firstBootloaderTable |
Pointer to first stage bootloader table.
|
|
#define | mainBootloaderTable |
Pointer to main bootloader table.
|
|
Enumerations |
|
enum |
BootloaderType_t
{
NO_BOOTLOADER = 0, SL_BOOTLOADER = 1 } |
Bootloader interface APIs are trust zone aware.
|
|
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) |
bool | bootloader_getUpgradeLocation (uint32_t *location) |
uint32_t | bootloader_remainingApplicationUpgrades (void) |
BootloaderResetCause_t | bootloader_getResetReason (void) |
__STATIC_INLINE bool | bootloader_pointerToFirstStageValid (const void *ptr) |
__STATIC_INLINE bool | bootloader_pointerValid (const void *ptr) |
Macro Definition Documentation
#define firstBootloaderTable |
btl_interface.h:125
Pointer to first stage bootloader table.
Definition at line
417
of file
btl_interface.h
.
#define mainBootloaderTable |
Pointer to main bootloader table.
Definition at line
421
of file
btl_interface.h
.
Enumeration Type Documentation
enum BootloaderType_t |
Function Documentation
void bootloader_getInfo | ( | BootloaderInformation_t * |
info
|
) |
Get information about the bootloader on this device.
The returned information 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 perform an install.
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.
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 whether signature verification on the application image in internal flash is enforced before every boot.
- Returns
- True if signature verification is enforced, else false.
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.
uint32_t bootloader_remainingApplicationUpgrades | ( | void |
|
) |
Count the total remaining number of application upgrades.
- Returns
- remaining number of application upgrades.
BootloaderResetCause_t bootloader_getResetReason | ( | void |
|
) |
Get reset cause of the bootloader.
- Returns
- Reset cause of the bootloader.
__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 checks 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
612
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 checks 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
649
of file
btl_interface.h
.