Add new parameter "--flash-sram" for J-Link runner to flash the image to SRAM and modify the PC register to start of SRAM. Signed-off-by: Jiafei Pan <Jiafei.Pan@nxp.com>
503 lines
20 KiB
Python
503 lines
20 KiB
Python
# Copyright (c) 2017 Linaro Limited.
|
|
#
|
|
# SPDX-License-Identifier: Apache-2.0
|
|
|
|
'''Runner for debugging with J-Link.'''
|
|
|
|
import argparse
|
|
import ipaddress
|
|
import logging
|
|
import os
|
|
import shlex
|
|
import socket
|
|
import subprocess
|
|
import sys
|
|
import tempfile
|
|
import time
|
|
from pathlib import Path
|
|
|
|
from runners.core import FileType, RunnerCaps, ZephyrBinaryRunner
|
|
|
|
try:
|
|
import pylink
|
|
from pylink.library import Library
|
|
MISSING_REQUIREMENTS = False
|
|
except ImportError:
|
|
MISSING_REQUIREMENTS = True
|
|
|
|
# Populated in do_add_parser()
|
|
DEFAULT_JLINK_EXE = None
|
|
DEFAULT_JLINK_GDB_PORT = 2331
|
|
DEFAULT_JLINK_RTT_PORT = 19021
|
|
|
|
def is_ip(ip):
|
|
if not ip:
|
|
return False
|
|
try:
|
|
ipaddress.ip_address(ip.split(':')[0])
|
|
except ValueError:
|
|
return False
|
|
return True
|
|
|
|
def is_tunnel(tunnel):
|
|
return tunnel.startswith("tunnel:") if tunnel else False
|
|
|
|
class ToggleAction(argparse.Action):
|
|
|
|
def __call__(self, parser, args, ignored, option):
|
|
setattr(args, self.dest, not option.startswith('--no-'))
|
|
|
|
class JLinkBinaryRunner(ZephyrBinaryRunner):
|
|
'''Runner front-end for the J-Link GDB server.'''
|
|
|
|
def __init__(self, cfg, device, dev_id=None,
|
|
commander=DEFAULT_JLINK_EXE,
|
|
dt_flash=True, erase=True, reset=False,
|
|
iface='swd', speed='auto', flash_script = None,
|
|
loader=None, flash_sram=False,
|
|
gdbserver='JLinkGDBServer',
|
|
gdb_host='',
|
|
gdb_port=DEFAULT_JLINK_GDB_PORT,
|
|
rtt_port=DEFAULT_JLINK_RTT_PORT,
|
|
tui=False, tool_opt=None):
|
|
super().__init__(cfg)
|
|
self.file = cfg.file
|
|
self.file_type = cfg.file_type
|
|
self.hex_name = cfg.hex_file
|
|
self.bin_name = cfg.bin_file
|
|
self.elf_name = cfg.elf_file
|
|
self.mot_name = cfg.mot_file
|
|
self.gdb_cmd = [cfg.gdb] if cfg.gdb else None
|
|
self.device = device
|
|
self.dev_id = dev_id
|
|
self.commander = commander
|
|
self.flash_script = flash_script
|
|
self.dt_flash = dt_flash
|
|
self.flash_sram = flash_sram
|
|
self.erase = erase
|
|
self.reset = reset
|
|
self.gdbserver = gdbserver
|
|
self.iface = iface
|
|
self.speed = speed
|
|
self.gdb_host = gdb_host
|
|
self.gdb_port = gdb_port
|
|
self.tui_arg = ['-tui'] if tui else []
|
|
self.loader = loader
|
|
self.rtt_port = rtt_port
|
|
|
|
self.tool_opt = []
|
|
if tool_opt is not None:
|
|
for opts in [shlex.split(opt) for opt in tool_opt]:
|
|
self.tool_opt += opts
|
|
|
|
@classmethod
|
|
def name(cls):
|
|
return 'jlink'
|
|
|
|
@classmethod
|
|
def capabilities(cls):
|
|
return RunnerCaps(commands={'flash', 'debug', 'debugserver', 'attach', 'rtt'},
|
|
dev_id=True, flash_addr=True, erase=True, reset=True,
|
|
tool_opt=True, file=True, rtt=True)
|
|
|
|
@classmethod
|
|
def dev_id_help(cls) -> str:
|
|
return '''Device identifier. Use it to select the J-Link Serial Number
|
|
of the device connected over USB. If the J-Link is connected over ip,
|
|
the Device identifier is the ip.'''
|
|
|
|
@classmethod
|
|
def tool_opt_help(cls) -> str:
|
|
return "Additional options for JLink Commander, e.g. '-autoconnect 1'"
|
|
|
|
@staticmethod
|
|
def default_jlink():
|
|
global DEFAULT_JLINK_EXE
|
|
|
|
if sys.platform == 'win32':
|
|
# JLink.exe can collide with the JDK executable of the same name
|
|
# Locate the executable using the registry
|
|
try:
|
|
import winreg
|
|
|
|
# Note that when multiple JLink versions are installed on the
|
|
# machine this points to the one that was installed
|
|
# last, and not to the latest version.
|
|
key = winreg.OpenKeyEx(
|
|
winreg.HKEY_CURRENT_USER, r"Software\SEGGER\J-Link")
|
|
DEFAULT_JLINK_EXE = (
|
|
Path(winreg.QueryValueEx(key, "InstallPath")[0])
|
|
/ "JLink.exe")
|
|
except Exception:
|
|
# Not found via the registry, hope that $PATH is correct
|
|
DEFAULT_JLINK_EXE = "JLink.exe"
|
|
else:
|
|
DEFAULT_JLINK_EXE = "JLinkExe"
|
|
|
|
@classmethod
|
|
def do_add_parser(cls, parser):
|
|
|
|
# Find the default JLink executable
|
|
cls.default_jlink()
|
|
|
|
# Required:
|
|
parser.add_argument('--device', required=True, help='device name')
|
|
|
|
# Optional:
|
|
parser.add_argument('--loader', required=False, dest='loader',
|
|
help='specifies a loader type')
|
|
parser.add_argument('--id', required=False, dest='dev_id',
|
|
help='obsolete synonym for -i/--dev-id')
|
|
parser.add_argument('--iface', default='swd',
|
|
help='interface to use, default is swd')
|
|
parser.add_argument('--speed', default='auto',
|
|
help='interface speed, default is autodetect')
|
|
parser.add_argument('--flash-script', default=None,
|
|
help='Custom flashing script, default is None')
|
|
parser.add_argument('--tui', default=False, action='store_true',
|
|
help='if given, GDB uses -tui')
|
|
parser.add_argument('--gdbserver', default='JLinkGDBServer',
|
|
help='GDB server, default is JLinkGDBServer')
|
|
parser.add_argument('--gdb-host', default='',
|
|
help='custom gdb host, defaults to the empty string '
|
|
'and runs a gdb server')
|
|
parser.add_argument('--gdb-port', default=DEFAULT_JLINK_GDB_PORT,
|
|
help=f'pyocd gdb port, defaults to {DEFAULT_JLINK_GDB_PORT}')
|
|
parser.add_argument('--commander', default=DEFAULT_JLINK_EXE,
|
|
help=f'''J-Link Commander, default is
|
|
{DEFAULT_JLINK_EXE}''')
|
|
parser.add_argument('--reset-after-load', '--no-reset-after-load',
|
|
dest='reset', nargs=0,
|
|
action=ToggleAction,
|
|
help='obsolete synonym for --reset/--no-reset')
|
|
parser.add_argument('--rtt-client', default='JLinkRTTClient',
|
|
help='RTT client, default is JLinkRTTClient')
|
|
parser.add_argument('--rtt-port', default=DEFAULT_JLINK_RTT_PORT,
|
|
help=f'jlink rtt port, defaults to {DEFAULT_JLINK_RTT_PORT}')
|
|
parser.add_argument('--flash-sram', default=False, action='store_true',
|
|
help='if given, flashing the image to SRAM and '
|
|
'modify PC register to be SRAM base address')
|
|
|
|
parser.set_defaults(reset=False)
|
|
|
|
@classmethod
|
|
def do_create(cls, cfg, args):
|
|
return JLinkBinaryRunner(cfg, args.device,
|
|
dev_id=args.dev_id,
|
|
commander=args.commander,
|
|
dt_flash=args.dt_flash,
|
|
flash_sram=args.flash_sram,
|
|
erase=args.erase,
|
|
reset=args.reset,
|
|
iface=args.iface, speed=args.speed,
|
|
flash_script=args.flash_script,
|
|
gdbserver=args.gdbserver,
|
|
loader=args.loader,
|
|
gdb_host=args.gdb_host,
|
|
gdb_port=args.gdb_port,
|
|
rtt_port=args.rtt_port,
|
|
tui=args.tui, tool_opt=args.tool_opt)
|
|
|
|
def print_gdbserver_message(self):
|
|
if not self.thread_info_enabled:
|
|
thread_msg = '; no thread info available'
|
|
elif self.supports_thread_info:
|
|
thread_msg = '; thread info enabled'
|
|
else:
|
|
thread_msg = '; update J-Link software for thread info'
|
|
self.logger.info('J-Link GDB server running on port '
|
|
f'{self.gdb_port}{thread_msg}')
|
|
|
|
def print_rttserver_message(self):
|
|
self.logger.info(f'J-Link RTT server running on port {self.rtt_port}')
|
|
|
|
@property
|
|
def jlink_version(self):
|
|
# Get the J-Link version as a (major, minor, rev) tuple of integers.
|
|
#
|
|
# J-Link's command line tools provide neither a standalone
|
|
# "--version" nor help output that contains the version. Hack
|
|
# around this deficiency by using the third-party pylink library
|
|
# to load the shared library distributed with the tools, which
|
|
# provides an API call for getting the version.
|
|
if not hasattr(self, '_jlink_version'):
|
|
# pylink 0.14.0/0.14.1 exposes JLink SDK DLL (libjlinkarm) in
|
|
# JLINK_SDK_STARTS_WITH, while other versions use JLINK_SDK_NAME
|
|
if pylink.__version__ in ('0.14.0', '0.14.1'):
|
|
sdk = Library.JLINK_SDK_STARTS_WITH
|
|
else:
|
|
sdk = Library.JLINK_SDK_NAME
|
|
|
|
plat = sys.platform
|
|
if plat.startswith('win32'):
|
|
libname = Library.get_appropriate_windows_sdk_name() + '.dll'
|
|
elif plat.startswith('linux'):
|
|
libname = sdk + '.so'
|
|
elif plat.startswith('darwin'):
|
|
libname = sdk + '.dylib'
|
|
else:
|
|
self.logger.warning(f'unknown platform {plat}; assuming UNIX')
|
|
libname = sdk + '.so'
|
|
|
|
lib = Library(dllpath=os.fspath(Path(self.commander).parent /
|
|
libname))
|
|
version = int(lib.dll().JLINKARM_GetDLLVersion())
|
|
self.logger.debug('JLINKARM_GetDLLVersion()=%s', version)
|
|
# The return value is an int with 2 decimal digits per
|
|
# version subfield.
|
|
self._jlink_version = (version // 10000,
|
|
(version // 100) % 100,
|
|
version % 100)
|
|
|
|
return self._jlink_version
|
|
|
|
@property
|
|
def jlink_version_str(self):
|
|
# Converts the numeric revision tuple to something human-readable.
|
|
if not hasattr(self, '_jlink_version_str'):
|
|
major, minor, rev = self.jlink_version
|
|
rev_str = chr(ord('a') + rev - 1) if rev else ''
|
|
self._jlink_version_str = f'{major}.{minor:02}{rev_str}'
|
|
return self._jlink_version_str
|
|
|
|
@property
|
|
def supports_nogui(self):
|
|
# -nogui was introduced in J-Link Commander v6.80
|
|
return self.jlink_version >= (6, 80, 0)
|
|
|
|
@property
|
|
def supports_thread_info(self):
|
|
# RTOSPlugin_Zephyr was introduced in 7.11b
|
|
return self.jlink_version >= (7, 11, 2)
|
|
|
|
@property
|
|
def supports_loader(self):
|
|
return self.jlink_version >= (7, 70, 4)
|
|
|
|
def do_run(self, command, **kwargs):
|
|
|
|
if MISSING_REQUIREMENTS:
|
|
raise RuntimeError('one or more Python dependencies were missing; '
|
|
"see the getting started guide for details on "
|
|
"how to fix")
|
|
# Convert commander to a real absolute path. We need this to
|
|
# be able to find the shared library that tells us what
|
|
# version of the tools we're using.
|
|
self.commander = os.fspath(
|
|
Path(self.require(self.commander)).resolve())
|
|
self.logger.debug(f'JLink executable: {self.commander}')
|
|
self.logger.info(f'JLink version: {self.jlink_version_str}')
|
|
|
|
rtos = self.thread_info_enabled and self.supports_thread_info
|
|
plugin_dir = os.fspath(Path(self.commander).parent / 'GDBServer' /
|
|
'RTOSPlugin_Zephyr')
|
|
big_endian = self.build_conf.getboolean('CONFIG_BIG_ENDIAN')
|
|
|
|
server_cmd = (
|
|
[self.gdbserver]
|
|
+ [
|
|
'-select',
|
|
('ip' if (is_ip(self.dev_id) or is_tunnel(self.dev_id)) else 'usb')
|
|
+ (f'={self.dev_id}' if self.dev_id else ''),
|
|
]
|
|
+ ['-port', str(self.gdb_port)]
|
|
+ ['-if', self.iface]
|
|
+ ['-speed', self.speed]
|
|
+ ['-device', self.device]
|
|
+ ['-silent']
|
|
+ ['-endian', 'big' if big_endian else 'little']
|
|
+ ['-singlerun']
|
|
+ (['-nogui'] if self.supports_nogui else [])
|
|
+ (['-rtos', plugin_dir] if rtos else [])
|
|
+ ['-rtttelnetport', str(self.rtt_port)]
|
|
+ self.tool_opt
|
|
)
|
|
|
|
if command == 'flash':
|
|
self.flash(**kwargs)
|
|
elif command == 'debugserver':
|
|
if self.gdb_host:
|
|
raise ValueError('Cannot run debugserver with --gdb-host')
|
|
self.require(self.gdbserver)
|
|
self.print_gdbserver_message()
|
|
self.check_call(server_cmd)
|
|
elif command == 'rtt':
|
|
self.print_gdbserver_message()
|
|
self.print_rttserver_message()
|
|
server_cmd += ['-nohalt']
|
|
server_proc = self.popen_ignore_int(server_cmd)
|
|
try:
|
|
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
|
|
# wait for the port to be open
|
|
while server_proc.poll() is None:
|
|
try:
|
|
sock.connect(('localhost', self.rtt_port))
|
|
break
|
|
except ConnectionRefusedError:
|
|
time.sleep(0.1)
|
|
self.run_telnet_client('localhost', self.rtt_port, sock)
|
|
except Exception as e:
|
|
self.logger.error(e)
|
|
finally:
|
|
server_proc.terminate()
|
|
server_proc.wait()
|
|
else:
|
|
if self.gdb_cmd is None:
|
|
raise ValueError('Cannot debug; gdb is missing')
|
|
if self.file is not None:
|
|
if self.file_type != FileType.ELF:
|
|
raise ValueError('Cannot debug; elf file required')
|
|
elf_name = self.file
|
|
elif self.elf_name is None:
|
|
raise ValueError('Cannot debug; elf is missing')
|
|
else:
|
|
elf_name = self.elf_name
|
|
client_cmd = (self.gdb_cmd +
|
|
self.tui_arg +
|
|
[elf_name] +
|
|
['-ex', f'target remote {self.gdb_host}:{self.gdb_port}'])
|
|
if command == 'debug':
|
|
client_cmd += ['-ex', 'monitor halt',
|
|
'-ex', 'monitor reset',
|
|
'-ex', 'load']
|
|
if self.reset:
|
|
client_cmd += ['-ex', 'monitor reset']
|
|
if not self.gdb_host:
|
|
self.require(self.gdbserver)
|
|
self.print_gdbserver_message()
|
|
self.run_server_and_client(server_cmd, client_cmd)
|
|
else:
|
|
self.run_client(client_cmd)
|
|
|
|
def get_default_flash_commands(self):
|
|
lines = [
|
|
'ExitOnError 1', # Treat any command-error as fatal
|
|
'r', # Reset and halt the target
|
|
'BE' if self.build_conf.getboolean('CONFIG_BIG_ENDIAN') else 'LE'
|
|
]
|
|
|
|
if self.erase:
|
|
lines.append('erase') # Erase all flash sectors
|
|
|
|
# Get the build artifact to flash
|
|
if self.file is not None:
|
|
# use file provided by the user
|
|
if not os.path.isfile(self.file):
|
|
err = 'Cannot flash; file ({}) not found'
|
|
raise ValueError(err.format(self.file))
|
|
|
|
flash_file = self.file
|
|
|
|
if self.file_type == FileType.HEX:
|
|
flash_cmd = f'loadfile "{self.file}"'
|
|
elif self.file_type == (FileType.BIN or FileType.MOT):
|
|
if self.flash_sram:
|
|
flash_addr = self.sram_address_from_build_conf(self.build_conf)
|
|
elif self.dt_flash:
|
|
flash_addr = self.flash_address_from_build_conf(self.build_conf)
|
|
else:
|
|
flash_addr = 0
|
|
flash_cmd = f'loadfile "{self.file}" 0x{flash_addr:x}'
|
|
else:
|
|
err = 'Cannot flash; jlink runner only supports hex and bin files'
|
|
raise ValueError(err)
|
|
|
|
else:
|
|
# Use hex, bin or elf file provided by the buildsystem.
|
|
# Preferring .hex over .mot, .bin and .elf
|
|
if self.hex_name is not None and os.path.isfile(self.hex_name):
|
|
flash_file = self.hex_name
|
|
flash_cmd = f'loadfile "{self.hex_name}"'
|
|
# Preferring .mot over .bin and .elf
|
|
elif self.mot_name is not None and os.path.isfile(self.mot_name):
|
|
flash_file = self.mot_name
|
|
flash_cmd = f'loadfile {self.mot_name}'
|
|
# Preferring .bin over .elf
|
|
elif self.bin_name is not None and os.path.isfile(self.bin_name):
|
|
if self.flash_sram:
|
|
flash_addr = self.sram_address_from_build_conf(self.build_conf)
|
|
elif self.dt_flash:
|
|
flash_addr = self.flash_address_from_build_conf(self.build_conf)
|
|
else:
|
|
flash_addr = 0
|
|
flash_file = self.bin_name
|
|
flash_cmd = f'loadfile "{self.bin_name}" 0x{flash_addr:x}'
|
|
elif self.elf_name is not None and os.path.isfile(self.elf_name):
|
|
flash_file = self.elf_name
|
|
flash_cmd = f'loadfile "{self.elf_name}"'
|
|
elif self.mot_name is not None and os.path.isfile(self.mot_name):
|
|
flash_file = self.mot_name
|
|
flash_cmd = f'loadfile {self.mot_name}'
|
|
else:
|
|
err = 'Cannot flash; no hex ({}), bin ({}) or mot ({}) files found.'
|
|
raise ValueError(err.format(self.hex_name, self.bin_name))
|
|
|
|
# Flash the selected build artifact
|
|
lines.append(flash_cmd)
|
|
|
|
if self.reset:
|
|
lines.append('r') # Reset and halt the target
|
|
|
|
if self.flash_sram:
|
|
sram_addr = self.sram_address_from_build_conf(self.build_conf)
|
|
lines.append(f'WReg PC 0x{sram_addr:x}') # Change PC to start of SRAM
|
|
|
|
lines.append('g') # Start the CPU
|
|
|
|
# Reset the Debug Port CTRL/STAT register
|
|
# Under normal operation this is done automatically, but if other
|
|
# JLink tools are running, it is not performed.
|
|
# The J-Link scripting layer chains commands, meaning that writes are
|
|
# not actually performed until after the next operation. After writing
|
|
# the register, read it back to perform this flushing.
|
|
lines.append('writeDP 1 0')
|
|
lines.append('readDP 1')
|
|
|
|
lines.append('q') # Close the connection and quit
|
|
|
|
self.logger.debug('JLink commander script:\n' +
|
|
'\n'.join(lines))
|
|
return flash_file, lines
|
|
|
|
def run_flash_cmd(self, fname, flash_file, **kwargs):
|
|
loader_details = ""
|
|
if self.supports_loader and self.loader:
|
|
loader_details = "?" + self.loader
|
|
|
|
cmd = (
|
|
[self.commander]
|
|
+ (
|
|
['-IP', f'{self.dev_id}']
|
|
if (is_ip(self.dev_id) or is_tunnel(self.dev_id))
|
|
else (['-USB', f'{self.dev_id}'] if self.dev_id else [])
|
|
)
|
|
+ (['-nogui', '1'] if self.supports_nogui else [])
|
|
+ ['-if', self.iface]
|
|
+ ['-speed', self.speed]
|
|
+ ['-device', self.device + loader_details]
|
|
+ ['-CommanderScript', fname]
|
|
+ (['-nogui', '1'] if self.supports_nogui else [])
|
|
+ self.tool_opt
|
|
)
|
|
|
|
if flash_file:
|
|
self.logger.info(f'Flashing file: {flash_file}')
|
|
kwargs = {}
|
|
if not self.logger.isEnabledFor(logging.DEBUG):
|
|
kwargs['stdout'] = subprocess.DEVNULL
|
|
self.check_call(cmd, **kwargs)
|
|
|
|
def flash(self, **kwargs):
|
|
fname = self.flash_script
|
|
if fname is None:
|
|
# Don't use NamedTemporaryFile: the resulting file can't be
|
|
# opened again on Windows.
|
|
with tempfile.TemporaryDirectory(suffix='jlink') as d:
|
|
flash_file, lines = self.get_default_flash_commands()
|
|
fname = os.path.join(d, 'runner.jlink')
|
|
with open(fname, 'wb') as f:
|
|
f.writelines(bytes(line + '\n', 'utf-8') for line in lines)
|
|
|
|
self.run_flash_cmd(fname, flash_file, **kwargs)
|
|
else:
|
|
self.run_flash_cmd(fname, None, **kwargs)
|