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 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.
- 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.
- 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 initialize the connection to target and enable using debug probe for DAT purposes.
- Return type:
None
- reset()#
Reset a target.
It resets a target.
- Return type:
None
- class spsdk.debuggers.debug_probe.DebugProbeLocal(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
- 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.SPSDKProbeNotFoundError(desc=None)#
Bases:
SPSDKDebugProbeError
The Probe not found exception for use with SPSDK.
Initialize the base SPSDK Exception.
Module for DebugMailbox Jlink Debug probes support#
Module for DebugMailbox PyLink Debug probes support.
- class spsdk.debuggers.debug_probe_jlink.DebugProbePyLink(hardware_id, options=None)#
Bases:
DebugProbeLocal
Class to define PyLink package interface for NXP SPSDK.
The PyLink class initialization.
The PyLink initialization function for SPSDK library to support various DEBUG PROBES.
- NAME = 'jlink'#
- 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 PyLink probe is NOT opened
SPSDKDebugProbeError – The PyLink 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
- coresight_reg_read(access_port=True, addr=0)#
Read coresight register over PyLink interface.
The PyLink 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 PyLink probe is NOT opened
- coresight_reg_write(access_port=True, addr=0, data=0)#
Write coresight register over PyLink interface.
The PyLink 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 PyLink probe is NOT opened
- Return type:
None
- classmethod get_connected_probes(hardware_id=None, options=None)#
Get all connected probes over PyLink.
This functions returns the list of all connected probes in system by PyLink 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
- classmethod get_jlink_lib()#
Get J-Link object.
- Return type:
JLink
- Returns:
The J-Link Object
- Raises:
SPSDKDebugProbeError – The J-Link object get function failed.
- 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.
- open()#
Open PyLink interface for NXP SPSDK.
The PyLink 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 PyLink cannot establish communication with target
- Return type:
None
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:
DebugProbeLocal
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.
- NAME = 'pemicro'#
- 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 Pemicro debug probe is not opened yet
SPSDKDebugProbeError – The PyPEMicro probe RESET function failed
- 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 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 Pemicro probe is NOT opened
- 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 Portaddr (
int
) – the register addressdata (
int
) – the data to be written into register
- Raises:
SPSDKDebugProbeTransferError – The IO operation failed
SPSDKDebugProbeNotOpenError – The Pemicro probe is NOT opened
- 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:
- 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:
DebugProbeLocal
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
- 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. The function is used to initialize the connection to target and enable using debug probe for DAT purposes.
- Raises:
SPSDKProbeNotFoundError – The probe has not found
SPSDKDebugMailBoxAPNotFoundError – The debug mailbox access port NOT found
SPSDKDebugProbeError – The PyOCD cannot establish communication with target
- 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
- 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.