Debuggers API

Debuggers API#

Architecture overview#

The spsdk.debuggers package provides a hardware-independent debug-probe abstraction that is used by the rest of SPSDK to communicate with NXP target devices. The application code always calls the same API — open a probe, read or write memory, exchange debug-mailbox commands — and the concrete probe implementation handles all low-level protocol details.

A debug probe is any physical adapter that connects a host PC to a target chip’s debug port. SPSDK represents this concept with the abstract base class DebugProbe. All higher-level features (firmware signing, secure provisioning, fuse programming, authenticated debug) are built on top of this single interface.

Two chip architectures are supported natively; each requires a completely different low-level protocol.

ARM CoreSight probes#

All NXP Cortex-M devices (LPC55, MCX, i.MX RT, MIMXRT, …) implement the ARM CoreSight debug architecture. The debug port (DP) is exposed over SWD (two-wire) or JTAG (four-wire) and acts as a gateway to a chain of Access Ports (APs).

Two APs are relevant for SPSDK:

MEM-AP (AHB-AP / AXI-AP)

Provides 32-bit read/write access to every address on the chip’s AHB or AXI bus fabric — SRAM, flash, and peripheral registers. SPSDK automatically locates the correct MEM-AP index for each device from the device database, and configures the CSW (Control/Status Word) to match the hardware capabilities of the specific part (including a preserve_csw_ro_bits flag needed for some MCX variants that have hardware-managed CSW bits).

Debug Mailbox AP

An NXP-proprietary AP implemented on LPC, MCX, and related families. It provides a command/response channel used to:

Inject a debug credential certificate signed with the device’s debug-authentication key, enabling fully authenticated debug on RoT-locked production parts.
Trigger an ISP mode entry without physical reset pins.
Initiate a device-level reset independently of the power rail.

SPSDK auto-detects the Debug Mailbox AP by scanning the AP IDR chain at connection time.

The ARM implementation also handles the complete debug port power-up / power-down lifecycle and implements four progressive sticky-error recovery levels — ranging from a soft ABORT to a full hardware reset — so that transient bus faults do not permanently stall provisioning scripts.

ARM access is handled by DebugProbeCoreSightOnly. Only MemorySpace.DATA is valid; passing MemorySpace.PROGRAM raises SPSDKError immediately.

DSC56800EX probes#

NXP’s Digital Signal Controller (DSC) family (MC56F8xx, MC56F81xx, …) is built around the DSC56800EX core — a Harvard-architecture dual-MAC DSP with an on-chip debug engine called OnCE (On-Chip Emulation), accessed over JTAG.

The key difference from ARM is the dual memory bus (Harvard) architecture:

X: DATA bus

Holds variables, stack, and peripheral registers. Accesses are made using OnCE’s DMOVX instruction, which performs a direct load/store to an absolute X: address. Both 16-bit and 32-bit (two consecutive 16-bit) transfers are supported.

P: PROGRAM bus

Holds executable code and constants stored in program flash. The P: bus is not reachable via the same DMOVX path used for X: space — the same numerical address refers to a completely different physical location. To access P: memory, OnCE requires a dedicated sequence:

Load the P: target address into core register R3 using a move.l #addr, R3 instruction (three 16-bit words: opcode 0xE41B followed by the high and low 16-bit halves of the address).
Execute a move.w P:(R3), Y0 or move.w Y0, P:(R3) to read or write the P: word through the program bus.

This sequence is generated automatically by DebugProbeDsc; callers simply pass space=MemorySpace.PROGRAM.

Warning

Verifying freshly-programmed DSC flash by reading back using X: (DATA) addresses always returns data from a different memory than was just written. Always use MemorySpace.PROGRAM for P: flash readback.

DSC devices may appear in JTAG TAP chains alongside other TAPs (e.g. an ARM companion core or an on-board FPGA). The TapConfig dataclass captures the IR/DR lengths, IDCODE, and the TAP-selection IR value. The device database (database.yaml per chip) stores these values so no manual JTAG configuration is needed.

Memory space selection#

The space parameter on every memory method accepts a MemorySpace value:

`MemorySpace`	ARM	DSC
`DATA` (default)	AHB/AXI via MEM-AP	OnCE `DMOVX` direct X: access; 16- and 32-bit word transfers
`PROGRAM`	raises `SPSDKError`	OnCE R3-indirect P: sequence; 16-bit word transfers only

Plugin architecture#

Physical probe drivers (J-Link, PyOCD, PE Micro, Lauterbach, MCU-Link) are distributed as optional plugin packages so that the SPSDK base installation stays lean. Each plugin:

Derives from DebugProbeCoreSightOnly (ARM targets) or DebugProbeDsc (DSC targets).
Sets NAME and ARCHITECTURE class variables ("arm_cortex" or "dsc56800ex").)
Registers itself via the spsdk.debug_probe setuptools entry-point.

At run time, get_connected_probes() iterates all registered entry-points, instantiates each probe class, and filters by ARCHITECTURE when the caller requests a specific architecture.

NXP-maintained plugin packages are available at nxp-mcuxpresso/spsdk_plugins

To create a custom probe plugin use the Cookiecutter template at examples/plugins/templates/cookiecutter-spsdk-debug-probe-plugin.zip.

API Reference#

Package#

SPSDK debugger interface wrappers.

Overview#

SPSDK communicates with NXP target devices through debug probes — physical hardware adapters that connect a host PC to the chip’s debug port (SWD or JTAG). This package provides a hardware-independent abstraction layer so that the rest of SPSDK never has to care which physical probe is plugged in or which architecture is being debugged.

Architecture support#

Two fundamentally different architectures are supported, each requiring a different low-level protocol:

ARM Cortex-M / CoreSight (module spsdk.debuggers.debug_probe_arm): NXP’s mainstream Cortex-M portfolio (LPC, MCX, i.MX RT, …) exposes the standard ARM CoreSight debug architecture over SWD or JTAG. Access to the CPU and its tightly-coupled memory is made through a chain of Access Ports (APs): a MEM-AP provides 32-bit load/store access to the AHB/AXI bus fabric, and an optional Debug Mailbox AP enables secure debug credential injection and RoT-authenticated debug sessions.
DSC56800EX (module spsdk.debuggers.debug_probe_dsc): NXP’s Digital Signal Controller (DSC) family uses an entirely different on-chip debug engine called OnCE (On-Chip Emulation) accessed over JTAG. The DSC Harvard architecture exposes two separate memory buses — the X: DATA bus for operand data and the P: PROGRAM bus for instruction words. Reading or writing program-space flash/RAM requires explicit P: addressing; naive DATA-space reads would return garbage from the wrong address space. MemorySpace selects which bus to use on every memory operation.

Plugin system#

Physical probe support (J-Link, PyOCD, PE Micro, Lauterbach, MCU-Link) is deliberately kept outside the SPSDK core as optional packages so that the base installation stays lean. Each plugin registers itself via the spsdk.debug_probe setuptools entry-point and is auto-discovered at run time. Custom probes can be created by deriving from DebugProbeCoreSightOnly (for ARM targets) or DebugProbeDsc (for DSC targets) and distributing a package with the appropriate entry-point metadata. See examples/plugins/README.md for a step-by-step guide and Cookiecutter templates.

Base interface and infrastructure#

SPSDK debug probe base interface and infrastructure.

This module is the foundation of the SPSDK debug-probe subsystem. It defines the contracts (abstract base class, exceptions, enumerations) that every concrete probe implementation must fulfil, plus the ProbeDescription / DebugProbes helpers used for probe discovery and selection.

Design goals#

Hardware independence — the rest of SPSDK calls only the API defined in DebugProbe. Switching from J-Link to PyOCD to a custom probe requires zero changes in application code.
Architecture independence — a single space parameter on every memory method (MemorySpace) makes ARM and DSC targets look identical to the caller. The concrete implementation decides how to honour a PROGRAM-space request.
Plugin-friendly — new probe hardware can be added as an installable Python package without touching the SPSDK core.

Class hierarchy#

DebugProbe  (ABC — this module)
├── DebugProbeCoreSightOnly   (spsdk.debuggers.debug_probe_arm)
│     ARM CoreSight / SWD / JTAG; MEM-AP, debug mailbox AP
└── DebugProbeDsc             (spsdk.debuggers.debug_probe_dsc)
      DSC56800EX OnCE; DATA bus and PROGRAM bus

Memory spaces#

MemorySpace reflects the hardware reality of the DSC Harvard architecture:

MemorySpace.DATA: The default. Accesses the X: data bus (DSC) or the normal AHB/AXI fabric (ARM). Supports 16- and 32-bit word transfers.
MemorySpace.PROGRAM: DSC P: program bus only. Because the P: bus is instruction-addressed, the DSC OnCE engine must use an R3-register-indirect move sequence to reach it — a detail hidden inside DebugProbeDsc. Passing MemorySpace.PROGRAM to an ARM probe raises SPSDKError immediately, making unintended cross-architecture use a hard error rather than silent data corruption.

Concrete implementations live in separate modules; import them directly from their home module:

spsdk.debuggers.debug_probe_arm — ARM CoreSight (DebugProbeCoreSightOnly)
spsdk.debuggers.debug_probe_dsc — DSC56800EX (DebugProbeDsc, TapConfig)

class spsdk.debuggers.debug_probe.DebugProbe(hardware_id, options=None)#

Bases: ABC

Abstract base class for SPSDK debug probe interfaces.

This class defines the common interface and constants for all debug probes supported by SPSDK, providing standardized access to target devices through various debug probe hardware implementations.

Variables:

NAME – Debug probe implementation name identifier.
APBANKSEL – Access Port bank selection mask for debug mailbox detection.
DP_IDR_REG – Debug Port Identification Register address.
DP_CTRL_STAT_REG – Debug Port Control/Status Register address.
DHCSR_REG – Debug Halting Control and Status Register address.
DHCSR_DEBUGKEY – Debug key value for DHCSR register access.
ARCHITECTURE – DB architecture identifier for this probe family. "abstract" means no restriction — the probe works with any architecture.

Initialize debug probe with hardware ID and configuration options.

This is general initialization function for SPSDK library to support various DEBUG PROBES. Sets up the probe connection parameters, family configuration, and memory access point index.

Parameters:

hardware_id (str) – Hardware identifier to open specific debug probe
options (Optional[dict]) – Configuration dictionary containing family, revision and other probe settings

AFTER_RESET_TIME = 0.05#

ARCHITECTURE = 'abstract'#

DEBUG_ACCESS_STATUS_LABELS: dict[str, str] = {'dp_idr_ok': 'Debug Port IDR readable (target chip responds on the debug port)', 'probe_connected': 'Probe attached to target (debug probe is correctly connected to the board via SWD/JTAG)', 'probe_opened': 'Debug probe opened (PC is correctly connected to the debug probe hardware)'}#

NAME = 'abstract'#

RESET_TIME = 0.1#

SUPPORTED_PROTOCOLS: tuple[DebugProbeProtocol, ...] = ()#

abstract assert_reset_line(assert_reset=False)#

Control reset line at a target.

Parameters:: assert_reset (bool) – If True, the reset line is asserted (pulled down), if False the reset line is not affected.
Return type:: None

abstract close()#

Close the debug probe connection.

This method provides a unified interface for closing debug probe connections across different debug probe implementations in the SPSDK library.

Return type:: None

abstract connect()#

Connect to the debug probe.

Initializes the connection to the target device through the debug probe. This is a general connecting function that supports various debug probe types across the SPSDK library.

Raises:

SPSDKError – If the connection to the debug probe fails.
SPSDKTimeoutError – If the connection attempt times out.

Return type:

None

abstract connect_safe()#

Debug probe connect in safe manner.

General connecting function for SPSDK library to support various DEBUG PROBES. The function is used to initialize the connection to target and establishes communication with the debug probe hardware.

Raises:

SPSDKError – When connection to debug probe fails.
SPSDKTimeoutError – When connection timeout occurs.

Return type:

None

abstract dbgmlbx_reg_read(addr=0)#

Read debug mailbox access port register.

This function reads a debug mailbox register through the debug probe interface to support various debug probes in the SPSDK library.

Parameters:: addr (int) – The register address to read from.
Return type:: int
Returns:: The read value of addressed register (4 bytes).

abstract dbgmlbx_reg_write(addr=0, data=0)#

Write debug mailbox access port register.

Writes data to a specified register address in the debug mailbox access port using the configured debug probe’s CoreSight interface.

Parameters:

addr (int) – Register address to write to.
data (int) – Data value to write into the register.

Return type:

None

abstract debug_halt()#

Halt the CPU execution.

This method stops the target CPU from executing instructions, putting it into a halted state for debugging purposes.

Raises:: SPSDKError – If the halt operation fails or the debug probe is not connected.
Return type:: None

abstract debug_resume()#

Resume the CPU execution.

This method continues the execution of the target CPU from its current state, typically used after the CPU has been halted or paused during debugging operations.

Raises:: SPSDKError – If the debug probe communication fails or the target is not connected.
Return type:: None

abstract debug_step()#

Step the CPU execution by one instruction.

This method advances the CPU execution by a single instruction step, allowing for detailed debugging and program flow analysis.

Raises:

SPSDKError – When the debug step operation fails.
SPSDKConnectionError – When the debug probe connection is lost.

Return type:

None

abstract classmethod get_connected_probes(hardware_id=None, options=None)#

Get connected debug probes in the system.

Retrieves a list of all connected debug probes, with an option to filter by hardware ID.

Parameters:

hardware_id (Optional[str]) – Hardware ID to filter for specific probe, None to list all probes.
options (Optional[dict]) – Additional options for probe discovery.

Return type:

DebugProbes

Returns:

Collection of connected debug probes.

get_never_tested_debug_access_gates()#

Get gate keys that will never be exercised due to a device-database shortcut.

Some gates could be tested in principle, but a device-database configuration shortcut (e.g. a fixed MEM-AP index skipping the AP-scan loop on DebugProbeCoreSightOnly) means the corresponding code path is never exercised for this family. Such gates are still shown in the diagnostic table (unlike get_not_applicable_debug_access_gates()), but rendered as “N/A” instead of “NOT TESTED” to avoid implying a real test was skipped or failed. Subclasses override this to compute the actual set from the device database.

Return type:: set[str]
Returns:: Set of gate keys to render as N/A. Empty for the base (architecture with no such shortcuts).

get_not_applicable_debug_access_gates()#

Get gate keys that can never apply to this probe/family combination.

Some gates in DEBUG_ACCESS_STATUS_LABELS are mutually exclusive at the device-database level (e.g. the SDA-AP secure-debug-unlock gate only applies to families with dat.sub_features: [sda], while the Debug Mailbox AP gate only applies to families with dat.dmbox_ap_ix set — no family currently has both). Such gates would otherwise always render as a misleading “NOT TESTED” even though they are, by design, never exercised for this particular chip. Subclasses (e.g. DebugProbeCoreSightOnly) override this to compute the actual set from the device database.

Return type:: set[str]
Returns:: Set of gate keys to omit entirely from the rendered diagnostic table for this probe instance. Empty for the base (architecture with no such mutually-exclusive gates).

classmethod get_options_help()#

Get full list of options of debug probe.

The method returns a dictionary containing all available configuration options for the debug probe with their corresponding help descriptions.

Return type:: dict[str, str]
Returns:: Dictionary with individual options. Key is parameter name and value the help text.

classmethod get_requested_protocol(options=None, default_protocol=False)#

Get generic debug probe protocol option.

Parameters:

options (Optional[dict]) – Optional debug probe options.
default_protocol (bool) – Return first supported protocol if protocol is not specified.

Return type:

DebugProbeProtocol | None

Returns:

Debug probe protocol or None if it was not specified.

Raises:

SPSDKDebugProbeError – Invalid debug probe protocol has been specified.

abstract is_cpu_halted()#

Check if the CPU is currently halted.

This method queries the hardware state directly without caching.

Return type:: bool
Returns:: True if CPU is halted, False if CPU is running.
Raises:: SPSDKDebugProbeError – If the check operation fails.

abstract mem_block_read(addr, size, space=MemorySpace(tag=0, label='data', description='Data memory bus (X: space) — default, 16/32-bit word access'))#

Read a block of memory from the MCU.

This method handles non-aligned addresses and sizes, providing flexibility for various memory operations.

Parameters:

addr (int) – The starting address to read from.
size (int) – The number of bytes to read.
space (MemorySpace) – Memory space selector. Defaults to DATA. PROGRAM is only valid for DSC architecture probes; ARM probes raise SPSDKError for non-DATA spaces.

Return type:

bytes

Returns:

The read data as a bytes object.

Raises:

SPSDKDebugProbeError – If there’s an error during the read operation.

abstract mem_block_write(addr, data, space=MemorySpace(tag=0, label='data', description='Data memory bus (X: space) — default, 16/32-bit word access'))#

Write a block of memory to the MCU.

This method handles non-aligned addresses and sizes, allowing for flexible memory write operations.

Parameters:

addr (int) – The starting address to write to.
data (bytes) – The data to be written, as a bytes object.
space (MemorySpace) – Memory space selector. Defaults to DATA. PROGRAM is only valid for DSC architecture probes; ARM probes raise SPSDKError for non-DATA spaces.

Raises:

SPSDKDebugProbeError – If there’s an error during the write operation.

Return type:

None

abstract mem_reg_read(addr=0, space=MemorySpace(tag=0, label='data', description='Data memory bus (X: space) — default, 16/32-bit word access'))#

Read 32-bit register in memory space of MCU.

This method reads a 32-bit register from the memory space of the target MCU through the debug probe interface.

Parameters:

addr (int) – The register address to read from.
space (MemorySpace) – Memory space selector. Defaults to DATA. PROGRAM is only valid for DSC architecture probes; ARM probes raise SPSDKError for non-DATA spaces.

Return type:

int

Returns:

The read value of addressed register (4 bytes).

abstract mem_reg_write(addr=0, data=0, space=MemorySpace(tag=0, label='data', description='Data memory bus (X: space) — default, 16/32-bit word access'))#

Write 32-bit register in memory space of MCU.

This method writes a 32-bit value to a specified register address in the MCU’s memory space through the debug probe interface.

Parameters:

addr (int) – The register address to write to.
data (int) – The 32-bit data value to be written into the register.
space (MemorySpace) – Memory space selector. Defaults to DATA. PROGRAM is only valid for DSC architecture probes; ARM probes raise SPSDKError for non-DATA spaces.

Return type:

None

abstract open()#

Open debug probe connection.

Establishes connection to the debug probe hardware, initializing communication interface and preparing the probe for debugging operations.

Raises:: SPSDKError – When debug probe connection fails or probe is not available.
Return type:: None

abstract read_dp_idr()#

Read Debug port identification register.

Return type:: int
Returns:: Debug port identification register value.

reset()#

Reset the target device.

Performs a hardware reset by asserting the reset line, waiting for the reset duration, then deasserting the reset line and waiting for the post-reset stabilization period.

Return type:: None

class spsdk.debuggers.debug_probe.DebugProbeProtocol(tag, label, description=None)#

Bases: SpsdkEnum

Debug probe physical protocol selector.

JTAG = (1, 'jtag', 'JTAG protocol')#

ONCE = (2, 'once', 'On-Chip Emulation protocol')#

SWD = (0, 'swd', 'Serial Wire Debug protocol')#

class spsdk.debuggers.debug_probe.DebugProbes(iterable=(), /)#

Bases: list[ProbeDescription]

Debug probe collection for hardware selection and display.

This class extends a list to specifically manage ProbeDescription objects, providing formatted output capabilities for debug probe selection interfaces. The class ensures type safety by accepting only ProbeDescription instances and offers colored table representation for user-friendly probe listing.

class spsdk.debuggers.debug_probe.MemorySpace(tag, label, description=None)#

Bases: SpsdkEnum

Memory space selector for debug probe memory access operations.

DSC56800EX architecture has two separate memory buses. DATA bus supports 16-bit and 32-bit word access via absolute addressing. PROGRAM bus supports only 16-bit word access via R3-register-indirect addressing. For non-DSC (e.g. ARM) probes only DATA is valid; passing PROGRAM raises SPSDKError.

DATA = (0, 'data', 'Data memory bus (X: space) — default, 16/32-bit word access')#

PROGRAM = (1, 'program', 'Program memory bus (P: space, DSC only) — 16-bit word access only')#

class spsdk.debuggers.debug_probe.ProbeDescription(interface, hardware_id, description, probe)#

Bases: object

Debug probe description container.

This class encapsulates information about a debug probe including its interface, hardware identification, description, and the probe class type. It provides a standardized way to describe and instantiate debug probes within the SPSDK framework.

Initialize Debug probe description class.

Parameters:

interface (str) – Probe interface type.
hardware_id (str) – Probe hardware ID for identification.
description (str) – Text description of the probe.
probe (type[DebugProbe]) – Debug probe class type.

property architecture: str#

Return the probe’s architecture identifier string.

Returns:: The ARCHITECTURE class variable of the underlying probe class.

get_probe(options=None)#

Get instance of debug probe.

Creates and returns a new instance of the debug probe with the specified hardware ID and optional configuration parameters.

Parameters:: options (Optional[dict]) – Optional dictionary containing probe-specific configuration options.
Return type:: DebugProbe
Returns:: Instance of the debug probe ready for use.

exception spsdk.debuggers.debug_probe.SPSDKDebugProbeError(desc=None)#

Bases: SPSDKError

SPSDK Debug Probe exception for debug probe related errors.

This exception is raised when debug probe operations fail or encounter errors during communication, initialization, or other debug probe specific operations within the SPSDK framework.