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 IDoptions (
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 Portaddr (
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 Portaddr (
int
) – the register addressdata (
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:
- 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 addressdata (
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 IDoptions (
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 addressdata (
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:
- 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:
SPSDKDebugProbeNotOpenError – The PyOCD debug probe is not opened yet
SPSDKDebugProbeError – The PyOCD probe RESET function failed
- 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 Portaddr (
int
) – the register address
- Return type:
int
- Returns:
The read value of addressed register (4 bytes)
- Raises:
SPSDKDebugProbeTransferError – The IO operation failed
SPSDKDebugProbeNotOpenError – The PyOCD probe is NOT opened
- 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 Portaddr (
int
) – the register addressdata (
int
) – the data to be written into register
- Raises:
SPSDKDebugProbeTransferError – The IO operation failed
SPSDKDebugProbeNotOpenError – The PyOCD probe is NOT opened
- 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:
- Returns:
probe_description
- open()#
Open PyOCD interface for NXP SPSDK.
The PyOCD opening function for SPSDK library to support various DEBUG PROBES.
- Raises:
SPSDKProbeNotFoundError – The probe has not found
SPSDKDebugMailBoxAPNotFoundError – The debug mailbox access port NOT found
SPSDKDebugProbeError – Opening of the debug probe failed
- 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 matchingoptions (
Optional
[dict
]) – The dictionary with optional options hardware id is listed.
- Return type:
- 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 matchingdebug_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 printinput_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 probessilent (
bool
) – When it True, the functions select the probe if applicable without any prints to logprint_func (
Callable
) – Custom function to print data, defaults to printinput_func (
Callable
[[],str
]) – Custom function to handle user input, defaults to input
- Return type:
- 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=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 0invasive (
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