GBL ParserComponents > Image Parser

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

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