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.

Options: pyocd | jlink | pemicro

-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 commandsAvailable options are: 1.0, 1.1, 2.0, 2.1, 2.2

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

[jlink]:

[frequency]: Set the communication frequency in KHz, default is 100KHz

[pemicro]:

[frequency]: Set the communication frequency in Hz, default is 100_000Hz

--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.

auth

Perform the Debug Authentication.

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

nxpdebugmbox auth [OPTIONS]

Options

-b, --beacon <beacon>: 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.

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.

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: mx8ulp | rt5xx | kw45xx | lpc550x | lpc551x | lpc55s0x | lpc55s1x | lpc55s6x | mcxn9xx | lpc55s3x | k32w1xx | mx95 | rw61x | lpc55s2x | rt118x | mx93 | rt6xx | lpc552x

-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]

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.