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

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
contextPointer to context for the parser implementation
decryptContextPointer to context for decryption of parsed file
authContextPointer to context for authentication of parsed file
flagsFlags 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
contextPointer to the specific parser's context variable
imagePropertiesPointer to the image file state variable
bufferPointer to byte array containing data to parse
lengthSize in bytes of the data in buffer
callbacksStruct 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]contextGBL parser context
[in]inputInput data
[in]blPropertiesPointer to ApplicationProperties_t of bootloader
[in,out]shaStatePointer 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
contextGBL parser context
bufferInput buffer containing data to be written
lengthSize of input buffer
callbacksGBL 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
contextGBL parser context
inputInput data
outputBufferOutput data
outputLengthOutput data length
applySHAUpdate SHA256 in the GBL parser context
decryptDecrypt the output data
Returns
Error code