doc/west/flash-debug.rst - third_party/github/zephyrproject-rtos/zephyr - Git at Google

 .. _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
	.. _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