Description

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
Custom GBL Tags
Handle custom GBL tags for added functionality in the GBL parser.

GBL Format

Data Structures
struct	ImageProperties_t
	Structure containing state of the image file processed.

struct	ParserContext_t
	Image parser context definition.

struct	GblInputBuffer_t
	GBL parser input buffer.

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)
	Parser requires upgrade images to be signed, providing authenticity, if true.

#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_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.

Enumerations
enum	GblParserState_t { GblParserStateInit , GblParserStateIdle , GblParserStateHeader , GblParserStateBootloader , GblParserStateBootloaderData , GblParserStateApplication , GblParserStateMetadata , GblParserStateMetadataData , GblParserStateProg , GblParserStateProgData , GblParserStateSe , GblParserStateSeData , GblParserStateEraseProg , GblParserStateFinalize , GblParserStateDone , GblParserStateEncryptionInit , GblParserStateEncryptionContainer , GblParserStateSignature , GblParserStateCustomTag , GblParserStateError }
	State in the GBL parser state machine.

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)

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

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

int32_t	gbl_getData ( ParserContext_t context, GblInputBuffer_t input, uint8_t outputBuffer[], size_t outputLength, bool applySHA, bool decrypt)

Macro Definition Documentation

#define PARSER_REQUIRE_AUTHENTICITY (false)

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

Bootloader/parser configurations

Definition at line 69 of file btl_gbl_parser.h .

Enumeration Type Documentation

enum 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.
GblParserStateSe	Parsing SE tag.
GblParserStateSeData	Parsing SE 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.
GblParserStateCustomTag	Parsing custom tag.
GblParserStateError	Error state.

Definition at line 106 of file btl_gbl_parser.h .

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.

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

Verify the 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.

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

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

Parameters

`context`	GBL parser context
`buffer`	Input buffer containing data to be written
`length`	Size of input buffer
`callbacks`	GBL Parser callbacks for writing data

Returns: Error code

int32_t gbl_getData	(	ParserContext_t *	`context,`
		GblInputBuffer_t *	`input,`
		uint8_t	`outputBuffer[],`
		size_t	`outputLength,`
		bool	`applySHA,`
		bool	`decrypt`
	)

Get data from storage and internal input buffer. This function advances the parser state.

Parameters

`context`	GBL parser context
`input`	Input data
`outputBuffer`	Output data
`outputLength`	Output data length
`applySHA`	Update SHA256 in the GBL parser context
`decrypt`	Decrypt the output data

Returns: Error code

GBL ParserComponents > Image Parser

Description

Modules

Data Structures

Macros

Enumerations

Functions

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation