Bootload#

Methods to verify and bootload application images.

Functions#

uint32_t

Get base address of the bootloader upgrade image.

uint32_t

Get the version of the bootloader.

bool

Get the version of the application.

bool

Check application properties magic.

bool

Check application properties struct version.

bool
bootload_verifyApplication(uint32_t startAddress)

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

void
bootload_bootloaderCallback(uint32_t offset, uint8_t data[], size_t length, void *context)

Bootloader upgrade callback implementation.

void
bootload_applicationCallback(uint32_t address, uint8_t data[], size_t length, void *context)

Image data callback implementation.

bool
bootload_commitBootloaderUpgrade(uint32_t upgradeAddress, uint32_t size)

Perform a bootloader upgrade using the upgrade image present at upgradeAddress with length size.

bool
bootload_verifyApplicationVersion(uint32_t appVersion, bool checkRemainingAppUpgrades)

Verify the application version for rollback protection.

bool
bootload_storeApplicationVersion(uint32_t startAddress)

Store the application version.

uint32_t

Count the total remaining number of application upgrades.

void

Store application version reset magic.

void

Clean the application versions seen.

uint32_t

Get the application version storage capacity.

uint32_t *

Get the address of the application version storage buffer.

bool

Check whether the application contains a certificate.

bool

Verify a certificate with a bootloader certificate.

bool
bootload_verifyApplicationCertificate(void *appProp, void *gotCert)

Verify the application certificate.

Function Documentation#

bootload_getUpgradeLocation#

uint32_t bootload_getUpgradeLocation (void)

Get base address of the bootloader upgrade image.

Parameters
N/A

Returns

  • Returns the base address of bootloader upgrade image.


Definition at line 40 of file platform/bootloader/core/btl_bootload.h

bootload_getBootloaderVersion#

uint32_t bootload_getBootloaderVersion (void)

Get the version of the bootloader.

Parameters
N/A

Returns

  • Returns the version of the bootloader.


Definition at line 47 of file platform/bootloader/core/btl_bootload.h

bootload_getApplicationVersion#

bool bootload_getApplicationVersion (uint32_t *version)

Get the version of the application.

Parameters
[out]version

The retrieved application version

Returns

  • Returns true if the version was retrieved successfully


Definition at line 56 of file platform/bootloader/core/btl_bootload.h

bootload_checkApplicationPropertiesMagic#

bool bootload_checkApplicationPropertiesMagic (void *appProperties)

Check application properties magic.

Parameters
N/AappProperties

Pointer to ApplicationProperties_t

Returns

  • True if the application properties magic is valid.


Definition at line 76 of file platform/bootloader/core/btl_bootload.h

bootload_checkApplicationPropertiesVersion#

bool bootload_checkApplicationPropertiesVersion (void *appProperties)

Check application properties struct version.

Parameters
N/AappProperties

Pointer to ApplicationProperties_t

Returns

  • True if the application properties struct version is compatible with the bootloader.


Definition at line 86 of file platform/bootloader/core/btl_bootload.h

bootload_verifyApplication#

bool bootload_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 secure boot is enforced, the function will only return true if the cryptographic signature of the application is valid. Else, the application is verified according to the signature type defined in the ApplicationProperties_t structure embedded in the application. Silicon Labs wireless stacks declare this structure. Applications, which are not using a full wireless stack may need to instantiate the structure.

Examples of results when 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 image is deemed valid


Definition at line 112 of file platform/bootloader/core/btl_bootload.h

bootload_bootloaderCallback#

void bootload_bootloaderCallback (uint32_t offset, uint8_t data[], size_t length, void *context)

Bootloader upgrade callback implementation.

Parameters
N/Aoffset

Offset of bootloader data (byte counter incrementing from 0)

N/Adata

Raw bootloader data

N/Alength

Size in bytes of raw bootloader data.

N/Acontext

A context variable defined by the implementation that is implementing this callback.


Definition at line 124 of file platform/bootloader/core/btl_bootload.h

bootload_applicationCallback#

void bootload_applicationCallback (uint32_t address, uint8_t data[], size_t length, void *context)

Image data callback implementation.

Parameters
N/Aaddress

Address (inside the raw image) the data starts at

N/Adata

Raw image data

N/Alength

Size in bytes of raw image data. Always constrained to a multiple of four.

N/Acontext

A context variable defined by the implementation that is implementing this callback.


Definition at line 139 of file platform/bootloader/core/btl_bootload.h

bootload_commitBootloaderUpgrade#

bool bootload_commitBootloaderUpgrade (uint32_t upgradeAddress, uint32_t size)

Perform a bootloader upgrade using the upgrade image present at upgradeAddress with length size.

Parameters
[in]upgradeAddress

The starting address of the upgrade image

[in]size

The length of the upgrade image in bytes

If the bootloader upgrade process starts successfully, this function does not return and execution will resume from the reset handler of the upgraded bootloader.

Returns

  • False if the bootloader upgrade process didn't start


Definition at line 157 of file platform/bootloader/core/btl_bootload.h

bootload_verifyApplicationVersion#

bool bootload_verifyApplicationVersion (uint32_t appVersion, bool checkRemainingAppUpgrades)

Verify the application version for rollback protection.

Parameters
[in]appVersion

Application version to be checked.

[in]checkRemainingAppUpgrades

Check remaining application upgrades.

Returns

  • True if the application version is higher or equal than the application versions seen. False if the application version is lower than the application versions seen. False if no remaining application upgrades are left when checkRemainingAppUpgrades is true.


Definition at line 172 of file platform/bootloader/core/btl_bootload.h

bootload_storeApplicationVersion#

bool bootload_storeApplicationVersion (uint32_t startAddress)

Store the application version.

Parameters
N/AstartAddress

Start address of application.

Note

  • Only the version of the verified application should be stored.

Returns

  • True if application version is successfully stored.


Definition at line 185 of file platform/bootloader/core/btl_bootload.h

bootload_remainingApplicationUpgrades#

uint32_t bootload_remainingApplicationUpgrades (void)

Count the total remaining number of application upgrades.

Parameters
N/A

Returns

  • remaining number of application upgrades.


Definition at line 192 of file platform/bootloader/core/btl_bootload.h

bootload_storeApplicationVersionResetMagic#

void bootload_storeApplicationVersionResetMagic (void)

Store application version reset magic.

Parameters
N/A

Note

  • Store application version reset magic to ensure that application versions are cleaned after a bootloader upgrade.


Definition at line 200 of file platform/bootloader/core/btl_bootload.h

bootload_removeStoredApplicationVersions#

void bootload_removeStoredApplicationVersions (void)

Clean the application versions seen.

Parameters
N/A

Note

  • The application versions are cleaned only if this is requested with a magic and the application version storage is not already empty.


Definition at line 208 of file platform/bootloader/core/btl_bootload.h

bootload_getApplicationVersionStorageCapacity#

uint32_t bootload_getApplicationVersionStorageCapacity (void)

Get the application version storage capacity.

Parameters
N/A

Returns

  • Application version storage capacity.


Definition at line 215 of file platform/bootloader/core/btl_bootload.h

bootload_getApplicationVersionStoragePtr#

uint32_t * bootload_getApplicationVersionStoragePtr (uint32_t index)

Get the address of the application version storage buffer.

Parameters
N/Aindex

Index of the application version storage buffer.

Returns

  • Address of the application version storage buffer with the given index.


Definition at line 225 of file platform/bootloader/core/btl_bootload.h

bootload_gotCertificate#

bool bootload_gotCertificate (void *appProp)

Check whether the application contains a certificate.

Parameters
N/AappProp

Pointer to ApplicationProperties_t of application.

Returns

  • True if application contains a certificate.


Definition at line 234 of file platform/bootloader/core/btl_bootload.h

bootload_verifyCertificate#

bool bootload_verifyCertificate (void *cert)

Verify a certificate with a bootloader certificate.

Parameters
N/Acert

Pointer to ApplicationCertificate_t.

Returns

  • True if certificate is verified.


Definition at line 243 of file platform/bootloader/core/btl_bootload.h

bootload_verifyApplicationCertificate#

bool bootload_verifyApplicationCertificate (void *appProp, void *gotCert)

Verify the application certificate.

Parameters
N/AappProp

Pointer to ApplicationProperties_t of application.

N/AgotCert

Boolean to store application certificate presence.

Note

  • This function will always return true if certificate support is not enabled. Also true if appProp does not contain any certificate and direct signed applications can be accepted.

Returns

  • True if application certificate is verified.


Definition at line 258 of file platform/bootloader/core/btl_bootload.h