User Guide - nxpimage
This user guide describes how to use nxpimage application. nxpimage is a tool for generating TrustZone, Master Boot Image and Secure Binary images. This tool is successor of obsolete elftosb application. The motivation to replace elftosb is bring clear and more usable user interface to application that is used to create various kind of NXP images. To keep backward compatibility as much as possible the configuration files has been kept as is.
For more information about the supported binary images and how to configure them visit page Supported binary images
Command line interface
nxpimage
NXP Image tool.
Manage various kinds of images for NXP parts. It’s successor of obsolete ELFTOSB tool.
nxpimage [OPTIONS] COMMAND [ARGS]...
Options
- -v, --verbose
Print more detailed information
- -vv, --debug
Display more debugging information.
- --version
Show the version and exit.
- --help
Show this message and exit.
ahab
Group of sub-commands related to AHAB.
nxpimage ahab [OPTIONS] COMMAND [ARGS]...
export
Generate AHAB Image from YAML/JSON configuration.
CONFIG is path to the YAML/JSON configuration
The configuration template files could be generated by subcommand ‘get-template’.
nxpimage ahab export [OPTIONS] CONFIG
Arguments
- CONFIG
Required argument
get-template
Create template of configuration in YAML format.
The template file name is specified as argument of this command.
nxpimage ahab get-template [OPTIONS] OUTPUT
Options
- -f, --chip-family <chip_family>
Required Select the chip family.
- Options
rt1180
- -o, --overwrite
Allow overwriting existing template file.
Arguments
- OUTPUT
Required argument
parse
Parse AHAB Image into YAML configuration and binary images.
nxpimage ahab parse [OPTIONS] PARSED_DATA
Options
- -f, --chip-family <chip_family>
Required Select the chip family.
- Options
rt1180
- -t, --image-type <image_type>
AHAB image type., default is XIP.
- Options
xip | non_xip | serial_downloader
- -b, --binary <binary>
Required Path to binary AHAB image to parse.
Arguments
- PARSED_DATA
Required argument
bootable-image
Group of bootable image utilities.
nxpimage bootable-image [OPTIONS] COMMAND [ARGS]...
fcb
FCB (Flash Configuration Block) utilities.
nxpimage bootable-image fcb [OPTIONS] COMMAND [ARGS]...
export
Export FCB Image from YAML/JSON configuration.
The configuration template files could be generated by subcommand ‘get-templates’.
nxpimage bootable-image fcb export [OPTIONS] OUTPUT
Options
- -c, --config <config>
Required FCB YAML/JSON Configuration.
Arguments
- OUTPUT
Required argument
get-templates
Create template of configurations in YAML format fro all memory types.
The template files folder name is specified as argument of this command.
nxpimage bootable-image fcb get-templates [OPTIONS] OUTPUT_FOLDER
Options
- -f, --chip-family <chip_family>
Required Select the chip family.
- Options
rt5xx | rt6xx | rt105x | rt106x | rt117x
- -o, --overwrite
Allow overwriting existing template file.
Arguments
- OUTPUT_FOLDER
Required argument
parse
Parse FCB Image into YAML configuration and binary images.
nxpimage bootable-image fcb parse [OPTIONS] CONFIG_FILE
Options
- -f, --chip-family <chip_family>
Required Select the chip family.
- Options
rt5xx | rt6xx | rt105x | rt106x | rt117x
- -m, --mem-type <mem_type>
Required Select the chip used memory type.
- Options
flexspi_nor
- -b, --binary <binary>
Required Path to binary FCB image to parse.
Arguments
- CONFIG_FILE
Required argument
get-templates
Create template of configurations in YAML format from all memory types.
The template files folder name is specified as argument of this command.
nxpimage bootable-image get-templates [OPTIONS] OUTPUT_FOLDER
Options
- -f, --chip-family <chip_family>
Required Select the chip family.
- Options
rt5xx | rt6xx | rt685
- -o, --overwrite
Allow overwriting existing template file.
Arguments
- OUTPUT_FOLDER
Required argument
merge
Merge boot image blocks into one bootable image.
The configuration template files could be generated by subcommand ‘get-templates’.
nxpimage bootable-image merge [OPTIONS] OUTPUT
Options
- -c, --config <config>
Required Bootable Image YAML/JSON Configuration.
Arguments
- OUTPUT
Required argument
parse
Parse Bootable Image into YAML configuration and binary images.
nxpimage bootable-image parse [OPTIONS] PARSED_DATA_PATH
Options
- -f, --chip-family <chip_family>
Required Select the chip family.
- Options
rt5xx | rt6xx | rt685
- -m, --mem-type <mem_type>
Required Select the chip used memory type.
- Options
flexspi_nor
- -b, --binary <binary>
Required Path to binary Bootable image to parse.
Arguments
- PARSED_DATA_PATH
Required argument
mbi
Group of sub-commands related to Master Boot Images.
nxpimage mbi [OPTIONS] COMMAND [ARGS]...
export
Generate Master Boot Image from YAML/JSON configuration.
CONFIG is path to the YAML/JSON configuration
The configuration template files could be generated by subcommand ‘get-templates’.
nxpimage mbi export [OPTIONS] CONFIG
Arguments
- CONFIG
Required argument
get-templates
Create template of MBI configurations in YAML format.
The path for template files is specified as argument of this command.
nxpimage mbi get-templates [OPTIONS] OUTPUT
Options
- -f, --chip-family <chip_family>
Required Select the chip family.
- Options
lpc55xx | lpc55s0x | lpc550x | lpc55s1x | lpc551x | lpc55s2x | lpc552x | lpc55s6x | rt5xx | rt6xx | lpc55s3x | lpc553x
- -o, --overwrite
Allow overwriting existing template file.
Arguments
- OUTPUT
Required argument
otfad
Group of sub-commands related to OTFAD.
nxpimage otfad [OPTIONS] COMMAND [ARGS]...
export
Generate OTFAD Images from YAML/JSON configuration.
CONFIG is path to the YAML/JSON configuration
The configuration template files could be generated by subcommand ‘get-template’.
nxpimage otfad export [OPTIONS] CONFIG
Options
- -a, --alignment <alignment>
Alignment of key blob data blocks to simplify align data to external memory blocks.
Arguments
- CONFIG
Required argument
get-kek
Compute OTFAD KEK value and optionally store it into folder in various formats.
The computed OTFAD KEK is shown in hexadecimal text, if the ‘output-folder’ is specified, it is stored in folder also in binary format.
nxpimage otfad get-kek [OPTIONS]
Options
- -m, --otp-master-key <otp_master_key>
OTP MASTER KEY in hexadecimal format or file name to binary or text file with key.
- -k, --otfad-key <otfad_key>
OTFAD KEY (OTFAD KEK seed) in hexadecimal format or file name to binary or text file with key.
- -f, --chip-family <chip_family>
Optional family, if it specified, the tool generates the BLHOST scripts to load key fuses. To use this feature, the ‘-o’ options has to be also defined!
- Options
rt5xx | rt6xx
- -o, --output-folder <output_folder>
Optional result output folder (otfad_kek.bin/txt, optionally BLHOST scripts to load keys into Fuses)
get-template
Create template of configuration in YAML format.
The template file name is specified as argument of this command.
nxpimage otfad get-template [OPTIONS] OUTPUT
Options
- -f, --chip-family <chip_family>
Required Select the chip family.
- Options
rt5xx | rt6xx
- -o, --overwrite
Allow overwriting existing template file.
Arguments
- OUTPUT
Required argument
sb21
Group of sub-commands related to Secure Binary 2.1.
nxpimage sb21 [OPTIONS] COMMAND [ARGS]...
export
Generate Secure Binary v2.1 Image from configuration.
EXTERNAL is a space separated list of external binary files defined in BD file
nxpimage sb21 export [OPTIONS] [EXTERNAL]...
Options
- -c, --command <command>
BD configuration file to produce secure binary v2.x
- -o, --output <output>
Output file path.
- -k, --key <key>
Add a key file and enable encryption.
- -s, --pkey <pkey>
Path to private key for signing.
- -S, --cert <cert>
Path to certificate files for signing. The first certificate will be the self signed root key certificate.
- -R, --root-key-cert <root_key_cert>
Path to root key certificate file(s) for verifying other certificates. Only 4 root key certificates are allowed, others are ignored. One of the certificates must match the first certificate passed with -S/–cert arg.
- -h, --hash-of-hashes <hash_of_hashes>
Path to output hash of hashes of root keys. If argument is not provided, then by default the tool creates hash.bin in the working directory.
Arguments
- EXTERNAL
Optional argument(s)
parse
Parse Secure Binary v2.1 Image.
nxpimage sb21 parse [OPTIONS] PARSED_DATA
Options
- -b, --binary <binary>
Required Path to the SB2 container that would be parsed.
- -k, --key <key>
Required Key file for SB2 decryption in plaintext
Arguments
- PARSED_DATA
Required argument
sb31
Group of sub-commands related to Secure Binary 3.1.
nxpimage sb31 [OPTIONS] COMMAND [ARGS]...
export
Generate Secure Binary v3.1 Image from YAML/JSON configuration.
CONFIG is path to the YAML/JSON configuration
The configuration template files could be generated by subcommand ‘get-template’.
nxpimage sb31 export [OPTIONS] CONFIG
Arguments
- CONFIG
Required argument
get-template
Create template of configuration in YAML format.
The template file name is specified as argument of this command.
nxpimage sb31 get-template [OPTIONS] OUTPUT
Options
- -f, --chip-family <chip_family>
Required Select the chip family.
- Options
lpc55s3x
- -o, --overwrite
Allow overwriting existing template file.
Arguments
- OUTPUT
Required argument
tz
Group of sub-commands related to Trust Zone.
nxpimage tz [OPTIONS] COMMAND [ARGS]...
export
Generate TrustZone Image from YAML/JSON configuration.
CONFIG is path to the YAML/JSON configuration
The configuration template files could be generated by subcommand ‘get-template’.
nxpimage tz export [OPTIONS] CONFIG
Arguments
- CONFIG
Required argument
get-template
Create template of configuration in YAML format.
The template file name is specified as argument of this command.
nxpimage tz get-template [OPTIONS] OUTPUT
Options
- -f, --chip-family <chip_family>
Required Select the chip family.
- Options
lpc55xx | lpc55s0x | lpc55s1x | lpc55s3x | lpc55s6x | rt5xx | rt6xx
- -r, --revision <revision>
Chip revision; if not specified, most recent one will be used
- -o, --overwrite
Allow overwriting existing template file.
Arguments
- OUTPUT
Required argument
utils
Group of utilities.
nxpimage utils [OPTIONS] COMMAND [ARGS]...
binary-image
Binary Image utilities.
nxpimage utils binary-image [OPTIONS] COMMAND [ARGS]...
convert
Convert input data file into selected format.
nxpimage utils binary-image convert [OPTIONS] OUTPUT
Options
- -i, --input-file <input_file>
Required Path to BIN/HEX/S19/ELF file to be converted.
- -f, --format <format>
Required Output format.
- Options
BIN | HEX | S19
Arguments
- OUTPUT
Required argument
create
Create binary file with pattern.
The helper utility to create simple binary file with pattern.
nxpimage utils binary-image create [OPTIONS] OUTPUT
Options
- -s, --size <size>
Required Size of file to be created.
- -p, --pattern <pattern>
Pattern of created file (‘zeros’, ‘ones’, ‘rand’, ‘inc’ or any number value).
Arguments
- OUTPUT
Required argument
extract
Extract chunk from binary file.
nxpimage utils binary-image extract [OPTIONS] OUTPUT
Options
- -b, --binary <binary>
Required Path to binary file to be used to extract chunk from.
- -a, --address <address>
Required Address of extracted chunk.
- -s, --size <size>
Required Size of extracted chunk. For ‘0’ it extract rest of the file from given address.
Arguments
- OUTPUT
Required argument
get-template
Create template of configuration in YAML format.
The template file name is specified as argument of this command.
nxpimage utils binary-image get-template [OPTIONS] OUTPUT
Options
- -o, --overwrite
Allow overwriting existing template file.
Arguments
- OUTPUT
Required argument
merge
Merge binary images together by description in YAML/JSON configuration.
The configuration template files could be generated by subcommand ‘utils bin-image get-template’.
nxpimage utils binary-image merge [OPTIONS] OUTPUT
Options
- -c, --config <config>
Required Path to configuration file of merge operation.
Arguments
- OUTPUT
Required argument
convert
Conversion utilities.
nxpimage utils convert [OPTIONS] COMMAND [ARGS]...
bin2hex
Convert binary file into hexadecimal text file with optional reverse order of stored bytes.
nxpimage utils convert bin2hex [OPTIONS] OUTPUT
Options
- -i, --input-file <input_file>
Required Path to binary file with to be converted to hexadecimal text file.
- -r, --reverse
The result binary bytes will be stored in reverse order (for example SBKEK in elftosb this required).
Arguments
- OUTPUT
Required argument
hex2bin
Convert file with hexadecimal string into binary file with optional reverse order of stored bytes.
nxpimage utils convert hex2bin [OPTIONS] OUTPUT
Options
- -i, --input-file <input_file>
Required Path to text file with hexadecimal string to be converted to binary.
- -r, --reverse
The resulting binary bytes will be stored in reverse order (for example SBKEK in elftosb requires that).
Arguments
- OUTPUT
Required argument