GBL3 Commands#

GBL3 File Creation#

Creates a Gecko Bootloader version 3 (GBL3) file from an application image and writes the output to the specified filename. Can optionally encrypt the GBL3 file using a keyfile generated by the util genkey command.

Command Line Syntax

$ commander gbl3 create <gblfile> --app <filename> [--encrypt <keyfile>]

Command Line Input Example

$ commander gbl3 create app.gbl.encrypted --app example.s37 --encrypt key.txt

Command Line Output Example

Parsing file example.s37...
Initializing GBL file...
Adding application to GBL...
Encrypting GBL...
Writing GBL file app.gbl.encrypted...
DONE

GBL3 File Creation with Compression#

Creates a compressed Gecko Bootloader version 3 (GBL3) file from an application image and writes the output to the specified filename. Can optionally encrypt the GBL3 file using a keyfile generated by the util genkey command.

The currently supported compression algorithms are lz4 and lzma. The bootloader on the targeted devices must support decompressing the selected compression type.

Command Line Syntax

$ commander gbl3 create <gblfile> --app <filename> --compress <compression algorithm> [--encrypt <keyfile>]

Command Line Input Example

$ commander gbl3 create app.gbl --app example.s37 --compress lz4

Command Line Output Example

Parsing file example.s37...
Initializing GBL file...
Adding application to GBL...
Compressing using lz4...
Writing GBL file app.gbl...
DONE

Create a GBL3 File for Bootloader Upgrade#

Creates a Gecko Bootloader version 3 (GBL3) file from a bootloader image and writes the output to the specified bootloader image filename. For more information, see UG266: Silicon Labs Gecko Bootloader User's Guide for GSDK 3.x and Lower or UG489: Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher.

Command Line Syntax

$ commander gbl3 create <gblfile> --bootloader <bootloader image file> [--encrypt <keyfile>]

Command Line Input Example

$ commander gbl3 create bootloader.gbl --bootloader bootloader.s37

Command Line Output Example

Initializing GBL file...
Adding bootloader to GBL...
Writing GBL file bootloader.gbl...
DONE

Creating a GBL3 File for Secure Engine Upgrade#

The Secure Engine on EFR32xG21 devices can be upgraded using a Secure Engine upgrade binary provided by Silicon Labs. This command creates a GBL3 file containing a Secure Engine upgrade file and writes the output to the specified GBL3 filename. For more information, see UG266: Silicon Labs Gecko Bootloader User's Guide for GSDK 3.x and Lower or UG489: Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher.

Command Line Syntax

$ commander gbl3 create <gblfile> --seupgrade <SE upgrade file> --app <application image>

Command Line Input Example

$ commander gbl3 create se-upgrade.gbl --seupgrade se_fw_upgrade_app_1v0p0.seu --app myapp.s37

Command Line Output Example

Parsing file myapp.s37...
Initializing GBL file...
Adding application to GBL...
Adding Secure Engine upgrade image to GBL...
Writing GBL file se-upgrade.gbl...
DONE

Creating a Signed and Encrypted GBL3 Upgrade Image File from an Application#

Creates a GBL3 file, signs the GBL3 file, and encrypts the GBL3 file. For more information, see UG266: Silicon Labs Gecko Bootloader User's Guide for GSDK 3.x and Lower or UG489: Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher.

Command Line Syntax

$ commander gbl3 create <gblfile> --app <app image file> --sign <signing key> [--encrypt <encryption key>]

Command Line Input Example

$ commander gbl3 create example.gbl --app example.s37 --sign ecdsakey --encrypt aeskey

Command Line Output Example

Parsing file example.s37...
Initializing GBL file...
Adding application to GBL...
Encrypting GBL...
Signing GBL...
Image SHA256: 74b126bdbad680470487e32d7d7b3ec7f12b15d9988e028b26c2dd54f81dcfb7
R = 055A23A44CDEDA34506EE72F4530FE174CFC85F48933C1379C1360F8BC1AA75B
S = 1C9EF6C3F5CAA0D5B92ECC2569E4A8251F8561DAF52DE54D3E59591A5001B9EA
Writing GBL file example.gbl...
DONE

Creating a Partial Signed and Encrypted GBL3 Upgrade File for Use with a Hardware Security Module#

It is often not desirable to keep the private key used for signing locally on the computer that creates the GBL3 images. A good way to increase security is to use a Hardware Security Module (HSM) to generate the actual signatures. Simplicity Commander supports using a three-step process:

  1. Create a partial GBL3 file for external signing using Simplicity Commander.

  2. Create an Elliptic Curve Digital Signature Algorithm (ECDSA) signature of the partial GBL3 file using an HSM.

  3. Use Simplicity Commander to sign the partial GBL3 file using the signature from the HSM, and create a complete GBL3 file.

Step 1 is described in this section. Step 2 is specific to the HSM you are using. Step 3 is described in Creating a Signed GBL3 File Using a Hardware Security Module. For more information, see UG266: Silicon Labs Gecko Bootloader User's Guide for GSDK 3.x and Lower or UG489: Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher.

Command Line Syntax

$ commander gbl3 create <output partial GBL3 file for external signing> --app <app image file>
--extsign [--encrypt <encryption key>]

Command Line Input Example

$ commander gbl3 create example.gbl.extsign --app example.s37 --extsign --encrypt aeskey

Command Line Output Example

Parsing file example.s37...
Initializing GBL file...
Adding application to GBL...
Encrypting GBL...
Preparing GBL for external signing...
Writing GBL file example.gbl.extsign...
DONE

Creating a Signed GBL3 File Using a Hardware Security Module#

Creates a signed GBL3 file from a partial GBL3 file and an ECDSA signature file in Distinguished Encoding Rules (DER) format generated as described in Creating a Partial Signed and Encrypted GBL3 Upgrade File for Use with a Hardware Security Module. For more information, see UG266: Silicon Labs Gecko Bootloader User's Guide for GSDK 3.x and Lower or UG489: Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher.

Silicon Labs recommends that you use the --verify option with the public key corresponding to the private key used by the HSM to ensure the integrity of the generated GBL3 file.

Command Line Syntax

$ commander gbl3 sign <partial GBL3 file for external signing> --signature <signature from HSM>
[--verify <public key file>] --outfile <signed GBL3 file>

Command Line Input Example

$ commander gbl3 sign example.gbl.extsign --signature example.gbl.extsign.sig --verify ecdsakey.pub
--outfile example-signed.gbl

Command Line Output Example

Reading GBL data from example.gbl.extsign...
Parsing signature file example.gbl.extsign.sig...
R = 2E73426A1052E12BFFFEFBA9BE2AA50CEA815B630C3CA878494EEF26088A5673
S = C218596DB9958AB30924B516953D2E5107644963B4CA128072AC965BE5C2992D
Writing signature to GBL...
Verifying GBL...
Image SHA256: 4d7325b09ade0ea272eb9895096c8137b18451f694a4eca9a5782f5c08dea03a
Q_X: 60BA97B850291456217C2149061AA344B32BBFB69A91A94BBF2F274744308D39
Q_Y: 41927DA5DB171E1C723C6B59C2BC88EDFF5A37014B0473775BA5B15921686ECA
R = 2E73426A1052E12BFFFEFBA9BE2AA50CEA815B630C3CA878494EEF26088A5673
S = C218596DB9958AB30924B516953D2E5107644963B4CA128072AC965BE5C2992D
Writing GBL file example-signed.gbl...
DONE

Creating a Signed GBL File Using an Intermediate Certificate#

Creates a GBL file with a signed intermediate certificate and signs the GBL file using the private key that corresponds to the public key in the certificate.

A suitable certificate can be generated and signed using the util gencert command - see Generate Certificate for details.

Note: To use GBL files with intermediate certificates the bootloader must be configured to:

  • Use certificate-based signing.

  • Include an intermediate certificate to authenticate the certificate embedded in the GBL file.

Command Line Syntax

$ commander gbl create <gblfile> --app <app image file> --sign <signing key> --certificate <signed certificate file>

Command Line Input Example

$ commander gbl create example.gbl --app example.s37 --sign ecdsakey --certificate signed_cert.bin

Command Line Output Example

Parsing file example.s37...
Initializing GBL file...
Adding application to GBL...
Adding certificate to GBL...
Signing GBL...
Image SHA256: 6b5c6b5b4236c31931ce68d98abc65dfdf9a663ce4bd5a96d747811ea32e003a
R = 04B146AF5757307108CF09D0E2E34E99E1585BD80E6F121B5E643A251BEC4C0C
S = FEC5F26782A05508183486F6EDD2D8AA7F20A527066715243AB4AD9C7DB2BD2E
Writing GBL file example.gbl...
DONE

GBL File Parsing#

Parses a Gecko Bootloader version 3 (GBL3) file and writes the application image to the specified filename. Optionally decrypts an encrypted GBL3 file. The keyfile must be the same as was used for encrypting the encrypted GBL3 file.

Command Line Syntax

$ commander gbl3 parse <gbl filename> --app < filename> [--decrypt <key filename>]

Command Line Input Example

$ commander gbl3 parse example.gbl.encrypted --app app.s37 --decrypt key.txt

Command Line Output Example

Reading GBL data...
Decrypting GBL...
Reading application...
Writing application to app.s37...
DONE

GBL3 Key Generation#

This command is deprecated. See Key Generation for more information about key generation.

Generating a Signing Key#

This command is deprecated. See Generating a Signing Key for more information about generating a signing key.

Generate a Signing Key Using a Hardware Security Module#

This command is deprecated. See Key to Token for more information about generating a signing key using a hardware security module.

Creating a Signed GBL3 File Using a Hardware Security Module#

Creates a signed GBL3 file from a partial GBL3 file and an ECDSA signature file in Distinguished Encoding Rules (DER) format generated as described in Creating a Partial Signed and Encrypted GBL3 Upgrade File for Use with a Hardware Security Module. For more information, see UG266: Silicon Labs Gecko Bootloader User's Guide for GSDK 3.x and Lower or UG489: Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher.

Silicon Labs recommends that you use the --verify option with the public key corresponding to the private key used by the HSM to ensure the integrity of the generated GBL3 file.

Command Line Syntax

$ commander gbl3 sign <partial GBL3 file for external signing> --signature <signature from HSM>
[--verify <public key file>] --outfile <signed GBL3 file>

Command Line Input Example

$ commander gbl3 sign example.gbl.extsign --signature example.gbl.extsign.sig --verify ecdsakey.pub
--outfile example-signed.gbl

Command Line Output Example

Reading GBL data from example.gbl.extsign...
Parsing signature file example.gbl.extsign.sig...
R = 2E73426A1052E12BFFFEFBA9BE2AA50CEA815B630C3CA878494EEF26088A5673
S = C218596DB9958AB30924B516953D2E5107644963B4CA128072AC965BE5C2992D
Writing signature to GBL...
Verifying GBL...
Image SHA256: 4d7325b09ade0ea272eb9895096c8137b18451f694a4eca9a5782f5c08dea03a
Q_X: 60BA97B850291456217C2149061AA344B32BBFB69A91A94BBF2F274744308D39
Q_Y: 41927DA5DB171E1C723C6B59C2BC88EDFF5A37014B0473775BA5B15921686ECA
R = 2E73426A1052E12BFFFEFBA9BE2AA50CEA815B630C3CA878494EEF26088A5673
S = C218596DB9958AB30924B516953D2E5107644963B4CA128072AC965BE5C2992D
Writing GBL file example-signed.gbl...
DONE

Create a GBL3 File from an ELF File#

Creates a Gecko Bootloader version 3 (GBL3) file from an Executable and Linkable Format (ELF) file and writes the output to the specified file. If neither the --include-section nor the --exclude-section option is used, Simplicity Commander will include all sections that appear to be part of the application.

Command Line Syntax

$ commander gbl3 create <gblfile> --app <application image file> [--include-section <section> --exclude-section <section>]

Command Line Input Example

$ commander gbl3 create app.gbl --app app.out --exclude-section text_apploader --exclude-section text_signature

Creates a GBL3 file containing an ELF application, excluding the text_apploader and text_signature sections from the application.

Command Line Output Example

Parsing file app.out...
Initializing GBL file...
Adding application to GBL...
Encrypting GBL...
Writing GBL file app.gbl.encrypted...
DONE

Create an Encrypted GBL3 File with an Unencrypted Secure Engine Upgrade File#

Creates an encrypted Gecko Bootloader version 3 (GBL3) file containing an unencrypted Secure Engine upgrade file and then writes the output to the specified GBL3 file.

Command Line Syntax

$ commander gbl3 create <gblfile> --seupgrade <SE upgrade file> --seunencrypted --app <application image> --encrypt <AES key file>

Command Line Input Example

$ commander gbl3 create se-upgrade.gbl --seupgrade sl_fw.seu --seunencrypted --app myapp.s37 --encrypt aes-key.txt

Creates an encrypted GBL3 file with a Secure Engine upgrade file outside the encrypted area of the file.

Command Line Output Example

Parsing file myapp.s37...
Initializing GBL file...
Adding application to GBL...
Adding Secure Engine upgrade image to GBL...
Encrypting GBL...
Writing GBL file se-upgrade.gbl...
DONE

Create a GBL3 File with Version Dependencies#

Any version dependencies between application, bootloader, and Secure Engine upgrade files in a Gecko Bootloader version 3 (GBL3) file may be resolved using the --dep-app, --dep-boot, and --dep-se options.

Command Line Syntax

$ commander gbl3 create <gblfile> --seupgrade <SE upgrade file> --app <application image> --dep-app <statement:version> --dep-se <statement:version> --dep-boot <statement:version>

Dependency Statement

The dependency statement may be one of the following:

Simplicity Commander Input

Statement

g

Greater than

geq

Greater than or equal

eq

Equal

leq

Less than or equal

l

Less than

The --dep-app option takes an uint32 as version input, while the --dep-se and --dep-boot options take the version input in the format major.minor.patch.

Command Line Input Example

$ commander gbl3 create se-upgrade.gbl --app myapp.s37 --seupgrade se_fw.seu --bootloader my-bootloader.s37 --dep-app geq:0x01020002 --dep-boot l:0.5.7 --dep-se g:1.2.3

Creates a GBL3 where the application version must be greater than or equal to version 0x01020002, bootloader version must be less than version 0.5.7, and Secure Engine upgrade version must be greater than version 1.2.3.

Command Line Output Example

Parsing file myapp.s37
Initializing GBL file...
Setting version dependency of Application to >= 0x00120002
Setting version dependency of Bootloader to < 0x00050007
Setting version dependency of SE upgrade image to > 0x00010203
Adding version dependencies to GBL...
Adding application to GBL...
Adding bootloader to GBL...
Adding Secure Engine upgrade image to GBL...
Writing GBL file se-upgrade.gbl
DONE

Create a Delta GBL3 File#

Creates a Gecko Bootloader version 3 (GBL3) file which contains the difference between two specific application versions for minimal upgrade file size. For more information on delta updates, see UG489: Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher.

Command Line Syntax

$ commander gbl3 create <gblfile> --app <new application image file>  --delta-app <old application image file> [--compress lzma|lz4]

Symbol Information

The calculation of the delta between two application versions is significantly improved by having access to symbol information. When given files without symbol information (typically srec or hex files), Simplicity Commander will try to find ELF files with the same name in the same directory, and extract the symbol information from the ELF file. For example, if Commander is given --app release/1.3.0/app.s37 --delta-app release/1.2.0/app.s37, it will try to find app.axf, app.out, or app.elf in both of the release/1.3.0/ and release/1.2.0/ folders. Symbol information for both versions is required.

Secure Boot

If using secure boot, please ensure that both the old and the new application file is signed. The signature is then restored as part of applying the delta patch.

Additionally, delta GBL3 files may be signed and/or encrypted just like regular GBL3 files. See Creating a Signed and Encrypted GBL3 Upgrade Image File from an Application for details.

Version Dependency

Simplicity Commander will automatically extract the version of the old application and add a version dependency tag to the GBL3. See Create a GBL3 File with Version Dependencies for details on version dependencies. If a specific version is provided with the --dep-app option, this is used instead of the version found in the application image.

Compression

Delta GBL3 files can be compressed using LZMA or LZ4 compression. See GBL3 File Creation with Compression for details.

Command Line Input Example

$ commander gbl3 create delta-upgrade.gbl --app app_1.3.0.s37 --delta-app app_1.2.3.s37

Command Line Output Example

Parsing file app_1.3.0.s37...
Initializing GBL file...
Parsing file app_1.2.3.s37...
Filling with 0xFF from 0x0800631c to 0x08006320
Automatically adding dependency to the detected version of "--delta-app"...
Setting version dependency of Application to = 0x00010203
Writing GBL file delta-upgrade.gbl...
DONE