PyLink
latest

Getting Started

  • Installation
  • Tutorial
  • Command-Line

Documentation

  • PyLink
    • Exceptions
    • Library
    • JLock
    • JLink
  • Protocols
  • Unlockers
  • Bindings
  • Extras
  • Troubleshooting

Debugging

  • Serial Wire Debug

About PyLink

  • About
PyLink
  • Docs »
  • PyLink
  • Edit on GitHub

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.

See also

J-Link Multi-session.

load_default()¶

Loads the default J-Link SDK DLL.

The default J-Link SDK is determined by first checking if ctypes can find the DLL, then by searching the platform-specific paths.

Parameters:self (Library) – the Library instance
Returns:True if the DLL was loaded, otherwise False.
unload()¶

Unloads the library’s DLL if it has been loaded.

This additionally cleans up the temporary DLL file that was created when the library was loaded.

Parameters:self (Library) – the Library instance
Returns:True if the DLL was unloaded, otherwise False.

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

For a full list of the supported commands, please see the SEGGER J-Link documentation, UM08001.

extended_capabilities¶

Gets the capabilities of the connected emulator as a list.

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

features¶

Returns a list of the J-Link embedded features.

Parameters:self (JLink) – the JLink instance
Returns:[ '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 instance
Returns:True if the J-Link’s firmware is newer than the one supported by the DLL, otherwise False.
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 instance
Returns:True if the J-Link’s firmware is older than the one supported by the DLL, otherwise False.
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 instance
Returns:Firmware identification string.
flash(*args, **kwargs)¶

Flashes the target device.

The given on_progress callback will be called as on_progress(action, progress_string, percentage) periodically as the data is written to flash. The action is one of Compare, 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.

flash_file(*args, **kwargs)¶

Flashes the target device.

The given on_progress callback will be called as on_progress(action, progress_string, percentage) periodically as the data is written to flash. The action is one of Compare, 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.

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

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.

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.

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.

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.

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.

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.

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 instance
Returns: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 – if len(pins) != len(states)
halt(*args, **kwargs)¶

Halts the CPU Core.

Parameters:self (JLink) – the JLink instance
Returns:True if halted, False otherwise.
halted(*args, **kwargs)¶

Returns whether the CPU core was halted.

Parameters:self (JLink) – the JLink instance
Returns:True if the CPU core is halted, otherwise False.
Raises:JLinkException – on device errors.
hardware_breakpoint_set(*args, **kwargs)¶

Sets a hardware 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 sbe retained for future breakpoint operations.

Raises:
  • TypeError – if the given address is not an integer.
  • JLinkException – if the breakpoint could not be set.
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:
  1. If 1, target is powered via J-Link.
  2. Overcurrent bitfield: 0: No overcurrent. 1: Overcurrent happened. 2ms @ 3000mA 2: Overcurrent happened. 10ms @ 1000mA 3: Overcurrent happened. 40ms @ 400mA
  3. Power consumption of target (mA).
  4. Peak of target power consumption (mA).
  5. Peak of target power consumption during J-Link operation (mA).
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 instance
Returns: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 instance
Returns: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.

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

index¶

Retrieves and returns the index number of the actual selected J-Link.

Parameters:self (JLink) – the JLink instance
Returns: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 instance
Returns: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 instance
Returns: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 – if instr_regs or data_bits are not natural numbers

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 instance
Returns:either 0 or 1.
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 instance
Returns: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 the tms and tdi parameters for the purpose of extracting state and data information
Returns:

None

Raises:

ValueError – if num_bits < 1 or num_bits > 32.

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.
Next Previous

© Copyright 2017, Square Inc. Revision 5c5c3853.

Built with Sphinx using a theme provided by Read the Docs.
Read the Docs v: latest
Versions
latest
stable
Downloads
pdf
html
epub
On Read the Docs
Project Home
Builds

Free document hosting provided by Read the Docs.