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 board.cmake
file declares that support properly. See Building, Flashing and Debugging for
more information on these commands.
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 west. 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:
west flash [ -r bossac ] [ -p /dev/ttyX ]
Flash configuration for devices:
These devices don’t need any special configuration. After building your
application, just run west flash
to flash the board.
For these devices, the user should:
Define flash partitions required to accommodate the bootloader and application image; see Flash map for details.
Have board
.defconfig
file with theCONFIG_USE_DT_CODE_PARTITION
Kconfig option set toy
to instruct the build system to use these partitions for code relocation. This option can also be set inprj.conf
or any other Kconfig fragment.Build and flash the SAM-BA bootloader on the device.
For these devices, the user should:
Define flash partitions required to accommodate the bootloader and application image; see Flash map for details.
Have board
.defconfig
file with theCONFIG_BOOTLOADER_BOSSA
Kconfig option set toy
. This will automatically select theCONFIG_USE_DT_CODE_PARTITION
Kconfig option which instruct the build system to use these partitions for code relocation. The board.defconfig
file should haveCONFIG_BOOTLOADER_BOSSA_ARDUINO
,CONFIG_BOOTLOADER_BOSSA_ADAFRUIT_UF2
or theCONFIG_BOOTLOADER_BOSSA_LEGACY
Kconfig option set toy
to select the right compatible SAM-BA bootloader mode. These options can also be set inprj.conf
or any other Kconfig fragment.Build and flash the SAM-BA bootloader on the device.
Note
The 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:
/ {
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:
/ {
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
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 Supported Boards documentation. As a quick reference, see these three board documentation pages:
SAM4E Xplained Pro (ROM bootloader)
Adafruit Feather M0 Basic Proto (Adafruit UF2 bootloader)
Arduino Nano 33 IOT (Arduino bootloader)
Arduino Nano 33 BLE (Sense) (Arduino legacy bootloader)
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:
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 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:
Check if your SoC is listed in OpenOCD Supported Devices.
Note
On Linux, openocd is available though the Zephyr SDK. 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 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 Get Zephyr and install Python dependencies step in the Getting Started Guide. pyOCD includes support for Zephyr RTOS-awareness.
These debug host tools are compatible with the following debug probes:
Check if your SoC is listed in pyOCD Supported Devices.
Lauterbach TRACE32 Debug Host Tools
Lauterbach TRACE32 is a product line of microprocessor development tools, debuggers and real-time tracer with support for JTAG, SWD, NEXUS or ETM over multiple core architectures, including Arm Cortex-A/-R/-M, RISC-V, Xtensa, etc. Zephyr allows users to develop and program boards with Lauterbach TRACE32 support using west.
The runner consists of a wrapper around TRACE32 software, and allows a Zephyr board to execute a custom start-up script (Practice Script) for the different commands supported, including the ability to pass extra arguments from CMake. Is up to the board using this runner to define the actions performed on each command.
Install Lauterbach TRACE32 Software
Download Lauterbach TRACE32 software from the Lauterbach TRACE32 download website (registration required) and follow the installation steps described in Lauterbach TRACE32 Installation Guide.
Flashing and Debugging
Set the environment variable T32_DIR
to the TRACE32
system directory. Then execute west flash
or west debug
commands to
flash or debug the Zephyr application as detailed in Building, Flashing and Debugging.
The debug
command launches TRACE32 GUI to allow debug the Zephyr
application, while the flash
command hides the GUI and perform all
operations in the background.
By default, the t32
runner will launch TRACE32 using the default
configuration file named config.t32
located in the TRACE32 system
directory. To use a different configuration file, supply the argument
--config CONFIG
to the runner, for example:
west flash --config myconfig.t32
For more options, run west flash --context -r t32
to print the usage.
Zephyr RTOS Awareness
To enable Zephyr RTOS awareness follow the steps described in Lauterbach TRACE32 Zephyr OS Awareness Manual.