User Guide - nxpdebugmbox#

This user’s guide describes how to use nxpdebugmbox application.

Command line interface#

nxpdebugmbox#

Tool for working with Debug Mailbox.

nxpdebugmbox [OPTIONS] COMMAND [ARGS]...

Options

-i, --interface <interface>#

Probe interface selection, if not specified, all available debug probe interfaces are used. [‘pyocd’]

-s, --serial-no <serial_no>#

Debug probe hardware ID/serial number to select the probe in system.

-p, --protocol <VERSION>#

Set the protocol version. Currently this option is used for gendc and auth sub commands.Available options are: 1.0, 1.1, 2.0, 2.1, 2.2. If not set, the version will be determined from the RoT public key type.

Options:

1.0 | 1.1 | 2.0 | 2.1 | 2.2

-t, --timing <timing>#

Duration of additional delay after reset sequence, defaults to 0 seconds

-n, --no-reset#

Omit reset of debug mailbox during initialization, default behavior is reset debug mailbox during initialization.

-o, --debug-probe-option <debug_probe_option>#

This option could be used multiply to setup non-standard option for debug probe.

The example of use: -o KEY=VALUE

[pyocd]:

[test_address]: Address for testing memory AP, default is 0x2000_0000

--operation-timeout <operation_timeout>#

Special option to change the standard operation timeout used for communication with debug mailbox. Default value is 1000ms.

-v, --verbose#

Print more detailed information

-vv, --debug#

Display more debugging information.

--version#

Show the version and exit.

--help#

Show this message and exit.

--plugin <plugin>#

External python file/package containing a custom plugin implementation.

auth#

Perform the Debug Authentication.

The -p protocol option must be defined in main application.

nxpdebugmbox auth [OPTIONS]

Options

-b, --beacon <beacon>#

Required Authentication beacon

-c, --certificate <certificate>#

Path to Debug Credentials.

-k, --key <key>#

Path to DCK private key.

-n, --no-exit#

When used, exit debug mailbox command is not executed after debug authentication.

-x, --nxp-keys#

Use the ROM NXP keys to authenticate.

-a, --address <address>#

The AHB access test address, the default is 0x2000_0000, but some chips needs different.

erase#

Erase Flash.

nxpdebugmbox erase [OPTIONS]

erase-one-sector#

Erase one flash sector.

nxpdebugmbox erase-one-sector [OPTIONS]

Options

-a, --address <address>#

Required Starting address

exit#

Exit DebugMailBox.

nxpdebugmbox exit [OPTIONS]

famode#

Set Fault Analysis Mode.

nxpdebugmbox famode [OPTIONS]

Options

-m, --message <message>#

Path to message file.

famode-image#

Group of sub-commands related to Fault Analysis Mode Image (related to some families).

nxpdebugmbox famode-image [OPTIONS] COMMAND [ARGS]...
export#

Generate Fault Analysis mode image from YAML/JSON configuration.

The configuration template files could be generated by subcommand ‘get-templates’.

nxpdebugmbox famode-image export [OPTIONS]

Options

-c, --config <config>#

Required Path to the YAML/JSON configuration file.

--plugin <plugin>#

External python file/package containing a custom plugin implementation.

get-templates#

Create template of Fault Analysis mode image configurations in YAML format.

nxpdebugmbox famode-image get-templates [OPTIONS]

Options

-f, --family <family>#

Select the chip family.

Options:

k32w1xx | kw45xx | mcxw71xx

-o, --output <output>#

Required Path to a directory, where to store generated/parsed files.

--force#

Force overwriting of existing files.

parse#

Parse MBI Image into YAML configuration and binary images.

nxpdebugmbox famode-image parse [OPTIONS]

Options

-f, --family <family>#

Select the chip family.

Options:

k32w1xx | kw45xx | mcxw71xx

-b, --binary <binary>#

Required Path to binary FA Mode image to parse.

-o, --output <output>#

Required Path to a directory, where to store generated/parsed files.

gendc#

Generate debug certificate (DC).

nxpdebugmbox gendc [OPTIONS]

Options

-c, --config <config>#

Required Path to the YAML/JSON configuration file.

-e, --rot-config <rot_config>#

Specify Root Of Trust from MBI or Cert block configuration file

--plugin <plugin>#

External python file/package containing a custom plugin implementation.

-o, --output <output>#

Required Path to a file, where to store the output.

--force#

Force overwriting of existing files.

get-crp#

Get CRP level. This command should be called after ‘start’ command and with no-reset ‘-n’ option.

nxpdebugmbox get-crp [OPTIONS]

get-template#

Generate the template of Debug Credentials YML configuration file.

nxpdebugmbox get-template [OPTIONS]

Options

-f, --family <family>#

If needed select the chip family.

Options:

k32w1xx | kw45xx | lpc55s0x | lpc55s1x | lpc55s2x | lpc55s3x | lpc55s6x | mcxn23x | mcxn54x | mcxn94x | mcxn9xx | mcxw71xx | mx8ulp | mx93 | mx95 | nhs52sxx | rt118x | rt5xx | rt6xx | rw61x

-r, --revision <revision>#

Chip revision; if not specified, most recent one will be used

-o, --output <output>#

Required Path to a file, where to store the output.

--force#

Force overwriting of existing files.

get-uuid#

Get the UUID from target if possible.

Some devices need to call ‘start’ command prior the get-uuid! Also there could be issue with repeating of this command without hard reset of device ‘reset -h’.

nxpdebugmbox get-uuid [OPTIONS]

ispmode#

Enter ISP Mode.

nxpdebugmbox ispmode [OPTIONS]

Options

-m, --mode <mode>#

Required

read-memory#

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

nxpdebugmbox read-memory [OPTIONS]

Options

-a, --address <address>#

Required Starting address

-c, --count <count>#

Required Number of bytes to read

-o, --output <output>#

Path to a file, where to store the output.

-h, --use-hexdump#

Use hexdump format

reset#

Reset MCU by DebugMailBox.

The reset command implemented in NXPDEBUGMBOX has two modes (option -h):

Reset by RESET REQUEST of debug mailbox that causes the reset of MCU by SYSRESET_REQ. The chip is reset, but the ROM code returns back the chip into debug mailbox handler (without -h/–hard-reset option).

Reset by external reset signal. This reset is done by asserting external reset signal over debug probe. After this reset type the chip behavior is same as after standard reset button on the board. (with -h/–hard-reset option)

nxpdebugmbox reset [OPTIONS]

Options

-h, --hard-reset#

When used, the hardware reset is used instead of debug mailbox reset.

start#

Start DebugMailBox.

nxpdebugmbox start [OPTIONS]

start-debug-session#

Start debug session.

nxpdebugmbox start-debug-session [OPTIONS]

test-connection#

Method just try if the device debug port is opened or not.

nxpdebugmbox test-connection [OPTIONS]

Options

-a, --address <address>#

The AHB access test address, the default is 0x2000_0000, but some chips needs different.

token_auth#

Debug Authentication using token.

nxpdebugmbox token_auth [OPTIONS]

Options

-f, --file <file>#

Required Path to token file (string hex format).

-n, --no-exit#

When used, exit debug mailbox command is not executed after debug authentication.

write-memory#

Writes memory from a file or a hex-data.

nxpdebugmbox write-memory [OPTIONS]

Options

-a, --address <address>#

Required Starting address

-f, --file <file>#

Path to file to write

-h, --hex-string <hex_string>#

String of hex values. e.g. ‘1234’, ‘12 34’

-c, --count <count>#

Number of bytes to write

write-to-flash#

Write data to flash.

nxpdebugmbox write-to-flash [OPTIONS]

Options

-a, --address <address>#

Required Starting address

-f, --file <file>#

Required Path to file.