Gecko Bootloader File Format#

The GBL file format is used by the Gecko Bootloader. File formats described in this section are generated by Simplicity Commander commands. For more information, see Simplicity Commander Reference Guide.

File Structures#

The GBL file format is composed of several tags that indicate a format of the subsequent data and the length of the entire tag. The format of a tag is as follows:

Plaintext Tag Description#

The allowed sequence of GBL tags in a GBL file is shown in the following figure.

Encrypted Tag Descriptions#

The encrypted GBL file format is like the unencrypted version. It introduces several new tags.

The allowed sequence of GBL tags in an encrypted GBL file is shown in the following figure.

GBL Tag Data Structures and Definitions#

GBL Tag Header

typedef struct {

uint32_t  tagId;  // Tag ID representing the type of tag (GBL Header Tag, GBL Bootloader Tag, etc.).

uint32_t  length; // Length of the subsequent tag data in bytes.

} GblTagHeader_t;

GBL Header Tag

typedef struct {

GblTagHeader_t header;  // Tag header.

uint32_t       version; // Version of the GBL file format specification. E.g. 0x03000000.

uint32_t       type;    // Flags indicating whether the GBL file is encrypted and/or signed.

// See definitions below.

} GblHeader_t;

// GBL types

#define GBL_TYPE_NONE                 0x00000000UL

#define GBL_TYPE_ENCRYPTION_AESCCM    0x00000001UL

#define GBL_TYPE_SIGNATURE_ECDSA      0x00000100UL

GBL Version Dependency Tag

typedef struct {

uint8_t  imageType;  // Type of image (application, bootloader, SE)

uint8_t  statement;  // Encoded dependency statement (ex. appVersion > (0).1.2.3)

uint16_t reserved;   // Reserved

uint32_t version;    // The version number used in the statement (ex. (0).1.2.3)

} VersionDependency_t;

// Image types

#define GBL_VERSION_DEPENDENCY_TYPE_APPLICATION             0x01U

#define GBL_VERSION_DEPENDENCY_TYPE_BOOTLOADER              0x02U

#define GBL_VERSION_DEPENDENCY_TYPE_SE                      0x03U

// Operator encoding

#define GBL_VERSION_DEPENDENCY_OPERATOR_MASK                0x0FU

#define GBL_VERSION_DEPENDENCY_OPERATOR_SHIFT               0x00U

#define GBL_VERSION_DEPENDENCY_OPERATOR_TYPE_MASK           0x0EU

#define GBL_VERSION_DEPENDENCY_OPERATOR_NEGATOR_BIT_MASK    0x01U

#define GBL_VERSION_DEPENDENCY_OPERATOR_LT                  0x00U

#define GBL_VERSION_DEPENDENCY_OPERATOR_LEQ                 0x02U

#define GBL_VERSION_DEPENDENCY_OPERATOR_EQ                  0x04U

#define GBL_VERSION_DEPENDENCY_OPERATOR_GEQ                 0x06U

#define GBL_VERSION_DEPENDENCY_OPERATOR_GT                  0x08U

// Connective encoding

#define GBL_VERSION_DEPENDENCY_CONNECTIVE_MASK              0xF0U

#define GBL_VERSION_DEPENDENCY_CONNECTIVE_SHIFT             0x04U

#define GBL_VERSION_DEPENDENCY_CONNECTIVE_TYPE_MASK         0x0EU

#define GBL_VERSION_DEPENDENCY_CONNECTIVE_NEGATOR_BIT_MASK  0x01U

#define GBL_VERSION_DEPENDENCY_CONNECTIVE_AND               0x00U

// SE version mask for ignoring the compatibility byte when comparing versions

#define GBL_VERSION_DEPENDENCY_SE_VERSION_MASK              0x00FFFFFFUL

GBL Application Info Tag

typedef struct {

GblTagHeader_t    header;  // Tag header.

ApplicationData_t appInfo; // Application information structure. See definition below.

} GblApplication_t;

typedef struct ApplicationData {

uint32_t type;           // Bitfield representing the type of application.

// See definitions below for possible values.

uint32_t version;        // Version number for this application (customer-defined).

uint32_t capabilities;   // Bitfield representing the capabilities of this application.

uint8_t  productId[16];  // Unique ID (UUID or GUID) for the product this application is built for.

} ApplicationData_t;

// Application types

#define APPLICATION_TYPE_ZIGBEE          (1UL << 0UL)

#define APPLICATION_TYPE_THREAD          (1UL << 1UL)

#define APPLICATION_TYPE_FLEX            (1UL << 2UL)

#define APPLICATION_TYPE_BLUETOOTH       (1UL << 3UL)

#define APPLICATION_TYPE_MCU             (1UL << 4UL)

#define APPLICATION_TYPE_BLUETOOTH_APP   (1UL << 5UL)

#define APPLICATION_TYPE_BOOTLOADER      (1UL << 6UL)

#define APPLICATION_TYPE_ZWAVE           (1UL << 7UL)

GBL SE Upgrade Tag

typedef struct {

GblTagHeader_t header;   // Tag header.

uint32_t       blobSize; // Size of the SE upgrade data blob.

uint32_t       version;  // Version of the SE image.

uint8_t        data[];   // Array of data containing the SE upgrade blob.

} GblSeUpgrade_t;

GBL Bootloader Tag

typedef struct {

GblTagHeader_t header;            // Tag header.

uint32_t       bootloaderVersion; // Version number of the bootloader.

uint32_t       address;           // Base address of the bootloader image.

uint8_t        data[];            // Array of data containing the bootloader upgrade image.

} GblBootloader_t;

GBL Program Data Tag

typedef struct {

GblTagHeader_t header;            // Tag header.

uint32_t       flashStartAddress; // Address at which to start flashing data.

uint8_t        data[];            // Array of data to be flashed

// (compressed data in the LZ4 and LZMA variants of the tag).

} GblProg_t;

GBL Metadata Tag

typedef struct {

GblTagHeader_t header;     // Tag header.

uint8_t        metadata[]; // Array containing the metadata.

} GblMetadata_t;

GBL Certificate Tag

typedef struct {

GblTagHeader_t           header;      // Tag header.

ApplicationCertificate_t certificate; // Certificate used to verify the GBL file. See definition below.

} GblCertificateEcdsaP256_t;

typedef struct ApplicationCertificate {

uint8_t  structVersion;     // Version of the certificate structure.

uint8_t  flags[3];          // Reserved flags.

uint8_t  key[64];           // Public key used to verify the GBL file.

uint32_t version;           // Version number of this certificate.

uint8_t  signature[64];     // The signature of the certificate itself (not the GBL file).

} ApplicationCertificate_t;

GBL Signature Tag

typedef struct {

GblTagHeader_t header; // Tag header.

uint8_t        r[32];  // The r value of the ECDSA signature.

uint8_t        s[32];  // The s value of the ECDSA signature.

} GblSignatureEcdsaP256_t;

GBL End Tag

typedef struct {

GblTagHeader_t header; // Tag header.

uint32_t       gblCrc; // CRC32 checksum of the entire GBL file.

} GblEnd_t;

GBL Encryption Init Header Tag

typedef struct {

GblTagHeader_t header;    // Tag header.

uint32_t       msgLen;    // Length of the ciphertext in bytes.

uint8_t        nonce[12]; // Random AES-CTR nonce.

} GblEncryptionInitAesCcm_t;

GBL Encrypted Data Tag

typedef struct {

GblTagHeader_t header;             // Tag header.

uint8_t        encryptedGblData[]; // Array containing the ciphertext (encrypted GBL data).

// Note that the corresponding plaintext must contain one or

// more complete GBL tags. Put differently: A single plaintext GBL

// tag cannot be split across multiple encrypted tags.

} GblEncryptionData_t;