User Guide - blhost

This user’s guide describes how to interface with the MCU bootloader using blhost application.

The blhost application is a command-line utility used on the host computer to initiate communication and issue commands to the MCU bootloader. The application only sends one command per invocation.

Communication

The blhost application can communicate directly with the MCU bootloader over the host computer’s UART (Serial Port) or USB connections.

MCU bootloader typically supports other peripherals such as I2C, SPI, and CAN. However, the blhost application cannot interface with the MCU bootloader over these transports without external hardware.

blhost - USB

blhost could be connected to MCU Bootloader over USB HID.

USB device identification in SPSDK

blhost - UART

blhost could be connected to MCU bootloader over UART.

UART device identification in SPSDK

blhost - BUSPAL

The BusPal acts as a bus translator running on selected platforms. BusPal assists blhost in carrying out commands and responses from the target device through an established connection with blhost over UART, and the target device over I2C, SPI, or CAN.

blhost - LPCUSBSIO

LPCUSBSIO - LPC USB Serial I/O(LPCUSBSIO), a firmware built in LPC Link2. The LPCUSBSIO acts as a bus translator, and establishes connection with blhost over USB-HID, and the MCU bootloader device over I2C and SPI.

MCU bootloader

The MCU bootloader is intended to be the standard bootloader for all MCU devices. It provides a standard interface to the device using any of the peripherals supported by the bootloader on a given NXP MCU device.

The MCU bootloader is available as source code for customer and flash-based implementations. There are example applications in the package which demonstrates how to interface with the MCU bootloader.

MCU Bootloader for NXP Microcontrollers

MCU bootloader properties

Current version

The value of this property is a 4-byte structure containing the current version of the bootloader. This property is encoded in a one-word value.

MCU Bootloader - bit ranges for version components

Bit

[31:24]

[23:16]

[15:8]

[7:0]

Field

Name

Major Version

Minor Version

Bugfix version

Available peripherals

The value of this property is a one-word bitfield that lists the peripherals supported by the bootloader and the hardware on which it is running.

MCU Bootloader - peripheral bits

Bit

5

4

3

2

1

0

Peripheral

Reserved

USB HID

CAN

SPI Slave

I2C Slave

UART

Available commands

This property value is a bitfield with bits set corresponding to commands enabled in the bootloader.

The bit number that identifies whether a command is present is the command’s tag value minus 1. To get the bit mask for a given command, use this expression

mask = 1 << (tag - 1)
MCU Bootloader - available commands

1

flash-erase-all (0x01)

2

flash-erase-region (0x02)

3

read-memory (0x03)

4

write-memory (0x04)

5

fill-memory (0x05)

6

flash-security-disable (0x06)

7

get-property (0x07)

8

receive-sb-file (0x08)

9

execute (0x09)

10

call (0x0a)

11

reset (0x0b)

12

set-property (0x0c)

13

flash-erase-all-unsecure (0x0d)

14

flash-program-once (0x0e)

15

flash-read-once (0x0f)

16

flash-read-resource (0x10)

17

configure-memory (0x11)

18

reliable-update (0x12)

19

generate-key-blob (0x13)

20

program-fuse (0x14)

21

key-provisioning (0x15)

22

trust-provisioning (0x16)

23

fuse-read (0x17)

24

update-life-cycle(0x18)

[31:25]

reserved

MCU Bootloader operation

The correct use of blhost program requires a connection to a MCU device running the MCU bootloader command interface. The diagram shows a simplified view of the MCU bootloader state machine that shows the states relevant to blhost application.

../_images/mcu_bootloader_state_diagram.png

Simplified MCU Bootloader state diagram

After reset, the bootloader monitors all enabled peripheral devices, UART, I2C, SPI, CAN, USB-HID, and USB-MSC for active communication. After communication is established, all peripherals except the active peripheral are shut down, and the bootloader enters the command processing state.

If the bootloader is in the “Detect Active Peripheral” state, the first use of blhost application establishes the active peripheral and the bootloader transitions to the “Process Commands” state. The active peripheral is established according to the transport used by the initial blhost invocation.

For example, if the -u option was successfully used to send the initial command, the USB-HID is the active peripheral and all future commands must use the -u option unless the bootloader is reset.

If the -p COMx option is used, the UART is the active peripheral and all future commands must use the –p COMx option unless the bootloader is reset. For the UART peripheral, the baud rate is automatically determined by the bootloader when processing the initial ping. Therefore, subsequent blhost invocations must specify the same baud rate as was used for the initial invocation unless the bootloader is reset. If the baud rate is not specified using the -p COMx,<baudrate> option, the UART baud rate is set to 57600.

Note

After the MCU bootloader is in the “Process Commands” state, the device has to be reset to communicate over a different peripheral or at a different baud rate over the same UART peripheral.

Command line interface

blhost consist of a set of sub-commands followed by options and arguments. The options and the sub-command are separated with a ‘–’.

blhost [options] -- [sub-command]

The “help” guide of blhost lists all of the options and sub-commands supported by the blhost utility.

blhost --help

All sub-commands are not supported on all MCU bootloader platforms. If a sub-command is not supported by the MCU bootloader, it returns k_StatusUnknownCommand.

When flash security is enabled, only the get-property, set-property, reset, flash-security-disable, and flash-erase-all-unsecure sub-commands are supported. The MCU bootloader returns kStatus_SecurityViolation if a sub-command is received that is not supported due to flash security settings.

blhost

Utility for communication with the bootloader on target.

blhost [OPTIONS] COMMAND [ARGS]...

Options

-p, --port <COM[,speed>

Serial port configuration. Default baud rate is 57600. Use ‘nxpdevscan’ utility to list devices on serial port.

-u, --usb <VID:PID|USB_PATH|DEV_NAME>

USB device identifier.

Following formats are supported: <vid>, <vid:pid> or <vid,pid>, device/instance path, device name.
<vid>: hex or dec string; e.g. 0x0AB12, 43794.
<vid/pid>: hex or dec string; e.g. 0x0AB12:0x123, 1:3451.
Use ‘nxpdevscan’ utility to list connected device names.
-l, --lpcusbsio <usb,VID:PID|USB_PATH|SER_NUM,]spi|i2c>

USB-SIO bridge interface.

Optional USB device filtering formats: [usb,vid:pid|usb_path|serial_number]

Following serial interfaces are supported:

spi[index][,port,pin,speed_kHz,polarity,phase]
- index … optional index of SPI peripheral. Example: “spi1” (default=0)
- port … bridge GPIO port used as SPI SSEL(default=0)
- pin … bridge GPIO pin used as SPI SSEL
default SSEL is set to 0.15 which works
for the LPCLink2 bridge. The MCULink OB
bridge ignores the SSEL value anyway.(default=15)
- speed_kHz … SPI clock in kHz (default 1000)
- polarity … SPI CPOL option (default=1)
- phase … SPI CPHA option (default=1)
i2c[index][,address,speed_kHz]
- index … optional index of I2C peripheral. Example: “i2c1” (default=0)
- address … I2C device address (default 0x10)
- speed_kHz … I2C clock in kHz (default 100)
-b, --buspal <spi[,speed,polarity,phase,lsb|msb] | i2c[,address,speed>

buspal settings

-j, --json

Use JSON output

-t, --timeout <ms>

Sets timeout when waiting on data over a serial line. The default is 5000 milliseconds.

-v, --verbose

Print more detailed information

-vv, --debug

Display more debugging information.

--version

Show the version and exit.

--help

Show this message and exit.

-s, --silent

Silent mode suppresses progress bar and status response

blhost reset

Resets the device.

A response packet is sent before resetting the device.

blhost reset [OPTIONS]

After the reset the device boots from flash and user image is programmed successfully using ROM bootloader.

Note

After issuing the reset sub-command, allow 5 seconds for the user application to start running from flash.

blhost get-property

Queries various bootloader properties and settings.

Each supported property has a unique <PROPERTY_TAG>.

PROPERTY_TAG - number or name representing the requested property
INDEX - id/index of the memory (default: 0)
Available properties:
0 or ‘list-properties’ List all properties
1 or ‘current-version’ Bootloader version
2 or ‘available-peripherals’ Available peripherals
3 or ‘flash-start-address’ Start of program flash, <index> is required
4 or ‘flash-size-in-bytes’ Size of program flash, <index> is required
5 or ‘flash-sector-size’ Size of flash sector, <index> is required
6 or ‘flash-block-count’ Blocks in flash array, <index> is required
7 or ‘available-commands’ Available commands
8 or ‘check-status’ Check Status, <status id> is required
9 or ‘reserved’
10 or ‘verify-writes’ Verify Writes flag
11 or ‘max-packet-size’ Max supported packet size
12 or ‘reserved-regions’ Reserved regions
13 or ‘reserved’
14 or ‘ram-start-address’ Start of RAM, <index> is required
15 or ‘ram-size-in-bytes’ Size of RAM, <index> is required
16 or ‘system-device-id’ System device identification
17 or ‘security-state’ Flash security state
18 or ‘unique-device-id’ Unique device identification
19 or ‘flash-fac-support’ FAC support flag
20 or ‘flash-access-segment-size’ FAC segment size
21 or ‘flash-access-segment-count’ FAC segment count
22 or ‘flash-read-margin’ Read margin level of program flash
23 or ‘qspi/otfad-init-status’ QuadSpi initialization status
24 or ‘target-version’ Target version
25 or ‘external-memory-attributes’ External memory attributes, <memoryId> is required
26 or ‘reliable-update-status’ Reliable update status
27 or ‘flash-page-size’ Flash page size, <index> is required
28 or ‘irq-notify-pin’ Interrupt notifier pin
29 or ‘pfr-keystore_update-opt’ PFR key store update option
30 or ‘byte-write-timeout-ms’ Byte write timeout in ms
Note: Not all the properties are available for all devices.
blhost get-property [OPTIONS] PROPERTY_TAG [INDEX]

Arguments

PROPERTY_TAG

Required argument

INDEX

Optional argument

Note

Not all properties are supported by all target. To check the supported properties, see the target’s user manual or the reference manual.

Memory ID

Internal Memory

Device internal memory space

0

Internal Memory (Default selected memory)

16 (0x10)

Execute-only region on internal flash (Only used for flash-erase-all)

Mapped
External
Memory

The memories that are remapped to internal space, and must be accessed
by internal addresses. (IDs in this group are only used for
flash-erase-all and configure-memory, and ignored by write-memory,
read-memory, flash-erase-region and flash-image(use default 0))

1

QuadSPI Memory

8

SEMC NOR Memory

9

FlexSPI NOR Memory

10 (0xa)

SPIFI NOR Memory

Unmapped
External
Memory

Memories which cannot be remapped to internal space, and only can be
accessed by memories’ addresses. (Must be specified for all commands
with <memoryId> argument)

256 (0x100)

SEMC NAND Memory

257 (0x101)

SPI NAND Memory

272 (0x110)

SPI NOR/EEPROM Memory

273 (0x111)

I2C NOR/EEPROM Memory

288 (0x120)

uSDHC SD Memory

289 (0x121)

uSDHC MMC Memory

blhost set-property

Changes properties and options in the bootloader.

Accepts the same <PROPERTY_TAG> used with the get-property sub-command; however, only some properties are writable.

PROPERTY_TAG - number or name representing the requested property
VALUE - value to set
Available properties to set:
10 or ‘verify-writes’ Verify Writes flag
22 or ‘flash-read-margin’ Read margin level of program flash
28 or ‘irq-notify-pin’ Interrupt notifier pin
29 or ‘pfr-keystore_update-opt’ PFR key store update option
30 or ‘byte-write-timeout-ms’ Byte write timeout in ms
Note: Not all properties can be set on all devices.
blhost set-property [OPTIONS] PROPERTY_TAG VALUE

Arguments

PROPERTY_TAG

Required argument

VALUE

Required argument

Note

If an attempt to write a read-only property is made, an error is returned indicating the property is read-only and cannot be changed.

Properties that can be changed all have 32-bit values.

blhost flash-erase-region

Erases one or more sectors of the flash memory.

The start <ADDRESS> and <BYTE_COUNT> must be a multiple of the word size. The entire sector(s) containing the start and end address is erased.

ADDRESS - starting address
BYTE_COUNT - number of bytes to erase
MEMORY_ID - id of memory to erase (default: 0)
blhost flash-erase-region [OPTIONS] ADDRESS BYTE_COUNT [MEMORY_ID]

Arguments

ADDRESS

Required argument

BYTE_COUNT

Required argument

MEMORY_ID

Optional argument

Note

If the VerifyWrites property is enabled, the sub-command performs a flash verify erase operation.

blhost flash-erase-all

Performs an erase of the entire flash memory.

MEMORY_ID - id of memory to erase (default: 0)
Note: excluding protected regions.
blhost flash-erase-all [OPTIONS] [MEMORY_ID]

Arguments

MEMORY_ID

Optional argument

Note

If any flash regions are protected, the sub-command fails with an error.

If any flash regions are reserved by the bootloader, they are ignored (not erased).

If the VerifyWrites property is enabled, the flash-erase-all sub-command performs a flash verify erase all operation, or multiple flash verify erase options if decomposed due to reserved regions.

blhost flash_security_disable

Disable flash security by using of backdoor key.

KEY - key value as hex-string (8 bytes long)
blhost flash_security_disable [OPTIONS] KEY

Arguments

KEY

Required argument

Note

Performs the flash security disable operation by comparing the provided 8-byte backdoor key against the backdoor key stored in the Flash Configuration Field at address 0x400 in flash.

If the backdoor key comparison fails, further attempts to disable security with this command fails until the system is reset.

Backdoor key access must be enabled by setting the KEYEN bitfield of the FSEC byte in the Flash Configuration Field to 0b10. It is disabled by default. The backdoor key in the Flash Configuration Field must also be set to a value other than all zeros or all ones.

blhost read-memory

Reads the memory and writes it to the file or stdout.

Returns the contents of memory at the given <ADDRESS>, for a specified <BYTE_COUNT>.

ADDRESS - starting address
BYTE_COUNT - number of bytes to read
FILE - store result into this file, if not specified use stdout.
If needed specify MEMORY_ID argument, use ‘-’ instead name of file
to print to stdout.
MEMORY_ID - id of memory to read from (default: 0)
blhost read-memory [OPTIONS] ADDRESS BYTE_COUNT FILE [MEMORY_ID]

Options

-h, --use-hexdump

Use hexdump format

-f, --fast-mode

Fast mode for USB-HID data transfer, not reliable !!!

Arguments

ADDRESS

Required argument

BYTE_COUNT

Required argument

FILE

Optional argument

MEMORY_ID

Optional argument

Note

This sub-command can read any region of memory accessible by the CPU and not protected by security. This includes flash, RAM, and peripheral registers.

Note that the minimum profile does not support reading the peripheral register space.

blhost write-memory

Writes memory from a file or a hex-data.

Writes memory specified by <MEMORY_ID> at <ADDRESS> from <FILE> or <HEX-DATA> Writes a provided buffer to a specified <BYTE_COUNT> in memory.

ADDRESS - starting address
FILE - write the content of this file
BYTE_COUNT - if specified, load only first BYTE_COUNT number of bytes from file
HEX-DATA - string of hex values: {{112233}}, {{11 22 33}}
MEMORY_ID - id of memory to read from (default: 0)
blhost write-memory [OPTIONS] ADDRESS FILE[,BYTE_COUNT] | {{HEX-DATA}}
                    [MEMORY_ID]

Arguments

ADDRESS

Required argument

FILE[,BYTE_COUNT] | {{HEX-DATA}}

Required argument

MEMORY_ID

Optional argument

Note

Can write to all accessible memory, including flash, RAM, and peripheral registers. However, if flash protection is enabled, writes to protected sectors fails. Data specified by file is treated as binary data.

Any flash sector written to must be previously erased with either a flash-erase-all, flash-erase-region, or flash-erase-allunsecure sub-command.

Writing to flash requires the start address to be word aligned. The byte count is rounded up to a multiple of the word size, and trailing bytes are filled with the flash erase pattern (0xff).

Word and half-word-aligned and sized writes to RAM and peripheral registers use appropriately sized writes. This enables writing to registers larger than a byte in a single bus transaction.

Note that the minimum profile does not support writing to the peripheral register space.

If the VerifyWrites property is enabled, writes to flash performs a flash verify program operation.

blhost list-memory

Lists all memories, supported by the current device.

blhost list-memory [OPTIONS]

blhost receive-sb-file

Receives a file in a Secure Binary (SB) format.

An SB file is an encapsulated, binary stream of bootloader commands that can be optionally encrypted.

FILE - SB file to send to the target
blhost receive-sb-file [OPTIONS] FILE

Options

-c, --check-errors

This flag should be used when the receive-sb-file operation fails using USB interface. Without this flag USB transfer is significantly faster (roughly 20x) However, the status code might be misleading in case of an error. In case of an error using USB interface, rerun receive-sb-file with this setting for clearer error message. This setting has no effect interfaces other than USB.

Arguments

FILE

Required argument

Note

The SB file format is described in the document elftosb User’s Guide and can be created using the elftosb tool.

Note that if the SB file contains a JUMP command, the receive-sb-file sub-command is aborted at the point of the jump, and a status of kStatus_AbortDataPhase is returned.

blhost execute

Jumps to code at the provided address.

The system is returned to a reset state before the jump. The function <ARGUMENT> parameter is passed in R0 to the called code.

The main stack pointer and process stack pointer registers are set to the <STACKPOINTER> parameter. If set to zero, the code being called should set the stack pointer before using the stack.

ADDRESS - Address of the application to run
ARGUMENT - Argument passed to the application
STACKPOINTER - Stack pointer for the application
blhost execute [OPTIONS] ADDRESS ARGUMENT STACKPOINTER

Arguments

ADDRESS

Required argument

ARGUMENT

Required argument

STACKPOINTER

Required argument

Note

The effective prototype of the called function is:

void function(uint32_t arg);

blhost call

Invokes code at an address, passing an argument to it.

ADDRESS - function code address
ARGUMENT - argument for the function
blhost call [OPTIONS] ADDRESS ARGUMENT

Arguments

ADDRESS

Required argument

ARGUMENT

Required argument

Note

The function that is called has the same prototype as for the one called by the execute command.

Because the intention is to return to the bootloader after the function executes, the function must not perform any action that would interfere with the bootloader operation. In particular, the following restrictions apply:

  • Do not use interrupts because the interrupt vectors are still owned by the bootloader.

  • Do not modify any memory locations used by the bootloader (use “get-property 12” to determine reserved regions).

  • Do not modify any pin mux or clock settings used by bootloader peripherals.

blhost flash-program-once

Writes provided data to a specific program once field.

INDEX - fuse word index
BYTE_COUNT - width in bits (acceptable only 4 or 8-byte long data)
DATA - 4 or 8-byte-hex according to <byte_count>
ENDIANNESS - output sequence is specified by LSB (Default) or MSB
blhost flash-program-once [OPTIONS] INDEX {4|8} DATA [LSB|MSB]

Arguments

INDEX

Required argument

BYTE_COUNT

Required argument

DATA

Required argument

[LSB|MSB]

Optional argument

Note

Special care must be taken when writing to program once field. The program once field only supports programming once.

Any attempts to reprogram a program once field gets an error response. The number of bytes to be written must be 4-byte aligned for non-FAC fields, and be 8-byte aligned for FAC fields.

blhost flash-read-once

Returns the contents of a specific program once field.

INDEX - fuse word index
BYTE_COUNT - width in bits (acceptable only 4 or 8-byte long data)
blhost flash-read-once [OPTIONS] INDEX {4|8}

Arguments

INDEX

Required argument

BYTE_COUNT

Required argument

blhost efuse-program-once

Writes data to a specific efuse word.

Each efuse bit can only be programmed once.

ADDRESS - address of OTP word, not the shadowed memory address.
DATA - hex digits without prefix ‘0x’.
blhost efuse-program-once [OPTIONS] ADDRESS DATA [nolock/lock]

Options

-v, --verify, --no-verify

Verify write operation (verify by default)

Arguments

ADDRESS

Required argument

DATA

Required argument

[nolock/lock]

Optional argument

blhost efuse-read-once

Returns the contents of a specific efuse word.

ADDRESS - is the address of OTP word, not the shadowed memory address.
blhost efuse-read-once [OPTIONS] ADDRESS

Arguments

ADDRESS

Required argument

blhost flash-read-resource

Read resource of flash module.

Reads the contents of Flash IFR or Flash Firmware ID as specified by option and writes result to file or stdout if file is not specified.

ADDRESS - Start address
LENGTH - Number of bytes to read. Must be 4-byte aligned.
OPTION - Area to be read. 0 means Flash IFR, 1 means Flash Firmware ID.
OUT_FILE - Path to file, where the output will be stored
blhost flash-read-resource [OPTIONS] ADDRESS LENGTH {0|1} FILE

Options

-h, --use-hexdump

Use hexdump format

Arguments

ADDRESS

Required argument

LENGTH

Required argument

OPTION

Required argument

FILE

Optional argument

blhost configure-memory

Sets a config at internal memory to memory with ID.

The specified configuration block must have been previously written to memory using the write-memory command.

MEMORY_ID - id of memory
ADDRESS - starting address
blhost configure-memory [OPTIONS] MEMORY_ID ADDRESS

Arguments

MEMORY_ID

Required argument

ADDRESS

Required argument

Note

The format of the configuration block is described in the MCU Bootloader Reference Manual document.

blhost flash-image

Write the formatted image in <FILE> to the memory specified by memoryID.

FILE - path to image file
ERASE - string ‘erase’ determines if flash is erased before writing
MEMORY_ID - id of memory to erase (default: 0)
blhost flash-image [OPTIONS] FILE [ERASE] [MEMORY_ID]

Arguments

FILE

Required argument

ERASE

Optional argument

MEMORY_ID

Optional argument

blhost generate-key-blob

Generates the Key Blob, and writes it to the file.

<KEY_SEL> selects the blob key encryption key(BKEK) used to generate the key blob.

DEK_FILE - the file with the binary DEK key
BLOB_FILE - the generated file with a binary key blob
KEY_SEL - select the BKEK used to wrap the BK and generate the blob.
For devices with SNVS, valid options of [key_sel] are
0, 1 or OTPMK: OTPMK from FUSE or OTP(default),
2 or ZMK: ZMK from SNVS,
3 or CMK: CMK from SNVS,
For devices without SNVS, this option will be ignored.
blhost generate-key-blob [OPTIONS] DEK_FILE BLOB_FILE [KEY_SEL]

Arguments

DEK_FILE

Required argument

BLOB_FILE

Required argument

[KEY_SEL]

Optional argument

blhost key-provisioning

Group of sub-commands related to key provisioning.

blhost key-provisioning [OPTIONS] COMMAND [ARGS]...

enroll

Enrolls key provisioning feature. No argument for this operation.

blhost key-provisioning enroll [OPTIONS]

read_key_nonvolatile

Loads the key from nonvolatile memory to bootloader.

memoryID - ID of the non-volatile memory, default: 0
blhost key-provisioning read_key_nonvolatile [OPTIONS] memoryID

Arguments

memoryID

Optional argument

read_key_store

Reads the key store from the bootloader to host(PC).

<FILE> is the binary file to store the key store.

FILE - Binary file to save the key store.
blhost key-provisioning read_key_store [OPTIONS] FILE

Arguments

FILE

Required argument

set_key

Generates a size bytes of the key specified by the type.

TYPE - type of key to generate,
SIZE - size of key to generate
Available KEY TYPES:
2 or ‘OTFADKEK’ OTFAD key
3 or ‘SBKEK’ SB file encryption key
7 or ‘PRINCE0’ Prince region 0 encryption key
8 or ‘PRINCE1’ Prince region 1 encryption key
9 or ‘PRINCE2’ Prince region 2 encryption key
11 or ‘USERKEK’ User/Boot-image encryption key
12 or ‘UDS’ Universal Device Secret for DICE
Note: The valid options of <type> and corresponding <size> are documented
in the target’s Reference Manual or User Manual.
Note: Names are case insensitive
blhost key-provisioning set_key [OPTIONS] TYPE SIZE

Arguments

TYPE

Required argument

SIZE

Required argument

set_user_key

Sends the user key specified by type to the bootloader.

<FILE> is the binary file containing user key plain text. If <SIZE> is not specified, the entire <FILE> will be sent. Otherwise, blhost only sends the first <SIZE> bytes.

TYPE - Type of user key
FILE - Binary file containing user key plaintext
SIZE - If not specified, the entire <file> will be sent. Otherwise, only send
the first <size> bytes.
Available KEY TYPES:
2 or ‘OTFADKEK’ OTFAD key
3 or ‘SBKEK’ SB file encryption key
7 or ‘PRINCE0’ Prince region 0 encryption key
8 or ‘PRINCE1’ Prince region 1 encryption key
9 or ‘PRINCE2’ Prince region 2 encryption key
11 or ‘USERKEK’ User/Boot-image encryption key
12 or ‘UDS’ Universal Device Secret for DICE
Note: The valid options of <type> and corresponding <size> are documented
in the target’s Reference Manual or User Manual.
Note: Names are case insensitive
blhost key-provisioning set_user_key [OPTIONS] TYPE FILE[,SIZE]

Arguments

TYPE

Required argument

FILE[,SIZE]

Required argument

write_key_nonvolatile

Writes the key to nonvolatile memory.

memoryID - ID of the non-volatile memory, default: 0
blhost key-provisioning write_key_nonvolatile [OPTIONS] memoryID

Arguments

memoryID

Optional argument

write_key_store

Sends the key store to the bootloader.

<FILE> is the binary file containing key store. If <SIZE> is not specified, the entire <FILE> will be sent. Otherwise, only send the first <SIZE> bytes.

FILE - Binary file containing key store.
SIZE - If not specified, the entire <file> will be sent. Otherwise, only send
the first <size> bytes.
blhost key-provisioning write_key_store [OPTIONS] FILE[,SIZE]

Arguments

FILE[,SIZE]

Required argument

blhost program-aeskey

Sends raw binary, which contains an aes key, to the devices and program it to the OTP field.

FILE - file, which contains an aes key
blhost program-aeskey [OPTIONS] FILE

Arguments

FILE

Required argument

blhost flash-erase-all-unsecure

Erase complete flash memory and recover flash security section.

blhost flash-erase-all-unsecure [OPTIONS]

Note

This command is only supported in new versions of the flash controller. Most MCU devices do not support this command, and the bootloader sends a kStatus_UnknownCommand error in response.

Performs a mass erase of the flash memory, including protected sectors and any reserved regions in flash. Flash security is immediately disabled if it was enabled and the FSEC byte in the Flash Configuration Field at address 0x40C is programmed to 0xFE.

The Mass Erase Enable option in the FSEC field is honored by this command. If mass erase is disabled, then this command fails.

This command is only useful and only present in ROM configurations of the bootloader because it erases reserved regions in flash.

blhost reliable-update

Reliable Update.

ADDRESS - starting address
blhost reliable-update [OPTIONS] ADDRESS

Arguments

ADDRESS

Required argument

Note

For software implementation: Checks the validity of backup application at <addr>, then copies the contents of backup application from <addr> to main application region.

For hardware implementation: Verifies if the provided <addr> is a valid swap indicator address for flash swap system, then checks the validity of backup application resided in upper flash block. After that, it swaps the flash system.

blhost fuse-program

Program fuse.

ADDRESS - starting address
FILE - write the content of this file
BYTE_COUNT - if specified, load only first BYTE_COUNT number of bytes from file
HEX-DATA - string of hex values: {{112233}}, {{11 22 33}}
MEMORY_ID - id of memory to read from (default: 0)
blhost fuse-program [OPTIONS] ADDRESS FILE[,BYTE_COUNT] | {{HEX-DATA}}
                    [MEMORY_ID]

Arguments

ADDRESS

Required argument

FILE[,BYTE_COUNT] | {{HEX-DATA}}

Required argument

MEMORY_ID

Optional argument

blhost fuse-read

Reads the fuse and writes it to the file or stdout.

Returns the contents of memory at the given <ADDRESS>, for a specified <BYTE_COUNT>.

ADDRESS - starting address
BYTE_COUNT - number of bytes to read
FILE - store result into this file, if not specified use stdout
MEMORY_ID - id of memory to read from (default: 0)
blhost fuse-read [OPTIONS] ADDRESS BYTE_COUNT FILE [MEMORY_ID]

Options

-h, --use-hexdump

Use hexdump format

Arguments

ADDRESS

Required argument

BYTE_COUNT

Required argument

FILE

Optional argument

MEMORY_ID

Optional argument

..note::

Write the formatted image in <file> to the memory specified by memoryID. Supported file types are S-Record (.srec and .s19), and Hex (.hex). Flash is erased before writing if [erase] is ‘erase’ or 1. This blhost command does not directly correspond to a bootloader command, but may send multiple bootloader commands to perform the operation.

..note:: Elf files are not supported yet.

blhost trust-provisioning

Group of sub-commands related to trust provisioning.

blhost trust-provisioning [OPTIONS] COMMAND [ARGS]...

hsm_enc_blk

Encrypts the given SB3 data block.

MFG_CUST_MK_SK_0_BLOB_INPUT_ADDR - The input buffer address where the CKDF Master Key Blob locates at
MFG_CUST_MK_SK_0_BLOB_INPUT_SIZE - The byte count of the CKDF Master Key Blob
KEK_ID - The CKDF Master Key Encryption Key ID
(0x10: NXP_CUST_KEK_INT_SK, 0x11: NXP_CUST_KEK_EXT_SK)
SB3_HEADER_INPUT_ADDR - The input buffer address where the SB3 Header(block0) locates at
SB3_HEADER_INPUT_SIZE - The byte count of the SB3 Header
BLOCK_NUM - The index of the block. Due to SB3 Header(block 0) is always unencrypted,
the index starts from block1
BLOCK_DATA_ADDR - The buffer address where the SB3 data block locates at
BLOCK_DATA_SIZE - The byte count of the SB3 data block
blhost trust-provisioning hsm_enc_blk [OPTIONS]
                                      MFG_CUST_MK_SK_0_BLOB_INPUT_ADDR
                                      MFG_CUST_MK_SK_0_BLOB_INPUT_SIZE KEK_ID
                                      SB3_HEADER_INPUT_ADDR
                                      SB3_HEADER_INPUT_SIZE BLOCK_NUM
                                      BLOCK_DATA_ADDR BLOCK_DATA_SIZE

Arguments

MFG_CUST_MK_SK_0_BLOB_INPUT_ADDR

Required argument

MFG_CUST_MK_SK_0_BLOB_INPUT_SIZE

Required argument

KEK_ID

Required argument

SB3_HEADER_INPUT_ADDR

Required argument

SB3_HEADER_INPUT_SIZE

Required argument

BLOCK_NUM

Required argument

BLOCK_DATA_ADDR

Required argument

BLOCK_DATA_SIZE

Required argument

hsm_enc_sign

Signs the given data.

It uses the private key in the given key blob, which is generated by HSM_GEN_KEY.

KEY_BLOB_INPUT_ADDR - The input buffer address where signing key blob locates at
KEY_BLOB_INPUT_SIZE - The byte count of the signing key blob
BLOCK_DATA_INPUT_ADDR - The input buffer address where the data locates at
BLOCK_DATA_INPUT_SIZE - The byte count of the data
SIGNATURE_OUTPUT_ADDR - The output buffer address where ROM writes the signature to
SIGNATURE_OUTPUT_SIZE - The output buffer size in byte
blhost trust-provisioning hsm_enc_sign [OPTIONS] KEY_BLOB_INPUT_ADDR
                                       KEY_BLOB_INPUT_SIZE
                                       BLOCK_DATA_INPUT_ADDR
                                       BLOCK_DATA_INPUT_SIZE
                                       SIGNATURE_OUTPUT_ADDR
                                       SIGNATURE_OUTPUT_SIZE

Arguments

KEY_BLOB_INPUT_ADDR

Required argument

KEY_BLOB_INPUT_SIZE

Required argument

BLOCK_DATA_INPUT_ADDR

Required argument

BLOCK_DATA_INPUT_SIZE

Required argument

SIGNATURE_OUTPUT_ADDR

Required argument

SIGNATURE_OUTPUT_SIZE

Required argument

hsm_gen_key

Creates OEM common keys, including encryption keys and signing keys.

It outputs the key blob, which is wrapped by NXP_CUST_KEK_IN_SK and the public portion of the signing key.

KEY_TYPE - Type of key to generate (MFWISK, MFWENCK, GENSIGNK, GETCUSTMKSK)
RESERVED - Reserved must be 0
KEY_BLOB_OUTPUT_ADDR - Output buffer address where ROM writes the key blob to
KEY_BLOB_OUTPUT_SIZE - Output buffer size in bytes
ECDSA_PUK_OUTPUT_ADDR - Output buffer address where ROM writes the public key to
ECDSA_PUK_OUTPUT_SIZE - Output buffer size in bytes
blhost trust-provisioning hsm_gen_key [OPTIONS] KEY_TYPE RESERVED
                                      KEY_BLOB_OUTPUT_ADDR
                                      KEY_BLOB_OUTPUT_SIZE
                                      ECDSA_PUK_OUTPUT_ADDR
                                      ECDSA_PUK_OUTPUT_SIZE

Arguments

KEY_TYPE

Required argument

RESERVED

Required argument

KEY_BLOB_OUTPUT_ADDR

Required argument

KEY_BLOB_OUTPUT_SIZE

Required argument

ECDSA_PUK_OUTPUT_ADDR

Required argument

ECDSA_PUK_OUTPUT_SIZE

Required argument

hsm_store_key

Stores known keys, and generate the corresponding key blob.

It wraps the known key, which is given by the customer, using NXP_CUST_KEK_EXT_SK, and output the RFC3396 key blob.

KEY_TYPE - Type of key to generate (CKDFK, HKDFK, HMACK, CMACK, AESK, KUOK)
KEY_PROPERTY - Bit 0: Key Size, 0 for 128bit, 1 for 256bit. Bits 30-31: set key protection CSS mode
KEY_INPUT_ADDR - The input buffer address where the key locates at
KEY_INPUT_SIZE - The byte count of the key
KEY_BLOB_OUTPUT_ADDR - The output buffer address where ROM writes the key blob to
KEY_BLOB_OUTPUT_SIZE - The output buffer size in byte
blhost trust-provisioning hsm_store_key [OPTIONS] KEY_TYPE KEY_PROPERTY
                                        KEY_INPUT_ADDR KEY_INPUT_SIZE
                                        KEY_BLOB_OUTPUT_ADDR
                                        KEY_BLOB_OUTPUT_SIZE

Arguments

KEY_TYPE

Required argument

KEY_PROPERTY

Required argument

KEY_INPUT_ADDR

Required argument

KEY_INPUT_SIZE

Required argument

KEY_BLOB_OUTPUT_ADDR

Required argument

KEY_BLOB_OUTPUT_SIZE

Required argument

isp_set_wrap_data

Start the process of setting wrapped OEM data.

ADDRESS - Address of the Wrapped data package in target
CONTROL - Controls location of the Wrapped data package (1 - by address /default/, 2 - in firmware)
STAGE - Stage of the OEM TrustProvisioning process
blhost trust-provisioning isp_set_wrap_data [OPTIONS] ADDRESS [CONTROL]
                                            [STAGE]

Arguments

ADDRESS

Required argument

CONTROL

Optional argument

STAGE

Optional argument

oem_gen_master_share

Creates shares for initial trust provisioning keys.

OEM_SHARE_INPUT_ADDR - The input buffer address where the OEM Share(entropy seed) locates at
OEM_SHARE_INPUT_SIZE - The byte count of the OEM Share
OEM_ENC_SHARE_OUTPUT_ADDR - The output buffer address where ROM writes the Encrypted OEM Share to
OEM_ENC_SHARE_OUTPUT_SIZE - The output buffer size in byte
OEM_ENC_MASTER_SHARE_OUTPUT_ADDR - The output buffer address where ROM writes the Encrypted OEM Master Share to
OEM_ENC_MASTER_SHARE_OUTPUT_SIZE - The output buffer size in byte.
OEM_CUST_CERT_PUK_OUTPUT_ADDR - The output buffer address where ROM writes
the OEM Customer Certificate Public Key to
OEM_CUST_CERT_PUK_OUTPUT_SIZE - The output buffer size in byte
blhost trust-provisioning oem_gen_master_share [OPTIONS] OEM_SHARE_INPUT_ADDR
                                               OEM_SHARE_INPUT_SIZE
                                               OEM_ENC_SHARE_OUTPUT_ADDR
                                               OEM_ENC_SHARE_OUTPUT_SIZE OEM_E
                                               NC_MASTER_SHARE_OUTPUT_ADDR OEM
                                               _ENC_MASTER_SHARE_OUTPUT_SIZE
                                               OEM_CUST_CERT_PUK_OUTPUT_ADDR
                                               OEM_CUST_CERT_PUK_OUTPUT_SIZE

Arguments

OEM_SHARE_INPUT_ADDR

Required argument

OEM_SHARE_INPUT_SIZE

Required argument

OEM_ENC_SHARE_OUTPUT_ADDR

Required argument

OEM_ENC_SHARE_OUTPUT_SIZE

Required argument

OEM_ENC_MASTER_SHARE_OUTPUT_ADDR

Required argument

OEM_ENC_MASTER_SHARE_OUTPUT_SIZE

Required argument

OEM_CUST_CERT_PUK_OUTPUT_ADDR

Required argument

OEM_CUST_CERT_PUK_OUTPUT_SIZE

Required argument

oem_get_cust_cert_dice_puk

Creates the initial trust provisioning keys.

OEM_RKTH_INPUT_ADDR - The input buffer address where the OEM RKTH locates at
OEM_RKTH_INPUT_SIZE - The byte count of the OEM RKTH
OEM_CUST_CERT_DICE_PUK_OUTPUT_ADDR - The output buffer address where ROM writes the OEM Customer
Certificate Public Key for DICE to
OEM_CUST_CERT_DICE_PUK_OUTPUT_SIZE - The output buffer size in byte
blhost trust-provisioning oem_get_cust_cert_dice_puk [OPTIONS]
                                                     OEM_RKTH_INPUT_ADDR
                                                     OEM_RKTH_INPUT_SIZE OEM_C
                                                     UST_CERT_DICE_PUK_OUTPUT_
                                                     ADDR OEM_CUST_CERT_DICE_P
                                                     UK_OUTPUT_SIZE

Arguments

OEM_RKTH_INPUT_ADDR

Required argument

OEM_RKTH_INPUT_SIZE

Required argument

OEM_CUST_CERT_DICE_PUK_OUTPUT_ADDR

Required argument

OEM_CUST_CERT_DICE_PUK_OUTPUT_SIZE

Required argument

oem_set_master_share

Takes the entropy seed and the Encrypted OEM Master Share.

blhost trust-provisioning oem_set_master_share [OPTIONS] OEM_SHARE_INPUT_ADDR
                                               OEM_SHARE_INPUT_SIZE
                                               OEM_ENC_MASTER_SHARE_INPUT_ADDR
                                               OEM_ENC_MASTER_SHARE_INPUT_SIZE

Arguments

OEM_SHARE_INPUT_ADDR

Required argument

OEM_SHARE_INPUT_SIZE

Required argument

OEM_ENC_MASTER_SHARE_INPUT_ADDR

Required argument

OEM_ENC_MASTER_SHARE_INPUT_SIZE

Required argument

prove_genuinity

Start the process of proving genuinity.

ADDRESS - Address where is the prove_genuinity request stored
BUFFER_SIZE - Maximal size of the generated prove_genuinity response
blhost trust-provisioning prove_genuinity [OPTIONS] ADDRESS BUFFER_SIZE

Arguments

ADDRESS

Required argument

BUFFER_SIZE

Required argument

blhost batch

Invoke blhost commands defined in command file.

Command file contains one blhost command per line. example: “read-memory 0 4096 memory.bin” example: “get-property 24 # read target version”

Comment are supported. Everything after ‘#’ is a comment (just like in Python/Shell)

Note: This is an early experimental format, it may change at any time.

COMMAND_FILE - path to blhost command file
blhost batch [OPTIONS] COMMAND_FILE

Arguments

COMMAND_FILE

Required argument

blhost update-life-cycle

Update life cycle of device.

LIFE CYCLE - Device life cycle to be device move to.
blhost update-life-cycle [OPTIONS] LIFE CYCLE

Arguments

LIFE CYCLE

Required argument