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, user_params=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 IDuser_params (
Optional
[Dict
]) – The user params dictionary
- APADDR = 16777215
- APBANKSEL = 240
- APBANK_SHIFT = 4
- APSEL = 4278190080
- APSEL_APBANKSEL = 4278190320
- APSEL_SHIFT = 24
- 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 Portaddr (
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 Portaddr (
int
) – the register addressdata (
int
) – the data to be written into register
- Raises
NotImplementedError – Derived class has to implement this method
- Return type
None
- dbgmlbx_reg_read(addr=0)
Read debug mailbox access port register.
This is read debug mailbox register 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)
- Raises
NotImplementedError – Derived class has to implement this method
- dbgmlbx_reg_write(addr=0, data=0)
Write debug mailbox access port register.
This is write debug mailbox register function for SPSDK library to support various DEBUG PROBES.
- Parameters
addr (
int
) – the register addressdata (
int
) – the data to be written into register
- Raises
NotImplementedError – Derived class has to implement this method
- Return type
None
- property debug_mailbox_access_port: int
Returns debug mailbox access port.
In case that the access port is not detected or selected, it returns value less than zero.
- Return type
int
- Returns
Index of Debug MailBox Access port.
- enable_memory_interface()
Debug probe enabling memory interface.
General memory interface enabling method (it should be called after open method) for SPSDK library to support various DEBUG PROBES. The function is used to initialize the target memory interface and enable using memory access of target over debug probe.
- Return type
None
- classmethod get_connected_probes(hardware_id=None, user_params=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.user_params (
Optional
[Dict
]) – The user params 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
ValueError – In case of invalid value.
- 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)
- Raises
NotImplementedError – Derived class has to implement this method
- 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
- Raises
NotImplementedError – Derived class has to implement this method
- 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
- reset()
Reset a target.
It resets a target.
- Raises
NotImplementedError – Derived class has to implement this method
- Return type
None
- exception spsdk.debuggers.debug_probe.SPSDKDebugMailBoxAPNotFoundError(desc=None)
Bases:
spsdk.debuggers.debug_probe.SPSDKDebugProbeError
The target doesn’t have debug mailbox access port exception for use with SPSDK.
Initialize the base SPSDK Exception.
- 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.SPSDKDebugProbeMemoryInterfaceAPNotFoundError(desc=None)
Bases:
spsdk.debuggers.debug_probe.SPSDKDebugProbeError
The target doesn’t have memory interface access port exception for use with SPSDK.
Initialize the base SPSDK Exception.
- exception spsdk.debuggers.debug_probe.SPSDKDebugProbeMemoryInterfaceNotEnabled(desc=None)
Bases:
spsdk.debuggers.debug_probe.SPSDKDebugProbeError
The target doesn’t have memory interface enabled 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 Jlink Debug probes support
Module for DebugMailbox PyLink Debug probes support.
- class spsdk.debuggers.debug_probe_jlink.DebugProbePyLink(hardware_id, user_params=None)
Bases:
spsdk.debuggers.debug_probe.DebugProbe
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.
- 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
- dbgmlbx_reg_read(addr=0)
Read debug mailbox access port register.
This is read debug mailbox register 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)
- dbgmlbx_reg_write(addr=0, data=0)
Write debug mailbox access port register.
This is write debug mailbox register 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
- enable_memory_interface()
Debug probe enabling memory interface.
General memory interface enabling method (it should be called after open method) for SPSDK library to support various DEBUG PROBES. The function is used to initialize the target memory interface and enable using memory access of target over debug probe.
- Raises
SPSDKDebugProbeNotOpenError – The PyLink probe is NOT opened
SPSDKDebugProbeError – Error with connection to target.
- Return type
None
- classmethod get_connected_probes(hardware_id=None, user_params=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.user_params (
Optional
[Dict
]) – The user params dictionary
- Return type
list
- 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.
- 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)
- Raises
SPSDKDebugProbeNotOpenError – The PyLink probe is NOT opened
SPSDKDebugProbeMemoryInterfaceNotEnabled – The PyLink is using just CoreSight access.
SPSDKDebugProbeTransferError – The IO operation failed
- 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
- Raises
SPSDKDebugProbeNotOpenError – The PyLink probe is NOT opened
SPSDKDebugProbeMemoryInterfaceNotEnabled – The PyLink is using just CoreSight access.
SPSDKDebugProbeTransferError – The IO operation failed
- Return type
None
- 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
- reset()
Reset a target.
It resets a target.
- Raises
SPSDKDebugProbeNotOpenError – The PyLink probe is NOT opened
- Return type
None
- spsdk.debuggers.debug_probe_jlink.set_logger(level)
Sets the log level for this module.
param level: Requested level.
- 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, user_params=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.
- 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
- dbgmlbx_reg_read(addr=0)
Read debug mailbox access port register.
This is read debug mailbox register 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)
- Raises
NotImplementedError – The dbgmlbx_reg_read is NOT implemented
- dbgmlbx_reg_write(addr=0, data=0)
Write debug mailbox access port register.
This is write debug mailbox register function for SPSDK library to support various DEBUG PROBES.
- Parameters
addr (
int
) – the register addressdata (
int
) – the data to be written into register
- Raises
NotImplementedError – The dbgmlbx_reg_write is NOT implemented
- Return type
None
- classmethod get_connected_probes(hardware_id=None, user_params=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.user_params (
Optional
[Dict
]) – The user params dictionary
- Return type
list
- Returns
probe_description
- classmethod get_pemicro_lib()
Get J-Link object.
- Return type
PyPemicro
- Returns
The J-Link Object
- Raises
SPSDKDebugProbeError – The J-Link object get function failed.
- 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)
- Raises
SPSDKDebugProbeNotOpenError – The Pemicro probe is NOT opened
SPSDKError – The Pemicro probe has failed during read operation
- 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
- Raises
SPSDKDebugProbeNotOpenError – The Pemicro probe is NOT opened
SPSDKError – The Pemicro probe has failed during write operation
- Return type
None
- 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
- reset()
Reset a target.
It resets a target.
- Raises
SPSDKDebugProbeNotOpenError – The Pemicro debug probe is not opened yet
- 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, user_params=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.
- DMBOX_ADI_DISCOVERY_CLASS_MAP = {<ADIVersion.ADIv5: 5>: <class 'spsdk.debuggers.debug_probe_pyocd.DebugProbePyOCD.DMBoxADIv5Discovery'>, <ADIVersion.ADIv6: 6>: <class 'spsdk.debuggers.debug_probe_pyocd.DebugProbePyOCD.DMBoxADIv6Discovery'>}
- class DMBoxADIv5Discovery(target)
Bases:
pyocd.coresight.discovery.ADIv5Discovery
Custom discoverer class based of ADIv5Discovery.
! @brief Constructor.
- discover()
Setup list of calls to perform the components discovery.
- Return type
CallSequence
- class DMBoxADIv6Discovery(target)
Bases:
pyocd.coresight.discovery.ADIv6Discovery
Custom discoverer class based of ADIv6Discovery.
! @brief Constructor.
- discover()
Setup list of calls to perform the components discovery.
- Return type
CallSequence
- close()
Close PyOCD interface.
The PyOCD 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
- dbgmlbx_reg_read(addr=0)
Read debug mailbox access port register.
This is read debug mailbox register 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)
- Raises
SPSDKDebugMailBoxAPNotFoundError – The dbgmlbx_reg_read is NOT implemented
SPSDKDebugProbeTransferError – The dbgmlbx_reg_read ends with data transfer error
- dbgmlbx_reg_write(addr=0, data=0)
Write debug mailbox access port register.
This is write debug mailbox register function for SPSDK library to support various DEBUG PROBES.
- Parameters
addr (
int
) – the register addressdata (
int
) – the data to be written into register
- Raises
SPSDKDebugMailBoxAPNotFoundError – The dbgmlbx_reg_write is NOT implemented
SPSDKDebugProbeTransferError – The dbgmlbx_reg_write ends with data transfer error
- Return type
None
- dp_init_sequence()
Debug Port init sequence modification function.
This function allows miss the Connect action for J-LINK probes, because the J-Link DLL do some additional unwanted actions that are not welcomed by DAT.
- Return type
CallSequence
- Returns
Debug Port initialization call sequence
- Raises
SPSDKDebugProbeNotOpenError – The PyOCD probe is NOT opened
- classmethod get_connected_probes(hardware_id=None, user_params=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.user_params (
Optional
[Dict
]) – The user params dictionary
- Return type
list
- Returns
probe_description
- 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)
- Raises
SPSDKDebugProbeMemoryInterfaceAPNotFoundError – The device doesn’t content memory interface
SPSDKDebugProbeTransferError – Memory read operation failed.
- 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
- Raises
SPSDKDebugProbeMemoryInterfaceAPNotFoundError – The device doesn’t content memory interface
SPSDKDebugProbeTransferError – Memory write operation failed.
- Return type
None
- 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
SPSDKDebugProbeNotOpenError – The PyOCD debug probe is not opened yet
- Return type
None
- will_init_target(target, init_sequence)
Initialize target.
Modification of initialization sequence to allow do debug authentication operations.
- 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, user_params=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 matchinguser_params (
Optional
[Dict
]) – The dictionary with optional user parameters hardware id is listed.
- Return type
- 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
) – ProbeDestription 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
) – ProbeDestription 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
- 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(user_params=None)
Get instance of probe.
- Parameters
user_params (
Optional
[Dict
]) – The dictionary with optional user parameters- Return type
- Returns
Instance of described probe.
- spsdk.debuggers.utils.test_ahb_access(probe, ap_mem=0)
The function safely test the access of debug probe to AHB in target.
- Parameters
probe (
DebugProbe
) – Probe object to use for test.ap_mem (
int
) – Index of memory access port., defaults to 0
- Return type
bool
- Returns
True is access to AHB is granted, False otherwise.