Debuggers API

Debuggers API#

SPSDK debugger interface wrappers.

This module provides unified wrappers for various types of debuggers used in SPSDK for device communication and debugging operations across NXP MCU portfolio.

Module for DebugMailbox Debug probes support#

SPSDK debug probe interface and management utilities.

This module provides abstract base classes and concrete implementations for debug probe communication, supporting various debug interfaces across NXP MCU portfolio. It includes probe discovery, connection management, and CoreSight debug operations.

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.

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#

APADDR = 16777215#

APBANKSEL = 240#

APBANK_SHIFT = 4#

APSEL = 4278190080#

APSEL_APBANKSEL = 4278190320#

APSEL_SHIFT = 24#

AP_IDR_REG = 252#

CDBGPWRUPACK = 536870912#

CDBGPWRUPREQ = 268435456#

CSYSPWRUPACK = 2147483648#

CSYSPWRUPREQ = 1073741824#

DHCSR_C_DEBUGEN = 1#

DHCSR_C_HALT = 2#

DHCSR_C_STEP = 4#

DHCSR_DEBUGKEY = 2690580480#

DHCSR_REG = 3758157296#

DP_ABORT_REG = 0#

DP_CTRL_STAT_REG = 4#

DP_IDR_REG = 0#

MASKLANE = 3840#

NAME = 'Abstract'#

RESET_TIME = 0.1#

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 coresight_reg_read(access_port=True, addr=0)#

Read coresight register.

It reads coresight register function for SPSDK library to support various DEBUG PROBES.

Parameters:

access_port (bool) – if True, the Access Port (AP) register will be read (default), otherwise the Debug Port (DP) register will be read.
addr (int) – the register address.

Return type:

int

Returns:

The read value of addressed register (4 bytes).

abstract coresight_reg_read_safe(access_port=True, addr=0, max_retries=3)#

Safe coresight register read with error handling and recovery.

Performs a safe read operation on CoreSight registers with automatic retry mechanism in case of transfer failures.

Parameters:

access_port (bool) – If True, reads Access Port (AP) register, otherwise reads Debug Port (DP) register.
addr (int) – Register address to read from.
max_retries (int) – Maximum number of retry attempts on failure.

Return type:

int

Returns:

Read value of the addressed register (4 bytes).

Raises:

SPSDKDebugProbeTransferError – If all retry attempts fail.

abstract coresight_reg_write(access_port=True, addr=0, data=0)#

Write coresight register.

It writes coresight register function for SPSDK library to support various DEBUG PROBES.

Parameters:

access_port (bool) – if True, the Access Port (AP) register will be written (default), otherwise the Debug Port register will be written.
addr (int) – the register address.
data (int) – the data to be written into register.

Return type:

None

abstract coresight_reg_write_safe(access_port=True, addr=0, data=0, max_retries=3)#

Write CoreSight register with error handling and recovery.

Internal method that performs CoreSight register write operations with automatic retry mechanism and error recovery capabilities.

Parameters:

access_port (bool) – If True, writes to Access Port (AP) register, otherwise to Debug Port (DP).
addr (int) – Register address to write to.
data (int) – Data value to write into the register.
max_retries (int) – Maximum number of retry attempts on failure.

Raises:

SPSDKDebugProbeTransferError – If all retry attempts fail.

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.

static get_coresight_ap_address(access_port, address)#

Compute the coresight access port register address.

The method combines the access port index with the register address using bit shifting to create the final coresight address for debug operations.

Parameters:

access_port (int) – Index of access port (0-255).
address (int) – Register address offset.

Return type:

int

Returns:

Computed coresight address.

Raises:

SPSDKValueError – If access port index exceeds 255.

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.

abstract mem_block_read(addr, size)#

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.

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)#

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.

Raises:

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

Return type:

None

abstract mem_reg_read(addr=0)#

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.
Return type:: int
Returns:: The read value of addressed register (4 bytes).

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

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.

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.DebugProbeCoreSightOnly(hardware_id, options=None)#

Bases: DebugProbe

SPSDK Debug Probe with CoreSight-only interface support.

This class provides a specialized debug probe implementation that focuses exclusively on CoreSight debug architecture operations. It extends the base DebugProbe class with ARM CoreSight-specific register definitions and memory access patterns for debugging ARM Cortex-based MCUs.

Variables:

NAME – Debug probe identifier name.
CSW_SIZE_8BIT – Control/Status Word 8-bit transfer size configuration.
CSW_SIZE_16BIT – Control/Status Word 16-bit transfer size configuration.
CSW_SIZE_32BIT – Control/Status Word 32-bit transfer size configuration.
CSW_ADDRINC_OFF – Control/Status Word no address increment mode.
CSW_ADDRINC_SINGLE – Control/Status Word single address increment mode.
CSW_ADDRINC_PACKED – Control/Status Word packed address increment mode.
CSW_DEVICEEN – Control/Status Word device enable flag.
CSW_TRINPROG – Control/Status Word transfer in progress flag.
CSW_HPROT – Control/Status Word HPROT signal configuration.
CSW_MASTER_DEBUG – Control/Status Word master debug enable flag.
CSW_DBGSWENABLE – Control/Status Word debug software enable flag.
CSW_FULL_DEBUG – Combined CSW configuration for full debug capabilities.
CSW_REG – CoreSight Control/Status Word register address.
TAR_REG – CoreSight Transfer Address register address.
DRW_REG – CoreSight Data Read/Write register address.
DP_CTRL_STAT_ERROR_MASK – Combined error mask for Debug Port status flags.

Initialize debug probe with hardware ID and options.

General initialization function for SPSDK library to support various debug probes.

Parameters:

hardware_id (str) – Hardware ID of the debug probe to open
options (Optional[dict[str, str]]) – Optional dictionary with probe-specific configuration options

CSW_ADDRINC_OFF = 0#

CSW_ADDRINC_PACKED = 32#

CSW_ADDRINC_SINGLE = 16#

CSW_DBGSWENABLE = 2147483648#

CSW_DEVICEEN = 64#

CSW_FULL_DEBUG = 2717909074#

CSW_HPROT = 33554432#

CSW_MASTER_DEBUG = 536870912#

CSW_REG = 0#

CSW_SIZE_16BIT = 1#

CSW_SIZE_32BIT = 2#

CSW_SIZE_8BIT = 0#

CSW_TRINPROG = 128#

DP_CTRL_STAT_ERROR_MASK = 178#

DP_CTRL_STAT_READOK = 64#

DP_CTRL_STAT_STICKYCMP = 16#

DP_CTRL_STAT_STICKYERR = 32#

DP_CTRL_STAT_STICKYORUN = 2#

DP_CTRL_STAT_WDATAERR = 128#

DRW_REG = 12#

NAME = 'local_help'#

TAR_REG = 4#

clear_sticky_errors()#

Clear sticky errors of Debug port interface.

This method reads the debug port control/status register to check for sticky errors and clears them if found. For JTAG interface, it performs an additional write operation. The method handles communication failures gracefully by attempting recovery.

Raises:: SPSDKDebugProbeTransferError – When debug probe communication cannot be reestablished.
Return type:: None

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 attempts recovery if the initial connection fails.

Raises:: Exception – Re-raises the original connection exception if recovery fails.
Return type:: None

coresight_reg_read_safe(access_port=True, addr=0, max_retries=3)#

Safe coresight register read with error handling and recovery.

This method attempts to read a CoreSight register with automatic retry and recovery mechanisms. If a read fails, it will attempt to recover the debug connection and retry the operation up to the specified maximum number of attempts.

Parameters:

access_port (bool) – If True, reads Access Port (AP) register, otherwise Debug Port (DP).
addr (int) – The register address to read from.
max_retries (int) – Maximum number of retry attempts before giving up.

Return type:

int

Returns:

The read value of addressed register (4 bytes).

Raises:

SPSDKDebugProbeTransferError – If all retry attempts fail.

coresight_reg_write_safe(access_port=True, addr=0, data=0, max_retries=3)#

Write CoreSight register with automatic retry and error recovery.

Performs a CoreSight register write operation with built-in error handling and automatic recovery attempts. If the initial write fails, the method attempts to recover the debug connection and retry the operation up to the specified maximum number of attempts.

Parameters:

access_port (bool) – If True, writes to Access Port register, otherwise Debug Port register
addr (int) – Register address to write to
data (int) – Data value to write into the register
max_retries (int) – Maximum number of retry attempts before giving up

Raises:

SPSDKDebugProbeTransferError – If all retry attempts fail

Return type:

None

debug_halt()#

Halt the CPU execution.

This method stops the CPU by writing to the Debug Halting Control and Status Register (DHCSR) with the appropriate debug key, halt, and debug enable flags.

Raises:: SPSDKError – If the memory register write operation fails.
Return type:: None

debug_resume()#

Resume the CPU execution.

This method clears the debug halt bit in the Debug Halting Control and Status Register (DHCSR) to allow the CPU to continue execution from its current state.

Raises:: SPSDKError – If the memory register write operation fails.
Return type:: None

debug_step()#

Step the CPU execution by one instruction.

This method performs a single-step operation on the target CPU by writing to the Debug Halting Control and Status Register (DHCSR) with appropriate control bits to enable debug mode and execute one instruction.

Raises:: SPSDKError – If the memory register write operation fails.
Return type:: None

get_mem_ap()#

Decorator that ensures correct Memory Access Port index is found before first use.

This decorator automatically discovers and configures the appropriate Memory Access Port (MEM AP) by testing possible AP indices and validating memory access functionality. It performs CoreSight AP identification, enters debug state, tests memory access, and restores the original state.

Parameters:: func – The function to be decorated that requires MEM AP access.
Returns:: Decorated function wrapper.
Raises:: SPSDKDebugProbeError – When no valid memory access port is found.

mem_block_read(addr, size)#

Read a block of memory from the MCU, handling non-aligned addresses and sizes.

This method implements a chunked reading approach to overcome the 1KB auto-increment limitation of the ARM Cortex Debug Access Port (DAP). The method handles memory alignment automatically and reads data in 1KB chunks to ensure reliable operation.

Parameters:

addr (int) – The starting memory address to read from.
size (int) – The number of bytes to read from memory.

Return type:

bytes

Returns:

The read data as a bytes object.

mem_block_write(addr, data)#

Write a block of memory to the MCU, handling unaligned addresses and sizes.

This method implements a three-stage writing approach: 1. Handles initial unaligned bytes using 8-bit writes. 2. Performs bulk 32-bit aligned writes for the main data block. 3. Handles any remaining bytes using 8-bit writes. This approach ensures efficient writing for aligned data while correctly handling unaligned start and end addresses.

Parameters:

addr (int) – The starting address to write to.
data (bytes) – The data to be written, as a bytes object.

Raises:

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

Return type:

None

mem_reg_read(addr=0)#

Read 32-bit register in memory space of MCU.

This method reads a 32-bit register from the memory space of the connected MCU using the configured debug probe interface.

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

mem_reg_write(addr=0, data=0)#

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 using the configured memory access port.

Parameters:

addr (int) – The register address to write to.
data (int) – The 32-bit data value to be written into the register.

Return type:

None

power_down_target()#

Power down the target for the Probe connection.

This method performs a two-step power down sequence: first disabling system power while maintaining debug power, then disabling debug power completely to ensure proper target shutdown.

Return type:: None

power_up_target()#

Power up the target for the Probe connection.

This method enables both system and debug power to establish a proper connection with the target device through the debug probe.

Raises:: SPSDKError – If power control operation fails.
Return type:: None

read_dp_idr()#

Read Debug port identification register.

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

recover_debug_connection()#

Recover debug connection using progressive recovery strategy.

Implements ARM CoreSight best practices by attempting multiple recovery levels in sequence: soft recovery, power cycle recovery, probe reconnect recovery, and hard reset recovery. Each level is progressively more invasive.

Return type:: bool
Returns:: True if recovery successful, False otherwise.

select_ap(addr)#

Select the access port in Debug Port (DP).

This method configures the Debug Port to access a specific Access Port by writing to the SELECT register. It includes caching optimization to avoid redundant writes when the same AP is already selected.

Parameters:: addr (int) – Requested AP access address containing AP selection and bank information.
Return type:: None

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

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.