a2f203dd1a
This is a partial revert of commit
2cee5ff519
("scripts: west_commands: runners: remove deprecated options").
I remarked at the time that the removal of the older way of writing
things from the runners themselves seemed gratuitous since they are
easy to continue to support indefinitely and people may have been used
to the old way of doing things. It didn't seem worth the fight to push
for a revert at the time, though.
Since then I've run into real problems that their removal has caused
in the wild and I am convinced that this part of that patch was wrong.
Restore the original, undeprecated forms of these options, but make it
clear in the command line help that they're just obsolete alternative
spellings at this point.
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
372 lines
15 KiB
Python
372 lines
15 KiB
Python
# Copyright (c) 2017 Linaro Limited.
|
|
#
|
|
# SPDX-License-Identifier: Apache-2.0
|
|
|
|
'''Runner for debugging with J-Link.'''
|
|
|
|
import argparse
|
|
import logging
|
|
import os
|
|
from pathlib import Path
|
|
import shlex
|
|
import subprocess
|
|
import sys
|
|
import tempfile
|
|
|
|
from runners.core import ZephyrBinaryRunner, RunnerCaps, FileType
|
|
|
|
try:
|
|
import pylink
|
|
from pylink.library import Library
|
|
MISSING_REQUIREMENTS = False
|
|
except ImportError:
|
|
MISSING_REQUIREMENTS = True
|
|
|
|
DEFAULT_JLINK_EXE = 'JLink.exe' if sys.platform == 'win32' else 'JLinkExe'
|
|
DEFAULT_JLINK_GDB_PORT = 2331
|
|
|
|
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_after_load=False,
|
|
iface='swd', speed='auto',
|
|
loader=None,
|
|
gdbserver='JLinkGDBServer',
|
|
gdb_host='',
|
|
gdb_port=DEFAULT_JLINK_GDB_PORT,
|
|
tui=False, tool_opt=[]):
|
|
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.gdb_cmd = [cfg.gdb] if cfg.gdb else None
|
|
self.device = device
|
|
self.dev_id = dev_id
|
|
self.commander = commander
|
|
self.dt_flash = dt_flash
|
|
self.erase = erase
|
|
self.reset_after_load = reset_after_load
|
|
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.tool_opt = []
|
|
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'},
|
|
dev_id=True, flash_addr=True, erase=True,
|
|
tool_opt=True, file=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.'''
|
|
|
|
@classmethod
|
|
def tool_opt_help(cls) -> str:
|
|
return "Additional options for JLink Commander, e.g. '-autoconnect 1'"
|
|
|
|
@classmethod
|
|
def do_add_parser(cls, parser):
|
|
# 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('--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='pyocd gdb port, defaults to {}'.format(
|
|
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_after_load', nargs=0,
|
|
action=ToggleAction,
|
|
help='reset after loading? (default: no)')
|
|
|
|
parser.set_defaults(reset_after_load=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,
|
|
erase=args.erase,
|
|
reset_after_load=args.reset_after_load,
|
|
iface=args.iface, speed=args.speed,
|
|
gdbserver=args.gdbserver,
|
|
loader=args.loader,
|
|
gdb_host=args.gdb_host,
|
|
gdb_port=args.gdb_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}')
|
|
|
|
@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.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')
|
|
|
|
server_cmd = ([self.gdbserver] +
|
|
# only USB connections supported
|
|
['-select', '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',
|
|
'-singlerun'] +
|
|
(['-nogui'] if self.supports_nogui else []) +
|
|
(['-rtos', plugin_dir] if rtos else []) +
|
|
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)
|
|
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', 'target remote {}:{}'.format(self.gdb_host, self.gdb_port)])
|
|
if command == 'debug':
|
|
client_cmd += ['-ex', 'monitor halt',
|
|
'-ex', 'monitor reset',
|
|
'-ex', 'load']
|
|
if self.reset_after_load:
|
|
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 flash(self, **kwargs):
|
|
|
|
loader_details = ""
|
|
lines = [
|
|
'ExitOnError 1', # Treat any command-error as fatal
|
|
'r', # Reset and halt the target
|
|
]
|
|
|
|
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:
|
|
if 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 or bin file provided by the buildsystem, preferring .hex over .bin
|
|
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}"'
|
|
elif self.bin_name is not None and os.path.isfile(self.bin_name):
|
|
if 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}'
|
|
else:
|
|
err = 'Cannot flash; no hex ({}) or bin ({}) files found.'
|
|
raise ValueError(err.format(self.hex_name, self.bin_name))
|
|
|
|
# Flash the selected build artifact
|
|
lines.append(flash_cmd)
|
|
|
|
if self.reset_after_load:
|
|
lines.append('r') # Reset and halt the target
|
|
|
|
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))
|
|
|
|
# Don't use NamedTemporaryFile: the resulting file can't be
|
|
# opened again on Windows.
|
|
with tempfile.TemporaryDirectory(suffix='jlink') as d:
|
|
fname = os.path.join(d, 'runner.jlink')
|
|
with open(fname, 'wb') as f:
|
|
f.writelines(bytes(line + '\n', 'utf-8') for line in lines)
|
|
if self.supports_loader and self.loader:
|
|
loader_details = "?" + self.loader
|
|
|
|
cmd = ([self.commander] +
|
|
# only USB connections supported
|
|
(['-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)
|
|
|
|
self.logger.info('Flashing file: {}'.format(flash_file))
|
|
kwargs = {}
|
|
if not self.logger.isEnabledFor(logging.DEBUG):
|
|
kwargs['stdout'] = subprocess.DEVNULL
|
|
self.check_call(cmd, **kwargs)
|