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` instance
Returns:	A `ctypes` DLL instance if one was loaded, otherwise `None`.

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` class
Returns:	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` class
Returns:	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` class
Returns:	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 platform
JLink_x64.dll for 64-bit platform

Parameters:	cls (Library) – the `Library` class
Returns:	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 given path, 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:	self (Library) – the `Library` instance path (path) – path to the DLL to load
Returns:	`True` if library was loaded successfully.
Raises:	`OSError` – if there is no J-LINK SDK DLL present at the path.

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` instance
Returns:	`True` if the lock was acquired, otherwise `False`.
Raises:	`OSError` – on file errors.

release()¶

Cleans up the lockfile if it was acquired.

Parameters:	self (JLock) – the `JLock` instance
Returns:	`False` if the lock was not released or the lock is not acquired, otherwise `True`.

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.

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, otherwise `False` if the breakpoint was not valid.

breakpoint_clear_all(*args, **kwargs)¶

Removes all breakpoints that have been set.

Parameters:	self (JLink) – the `JLink` instance
Returns:	`True` if they were cleared, otherwise `False`.

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.

breakpoint_info(*args, **kwargs)¶

Returns the information about a set breakpoint.

Note

Either handle or index can be specified. If the index is not provided, the handle must be set, and vice-versa. If both index and handle are provided, the index overrides the provided handle.

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.

breakpoint_set(*args, **kwargs)¶

Sets a breakpoint at the specified address.

If thumb is True, the breakpoint is set in THUMB-mode, while if arm is True, 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.

capabilities¶

Returns a bitwise combination of the emulator’s capabilities.

Parameters:	self (JLink) – the `JLink` instance
Returns:	Bitfield of emulator capabilities.

clear_error()¶

Clears the DLL internal error state.

Parameters:	self (JLink) – the `JLink` instance
Returns:	The error state before the clear.

close()¶

Closes the open J-Link.

Parameters:	self (JLink) – the `JLink` instance
Returns:	`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 or memory_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.

comm_supported(*args, **kwargs)¶

Returns true if the connected emulator supports comm_* functions.

Parameters:	self (JLink) – the `JLink` instance
Returns:	`True` if the emulator supports `comm_*` functions, otherwise `False`.

compatible_firmware_version¶

Returns the DLL’s compatible J-Link firmware version.

Parameters:	self (JLink) – the `JLink` instance
Returns:	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` instance
Returns:	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

connected()¶

Returns whether a J-Link is connected.

Parameters:	self (JLink) – the `JLink` instance
Returns:	`True` if the J-Link is open and connected, otherwise `False`.

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.

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` instance
Returns:	The identifier of the CPU core.

core_id(*args, **kwargs)¶

Returns the identifier of the target ARM core.

Parameters:	self (JLink) – the `JLink` instance
Returns:	Integer identifier of ARM core.

core_name(*args, **kwargs)¶

Returns the name of the target ARM core.

Parameters:	self (JLink) – the `JLink` instance
Returns:	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() or coresight_write().

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, otherwise `False` for Debug Port
Returns:	Data read from register.
Raises:	`JLinkException` – on hardware error

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, otherwise `False` for Debug Port
Returns:	Number of repetitions needed until write request accepted.
Raises:	`JLinkException` – on hardware error

cp15_present(*args, **kwargs)¶

Returns whether target has CP15 co-processor.

Returns:	`True` if the target has CP15 co-processor, otherwise `False`.

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 given `capability` for the CPU it is connected to, otherwise `False`.

cpu_halt_reasons(*args, **kwargs)¶

Retrives the reasons that the CPU was halted.

Parameters:	self (JLink) – the `JLink` instance
Returns:	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.

custom_licenses¶

Returns a string of the installed licenses the J-Link has.

Parameters:	self (JLink) – the `JLink` instance
Returns:	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` instance
Returns:	`None` if the detailed log handler was not set, otherwise a `ctypes.CFUNCTYPE`.

device_family(*args, **kwargs)¶

Returns the device family of the target CPU.

Parameters:	self (JLink) – the `JLink` instance
Returns:	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` instance
Returns:	`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` instance
Returns:	`True` if was previously enabled, otherwise `False`.

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` instance
Returns:	`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` instance
Returns:	`None`

disable_soft_breakpoints(*args, **kwargs)¶

Disables software breakpoints.

Note

After this function is called, software_breakpoint_set() cannot be used without first calling enable_soft_breakpoints().

Parameters:	self (JLink) – the `JLink` instance
Returns:	`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` – if `instruction` is not a number.

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` instance
Returns:	`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` instance
Returns:	`True` if was previously enabled, otherwise `False`.

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` instance
Returns:	`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` instance
Returns:	`None`

enable_soft_breakpoints(*args, **kwargs)¶

Enables software breakpoints.

Note

This should be called before calling software_breakpoint_set().

Parameters:	self (JLink) – the `JLink` instance
Returns:	`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` instance
Returns:	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` instance
Returns:	`True` on success, otherwise `False`.

error¶

DLL internal error state.

Parameters:	self (JLink) – the `JLink` instance
Returns:	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` instance
Returns:	`None` if the error handler was not set, otherwise a `ctypes.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.

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`

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, otherwise `False`.

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

JTAG Technical Overview.

licenses¶

Returns a string of the built-in licenses the J-Link has.

Parameters:	self (JLink) – the `JLink` instance
Returns:	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` instance
Returns:	`None` if the log handler was not set, otherwise a `ctypes.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, or CODE.

The given number of bits, if provided, must be either 8, 16, or 32. If not provided, always reads num_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` – if `nbits` is not `None`, and not in `8`, `16`, or `32`.

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

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

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

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.

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, or CODE.

The given number of bits, if provided, must be either 8, 16, or 32.

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` – if `nbits` is not `None`, and not in `8`, `16` or `32`.

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.

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.

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.

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.

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` instance
Returns:	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` instance
Returns:	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` instance
Returns:	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. If thumb is set, gets the number of available THUMB breakpoint units. If ram is set, gets the number of available software RAM breakpoint units. If flash is set, gets the number of available software flash breakpoint units. If hw 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.

num_available_watchpoints(*args, **kwargs)¶

Returns the number of available watchpoints.

Parameters:	self (JLink) – the `JLink` instance
Returns:	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` instance
Returns:	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` instance
Returns:	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` instance
Returns:	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` instance
Returns:	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 and ip_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` – if `serial_no` is present, but not `int` coercible. `AttributeError` – if `serial_no` and `ip_addr` are both `None`.

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`

opened()¶

Returns whether the DLL is open.

Parameters:	self (JLink) – the `JLink` instance
Returns:	`True` if the J-Link is open, otherwise `False`.

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` instance
Raises:	`JLinkException` – if J-Link does not support powering the target.

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.

product_name¶

Returns the product name of the connected J-Link.

Parameters:	self (JLink) – the `JLink` instance
Returns:	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` instance
Returns:	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.

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.

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.

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.

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` – if `len(register_indices) != len(values)` `JLinkException` – if a register could not be written to or on error

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.

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` instance
Returns:	`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, otherwise `False`.
Raises:	`ValueError` – if instruction count is not a natural number.

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.

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, otherwise `False`.
Returns:	`JLinkRTTerminalBufDesc` describing the buffer.
Raises:	`JLinkRTTException` – if the RTT control block has not yet been found.

rtt_get_num_down_buffers(*args, **kwargs)¶

After starting RTT, get the current number of down buffers.

Parameters:	self (JLink) – the `JLink` instance
Returns:	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` instance
Returns:	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` instance
Returns:	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.

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.

rtt_stop(*args, **kwargs)¶

Stops RTT on the J-Link and host side.

Parameters:	self (JLink) – the `JLink` instance
Returns:	`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.

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.

scan_len(*args, **kwargs)¶

Retrieves and returns the length of the scan chain select register.

Parameters:	self (JLink) – the `JLink` instance
Returns:	Length of the scan chain select register.

serial_number¶

Returns the serial number of the connected J-Link.

Parameters:	self (JLink) – the `JLink` instance
Returns:	Serial number as an integer.

set_big_endian(*args, **kwargs)¶

Sets the target hardware to big endian.

Parameters:	self (JLink) – the `JLink` instance
Returns:	`True` if target was little endian before call, otherwise `False`.

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` instance
Returns:	`True` if target was big endian before call, otherwise `False`.

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.

set_max_speed(*args, **kwargs)¶

Sets JTAG communication speed to the maximum supported speed.

Parameters:	self (JLink) – the `JLink` instance
Returns:	`None`

set_reset_pin_high(*args, **kwargs)¶

Sets the reset pin high.

Parameters:	self (JLink) – the `JLink` instance
Returns:	`None`

set_reset_pin_low(*args, **kwargs)¶

Sets the reset pin low.

Parameters:	self (JLink) – the `JLink` instance
Returns:	`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.

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 than JLink.MAX_JTAG_SPEED and no smaller than JLink.MIN_JTAG_SPEED. The given speed can also not be JLink.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.

set_tck_pin_high(*args, **kwargs)¶

Sets the TCK pin to the high value (1).

Parameters:	self (JLink) – the `JLink` instance
Returns:	`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` instance
Returns:	`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` instance
Returns:	`None`

set_tdi_pin_low(*args, **kwargs)¶

Clears the test data input.

TDI is set to logical 0 (Ground).

Parameters:	self (JLink) – the `JLink` instance
Returns:	`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, otherwise `False`.
Raises:	`JLinkException` – if the given interface is invalid or unsupported.

set_tms_pin_high(*args, **kwargs)¶

Sets the test mode select to logical 1.

Parameters:	self (JLink) – the `JLink` instance
Returns:	`None`

set_tms_pin_low(*args, **kwargs)¶

Clears the test mode select.

TMS is set to logical 0 (Ground).

Parameters:	self (JLink) – the `JLink` instance
Returns:	`None`

set_trace_source(*args, **kwargs)¶

Sets the source to be used for tracing.

The source must be one of the ones provided by enums.JLinkTraceSource.

Parameters:	self (JLink) – the `JLink` instance. source (int) – the source to use.
Returns:	`None`

set_trst_pin_high(*args, **kwargs)¶

Sets the TRST pin to high (1).

Deasserts the TRST pin.

Parameters:	self (JLink) – the `JLink` instance
Returns:	`None`

set_trst_pin_low(*args, **kwargs)¶

Sets the TRST pin to low (0).

This asserts the TRST pin.

Parameters:	self (JLink) – the `JLink` instance
Returns:	`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` instance
Returns:	`None`
Raises:	`JLinkException` – on error.

software_breakpoint_set(*args, **kwargs)¶

Sets a software breakpoint at the specified address.

If thumb is True, the breakpoint is set in THUMB-mode, while if arm is True, the breakpoint is set in ARM-mode, otherwise a normal breakpoint is set.

If flash is True, the breakpoint is set in flash, otherwise if ram is True, the breakpoint is set in RAM. If both are True or both are False, 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.

speed¶

Returns the current JTAG connection speed.

Parameters:	self (JLink) – the `JLink` instance
Returns:	JTAG connection speed.

speed_info¶

Retrieves information about supported target interface speeds.

Parameters:	self (JLink) – the `JLink` instance
Returns:	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

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.

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.

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` – if `port_width` is not `1`, `2`, or `4`. `JLinkException` – on error.

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.

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.

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.

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` – if `num_instructions < 0` or `num_instructions > 0x10000`.

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.

supported_tifs(*args, **kwargs)¶

Returns a bitmask of the supported target interfaces.

Parameters:	self (JLink) – the `JLink` instance
Returns:	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.

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.

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.

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`

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` and `value`
Returns:	The bit position of the response in the input buffer.

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.

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.

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.

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

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

swo_enabled()¶

Returns whether or not SWO is enabled.

Parameters:	self (JLink) – the `JLink` instance
Returns:	`True` if SWO is enabled, otherwise `False`.

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

swo_num_bytes(*args, **kwargs)¶

Retrives the number of bytes in the SWO buffer.

Parameters:	self (JLink) – the `JLink` instance
Returns:	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 is True. 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.

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 for printf 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` – if `port < 0` or `port > 31`

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

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

swo_speed_info(*args, **kwargs)¶

Retrieves information about the supported SWO speeds.

Parameters:	self (JLink) – the `JLink` instance
Returns:	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

swo_stop(*args, **kwargs)¶

Stops collecting SWO data.

Parameters:	self (JLink) – the `JLink` instance
Returns:	`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.

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` instance
Returns:	`None`

target_connected()¶

Returns whether a target is connected to the J-Link.

Parameters:	self (JLink) – the `JLink` instance
Returns:	`True` if a target is connected, otherwise `False`.

test()¶

Performs a self test.

Parameters:	self (JLink) – the `JLink` instance
Returns:	`True` if test passed, otherwise `False`.

tif¶

Returns the current target interface of the J-Link.

Parameters:	self (JLink) – the `JLink` instance
Returns:	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 than `num_items` in the event that there are not `num_items` items in the trace buffer.
Raises:	`JLinkException` – on error.

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.

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`

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`

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` instance
Returns:	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, and r is revision character.

Parameters:	self (JLink) – the `JLink` instance
Returns:	Device version string.

warning_handler¶

Returns the warning handler function.

Parameters:	self (JLink) – the `JLink` instance
Returns:	`None` if the warning handler was not set, otherwise a `ctypes.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, otherwise `False`.

watchpoint_clear_all(*args, **kwargs)¶

Removes all watchpoints that have been set.

Parameters:	self (JLink) – the `JLink` instance
Returns:	`True` if they were cleared, otherwise `False`.

watchpoint_info(*args, **kwargs)¶

Returns information about the specified watchpoint.

Note

Either handle or index can be specified. If the index is not provided, the handle must be set, and vice-versa. If both index and handle are provided, the index overrides the provided handle.

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, otherwise `None`.
Raises:	`JLinkException` – on error. `ValueError` – if both handle and index are invalid.

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 by data_mask, on specific access size events, reads, writes, or privileged accesses.

Both addr_mask and data_mask are used to specify ranges. Bits set to 1 are masked out and not taken into consideration when comparison against an address or data value. E.g. an addr_mask with a value of 0x1 and addr with value 0xdeadbeef means that the watchpoint will be set on addresses 0xdeadbeef and 0xdeadbeee. If the data was 0x11223340 and the given data_mask has a value of 0x0000000F, then the watchpoint would trigger for data matching 0x11223340 - 0x1122334F.

Note

If both read and write 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.