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: object

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
DP_ABORT_REG = 0
DP_CTRL_STAT_REG = 4
IDR_REG = 252
MASKLANE = 3840
RESET_TIME = 0.1
TEST_MEM_AP_ADDRESS = 536903680
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

NotImplementedError – Derived class has to implement this method

Return type

None

clear_sticky_errors()

Clear sticky errors of Debug port interface.

Return type

None

close()

Debug probe close.

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

Raises

NotImplementedError – Derived class has to implement this method

Return type

None

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)

Raises

NotImplementedError – Derived class has to implement this method

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

Raises

NotImplementedError – Derived class has to implement this method

Return type

None

get_ap_list(ap_filter=None)

Gets the dictionary of AP IDR’s active in target.

Parameters

ap_filter (Optional[List[int]]) – List of AP be scanned - otherwise all range will be used[0-255].

Return type

Dict[int, int]

Returns

Dictionary with active AP’s. Key is index of AP, value is IDR value.

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

list

Returns

ProbeDescription

Raises

NotImplementedError – Derived class has to implement this method

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

get_mem_ap()

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

Parameters

func – Decorated function.

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

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

Raises

SPSDKDebugProbeTransferError – Error occur during memory transfer.

Return type

None

open()

Debug probe open.

General opening function for SPSDK library to support various DEBUG PROBES. The function is used to initialize the connection to target and enable using debug probe for DAT purposes.

Raises

NotImplementedError – Derived class has to implement this method

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

reset()

Reset a target.

It resets a target.

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

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

Bases: spsdk.exceptions.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: spsdk.debuggers.debug_probe.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: spsdk.debuggers.debug_probe.SPSDKDebugProbeError

The communication error exception for use with SPSDK.

Initialize the base SPSDK Exception.

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

Bases: spsdk.debuggers.debug_probe.SPSDKDebugProbeError

The Probe not found exception for use with SPSDK.

Initialize the base SPSDK Exception.

Module for DebugMailbox Pemicro Debug probes support

Module for DebugMailbox Pemicro Debug probes support.

class spsdk.debuggers.debug_probe_pemicro.DebugProbePemicro(hardware_id, options=None)

Bases: spsdk.debuggers.debug_probe.DebugProbe

Class to define Pemicro package interface for NXP SPSDK.

The Pemicro class initialization.

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

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

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

Return type

None

coresight_reg_read(access_port=True, addr=0)

Read coresight register over Pemicro interface.

The Pemicro 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 Pemicro interface.

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

This functions returns the list of all connected probes in system by Pemicro 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

list

Returns

probe_description

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

classmethod get_pemicro_lib()

Get Pemicro object.

Return type

PyPemicro

Returns

The Pemicro Object

Raises

SPSDKDebugProbeError – The Pemicro object get function failed.

open()

Open Pemicro interface for NXP SPSDK.

The Pemicro opening function for SPSDK library to support various DEBUG PROBES. The function is used to initialize the connection to target and enable using debug probe for DAT purposes.

Raises

SPSDKDebugProbeError – The Pemicro cannot establish communication with target

Return type

None

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: spsdk.debuggers.debug_probe.DebugProbe

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.

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

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

list

Returns

probe_description

open()

Open PyOCD interface for NXP SPSDK.

The PyOCD opening function for SPSDK library to support various DEBUG PROBES. The function is used to initialize the connection to target and enable using debug probe for DAT purposes.

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

spsdk.debuggers.debug_probe_pyocd.set_logger(level)

Sets the log level for this module.

param level: Requested level.

Return type

None

Module with common utils for debuggers module

Module for DebugMailbox Debug probes support.

class spsdk.debuggers.utils.DebugProbeUtils

Bases: object

The SPSDK debug probes utilities class.

The SPSDK debug probes utilities, that helps user to find and open the real hardware debug probe to establish connection with hardware.

static 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

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

Bases: list

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

append(item)

Overriding build-in function by check the type.

Parameters

item (ProbeDescription) – ProbeDescription item.

Raises

SPSDKError – Invalid input types has been used.

Return type

None

insert(index, item)

Overriding build-in function by check the type.

Parameters

  • item (ProbeDescription) – ProbeDescription item.

  • index (int) – Index in list to insert.

Raises

SPSDKError – Invalid input types has been used.

Return type

None

print()

Prints the List of Probes to nice colored table.

Return type

None

select_probe(silent=False)

Perform Probe selection.

Parameters

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

Return type

ProbeDescription

Returns

The record of selected DebugProbe

Raises

SPSDKProbeNotFoundError – No probe has been founded

class spsdk.debuggers.utils.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.

spsdk.debuggers.utils.open_debug_probe(interface=None, serial_no=None, debug_probe_params=None)

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.

Return type

Iterator[DebugProbe]

Returns

Active DebugProbe object.

Raises

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

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

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)

Return type

bool

Returns

True is access to AHB is granted, False otherwise.