Debuggers API

Contents

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#
CDBGPWRUPACK = 536870912#
CDBGPWRUPREQ = 268435456#
CSYSPWRUPACK = 2147483648#
CSYSPWRUPREQ = 1073741824#
DHCSR_C_DEBUGEN = 1#
DHCSR_C_HALT = 2#
DHCSR_DEBUGKEY = 2690580480#
DHCSR_REG = 3758157296#
DP_ABORT_REG = 0#
DP_CTRL_STAT_REG = 4#
IDR_REG = 252#
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 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_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

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

NAME = 'local_help'#
clear_sticky_errors()#

Clear sticky errors of Debug port interface.

Return type:

None

get_mem_ap()#

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

Parameters:

func – Decorated function.

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

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 for DebugMailbox PyOCD Debug probes support#

Module for DebugMailbox PyOCD Debug probes support.

class spsdk.debuggers.debug_probe_pyocd.DebugProbePyOCD(hardware_id, options=None)#

Bases: DebugProbeCoreSightOnly

Class to define PyOCD package interface for NXP SPSDK.

The PyOCD class initialization.

The PyOCD initialization function for SPSDK library to support various DEBUG PROBES.

NAME = 'pyocd'#
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.

Raises:
Return type:

None

close()#

Close PyLink interface.

The PyLink closing function for SPSDK library to support various DEBUG PROBES.

Return type:

None

configure_logger(logging_level=40)#

Configure PyOCD logger.

Return type:

None

connect()#

Connect to target.

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

Raises:

SPSDKDebugProbeError – The PyOCD cannot establish communication with target

Return type:

None

coresight_reg_read(access_port=True, addr=0)#

Read coresight register over PyOCD interface.

The PyOCD read 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)

Raises:
coresight_reg_write(access_port=True, addr=0, data=0)#

Write coresight register over PyOCD interface.

The PyOCD write 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

Raises:
Return type:

None

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

Get all connected probes over PyOCD.

This functions returns the list of all connected probes in system by PyOCD package.

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:

probe_description

open()#

Open PyOCD interface for NXP SPSDK.

The PyOCD opening function for SPSDK library to support various DEBUG PROBES.

Raises:
Return type:

None

reset()#

Reset a target.

It resets a target.

Raises:

SPSDKDebugProbeError – Internal error on debug probe, detected during reset request.

Return type:

None

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.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:
spsdk.debuggers.utils.test_ahb_access(probe, ap_mem=None, invasive=True, test_mem_address=536870912)#

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