Gecko Bootloader File Format v4#
The Gecko Bootloader supports GBL File format v4 for Series 3 device. This format has significant differences as compared to version 3, The file formats described in this section are generated by Simplicity Commander commands.
File Structures#
The GBL v4 file format is composed of nested TLV (Type-Length-Value) elements. The format of the TLV is as follows:
Field | Length (Bytes) | Description |
|---|---|---|
Type | 4 | Type indicates the content of the Value field |
Length | 4 | Length of the Value field in bytes |
Value | N | Length size field containing either more TLVs or data |
There are two types of TLVs, data and container. Data TLVs value field contains data whose format is specified in the type field and the container TLVs value filed contains more TLVs, which in turn again may contain data or container TLVs.
TLV Descriptions#
This section describes each of the TLVs.
GBLV4#
This mandatory TLV is used to identify the GBLv4 file when parsing and tell the length of the file.
Type | Length | Value |
|---|---|---|
0x84A617EB | Variable | Contains all the TLVs for the file |
MANIFEST#
MANIFEST TLV is present inside the GBLV4 TLV. It has a collection, TLVs, that describes the metadata of the GBLv4 file that is used during the update process.
Type | Length | Value |
|---|---|---|
0xAA01012A | Variable | Contains metadata TLVs for applying the file. |
MANIFEST_INFO#
The MANIFEST_INFO TVL contains the ManifestInfo_t structure that describes the version dependency and the features of the GBL file.
Type | Length | Value |
|---|---|---|
0x2B03032B | Variable | manifest_info structure |
The ManifestInfo_t structure is as follows:
Data Type | Field | Purpose |
|---|---|---|
uint32_t | version | Minimum version of the GLBv4 parser required, used for future extensions. |
uint32_t | features | Features requested from the parser (encryption, compression etc.) |
BUNDLE_VERSION#
This is the child TVL of MANIFEST TLV, required to identify the bundle/file and is used for versioning and rejection of downgrades.
Type | Length | Value |
|---|---|---|
0x2B04042B | Fixed | bundle_version structure |
The BundleVersion_t structure is as follows:
Data Type | Field | Purpose |
|---|---|---|
Uint8_t | productId | 128 bit unique product ID |
uint32_t | bundleVersion | Reject if smaller than this exists |
Uint32_t | minVersion | The minimum previous version to which this update file can be applied |
CONTENT_HASH#
An optional TLV that provides integrity checking on the remainder of the file. This TLV is applicable to batch updates only.
Type | Length | Value |
|---|---|---|
0x0x2B05052BUL | Fixed | content_hash structure |
The content_hash structure is as follows:
Data Type | Field | Purpose |
|---|---|---|
uint32_t | hashType | The hash function used to validate (1=SHA, etc.) |
uint8_t | sha[] | The hash of all contents following the manifest |
MANIFEST_CERTIFICATE#
Type | Length | Value |
|---|---|---|
0x2B01012B | Fixed | ApplicationCertificate_t |
The ApplicationCertificate_t structure is as follows:
Data Type | Field | Purpose |
|---|---|---|
uint8_t | structVersion | Vesion of the certificate structure |
uint8_t | flags | Reserved flags |
uint8_t | key | Public key used to verify GBL file |
uint32_t | version | Version number of this certificate |
uint8_t | signature | The signature of the certificate itself (not the GBL file) |
MANIFEST_SIGNATURE#
Type | Length | Value |
|---|---|---|
0x2B02022BUL | Variable | Manifest signature structure |
The Manifest_signature structure is as follows:
Data Type | Field | Purpose |
|---|---|---|
uint32_t | Signature function | The function used for signing |
uint8_t[] | Signature | The signature for authentication |
UPDATE_PROCESS#
This is a collection of TLVs that describes the update process. Parsing this TLV does not happen until the MANIFEST_TLV is authenticated. Each TLV contained in this is parsed and processed one at a time in the order they are listed.
Type | Length | Value |
|---|---|---|
0xAB06062BUL | Variable | TLVs describing the steps to update the system |
UPDATE_SE#
This is an optional TLV that is used to update the SE.
Type | Length | Value |
|---|---|---|
0x2C02022CUL | Fixed | UpdateSe_t structure |
The UpdateSe_t structure is as follows:
Data Type | Field | Purpose |
|---|---|---|
uint32_t | version | Version number of the SE update image. |
uint32_t | tlvPosition | The absolute position of the SE update image Blob TLV |
UPDATE_MEMORY_SECTION#
The memory section’s content is present in the file and needs to be updated.
Type | Length | Value |
|---|---|---|
0x2C03032CUL | Fixed | UpdateMemorySection_t structure |
The UpdateMemorySection_t structure is as follows:
Data Type | Field | Purpose |
|---|---|---|
uint8_t | targetMemory | Which memory this definition is for (0=main memory, 0x1-0x7f = reserved, 0x80-0xff=defined by the user) |
uint8_t | plainImageSize | Represents the size of the plain image in 3 bytes |
uint32_t | targetAddr | The target memory address for the update |
uint32_t | type | Bitfield representing the type of application |
uint32_t | version | Version number for this application (customer-defined) |
uint32_t | capabilities | Bitfield representing the capabilities of this application |
uint32_t | memorySectionPos | The absolute position of the MEMORY_SECTION_TLV in the file |
HashVaule_t | memSecHash | A hash value for verifying the integrity of the memory section |
MANIFEST_FINISH#
TLV to indicate the end of an update.
Type | Length | Value |
|---|---|---|
0x2C04042CUL | Fixed | Empty |
MEMORY_SECTION#
This TLV contains TLVs for a memory section update.
Type | Length | Value |
|---|---|---|
0xBA01013AUL | Variable | TLVs for the region |
MEMORY_SECTION_INFO#
This TLV contains information about how the blob data is read and where the data is to be written to. This is a common wrapper for all data as it allows the data to be compressed, verified and processed in a unified manner.
The data can be divided into blocks, with each block having its own hash. This can then be compared with the hashes in the memory section info to authenticate the block. This is useful during streaming updates to avoid writing unauthenticated data to flash.
Type | Length | Value |
|---|---|---|
0x3B01013BUL | Fixed | MemSectionPartialInfo_t |
The MemSectionPartialInfo_t structure is as follows:
| Data Type | Field | Purpose |
|---|---|---|
| uint8_t | compressionScheme |
0 = No compression 1 = LZ4 compression 2 = LMZA compression |
| uint8_t | encryptionScheme |
0 = No encryption 1 = AES CCM |
| uint8_t | secureBootScheme | Reserved for future use. |
| uint8_t | reserved | |
| uint16_t | signBlockSize | Block size if DFU authentication is done for each block. |
| uint16_t | numBlocks | Number of blocks inside the BLOB. |
| uint8_t[] | nonce | Nonce for encryption |
| uint8_t[] | finalImageHash | Reserved for future use. |
| uint8_t[] | secureBootSign | Reserved for future use. |
BLOB#
This TLV contains variable length binary data.
Type | Length | Value |
|---|---|---|
0x3B02023BUL | Variable | Binary Data |
The figure below shows the structure of a GBL v4 file.
