OrgZephyr/zephyr
OrgZephyr
/
zephyr
mirror of https://github.com/zephyrproject-rtos/zephyr.git
1
0
Fork 0
Code Issues Releases Wiki Activity
zephyr/doc/develop/flash_debug/host-tools.rst

275 lines
8.9 KiB
ReStructuredText
Raw Blame History

.. _flash-debug-host-tools:
Flash & Debug Host Tools
########################
This guide describes the software tools you can run on your host workstation to
flash and debug Zephyr applications.
Zephyr's west tool has built-in support for all of these in its ``flash``,
``debug``, ``debugserver``, and ``attach`` commands, provided your board
hardware supports them and your Zephyr board directory's :file:`board.cmake`
file declares that support properly. See :ref:`west-build-flash-debug` for
more information on these commands.
.. _atmel_sam_ba_bootloader:
SAM Boot Assistant (SAM-BA)
***************************
Atmel SAM Boot Assistant (Atmel SAM-BA) allows In-System Programming (ISP)
from USB or UART host without any external programming interface. Zephyr
allows users to develop and program boards with SAM-BA support using
:ref:`west <west-flashing>`. Zephyr supports devices with/without ROM
bootloader and both extensions from Arduino and Adafruit. Full support was
introduced in Zephyr SDK 0.12.0.
The typical command to flash the board is:
.. code-block:: console
west flash [ -r bossac ] [ -p /dev/ttyX ]
Flash configuration for devices:
.. tabs::
.. tab:: With ROM bootloader
These devices don't need any special configuration. After building your
application, just run ``west flash`` to flash the board.
.. tab:: Without ROM bootloader
For these devices, the user should:
1. Define flash partitions required to accommodate the bootloader and
application image; see :ref:`flash_map_api` for details.
2. Have board :file:`.defconfig` file with the
:kconfig:option:`CONFIG_USE_DT_CODE_PARTITION` Kconfig option set to ``y`` to
instruct the build system to use these partitions for code relocation.
This option can also be set in ``prj.conf`` or any other Kconfig fragment.
3. Build and flash the SAM-BA bootloader on the device.
.. tab:: With compatible SAM-BA bootloader
For these devices, the user should:
1. Define flash partitions required to accommodate the bootloader and
application image; see :ref:`flash_map_api` for details.
2. Have board :file:`.defconfig` file with the
:kconfig:option:`CONFIG_BOOTLOADER_BOSSA` Kconfig option set to ``y``. This will
automatically select the :kconfig:option:`CONFIG_USE_DT_CODE_PARTITION` Kconfig
option which instruct the build system to use these partitions for code
relocation. The board :file:`.defconfig` file should have
:kconfig:option:`CONFIG_BOOTLOADER_BOSSA_ARDUINO` ,
:kconfig:option:`CONFIG_BOOTLOADER_BOSSA_ADAFRUIT_UF2` or the
:kconfig:option:`CONFIG_BOOTLOADER_BOSSA_LEGACY` Kconfig option set to ``y``
to select the right compatible SAM-BA bootloader mode.
These options can also be set in ``prj.conf`` or any other Kconfig fragment.
3. Build and flash the SAM-BA bootloader on the device.
.. note::
The :kconfig:option:`CONFIG_BOOTLOADER_BOSSA_LEGACY` Kconfig option should be used
as last resource. Try configure first with Devices without ROM bootloader.
Typical flash layout and configuration
--------------------------------------
For bootloaders that reside on flash, the devicetree partition layout is
mandatory. For devices that have a ROM bootloader, they are mandatory when
the application uses a storage or other non-application partition. In this
special case, the boot partition should be omitted and code_partition should
start from offset 0. It is necessary to define the partitions with sizes that
avoid overlaps, always.
A typical flash layout for devices without a ROM bootloader is:
.. code-block:: devicetree
/ {
chosen {
zephyr,code-partition = &code_partition;
};
};
&flash0 {
partitions {
compatible = "fixed-partitions";
#address-cells = <1>;
#size-cells = <1>;
boot_partition: partition@0 {
label = "sam-ba";
reg = <0x00000000 0x2000>;
read-only;
};
code_partition: partition@2000 {
label = "code";
reg = <0x2000 0x3a000>;
read-only;
};
/*
* The final 16 KiB is reserved for the application.
* Storage partition will be used by FCB/LittleFS/NVS
* if enabled.
*/
storage_partition: partition@3c000 {
label = "storage";
reg = <0x0003c000 0x00004000>;
};
};
};
A typical flash layout for devices with a ROM bootloader and storage
partition is:
.. code-block:: devicetree
/ {
chosen {
zephyr,code-partition = &code_partition;
};
};
&flash0 {
partitions {
compatible = "fixed-partitions";
#address-cells = <1>;
#size-cells = <1>;
code_partition: partition@0 {
label = "code";
reg = <0x0 0xF0000>;
read-only;
};
/*
* The final 64 KiB is reserved for the application.
* Storage partition will be used by FCB/LittleFS/NVS
* if enabled.
*/
storage_partition: partition@F0000 {
label = "storage";
reg = <0x000F0000 0x00100000>;
};
};
};
Enabling SAM-BA runner
----------------------
In order to instruct Zephyr west tool to use the SAM-BA bootloader the
:file:`board.cmake` file must have
``include(${ZEPHYR_BASE}/boards/common/bossac.board.cmake)`` entry. Note that
Zephyr tool accept more entries to define multiple runners. By default, the
first one will be selected when using ``west flash`` command. The remaining
options are available passing the runner option, for instance
``west flash -r bossac``.
More implementation details can be found in the :ref:`boards` documentation.
As a quick reference, see these three board documentation pages:
- :ref:`sam4e_xpro` (ROM bootloader)
- :ref:`adafruit_feather_m0_basic_proto` (Adafruit UF2 bootloader)
- :ref:`arduino_nano_33_iot` (Arduino bootloader)
- :ref:`arduino_nano_33_ble` (Arduino legacy bootloader)
.. _jlink-debug-host-tools:
J-Link Debug Host Tools
***********************
Segger provides a suite of debug host tools for Linux, macOS, and Windows
operating systems:
- J-Link GDB Server: GDB remote debugging
- J-Link Commander: Command-line control and flash programming
- RTT Viewer: RTT terminal input and output
- SystemView: Real-time event visualization and recording
These debug host tools are compatible with the following debug probes:
- :ref:`lpclink2-jlink-onboard-debug-probe`
- :ref:`opensda-jlink-onboard-debug-probe`
- :ref:`jlink-external-debug-probe`
- :ref:`stlink-v21-onboard-debug-probe`
Check if your SoC is listed in `J-Link Supported Devices`_.
Download and install the `J-Link Software and Documentation Pack`_ to get the
J-Link GDB Server and Commander, and to install the associated USB device
drivers. RTT Viewer and SystemView can be downloaded separately, but are not
required.
Note that the J-Link GDB server does not yet support Zephyr RTOS-awareness.
.. _openocd-debug-host-tools:
OpenOCD Debug Host Tools
************************
OpenOCD is a community open source project that provides GDB remote debugging
and flash programming support for a wide range of SoCs. A fork that adds Zephyr
RTOS-awareness is included in the Zephyr SDK; otherwise see `Getting OpenOCD`_
for options to download OpenOCD from official repositories.
These debug host tools are compatible with the following debug probes:
- :ref:`opensda-daplink-onboard-debug-probe`
- :ref:`jlink-external-debug-probe`
- :ref:`stlink-v21-onboard-debug-probe`
Check if your SoC is listed in `OpenOCD Supported Devices`_.
.. note:: On Linux, openocd is available though the `Zephyr SDK
<https://github.com/zephyrproject-rtos/sdk-ng/releases>`_.
Windows users should use the following steps to install
openocd:
- Download openocd for Windows from here: `OpenOCD Windows`_
- Copy bin and share dirs to ``C:\Program Files\OpenOCD\``
- Add ``C:\Program Files\OpenOCD\bin`` to 'PATH' environment variable
.. _pyocd-debug-host-tools:
pyOCD Debug Host Tools
**********************
pyOCD is an open source project from Arm that provides GDB remote debugging and
flash programming support for Arm Cortex-M SoCs. It is distributed on PyPi and
installed when you complete the :ref:`gs_python_deps` step in the Getting
Started Guide. pyOCD includes support for Zephyr RTOS-awareness.
These debug host tools are compatible with the following debug probes:
- :ref:`opensda-daplink-onboard-debug-probe`
- :ref:`stlink-v21-onboard-debug-probe`
Check if your SoC is listed in `pyOCD Supported Devices`_.
.. _J-Link Software and Documentation Pack:
https://www.segger.com/downloads/jlink/#J-LinkSoftwareAndDocumentationPack
.. _J-Link Supported Devices:
https://www.segger.com/downloads/supported-devices.php
.. _Getting OpenOCD:
http://openocd.org/getting-openocd/
.. _OpenOCD Supported Devices:
https://github.com/zephyrproject-rtos/openocd/tree/master/tcl/target
.. _pyOCD Supported Devices:
https://github.com/mbedmicro/pyOCD/tree/master/pyocd/target/builtin
.. _OpenOCD Windows:
http://gnutoolchains.com/arm-eabi/openocd/
Reference in New Issue View Git Blame Copy Permalink