PyLink¶
The PyLink package provides a Pythonic interface for interacting with the
J-Link C SDK. This interface is provided through the JLink
class, which
provides several of the functions provided by the native SDK. Some methods
require a specific interface, a target being connected, or an emulator being
connected, and will raise errors as appropriate if these conditions are not
met.
In lieu of return codes, this library uses the object-oriented paradigm of
raising an exception. All exceptions are inherited from the JLinkException
base class.
Exceptions¶
This submodule defines the different exceptions that can be generated by the
JLink
methods.
-
exception
pylink.errors.
JLinkDataException
(code)¶ Bases:
pylink.enums.JLinkDataErrors
,pylink.errors.JLinkException
J-Link data event exception.
-
exception
pylink.errors.
JLinkEraseException
(code)¶ Bases:
pylink.enums.JLinkEraseErrors
,pylink.errors.JLinkException
J-Link erase exception.
-
exception
pylink.errors.
JLinkException
(code)¶ Bases:
pylink.enums.JLinkGlobalErrors
,exceptions.Exception
Generic J-Link exception.
-
exception
pylink.errors.
JLinkFlashException
(code)¶ Bases:
pylink.enums.JLinkFlashErrors
,pylink.errors.JLinkException
J-Link flash exception.
-
exception
pylink.errors.
JLinkRTTException
(code)¶ Bases:
pylink.enums.JLinkRTTErrors
,pylink.errors.JLinkException
J-Link RTT exception.
-
exception
pylink.errors.
JLinkReadException
(code)¶ Bases:
pylink.enums.JLinkReadErrors
,pylink.errors.JLinkException
J-Link read exception.
-
exception
pylink.errors.
JLinkWriteException
(code)¶ Bases:
pylink.enums.JLinkWriteErrors
,pylink.errors.JLinkException
J-Link write exception.
Library¶
This submodule defines a Library
. This is not needed unless explicitly
specifying a different version of the J-Link dynamic library.
-
class
pylink.library.
Library
(dllpath=None)¶ Bases:
object
Wrapper to provide easy access to loading the J-Link SDK DLL.
This class provides a convenience for finding and loading the J-Link DLL across multiple platforms, and accounting for the inconsistencies between Windows and nix-based platforms.
-
_standard_calls_
¶ list of names of the methods for the API calls that must be converted to standard calling convention on the Windows platform.
-
JLINK_SDK_NAME
¶ name of the J-Link DLL on nix-based platforms.
-
WINDOWS_JLINK_SDK_NAME
¶ name of the J-Link DLL on Windows platforms.
-
JLINK_SDK_NAME
= 'libjlinkarm'
-
WINDOWS_32_JLINK_SDK_NAME
= 'JLinkARM'¶
-
WINDOWS_64_JLINK_SDK_NAME
= 'JLink_x64'¶
-
dll
()¶ Returns the DLL for the underlying shared library.
Parameters: self (Library) – the Library
instanceReturns: A ctypes
DLL instance if one was loaded, otherwiseNone
.
-
classmethod
find_library_darwin
()¶ Loads the SEGGER DLL from the installed applications.
This method accounts for the all the different ways in which the DLL may be installed depending on the version of the DLL. Always uses the first directory found.
SEGGER’s DLL is installed in one of three ways dependent on which which version of the SEGGER tools are installed:
Versions Directory < 5.0.0 /Applications/SEGGER/JLink\ NUMBER
< 6.0.0 /Applications/SEGGER/JLink/libjlinkarm.major.minor.dylib
>= 6.0.0 /Applications/SEGGER/JLink/libjlinkarm
Parameters: cls (Library) – the Library
classReturns: The path to the J-Link library files in the order they are found.
-
classmethod
find_library_linux
()¶ Loads the SEGGER DLL from the root directory.
On Linux, the SEGGER tools are installed under the
/opt/SEGGER
directory with versioned directories having the suffix_VERSION
.Parameters: cls (Library) – the Library
classReturns: The paths to the J-Link library files in the order that they are found.
-
classmethod
find_library_windows
()¶ Loads the SEGGER DLL from the windows installation directory.
- On Windows, these are found either under:
C:\Program Files\SEGGER\JLink
C:\Program Files (x86)\SEGGER\JLink
.
Parameters: cls (Library) – the Library
classReturns: The paths to the J-Link library files in the order that they are found.
-
classmethod
get_appropriate_windows_sdk_name
()¶ Returns the appropriate JLink SDK library name on Windows depending on 32bit or 64bit Python variant.
- SEGGER delivers two variants of their dynamic library on Windows:
JLinkARM.dll
for 32-bit platformJLink_x64.dll
for 64-bit platform
Parameters: cls (Library) – the Library
classReturns: The name of the library depending on the platform this module is run on.
-
load
(path=None)¶ Loads the specified DLL, if any, otherwise re-loads the current DLL.
If
path
is specified, loads the DLL at the givenpath
, otherwise re-loads the DLL currently specified by this library.Note
This creates a temporary DLL file to use for the instance. This is necessary to work around a limitation of the J-Link DLL in which multiple J-Links cannot be accessed from the same process.
Parameters: Returns: True
if library was loaded successfully.Raises: OSError
– if there is no J-LINK SDK DLL present at the path.See also
-
JLock¶
This submodule defines a JLock
. This acts as a lockfile-like interface for
interacting with a particular emulator in order to prevent multiple threads or
processes from creating instances of JLink
to interact with the same
emulator.
-
class
pylink.jlock.
JLock
(serial_no)¶ Bases:
object
Lockfile for accessing a particular J-Link.
The J-Link SDK does not prevent accessing the same J-Link multiple times from the same process or multiple processes. As a result, a user can have the same J-Link being accessed by multiple processes. This class provides an interface to a lock-file like structure for the physical J-Links to ensure that any instance of a
JLink
with an open emulator connection will be the only one accessing that emulator.This class uses a PID-style lockfile to allow acquiring of the lockfile in the instances where the lockfile exists, but the process which created it is no longer running.
To share the same emulator connection between multiple threads, processes, or functions, a single instance of a
JLink
should be created and passed between the threads and processes.-
name
¶ the name of the lockfile.
-
path
¶ full path to the lockfile.
-
fd
¶ file description of the lockfile.
-
acquired
¶ boolean indicating if the lockfile lock has been acquired.
-
IPADDR_NAME_FMT
= '.pylink-ip-{}.lck'¶
-
SERIAL_NAME_FMT
= '.pylink-usb-{}.lck'¶
-
acquire
()¶ Attempts to acquire a lock for the J-Link lockfile.
If the lockfile exists but does not correspond to an active process, the lockfile is first removed, before an attempt is made to acquire it.
Parameters: self (Jlock) – the JLock
instanceReturns: True
if the lock was acquired, otherwiseFalse
.Raises: OSError
– on file errors.
-
JLink¶
This submodule provides the definition for the JLink
class, which is the
interface to the J-Link.
-
class
pylink.jlink.
JLink
(lib=None, log=None, detailed_log=None, error=None, warn=None, unsecure_hook=None, serial_no=None, ip_addr=None, open_tunnel=False)¶ Bases:
object
Python interface for the SEGGER J-Link.
This is a wrapper around the J-Link C SDK to provide a Python interface to it. The shared library is loaded and used to call the SDK methods.
-
ADAPTIVE_JTAG_SPEED
= 65535¶
-
AUTO_JTAG_SPEED
= 0¶
-
INVALID_JTAG_SPEED
= 65534¶
-
MAX_BUF_SIZE
= 336¶
-
MAX_JTAG_SPEED
= 50000¶
-
MAX_NUM_CPU_REGISTERS
= 256¶
-
MAX_NUM_MOES
= 8¶
-
MIN_JTAG_SPEED
= 5¶
-
add_license
(*args, **kwargs)¶ Adds the given
contents
as a new custom license to the J-Link.Parameters: - self (JLink) – the
JLink
instance - contents – the string contents of the new custom license
Returns: True
if license was added,False
if license already existed.Raises: JLinkException
– if the write fails.Note
J-Link V9 and J-Link ULTRA/PRO V4 have 336 Bytes of memory for licenses, while older versions of 80 bytes.
- self (JLink) – the
-
breakpoint_clear
(*args, **kwargs)¶ Removes a single breakpoint.
Parameters: - self (JLink) – the
JLink
instance - handle (int) – the handle of the breakpoint to be removed
Returns: True
if the breakpoint was cleared, otherwiseFalse
if the breakpoint was not valid.- self (JLink) – the
-
breakpoint_clear_all
(*args, **kwargs)¶ Removes all breakpoints that have been set.
Parameters: self (JLink) – the JLink
instanceReturns: True
if they were cleared, otherwiseFalse
.
-
breakpoint_find
(*args, **kwargs)¶ Returns the handle of a breakpoint at the given address, if any.
Parameters: - self (JLink) – the
JLink
instance - addr (int) – the address to search for the breakpoint
Returns: A non-zero integer if a breakpoint was found at the given address, otherwise zero.
- self (JLink) – the
-
breakpoint_info
(*args, **kwargs)¶ Returns the information about a set breakpoint.
Note
Either
handle
orindex
can be specified. If theindex
is not provided, thehandle
must be set, and vice-versa. If bothindex
andhandle
are provided, theindex
overrides the providedhandle
.Parameters: - self (JLink) – the
JLink
instance - handle (int) – option handle of a valid breakpoint
- index (int) – optional index of the breakpoint.
Returns: An instance of
JLinkBreakpointInfo
specifying information about the breakpoint.Raises: JLinkException
– on error.ValueError
– if both the handle and index are invalid.
- self (JLink) – the
-
breakpoint_set
(*args, **kwargs)¶ Sets a breakpoint at the specified address.
If
thumb
isTrue
, the breakpoint is set in THUMB-mode, while ifarm
isTrue
, the breakpoint is set in ARM-mode, otherwise a normal breakpoint is set.Parameters: - self (JLink) – the
JLink
instance - addr (int) – the address where the breakpoint will be set
- thumb (bool) – boolean indicating to set the breakpoint in THUMB mode
- arm (bool) – boolean indicating to set the breakpoint in ARM mode
Returns: An integer specifying the breakpoint handle. This handle should be retained for future breakpoint operations.
Raises: TypeError
– if the given address is not an integer.JLinkException
– if the breakpoint could not be set.
- self (JLink) – the
-
capabilities
¶ Returns a bitwise combination of the emulator’s capabilities.
Parameters: self (JLink) – the JLink
instanceReturns: Bitfield of emulator capabilities.
-
clear_error
()¶ Clears the DLL internal error state.
Parameters: self (JLink) – the JLink
instanceReturns: The error state before the clear.
-
close
()¶ Closes the open J-Link.
Parameters: self (JLink) – the JLink
instanceReturns: None
Raises: JLinkException
– if there is no connected JLink.
-
code_memory_read
(*args, **kwargs)¶ Reads bytes from code memory.
Note
This is similar to calling
memory_read
ormemory_read8
, except that this uses a cache and reads ahead. This should be used in instances where you want to read a small amount of bytes at a time, and expect to always read ahead.Parameters: - self (JLink) – the
JLink
instance - addr (int) – starting address from which to read
- num_bytes (int) – number of bytes to read
Returns: A list of bytes read from the target.
Raises: JLinkException
– if memory could not be read.- self (JLink) – the
-
comm_supported
(*args, **kwargs)¶ Returns true if the connected emulator supports
comm_*
functions.Parameters: self (JLink) – the JLink
instanceReturns: True
if the emulator supportscomm_*
functions, otherwiseFalse
.
-
compatible_firmware_version
¶ Returns the DLL’s compatible J-Link firmware version.
Parameters: self (JLink) – the JLink
instanceReturns: The firmware version of the J-Link that the DLL is compatible with. Raises: JLinkException
– on error.
-
compile_date
¶ Returns a string specifying the date and time at which the DLL was translated.
Parameters: self (JLink) – the JLink
instanceReturns: Datetime string.
-
connect
(*args, **kwargs)¶ Connects the J-Link to its target.
Parameters: - self (JLink) – the
JLink
instance - chip_name (str) – target chip name
- speed (int) – connection speed, one of
{5-12000, 'auto', 'adaptive'}
- verbose (bool) – boolean indicating if connection should be verbose in logging
Returns: None
Raises: JLinkException
– if connection fails to establish.TypeError
– if given speed is invalid
- self (JLink) – the
-
connected
()¶ Returns whether a J-Link is connected.
Parameters: self (JLink) – the JLink
instanceReturns: True
if the J-Link is open and connected, otherwiseFalse
.
-
connected_emulators
(host=1)¶ Returns a list of all the connected emulators.
Parameters: - self (JLink) – the
JLink
instance - host (int) – host type to search (default:
JLinkHost.USB
)
Returns: List of
JLinkConnectInfo
specifying the connected emulators.Raises: JLinkException
– if fails to enumerate devices.- self (JLink) – the
-
connection_required
(func)¶ Decorator to specify that a target connection is required in order for the given method to be used.
Parameters: func (function) – function being decorated Returns: The wrapper function.
-
core_cpu
(*args, **kwargs)¶ Returns the identifier of the core CPU.
Note
This is distinct from the value returned from
core_id()
which is the ARM specific identifier.Parameters: self (JLink) – the JLink
instanceReturns: The identifier of the CPU core.
-
core_id
(*args, **kwargs)¶ Returns the identifier of the target ARM core.
Parameters: self (JLink) – the JLink
instanceReturns: Integer identifier of ARM core.
-
core_name
(*args, **kwargs)¶ Returns the name of the target ARM core.
Parameters: self (JLink) – the JLink
instanceReturns: The target core’s name.
-
coresight_configuration_required
(func)¶ Decorator to specify that a coresight configuration or target connection is required in order for the given method to be used.
Parameters: func (function) – function being decorated Returns: The wrapper function.
-
coresight_configure
(*args, **kwargs)¶ Prepares target and J-Link for CoreSight function usage.
Parameters: - self (JLink) – the
JLink
instance - ir_pre (int) – sum of instruction register length of all JTAG devices in the JTAG chain, close to TDO than the actual one, that J-Link shall communicate with
- dr_pre (int) – number of JTAG devices in the JTAG chain, closer to TDO than the actual one, that J-Link shall communicate with
- ir_post (int) – sum of instruction register length of all JTAG devices in the JTAG chain, following the actual one, that J-Link shall communicate with
- dr_post (int) – Number of JTAG devices in the JTAG chain, following the actual one, J-Link shall communicate with
- ir_len (int) – instruction register length of the actual device that J-Link shall communicate with
- perform_tif_init (bool) – if
False
, then do not output switching sequence on completion
Returns: None
Note
This must be called before calling
coresight_read()
orcoresight_write()
.- self (JLink) – the
-
coresight_read
(*args, **kwargs)¶ Reads an Ap/DP register on a CoreSight DAP.
Wait responses and special handling are both handled by this method.
Note
coresight_configure()
must be called prior to calling this method.Parameters: - self (JLink) – the
JLink
instance - reg (int) – index of DP/AP register to read
- ap (bool) –
True
if reading from an Access Port register, otherwiseFalse
for Debug Port
Returns: Data read from register.
Raises: JLinkException
– on hardware error- self (JLink) – the
-
coresight_write
(*args, **kwargs)¶ Writes an Ap/DP register on a CoreSight DAP.
Note
coresight_configure()
must be called prior to calling this method.Parameters: - self (JLink) – the
JLink
instance - reg (int) – index of DP/AP register to write
- data (int) – data to write
- ap (bool) –
True
if writing to an Access Port register, otherwiseFalse
for Debug Port
Returns: Number of repetitions needed until write request accepted.
Raises: JLinkException
– on hardware error- self (JLink) – the
-
cp15_present
(*args, **kwargs)¶ Returns whether target has CP15 co-processor.
Returns: True
if the target has CP15 co-processor, otherwiseFalse
.
-
cp15_register_read
(*args, **kwargs)¶ Reads value from specified coprocessor register.
Parameters: - cr_n (int) – CRn value
- op_1 (int) – Op1 value
- cr_m (int) – CRm value
- op_2 (int) – Op2 value
Returns: An integer containing the value of coprocessor register
Raises: JLinkException
– on error
-
cp15_register_write
(*args, **kwargs)¶ Writes value to specified coprocessor register.
Parameters: - cr_n (int) – CRn value
- op_1 (int) – Op1 value
- cr_m (int) – CRm value
- op_2 (int) – Op2 value
- value (int) – value to write
Returns: An integer containing the result of the command
Raises: JLinkException
– on error
-
cpu_capability
(*args, **kwargs)¶ Checks whether the J-Link has support for a CPU capability.
This method checks if the emulator has built-in intelligence to handle the given CPU capability for the target CPU it is connected to.
Parameters: - self (JLink) – the
JLink
instance - capability (int) – the capability to check for
Returns: True
if the J-Link has built-in intelligence to support the givencapability
for the CPU it is connected to, otherwiseFalse
.- self (JLink) – the
-
cpu_halt_reasons
(*args, **kwargs)¶ Retrives the reasons that the CPU was halted.
Parameters: self (JLink) – the JLink
instanceReturns: A list of JLInkMOEInfo
instances specifying the reasons for which the CPU was halted. This list may be empty in the case that the CPU is not halted.Raises: JLinkException
– on hardware error.
-
cpu_speed
(*args, **kwargs)¶ Retrieves the CPU speed of the target.
If the target does not support CPU frequency detection, this function will return
0
.Parameters: - self (JLink) – the
JLink
instance - silent (bool) –
True
if the CPU detection should not report errors to the error handler on failure.
Returns: The measured CPU frequency on success, otherwise
0
if the core does not support CPU frequency detection.Raises: JLinkException
– on hardware error.- self (JLink) – the
-
custom_licenses
¶ Returns a string of the installed licenses the J-Link has.
Parameters: self (JLink) – the JLink
instanceReturns: String of the contents of the custom licenses the J-Link has.
-
detailed_log_handler
¶ Returns the detailed log handler function.
Parameters: self (JLink) – the JLink
instanceReturns: None
if the detailed log handler was not set, otherwise actypes.CFUNCTYPE
.
-
device_family
(*args, **kwargs)¶ Returns the device family of the target CPU.
Parameters: self (JLink) – the JLink
instanceReturns: Integer identifier of the device family.
-
disable_dialog_boxes
(*args, **kwargs)¶ Disables showing dialog boxes on certain methods.
Warning
This has the effect of also silencing dialog boxes that appear when updating firmware / to confirm updating firmware.
Dialog boxes will be shown for a brief period of time (approximately five seconds), before being automatically hidden, and the default option chosen.
Parameters: self (JLink) – the JLink
instanceReturns: None
-
disable_reset_inits_registers
(*args, **kwargs)¶ Disables CPU register initialization on resets.
When
.reset()
is called, the CPU registers will be read and not initialized.Parameters: self (JLink) – the JLink
instanceReturns: True
if was previously enabled, otherwiseFalse
.
-
disable_reset_pulls_reset
(*args, **kwargs)¶ Disables RESET pin toggling on the JTAG bus on resets.
When
.reset()
is called, it will not toggle the RESET pin on the JTAG bus.Parameters: self (JLink) – the JLink
instanceReturns: None
-
disable_reset_pulls_trst
(*args, **kwargs)¶ Disables TRST pin toggling on the JTAG bus on resets.
When
.reset()
is called, it will not toggle the TRST pin on the JTAG bus.Parameters: self (JLink) – the JLink
instanceReturns: None
-
disable_soft_breakpoints
(*args, **kwargs)¶ Disables software breakpoints.
Note
After this function is called,
software_breakpoint_set()
cannot be used without first callingenable_soft_breakpoints()
.Parameters: self (JLink) – the JLink
instanceReturns: None
-
disassemble_instruction
(instruction)¶ Disassembles and returns the assembly instruction string.
Parameters: - self (JLink) – the
JLink
instance. - instruction (int) – the instruction address.
Returns: A string corresponding to the assembly instruction string at the given instruction address.
Raises: JLinkException
– on error.TypeError
– ifinstruction
is not a number.
- self (JLink) – the
-
enable_dialog_boxes
(*args, **kwargs)¶ Enables showing dialog boxes on certain methods.
Note
This can be used for batch or automized test running.
Parameters: self (JLink) – the JLink
instanceReturns: None
-
enable_reset_inits_registers
(*args, **kwargs)¶ Enables CPU register initialization on resets.
When
.reset()
is called, it will initialize the CPU registers.Parameters: self (JLink) – the JLink
instanceReturns: True
if was previously enabled, otherwiseFalse
.
-
enable_reset_pulls_reset
(*args, **kwargs)¶ Enables RESET pin toggling on the JTAG bus on resets.
When
.reset()
is called, it will also toggle the RESET pin on the JTAG bus.Parameters: self (JLink) – the JLink
instanceReturns: None
-
enable_reset_pulls_trst
(*args, **kwargs)¶ Enables TRST pin toggling on the JTAG bus on resets.
When
.reset()
is called, it will also toggle the TRST pin on the JTAG bus.Parameters: self (JLink) – the JLink
instanceReturns: None
-
enable_soft_breakpoints
(*args, **kwargs)¶ Enables software breakpoints.
Note
This should be called before calling
software_breakpoint_set()
.Parameters: self (JLink) – the JLink
instanceReturns: None
-
erase
(*args, **kwargs)¶ Erases the flash contents of the device.
This erases the flash memory of the target device. If this method fails, the device may be left in an inoperable state.
Parameters: self (JLink) – the JLink
instanceReturns: Number of bytes erased.
-
erase_licenses
(*args, **kwargs)¶ Erases the custom licenses from the connected J-Link.
Note
This method will erase all licenses stored on the J-Link.
Parameters: self (JLink) – the JLink
instanceReturns: True
on success, otherwiseFalse
.
-
error
¶ DLL internal error state.
Parameters: self (JLink) – the JLink
instanceReturns: The DLL internal error state. This is set if any error occurs in underlying DLL, otherwise it is None
.
-
error_handler
¶ Returns the error handler function.
Parameters: self (JLink) – the JLink
instanceReturns: None
if the error handler was not set, otherwise actypes.CFUNCTYPE
.
-
etm_register_read
(*args, **kwargs)¶ Reads a value from an ETM register.
Parameters: - self (JLink) – the
JLink
instance. - register_index (int) – the register to read.
Returns: The value read from the ETM register.
- self (JLink) – the
-
etm_register_write
(*args, **kwargs)¶ Writes a value to an ETM register.
Parameters: - self (JLink) – the
JLink
instance. - register_index (int) – the register to write to.
- value (int) – the value to write to the register.
- delay (bool) – boolean specifying if the write should be buffered.
Returns: None
- self (JLink) – the
-
etm_supported
(*args, **kwargs)¶ Returns if the CPU core supports ETM.
Parameters: self (JLink) – the JLink
instance.Returns: True
if the CPU has the ETM unit, otherwiseFalse
.
-
exec_command
(cmd)¶ Executes the given command.
This method executes a command by calling the DLL’s exec method. Direct API methods should be prioritized over calling this method.
Parameters: - self (JLink) – the
JLink
instance - cmd (str) – the command to run
Returns: The return code of running the command.
Raises: JLinkException
– if the command is invalid or fails.See also
For a full list of the supported commands, please see the SEGGER J-Link documentation, UM08001.
- self (JLink) – the
-
extended_capabilities
¶ Gets the capabilities of the connected emulator as a list.
Parameters: self (JLink) – the JLink
instanceReturns: List of 32 integers which define the extended capabilities based on their value and index within the list.
-
extended_capability
(*args, **kwargs)¶ Checks if the emulator has the given extended capability.
Parameters: - self (JLink) – the
JLink
instance - capability (int) – capability being queried
Returns: True
if the emulator has the given extended capability, otherwiseFalse
.- self (JLink) – the
-
features
¶ Returns a list of the J-Link embedded features.
Parameters: self (JLink) – the JLink
instanceReturns: [ 'RDI', 'FlashBP', 'FlashDL', 'JFlash', 'GDB' ]
Return type: A list of strings, each a feature. Example
-
firmware_newer
(*args, **kwargs)¶ Returns whether the J-Link’s firmware version is newer than the one that the DLL is compatible with.
Note
This is not the same as calling
not jlink.firmware_outdated()
.Parameters: self (JLink) – the JLink
instanceReturns: True
if the J-Link’s firmware is newer than the one supported by the DLL, otherwiseFalse
.
-
firmware_outdated
(*args, **kwargs)¶ Returns whether the J-Link’s firmware version is older than the one that the DLL is compatible with.
Note
This is not the same as calling
not jlink.firmware_newer()
.Parameters: self (JLink) – the JLink
instanceReturns: True
if the J-Link’s firmware is older than the one supported by the DLL, otherwiseFalse
.
-
firmware_version
¶ Returns a firmware identification string of the connected J-Link.
- It consists of the following:
- Product Name (e.g. J-Link)
- The string: compiled
- Compile data and time.
- Optional additional information.
Parameters: self (JLink) – the JLink
instanceReturns: Firmware identification string.
-
flash
(*args, **kwargs)¶ Flashes the target device.
The given
on_progress
callback will be called ason_progress(action, progress_string, percentage)
periodically as the data is written to flash. The action is one ofCompare
,Erase
,Verify
,Flash
.Parameters: - self (JLink) – the
JLink
instance - data (list) – list of bytes to write to flash
- addr (int) – start address on flash which to write the data
- on_progress (function) – callback to be triggered on flash progress
- power_on (boolean) – whether to power the target before flashing
- flags (int) – reserved, do not use
Returns: Number of bytes flashed. This number may not necessarily be equal to
len(data)
, but that does not indicate an error.Raises: JLinkException
– on hardware errors.- self (JLink) – the
-
flash_file
(*args, **kwargs)¶ Flashes the target device.
The given
on_progress
callback will be called ason_progress(action, progress_string, percentage)
periodically as the data is written to flash. The action is one ofCompare
,Erase
,Verify
,Flash
.Parameters: - self (JLink) – the
JLink
instance - path (str) – absolute path to the source file to flash
- addr (int) – start address on flash which to write the data
- on_progress (function) – callback to be triggered on flash progress
- power_on (boolean) – whether to power the target before flashing
Returns: Integer value greater than or equal to zero. Has no significance.
Raises: JLinkException
– on hardware errors.- self (JLink) – the
-
flash_write
(*args, **kwargs)¶ Writes data to the flash region of a device.
The given number of bits, if provided, must be either
8
,16
, or32
.Parameters: - self (JLink) – the
JLink
instance - addr (int) – starting flash address to write to
- data (list) – list of data units to write
- nbits (int) – number of bits to use for each unit
Returns: Number of bytes written to flash.
- self (JLink) – the
-
flash_write16
(*args, **kwargs)¶ Writes halfwords to the flash region of a device.
Parameters: - self (JLink) – the
JLink
instance - addr (int) – starting flash address to write to
- data (list) – list of halfwords to write
Returns: Number of bytes written to flash.
- self (JLink) – the
-
flash_write32
(*args, **kwargs)¶ Writes words to the flash region of a device.
Parameters: - self (JLink) – the
JLink
instance - addr (int) – starting flash address to write to
- data (list) – list of words to write
Returns: Number of bytes written to flash.
- self (JLink) – the
-
flash_write8
(*args, **kwargs)¶ Writes bytes to the flash region of a device.
Parameters: - self (JLink) – the
JLink
instance - addr (int) – starting flash address to write to
- data (list) – list of bytes to write
Returns: Number of bytes written to flash.
- self (JLink) – the
-
get_device_index
(chip_name)¶ Finds index of device with chip name
Parameters: - self (JLink) – the
JLink
instance - chip_name (str) – target chip name
Returns: Index of the device with the matching chip name.
Raises: JLinkException
– if chip is unsupported.- self (JLink) – the
-
gpio_get
(*args, **kwargs)¶ Returns a list of states for the given pins.
Defaults to the first four pins if an argument is not given.
Parameters: - self (JLink) – the
JLink
instance - pins (list) – indices of the GPIO pins whose states are requested
Returns: A list of states.
Raises: JLinkException
– on error.- self (JLink) – the
-
gpio_properties
(*args, **kwargs)¶ Returns the properties of the user-controllable GPIOs.
Provided the device supports user-controllable GPIOs, they will be returned by this method.
Parameters: self (JLink) – the JLink
instanceReturns: A list of JLinkGPIODescriptor
instances totalling the number of requested properties.Raises: JLinkException
– on error.
-
gpio_set
(*args, **kwargs)¶ Sets the state for one or more user-controllable GPIOs.
For each of the given pins, sets the the corresponding state based on the index.
Parameters: - self (JLink) – the
JLink
instance - pins (list) – list of GPIO indices
- states (list) – list of states to set
Returns: A list of updated states.
Raises: JLinkException
– on error.ValueError
– iflen(pins) != len(states)
- self (JLink) – the
-
halt
(*args, **kwargs)¶ Halts the CPU Core.
Parameters: self (JLink) – the JLink
instanceReturns: True
if halted,False
otherwise.
-
halted
(*args, **kwargs)¶ Returns whether the CPU core was halted.
Parameters: self (JLink) – the JLink
instanceReturns: True
if the CPU core is halted, otherwiseFalse
.Raises: JLinkException
– on device errors.
-
hardware_breakpoint_set
(*args, **kwargs)¶ Sets a hardware breakpoint at the specified address.
If
thumb
isTrue
, the breakpoint is set in THUMB-mode, while ifarm
isTrue
, the breakpoint is set in ARM-mode, otherwise a normal breakpoint is set.Parameters: - self (JLink) – the
JLink
instance - addr (int) – the address where the breakpoint will be set
- thumb (bool) – boolean indicating to set the breakpoint in THUMB mode
- arm (bool) – boolean indicating to set the breakpoint in ARM mode
Returns: An integer specifying the breakpoint handle. This handle should sbe retained for future breakpoint operations.
Raises: TypeError
– if the given address is not an integer.JLinkException
– if the breakpoint could not be set.
- self (JLink) – the
-
hardware_info
¶ Returns a list of 32 integer values corresponding to the bitfields specifying the power consumption of the target.
The values returned by this function only have significance if the J-Link is powering the target.
- The words, indexed, have the following significance:
- If
1
, target is powered via J-Link. - Overcurrent bitfield: 0: No overcurrent. 1: Overcurrent happened. 2ms @ 3000mA 2: Overcurrent happened. 10ms @ 1000mA 3: Overcurrent happened. 40ms @ 400mA
- Power consumption of target (mA).
- Peak of target power consumption (mA).
- Peak of target power consumption during J-Link operation (mA).
- If
Parameters: - self (JLink) – the
JLink
instance - mask (int) – bit mask to decide which hardware information words are returned (defaults to all the words).
Returns: List of bitfields specifying different states based on their index within the list and their value.
Raises: JLinkException
– on hardware error.
-
hardware_status
¶ Retrieves and returns the hardware status.
Parameters: self (JLink) – the JLink
instanceReturns: A JLinkHardwareStatus
describing the J-Link hardware.
-
hardware_version
¶ Returns the hardware version of the connected J-Link as a major.minor string.
Parameters: self (JLink) – the JLink
instanceReturns: Hardware version string.
-
ice_register_read
(*args, **kwargs)¶ Reads a value from an ARM ICE register.
Parameters: - self (JLink) – the
JLink
instance - register_index (int) – the register to read
Returns: The value read from the register.
- self (JLink) – the
-
ice_register_write
(*args, **kwargs)¶ Writes a value to an ARM ICE register.
Parameters: - self (JLink) – the
JLink
instance - register_index (int) – the ICE register to write to
- value (int) – the value to write to the ICE register
- delay (bool) – boolean specifying if the write should be delayed
Returns: None
- self (JLink) – the
-
index
¶ Retrieves and returns the index number of the actual selected J-Link.
Parameters: self (JLink) – the JLink
instanceReturns: Index of the currently connected J-Link.
-
interface_required
(interface)¶ Decorator to specify that a particular interface type is required for the given method to be used.
Parameters: interface (int) – attribute of JLinkInterfaces
Returns: A decorator function.
-
invalidate_firmware
(*args, **kwargs)¶ Invalidates the emulator’s firmware.
This method is useful for downgrading the firmware on an emulator. By calling this method, the current emulator’s firmware is invalidated, which will make the emulator download the firmware of the J-Link SDK DLL that this instance was created with.
Parameters: self (JLink) – the JLink
instanceReturns: None
Raises: JLinkException
– on hardware error.
-
ir_len
(*args, **kwargs)¶ Counts and returns the total length of instruction registers of all the devices in the JTAG scan chain.
Parameters: self (JLink) – the JLink
instanceReturns: Total instruction register length.
-
jtag_configure
(*args, **kwargs)¶ Configures the JTAG scan chain to determine which CPU to address.
Must be called if the J-Link is connected to a JTAG scan chain with multiple devices.
Parameters: - self (JLink) – the
JLink
instance - instr_regs (int) – length of instruction registers of all devices closer to TD1 then the addressed CPU
- data_bits (int) – total number of data bits closer to TD1 than the addressed CPU
Returns: None
Raises: ValueError
– ifinstr_regs
ordata_bits
are not natural numbers- self (JLink) – the
-
jtag_create_clock
(*args, **kwargs)¶ Creates a JTAG clock on TCK.
Note
This function only needs to be called once.
Parameters: self (JLink) – the JLink
instanceReturns: either 0
or1
.Return type: The state of the TDO pin
-
jtag_flush
(*args, **kwargs)¶ Flushes the internal JTAG buffer.
Note
The buffer is automatically flushed when a response from the target is expected, or the buffer is full. This can be used after a
memory_write()
in order to flush the buffer.Parameters: self (JLink) – the JLink
instanceReturns: None
-
jtag_send
(*args, **kwargs)¶ Sends data via JTAG.
Sends data via JTAG on the rising clock edge, TCK. At on each rising clock edge, on bit is transferred in from TDI and out to TDO. The clock uses the TMS to step through the standard JTAG state machine.
Parameters: - self (JLink) – the
JLink
instance - tms (int) – used to determine the state transitions for the Test Access Port (TAP) controller from its current state
- tdi (int) – input data to be transferred in from TDI to TDO
- num_bits (int) – a number in the range
[1, 32]
inclusively specifying the number of meaningful bits in thetms
andtdi
parameters for the purpose of extracting state and data information
Returns: None
Raises: ValueError
– ifnum_bits < 1
ornum_bits > 32
.See also
- self (JLink) – the
-
licenses
¶ Returns a string of the built-in licenses the J-Link has.
Parameters: self (JLink) – the JLink
instanceReturns: String of the contents of the built-in licenses the J-Link has.
-
log_handler
¶ Returns the log handler function.
Parameters: self (JLink) – the JLink
instanceReturns: None
if the log handler was not set, otherwise actypes.CFUNCTYPE
.
-
memory_read
(*args, **kwargs)¶ Reads memory from a target system or specific memory zone.
The optional
zone
specifies a memory zone to access to read from, e.g.IDATA
,DDATA
, orCODE
.The given number of bits, if provided, must be either
8
,16
, or32
. If not provided, always readsnum_units
bytes.Parameters: - self (JLink) – the
JLink
instance - addr (int) – start address to read from
- num_units (int) – number of units to read
- zone (str) – optional memory zone name to access
- nbits (int) – number of bits to use for each unit
Returns: List of units read from the target system.
Raises: JLinkException
– if memory could not be read.ValueError
– ifnbits
is notNone
, and not in8
,16
, or32
.
- self (JLink) – the
-
memory_read16
(*args, **kwargs)¶ Reads memory from the target system in units of 16-bits.
Parameters: - self (JLink) – the
JLink
instance - addr (int) – start address to read from
- num_halfwords (int) – number of half words to read
- zone (str) – memory zone to read from
Returns: List of halfwords read from the target system.
Raises: JLinkException
– if memory could not be read- self (JLink) – the
-
memory_read32
(*args, **kwargs)¶ Reads memory from the target system in units of 32-bits.
Parameters: - self (JLink) – the
JLink
instance - addr (int) – start address to read from
- num_words (int) – number of words to read
- zone (str) – memory zone to read from
Returns: List of words read from the target system.
Raises: JLinkException
– if memory could not be read- self (JLink) – the
-
memory_read64
(*args, **kwargs)¶ Reads memory from the target system in units of 64-bits.
Parameters: - self (JLink) – the
JLink
instance - addr (int) – start address to read from
- num_long_words (int) – number of long words to read
Returns: List of long words read from the target system.
Raises: JLinkException
– if memory could not be read- self (JLink) – the
-
memory_read8
(*args, **kwargs)¶ Reads memory from the target system in units of bytes.
Parameters: - self (JLink) – the
JLink
instance - addr (int) – start address to read from
- num_bytes (int) – number of bytes to read
- zone (str) – memory zone to read from
Returns: List of bytes read from the target system.
Raises: JLinkException
– if memory could not be read.- self (JLink) – the
-
memory_write
(*args, **kwargs)¶ Writes memory to a target system or specific memory zone.
The optional
zone
specifies a memory zone to access to write to, e.g.IDATA
,DDATA
, orCODE
.The given number of bits, if provided, must be either
8
,16
, or32
.Parameters: - self (JLink) – the
JLink
instance - addr (int) – start address to write to
- data (list) – list of data units to write
- zone (str) – optional memory zone name to access
- nbits (int) – number of bits to use for each unit
Returns: Number of units written.
Raises: JLinkException
– on write hardware failure.ValueError
– ifnbits
is notNone
, and not in8
,16
or32
.
- self (JLink) – the
-
memory_write16
(*args, **kwargs)¶ Writes half-words to memory of a target system.
Parameters: - self (JLink) – the
JLink
instance - addr (int) – start address to write to
- data (list) – list of half-words to write
- zone (str) – optional memory zone to access
Returns: Number of half-words written to target.
Raises: JLinkException
– on memory access error.- self (JLink) – the
-
memory_write32
(*args, **kwargs)¶ Writes words to memory of a target system.
Parameters: - self (JLink) – the
JLink
instance - addr (int) – start address to write to
- data (list) – list of words to write
- zone (str) – optional memory zone to access
Returns: Number of words written to target.
Raises: JLinkException
– on memory access error.- self (JLink) – the
-
memory_write64
(*args, **kwargs)¶ Writes long words to memory of a target system.
Note
This is little-endian.
Parameters: - self (JLink) – the
JLink
instance - addr (int) – start address to write to
- data (list) – list of long words to write
- zone (str) – optional memory zone to access
Returns: Number of long words written to target.
Raises: JLinkException
– on memory access error.- self (JLink) – the
-
memory_write8
(*args, **kwargs)¶ Writes bytes to memory of a target system.
Parameters: - self (JLink) – the
JLink
instance - addr (int) – start address to write to
- data (list) – list of bytes to write
- zone (str) – optional memory zone to access
Returns: Number of bytes written to target.
Raises: JLinkException
– on memory access error.- self (JLink) – the
-
memory_zones
(*args, **kwargs)¶ Gets all memory zones supported by the current target.
Some targets support multiple memory zones. This function provides the ability to get a list of all the memory zones to facilate using the memory zone routing functions.
Parameters: self (JLink) – the JLink
instanceReturns: A list of all the memory zones as JLinkMemoryZone
structures.Raises: JLinkException
– on hardware errors.
-
minimum_required
(version)¶ Decorator to specify the minimum SDK version required.
Parameters: version (str) – valid version string Returns: A decorator function.
-
num_active_breakpoints
(*args, **kwargs)¶ Returns the number of currently active breakpoints.
Parameters: self (JLink) – the JLink
instanceReturns: The number of breakpoints that are currently set.
-
num_active_watchpoints
(*args, **kwargs)¶ Returns the number of currently active watchpoints.
Parameters: self (JLink) – the JLink
instanceReturns: The number of watchpoints that are currently set.
-
num_available_breakpoints
(*args, **kwargs)¶ Returns the number of available breakpoints of the specified type.
If
arm
is set, gets the number of available ARM breakpoint units. Ifthumb
is set, gets the number of available THUMB breakpoint units. Ifram
is set, gets the number of available software RAM breakpoint units. Ifflash
is set, gets the number of available software flash breakpoint units. Ifhw
is set, gets the number of available hardware breakpoint units.If a combination of the flags is given, then
num_available_breakpoints()
returns the number of breakpoints specified by the given flags. If no flags are specified, then the count of available breakpoint units is returned.Parameters: - self (JLink) – the
JLink
instance - arm (bool) – Boolean indicating to get number of ARM breakpoints.
- thumb (bool) – Boolean indicating to get number of THUMB breakpoints.
- ram (bool) – Boolean indicating to get number of SW RAM breakpoints.
- flash (bool) – Boolean indicating to get number of Flash breakpoints.
- hw (bool) – Boolean indicating to get number of Hardware breakpoints.
Returns: The number of available breakpoint units of the specified type.
- self (JLink) – the
-
num_available_watchpoints
(*args, **kwargs)¶ Returns the number of available watchpoints.
Parameters: self (JLink) – the JLink
instanceReturns: The number of watchpoints that are available to be set.
-
num_connected_emulators
()¶ Returns the number of emulators which are connected via USB to the host.
Parameters: self (JLink) – the JLink
instanceReturns: The number of connected emulators.
-
num_memory_zones
(*args, **kwargs)¶ Returns the number of memory zones supported by the target.
Parameters: self (JLink) – the JLink
instanceReturns: An integer count of the number of memory zones supported by the target. Raises: JLinkException
– on error.
-
num_supported_devices
()¶ Returns the number of devices that are supported by the opened J-Link DLL.
Parameters: self (JLink) – the JLink
instanceReturns: Number of devices the J-Link DLL supports.
-
oem
¶ Retrieves and returns the OEM string of the connected J-Link.
Parameters: self (JLink) – the JLink
instanceReturns: The string of the OEM. If this is an original SEGGER product, then None
is returned instead.Raises: JLinkException
– on hardware error.
-
open
(serial_no=None, ip_addr=None)¶ Connects to the J-Link emulator (defaults to USB).
If
serial_no
andip_addr
are both given, this function will connect to the J-Link over TCP/IP.Parameters: - self (JLink) – the
JLink
instance - serial_no (int) – serial number of the J-Link
- ip_addr (str) – IP address and port of the J-Link (e.g. 192.168.1.1:80)
Returns: None
Raises: JLinkException
– if fails to open (i.e. if device is unplugged)TypeError
– ifserial_no
is present, but notint
coercible.AttributeError
– ifserial_no
andip_addr
are bothNone
.
- self (JLink) – the
-
open_required
(func)¶ Decorator to specify that the J-Link DLL must be opened, and a J-Link connection must be established.
Parameters: func (function) – function being decorated Returns: The wrapper function.
-
open_tunnel
(serial_no, port=19020)¶ Connects to the J-Link emulator (over SEGGER tunnel).
Parameters: - self (JLink) – the
JLink
instance - serial_no (int) – serial number of the J-Link
- port (int) – optional port number (default to 19020).
Returns: None
- self (JLink) – the
-
opened
()¶ Returns whether the DLL is open.
Parameters: self (JLink) – the JLink
instanceReturns: True
if the J-Link is open, otherwiseFalse
.
-
power_off
(*args, **kwargs)¶ Turns off the power supply over pin 19 of the JTAG connector.
If given the optional
default
parameter, deactivates the power supply by default.Parameters: - self (JLink) – the
JLink
instance - default (bool) – boolean indicating if to set power off by default
Returns: The current
JLink
instanceRaises: JLinkException
– if J-Link does not support powering the target.- self (JLink) – the
-
power_on
(*args, **kwargs)¶ Turns on the power supply over pin 19 of the JTAG connector.
If given the optional
default
parameter, activates the power supply by default.Parameters: - self (JLink) – the
JLink
instance - default (bool) – boolean indicating if to set power by default
Returns: None
Raises: JLinkException
– if J-Link does not support powering the target.- self (JLink) – the
-
product_name
¶ Returns the product name of the connected J-Link.
Parameters: self (JLink) – the JLink
instanceReturns: Product name.
-
register_list
(*args, **kwargs)¶ Returns a list of the indices for the CPU registers.
The returned indices can be used to read the register content or grab the register name.
Parameters: self (JLink) – the JLink
instanceReturns: List of registers.
-
register_name
(*args, **kwargs)¶ Retrives and returns the name of an ARM CPU register.
Parameters: - self (JLink) – the
JLink
instance - register_index (int) – index of the register whose name to retrieve
Returns: Name of the register.
- self (JLink) – the
-
register_read
(*args, **kwargs)¶ Reads the value from the given register.
Parameters: - self (JLink) – the
JLink
instance - register_index (int/str) – the register to read
Returns: The value stored in the given register.
- self (JLink) – the
-
register_read_multiple
(*args, **kwargs)¶ Retrieves the values from the registers specified.
Parameters: - self (JLink) – the
JLink
instance - register_indices (list) – list of registers to read
Returns: A list of values corresponding one-to-one for each of the given register indices. The returned list of values are the values in order of which the indices were specified.
Raises: JLinkException
– if a given register is invalid or an error occurs.- self (JLink) – the
-
register_write
(*args, **kwargs)¶ Writes into an ARM register.
Note
The data is not immediately written, but is cached before being transferred to the CPU on CPU start.
Parameters: - self (JLink) – the
JLink
instance - reg_index (int/str) – the ARM register to write to
- value (int) – the value to write to the register
Returns: The value written to the ARM register.
Raises: JLinkException
– on write error.- self (JLink) – the
-
register_write_multiple
(*args, **kwargs)¶ Writes to multiple CPU registers.
Writes the values to the given registers in order. There must be a one-to-one correspondence between the values and the registers specified.
Parameters: - self (JLink) – the
JLink
instance - register_indices (list) – list of registers to write to
- values (list) – list of values to write to the registers
Returns: None
Raises: ValueError
– iflen(register_indices) != len(values)
JLinkException
– if a register could not be written to or on error
- self (JLink) – the
-
reset
(*args, **kwargs)¶ Resets the target.
This method resets the target, and by default toggles the RESET and TRST pins.
Parameters: - self (JLink) – the
JLink
instance - ms (int) – Amount of milliseconds to delay after reset (default: 0)
- halt (bool) – if the CPU should halt after reset (default: True)
Returns: Number of bytes read.
- self (JLink) – the
-
reset_tap
(*args, **kwargs)¶ Resets the TAP controller via TRST.
Note
This must be called at least once after power up if the TAP controller is to be used.
Parameters: self (JLink) – the JLink
instanceReturns: None
-
restart
(*args, **kwargs)¶ Restarts the CPU core and simulates/emulates instructions.
Note
This is a no-op if the CPU isn’t halted.
Parameters: - self (JLink) – the
JLink
instance - num_instructions (int) – number of instructions to simulate, defaults to zero
- skip_breakpoints (bool) – skip current breakpoint (default:
False
)
Returns: True
if device was restarted, otherwiseFalse
.Raises: ValueError
– if instruction count is not a natural number.- self (JLink) – the
-
rtt_control
(*args, **kwargs)¶ Issues an RTT Control command.
All RTT control is done through a single API call which expects specifically laid-out configuration structures.
Parameters: - self (JLink) – the
JLink
instance - command (int) – the command to issue (see enums.JLinkRTTCommand)
- config (ctypes type) – the configuration to pass by reference.
Returns: An integer containing the result of the command.
Raises: JLinkRTTException
– on error.- self (JLink) – the
-
rtt_get_buf_descriptor
(*args, **kwargs)¶ After starting RTT, get the descriptor for an RTT control block.
Parameters: - self (JLink) – the
JLink
instance - buffer_index (int) – the index of the buffer to get.
- up (bool) –
True
if buffer is an UP buffer, otherwiseFalse
.
Returns: JLinkRTTerminalBufDesc
describing the buffer.Raises: JLinkRTTException
– if the RTT control block has not yet been found.- self (JLink) – the
-
rtt_get_num_down_buffers
(*args, **kwargs)¶ After starting RTT, get the current number of down buffers.
Parameters: self (JLink) – the JLink
instanceReturns: The number of configured down buffers on the target. Raises: JLinkRTTException
– if the underlying JLINK_RTTERMINAL_Control call fails.
-
rtt_get_num_up_buffers
(*args, **kwargs)¶ After starting RTT, get the current number of up buffers.
Parameters: self (JLink) – the JLink
instanceReturns: The number of configured up buffers on the target. Raises: JLinkRTTException
– if the underlying JLINK_RTTERMINAL_Control call fails.
-
rtt_get_status
(*args, **kwargs)¶ After starting RTT, get the status.
Parameters: self (JLink) – the JLink
instanceReturns: The status of RTT. Raises: JLinkRTTException
– on error.
-
rtt_read
(*args, **kwargs)¶ Reads data from the RTT buffer.
This method will read at most num_bytes bytes from the specified RTT buffer. The data is automatically removed from the RTT buffer. If there are not num_bytes bytes waiting in the RTT buffer, the entire contents of the RTT buffer will be read.
Parameters: - self (JLink) – the
JLink
instance - buffer_index (int) – the index of the RTT buffer to read from
- num_bytes (int) – the maximum number of bytes to read
Returns: A list of bytes read from RTT.
Raises: JLinkRTTException
– if the underlying JLINK_RTTERMINAL_Read call fails.- self (JLink) – the
-
rtt_start
(*args, **kwargs)¶ Starts RTT processing, including background read of target data.
Parameters: - self (JLink) – the
JLink
instance - block_address (int) – optional configuration address for the RTT block
Returns: None
Raises: JLinkRTTException
– if the underlying JLINK_RTTERMINAL_Control call fails.- self (JLink) – the
-
rtt_stop
(*args, **kwargs)¶ Stops RTT on the J-Link and host side.
Parameters: self (JLink) – the JLink
instanceReturns: None
Raises: JLinkRTTException
– if the underlying JLINK_RTTERMINAL_Control call fails.
-
rtt_write
(*args, **kwargs)¶ Writes data to the RTT buffer.
This method will write at most len(data) bytes to the specified RTT buffer.
Parameters: - self (JLink) – the
JLink
instance - buffer_index (int) – the index of the RTT buffer to write to
- data (list) – the list of bytes to write to the RTT buffer
Returns: The number of bytes successfully written to the RTT buffer.
Raises: JLinkRTTException
– if the underlying JLINK_RTTERMINAL_Write call fails.- self (JLink) – the
-
scan_chain_len
(*args, **kwargs)¶ Retrieves and returns the number of bits in the scan chain.
Parameters: - self (JLink) – the
JLink
instance - scan_chain (int) – scan chain to be measured
Returns: Number of bits in the specified scan chain.
Raises: JLinkException
– on error.- self (JLink) – the
-
scan_len
(*args, **kwargs)¶ Retrieves and returns the length of the scan chain select register.
Parameters: self (JLink) – the JLink
instanceReturns: Length of the scan chain select register.
-
serial_number
¶ Returns the serial number of the connected J-Link.
Parameters: self (JLink) – the JLink
instanceReturns: Serial number as an integer.
-
set_big_endian
(*args, **kwargs)¶ Sets the target hardware to big endian.
Parameters: self (JLink) – the JLink
instanceReturns: True
if target was little endian before call, otherwiseFalse
.
-
set_etb_trace
(*args, **kwargs)¶ Sets the trace source to ETB.
Parameters: self (JLink) – the JLink
instance.Returns: None
-
set_etm_trace
(*args, **kwargs)¶ Sets the trace source to ETM.
Parameters: self (JLink) – the JLink
instance.Returns: None
-
set_little_endian
(*args, **kwargs)¶ Sets the target hardware to little endian.
Parameters: self (JLink) – the JLink
instanceReturns: True
if target was big endian before call, otherwiseFalse
.
-
set_log_file
(*args, **kwargs)¶ Sets the log file output path. see https://wiki.segger.com/Enable_J-Link_log_file
Parameters: - self (JLink) – the
JLink
instance - file_path (str) – the file path where the log file will be stored
Returns: None
Raises: JLinkException
– if the path specified is invalid.- self (JLink) – the
-
set_max_speed
(*args, **kwargs)¶ Sets JTAG communication speed to the maximum supported speed.
Parameters: self (JLink) – the JLink
instanceReturns: None
-
set_reset_pin_high
(*args, **kwargs)¶ Sets the reset pin high.
Parameters: self (JLink) – the JLink
instanceReturns: None
-
set_reset_pin_low
(*args, **kwargs)¶ Sets the reset pin low.
Parameters: self (JLink) – the JLink
instanceReturns: None
-
set_reset_strategy
(*args, **kwargs)¶ Sets the reset strategy for the target.
The reset strategy defines what happens when the target is reset.
Parameters: - self (JLink) – the
JLink
instance - strategy (int) – the reset strategy to use
Returns: The previous reset streategy.
- self (JLink) – the
-
set_speed
(*args, **kwargs)¶ Sets the speed of the JTAG communication with the ARM core.
If no arguments are present, automatically detects speed.
If a
speed
is provided, the speed must be no larger thanJLink.MAX_JTAG_SPEED
and no smaller thanJLink.MIN_JTAG_SPEED
. The givenspeed
can also not beJLink.INVALID_JTAG_SPEED
.Parameters: - self (JLink) – the
JLink
instance - speed (int) – the speed in kHz to set the communication at
- auto (bool) – automatically detect correct speed
- adaptive (bool) – select adaptive clocking as JTAG speed
Returns: None
Raises: TypeError
– if given speed is not a natural number.ValueError
– if given speed is too high, too low, or invalid.
- self (JLink) – the
-
set_tck_pin_high
(*args, **kwargs)¶ Sets the TCK pin to the high value (1).
Parameters: self (JLink) – the JLink
instanceReturns: None
Raises: JLinkException
– if the emulator does not support this feature.
-
set_tck_pin_low
(*args, **kwargs)¶ Sets the TCK pin to the low value (0).
Parameters: self (JLink) – the JLink
instanceReturns: None
Raises: JLinkException
– if the emulator does not support this feature.
-
set_tdi_pin_high
(*args, **kwargs)¶ Sets the test data input to logical
1
.Parameters: self (JLink) – the JLink
instanceReturns: None
-
set_tdi_pin_low
(*args, **kwargs)¶ Clears the test data input.
TDI is set to logical
0
(Ground).Parameters: self (JLink) – the JLink
instanceReturns: None
-
set_tif
(*args, **kwargs)¶ Selects the specified target interface.
Note that a restart must be triggered for this to take effect.
Parameters: - self (Jlink) – the
JLink
instance - interface (int) – integer identifier of the interface
Returns: True
if target was updated, otherwiseFalse
.Raises: JLinkException
– if the given interface is invalid or unsupported.- self (Jlink) – the
-
set_tms_pin_high
(*args, **kwargs)¶ Sets the test mode select to logical
1
.Parameters: self (JLink) – the JLink
instanceReturns: None
-
set_tms_pin_low
(*args, **kwargs)¶ Clears the test mode select.
TMS is set to logical
0
(Ground).Parameters: self (JLink) – the JLink
instanceReturns: None
-
set_trace_source
(*args, **kwargs)¶ Sets the source to be used for tracing.
The
source
must be one of the ones provided byenums.JLinkTraceSource
.Parameters: - self (JLink) – the
JLink
instance. - source (int) – the source to use.
Returns: None
- self (JLink) – the
-
set_trst_pin_high
(*args, **kwargs)¶ Sets the TRST pin to high (
1
).Deasserts the TRST pin.
Parameters: self (JLink) – the JLink
instanceReturns: None
-
set_trst_pin_low
(*args, **kwargs)¶ Sets the TRST pin to low (
0
).This asserts the TRST pin.
Parameters: self (JLink) – the JLink
instanceReturns: None
-
set_vector_catch
(*args, **kwargs)¶ Sets vector catch bits of the processor.
The CPU will jump to a vector if the given vector catch is active, and will enter a debug state. This has the effect of halting the CPU as well, meaning the CPU must be explicitly restarted.
Parameters: self (JLink) – the JLink
instanceReturns: None
Raises: JLinkException
– on error.
-
software_breakpoint_set
(*args, **kwargs)¶ Sets a software breakpoint at the specified address.
If
thumb
isTrue
, the breakpoint is set in THUMB-mode, while ifarm
isTrue
, the breakpoint is set in ARM-mode, otherwise a normal breakpoint is set.If
flash
isTrue
, the breakpoint is set in flash, otherwise ifram
isTrue
, the breakpoint is set in RAM. If both areTrue
or both areFalse
, then the best option is chosen for setting the breakpoint in software.Parameters: - self (JLink) – the
JLink
instance - addr (int) – the address where the breakpoint will be set
- thumb (bool) – boolean indicating to set the breakpoint in THUMB mode
- arm (bool) – boolean indicating to set the breakpoint in ARM mode
- flash (bool) – boolean indicating to set the breakpoint in flash
- ram (bool) – boolean indicating to set the breakpoint in RAM
Returns: An integer specifying the breakpoint handle. This handle should sbe retained for future breakpoint operations.
Raises: TypeError
– if the given address is not an integer.JLinkException
– if the breakpoint could not be set.
- self (JLink) – the
-
speed
¶ Returns the current JTAG connection speed.
Parameters: self (JLink) – the JLink
instanceReturns: JTAG connection speed.
-
speed_info
¶ Retrieves information about supported target interface speeds.
Parameters: self (JLink) – the JLink
instanceReturns: The JLinkSpeedInfo
instance describing the supported target interface speeds.
-
step
(*args, **kwargs)¶ Executes a single step.
Steps even if there is a breakpoint.
Parameters: - self (JLink) – the
JLink
instance - thumb (bool) – boolean indicating if to step in thumb mode
Returns: None
Raises: JLinkException
– on error- self (JLink) – the
-
strace_clear
(*args, **kwargs)¶ Clears the trace event specified by the given handle.
Parameters: - self (JLink) – the
JLink
instance. - handle (int) – handle of the trace event.
Returns: None
Raises: JLinkException
– on error.- self (JLink) – the
-
strace_clear_all
(*args, **kwargs)¶ Clears all STRACE events.
Parameters: self (JLink) – the JLink
instance.Returns: None
Raises: JLinkException
– on error.
-
strace_code_fetch_event
(*args, **kwargs)¶ Sets an event to trigger trace logic when an instruction is fetched.
Parameters: - self (JLink) – the
JLink
instance. - operation (int) – one of the operations in
JLinkStraceOperation
. - address (int) – the address of the instruction that is fetched.
- address_range (int) – optional range of address to trigger event on.
Returns: An integer specifying the trace event handle. This handle should be retained in order to clear the event at a later time.
Raises: JLinkException
– on error.- self (JLink) – the
-
strace_configure
(*args, **kwargs)¶ Configures the trace port width for tracing.
Note that configuration cannot occur while STRACE is running.
Parameters: - self (JLink) – the
JLink
instance - port_width (int) – the trace port width to use.
Returns: None
Raises: ValueError
– ifport_width
is not1
,2
, or4
.JLinkException
– on error.
- self (JLink) – the
-
strace_data_access_event
(*args, **kwargs)¶ Sets an event to trigger trace logic when data access is made.
Data access corresponds to either a read or write.
Parameters: - self (JLink) – the
JLink
instance. - operation (int) – one of the operations in
JLinkStraceOperation
. - address (int) – the address of the load/store data.
- data (int) – the data to be compared the event data to.
- data_mask (int) – optional bitmask specifying bits to ignore in comparison.
- acess_width (int) – optional access width for the data.
- address_range (int) – optional range of address to trigger event on.
Returns: An integer specifying the trace event handle. This handle should be retained in order to clear the event at a later time.
Raises: JLinkException
– on error.- self (JLink) – the
-
strace_data_load_event
(*args, **kwargs)¶ Sets an event to trigger trace logic when data read access is made.
Parameters: - self (JLink) – the
JLink
instance. - operation (int) – one of the operations in
JLinkStraceOperation
. - address (int) – the address of the load data.
- address_range (int) – optional range of address to trigger event on.
Returns: An integer specifying the trace event handle. This handle should be retained in order to clear the event at a later time.
Raises: JLinkException
– on error.- self (JLink) – the
-
strace_data_store_event
(*args, **kwargs)¶ Sets an event to trigger trace logic when data write access is made.
Parameters: - self (JLink) – the
JLink
instance. - operation (int) – one of the operations in
JLinkStraceOperation
. - address (int) – the address of the store data.
- address_range (int) – optional range of address to trigger event on.
Returns: An integer specifying the trace event handle. This handle should be retained in order to clear the event at a later time.
Raises: JLinkException
– on error.- self (JLink) – the
-
strace_read
(*args, **kwargs)¶ Reads and returns a number of instructions captured by STRACE.
The number of instructions must be a non-negative value of at most
0x10000
(65536
).Parameters: - self (JLink) – the
JLink
instance. - num_instructions (int) – number of instructions to fetch.
Returns: A list of instruction addresses in order from most recently executed to oldest executed instructions. Note that the number of instructions returned can be less than the number of instructions requested in the case that there are not
num_instructions
in the trace buffer.Raises: JLinkException
– on error.ValueError
– ifnum_instructions < 0
ornum_instructions > 0x10000
.
- self (JLink) – the
-
strace_set_buffer_size
(*args, **kwargs)¶ Sets the STRACE buffer size.
Parameters: self (JLink) – the JLink
instance.Returns: None
Raises: JLinkException
– on error.
-
strace_start
(*args, **kwargs)¶ Starts the capturing of STRACE data.
Parameters: self (JLink) – the JLink
instance.Returns: None
Raises: JLinkException
– on error.
-
strace_stop
(*args, **kwargs)¶ Stops the sampling of STRACE data.
Any capturing of STRACE data is automatically stopped when the CPU is halted.
Parameters: self (JLink) – the JLink
instance.Returns: None
Raises: JLinkException
– on error.
-
supported_device
(index=0)¶ Gets the device at the given
index
.Parameters: - self (JLink) – the
JLink
instance - index (int) – the index of the device whose information to get
Returns: A
JLinkDeviceInfo
describing the requested device.Raises: ValueError
– if index is less than 0 or >= supported device count.- self (JLink) – the
-
supported_tifs
(*args, **kwargs)¶ Returns a bitmask of the supported target interfaces.
Parameters: self (JLink) – the JLink
instanceReturns: Bitfield specifying which target interfaces are supported.
-
swd_read16
(*args, **kwargs)¶ Gets a unit of
16
bits from the input buffer.Parameters: - self (JLink) – the
JLink
instance - offset (int) – the offset (in bits) from which to start reading
Returns: The integer read from the input buffer.
- self (JLink) – the
-
swd_read32
(*args, **kwargs)¶ Gets a unit of
32
bits from the input buffer.Parameters: - self (JLink) – the
JLink
instance - offset (int) – the offset (in bits) from which to start reading
Returns: The integer read from the input buffer.
- self (JLink) – the
-
swd_read8
(*args, **kwargs)¶ Gets a unit of
8
bits from the input buffer.Parameters: - self (JLink) – the
JLink
instance - offset (int) – the offset (in bits) from which to start reading
Returns: The integer read from the input buffer.
- self (JLink) – the
-
swd_sync
(*args, **kwargs)¶ Causes a flush to write all data remaining in output buffers to SWD device.
Parameters: - self (JLink) – the
JLink
instance - pad (bool) –
True
if should pad the data to full byte size
Returns: None
- self (JLink) – the
-
swd_write
(*args, **kwargs)¶ Writes bytes over SWD (Serial Wire Debug).
Parameters: - self (JLink) – the
JLink
instance - output (int) – the output buffer offset to write to
- value (int) – the value to write to the output buffer
- nbits (int) – the number of bits needed to represent the
output
andvalue
Returns: The bit position of the response in the input buffer.
- self (JLink) – the
-
swd_write16
(*args, **kwargs)¶ Writes two bytes over SWD (Serial Wire Debug).
Parameters: - self (JLink) – the
JLink
instance - output (int) – the output buffer offset to write to
- value (int) – the value to write to the output buffer
Returns: The bit position of the response in the input buffer.
- self (JLink) – the
-
swd_write32
(*args, **kwargs)¶ Writes four bytes over SWD (Serial Wire Debug).
Parameters: - self (JLink) – the
JLink
instance - output (int) – the output buffer offset to write to
- value (int) – the value to write to the output buffer
Returns: The bit position of the response in the input buffer.
- self (JLink) – the
-
swd_write8
(*args, **kwargs)¶ Writes one byte over SWD (Serial Wire Debug).
Parameters: - self (JLink) – the
JLink
instance - output (int) – the output buffer offset to write to
- value (int) – the value to write to the output buffer
Returns: The bit position of the response in the input buffer.
- self (JLink) – the
-
swo_disable
(*args, **kwargs)¶ Disables ITM & Stimulus ports.
Parameters: - self (JLink) – the
JLink
instance - port_mask (int) – mask specifying which ports to disable
Returns: None
Raises: JLinkException
– on error- self (JLink) – the
-
swo_enable
(*args, **kwargs)¶ Enables SWO output on the target device.
Configures the output protocol, the SWO output speed, and enables any ITM & stimulus ports.
This is equivalent to calling
.swo_start()
.Note
If SWO is already enabled, it will first stop SWO before enabling it again.
Parameters: - self (JLink) – the
JLink
instance - cpu_speed (int) – the target CPU frequency in Hz
- swo_speed (int) – the frequency in Hz used by the target to communicate
- port_mask (int) – port mask specifying which stimulus ports to enable
Returns: None
Raises: JLinkException
– on error- self (JLink) – the
-
swo_enabled
()¶ Returns whether or not SWO is enabled.
Parameters: self (JLink) – the JLink
instanceReturns: True
if SWO is enabled, otherwiseFalse
.
-
swo_flush
(*args, **kwargs)¶ Flushes data from the SWO buffer.
After this method is called, the flushed part of the SWO buffer is empty.
If
num_bytes
is not present, flushes all data currently in the SWO buffer.Parameters: - self (JLink) – the
JLink
instance - num_bytes (int) – the number of bytes to flush
Returns: None
Raises: JLinkException
– on error- self (JLink) – the
-
swo_num_bytes
(*args, **kwargs)¶ Retrives the number of bytes in the SWO buffer.
Parameters: self (JLink) – the JLink
instanceReturns: Number of bytes in the SWO buffer. Raises: JLinkException
– on error
-
swo_read
(*args, **kwargs)¶ Reads data from the SWO buffer.
The data read is not automatically removed from the SWO buffer after reading unless
remove
isTrue
. Otherwise the callee must explicitly remove the data by calling.swo_flush()
.Parameters: - self (JLink) – the
JLink
instance - offset (int) – offset of first byte to be retrieved
- num_bytes (int) – number of bytes to read
- remove (bool) – if data should be removed from buffer after read
Returns: A list of bytes read from the SWO buffer.
- self (JLink) – the
-
swo_read_stimulus
(*args, **kwargs)¶ Reads the printable data via SWO.
This method reads SWO for one stimulus port, which is all printable data.
Note
Stimulus port
0
is used forprintf
debugging.Parameters: - self (JLink) – the
JLink
instance - port (int) – the stimulus port to read from,
0 - 31
- num_bytes (int) – number of bytes to read
Returns: A list of bytes read via SWO.
Raises: ValueError
– ifport < 0
orport > 31
- self (JLink) – the
-
swo_set_emu_buffer_size
(*args, **kwargs)¶ Sets the size of the buffer used by the J-Link to collect SWO data.
Parameters: - self (JLink) – the
JLink
instance - buf_size (int) – the new size of the emulator buffer
Returns: None
Raises: JLinkException
– on error- self (JLink) – the
-
swo_set_host_buffer_size
(*args, **kwargs)¶ Sets the size of the buffer used by the host to collect SWO data.
Parameters: - self (JLink) – the
JLink
instance - buf_size (int) – the new size of the host buffer
Returns: None
Raises: JLinkException
– on error- self (JLink) – the
-
swo_speed_info
(*args, **kwargs)¶ Retrieves information about the supported SWO speeds.
Parameters: self (JLink) – the JLink
instanceReturns: A JLinkSWOSpeedInfo
instance describing the target’s supported SWO speeds.Raises: JLinkException
– on error
-
swo_start
(*args, **kwargs)¶ Starts collecting SWO data.
Note
If SWO is already enabled, it will first stop SWO before enabling it again.
Parameters: - self (JLink) – the
JLink
instance - swo_speed (int) – the frequency in Hz used by the target to communicate
Returns: None
Raises: JLinkException
– on error- self (JLink) – the
-
swo_stop
(*args, **kwargs)¶ Stops collecting SWO data.
Parameters: self (JLink) – the JLink
instanceReturns: None
Raises: JLinkException
– on error
-
swo_supported_speeds
(*args, **kwargs)¶ Retrives a list of SWO speeds supported by both the target and the connected J-Link.
The supported speeds are returned in order from highest to lowest.
Parameters: - self (JLink) – the
JLink
instance - cpu_speed (int) – the target’s CPU speed in Hz
- num_speeds (int) – the number of compatible speeds to return
Returns: A list of compatible SWO speeds in Hz in order from highest to lowest.
- self (JLink) – the
-
sync_firmware
(*args, **kwargs)¶ Syncs the emulator’s firmware version and the DLL’s firmware.
This method is useful for ensuring that the firmware running on the J-Link matches the firmware supported by the DLL.
Parameters: self (JLink) – the JLink
instanceReturns: None
-
target_connected
()¶ Returns whether a target is connected to the J-Link.
Parameters: self (JLink) – the JLink
instanceReturns: True
if a target is connected, otherwiseFalse
.
-
test
()¶ Performs a self test.
Parameters: self (JLink) – the JLink
instanceReturns: True
if test passed, otherwiseFalse
.
-
tif
¶ Returns the current target interface of the J-Link.
Parameters: self (JLink) – the JLink
instanceReturns: Integer specifying the current target interface.
-
trace_buffer_capacity
(*args, **kwargs)¶ Retrieves the trace buffer’s current capacity.
Parameters: self (JLink) – the JLink
instance.Returns: The current capacity of the trace buffer. This is not necessarily the maximum possible size the buffer could be configured with.
-
trace_flush
(*args, **kwargs)¶ Flushes the trace buffer.
After this method is called, the trace buffer is empty. This method is best called when the device is reset.
Parameters: self (JLink) – the JLink
instance.Returns: None
-
trace_format
(*args, **kwargs)¶ Retrieves the current format the trace buffer is using.
Parameters: self (JLink) – the JLink
instance.Returns: The current format the trace buffer is using. This is one of the attributes of JLinkTraceFormat
.
-
trace_max_buffer_capacity
(*args, **kwargs)¶ Retrieves the maximum size the trace buffer can be configured with.
Parameters: self (JLink) – the JLink
instance.Returns: The maximum configurable capacity for the trace buffer.
-
trace_min_buffer_capacity
(*args, **kwargs)¶ Retrieves the minimum capacity the trace buffer can be configured with.
Parameters: self (JLink) – the JLink
instance.Returns: The minimum configurable capacity for the trace buffer.
-
trace_read
(*args, **kwargs)¶ Reads data from the trace buffer and returns it.
Parameters: - self (JLink) – the
JLink
instance. - offset (int) – the offset from which to start reading from the trace buffer.
- num_items (int) – number of items to read from the trace buffer.
Returns: A list of
JLinkTraceData
instances corresponding to the items read from the trace buffer. Note that this list may have size less thannum_items
in the event that there are notnum_items
items in the trace buffer.Raises: JLinkException
– on error.- self (JLink) – the
-
trace_region
(*args, **kwargs)¶ Retrieves the properties of a trace region.
Parameters: - self (JLink) – the
JLink
instance. - region_index (int) – the trace region index.
Returns: An instance of
JLinkTraceRegion
describing the specified region.- self (JLink) – the
-
trace_region_count
(*args, **kwargs)¶ Retrieves a count of the number of available trace regions.
Parameters: self (JLink) – the JLink
instance.Returns: Count of the number of available trace regions.
-
trace_sample_count
(*args, **kwargs)¶ Retrieves the number of samples in the trace buffer.
Parameters: self (JLink) – the JLink
instance.Returns: Number of samples in the trace buffer.
-
trace_set_buffer_capacity
(*args, **kwargs)¶ Sets the capacity for the trace buffer.
Parameters: - self (JLink) – the
JLink
instance. - size (int) – the new capacity for the trace buffer.
Returns: None
- self (JLink) – the
-
trace_set_format
(*args, **kwargs)¶ Sets the format for the trace buffer to use.
Parameters: - self (JLink) – the
JLink
instance. - fmt (int) – format for the trace buffer; this is one of the attributes
of
JLinkTraceFormat
.
Returns: None
- self (JLink) – the
-
trace_start
(*args, **kwargs)¶ Starts collecting trace data.
Parameters: self (JLink) – the JLink
instance.Returns: None
-
trace_stop
(*args, **kwargs)¶ Stops collecting trace data.
Parameters: self (JLink) – the JLink
instance.Returns: None
-
unlock
(*args, **kwargs)¶ Unlocks the device connected to the J-Link.
Unlocking a device allows for access to read/writing memory, as well as flash programming.
Note
Unlock is not supported on all devices.
- Supported Devices:
- Kinetis
Returns: True
.Raises: JLinkException
– if the device fails to unlock.
-
update_firmware
(*args, **kwargs)¶ Performs a firmware update.
If there is a newer version of firmware available for the J-Link device, then updates the firmware.
Parameters: self (JLink) – the JLink
instanceReturns: Checksum of the new firmware on update, 0
if the firmware was not changed.
-
version
¶ Returns the device’s version.
The device’s version is returned as a string of the format: M.mr where
M
is major number,m
is minor number, andr
is revision character.Parameters: self (JLink) – the JLink
instanceReturns: Device version string.
-
warning_handler
¶ Returns the warning handler function.
Parameters: self (JLink) – the JLink
instanceReturns: None
if the warning handler was not set, otherwise actypes.CFUNCTYPE
.
-
watchpoint_clear
(*args, **kwargs)¶ Clears the watchpoint with the specified handle.
Parameters: - self (JLink) – the
JLink
instance - handle (int) – the handle of the watchpoint
Returns: True
if watchpoint was removed, otherwiseFalse
.- self (JLink) – the
-
watchpoint_clear_all
(*args, **kwargs)¶ Removes all watchpoints that have been set.
Parameters: self (JLink) – the JLink
instanceReturns: True
if they were cleared, otherwiseFalse
.
-
watchpoint_info
(*args, **kwargs)¶ Returns information about the specified watchpoint.
Note
Either
handle
orindex
can be specified. If theindex
is not provided, thehandle
must be set, and vice-versa. If bothindex
andhandle
are provided, theindex
overrides the providedhandle
.Parameters: - self (JLink) – the
JLink
instance - handle (int) – optional handle of a valid watchpoint.
- index (int) – optional index of a watchpoint.
Returns: An instance of
JLinkWatchpointInfo
specifying information about the watchpoint if the watchpoint was found, otherwiseNone
.Raises: JLinkException
– on error.ValueError
– if both handle and index are invalid.
- self (JLink) – the
-
watchpoint_set
(*args, **kwargs)¶ Sets a watchpoint at the given address.
This method allows for a watchpoint to be set on an given address or range of addresses. The watchpoint can then be triggered if the data at the given address matches the specified
data
or range of data as determined bydata_mask
, on specific access size events, reads, writes, or privileged accesses.Both
addr_mask
anddata_mask
are used to specify ranges. Bits set to1
are masked out and not taken into consideration when comparison against an address or data value. E.g. anaddr_mask
with a value of0x1
andaddr
with value0xdeadbeef
means that the watchpoint will be set on addresses0xdeadbeef
and0xdeadbeee
. If thedata
was0x11223340
and the givendata_mask
has a value of0x0000000F
, then the watchpoint would trigger for data matching0x11223340 - 0x1122334F
.Note
If both
read
andwrite
are specified, then the watchpoint will trigger on both read and write events to the given address.Parameters: - self (JLink) – the
JLink
instance - addr_mask (int) – optional mask to use for determining which address the watchpoint should be set on
- data (int) – optional data to set the watchpoint on in order to have
the watchpoint triggered when the value at the specified address
matches the given
data
- data_mask (int) – optional mask to use for determining the range of data on which the watchpoint should be triggered
- access_size (int) – if specified, this must be one of
{8, 16, 32}
and determines the access size for which the watchpoint should trigger - read (bool) – if
True
, triggers the watchpoint on read events - write (bool) – if
True
, triggers the watchpoint on write events - privileged (bool) – if
True
, triggers the watchpoint on privileged accesses
Returns: The handle of the created watchpoint.
Raises: ValueError
– if an invalid access size is given.JLinkException
– if the watchpoint fails to be set.
- self (JLink) – the
-