Image Parser
Plugin

Description

Image parser plugin.

Generic image parser interface for Silicon Labs bootloader.

Modules

GBL Parser
GBL parser implementation.

Data Structures

struct ImageProperties_t
Structure containing state of the image file processed.

Macros

#define BTL_IMAGE_CONTENT_APPLICATION 0x01U
Upgrade image contains application upgrade.
#define BTL_IMAGE_CONTENT_BOOTLOADER 0x02U
Upgrade image contains bootloader upgrade.
#define BTL_IMAGE_CONTENT_SE 0x04U
Upgrade image contains SE upgrade.
#define BTL_IMAGE_INSTRUCTION_APPLICATION 0x01U
Application upgrade should be applied from upgrade image.
#define BTL_IMAGE_INSTRUCTION_BOOTLOADER 0x02U
Bootloader upgrade should be applied from upgrade image.
#define BTL_IMAGE_INSTRUCTION_SE 0x04U
SE upgrade should be applied from upgrade image.

Functions

int32_t parser_init (void *context, void *decryptContext, void *authContext, uint8_t flags)
int32_t parser_parse (void *context, ImageProperties_t *imageProperties, uint8_t buffer[], size_t length, const BootloaderParserCallbacks_t *callbacks)
bool parser_requireAuthenticity (void)
bool parser_requireConfidentiality (void)
bool parser_requireCertificateAuthenticity (void)
bool parser_requireCertificateSignedImage (void)
bool parser_requireAntiRollbackProtection (void)
uint32_t parser_applicationMinimumVersionValid (void)
bool parser_applicationUpgradeVersionValid ( ApplicationData_t *app, bool checkRemainingAppUpgrades)
uint32_t parser_getApplicationAddress (void)
uint32_t parser_getFirstStageBootloaderTable (void)
uint32_t parser_getMainBootloaderTable (void)
uint32_t parser_getBootloaderUpgradeAddress (void)
bool parser_applicationUpgradeValidCallback ( ApplicationData_t *app)
int32_t parser_verifyCertificate (void *context, void *input, void *blProperties, void *shaState)

Function Documentation

int32_t parser_init ( void * context,
void * decryptContext,
void * authContext,
uint8_t flags
)

Initialize the parser's context.

Parameters
context Pointer to context for the parser implementation
decryptContext Pointer to context for decryption of parsed file
authContext Pointer to context for authentication of parsed file
flags Flags for parser support
Returns
BOOTLOADER_OK if OK, error code otherwise.
int32_t parser_parse ( void * context,
ImageProperties_t * imageProperties,
uint8_t buffer[],
size_t length,
const BootloaderParserCallbacks_t * callbacks
)

Parse an image file to extract the binary and some metadata.

Pushes data into the image file parser to be parsed.

Parameters
context Pointer to the specific parser's context variable
imageProperties Pointer to the image file state variable
buffer Pointer to byte array containing data to parse
length Size in bytes of the data in buffer
callbacks Struct containing function pointers to be called by the parser to pass the extracted binary data back to BTL.
Returns
BOOTLOADER_OK if OK, error code otherwise.
bool parser_requireAuthenticity ( void )

Check whether the parser requires images to be signed.

Returns
True if authenticity is required, else false
bool parser_requireConfidentiality ( void )

Check whether the parser requires images to be encrypted.

Returns
True if confidentiality is required, else false
bool parser_requireCertificateAuthenticity ( void )

Check whether the parser requires images to be authenticated by the bootloader certificate.

Returns
True if certificate based authenticity is required, else false
bool parser_requireCertificateSignedImage ( void )

Check whether the parser requires images to be signed by a certificate.

Returns
True if certificate signed image is required, else false
bool parser_requireAntiRollbackProtection ( void )

Check whether the parser requires rollback protection of applications.

Returns
True if rollback protection of application is required, else false
uint32_t parser_applicationMinimumVersionValid ( void )

Check the minimum version of the applications that can be accepted.

Returns
Minimum version of the applications that can be accepted.
bool parser_applicationUpgradeVersionValid ( ApplicationData_t * app,
bool checkRemainingAppUpgrades
)

Check whether the application version is valid and the application can be accepted.

Note
This function will always return true if BOOTLOADER_ROLLBACK_PROTECTION is not enabled from the core plugin option.
Parameters
[in] app Pointer to the application data structure contained in the upgrade image.
[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.
uint32_t parser_getApplicationAddress ( void )

Return the start address of the application.

Returns
start address of the application.
uint32_t parser_getFirstStageBootloaderTable ( void )

Return the address of the first stage bootloader table.

Returns
address of the first stage bootloader table.
uint32_t parser_getMainBootloaderTable ( void )

Return the address of the main bootloader table.

Returns
address of the main bootloader table.
uint32_t parser_getBootloaderUpgradeAddress ( void )

Return the start address of the bootloader upgrade location.

Returns
start address of the bootloader upgrade location if upgrading is supported, otherwise 0.
bool parser_applicationUpgradeValidCallback ( ApplicationData_t * app )

Callback to tell the parser whether to accept the application upgrade present in the upgrade image.

Parameters
[in] app Pointer to the application data structure contained in the upgrade image.
Returns
True if the application is accepted, and the parser should continue. False if the application is rejected. If rejected, the parser will abort parsing the image file and return BOOTLOADER_ERROR_PARSER_REJECTED .
int32_t parser_verifyCertificate ( void * context,
void * input,
void * blProperties,
void * shaState
)

Verify GBL certificate.

Note
The behavior of this function depends on the context state.
Parameters
[in,out] context GBL parser context
[in] input Input data
[in] blProperties Pointer to ApplicationProperties_t of bootloader
[in,out] shaState Pointer to Sha256Context_t used to store SHA256 of GBL certificate
Returns
BOOTLOADER_ERROR_PARSER_PARSED if done parsing the current input buffer. BOOTLOADER_OK if input data is stored in the internal buffer. BOOTLOADER_OK if the certificate in GBL is accepted. BOOTLOADER_ERROR_PARSER_SIGNATURE if the certificate in GBL is rejected.