Bootload#

Methods to verify and bootload application images.

Functions#

uint32_t

bootload_getUpgradeLocation(void)

Get base address of the bootloader upgrade image.

uint32_t

bootload_getBootloaderVersion(void)

Get the version of the bootloader.

bool

bootload_getApplicationVersion(uint32_t *version)

Get the version of the application.

bool

bootload_checkApplicationPropertiesMagic(void *appProperties)

Check application properties magic.

bool

bootload_checkApplicationPropertiesVersion(void *appProperties)

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

bootload_remainingApplicationUpgrades(void)

Count the total remaining number of application upgrades.

void

bootload_storeApplicationVersionResetMagic(void)

Store application version reset magic.

void

bootload_removeStoredApplicationVersions(void)

Clean the application versions seen.

uint32_t

bootload_getApplicationVersionStorageCapacity(void)

Get the application version storage capacity.

uint32_t *

bootload_getApplicationVersionStoragePtr(uint32_t index)

Get the address of the application version storage buffer.

bool

bootload_gotCertificate(void *appProp)

Check whether the application contains a certificate.

bool

bootload_verifyCertificate(void *cert)

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

Type	Direction	Argument Name	Description
void	N/A

Returns

Returns the base address of bootloader upgrade image.

bootload_getBootloaderVersion#

uint32_t bootload_getBootloaderVersion (void )

Get the version of the bootloader.

Parameters

Type	Direction	Argument Name	Description
void	N/A

Returns

Returns the version of the bootloader.

bootload_getApplicationVersion#

bool bootload_getApplicationVersion (uint32_t * version)

Get the version of the application.

Parameters

Type	Direction	Argument Name	Description
uint32_t *	[out]	version	The retrieved application version

Returns

Returns true if the version was retrieved successfully

bootload_checkApplicationPropertiesMagic#

bool bootload_checkApplicationPropertiesMagic (void * appProperties)

Check application properties magic.

Parameters

Type	Direction	Argument Name	Description
void *	N/A	appProperties	Pointer to ApplicationProperties_t

Returns

True if the application properties magic is valid.

bootload_checkApplicationPropertiesVersion#

bool bootload_checkApplicationPropertiesVersion (void * appProperties)

Check application properties struct version.

Parameters

Type	Direction	Argument Name	Description
void *	N/A	appProperties	Pointer to ApplicationProperties_t

Returns

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

bootload_verifyApplication#

bool bootload_verifyApplication (uint32_t startAddress)

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

Parameters

Type	Direction	Argument Name	Description
uint32_t	[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

bootload_bootloaderCallback#

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

Bootloader upgrade callback implementation.

Parameters

Type	Direction	Argument Name	Description
uint32_t	N/A	offset	Offset of bootloader data (byte counter incrementing from 0)
uint8_t	N/A	data	Raw bootloader data
size_t	N/A	length	Size in bytes of raw bootloader data.
void *	N/A	context	A context variable defined by the implementation that is implementing this callback.

bootload_applicationCallback#

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

Image data callback implementation.

Parameters

Type	Direction	Argument Name	Description
uint32_t	N/A	address	Address (inside the raw image) the data starts at
uint8_t	N/A	data	Raw image data
size_t	N/A	length	Size in bytes of raw image data. Always constrained to a multiple of four.
void *	N/A	context	A context variable defined by the implementation that is implementing this callback.

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

Type	Direction	Argument Name	Description
uint32_t	[in]	upgradeAddress	The starting address of the upgrade image
uint32_t	[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

bootload_verifyApplicationVersion#

bool bootload_verifyApplicationVersion (uint32_t appVersion, bool checkRemainingAppUpgrades)

Verify the application version for rollback protection.

Parameters

Type	Direction	Argument Name	Description
uint32_t	[in]	appVersion	Application version to be checked.
bool	[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.

bootload_storeApplicationVersion#

bool bootload_storeApplicationVersion (uint32_t startAddress)

Store the application version.

Parameters

Type	Direction	Argument Name	Description
uint32_t	N/A	startAddress	Start address of application.

Note

Only the version of the verified application should be stored.

Returns

True if application version is successfully stored.

bootload_remainingApplicationUpgrades#

uint32_t bootload_remainingApplicationUpgrades (void )

Count the total remaining number of application upgrades.

Parameters

Type	Direction	Argument Name	Description
void	N/A

Returns

remaining number of application upgrades.

bootload_storeApplicationVersionResetMagic#

void bootload_storeApplicationVersionResetMagic (void )

Store application version reset magic.

Parameters

Type	Direction	Argument Name	Description
void	N/A

Note

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

bootload_removeStoredApplicationVersions#

void bootload_removeStoredApplicationVersions (void )

Clean the application versions seen.

Parameters

Type	Direction	Argument Name	Description
void	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.

bootload_getApplicationVersionStorageCapacity#

uint32_t bootload_getApplicationVersionStorageCapacity (void )

Get the application version storage capacity.

Parameters

Type	Direction	Argument Name	Description
void	N/A

Returns

Application version storage capacity.

bootload_getApplicationVersionStoragePtr#

uint32_t * bootload_getApplicationVersionStoragePtr (uint32_t index)

Get the address of the application version storage buffer.

Parameters

Type	Direction	Argument Name	Description
uint32_t	N/A	index	Index of the application version storage buffer.

Returns

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

bootload_gotCertificate#

bool bootload_gotCertificate (void * appProp)

Check whether the application contains a certificate.

Parameters

Type	Direction	Argument Name	Description
void *	N/A	appProp	Pointer to ApplicationProperties_t of application.

Returns

True if application contains a certificate.

bootload_verifyCertificate#

bool bootload_verifyCertificate (void * cert)

Verify a certificate with a bootloader certificate.

Parameters

Type	Direction	Argument Name	Description
void *	N/A	cert	Pointer to ApplicationCertificate_t.

Returns

True if certificate is verified.

bootload_verifyApplicationCertificate#

bool bootload_verifyApplicationCertificate (void * appProp, void * gotCert)

Verify the application certificate.

Parameters

Type	Direction	Argument Name	Description
void *	N/A	appProp	Pointer to ApplicationProperties_t of application.
void *	N/A	gotCert	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.