Debuggers API

Debuggers module provides wrappers for various types of debuggers.

Module for DebugMailbox Debug probes support

Module for DebugMailbox Debug probes support.

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

Bases: ABC

Abstraction class to define SPSDK debug probes interface.

This is general initialization function for SPSDK library to support various DEBUG PROBES.

Parameters:

• hardware_id (str) – Open probe with selected hardware ID

• options (Optional[dict]) – The options dictionary

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

Debug probe close.

This is general closing function for SPSDK library to support various DEBUG PROBES.

Return type:

None

abstract connect()

Debug probe connect.

General connecting function for SPSDK library to support various DEBUG PROBES. The function is used to initialize the connection to target

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

• addr (int) – the register address

Return type:

int

Returns:

The read value of addressed register (4 bytes)

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 write(default), otherwise the Debug Port

• addr (int) – the register address

• data (int) – the data to be written into register

Return type:

None

abstract debug_halt()

Halt the CPU execution.

Return type:

None

abstract debug_resume()

Resume the CPU execution.

Return type:

None

abstract debug_step()

Step the CPU execution.

Return type:

None

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

Functions returns the list of all connected probes in system.

There is option to look for just for one debug probe defined by its hardware ID.

Parameters:

• hardware_id (Optional[str]) – None to list all probes, otherwise the the only probe with matching hardware id is listed.

• options (Optional[dict]) – The options dictionary

Return type:

DebugProbes

Returns:

List of ProbeDescription

static get_coresight_ap_address(access_port, address)

Return computed address of coresight access port register.

Parameters:

• access_port (int) – Index of access port 0-255.

• address (int) – Register address.

Return type:

int

Returns:

Coresight address.

Raises:

SPSDKError – In case of invalid value.

classmethod get_options_help()

Get full list of options of debug probe.

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 is read 32-bit register in memory space of MCU function for SPSDK library to support various DEBUG PROBES.

Parameters:

addr (int) – The register address

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 is write 32-bit register in memory space of MCU function for SPSDK library to support various DEBUG PROBES.

Parameters:

• addr (int) – the register address

• data (int) – the data to be written into register

Return type:

None

abstract open()

Debug probe open.

General opening function for SPSDK library to support various DEBUG PROBES. The function is used to opening the debug probe

Return type:

None

abstract read_dp_idr()

Read Debug port identification register.

Return type:

int

reset()

Reset a target.

It resets a target.

Return type:

None

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

Bases: DebugProbe

Abstraction class to define SPSDK debug probes interface.

This is general initialization function for SPSDK library to support various DEBUG PROBES.

Parameters:

• hardware_id (str) – Open probe with selected hardware ID

• options (Optional[dict[str, str]]) – The options dictionary

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

DRW_REG = 12

NAME = 'local_help'

TAR_REG = 4

clear_sticky_errors()

Clear sticky errors of Debug port interface.

Return type:

None

debug_halt()

Halt the CPU execution.

Return type:

None

debug_resume()

Resume the CPU execution.

Return type:

None

debug_step()

Step the CPU execution.

Return type:

None

get_mem_ap()

Decorator function that secure the getting right MEM AP ix for first use.

Parameters:

func – Decorated function.

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

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.

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 is read 32-bit register in memory space of MCU function for SPSDK library to support various DEBUG PROBES.

Parameters:

addr (int) – The register address

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 is write 32-bit register in memory space of MCU function for SPSDK library to support various DEBUG PROBES.

Parameters:

• addr (int) – the register address

• data (int) – the data to be written into register

Return type:

None

power_down_target()

Power down the target for the Probe connection.

Return type:

None

power_up_target()

Power up the target for the Probe connection.

Return type:

None

read_dp_idr()

Read Debug port identification register.

Return type:

int

select_ap(addr)

Helper function to select the access port in DP.

Parameters:

addr (int) – Requested AP access address.

Return type:

None

spsdk.debuggers.debug_probe.DebugProbeLocal

alias of DebugProbeCoreSightOnly

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

Bases: list[ProbeDescription]

Helper class for debug probe selection. This class accepts only ProbeDescription object.

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

Bases: object

NamedTuple for DAT record of debug probe description.

Initialization of Debug probe description class.

param interface: Probe Interface. param hardware_id: Probe Hardware ID(Identification). param description: Probe Text description. param probe: Probe name of the class.

get_probe(options=None)

Get instance of probe.

Parameters:

options (Optional[dict]) – The dictionary with options

Return type:

DebugProbe

Returns:

Instance of described probe.

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

Bases: SPSDKError

The general issue with debug probe exception for use with SPSDK.

Initialize the base SPSDK Exception.

exception spsdk.debuggers.debug_probe.SPSDKDebugProbeNotOpenError(desc=None)

Bases: SPSDKDebugProbeError

The debug probe is not opened exception for use with SPSDK.

Initialize the base SPSDK Exception.

exception spsdk.debuggers.debug_probe.SPSDKDebugProbeTransferError(desc=None)

Bases: SPSDKDebugProbeError

The communication error exception for use with SPSDK.

Initialize the base SPSDK Exception.

exception spsdk.debuggers.debug_probe.SPSDKMultipleProbesError(desc=None)

Bases: SPSDKDebugProbeError

Multiple probes found exception for use with SPSDK.

Initialize the base SPSDK Exception.

exception spsdk.debuggers.debug_probe.SPSDKProbeNotFoundError(desc=None)

Bases: SPSDKDebugProbeError

The Probe not found exception for use with SPSDK.

Initialize the base SPSDK Exception.

Module with common utils for debuggers module

Module for DebugMailbox Debug probes support.

spsdk.debuggers.utils.get_all_debug_probe_plugins()

Get dictionary of all available debug probe types.

Return type:

dict[str, Type[DebugProbe]]

spsdk.debuggers.utils.get_connected_probes(interface=None, hardware_id=None, options=None)

Functions returns the list of all connected probes in system.

The caller could restrict the scanned interfaces by specification of hardware ID.

Parameters:

• interface (Optional[str]) – None to scan all interfaces, otherwise the selected interface is scanned only.

• hardware_id (Optional[str]) – None to list all probes, otherwise the the only probe with matching

• options (Optional[dict]) – The dictionary with optional options hardware id is listed.

Return type:

DebugProbes

Returns:

list of probe_description’s

spsdk.debuggers.utils.get_test_address(family, revision='latest')

Get AHB access test address for the device.

The address is stored in SPSDK database. I worst case that address is not found, exception is raised. :raises SPSDKError: The address is not stored in database.

Return type:

int

spsdk.debuggers.utils.load_all_probe_types()

Method to load the current list of all debug probe types.

Return type:

None

spsdk.debuggers.utils.load_debug_probe_plugins()

Load all installed signature provider plugins.

Return type:

dict[str, ModuleType]

spsdk.debuggers.utils.open_debug_probe(interface=None, serial_no=None, debug_probe_params=None, print_func=<built-in function print>, input_func=<built-in function input>)

Method opens DebugProbe object based on input arguments.

Parameters:

• interface (Optional[str]) – None to scan all interfaces, otherwise the selected interface is scanned only.

• serial_no (Optional[str]) – None to list all probes, otherwise the the only probe with matching

• debug_probe_params (Optional[dict]) – The dictionary with optional options hardware id is listed.

• print_func (Callable[[str], None]) – Custom function to print data, defaults to print

• input_func (Callable[[], str]) – Custom function to handle user input, defaults to input

Return type:

Iterator[DebugProbe]

Returns:

Active DebugProbe object.

Raises:

SPSDKError – Raised with any kind of problems with debug probe.

spsdk.debuggers.utils.select_probe(probes, silent=False, print_func=<built-in function print>, input_func=<built-in function input>)

Perform Probe selection.

Parameters:

• probes (DebugProbes) – The input list of probes

• silent (bool) – When it True, the functions select the probe if applicable without any prints to log

• print_func (Callable) – Custom function to print data, defaults to print

• input_func (Callable[[], str]) – Custom function to handle user input, defaults to input

Return type:

ProbeDescription

Returns:

The record of selected DebugProbe

Raises:

• SPSDKProbeNotFoundError – No probe has been founded

• SPSDKMultipleProbesError – Multiple probes have been found in non-interactive mode

spsdk.debuggers.utils.test_ahb_access(probe, ap_mem=None, invasive=True, test_mem_address=None)

The function safely test the access of debug probe to AHB in target.

Parameters:

• probe (DebugProbe) – Probe object to use for test.

• ap_mem (Optional[int]) – Index of memory access port, defaults to 0

• invasive (bool) – Invasive type of test (temporary changed destination RAM value)

• test_mem_address (Optional[int]) – The address in volatile memory usable to test AHB memory access.

Return type:

bool

Returns:

True is access to AHB is granted, False otherwise.

Additional debuggers

SPSDK does have a plugin system in place to support additional debuggers. There are couple of plugins provided by NXP which you may find here: nxp-mcuxpresso/spsdk_plugins

If you want to add support for a different debugger, you may create a Python module by using Cookiecutter template in examples/plugins/templates/cookiecutter-spsdk-debug-probe-plugin.zip