255 lines
8.4 KiB
ReStructuredText
255 lines
8.4 KiB
ReStructuredText
.. _west-flash-debug:
|
|
|
|
West: Flashing and Debugging
|
|
############################
|
|
|
|
West provides three commands for running and interacting with Zephyr
|
|
programs running on a board: ``flash``, ``debug``, and
|
|
``debugserver``.
|
|
|
|
These use information stored in the CMake cache [#cmakecache]_ to
|
|
flash or attach a debugger to a board supported by Zephyr. The CMake
|
|
build system commands with the same names directly delegate to West.
|
|
|
|
.. _west-flashing:
|
|
|
|
Flashing: ``west flash``
|
|
************************
|
|
|
|
.. tip:: Run ``west flash -h`` for additional help.
|
|
|
|
Basics
|
|
======
|
|
|
|
From a Zephyr build directory, re-build the binary and flash it to
|
|
your board::
|
|
|
|
west flash
|
|
|
|
Without options, the behavior is the same as ``ninja flash`` (or
|
|
``make flash``, etc.).
|
|
|
|
To specify the build directory, use ``--build-dir`` (or ``-d``)::
|
|
|
|
west flash --build-dir path/to/build/directory
|
|
|
|
Choosing a Runner
|
|
=================
|
|
|
|
If your board's Zephyr integration supports flashing with multiple
|
|
programs, you can specify which one to use using the ``--runner`` (or
|
|
``-r``) option. For example, if West flashes your board with
|
|
``nrfjprog`` by default, but it also supports JLink, you can override
|
|
the default with::
|
|
|
|
west flash --runner jlink
|
|
|
|
See :ref:`west-runner` below for more information on the ``runner``
|
|
library used by West. The list of runners which support flashing can
|
|
be obtained with ``west flash -H``; if run from a build directory or
|
|
with ``--build-dir``, this will print additional information on
|
|
available runners for your board.
|
|
|
|
Configuration Overrides
|
|
=======================
|
|
|
|
The CMake cache contains default values West uses while flashing, such
|
|
as where the board directory is on the file system, the path to the
|
|
kernel binaries to flash in several formats, and more. You can
|
|
override any of this configuration at runtime with additional options.
|
|
|
|
For example, to override the HEX file containing the Zephyr image to
|
|
flash (assuming your runner expects a HEX file), but keep other
|
|
flash configuration at default values::
|
|
|
|
west flash --kernel-hex path/to/some/other.hex
|
|
|
|
The ``west flash -h`` output includes a complete list of overrides
|
|
supported by all runners.
|
|
|
|
Runner-Specific Overrides
|
|
=========================
|
|
|
|
Each runner may support additional options related to flashing. For
|
|
example, some runners support an ``--erase`` flag, which mass-erases
|
|
the flash storage on your board before flashing the Zephyr image.
|
|
|
|
To view all of the available options for the runners your board
|
|
supports, as well as their usage information, use ``--context`` (or
|
|
``-H``)::
|
|
|
|
west flash --context
|
|
|
|
.. important::
|
|
|
|
Note the capital H in the short option name. This re-runs the build
|
|
in order to ensure the information displayed is up to date!
|
|
|
|
When running West outside of a build directory, ``west flash -H`` just
|
|
prints a list of runners. You can use ``west flash -H -r
|
|
<runner-name>`` to print usage information for options supported by
|
|
that runner.
|
|
|
|
For example, to print usage information about the ``jlink`` runner::
|
|
|
|
west flash -H -r jlink
|
|
|
|
.. _west-debugging:
|
|
|
|
Debugging: ``west debug``, ``west debugserver``
|
|
***********************************************
|
|
|
|
.. tip::
|
|
|
|
Run ``west debug -h`` or ``west debugserver -h`` for additional help.
|
|
|
|
Basics
|
|
======
|
|
|
|
From a Zephyr build directory, to attach a debugger to your board and
|
|
open up a debug console (e.g. a GDB session)::
|
|
|
|
west debug
|
|
|
|
To attach a debugger to your board and open up a local network port
|
|
you can connect a debugger to (e.g. an IDE debugger)::
|
|
|
|
west debugserver
|
|
|
|
Without options, the behavior is the same as ``ninja debug`` and
|
|
``ninja debugserver`` (or ``make debug``, etc.).
|
|
|
|
To specify the build directory, use ``--build-dir`` (or ``-d``)::
|
|
|
|
west debug --build-dir path/to/build/directory
|
|
west debugserver --build-dir path/to/build/directory
|
|
|
|
Choosing a Runner
|
|
=================
|
|
|
|
If your board's Zephyr integration supports debugging with multiple
|
|
programs, you can specify which one to use using the ``--runner`` (or
|
|
``-r``) option. For example, if West debugs your board with
|
|
``pyocd-gdbserver`` by default, but it also supports JLink, you can
|
|
override the default with::
|
|
|
|
west debug --runner jlink
|
|
west debugserver --runner jlink
|
|
|
|
See :ref:`west-runner` below for more information on the ``runner``
|
|
library used by West. The list of runners which support debugging can
|
|
be obtained with ``west debug -H``; if run from a build directory or
|
|
with ``--build-dir``, this will print additional information on
|
|
available runners for your board.
|
|
|
|
Configuration Overrides
|
|
=======================
|
|
|
|
The CMake cache contains default values West uses for debugging, such
|
|
as where the board directory is on the file system, the path to the
|
|
kernel binaries containing symbol tables, and more. You can override
|
|
any of this configuration at runtime with additional options.
|
|
|
|
For example, to override the ELF file containing the Zephyr binary and
|
|
symbol tables (assuming your runner expects an ELF file), but keep
|
|
other debug configuration at default values::
|
|
|
|
west debug --kernel-elf path/to/some/other.elf
|
|
west debugserver --kernel-elf path/to/some/other.elf
|
|
|
|
The ``west debug -h`` output includes a complete list of overrides
|
|
supported by all runners.
|
|
|
|
Runner-Specific Overrides
|
|
=========================
|
|
|
|
Each runner may support additional options related to debugging. For
|
|
example, some runners support flags which allow you to set the network
|
|
ports used by debug servers.
|
|
|
|
To view all of the available options for the runners your board
|
|
supports, as well as their usage information, use ``--context`` (or
|
|
``-H``)::
|
|
|
|
west debug --context
|
|
|
|
(The command ``west debugserver --context`` will print the same output.)
|
|
|
|
.. important::
|
|
|
|
Note the capital H in the short option name. This re-runs the build
|
|
in order to ensure the information displayed is up to date!
|
|
|
|
When running West outside of a build directory, ``west debug -H`` just
|
|
prints a list of runners. You can use ``west debug -H -r
|
|
<runner-name>`` to print usage information for options supported by
|
|
that runner.
|
|
|
|
For example, to print usage information about the ``jlink`` runner::
|
|
|
|
west debug -H -r jlink
|
|
|
|
.. _west-runner:
|
|
|
|
Library Backend: ``west.runner``
|
|
********************************
|
|
|
|
In keeping with West's :ref:`west-design-constraints`, the flash and
|
|
debug commands are wrappers around a separate library that is part of
|
|
West, and can be used by other code.
|
|
|
|
This library is the ``west.runner`` subpackage of West itself. The
|
|
central abstraction within this library is ``ZephyrBinaryRunner``, an
|
|
abstract class which represents *runner* objects, which can flash
|
|
and/or debug Zephyr programs. The set of available runners is
|
|
determined by the imported subclasses of ``ZephyrBinaryRunner``.
|
|
``ZephyrBinaryRunner`` is available in the ``west.runner.core``
|
|
module; individual runner implementations are in other submodules,
|
|
such as ``west.runner.nrfjprog``, ``west.runner.openocd``, etc.
|
|
|
|
Developers can add support for new ways to flash and debug Zephyr
|
|
programs by implementing additional runners. To get this support into
|
|
upstream Zephyr, the runner should be added into a new or existing
|
|
``west.runner`` module, and imported from
|
|
:file:`west/runner/__init__.py`.
|
|
|
|
.. important::
|
|
|
|
Submit any changes to West to its own separate Git repository
|
|
(https://github.com/zephyrproject-rtos/west), not to the copy of
|
|
West currently present in the Zephyr tree. This copy is a temporary
|
|
measure; when West learns how to manage multiple repositories, the
|
|
copy will be removed.
|
|
|
|
API documentation for the core module follows.
|
|
|
|
.. automodule:: west.runner.core
|
|
:members:
|
|
|
|
Doing it By Hand
|
|
****************
|
|
|
|
If you prefer not to use West to flash or debug your board, simply
|
|
inspect the build directory for the binaries output by the build
|
|
system. These will be named something like ``zephyr/zephyr.elf``,
|
|
``zephyr/zephyr.hex``, etc., depending on your board's build system
|
|
integration. These binaries may be flashed to a board using
|
|
alternative tools of your choice, or used for debugging as needed,
|
|
e.g. as a source of symbol tables.
|
|
|
|
By default, these West commands rebuild binaries before flashing and
|
|
debugging. This can of course also be accomplished using the usual
|
|
targets provided by Zephyr's build system (in fact, that's how West
|
|
does it).
|
|
|
|
.. rubric:: Footnotes
|
|
|
|
.. [#cmakecache]
|
|
|
|
The CMake cache is a file containing saved variables and values
|
|
which is created by CMake when it is first run to generate a build
|
|
system. See the `cmake(1)`_ manual for more details.
|
|
|
|
.. _cmake(1):
|
|
https://cmake.org/cmake/help/latest/manual/cmake.1.html
|