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#

GblTagParsingInfo_t

ImageProperties_t

ParserContext_t

GblInputBuffer_t

Custom GBL Tags

GBL Format

Enumerations#

enum
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#

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

GBL file is encrypted.

#define

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.

#define

Bootloader/parser configurations.

#define

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

#define

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

#define

Parser requires rollback protection of applications, if true.

#define

Defines the minimum application version that can be accepted.

#define

Upgrade image contains application upgrade.

#define

Upgrade image contains bootloader upgrade.

#define

Upgrade image contains SE upgrade.

#define

Application upgrade should be applied from upgrade image.

#define

Bootloader upgrade should be applied from upgrade image.

#define

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.


Definition at line 107 of file platform/bootloader/parser/gbl/btl_gbl_parser.h

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
[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.


Definition at line 300 of file platform/bootloader/parser/gbl/btl_gbl_parser.h

parser_init#

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

Initialize the parser's context.

Parameters
N/Acontext

Pointer to context for the parser implementation

N/AdecryptContext

Pointer to context for decryption of parsed file

N/AauthContext

Pointer to context for authentication of parsed file

N/Aflags

Flags for parser support

Returns


Definition at line 312 of file platform/bootloader/parser/gbl/btl_gbl_parser.h

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
N/Acontext

Pointer to the specific parser's context variable

N/AimageProperties

Pointer to the image file state variable

N/Abuffer

Pointer to byte array containing data to parse

N/Alength

Size in bytes of the data in buffer

N/Acallbacks

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


Definition at line 331 of file platform/bootloader/parser/gbl/btl_gbl_parser.h

parser_verifyCertificate#

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

Verify the GBL certificate.

Parameters
[inout]context

GBL parser context

[in]input

Input data

[in]blProperties

Pointer to ApplicationProperties_t of bootloader

[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


Definition at line 372 of file platform/bootloader/parser/gbl/btl_gbl_parser.h

gbl_writeProgData#

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

Write application data.

Parameters
N/Acontext

GBL parser context

N/Abuffer

Input buffer containing data to be written

N/Alength

Size of input buffer

N/Acallbacks

GBL Parser callbacks for writing data

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

Returns

  • Error code


Definition at line 388 of file platform/bootloader/parser/gbl/btl_gbl_parser.h

Macro Definition Documentation#

PARSER_FLAG_ENCRYPTED#

#define PARSER_FLAG_ENCRYPTED
Value:
(1U << 0U)

GBL file is encrypted.


Definition at line 53 of file platform/bootloader/parser/gbl/btl_gbl_parser.h

PARSER_FLAG_PARSE_CUSTOM_TAGS#

#define PARSER_FLAG_PARSE_CUSTOM_TAGS
Value:
(1U << 5U)

Parse custom tags rather than silently traversing them.


Definition at line 55 of file platform/bootloader/parser/gbl/btl_gbl_parser.h

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.


Definition at line 58 of file platform/bootloader/parser/gbl/btl_gbl_parser.h

GBL_PARSER_BUFFER_SIZE#

#define GBL_PARSER_BUFFER_SIZE
Value:
64UL

GBL parser buffer size.


Definition at line 61 of file platform/bootloader/parser/gbl/btl_gbl_parser.h

PARSER_REQUIRE_AUTHENTICITY#

#define PARSER_REQUIRE_AUTHENTICITY
Value:
(false)

Bootloader/parser configurations.

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


Definition at line 70 of file platform/bootloader/parser/gbl/btl_gbl_parser.h

PARSER_REQUIRE_CONFIDENTIALITY#

#define PARSER_REQUIRE_CONFIDENTIALITY
Value:
(false)

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


Definition at line 77 of file platform/bootloader/parser/gbl/btl_gbl_parser.h

PARSER_REQUIRE_CERTIFICATE_AUTHENTICITY#

#define PARSER_REQUIRE_CERTIFICATE_AUTHENTICITY
Value:
(false)

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


Definition at line 85 of file platform/bootloader/parser/gbl/btl_gbl_parser.h

PARSER_REQUIRE_ANTI_ROLLBACK_PROTECTION#

#define PARSER_REQUIRE_ANTI_ROLLBACK_PROTECTION
Value:
(false)

Parser requires rollback protection of applications, if true.


Definition at line 93 of file platform/bootloader/parser/gbl/btl_gbl_parser.h

PARSER_APPLICATION_MINIMUM_VERSION_VALID#

#define PARSER_APPLICATION_MINIMUM_VERSION_VALID
Value:
(0UL)

Defines the minimum application version that can be accepted.


Definition at line 100 of file platform/bootloader/parser/gbl/btl_gbl_parser.h

BTL_IMAGE_CONTENT_APPLICATION#

#define BTL_IMAGE_CONTENT_APPLICATION
Value:
0x01U

Upgrade image contains application upgrade.


Definition at line 195 of file platform/bootloader/parser/gbl/btl_gbl_parser.h

BTL_IMAGE_CONTENT_BOOTLOADER#

#define BTL_IMAGE_CONTENT_BOOTLOADER
Value:
0x02U

Upgrade image contains bootloader upgrade.


Definition at line 197 of file platform/bootloader/parser/gbl/btl_gbl_parser.h

BTL_IMAGE_CONTENT_SE#

#define BTL_IMAGE_CONTENT_SE
Value:
0x04U

Upgrade image contains SE upgrade.


Definition at line 199 of file platform/bootloader/parser/gbl/btl_gbl_parser.h

BTL_IMAGE_INSTRUCTION_APPLICATION#

#define BTL_IMAGE_INSTRUCTION_APPLICATION
Value:
0x01U

Application upgrade should be applied from upgrade image.


Definition at line 202 of file platform/bootloader/parser/gbl/btl_gbl_parser.h

BTL_IMAGE_INSTRUCTION_BOOTLOADER#

#define BTL_IMAGE_INSTRUCTION_BOOTLOADER
Value:
0x02U

Bootloader upgrade should be applied from upgrade image.


Definition at line 204 of file platform/bootloader/parser/gbl/btl_gbl_parser.h

BTL_IMAGE_INSTRUCTION_SE#

#define BTL_IMAGE_INSTRUCTION_SE
Value:
0x04U

SE upgrade should be applied from upgrade image.


Definition at line 206 of file platform/bootloader/parser/gbl/btl_gbl_parser.h