7a3462de7a
The various runners (flash/debug scripts) use environment variables to
take arguments. This is legacy behavior which is not desirable.
Use command line arguments instead.
Note: this leaves more general environment variables with publicly
documented behavior in place for now, for compatibility, e.g.:
ZEPHYR_FLASH_OVER_DFU, OPENSDA_FW, ESP_IDF_PATH, PYOCD_DAPARG
For example, when using dfu-util to flash arduino_101, instead of
setting DFUUTIL_PID, DFUUTIL_ALT, and DFUUTIL_IMG environment
variables, have the script invocation look like this:
python3 .../zephyr_flash_debug.py dfu-util flash \
[common arguments omitted] \
--pid=8087:0aba --alt=x86_app \
--img=.../build/zephyr/zephyr.bin
Make similar changes for other runners (openocd, etc.) and
targets (debug, debugserver).
To implement this in the scripts:
- have the individual scripts/support/runner/some-runner.py files
register their own command line arguments
- teach them to construct instances from arguments, not the
environment
- have zephyr_flash_debug.py request runners to register command
line argument parsers, and handle arguments
In the build system:
- add a new board_runner_args() extension function that board.cmake
files can use to add to the zephyr_flash_debug.py command line
- adjust cmake/flash/CMakeLists.txt to invoke with arguments
- add new helper include files for each runner (like
boards/common/dfu-util.board.cmake, etc.), which add default
options as needed and then add on overrides from
board_runner_args() calls
- update board.cmake files to use the new includes and extension
This implied some tweaking when using openocd to make the CMake string
escaping and unescaping work properly.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
81 lines
2.6 KiB
Python
Executable file
81 lines
2.6 KiB
Python
Executable file
#! /usr/bin/env python3
|
|
|
|
# Copyright (c) 2017 Linaro Limited.
|
|
# Copyright (c) 2017 Open Source Foundries Limited.
|
|
#
|
|
# SPDX-License-Identifier: Apache-2.0
|
|
|
|
"""Zephyr flash/debug script
|
|
|
|
This helper script is the build system's entry point to Zephyr's
|
|
"runner" Python package. This package provides ZephyrBinaryRunner,
|
|
which is a standard interface for flashing and debugging boards
|
|
supported by Zephyr, as well as backend-specific scripts for tools
|
|
such as OpenOCD, pyOCD, etc.
|
|
"""
|
|
|
|
import argparse
|
|
import functools
|
|
import sys
|
|
|
|
from runner.core import ZephyrBinaryRunner
|
|
|
|
|
|
def runner_handler(cls, args):
|
|
runner = cls.create_from_args(args)
|
|
# This relies on ZephyrBinaryRunner.add_parser() having command as
|
|
# its single positional argument; see its docstring for details.
|
|
runner.run(args.command)
|
|
|
|
|
|
def main():
|
|
# Argument handling is split into a two-level structure, with
|
|
# common options to the script first, then a sub-command (i.e. a
|
|
# runner name), then options and arguments for that sub-command
|
|
# (like 'flash --some-option=value').
|
|
#
|
|
# For top-level help (including a list of runners), run:
|
|
#
|
|
# $ZEPHYR_BASE/.../SCRIPT.py -h
|
|
#
|
|
# For help on a particular RUNNER (like 'pyocd'), run:
|
|
#
|
|
# $ZEPHYR_BASE/.../SCRIPT.py RUNNER -h
|
|
#
|
|
# For verbose output, use:
|
|
#
|
|
# $ZEPHYR_BASE/.../SCRIPT.py [-v|--verbose] RUNNER [--runner-options]
|
|
#
|
|
# Note that --verbose comes *before* RUNNER, not after!
|
|
top_parser = argparse.ArgumentParser()
|
|
top_parser.add_argument('-v', '--verbose',
|
|
default=False, action='store_true',
|
|
help='If set, enable verbose output.')
|
|
sub_parsers = top_parser.add_subparsers(dest='runner')
|
|
|
|
# Add a sub-command for each runner. (It's a bit hackish for runners
|
|
# to know about argparse, but it's good enough for now.)
|
|
handlers = {}
|
|
for cls in ZephyrBinaryRunner.get_runners():
|
|
if cls.name() in handlers:
|
|
print('Runner {} name is already a sub-command'.format(cls.name()),
|
|
file=sys.sterr)
|
|
sys.exit(1)
|
|
sub_parser = sub_parsers.add_parser(cls.name())
|
|
cls.add_parser(sub_parser)
|
|
handlers[cls.name()] = functools.partial(runner_handler, cls)
|
|
|
|
args = top_parser.parse_args()
|
|
if args.runner is None:
|
|
runners = ', '.join(handlers.keys())
|
|
print('Missing runner; choices: {}'.format(runners), file=sys.stderr)
|
|
sys.exit(1)
|
|
try:
|
|
handlers[args.runner](args)
|
|
except Exception as e:
|
|
print('Error: {}'.format(e), file=sys.stderr)
|
|
raise
|
|
|
|
|
|
if __name__ == '__main__':
|
|
main()
|