GBL Parser#

GBL parser implementation.

Image parser for GBL files. Parses GBL files based on the GBL file format specification. Callbacks are used to present data and metadata contents of the GBL file to the bootloader.

Modules#

Enumerations#

enum

GblParserState_t {

GblParserStateInit

GblParserStateIdle

GblParserStateHeader

GblParserStateBootloader

GblParserStateBootloaderData

GblParserStateApplication

GblParserStateMetadata

GblParserStateMetadataData

GblParserStateProg

GblParserStateProgData

GblParserStateEraseProg

GblParserStateFinalize

GblParserStateDone

GblParserStateEncryptionInit

GblParserStateEncryptionContainer

GblParserStateSignature

GblParserStateError

}

State in the GBL parser state machine.

Functions#

const GblTagParsingInfo_t *

gbl_getTagParsingInfoFromTagId(uint32_t tagId)

Function for looking up and retrieving the parsing information struct associated with a particular GBL tag type / tag ID.

int32_t

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

Initialize the parser's context.

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.

int32_t

parser_verifyCertificate(void *context, void *input, void *blProperties, void *shaState)

Verify the GBL certificate.

int32_t

gbl_writeProgData(ParserContext_t *context, uint8_t buffer[], size_t length, const BootloaderParserCallbacks_t *callbacks)

Write application data.

Macros#

#define

PARSER_FLAG_ENCRYPTED (1U << 0U)

GBL file is encrypted.

#define

PARSER_FLAG_PARSE_CUSTOM_TAGS (1U << 5U)

Parse custom tags rather than silently traversing them.

#define

PARSER_FLAGS_PUBLIC_MASK PARSER_FLAG_PARSE_CUSTOM_TAGS

Some flags are public, some are internal to the parser.

#define

GBL_PARSER_BUFFER_SIZE 64UL

GBL parser buffer size.

#define

PARSER_REQUIRE_AUTHENTICITY (false)

Bootloader/parser configurations.

#define

PARSER_REQUIRE_CONFIDENTIALITY (false)

Parser requires upgrade images to be encrypted, providing confidentiality, if true.

#define

PARSER_REQUIRE_CERTIFICATE_AUTHENTICITY (false)

Parser requires upgrade images to be authenticated by the bootloader certificate, if true.

#define

PARSER_REQUIRE_ANTI_ROLLBACK_PROTECTION (false)

Parser requires rollback protection of applications, if true.

#define

PARSER_APPLICATION_MINIMUM_VERSION_VALID (0UL)

Defines the minimum application version that can be accepted.

#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_CONTENT_DELTA 0x08U

Upgrade image contains Delta 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.

Enumeration Documentation#

GblParserState_t#

GblParserState_t

State in the GBL parser state machine.

Enumerator
GblParserStateInit	Initial state.
GblParserStateIdle	Idle state.
GblParserStateHeader	Parsing header tag.
GblParserStateBootloader	Parsing bootloader tag.
GblParserStateBootloaderData	Parsing bootloader tag data.
GblParserStateApplication	Parsing application tag.
GblParserStateMetadata	Parsing metadata tag.
GblParserStateMetadataData	Parsing metadata tag data.
GblParserStateProg	Parsing flash program tag.
GblParserStateProgData	Parsing flash program tag data.
GblParserStateEraseProg	Parsing flash erase&program tag.
GblParserStateFinalize	Finalizing file.
GblParserStateDone	Parsing complete.
GblParserStateEncryptionInit	Parsing encryption init tag.
GblParserStateEncryptionContainer	Parsing encryption data tag.
GblParserStateSignature	Parsing signature tag.
GblParserStateError	Error state.

Function Documentation#

gbl_getTagParsingInfoFromTagId#

const GblTagParsingInfo_t * gbl_getTagParsingInfoFromTagId (uint32_t tagId)

Function for looking up and retrieving the parsing information struct associated with a particular GBL tag type / tag ID.

Parameters

Type	Direction	Argument Name	Description
uint32_t	[in]	tagId	The tag ID to be looked up.

Returns

A pointer to the GblTagParsingInfo_t struct associated with tagId, or a NULL pointer if the provided tagId cannot be found.

parser_init#

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

Initialize the parser's context.

Parameters

Type	Direction	Argument Name	Description
void *	N/A	context	Pointer to context for the parser implementation
void *	N/A	decryptContext	Pointer to context for decryption of parsed file
void *	N/A	authContext	Pointer to context for authentication of parsed file
uint8_t	N/A	flags	Flags for parser support

Returns

BOOTLOADER_OK if OK, error code otherwise.

parser_parse#

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.

Parameters

Type	Direction	Argument Name	Description
void *	N/A	context	Pointer to the specific parser's context variable
ImageProperties_t *	N/A	imageProperties	Pointer to the image file state variable
uint8_t	N/A	buffer	Pointer to byte array containing data to parse
size_t	N/A	length	Size in bytes of the data in buffer
const BootloaderParserCallbacks_t *	N/A	callbacks	Struct containing function pointers to be called by the parser to pass the extracted binary data back to BTL.

Pushes data into the image file parser to be parsed.

Returns

BOOTLOADER_OK if OK, error code otherwise.

parser_verifyCertificate#

int32_t parser_verifyCertificate (void * context, void * input, void * blProperties, void * shaState)

Verify the GBL certificate.

Parameters

Type	Direction	Argument Name	Description
void *	[inout]	context	GBL parser context
void *	[in]	input	Input data
void *	[in]	blProperties	Pointer to ApplicationProperties_t of bootloader
void *	[inout]	shaState	Pointer to Sha256Context_t used to store SHA256 of GBL certificate

Note

The behavior of this function depends on the context state.

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.

gbl_writeProgData#

int32_t gbl_writeProgData (ParserContext_t * context, uint8_t buffer, size_t length, const BootloaderParserCallbacks_t * callbacks)

Write application data.

Parameters

Type	Direction	Argument Name	Description
ParserContext_t *	N/A	context	GBL parser context
uint8_t	N/A	buffer	Input buffer containing data to be written
size_t	N/A	length	Size of input buffer
const BootloaderParserCallbacks_t *	N/A	callbacks	GBL Parser callbacks for writing data

This function is called when parsing any tag with GblProg_t structured content.

Returns

Error code

Macro Definition Documentation#

PARSER_FLAG_ENCRYPTED#

#define PARSER_FLAG_ENCRYPTED

Value:

(1U << 0U)

GBL file is encrypted.

PARSER_FLAG_PARSE_CUSTOM_TAGS#

#define PARSER_FLAG_PARSE_CUSTOM_TAGS

Value:

(1U << 5U)

Parse custom tags rather than silently traversing them.

PARSER_FLAGS_PUBLIC_MASK#

#define PARSER_FLAGS_PUBLIC_MASK

Value:

PARSER_FLAG_PARSE_CUSTOM_TAGS

Some flags are public, some are internal to the parser.

GBL_PARSER_BUFFER_SIZE#

#define GBL_PARSER_BUFFER_SIZE

Value:

64UL

GBL parser buffer size.

PARSER_REQUIRE_AUTHENTICITY#

#define PARSER_REQUIRE_AUTHENTICITY

Value:

(false)

Bootloader/parser configurations.

Parser requires upgrade images to be signed, providing authenticity, if true.

PARSER_REQUIRE_CONFIDENTIALITY#

#define PARSER_REQUIRE_CONFIDENTIALITY

Value:

(false)

Parser requires upgrade images to be encrypted, providing confidentiality, if true.

PARSER_REQUIRE_CERTIFICATE_AUTHENTICITY#

#define PARSER_REQUIRE_CERTIFICATE_AUTHENTICITY

Value:

(false)

Parser requires upgrade images to be authenticated by the bootloader certificate, if true.

PARSER_REQUIRE_ANTI_ROLLBACK_PROTECTION#

#define PARSER_REQUIRE_ANTI_ROLLBACK_PROTECTION

Value:

(false)

Parser requires rollback protection of applications, if true.

PARSER_APPLICATION_MINIMUM_VERSION_VALID#

#define PARSER_APPLICATION_MINIMUM_VERSION_VALID

Value:

(0UL)

Defines the minimum application version that can be accepted.

BTL_IMAGE_CONTENT_APPLICATION#

#define BTL_IMAGE_CONTENT_APPLICATION

Value:

0x01U

Upgrade image contains application upgrade.

BTL_IMAGE_CONTENT_BOOTLOADER#

#define BTL_IMAGE_CONTENT_BOOTLOADER

Value:

0x02U

Upgrade image contains bootloader upgrade.

BTL_IMAGE_CONTENT_SE#

#define BTL_IMAGE_CONTENT_SE

Value:

0x04U

Upgrade image contains SE upgrade.

BTL_IMAGE_CONTENT_DELTA#

#define BTL_IMAGE_CONTENT_DELTA

Value:

0x08U

Upgrade image contains Delta upgrade.

BTL_IMAGE_INSTRUCTION_APPLICATION#

#define BTL_IMAGE_INSTRUCTION_APPLICATION

Value:

0x01U

Application upgrade should be applied from upgrade image.

BTL_IMAGE_INSTRUCTION_BOOTLOADER#

#define BTL_IMAGE_INSTRUCTION_BOOTLOADER

Value:

0x02U

Bootloader upgrade should be applied from upgrade image.

BTL_IMAGE_INSTRUCTION_SE#

#define BTL_IMAGE_INSTRUCTION_SE

Value:

0x04U

SE upgrade should be applied from upgrade image.