lobo
/
blflashcommand
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
blflashcommand/pylink/jlink.py

4630 lines
148 KiB
Python
Raw Blame History

# decompyle3 version 3.9.0
# Python bytecode version base 3.7.0 (3394)
# Decompiled from: Python 3.7.16 (default, Mar 30 2023, 01:25:49)
# [GCC 12.2.1 20220924]
# Embedded file name: pylink/jlink.py
from . import binpacker
from . import decorators
from . import enums
from . import errors
from . import jlock
from . import library
from . import structs
from . import unlockers
from . import util
import ctypes, datetime, functools, itertools, logging, math, operator, sys, time, six
logger = logging.getLogger(__name__)
class JLink(object):
__doc__ = 'Python interface for the SEGGER J-Link.\n\n This is a wrapper around the J-Link C SDK to provide a Python interface\n to it. The shared library is loaded and used to call the SDK methods.\n '
MAX_BUF_SIZE = 336
MAX_NUM_CPU_REGISTERS = 256
MAX_JTAG_SPEED = 12000
MIN_JTAG_SPEED = 5
INVALID_JTAG_SPEED = 65534
AUTO_JTAG_SPEED = 0
ADAPTIVE_JTAG_SPEED = 65535
MAX_NUM_MOES = 8
def minimum_required(version):
"""Decorator to specify the minimum SDK version required.
Args:
version (str): valid version string
Returns:
A decorator function.
"""
def _minimum_required(func):
@functools.wraps(func)
def wrapper(self, *args, **kwargs):
if list(self.version) < list(version):
raise errors.JLinkException('Version %s required.' % version)
return func(self, *args, **kwargs)
return wrapper
return _minimum_required
def open_required(func):
"""Decorator to specify that the J-Link DLL must be opened, and a
J-Link connection must be established.
Args:
func (function): function being decorated
Returns:
The wrapper function.
"""
@functools.wraps(func)
def wrapper(self, *args, **kwargs):
if not self.opened():
raise errors.JLinkException('J-Link DLL is not open.')
else:
if not self.connected():
raise errors.JLinkException('J-Link connection has been lost.')
return func(self, *args, **kwargs)
return wrapper
def connection_required(func):
"""Decorator to specify that a target connection is required in order
for the given method to be used.
Args:
func (function): function being decorated
Returns:
The wrapper function.
"""
@functools.wraps(func)
def wrapper(self, *args, **kwargs):
if not self.target_connected():
raise errors.JLinkException('Target is not connected.')
return func(self, *args, **kwargs)
return wrapper
def interface_required(interface):
"""Decorator to specify that a particular interface type is required
for the given method to be used.
Args:
interface (int): attribute of ``JLinkInterfaces``
Returns:
A decorator function.
"""
def _interface_required(func):
@functools.wraps(func)
def wrapper(self, *args, **kwargs):
if self.tif != interface:
raise errors.JLinkException('Unsupported for current interface.')
return func(self, *args, **kwargs)
return wrapper
return _interface_required
def __init__(self, lib=None, log=None, detailed_log=None, error=None, warn=None, unsecure_hook=None, serial_no=None, ip_addr=None, open_tunnel=False):
"""Initializes the J-Link interface object.
Note:
By default, the unsecure dialog will reject unsecuring the device on
connection. If you wish to change this behaviour (to have the device
be unsecured and erased), pass a callback that returns
``JLinkFlags.DLG_BUTTON_YES`` as its return value.
Args:
self (JLink): the ``JLink`` instance
lib (Library): a valid ``Library`` instance (not ``None`` dll)
log (function): function to be called to write out log messages, by
default this writes to standard out
detailed_log (function): function to be called to write out detailed
log messages, by default this writes to standard out
error (function): function to be called to write out error messages,
default this writes to standard error
warn (function): function to be called to write out warning messages,
default this his writes to standard error
unsecure_hook (function): function to be called for the unsecure
dialog
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)
open_tunnel (bool, None): If ``False`` (default), the ``open``
method will be called when entering the context manager using
the ``serial_no`` and ``ip_addr`` provided here.
If ``True`` ``open_tunnel`` method will be called instead
of ``open`` method.
If ``None``, the driver will not be opened automatically
(however, it is still closed when exiting the context manager).
Returns:
``None``
Raises:
TypeError: if lib's DLL is ``None``
"""
self._initialized = False
if lib is None:
lib = library.Library()
if lib.dll() is None:
raise TypeError('Expected to be given a valid DLL.')
self._library = lib
self._dll = lib.dll()
self._tif = enums.JLinkInterfaces.JTAG
self._unsecure_hook = unsecure_hook or util.unsecure_hook_dialog
self._log_handler = None
self._warning_handler = None
self._error_handler = None
self._detailed_log_handler = None
self._swo_enabled = False
self._lock = None
self._device = None
self._open_refcount = 0
self._dll.JLINKARM_OpenEx.restype = ctypes.POINTER(ctypes.c_char)
self._dll.JLINKARM_GetCompileDateTime.restype = ctypes.POINTER(ctypes.c_char)
self._dll.JLINKARM_GetRegisterName.restype = ctypes.POINTER(ctypes.c_char)
self.error_handler = lambda s: error or logger.error(s.decode())
self.warning_handler = lambda s: warn or logger.warning(s.decode())
self.log_handler = lambda s: log or logger.info(s.decode())
self.detailed_log_handler = lambda s: detailed_log or logger.debug(s.decode())
self._JLink__serial_no = serial_no
self._JLink__ip_addr = ip_addr
self._JLink__open_tunnel = open_tunnel
self._initialized = True
def __del__(self):
"""Destructor for the ``JLink`` instance. Closes the J-Link connection
if one exists.
Args:
self (JLink): the ``JLink`` instance
Returns:
``None``
"""
self._finalize()
def __enter__(self):
"""Connects to the J-Link emulator (defaults to USB) using context manager.
Parameters passed to __init__ are used for open() function.
Returns:
the ``JLink`` instance
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``.
"""
if self._JLink__open_tunnel is False:
self.open(serial_no=(self._JLink__serial_no), ip_addr=(self._JLink__ip_addr))
else:
if self._JLink__open_tunnel is True:
self.open_tunnel(serial_no=(self._JLink__serial_no))
return self
def __exit__(self, exc_type, exc_val, exc_tb):
"""Closes the JLink connection on exit of the context manager.
Stops the SWO if enabled and closes the J-Link connection if one
exists.
Args:
self (JLink): the ``JLink`` instance
exc_type (BaseExceptionType, None): the exception class, if any
raised inside the context manager
exc_val (BaseException, None): the exception object, if any raised
inside the context manager
exc_tb (TracebackType, None): the exception traceback, if any
exception was raised inside the context manager.
Returns:
``True`` if exception raised inside the context manager was handled
and shall be suppressed (not propagated), ``None`` otherwise.
"""
self._finalize()
def _finalize(self):
"""Finalizer ("destructor") for the ``JLink`` instance.
Stops the SWO if enabled and closes the J-Link connection if one
exists.
Called when exiting the context manager or when this object is
destructed (garbage collected).
Args:
self (JLink): the ``JLink`` instance
Returns:
``None``
"""
if self._initialized:
if self.connected():
if self.swo_enabled():
self.swo_stop()
if self.opened():
self.close()
def _get_register_index_from_name(self, register):
"""
Converts a register name to a register index
Args:
self (JLink): the ``JLink`` instance
register (str): the register name
Returns:
``int``
"""
regs = list((self.register_name(idx) for idx in self.register_list()))
if isinstance(register, six.string_types):
try:
result = regs.index(register)
except ValueError:
error_message = 'No register found matching name: {}. (available registers: {})'
raise errors.JLinkException(error_message.format(register, ', '.join(regs)))
return result
def opened(self):
"""Returns whether the DLL is open.
Args:
self (JLink): the ``JLink`` instance
Returns:
``True`` if the J-Link is open, otherwise ``False``.
"""
return bool(self._dll.JLINKARM_IsOpen())
def connected(self):
"""Returns whether a J-Link is connected.
Args:
self (JLink): the ``JLink`` instance
Returns:
``True`` if the J-Link is open and connected, otherwise ``False``.
"""
return self.opened() and bool(self._dll.JLINKARM_EMU_IsConnected())
def target_connected(self):
"""Returns whether a target is connected to the J-Link.
Args:
self (JLink): the ``JLink`` instance
Returns:
``True`` if a target is connected, otherwise ``False``.
"""
return self.connected() and bool(self._dll.JLINKARM_IsConnected())
@property
def log_handler(self):
"""Returns the log handler function.
Args:
self (JLink): the ``JLink`` instance
Returns:
``None`` if the log handler was not set, otherwise a
``ctypes.CFUNCTYPE``.
"""
return self._log_handler
@log_handler.setter
def log_handler(self, handler):
"""Setter for the log handler function.
Args:
self (JLink): the ``JLink`` instance
Returns:
``None``
"""
if not self.opened():
handler = handler or util.noop
self._log_handler = enums.JLinkFunctions.LOG_PROTOTYPE(handler)
self._dll.JLINKARM_EnableLog(self._log_handler)
@property
def detailed_log_handler(self):
"""Returns the detailed log handler function.
Args:
self (JLink): the ``JLink`` instance
Returns:
``None`` if the detailed log handler was not set, otherwise a
``ctypes.CFUNCTYPE``.
"""
return self._detailed_log_handler
@detailed_log_handler.setter
def detailed_log_handler(self, handler):
"""Setter for the detailed log handler function.
Args:
self (JLink): the ``JLink`` instance
Returns:
``None``
"""
if not self.opened():
handler = handler or util.noop
self._detailed_log_handler = enums.JLinkFunctions.LOG_PROTOTYPE(handler)
self._dll.JLINKARM_EnableLogCom(self._detailed_log_handler)
@property
def error_handler(self):
"""Returns the error handler function.
Args:
self (JLink): the ``JLink`` instance
Returns:
``None`` if the error handler was not set, otherwise a
``ctypes.CFUNCTYPE``.
"""
return self._error_handler
@error_handler.setter
def error_handler(self, handler):
"""Setter for the error handler function.
If the DLL is open, this function is a no-op, so it should be called
prior to calling ``open()``.
Args:
self (JLink): the ``JLink`` instance
handler (function): function to call on error messages
Returns:
``None``
"""
if not self.opened():
handler = handler or util.noop
self._error_handler = enums.JLinkFunctions.LOG_PROTOTYPE(handler)
self._dll.JLINKARM_SetErrorOutHandler(self._error_handler)
@property
def warning_handler(self):
"""Returns the warning handler function.
Args:
self (JLink): the ``JLink`` instance
Returns:
``None`` if the warning handler was not set, otherwise a
``ctypes.CFUNCTYPE``.
"""
return self._warning_handler
@warning_handler.setter
def warning_handler(self, handler):
"""Setter for the warning handler function.
If the DLL is open, this function is a no-op, so it should be called
prior to calling ``open()``.
Args:
self (JLink): the ``JLink`` instance
handler (function): function to call on warning messages
Returns:
``None``
"""
if not self.opened():
handler = handler or util.noop
self._warning_handler = enums.JLinkFunctions.LOG_PROTOTYPE(handler)
self._dll.JLINKARM_SetWarnOutHandler(self._warning_handler)
def num_connected_emulators(self):
"""Returns the number of emulators which are connected via USB to the
host.
Args:
self (JLink): the ``JLink`` instance
Returns:
The number of connected emulators.
"""
return self._dll.JLINKARM_EMU_GetNumDevices()
def connected_emulators(self, host=enums.JLinkHost.USB):
"""Returns a list of all the connected emulators.
Args:
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.
"""
res = self._dll.JLINKARM_EMU_GetList(host, 0, 0)
if res < 0:
raise errors.JLinkException(res)
num_devices = res
info = (structs.JLinkConnectInfo * num_devices)()
num_found = self._dll.JLINKARM_EMU_GetList(host, info, num_devices)
if num_found < 0:
raise errors.JLinkException(num_found)
return list(info)[:num_found]
def num_supported_devices(self):
"""Returns the number of devices that are supported by the opened
J-Link DLL.
Args:
self (JLink): the ``JLink`` instance
Returns:
Number of devices the J-Link DLL supports.
"""
return int(self._dll.JLINKARM_DEVICE_GetInfo(-1, 0))
def supported_device(self, index=0):
"""Gets the device at the given ``index``.
Args:
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.
"""
if not util.is_natural(index) or index >= self.num_supported_devices():
raise ValueError('Invalid index.')
info = structs.JLinkDeviceInfo()
result = self._dll.JLINKARM_DEVICE_GetInfo(index, ctypes.byref(info))
return info
def open(self, 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.
Args:
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``.
"""
if self._open_refcount > 0:
self._open_refcount += 1
return
self.close()
if ip_addr is not None:
addr, port = ip_addr.rsplit(':', 1)
if serial_no is None:
result = self._dll.JLINKARM_SelectIP(addr.encode(), int(port))
if result == 1:
raise errors.JLinkException('Could not connect to emulator at %s.' % ip_addr)
else:
self._dll.JLINKARM_EMU_SelectIPBySN(int(serial_no))
else:
if serial_no is not None:
result = self._dll.JLINKARM_EMU_SelectByUSBSN(int(serial_no))
if result < 0:
raise errors.JLinkException('No emulator with serial number %s found.' % serial_no)
else:
result = self._dll.JLINKARM_SelectUSB(0)
if result != 0:
raise errors.JlinkException('Could not connect to default emulator.')
if serial_no is not None:
self._lock = jlock.JLock(serial_no)
if not self._lock.acquire():
raise errors.JLinkException('J-Link is already open.')
result = self._dll.JLINKARM_OpenEx(self.log_handler, self.error_handler)
result = ctypes.cast(result, ctypes.c_char_p).value
if result is not None:
raise errors.JLinkException(result.decode())
unsecure_hook = self._unsecure_hook
if unsecure_hook is not None:
if hasattr(self._dll, 'JLINK_SetHookUnsecureDialog'):
func = enums.JLinkFunctions.UNSECURE_HOOK_PROTOTYPE(unsecure_hook)
self._dll.JLINK_SetHookUnsecureDialog(func)
self._open_refcount = 1
def open_tunnel(self, serial_no, port=19020):
"""Connects to the J-Link emulator (over SEGGER tunnel).
Args:
self (JLink): the ``JLink`` instance
serial_no (int): serial number of the J-Link
port (int): optional port number (default to 19020).
Returns:
``None``
"""
return self.open(ip_addr=('tunnel:' + str(serial_no) + ':' + str(port)))
def close(self):
"""Closes the open J-Link.
Args:
self (JLink): the ``JLink`` instance
Returns:
``None``
Raises:
JLinkException: if there is no connected JLink.
"""
if self._open_refcount == 0:
return
self._open_refcount -= 1
if self._open_refcount > 0:
return
self._dll.JLINKARM_Close()
if self._lock is not None:
del self._lock
self._lock = None
def test(self):
"""Performs a self test.
Args:
self (JLink): the ``JLink`` instance
Returns:
``True`` if test passed, otherwise ``False``.
"""
res = self._dll.JLINKARM_Test()
return res == 0
@open_required
def invalidate_firmware(self):
"""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.
Args:
self (JLink): the ``JLink`` instance
Returns:
``None``
Raises:
JLinkException: on hardware error.
"""
self.exec_command('InvalidateFW')
@open_required
def update_firmware(self):
"""Performs a firmware update.
If there is a newer version of firmware available for the J-Link
device, then updates the firmware.
Args:
self (JLink): the ``JLink`` instance
Returns:
Checksum of the new firmware on update, ``0`` if the firmware was not
changed.
"""
return self._dll.JLINKARM_UpdateFirmwareIfNewer()
@open_required
def sync_firmware(self):
"""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.
Args:
self (JLink): the ``JLink`` instance
Returns:
``None``
"""
serial_no = self.serial_number
if self.firmware_newer():
try:
self.invalidate_firmware()
self.update_firmware()
except errors.JLinkException as e:
try:
pass
finally:
e = None
del e
res = self.open(serial_no=serial_no)
if self.firmware_newer():
raise errors.JLinkException('Failed to sync firmware version.')
return res
if self.firmware_outdated():
try:
self.update_firmware()
except errors.JLinkException as e:
try:
pass
finally:
e = None
del e
if self.firmware_outdated():
raise errors.JLinkException('Failed to sync firmware version.')
return self.open(serial_no=serial_no)
def exec_command(self, 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.
Args:
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 <https://www.segger.com/downloads/jlink>`__.
"""
err_buf = (ctypes.c_char * self.MAX_BUF_SIZE)()
res = self._dll.JLINKARM_ExecCommand(cmd.encode(), err_buf, self.MAX_BUF_SIZE)
err_buf = ctypes.string_at(err_buf).decode()
if len(err_buf) > 0:
raise errors.JLinkException(err_buf.strip())
return res
@minimum_required('5.02')
def enable_dialog_boxes(self):
"""Enables showing dialog boxes on certain methods.
Note:
Dialog boxes only appear on Windows platforms.
Note:
This can be used for batch or automized test running.
Args:
self (JLink): the ``JLink`` instance
Returns:
``None``
"""
self.exec_command('SetBatchMode = 0')
@minimum_required('5.02')
def disable_dialog_boxes(self):
"""Disables showing dialog boxes on certain methods.
Note:
Dialog boxes only appear on Windows platforms.
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.
Args:
self (JLink): the ``JLink`` instance
Returns:
``None``
"""
self.exec_command('SilentUpdateFW')
self.exec_command('SuppressInfoUpdateFW')
self.exec_command('SetBatchMode = 1')
@open_required
def jtag_configure(self, instr_regs=0, data_bits=0):
"""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.
Args:
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
"""
if not util.is_natural(instr_regs):
raise ValueError('IR value is not a natural number.')
if not util.is_natural(data_bits):
raise ValueError('Data bits is not a natural number.')
self._dll.JLINKARM_ConfigJTAG(instr_regs, data_bits)
@open_required
@minimum_required('4.98e')
def coresight_configure(self, ir_pre=0, dr_pre=0, ir_post=0, dr_post=0, ir_len=0, perform_tif_init=True):
"""Prepares target and J-Link for CoreSight function usage.
Args:
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()``.
"""
if self.tif == enums.JLinkInterfaces.SWD:
res = self._dll.JLINKARM_CORESIGHT_Configure('')
if res < 0:
raise errors.JLinkException(res)
return
config_string = 'IRPre=%s;DRPre=%s;IRPost=%s;DRPost=%s;IRLenDevice=%s;'
config_string = config_string % (ir_pre, dr_pre, ir_post, dr_post, ir_len)
if not perform_tif_init:
config_string = config_string + 'PerformTIFInit=0;'
res = self._dll.JLINKARM_CORESIGHT_Configure(config_string.encode())
if res < 0:
raise errors.JLinkException(res)
@open_required
def connect(self, chip_name, speed='auto', verbose=False):
"""Connects the J-Link to its target.
Args:
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
"""
if verbose:
self.exec_command('EnableRemarks = 1')
self.exec_command('Device = %s' % chip_name)
if speed == 'auto':
self.set_speed(auto=True)
else:
if speed == 'adaptive':
self.set_speed(adaptive=True)
else:
self.set_speed(speed)
result = self._dll.JLINKARM_Connect()
if result < 0:
raise errors.JLinkException(result)
try:
self.halted()
except errors.JLinkException:
pass
for index in range(self.num_supported_devices()):
device = self.supported_device(index)
if device.name.lower() == chip_name.lower():
self._device = device
break
else:
raise errors.JLinkException('Unsupported device was connected to.')
@property
def error(self):
"""DLL internal error state.
Args:
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 = int(self._dll.JLINKARM_HasError())
if error == 0:
return
return error
def clear_error(self):
"""Clears the DLL internal error state.
Args:
self (JLink): the ``JLink`` instance
Returns:
The error state before the clear.
"""
error = self.error
self._dll.JLINKARM_ClrError()
return error
@property
def compile_date(self):
"""Returns a string specifying the date and time at which the DLL was
translated.
Args:
self (JLink): the ``JLink`` instance
Returns:
Datetime string.
"""
result = self._dll.JLINKARM_GetCompileDateTime()
return ctypes.cast(result, ctypes.c_char_p).value.decode()
@property
def version(self):
"""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.
Args:
self (JLink): the ``JLink`` instance
Returns:
Device version string.
"""
version = int(self._dll.JLINKARM_GetDLLVersion())
major = version / 10000
minor = version / 100 % 100
rev = version % 100
rev = '' if rev == 0 else chr(rev + ord('a') - 1)
return '%d.%02d%s' % (major, minor, rev)
@property
@open_required
def compatible_firmware_version(self):
"""Returns the DLL's compatible J-Link firmware version.
Args:
self (JLink): the ``JLink`` instance
Returns:
The firmware version of the J-Link that the DLL is compatible
with.
Raises:
JLinkException: on error.
"""
identifier = self.firmware_version.split('compiled')[0]
buf_size = self.MAX_BUF_SIZE
buf = (ctypes.c_char * buf_size)()
res = self._dll.JLINKARM_GetEmbeddedFWString(identifier.encode(), buf, buf_size)
if res < 0:
raise errors.JLinkException(res)
return ctypes.string_at(buf).decode()
@open_required
def firmware_outdated(self):
"""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()``.
Args:
self (JLink): the ``JLink`` instance
Returns:
``True`` if the J-Link's firmware is older than the one supported by
the DLL, otherwise ``False``.
"""
datefmt = ' %b %d %Y %H:%M:%S'
compat_date = self.compatible_firmware_version.split('compiled')[1]
compat_date = datetime.datetime.strptime(compat_date, datefmt)
fw_date = self.firmware_version.split('compiled')[1]
fw_date = datetime.datetime.strptime(fw_date, datefmt)
return compat_date > fw_date
@open_required
def firmware_newer(self):
"""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()``.
Args:
self (JLink): the ``JLink`` instance
Returns:
``True`` if the J-Link's firmware is newer than the one supported by
the DLL, otherwise ``False``.
"""
if self.firmware_outdated():
return False
return self.firmware_version != self.compatible_firmware_version
@property
@open_required
def hardware_info(self, mask=4294967295):
"""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:
0. If ``1``, target is powered via J-Link.
1. Overcurrent bitfield:
0: No overcurrent.
1: Overcurrent happened. 2ms @ 3000mA
2: Overcurrent happened. 10ms @ 1000mA
3: Overcurrent happened. 40ms @ 400mA
2. Power consumption of target (mA).
3. Peak of target power consumption (mA).
4. Peak of target power consumption during J-Link operation (mA).
Args:
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.
"""
buf = (ctypes.c_uint32 * 32)()
res = self._dll.JLINKARM_GetHWInfo(mask, ctypes.byref(buf))
if res != 0:
raise errors.JLinkException(res)
return list(buf)
@property
@open_required
def hardware_status(self):
"""Retrieves and returns the hardware status.
Args:
self (JLink): the ``JLink`` instance
Returns:
A ``JLinkHardwareStatus`` describing the J-Link hardware.
"""
stat = structs.JLinkHardwareStatus()
res = self._dll.JLINKARM_GetHWStatus(ctypes.byref(stat))
if res == 1:
raise errors.JLinkException('Error in reading hardware status.')
return stat
@property
@open_required
def hardware_version(self):
"""Returns the hardware version of the connected J-Link as a
major.minor string.
Args:
self (JLink): the ``JLink`` instance
Returns:
Hardware version string.
"""
version = self._dll.JLINKARM_GetHardwareVersion()
major = version / 10000 % 100
minor = version / 100 % 100
return '%d.%02d' % (major, minor)
@property
@open_required
def firmware_version(self):
"""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.
Args:
self (JLink): the ``JLink`` instance
Returns:
Firmware identification string.
"""
buf = (ctypes.c_char * self.MAX_BUF_SIZE)()
self._dll.JLINKARM_GetFirmwareString(buf, self.MAX_BUF_SIZE)
return ctypes.string_at(buf).decode()
@property
@open_required
def capabilities(self):
"""Returns a bitwise combination of the emulator's capabilities.
Args:
self (JLink): the ``JLink`` instance
Returns:
Bitfield of emulator capabilities.
"""
return self._dll.JLINKARM_GetEmuCaps()
@property
@open_required
def extended_capabilities(self):
"""Gets the capabilities of the connected emulator as a list.
Args:
self (JLink): the ``JLink`` instance
Returns:
List of 32 integers which define the extended capabilities based on
their value and index within the list.
"""
buf = (ctypes.c_uint8 * 32)()
self._dll.JLINKARM_GetEmuCapsEx(buf, 32)
return list(buf)
@open_required
def extended_capability(self, capability):
"""Checks if the emulator has the given extended capability.
Args:
self (JLink): the ``JLink`` instance
capability (int): capability being queried
Returns:
``True`` if the emulator has the given extended capability, otherwise
``False``.
"""
res = self._dll.JLINKARM_EMU_HasCapEx(capability)
return res == 1
@property
@open_required
def features(self):
"""Returns a list of the J-Link embedded features.
Args:
self (JLink): the ``JLink`` instance
Returns:
A list of strings, each a feature. Example:
``[ 'RDI', 'FlashBP', 'FlashDL', 'JFlash', 'GDB' ]``
"""
buf = (ctypes.c_char * self.MAX_BUF_SIZE)()
self._dll.JLINKARM_GetFeatureString(buf)
result = ctypes.string_at(buf).decode().strip()
if len(result) == 0:
return list()
return result.split(', ')
@property
@open_required
def product_name(self):
"""Returns the product name of the connected J-Link.
Args:
self (JLink): the ``JLink`` instance
Returns:
Product name.
"""
buf = (ctypes.c_char * self.MAX_BUF_SIZE)()
self._dll.JLINKARM_EMU_GetProductName(buf, self.MAX_BUF_SIZE)
return ctypes.string_at(buf).decode()
@property
@open_required
def serial_number(self):
"""Returns the serial number of the connected J-Link.
Args:
self (JLink): the ``JLink`` instance
Returns:
Serial number as an integer.
"""
return self._dll.JLINKARM_GetSN()
@property
@open_required
def oem(self):
"""Retrieves and returns the OEM string of the connected J-Link.
Args:
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.
"""
buf = (ctypes.c_char * self.MAX_BUF_SIZE)()
res = self._dll.JLINKARM_GetOEMString(ctypes.byref(buf))
if res != 0:
raise errors.JLinkException('Failed to grab OEM string.')
oem = ctypes.string_at(buf).decode()
if len(oem) == 0:
return
return oem
@property
@open_required
def index(self):
"""Retrieves and returns the index number of the actual selected
J-Link.
Args:
self (JLink): the ``JLink`` instance
Returns:
Index of the currently connected J-Link.
"""
return self._dll.JLINKARM_GetSelDevice()
@property
@open_required
def speed(self):
"""Returns the current JTAG connection speed.
Args:
self (JLink): the ``JLink`` instance
Returns:
JTAG connection speed.
"""
return self._dll.JLINKARM_GetSpeed()
@open_required
def set_speed(self, speed=None, auto=False, adaptive=False):
"""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``.
Args:
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.
"""
if speed is None:
speed = 0
else:
if not util.is_natural(speed):
raise TypeError('Expected positive number for speed, given %s.' % speed)
else:
if speed > self.MAX_JTAG_SPEED:
raise ValueError('Given speed exceeds max speed of %d.' % self.MAX_JTAG_SPEED)
else:
if speed < self.MIN_JTAG_SPEED:
raise ValueError('Given speed is too slow. Minimum is %d.' % self.MIN_JTAG_SPEED)
if auto:
speed = speed | self.AUTO_JTAG_SPEED
if adaptive:
speed = speed | self.ADAPTIVE_JTAG_SPEED
self._dll.JLINKARM_SetSpeed(speed)
@open_required
def set_max_speed(self):
"""Sets JTAG communication speed to the maximum supported speed.
Args:
self (JLink): the ``JLink`` instance
Returns:
``None``
"""
self._dll.JLINKARM_SetMaxSpeed()
@property
@open_required
def speed_info(self):
"""Retrieves information about supported target interface speeds.
Args:
self (JLink): the ``JLink`` instance
Returns:
The ``JLinkSpeedInfo`` instance describing the supported target
interface speeds.
"""
speed_info = structs.JLinkSpeedInfo()
self._dll.JLINKARM_GetSpeedInfo(ctypes.byref(speed_info))
return speed_info
@property
@open_required
def licenses(self):
"""Returns a string of the built-in licenses the J-Link has.
Args:
self (JLink): the ``JLink`` instance
Returns:
String of the contents of the built-in licenses the J-Link has.
"""
buf_size = self.MAX_BUF_SIZE
buf = (ctypes.c_char * buf_size)()
res = self._dll.JLINK_GetAvailableLicense(buf, buf_size)
if res < 0:
raise errors.JLinkException(res)
return ctypes.string_at(buf).decode()
@property
@open_required
@minimum_required('4.98b')
def custom_licenses(self):
"""Returns a string of the installed licenses the J-Link has.
Args:
self (JLink): the ``JLink`` instance
Returns:
String of the contents of the custom licenses the J-Link has.
"""
buf = (ctypes.c_char * self.MAX_BUF_SIZE)()
result = self._dll.JLINK_EMU_GetLicenses(buf, self.MAX_BUF_SIZE)
if result < 0:
raise errors.JLinkException(result)
return ctypes.string_at(buf).decode()
@open_required
@minimum_required('4.98b')
def add_license(self, contents):
"""Adds the given ``contents`` as a new custom license to the J-Link.
Args:
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.
"""
buf_size = len(contents)
buf = (ctypes.c_char * (buf_size + 1))(*contents.encode())
res = self._dll.JLINK_EMU_AddLicense(buf)
if res == -1:
raise errors.JLinkException('Unspecified error.')
else:
if res == -2:
raise errors.JLinkException('Failed to read/write license area.')
else:
if res == -3:
raise errors.JLinkException('J-Link out of space.')
return res == 0
@open_required
@minimum_required('4.98b')
def erase_licenses(self):
"""Erases the custom licenses from the connected J-Link.
Note:
This method will erase all licenses stored on the J-Link.
Args:
self (JLink): the ``JLink`` instance
Returns:
``True`` on success, otherwise ``False``.
"""
res = self._dll.JLINK_EMU_EraseLicenses()
return res == 0
@property
@open_required
def tif(self):
"""Returns the current target interface of the J-Link.
Args:
self (JLink): the ``JLink`` instance
Returns:
Integer specifying the current target interface.
"""
return self._tif
@open_required
def supported_tifs(self):
"""Returns a bitmask of the supported target interfaces.
Args:
self (JLink): the ``JLink`` instance
Returns:
Bitfield specifying which target interfaces are supported.
"""
buf = ctypes.c_uint32()
self._dll.JLINKARM_TIF_GetAvailable(ctypes.byref(buf))
return buf.value
@open_required
def set_tif(self, interface):
"""Selects the specified target interface.
Note that a restart must be triggered for this to take effect.
Args:
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.
"""
if not 1 << interface & self.supported_tifs():
raise errors.JLinkException('Unsupported target interface: %s' % interface)
res = self._dll.JLINKARM_TIF_Select(interface)
if res != 0:
return False
self._tif = interface
return True
@open_required
def gpio_properties(self):
"""Returns the properties of the user-controllable GPIOs.
Provided the device supports user-controllable GPIOs, they will be
returned by this method.
Args:
self (JLink): the ``JLink`` instance
Returns:
A list of ``JLinkGPIODescriptor`` instances totalling the number of
requested properties.
Raises:
JLinkException: on error.
"""
res = self._dll.JLINK_EMU_GPIO_GetProps(0, 0)
if res < 0:
raise errors.JLinkException(res)
num_props = res
buf = (structs.JLinkGPIODescriptor * num_props)()
res = self._dll.JLINK_EMU_GPIO_GetProps(ctypes.byref(buf), num_props)
if res < 0:
raise errors.JLinkException(res)
return list(buf)
@open_required
def gpio_get(self, pins=None):
"""Returns a list of states for the given pins.
Defaults to the first four pins if an argument is not given.
Args:
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.
"""
if pins is None:
pins = range(4)
size = len(pins)
indices = (ctypes.c_uint8 * size)(*pins)
statuses = (ctypes.c_uint8 * size)()
result = self._dll.JLINK_EMU_GPIO_GetState(ctypes.byref(indices), ctypes.byref(statuses), size)
if result < 0:
raise errors.JLinkException(result)
return list(statuses)
@open_required
def gpio_set(self, pins, states):
"""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.
Args:
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)``
"""
if len(pins) != len(states):
raise ValueError('Length mismatch between pins and states.')
size = len(pins)
indices = (ctypes.c_uint8 * size)(*pins)
states = (ctypes.c_uint8 * size)(*states)
result_states = (ctypes.c_uint8 * size)()
result = self._dll.JLINK_EMU_GPIO_SetState(ctypes.byref(indices), ctypes.byref(states), ctypes.byref(result_states), size)
if result < 0:
raise errors.JLinkException(result)
return list(result_states)
@open_required
def comm_supported(self):
"""Returns true if the connected emulator supports ``comm_*``
functions.
Args:
self (JLink): the ``JLink`` instance
Returns:
``True`` if the emulator supports ``comm_*`` functions, otherwise
``False``.
"""
return bool(self._dll.JLINKARM_EMU_COM_IsSupported())
@open_required
def power_on(self, default=False):
"""Turns on the power supply over pin 19 of the JTAG connector.
If given the optional ``default`` parameter, activates the power supply
by default.
Args:
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.
"""
if default:
return self.exec_command('SupplyPowerDefault = 1')
return self.exec_command('SupplyPower = 1')
@open_required
def power_off(self, default=False):
"""Turns off the power supply over pin 19 of the JTAG connector.
If given the optional ``default`` parameter, deactivates the power supply
by default.
Args:
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.
"""
if default:
return self.exec_command('SupplyPowerDefault = 0')
return self.exec_command('SupplyPower = 0')
@connection_required
def unlock(self):
"""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.
"""
if not unlockers.unlock(self, self._device.manufacturer):
raise errors.JLinkException('Failed to unlock device.')
return True
@connection_required
def cpu_capability(self, capability):
"""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.
Args:
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``.
"""
res = self._dll.JLINKARM_EMU_HasCPUCap(capability)
return res == 1
@connection_required
def set_trace_source(self, source):
"""Sets the source to be used for tracing.
The ``source`` must be one of the ones provided by
``enums.JLinkTraceSource``.
Args:
self (JLink): the ``JLink`` instance.
source (int): the source to use.
Returns:
``None``
"""
self._dll.JLINKARM_SelectTraceSource(source)
@connection_required
def set_etb_trace(self):
"""Sets the trace source to ETB.
Args:
self (JLink): the ``JLink`` instance.
Returns:
``None``
"""
return self.set_trace_source(enums.JLinkTraceSource.ETB)
@connection_required
def set_etm_trace(self):
"""Sets the trace source to ETM.
Args:
self (JLink): the ``JLink`` instance.
Returns:
``None``
"""
return self.set_trace_source(enums.JLinkTraceSource.ETM)
@connection_required
def set_reset_strategy(self, strategy):
"""Sets the reset strategy for the target.
The reset strategy defines what happens when the target is reset.
Args:
self (JLink): the ``JLink`` instance
strategy (int): the reset strategy to use
Returns:
The previous reset streategy.
"""
return self._dll.JLINKARM_SetResetType(strategy)
@connection_required
def set_reset_pin_high(self):
"""Sets the reset pin high.
Args:
self (JLink): the ``JLink`` instance
Returns:
``None``
"""
self._dll.JLINKARM_SetRESET()
@connection_required
def set_reset_pin_low(self):
"""Sets the reset pin low.
Args:
self (JLink): the ``JLink`` instance
Returns:
``None``
"""
self._dll.JLINKARM_ClrRESET()
@connection_required
def set_tck_pin_high(self):
"""Sets the TCK pin to the high value (1).
Args:
self (JLink): the ``JLink`` instance
Returns:
``None``
Raises:
JLinkException: if the emulator does not support this feature.
"""
res = self._dll.JLINKARM_SetTCK()
if res < 0:
raise errors.JLinkException('Feature not supported.')
@connection_required
def set_tck_pin_low(self):
"""Sets the TCK pin to the low value (0).
Args:
self (JLink): the ``JLink`` instance
Returns:
``None``
Raises:
JLinkException: if the emulator does not support this feature.
"""
res = self._dll.JLINKARM_ClrTCK()
if res < 0:
raise errors.JLinkException('Feature not supported.')
@connection_required
def set_tdi_pin_high(self):
"""Sets the test data input to logical ``1``.
Args:
self (JLink): the ``JLink`` instance
Returns:
``None``
"""
self._dll.JLINKARM_SetTDI()
@connection_required
def set_tdi_pin_low(self):
"""Clears the test data input.
TDI is set to logical ``0`` (Ground).
Args:
self (JLink): the ``JLink`` instance
Returns:
``None``
"""
self._dll.JLINKARM_ClrTDI()
@connection_required
def set_tms_pin_high(self):
"""Sets the test mode select to logical ``1``.
Args:
self (JLink): the ``JLink`` instance
Returns:
``None``
"""
self._dll.JLINKARM_SetTMS()
@connection_required
def set_tms_pin_low(self):
"""Clears the test mode select.
TMS is set to logical ``0`` (Ground).
Args:
self (JLink): the ``JLink`` instance
Returns:
``None``
"""
self._dll.JLINKARM_ClrTMS()
@connection_required
def set_trst_pin_high(self):
"""Sets the TRST pin to high (``1``).
Deasserts the TRST pin.
Args:
self (JLink): the ``JLink`` instance
Returns:
``None``
"""
self._dll.JLINKARM_SetTRST()
@connection_required
def set_trst_pin_low(self):
"""Sets the TRST pin to low (``0``).
This asserts the TRST pin.
Args:
self (JLink): the ``JLink`` instance
Returns:
``None``
"""
self._dll.JLINKARM_ClrTRST()
@connection_required
def erase(self):
"""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.
Args:
self (JLink): the ``JLink`` instance
Returns:
Number of bytes erased.
"""
try:
if not self.halted():
self.halt()
except errors.JLinkException:
pass
res = self._dll.JLINK_EraseChip()
if res < 0:
raise errors.JLinkEraseException(res)
return res
@connection_required
def flash(self, data, addr, on_progress=None, power_on=False, flags=0):
"""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``.
Args:
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.
"""
if flags != 0:
raise errors.JLinkException('Flags are reserved for future use.')
if on_progress is not None:
func = enums.JLinkFunctions.FLASH_PROGRESS_PROTOTYPE(on_progress)
self._dll.JLINK_SetFlashProgProgressCallback(func)
else:
self._dll.JLINK_SetFlashProgProgressCallback(0)
if power_on:
self.power_on()
try:
if not self.halted():
self.halt()
except errors.JLinkException:
pass
res = self.flash_write(addr, data, flags=flags)
return res
@connection_required
def flash_file(self, path, addr, on_progress=None, power_on=False):
"""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``.
Args:
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.
"""
if on_progress is not None:
func = enums.JLinkFunctions.FLASH_PROGRESS_PROTOTYPE(on_progress)
self._dll.JLINK_SetFlashProgProgressCallback(func)
else:
self._dll.JLINK_SetFlashProgProgressCallback(0)
if power_on:
self.power_on()
try:
if not self.halted():
self.halt()
except errors.JLinkException:
pass
bytes_flashed = self._dll.JLINK_DownloadFile(path.encode(), addr)
if bytes_flashed < 0:
raise errors.JLinkFlashException(bytes_flashed)
return bytes_flashed
@connection_required
def reset(self, ms=0, halt=True):
"""Resets the target.
This method resets the target, and by default toggles the RESET and
TRST pins.
Args:
self (JLink): the ``JLink`` instance
ms (int): Amount of milliseconds to delay after reset (default: 0)
halt (bool): if the CPU should halt after reset (default: True)
Returns:
Number of bytes read.
"""
self._dll.JLINKARM_SetResetDelay(ms)
res = self._dll.JLINKARM_Reset()
if res < 0:
raise errors.JLinkException(res)
else:
if not halt:
self._dll.JLINKARM_Go()
return res
@connection_required
def reset_tap(self):
"""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.
Args:
self (JLink): the ``JLink`` instance
Returns:
``None``
"""
self._dll.JLINKARM_ResetTRST()
@connection_required
def restart(self, num_instructions=0, skip_breakpoints=False):
"""Restarts the CPU core and simulates/emulates instructions.
Note:
This is a no-op if the CPU isn't halted.
Args:
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.
"""
if not util.is_natural(num_instructions):
raise ValueError('Invalid instruction count: %s.' % num_instructions)
if not self.halted():
return False
flags = 0
if skip_breakpoints:
flags = flags | enums.JLinkFlags.GO_OVERSTEP_BP
self._dll.JLINKARM_GoEx(num_instructions, flags)
return True
@connection_required
@decorators.async_decorator
def halt(self):
"""Halts the CPU Core.
Args:
self (JLink): the ``JLink`` instance
Returns:
``True`` if halted, ``False`` otherwise.
"""
res = int(self._dll.JLINKARM_Halt())
if res == 0:
time.sleep(1)
return True
return False
@connection_required
def halted(self):
"""Returns whether the CPU core was halted.
Args:
self (JLink): the ``JLink`` instance
Returns:
``True`` if the CPU core is halted, otherwise ``False``.
Raises:
JLinkException: on device errors.
"""
result = int(self._dll.JLINKARM_IsHalted())
if result < 0:
raise errors.JLinkException(result)
return result > 0
@connection_required
def core_id(self):
"""Returns the identifier of the target ARM core.
Args:
self (JLink): the ``JLink`` instance
Returns:
Integer identifier of ARM core.
"""
return self._dll.JLINKARM_GetId()
@connection_required
def core_cpu(self):
"""Returns the identifier of the core CPU.
Note:
This is distinct from the value returned from ``core_id()`` which is
the ARM specific identifier.
Args:
self (JLink): the ``JLink`` instance
Returns:
The identifier of the CPU core.
"""
return self._dll.JLINKARM_CORE_GetFound()
@connection_required
def core_name(self):
"""Returns the name of the target ARM core.
Args:
self (JLink): the ``JLink`` instance
Returns:
The target core's name.
"""
buf_size = self.MAX_BUF_SIZE
buf = (ctypes.c_char * buf_size)()
self._dll.JLINKARM_Core2CoreName(self.core_cpu(), buf, buf_size)
return ctypes.string_at(buf).decode()
@connection_required
def ir_len(self):
"""Counts and returns the total length of instruction registers of all
the devices in the JTAG scan chain.
Args:
self (JLink): the ``JLink`` instance
Returns:
Total instruction register length.
"""
return self._dll.JLINKARM_GetIRLen()
@connection_required
def scan_len(self):
"""Retrieves and returns the length of the scan chain select register.
Args:
self (JLink): the ``JLink`` instance
Returns:
Length of the scan chain select register.
"""
return self._dll.JLINKARM_GetScanLen()
@connection_required
def scan_chain_len(self, scan_chain):
"""Retrieves and returns the number of bits in the scan chain.
Args:
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.
"""
res = self._dll.JLINKARM_MeasureSCLen(scan_chain)
if res < 0:
raise errors.JLinkException(res)
return res
@connection_required
def device_family(self):
"""Returns the device family of the target CPU.
Args:
self (JLink): the ``JLink`` instance
Returns:
Integer identifier of the device family.
"""
return self._dll.JLINKARM_GetDeviceFamily()
@connection_required
def register_list(self):
"""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.
Args:
self (JLink): the ``JLink`` instance
Returns:
List of registers.
"""
num_items = self.MAX_NUM_CPU_REGISTERS
buf = (ctypes.c_uint32 * num_items)()
num_regs = self._dll.JLINKARM_GetRegisterList(buf, num_items)
return buf[:num_regs]
@connection_required
def register_name(self, register_index):
"""Retrives and returns the name of an ARM CPU register.
Args:
self (JLink): the ``JLink`` instance
register_index (int): index of the register whose name to retrieve
Returns:
Name of the register.
"""
result = self._dll.JLINKARM_GetRegisterName(register_index)
return ctypes.cast(result, ctypes.c_char_p).value.decode()
@connection_required
def cpu_speed(self, silent=False):
"""Retrieves the CPU speed of the target.
If the target does not support CPU frequency detection, this function
will return ``0``.
Args:
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.
"""
res = self._dll.JLINKARM_MeasureCPUSpeedEx(-1, 1, int(silent))
if res < 0:
raise errors.JLinkException(res)
return res
@connection_required
def cpu_halt_reasons(self):
"""Retrives the reasons that the CPU was halted.
Args:
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.
"""
buf_size = self.MAX_NUM_MOES
buf = (structs.JLinkMOEInfo * buf_size)()
num_reasons = self._dll.JLINKARM_GetMOEs(buf, buf_size)
if num_reasons < 0:
raise errors.JLinkException(num_reasons)
return list(buf)[:num_reasons]
@connection_required
def jtag_create_clock(self):
"""Creates a JTAG clock on TCK.
Note:
This function only needs to be called once.
Args:
self (JLink): the ``JLink`` instance
Returns:
The state of the TDO pin: either ``0`` or ``1``.
"""
return self._dll.JLINKARM_Clock()
@connection_required
def jtag_send(self, tms, tdi, num_bits):
"""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.
Args:
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 <https://www.xjtag.com/about-jtag/jtag-a-technical-overview>`_.
"""
if util.is_natural(num_bits) and num_bits <= 0 or num_bits > 32:
raise ValueError('Number of bits must be >= 1 and <= 32.')
self._dll.JLINKARM_StoreBits(tms, tdi, num_bits)
@connection_required
def jtag_flush(self):
"""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.
Args:
self (JLink): the ``JLink`` instance
Returns:
``None``
"""
self._dll.JLINKARM_WriteBits()
@interface_required(enums.JLinkInterfaces.SWD)
@connection_required
def swd_read8(self, offset):
"""Gets a unit of ``8`` bits from the input buffer.
Args:
self (JLink): the ``JLink`` instance
offset (int): the offset (in bits) from which to start reading
Returns:
The integer read from the input buffer.
"""
value = self._dll.JLINK_SWD_GetU8(offset)
return ctypes.c_uint8(value).value
@interface_required(enums.JLinkInterfaces.SWD)
@connection_required
def swd_read16(self, offset):
"""Gets a unit of ``16`` bits from the input buffer.
Args:
self (JLink): the ``JLink`` instance
offset (int): the offset (in bits) from which to start reading
Returns:
The integer read from the input buffer.
"""
value = self._dll.JLINK_SWD_GetU16(offset)
return ctypes.c_uint16(value).value
@interface_required(enums.JLinkInterfaces.SWD)
@connection_required
def swd_read32(self, offset):
"""Gets a unit of ``32`` bits from the input buffer.
Args:
self (JLink): the ``JLink`` instance
offset (int): the offset (in bits) from which to start reading
Returns:
The integer read from the input buffer.
"""
value = self._dll.JLINK_SWD_GetU32(offset)
return ctypes.c_uint32(value).value
@interface_required(enums.JLinkInterfaces.SWD)
@connection_required
def swd_write(self, output, value, nbits):
"""Writes bytes over SWD (Serial Wire Debug).
Args:
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.
"""
pDir = binpacker.pack(output, nbits)
pIn = binpacker.pack(value, nbits)
bitpos = self._dll.JLINK_SWD_StoreRaw(pDir, pIn, nbits)
if bitpos < 0:
raise errors.JLinkException(bitpos)
return bitpos
@interface_required(enums.JLinkInterfaces.SWD)
@connection_required
def swd_write8(self, output, value):
"""Writes one byte over SWD (Serial Wire Debug).
Args:
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.
"""
return self.swd_write(output, value, 8)
@interface_required(enums.JLinkInterfaces.SWD)
@connection_required
def swd_write16(self, output, value):
"""Writes two bytes over SWD (Serial Wire Debug).
Args:
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.
"""
return self.swd_write(output, value, 16)
@interface_required(enums.JLinkInterfaces.SWD)
@connection_required
def swd_write32(self, output, value):
"""Writes four bytes over SWD (Serial Wire Debug).
Args:
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.
"""
return self.swd_write(output, value, 32)
@interface_required(enums.JLinkInterfaces.SWD)
@connection_required
def swd_sync(self, pad=False):
"""Causes a flush to write all data remaining in output buffers to SWD
device.
Args:
self (JLink): the ``JLink`` instance
pad (bool): ``True`` if should pad the data to full byte size
Returns:
``None``
"""
if pad:
self._dll.JLINK_SWD_SyncBytes()
else:
self._dll.JLINK_SWD_SyncBits()
@connection_required
def flash_write(self, addr, data, nbits=None, flags=0):
"""Writes data to the flash region of a device.
The given number of bits, if provided, must be either ``8``, ``16``, or
``32``.
Args:
self (JLink): the ``JLink`` instance
addr (int): starting flash address to write to
data (list): list of data units to write
nbits (int): number of bits to use for each unit
Returns:
Number of bytes written to flash.
"""
self._dll.JLINKARM_BeginDownload(flags)
self.memory_write(addr, data, nbits=nbits)
bytes_flashed = self._dll.JLINKARM_EndDownload()
if bytes_flashed < 0:
raise errors.JLinkFlashException(bytes_flashed)
return bytes_flashed
@connection_required
def flash_write8(self, addr, data):
"""Writes bytes to the flash region of a device.
Args:
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.
"""
return self.flash_write(addr, data, 8)
@connection_required
def flash_write16(self, addr, data):
"""Writes halfwords to the flash region of a device.
Args:
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.
"""
return self.flash_write(addr, data, 16)
@connection_required
def flash_write32(self, addr, data):
"""Writes words to the flash region of a device.
Args:
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.
"""
return self.flash_write(addr, data, 32)
@connection_required
def code_memory_read(self, addr, num_bytes):
"""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.
Args:
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.
"""
buf_size = num_bytes
buf = (ctypes.c_uint8 * buf_size)()
res = self._dll.JLINKARM_ReadCodeMem(addr, buf_size, buf)
if res < 0:
raise errors.JLinkException(res)
return list(buf)[:res]
@connection_required
def num_memory_zones(self):
"""Returns the number of memory zones supported by the target.
Args:
self (JLink): the ``JLink`` instance
Returns:
An integer count of the number of memory zones supported by the
target.
Raises:
JLinkException: on error.
"""
count = self._dll.JLINK_GetMemZones(0, 0)
if count < 0:
raise errors.JLinkException(count)
return count
@connection_required
def memory_zones(self):
"""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.
Args:
self (JLink): the ``JLink`` instance
Returns:
A list of all the memory zones as ``JLinkMemoryZone`` structures.
Raises:
JLinkException: on hardware errors.
"""
count = self.num_memory_zones()
if count == 0:
return list()
buf = (structs.JLinkMemoryZone * count)()
res = self._dll.JLINK_GetMemZones(buf, count)
if res < 0:
raise errors.JLinkException(res)
return list(buf)
@connection_required
def memory_read(self, addr, num_units, zone=None, nbits=None):
"""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.
Args:
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``.
"""
buf_size = num_units
buf = None
access = 0
if nbits is None:
buf = (ctypes.c_uint8 * buf_size)()
access = 0
else:
if nbits == 8:
buf = (ctypes.c_uint8 * buf_size)()
access = 1
else:
if nbits == 16:
buf = (ctypes.c_uint16 * buf_size)()
access = 2
buf_size = buf_size * access
else:
if nbits == 32:
buf = (ctypes.c_uint32 * buf_size)()
access = 4
buf_size = buf_size * access
else:
raise ValueError('Given bit size is invalid: %s' % nbits)
args = [
addr, buf_size, buf, access]
method = self._dll.JLINKARM_ReadMemEx
if zone is not None:
method = self._dll.JLINKARM_ReadMemZonedEx
args.append(zone.encode())
units_read = method(*args)
if units_read < 0:
raise errors.JLinkReadException(units_read)
return buf[:units_read]
@connection_required
def memory_read8(self, addr, num_bytes, zone=None):
"""Reads memory from the target system in units of bytes.
Args:
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.
"""
return self.memory_read(addr, num_bytes, zone=zone, nbits=8)
@connection_required
def memory_read16(self, addr, num_halfwords, zone=None):
"""Reads memory from the target system in units of 16-bits.
Args:
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
"""
return self.memory_read(addr, num_halfwords, zone=zone, nbits=16)
@connection_required
def memory_read32(self, addr, num_words, zone=None):
"""Reads memory from the target system in units of 32-bits.
Args:
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
"""
return self.memory_read(addr, num_words, zone=zone, nbits=32)
@connection_required
def memory_read64(self, addr, num_long_words):
"""Reads memory from the target system in units of 64-bits.
Args:
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
"""
buf_size = num_long_words
buf = (ctypes.c_ulonglong * buf_size)()
units_read = self._dll.JLINKARM_ReadMemU64(addr, buf_size, buf, 0)
if units_read < 0:
raise errors.JLinkException(units_read)
return buf[:units_read]
@connection_required
def memory_write(self, addr, data, zone=None, nbits=None):
"""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``.
Args:
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``.
"""
buf_size = len(data)
buf = None
access = 0
if nbits is None:
packed_data = map(lambda d: reversed(binpacker.pack(d))
, data)
packed_data = list((itertools.chain)(*packed_data))
buf_size = len(packed_data)
buf = (ctypes.c_uint8 * buf_size)(*packed_data)
access = 0
else:
if nbits == 8:
buf = (ctypes.c_uint8 * buf_size)(*data)
access = 1
else:
if nbits == 16:
buf = (ctypes.c_uint16 * buf_size)(*data)
access = 2
buf_size = buf_size * access
else:
if nbits == 32:
buf = (ctypes.c_uint32 * buf_size)(*data)
access = 4
buf_size = buf_size * access
else:
raise ValueError('Given bit size is invalid: %s' % nbits)
args = [
addr, buf_size, buf, access]
method = self._dll.JLINKARM_WriteMemEx
if zone is not None:
method = self._dll.JLINKARM_WriteMemZonedEx
args.append(zone.encode())
units_written = method(*args)
if units_written < 0:
raise errors.JLinkWriteException(units_written)
return units_written
@connection_required
def memory_write8(self, addr, data, zone=None):
"""Writes bytes to memory of a target system.
Args:
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.
"""
return self.memory_write(addr, data, zone, 8)
@connection_required
def memory_write16(self, addr, data, zone=None):
"""Writes half-words to memory of a target system.
Args:
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.
"""
return self.memory_write(addr, data, zone, 16)
@connection_required
def memory_write32(self, addr, data, zone=None):
"""Writes words to memory of a target system.
Args:
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.
"""
return self.memory_write(addr, data, zone, 32)
@connection_required
def memory_write64(self, addr, data, zone=None):
"""Writes long words to memory of a target system.
Note:
This is little-endian.
Args:
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.
"""
words = []
bitmask = 4294967295
for long_word in data:
words.append(long_word & bitmask)
words.append(long_word >> 32 & bitmask)
return self.memory_write32(addr, words, zone=zone)
@connection_required
def register_read(self, register_index):
"""Reads the value from the given register.
Args:
self (JLink): the ``JLink`` instance
register_index (int/str): the register to read
Returns:
The value stored in the given register.
"""
if isinstance(register_index, six.string_types):
register_index = self._get_register_index_from_name(register_index)
return self._dll.JLINKARM_ReadReg(register_index)
@connection_required
def register_read_multiple(self, register_indices):
"""Retrieves the values from the registers specified.
Args:
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_indices = register_indices[:]
num_regs = len(register_indices)
for idx, indice in enumerate(register_indices):
if isinstance(indice, six.string_types):
register_indices[idx] = self._get_register_index_from_name(indice)
buf = (ctypes.c_uint32 * num_regs)(*register_indices)
data = ctypes.c_uint32 * num_regs(0)
statuses = ctypes.c_uint8 * num_regs(0)
res = self._dll.JLINKARM_ReadRegs(buf, data, statuses, num_regs)
if res < 0:
raise errors.JLinkException(res)
return list(data)
@connection_required
def register_write(self, reg_index, value):
"""Writes into an ARM register.
Note:
The data is not immediately written, but is cached before being
transferred to the CPU on CPU start.
Args:
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.
"""
if isinstance(reg_index, six.string_types):
reg_index = self._get_register_index_from_name(reg_index)
res = self._dll.JLINKARM_WriteReg(reg_index, value)
if res != 0:
raise errors.JLinkException('Error writing to register %d' % reg_index)
return value
@connection_required
def register_write_multiple(self, register_indices, values):
"""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.
Args:
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
"""
register_indices = register_indices[:]
if len(register_indices) != len(values):
raise ValueError('Must be an equal number of registers and values')
num_regs = len(register_indices)
for idx, indice in enumerate(register_indices):
if isinstance(indice, six.string_types):
register_indices[idx] = self._get_register_index_from_name(indice)
buf = (ctypes.c_uint32 * num_regs)(*register_indices)
data = (ctypes.c_uint32 * num_regs)(*values)
statuses = ctypes.c_uint8 * num_regs(0)
res = self._dll.JLINKARM_WriteRegs(buf, data, statuses, num_regs)
if res != 0:
raise errors.JLinkException(res)
@connection_required
def ice_register_read(self, register_index):
"""Reads a value from an ARM ICE register.
Args:
self (JLink): the ``JLink`` instance
register_index (int): the register to read
Returns:
The value read from the register.
"""
return self._dll.JLINKARM_ReadICEReg(register_index)
@connection_required
def ice_register_write(self, register_index, value, delay=False):
"""Writes a value to an ARM ICE register.
Args:
self (JLink): the ``JLink`` instance
register_index (int): the ICE register to write to
value (int): the value to write to the ICE register
delay (bool): boolean specifying if the write should be delayed
Returns:
``None``
"""
self._dll.JLINKARM_WriteICEReg(register_index, int(value), int(delay))
@connection_required
def etm_supported(self):
"""Returns if the CPU core supports ETM.
Args:
self (JLink): the ``JLink`` instance.
Returns:
``True`` if the CPU has the ETM unit, otherwise ``False``.
"""
res = self._dll.JLINKARM_ETM_IsPresent()
if res == 1:
return True
info = ctypes.c_uint32(0)
index = enums.JLinkROMTable.ETM
res = self._dll.JLINKARM_GetDebugInfo(index, ctypes.byref(info))
if res == 1:
return False
return True
@connection_required
def etm_register_read(self, register_index):
"""Reads a value from an ETM register.
Args:
self (JLink): the ``JLink`` instance.
register_index (int): the register to read.
Returns:
The value read from the ETM register.
"""
return self._dll.JLINKARM_ETM_ReadReg(register_index)
@connection_required
def etm_register_write(self, register_index, value, delay=False):
"""Writes a value to an ETM register.
Args:
self (JLink): the ``JLink`` instance.
register_index (int): the register to write to.
value (int): the value to write to the register.
delay (bool): boolean specifying if the write should be buffered.
Returns:
``None``
"""
self._dll.JLINKARM_ETM_WriteReg(int(register_index), int(value), int(delay))
@connection_required
def coresight_read(self, reg, ap=True):
"""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.
Args:
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
"""
data = ctypes.c_uint32()
ap = 1 if ap else 0
res = self._dll.JLINKARM_CORESIGHT_ReadAPDPReg(reg, ap, ctypes.byref(data))
if res < 0:
raise errors.JLinkException(res)
return data.value
@connection_required
def coresight_write(self, reg, data, ap=True):
"""Writes an Ap/DP register on a CoreSight DAP.
Note:
``coresight_configure()`` must be called prior to calling this method.
Args:
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
"""
ap = 1 if ap else 0
res = self._dll.JLINKARM_CORESIGHT_WriteAPDPReg(reg, ap, data)
if res < 0:
raise errors.JLinkException(res)
return res
@connection_required
def enable_reset_pulls_reset(self):
"""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.
Args:
self (JLink): the ``JLink`` instance
Returns:
``None``
"""
self._dll.JLINKARM_ResetPullsRESET(1)
@connection_required
def disable_reset_pulls_reset(self):
"""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.
Args:
self (JLink): the ``JLink`` instance
Returns:
``None``
"""
self._dll.JLINKARM_ResetPullsRESET(0)
@connection_required
def enable_reset_pulls_trst(self):
"""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.
Args:
self (JLink): the ``JLink`` instance
Returns:
``None``
"""
self._dll.JLINKARM_ResetPullsTRST(1)
@connection_required
def disable_reset_pulls_trst(self):
"""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.
Args:
self (JLink): the ``JLink`` instance
Returns:
``None``
"""
self._dll.JLINKARM_ResetPullsTRST(0)
@connection_required
def enable_reset_inits_registers(self):
"""Enables CPU register initialization on resets.
When ``.reset()`` is called, it will initialize the CPU registers.
Args:
self (JLink): the ``JLink`` instance
Returns:
``True`` if was previously enabled, otherwise ``False``.
"""
return bool(self._dll.JLINKARM_SetInitRegsOnReset(1))
@connection_required
def disable_reset_inits_registers(self):
"""Disables CPU register initialization on resets.
When ``.reset()`` is called, the CPU registers will be read and not
initialized.
Args:
self (JLink): the ``JLink`` instance
Returns:
``True`` if was previously enabled, otherwise ``False``.
"""
return bool(self._dll.JLINKARM_SetInitRegsOnReset(0))
@connection_required
def set_little_endian(self):
"""Sets the target hardware to little endian.
Args:
self (JLink): the ``JLink`` instance
Returns:
``True`` if target was big endian before call, otherwise ``False``.
"""
res = self._dll.JLINKARM_SetEndian(0)
return res == 1
@connection_required
def set_big_endian(self):
"""Sets the target hardware to big endian.
Args:
self (JLink): the ``JLink`` instance
Returns:
``True`` if target was little endian before call, otherwise ``False``.
"""
res = self._dll.JLINKARM_SetEndian(1)
return res == 0
@connection_required
def set_vector_catch(self, flags):
"""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.
Args:
self (JLink): the ``JLink`` instance
Returns:
``None``
Raises:
JLinkException: on error.
"""
res = self._dll.JLINKARM_WriteVectorCatch(flags)
if res < 0:
raise errors.JLinkException(res)
@connection_required
def step(self, thumb=False):
"""Executes a single step.
Steps even if there is a breakpoint.
Args:
self (JLink): the ``JLink`` instance
thumb (bool): boolean indicating if to step in thumb mode
Returns:
``None``
Raises:
JLinkException: on error
"""
method = self._dll.JLINKARM_Step
if thumb:
method = self._dll.JLINKARM_StepComposite
res = method()
if res != 0:
raise errors.JLinkException('Failed to step over instruction.')
@connection_required
def enable_soft_breakpoints(self):
"""Enables software breakpoints.
Note:
This should be called before calling ``software_breakpoint_set()``.
Args:
self (JLink): the ``JLink`` instance
Returns:
``None``
"""
self._dll.JLINKARM_EnableSoftBPs(1)
@connection_required
def disable_soft_breakpoints(self):
"""Disables software breakpoints.
Note:
After this function is called, ``software_breakpoint_set()`` cannot
be used without first calling ``enable_soft_breakpoints()``.
Args:
self (JLink): the ``JLink`` instance
Returns:
``None``
"""
self._dll.JLINKARM_EnableSoftBPs(0)
@connection_required
def num_active_breakpoints(self):
"""Returns the number of currently active breakpoints.
Args:
self (JLink): the ``JLink`` instance
Returns:
The number of breakpoints that are currently set.
"""
return self._dll.JLINKARM_GetNumBPs()
@connection_required
def num_available_breakpoints(self, arm=False, thumb=False, ram=False, flash=False, hw=False):
"""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.
Args:
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.
"""
flags = [
enums.JLinkBreakpoint.ARM,
enums.JLinkBreakpoint.THUMB,
enums.JLinkBreakpoint.SW_RAM,
enums.JLinkBreakpoint.SW_FLASH,
enums.JLinkBreakpoint.HW]
set_flags = [
arm,
thumb,
ram,
flash,
hw]
if not any(set_flags):
flags = enums.JLinkBreakpoint.ANY
else:
flags = list((f for i, f in enumerate(flags) if set_flags[i]))
flags = functools.reduce(operator.__or__, flags, 0)
return self._dll.JLINKARM_GetNumBPUnits(flags)
@connection_required
def breakpoint_info(self, handle=0, index=-1):
"""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``.
Args:
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.
"""
if index < 0:
if handle == 0:
raise ValueError('Handle must be provided if index is not set.')
bp = structs.JLinkBreakpointInfo()
bp.Handle = int(handle)
res = self._dll.JLINKARM_GetBPInfoEx(index, ctypes.byref(bp))
if res < 0:
raise errors.JLinkException('Failed to get breakpoint info.')
return bp
@connection_required
def breakpoint_find(self, addr):
"""Returns the handle of a breakpoint at the given address, if any.
Args:
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.
"""
return self._dll.JLINKARM_FindBP(addr)
@connection_required
def breakpoint_set(self, addr, thumb=False, arm=False):
"""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.
Args:
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.
"""
flags = enums.JLinkBreakpoint.ANY
if thumb:
flags = flags | enums.JLinkBreakpoint.THUMB
else:
if arm:
flags = flags | enums.JLinkBreakpoint.ARM
handle = self._dll.JLINKARM_SetBPEx(int(addr), flags)
if handle <= 0:
raise errors.JLinkException('Breakpoint could not be set.')
return handle
@connection_required
def software_breakpoint_set(self, addr, thumb=False, arm=False, flash=False, ram=False):
"""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.
Args:
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.
"""
if flash and not ram:
flags = enums.JLinkBreakpoint.SW_FLASH
else:
if not flash or ram:
flags = enums.JLinkBreakpoint.SW_RAM
else:
flags = enums.JLinkBreakpoint.SW
if thumb:
flags = flags | enums.JLinkBreakpoint.THUMB
else:
if arm:
flags = flags | enums.JLinkBreakpoint.ARM
handle = self._dll.JLINKARM_SetBPEx(int(addr), flags)
if handle <= 0:
raise errors.JLinkException('Software breakpoint could not be set.')
return handle
@connection_required
def hardware_breakpoint_set(self, addr, thumb=False, arm=False):
"""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.
Args:
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.
"""
flags = enums.JLinkBreakpoint.HW
if thumb:
flags = flags | enums.JLinkBreakpoint.THUMB
else:
if arm:
flags = flags | enums.JLinkBreakpoint.ARM
handle = self._dll.JLINKARM_SetBPEx(int(addr), flags)
if handle <= 0:
raise errors.JLinkException('Hardware breakpoint could not be set.')
return handle
@connection_required
def breakpoint_clear(self, handle):
"""Removes a single breakpoint.
Args:
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.
"""
return not self._dll.JLINKARM_ClrBPEx(handle)
@connection_required
def breakpoint_clear_all(self):
"""Removes all breakpoints that have been set.
Args:
self (JLink): the ``JLink`` instance
Returns:
``True`` if they were cleared, otherwise ``False``.
"""
return not self._dll.JLINKARM_ClrBPEx(4294967295)
@connection_required
def num_active_watchpoints(self):
"""Returns the number of currently active watchpoints.
Args:
self (JLink): the ``JLink`` instance
Returns:
The number of watchpoints that are currently set.
"""
return self._dll.JLINKARM_GetNumWPs()
@connection_required
def num_available_watchpoints(self):
"""Returns the number of available watchpoints.
Args:
self (JLink): the ``JLink`` instance
Returns:
The number of watchpoints that are available to be set.
"""
return self._dll.JLINKARM_GetNumWPUnits()
@connection_required
def watchpoint_info(self, handle=0, index=-1):
"""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``.
Args:
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.
"""
if index < 0:
if handle == 0:
raise ValueError('Handle must be provided if index is not set.')
wp = structs.JLinkWatchpointInfo()
res = self._dll.JLINKARM_GetWPInfoEx(index, ctypes.byref(wp))
if res < 0:
raise errors.JLinkException('Failed to get watchpoint info.')
for i in range(res):
res = self._dll.JLINKARM_GetWPInfoEx(i, ctypes.byref(wp))
if res < 0:
raise errors.JLinkException('Failed to get watchpoint info.')
if wp.Handle == handle or wp.WPUnit == index:
return wp
@connection_required
def watchpoint_set(self, addr, addr_mask=0, data=0, data_mask=0, access_size=None, read=False, write=False, privileged=False):
"""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.
Args:
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.
"""
access_flags = 0
access_mask_flags = 0
if access_size is None:
access_mask_flags = access_mask_flags | enums.JLinkAccessMaskFlags.SIZE
else:
if access_size == 8:
access_flags = access_flags | enums.JLinkAccessFlags.SIZE_8BIT
else:
if access_size == 16:
access_flags = access_flags | enums.JLinkAccessFlags.SIZE_16BIT
else:
if access_size == 32:
access_flags = access_flags | enums.JLinkAccessFlags.SIZE_32BIT
else:
raise ValueError('Invalid access size given: %d' % access_size)
if read and write:
access_mask_flags = access_mask_flags | enums.JLinkAccessMaskFlags.DIR
else:
if read:
access_flags = access_flags | enums.JLinkAccessFlags.READ
else:
if write:
access_flags = access_flags | enums.JLinkAccessFlags.WRITE
if privileged:
access_flags = access_flags | enums.JLinkAccessFlags.PRIV
else:
access_mask_flags = access_mask_flags | enums.JLinkAccessMaskFlags.PRIV
wp = structs.JLinkDataEvent()
wp.Addr = addr
wp.AddrMask = addr_mask
wp.Data = data
wp.DataMask = data_mask
wp.Access = access_flags
wp.AccessMask = access_mask_flags
handle = ctypes.c_uint32()
res = self._dll.JLINKARM_SetDataEvent(ctypes.pointer(wp), ctypes.pointer(handle))
if res < 0:
raise errors.JLinkDataException(res)
return handle.value
@connection_required
def watchpoint_clear(self, handle):
"""Clears the watchpoint with the specified handle.
Args:
self (JLink): the ``JLink`` instance
handle (int): the handle of the watchpoint
Returns:
``True`` if watchpoint was removed, otherwise ``False``.
"""
return not self._dll.JLINKARM_ClrDataEvent(handle)
@connection_required
def watchpoint_clear_all(self):
"""Removes all watchpoints that have been set.
Args:
self (JLink): the ``JLink`` instance
Returns:
``True`` if they were cleared, otherwise ``False``.
"""
return not self._dll.JLINKARM_ClrDataEvent(4294967295)
def disassemble_instruction(self, instruction):
"""Disassembles and returns the assembly instruction string.
Args:
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.
"""
if not util.is_integer(instruction):
raise TypeError('Expected instruction to be an integer.')
buf_size = self.MAX_BUF_SIZE
buf = (ctypes.c_char * buf_size)()
res = self._dll.JLINKARM_DisassembleInst(ctypes.byref(buf), buf_size, instruction)
if res < 0:
raise errors.JLinkException('Failed to disassemble instruction.')
return ctypes.string_at(buf).decode()
@connection_required
def strace_configure(self, port_width):
"""Configures the trace port width for tracing.
Note that configuration cannot occur while STRACE is running.
Args:
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.
"""
if port_width not in (1, 2, 4):
raise ValueError('Invalid port width: %s' % str(port_width))
config_string = 'PortWidth=%d' % port_width
res = self._dll.JLINK_STRACE_Config(config_string.encode())
if res < 0:
raise errors.JLinkException('Failed to configure STRACE port')
@connection_required
def strace_start(self):
"""Starts the capturing of STRACE data.
Args:
self (JLink): the ``JLink`` instance.
Returns:
``None``
Raises:
JLinkException: on error.
"""
res = self._dll.JLINK_STRACE_Start()
if res < 0:
raise errors.JLinkException('Failed to start STRACE.')
@connection_required
def strace_stop(self):
"""Stops the sampling of STRACE data.
Any capturing of STRACE data is automatically stopped when the CPU is
halted.
Args:
self (JLink): the ``JLink`` instance.
Returns:
``None``
Raises:
JLinkException: on error.
"""
res = self._dll.JLINK_STRACE_Stop()
if res < 0:
raise errors.JLinkException('Failed to stop STRACE.')
@connection_required
def strace_read(self, num_instructions):
"""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``).
Args:
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``.
"""
if num_instructions < 0 or num_instructions > 65536:
raise ValueError('Invalid instruction count.')
buf = (ctypes.c_uint32 * num_instructions)()
buf_size = num_instructions
res = self._dll.JLINK_STRACE_Read(ctypes.byref(buf), buf_size)
if res < 0:
raise errors.JLinkException('Failed to read from STRACE buffer.')
return list(buf)[:res]
@connection_required
def strace_code_fetch_event(self, operation, address, address_range=0):
"""Sets an event to trigger trace logic when an instruction is fetched.
Args:
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.
"""
cmd = enums.JLinkStraceCommand.TRACE_EVENT_SET
event_info = structs.JLinkStraceEventInfo()
event_info.Type = enums.JLinkStraceEvent.CODE_FETCH
event_info.Op = operation
event_info.Addr = int(address)
event_info.AddrRangeSize = int(address_range)
handle = self._dll.JLINK_STRACE_Control(cmd, ctypes.byref(event_info))
if handle < 0:
raise errors.JLinkException(handle)
return handle
@connection_required
def strace_data_access_event(self, operation, address, data, data_mask=None, access_width=4, address_range=0):
"""Sets an event to trigger trace logic when data access is made.
Data access corresponds to either a read or write.
Args:
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.
"""
cmd = enums.JLinkStraceCommand.TRACE_EVENT_SET
event_info = structs.JLinkStraceEventInfo()
event_info.Type = enums.JLinkStraceEvent.DATA_ACCESS
event_info.Op = operation
event_info.AccessSize = int(access_width)
event_info.Addr = int(address)
event_info.Data = int(data)
event_info.DataMask = int(data_mask or 0)
event_info.AddrRangeSize = int(address_range)
handle = self._dll.JLINK_STRACE_Control(cmd, ctypes.byref(event_info))
if handle < 0:
raise errors.JLinkException(handle)
return handle
@connection_required
def strace_data_load_event(self, operation, address, address_range=0):
"""Sets an event to trigger trace logic when data read access is made.
Args:
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.
"""
cmd = enums.JLinkStraceCommand.TRACE_EVENT_SET
event_info = structs.JLinkStraceEventInfo()
event_info.Type = enums.JLinkStraceEvent.DATA_LOAD
event_info.Op = operation
event_info.Addr = int(address)
event_info.AddrRangeSize = int(address_range)
handle = self._dll.JLINK_STRACE_Control(cmd, ctypes.byref(event_info))
if handle < 0:
raise errors.JLinkException(handle)
return handle
@connection_required
def strace_data_store_event(self, operation, address, address_range=0):
"""Sets an event to trigger trace logic when data write access is made.
Args:
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.
"""
cmd = enums.JLinkStraceCommand.TRACE_EVENT_SET
event_info = structs.JLinkStraceEventInfo()
event_info.Type = enums.JLinkStraceEvent.DATA_STORE
event_info.Op = operation
event_info.Addr = int(address)
event_info.AddrRangeSize = int(address_range)
handle = self._dll.JLINK_STRACE_Control(cmd, ctypes.byref(event_info))
if handle < 0:
raise errors.JLinkException(handle)
return handle
@connection_required
def strace_clear(self, handle):
"""Clears the trace event specified by the given handle.
Args:
self (JLink): the ``JLink`` instance.
handle (int): handle of the trace event.
Returns:
``None``
Raises:
JLinkException: on error.
"""
data = ctypes.c_int(handle)
res = self._dll.JLINK_STRACE_Control(enums.JLinkStraceCommand.TRACE_EVENT_CLR, ctypes.byref(data))
if res < 0:
raise errors.JLinkException('Failed to clear STRACE event.')
@connection_required
def strace_clear_all(self):
"""Clears all STRACE events.
Args:
self (JLink): the ``JLink`` instance.
Returns:
``None``
Raises:
JLinkException: on error.
"""
data = 0
res = self._dll.JLINK_STRACE_Control(enums.JLinkStraceCommand.TRACE_EVENT_CLR_ALL, data)
if res < 0:
raise errors.JLinkException('Failed to clear all STRACE events.')
@connection_required
def strace_set_buffer_size(self, size):
"""Sets the STRACE buffer size.
Args:
self (JLink): the ``JLink`` instance.
Returns:
``None``
Raises:
JLinkException: on error.
"""
size = ctypes.c_uint32(size)
res = self._dll.JLINK_STRACE_Control(enums.JLinkStraceCommand.SET_BUFFER_SIZE, size)
if res < 0:
raise errors.JLinkException('Failed to set the STRACE buffer size.')
@connection_required
def trace_start(self):
"""Starts collecting trace data.
Args:
self (JLink): the ``JLink`` instance.
Returns:
``None``
"""
cmd = enums.JLinkTraceCommand.START
res = self._dll.JLINKARM_TRACE_Control(cmd, 0)
if res == 1:
raise errors.JLinkException('Failed to start trace.')
@connection_required
def trace_stop(self):
"""Stops collecting trace data.
Args:
self (JLink): the ``JLink`` instance.
Returns:
``None``
"""
cmd = enums.JLinkTraceCommand.STOP
res = self._dll.JLINKARM_TRACE_Control(cmd, 0)
if res == 1:
raise errors.JLinkException('Failed to stop trace.')
@connection_required
def trace_flush(self):
"""Flushes the trace buffer.
After this method is called, the trace buffer is empty. This method is
best called when the device is reset.
Args:
self (JLink): the ``JLink`` instance.
Returns:
``None``
"""
cmd = enums.JLinkTraceCommand.FLUSH
res = self._dll.JLINKARM_TRACE_Control(cmd, 0)
if res == 1:
raise errors.JLinkException('Failed to flush the trace buffer.')
@connection_required
def trace_sample_count(self):
"""Retrieves the number of samples in the trace buffer.
Args:
self (JLink): the ``JLink`` instance.
Returns:
Number of samples in the trace buffer.
"""
cmd = enums.JLinkTraceCommand.GET_NUM_SAMPLES
data = ctypes.c_uint32(self.trace_max_buffer_capacity())
res = self._dll.JLINKARM_TRACE_Control(cmd, ctypes.byref(data))
if res == 1:
raise errors.JLinkException('Failed to get trace sample count.')
return data.value
@connection_required
def trace_buffer_capacity(self):
"""Retrieves the trace buffer's current capacity.
Args:
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.
"""
cmd = enums.JLinkTraceCommand.GET_CONF_CAPACITY
data = ctypes.c_uint32(0)
res = self._dll.JLINKARM_TRACE_Control(cmd, ctypes.byref(data))
if res == 1:
raise errors.JLinkException('Failed to get trace buffer size.')
return data.value
@connection_required
def trace_set_buffer_capacity(self, size):
"""Sets the capacity for the trace buffer.
Args:
self (JLink): the ``JLink`` instance.
size (int): the new capacity for the trace buffer.
Returns:
``None``
"""
cmd = enums.JLinkTraceCommand.SET_CAPACITY
data = ctypes.c_uint32(size)
res = self._dll.JLINKARM_TRACE_Control(cmd, ctypes.byref(data))
if res == 1:
raise errors.JLinkException('Failed to set trace buffer size.')
@connection_required
def trace_min_buffer_capacity(self):
"""Retrieves the minimum capacity the trace buffer can be configured with.
Args:
self (JLink): the ``JLink`` instance.
Returns:
The minimum configurable capacity for the trace buffer.
"""
cmd = enums.JLinkTraceCommand.GET_MIN_CAPACITY
data = ctypes.c_uint32(0)
res = self._dll.JLINKARM_TRACE_Control(cmd, ctypes.byref(data))
if res == 1:
raise errors.JLinkException('Failed to get min trace buffer size.')
return data.value
@connection_required
def trace_max_buffer_capacity(self):
"""Retrieves the maximum size the trace buffer can be configured with.
Args:
self (JLink): the ``JLink`` instance.
Returns:
The maximum configurable capacity for the trace buffer.
"""
cmd = enums.JLinkTraceCommand.GET_MAX_CAPACITY
data = ctypes.c_uint32(0)
res = self._dll.JLINKARM_TRACE_Control(cmd, ctypes.byref(data))
if res == 1:
raise errors.JLinkException('Failed to get max trace buffer size.')
return data.value
@connection_required
def trace_set_format(self, fmt):
"""Sets the format for the trace buffer to use.
Args:
self (JLink): the ``JLink`` instance.
fmt (int): format for the trace buffer; this is one of the attributes
of ``JLinkTraceFormat``.
Returns:
``None``
"""
cmd = enums.JLinkTraceCommand.SET_FORMAT
data = ctypes.c_uint32(fmt)
res = self._dll.JLINKARM_TRACE_Control(cmd, ctypes.byref(data))
if res == 1:
raise errors.JLinkException('Failed to set trace format.')
@connection_required
def trace_format(self):
"""Retrieves the current format the trace buffer is using.
Args:
self (JLink): the ``JLink`` instance.
Returns:
The current format the trace buffer is using. This is one of the
attributes of ``JLinkTraceFormat``.
"""
cmd = enums.JLinkTraceCommand.GET_FORMAT
data = ctypes.c_uint32(0)
res = self._dll.JLINKARM_TRACE_Control(cmd, ctypes.byref(data))
if res == 1:
raise errors.JLinkException('Failed to get trace format.')
return data.value
@connection_required
def trace_region_count(self):
"""Retrieves a count of the number of available trace regions.
Args:
self (JLink): the ``JLink`` instance.
Returns:
Count of the number of available trace regions.
"""
cmd = enums.JLinkTraceCommand.GET_NUM_REGIONS
data = ctypes.c_uint32(0)
res = self._dll.JLINKARM_TRACE_Control(cmd, ctypes.byref(data))
if res == 1:
raise errors.JLinkException('Failed to get trace region count.')
return data.value
@connection_required
def trace_region(self, region_index):
"""Retrieves the properties of a trace region.
Args:
self (JLink): the ``JLink`` instance.
region_index (int): the trace region index.
Returns:
An instance of ``JLinkTraceRegion`` describing the specified region.
"""
cmd = enums.JLinkTraceCommand.GET_REGION_PROPS_EX
region = structs.JLinkTraceRegion()
region.RegionIndex = int(region_index)
res = self._dll.JLINKARM_TRACE_Control(cmd, ctypes.byref(region))
if res == 1:
raise errors.JLinkException('Failed to get trace region.')
return region
@connection_required
def trace_read(self, offset, num_items):
"""Reads data from the trace buffer and returns it.
Args:
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.
"""
buf_size = ctypes.c_uint32(num_items)
buf = (structs.JLinkTraceData * num_items)()
res = self._dll.JLINKARM_TRACE_Read(buf, int(offset), ctypes.byref(buf_size))
if res == 1:
raise errors.JLinkException('Failed to read from trace buffer.')
return list(buf)[:int(buf_size.value)]
def swo_enabled(self):
"""Returns whether or not SWO is enabled.
Args:
self (JLink): the ``JLink`` instance
Returns:
``True`` if SWO is enabled, otherwise ``False``.
"""
return self._swo_enabled
@connection_required
def swo_start(self, swo_speed=9600):
"""Starts collecting SWO data.
Note:
If SWO is already enabled, it will first stop SWO before enabling it
again.
Args:
self (JLink): the ``JLink`` instance
swo_speed (int): the frequency in Hz used by the target to communicate
Returns:
``None``
Raises:
JLinkException: on error
"""
if self.swo_enabled():
self.swo_stop()
info = structs.JLinkSWOStartInfo()
info.Speed = swo_speed
res = self._dll.JLINKARM_SWO_Control(enums.JLinkSWOCommands.START, ctypes.byref(info))
if res < 0:
raise errors.JLinkException(res)
self._swo_enabled = True
@connection_required
def swo_stop(self):
"""Stops collecting SWO data.
Args:
self (JLink): the ``JLink`` instance
Returns:
``None``
Raises:
JLinkException: on error
"""
res = self._dll.JLINKARM_SWO_Control(enums.JLinkSWOCommands.STOP, 0)
if res < 0:
raise errors.JLinkException(res)
@connection_required
def swo_enable(self, cpu_speed, swo_speed=9600, port_mask=1):
"""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.
Args:
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
"""
if self.swo_enabled():
self.swo_stop()
res = self._dll.JLINKARM_SWO_EnableTarget(cpu_speed, swo_speed, enums.JLinkSWOInterfaces.UART, port_mask)
if res != 0:
raise errors.JLinkException(res)
self._swo_enabled = True
@connection_required
def swo_disable(self, port_mask):
"""Disables ITM & Stimulus ports.
Args:
self (JLink): the ``JLink`` instance
port_mask (int): mask specifying which ports to disable
Returns:
``None``
Raises:
JLinkException: on error
"""
res = self._dll.JLINKARM_SWO_DisableTarget(port_mask)
if res != 0:
raise errors.JLinkException(res)
@connection_required
def swo_flush(self, num_bytes=None):
"""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.
Args:
self (JLink): the ``JLink`` instance
num_bytes (int): the number of bytes to flush
Returns:
``None``
Raises:
JLinkException: on error
"""
if num_bytes is None:
num_bytes = self.swo_num_bytes()
buf = ctypes.c_uint32(num_bytes)
res = self._dll.JLINKARM_SWO_Control(enums.JLinkSWOCommands.FLUSH, ctypes.byref(buf))
if res < 0:
raise errors.JLinkException(res)
@connection_required
def swo_speed_info(self):
"""Retrieves information about the supported SWO speeds.
Args:
self (JLink): the ``JLink`` instance
Returns:
A ``JLinkSWOSpeedInfo`` instance describing the target's supported
SWO speeds.
Raises:
JLinkException: on error
"""
info = structs.JLinkSWOSpeedInfo()
res = self._dll.JLINKARM_SWO_Control(enums.JLinkSWOCommands.GET_SPEED_INFO, ctypes.byref(info))
if res < 0:
raise errors.JLinkException(res)
return info
@connection_required
def swo_num_bytes(self):
"""Retrives the number of bytes in the SWO buffer.
Args:
self (JLink): the ``JLink`` instance
Returns:
Number of bytes in the SWO buffer.
Raises:
JLinkException: on error
"""
res = self._dll.JLINKARM_SWO_Control(enums.JLinkSWOCommands.GET_NUM_BYTES, 0)
if res < 0:
raise errors.JLinkException(res)
return res
@connection_required
def swo_set_host_buffer_size(self, buf_size):
"""Sets the size of the buffer used by the host to collect SWO data.
Args:
self (JLink): the ``JLink`` instance
buf_size (int): the new size of the host buffer
Returns:
``None``
Raises:
JLinkException: on error
"""
buf = ctypes.c_uint32(buf_size)
res = self._dll.JLINKARM_SWO_Control(enums.JLinkSWOCommands.SET_BUFFERSIZE_HOST, ctypes.byref(buf))
if res < 0:
raise errors.JLinkException(res)
@connection_required
def swo_set_emu_buffer_size(self, buf_size):
"""Sets the size of the buffer used by the J-Link to collect SWO data.
Args:
self (JLink): the ``JLink`` instance
buf_size (int): the new size of the emulator buffer
Returns:
``None``
Raises:
JLinkException: on error
"""
buf = ctypes.c_uint32(buf_size)
res = self._dll.JLINKARM_SWO_Control(enums.JLinkSWOCommands.SET_BUFFERSIZE_EMU, ctypes.byref(buf))
if res < 0:
raise errors.JLinkException(res)
@connection_required
def swo_supported_speeds(self, cpu_speed, num_speeds=3):
"""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.
Args:
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.
"""
buf_size = num_speeds
buf = (ctypes.c_uint32 * buf_size)()
res = self._dll.JLINKARM_SWO_GetCompatibleSpeeds(cpu_speed, 0, buf, buf_size)
if res < 0:
raise errors.JLinkException(res)
return list(buf)[:res]
@connection_required
def swo_read(self, offset, num_bytes, remove=False):
"""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()``.
Args:
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.
"""
buf_size = ctypes.c_uint32(num_bytes)
buf = ctypes.c_uint8 * num_bytes(0)
self._dll.JLINKARM_SWO_Read(buf, offset, ctypes.byref(buf_size))
buf_size = buf_size.value
if remove:
self.swo_flush(buf_size)
return list(buf)[:buf_size]
@connection_required
def swo_read_stimulus(self, port, num_bytes):
"""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.
Args:
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``
"""
if port < 0 or port > 31:
raise ValueError('Invalid port number: %s' % port)
buf_size = num_bytes
buf = (ctypes.c_uint8 * buf_size)()
bytes_read = self._dll.JLINKARM_SWO_ReadStimulus(port, buf, buf_size)
return list(buf)[:bytes_read]
@open_required
def rtt_start(self):
"""Starts RTT processing, including background read of target data.
Args:
self (JLink): the ``JLink`` instance
Raises:
JLinkRTTException if the underlying JLINK_RTTERMINAL_Control call fails.
"""
self.rtt_control(enums.JLinkRTTCommand.START, None)
@open_required
def rtt_stop(self):
"""Stops RTT on the J-Link and host side.
Args:
self (JLink): the ``JLink`` instance
Raises:
JLinkRTTException if the underlying JLINK_RTTERMINAL_Control call fails.
"""
self.rtt_control(enums.JLinkRTTCommand.STOP, None)
@open_required
def rtt_get_num_up_buffers(self):
"""After starting RTT, get the current number of up buffers.
Args:
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.
"""
cmd = enums.JLinkRTTCommand.GETNUMBUF
dir = ctypes.c_int(enums.JLinkRTTDirection.UP)
return self.rtt_control(cmd, dir)
@open_required
def rtt_get_num_down_buffers(self):
"""After starting RTT, get the current number of down buffers.
Args:
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.
"""
cmd = enums.JLinkRTTCommand.GETNUMBUF
dir = ctypes.c_int(enums.JLinkRTTDirection.DOWN)
return self.rtt_control(cmd, dir)
@open_required
def rtt_read(self, buffer_index, num_bytes):
"""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.
Args:
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.
"""
buf = (ctypes.c_ubyte * num_bytes)()
bytes_read = self._dll.JLINK_RTTERMINAL_Read(buffer_index, buf, num_bytes)
if bytes_read < 0:
raise errors.JLinkRTTException(bytes_read)
return list(buf)[:bytes_read]
@open_required
def rtt_write(self, buffer_index, data):
"""Writes data to the RTT buffer.
This method will write at most len(data) bytes to the specified RTT
buffer.
Args:
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.
"""
buf_size = len(data)
buf = (ctypes.c_ubyte * buf_size)(*bytearray(data))
bytes_written = self._dll.JLINK_RTTERMINAL_Write(buffer_index, buf, buf_size)
if bytes_written < 0:
raise errors.JLinkRTTException(bytes_written)
return bytes_written
@open_required
def rtt_control(self, command, config):
"""Issues an RTT Control command.
All RTT control is done through a single API call which expects
specifically laid-out configuration structures.
Args:
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.
"""
config_byref = ctypes.byref(config) if config is not None else None
res = self._dll.JLINK_RTTERMINAL_Control(command, config_byref)
if res < 0:
raise errors.JLinkRTTException(res)
return res
@connection_required
def cp15_present(self):
"""Returns whether target has CP15 co-processor.
Returns:
``True`` if the target has CP15 co-processor, otherwise ``False``.
"""
result = False
if self._dll.JLINKARM_CP15_IsPresent() != 0:
result = True
return result
@open_required
def cp15_register_read(self, cr_n, op_1, cr_m, op_2):
"""Reads value from specified coprocessor register.
Args:
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
"""
value = ctypes.c_uint32(0)
p_value = ctypes.pointer(value)
res = self._dll.JLINKARM_CP15_ReadEx(cr_n, cr_m, op_1, op_2, p_value)
if res != 0:
raise errors.JLinkException(res)
else:
value = value.value
return value
@open_required
def cp15_register_write(self, cr_n, op_1, cr_m, op_2, value):
"""Writes value to specified coprocessor register.
Args:
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
"""
res = self._dll.JLINKARM_CP15_WriteEx(cr_n, cr_m, op_1, op_2, value)
if res != 0:
raise errors.JLinkException(res)
return res
# okay decompiling ./pylink/jlink.pyc
Reference in New Issue View Git Blame Copy Permalink