User Guide - nxpdebugmbox#
This user’s guide describes how to use nxpdebugmbox application.
Note
If you encounter this warning: STLink, CMSIS-DAPv2 and PicoProbe probes are not supported because no libusb library was found. It means that libusb cannot be found on your system. Libusb in PyOCD is distributed as python package libusb-package which does not have wheel distribution for Python 3.12 pyocd/libusb-package#16 (October 2024). As a workaround you might copy the libusb-1.0.dll to the root of libusb-package folder in your virtual environment e.g.: venv/Lib/site-packages/libusb_package/libusb-1.0.dll or copy it to Windows/System32/. You can get the dll here: https://libusb.info/
Command line interface#
nxpdebugmbox#
Tool for working with Debug Mailbox.
nxpdebugmbox [OPTIONS] COMMAND [ARGS]...
Options
- -f, --family <family>#
Select the chip family.
- Options:
k32w148 | kw45b41z5 | kw45b41z8 | lpc55s04 | lpc55s06 | lpc55s14 | lpc55s16 | lpc55s26 | lpc55s28 | lpc55s36 | lpc55s66 | lpc55s69 | mcxa132 | mcxa133 | mcxa142 | mcxa143 | mcxa144 | mcxa145 | mcxa146 | mcxa152 | mcxa153 | mcxa154 | mcxa155 | mcxa156 | mcxn235 | mcxn236 | mcxn546 | mcxn547 | mcxn946 | mcxn947 | mcxw716a | mcxw716c | mimx8ulp | mimx9352 | mimx9596 | mimxrt1181 | mimxrt1182 | mimxrt1187 | mimxrt1189 | mimxrt533s | mimxrt555s | mimxrt595s | mimxrt685s | mimxrt798s | nhs52s04 | rw610 | rw612
- -r, --revision <revision>#
Chip revision; if not specified, most recent one will be used
- -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.
- -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.
cmd#
Group of commands for working with raw Debug MailBox commands.
nxpdebugmbox cmd [OPTIONS] COMMAND [ARGS]...
erase#
Erase Flash.
nxpdebugmbox cmd erase [OPTIONS]
erase-one-sector#
Erase one flash sector.
nxpdebugmbox cmd erase-one-sector [OPTIONS]
Options
- -a, --address <address>#
Required Starting address
exit#
Exit DebugMailBox.
nxpdebugmbox cmd exit [OPTIONS]
famode#
Set Fault Analysis Mode.
nxpdebugmbox cmd famode [OPTIONS]
Options
- -m, --message <message>#
Path to message file.
get-crp#
Get CRP level. This command should be called after ‘start’ command and with no-reset ‘-n’ option.
nxpdebugmbox cmd get-crp [OPTIONS]
get-dac#
Perform the Start of Debug Authentication and get the DAC.
The -p option must be defined in main application.
nxpdebugmbox cmd get-dac [OPTIONS]
Options
- -o, --output <output>#
Required Path to a file, where to store the output.
- -l, --rot-hash-length <rot_hash_length>#
- The length of Root of Trust hash in Debug authentication challenge packet.There is simple key do decide:- Most device depends on used RoT keys type:– RSA (all types): 32– ECC 256: 32– ECC 384: 48– ECC 521: 66- The exceptions:– The KW45xx devices has always 32 bytes– Devices based on EdgeLock Enclave security element has 32 bytes
- Options:
32 | 48 | 66
- -x, --nxp-keys#
Use the ROM NXP keys to authenticate.
ispmode#
Enter ISP Mode.
nxpdebugmbox cmd ispmode [OPTIONS]
Options
- -m, --mode <mode>#
Required
send-dar#
Send the Debug Authentication response to device.
nxpdebugmbox cmd send-dar [OPTIONS]
Options
- -b, --binary <binary>#
Required Path to binary with DAR packet.
- -x, --nxp-keys#
Use the ROM NXP keys to authenticate.
start#
Start DebugMailBox.
nxpdebugmbox cmd start [OPTIONS]
start-debug-session#
Start debug session.
nxpdebugmbox cmd start-debug-session [OPTIONS]
token-auth#
Debug Authentication using token.
nxpdebugmbox cmd 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-to-flash#
Write data to flash.
nxpdebugmbox cmd write-to-flash [OPTIONS]
Options
- -a, --address <address>#
Required Starting address
- -f, --file <file>#
Required Path to file.
dat#
Group of commands for working with Debug Authentication Procedure.
nxpdebugmbox dat [OPTIONS] COMMAND [ARGS]...
auth#
Perform the Debug Authentication.
nxpdebugmbox dat auth [OPTIONS]
Options
- -c, --config <config>#
Path to Debug Authentication configuration file.
- -n, --no-exit#
When used, exit debug mailbox command is not executed after debug authentication.
- -a, --address <address>#
The AHB access test address, the default is 0x2000_0000, but some chips needs different.
dc#
Group of commands for Debug Credential binaries.
nxpdebugmbox dat dc [OPTIONS] COMMAND [ARGS]...
export#
Generate debug certificate (DC).
nxpdebugmbox dat dc export [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-template#
Generate the template of Debug Credentials YML configuration file.
nxpdebugmbox dat dc get-template [OPTIONS]
Options
- -o, --output <output>#
Required Path to a file, where to store the output.
- --force#
Force overwriting of existing files.
get-template#
Create template of Debug authentication configurations in YAML format.
nxpdebugmbox dat get-template [OPTIONS]
Options
- -o, --output <output>#
Required Path to a file, where to store the output.
- --force#
Force overwriting of existing files.
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-families#
Shows the full family info for commands in this group.
nxpdebugmbox famode-image get-families [OPTIONS]
Options
- -c, --cmd-name <cmd_name>#
Choose the command name to get full information about NXP families support.
- Options:
parse | get-templates
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:
k32w148 | kw45b41z5 | kw45b41z8 | mcxw716a | mcxw716c
- -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:
k32w148 | kw45b41z5 | kw45b41z8 | mcxw716a | mcxw716c
- -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.
get-families#
Shows the full family info for commands in this group.
nxpdebugmbox get-families [OPTIONS]
mem-tool#
Group of commands for working with target memory over debug probe.
nxpdebugmbox mem-tool [OPTIONS] COMMAND [ARGS]...
read-memory#
Reads the memory and writes it to the file or stdout.
nxpdebugmbox mem-tool 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
test-connection#
Method just try if the device debug port is opened or not.
nxpdebugmbox mem-tool test-connection [OPTIONS]
Options
- -a, --address <address>#
The AHB access test address, the default is 0x2000_0000, but some chips needs different.
write-memory#
Writes memory from a file or a hex-data.
nxpdebugmbox mem-tool 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
tool#
Group of commands for working with various tools over debug probe.
nxpdebugmbox tool [OPTIONS] COMMAND [ARGS]...
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 tool get-uuid [OPTIONS]
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 tool reset [OPTIONS]
Options
- -h, --hard-reset#
When used, the hardware reset is used instead of debug mailbox reset.