1.. _flash-debug-host-tools: 2 3Flash & Debug Host Tools 4######################## 5 6This guide describes the software tools you can run on your host workstation to 7flash and debug Zephyr applications. 8 9Zephyr's west tool has built-in support for all of these in its ``flash``, 10``debug``, ``debugserver``, and ``attach`` commands, provided your board 11hardware supports them and your Zephyr board directory's :file:`board.cmake` 12file declares that support properly. See :ref:`west-build-flash-debug` for 13more information on these commands. 14 15.. _atmel_sam_ba_bootloader: 16 17 18SAM Boot Assistant (SAM-BA) 19*************************** 20 21Atmel SAM Boot Assistant (Atmel SAM-BA) allows In-System Programming (ISP) 22from USB or UART host without any external programming interface. Zephyr 23allows users to develop and program boards with SAM-BA support using 24:ref:`west <west-flashing>`. Zephyr supports devices with/without ROM 25bootloader and both extensions from Arduino and Adafruit. Full support was 26introduced in Zephyr SDK 0.12.0. 27 28The typical command to flash the board is: 29 30.. code-block:: console 31 32 west flash [ -r bossac ] [ -p /dev/ttyX ] 33 34Flash configuration for devices: 35 36.. tabs:: 37 38 .. tab:: With ROM bootloader 39 40 These devices don't need any special configuration. After building your 41 application, just run ``west flash`` to flash the board. 42 43 .. tab:: Without ROM bootloader 44 45 For these devices, the user should: 46 47 1. Define flash partitions required to accommodate the bootloader and 48 application image; see :ref:`flash_map_api` for details. 49 2. Have board :file:`.defconfig` file with the 50 :kconfig:option:`CONFIG_USE_DT_CODE_PARTITION` Kconfig option set to ``y`` to 51 instruct the build system to use these partitions for code relocation. 52 This option can also be set in ``prj.conf`` or any other Kconfig fragment. 53 3. Build and flash the SAM-BA bootloader on the device. 54 55 .. tab:: With compatible SAM-BA bootloader 56 57 For these devices, the user should: 58 59 1. Define flash partitions required to accommodate the bootloader and 60 application image; see :ref:`flash_map_api` for details. 61 2. Have board :file:`.defconfig` file with the 62 :kconfig:option:`CONFIG_BOOTLOADER_BOSSA` Kconfig option set to ``y``. This will 63 automatically select the :kconfig:option:`CONFIG_USE_DT_CODE_PARTITION` Kconfig 64 option which instruct the build system to use these partitions for code 65 relocation. The board :file:`.defconfig` file should have 66 :kconfig:option:`CONFIG_BOOTLOADER_BOSSA_ARDUINO` , 67 :kconfig:option:`CONFIG_BOOTLOADER_BOSSA_ADAFRUIT_UF2` or the 68 :kconfig:option:`CONFIG_BOOTLOADER_BOSSA_LEGACY` Kconfig option set to ``y`` 69 to select the right compatible SAM-BA bootloader mode. 70 These options can also be set in ``prj.conf`` or any other Kconfig fragment. 71 3. Build and flash the SAM-BA bootloader on the device. 72 73.. note:: 74 75 The :kconfig:option:`CONFIG_BOOTLOADER_BOSSA_LEGACY` Kconfig option should be used 76 as last resource. Try configure first with Devices without ROM bootloader. 77 78 79Typical flash layout and configuration 80-------------------------------------- 81 82For bootloaders that reside on flash, the devicetree partition layout is 83mandatory. For devices that have a ROM bootloader, they are mandatory when 84the application uses a storage or other non-application partition. In this 85special case, the boot partition should be omitted and code_partition should 86start from offset 0. It is necessary to define the partitions with sizes that 87avoid overlaps, always. 88 89A typical flash layout for devices without a ROM bootloader is: 90 91.. code-block:: devicetree 92 93 / { 94 chosen { 95 zephyr,code-partition = &code_partition; 96 }; 97 }; 98 99 &flash0 { 100 partitions { 101 compatible = "fixed-partitions"; 102 #address-cells = <1>; 103 #size-cells = <1>; 104 105 boot_partition: partition@0 { 106 label = "sam-ba"; 107 reg = <0x00000000 0x2000>; 108 read-only; 109 }; 110 111 code_partition: partition@2000 { 112 label = "code"; 113 reg = <0x2000 0x3a000>; 114 read-only; 115 }; 116 117 /* 118 * The final 16 KiB is reserved for the application. 119 * Storage partition will be used by FCB/LittleFS/NVS 120 * if enabled. 121 */ 122 storage_partition: partition@3c000 { 123 label = "storage"; 124 reg = <0x0003c000 0x00004000>; 125 }; 126 }; 127 }; 128 129A typical flash layout for devices with a ROM bootloader and storage 130partition is: 131 132.. code-block:: devicetree 133 134 / { 135 chosen { 136 zephyr,code-partition = &code_partition; 137 }; 138 }; 139 140 &flash0 { 141 partitions { 142 compatible = "fixed-partitions"; 143 #address-cells = <1>; 144 #size-cells = <1>; 145 146 code_partition: partition@0 { 147 label = "code"; 148 reg = <0x0 0xF0000>; 149 read-only; 150 }; 151 152 /* 153 * The final 64 KiB is reserved for the application. 154 * Storage partition will be used by FCB/LittleFS/NVS 155 * if enabled. 156 */ 157 storage_partition: partition@F0000 { 158 label = "storage"; 159 reg = <0x000F0000 0x00100000>; 160 }; 161 }; 162 }; 163 164 165Enabling SAM-BA runner 166---------------------- 167 168In order to instruct Zephyr west tool to use the SAM-BA bootloader the 169:file:`board.cmake` file must have 170``include(${ZEPHYR_BASE}/boards/common/bossac.board.cmake)`` entry. Note that 171Zephyr tool accept more entries to define multiple runners. By default, the 172first one will be selected when using ``west flash`` command. The remaining 173options are available passing the runner option, for instance 174``west flash -r bossac``. 175 176 177More implementation details can be found in the :ref:`boards` documentation. 178As a quick reference, see these three board documentation pages: 179 180 - :ref:`sam4e_xpro` (ROM bootloader) 181 - :ref:`adafruit_feather_m0_basic_proto` (Adafruit UF2 bootloader) 182 - :ref:`arduino_nano_33_iot` (Arduino bootloader) 183 - :ref:`arduino_nano_33_ble` (Arduino legacy bootloader) 184 185.. _jlink-debug-host-tools: 186 187Enabling BOSSAC on Windows Native [Experimental] 188------------------------------------------------ 189Zephyr SDK´s bossac is only currenty support on Linux and macOS. Windows support 190can be achieved by using the bossac version from `BOSSA oficial releases`_. 191After installing using default options, the :file:`bossac.exe` must be added to 192Windows PATH. A specific bossac executable can be used by passing the 193``--bossac`` option, as follows: 194 195.. code-block:: console 196 197 west flash -r bossac --bossac="C:\Program Files (x86)\BOSSA\bossac.exe" --bossac-port="COMx" 198 199.. note:: 200 201 WSL is not currently supported. 202 203J-Link Debug Host Tools 204*********************** 205 206Segger provides a suite of debug host tools for Linux, macOS, and Windows 207operating systems: 208 209- J-Link GDB Server: GDB remote debugging 210- J-Link Commander: Command-line control and flash programming 211- RTT Viewer: RTT terminal input and output 212- SystemView: Real-time event visualization and recording 213 214These debug host tools are compatible with the following debug probes: 215 216- :ref:`lpclink2-jlink-onboard-debug-probe` 217- :ref:`opensda-jlink-onboard-debug-probe` 218- :ref:`jlink-external-debug-probe` 219- :ref:`stlink-v21-onboard-debug-probe` 220 221Check if your SoC is listed in `J-Link Supported Devices`_. 222 223Download and install the `J-Link Software and Documentation Pack`_ to get the 224J-Link GDB Server and Commander, and to install the associated USB device 225drivers. RTT Viewer and SystemView can be downloaded separately, but are not 226required. 227 228Note that the J-Link GDB server does not yet support Zephyr RTOS-awareness. 229 230.. _openocd-debug-host-tools: 231 232OpenOCD Debug Host Tools 233************************ 234 235OpenOCD is a community open source project that provides GDB remote debugging 236and flash programming support for a wide range of SoCs. A fork that adds Zephyr 237RTOS-awareness is included in the Zephyr SDK; otherwise see `Getting OpenOCD`_ 238for options to download OpenOCD from official repositories. 239 240These debug host tools are compatible with the following debug probes: 241 242- :ref:`opensda-daplink-onboard-debug-probe` 243- :ref:`jlink-external-debug-probe` 244- :ref:`stlink-v21-onboard-debug-probe` 245 246Check if your SoC is listed in `OpenOCD Supported Devices`_. 247 248.. note:: On Linux, openocd is available though the `Zephyr SDK 249 <https://github.com/zephyrproject-rtos/sdk-ng/releases>`_. 250 Windows users should use the following steps to install 251 openocd: 252 253 - Download openocd for Windows from here: `OpenOCD Windows`_ 254 - Copy bin and share dirs to ``C:\Program Files\OpenOCD\`` 255 - Add ``C:\Program Files\OpenOCD\bin`` to 'PATH' environment variable 256 257.. _pyocd-debug-host-tools: 258 259pyOCD Debug Host Tools 260********************** 261 262pyOCD is an open source project from Arm that provides GDB remote debugging and 263flash programming support for Arm Cortex-M SoCs. It is distributed on PyPi and 264installed when you complete the :ref:`gs_python_deps` step in the Getting 265Started Guide. pyOCD includes support for Zephyr RTOS-awareness. 266 267These debug host tools are compatible with the following debug probes: 268 269- :ref:`opensda-daplink-onboard-debug-probe` 270- :ref:`stlink-v21-onboard-debug-probe` 271 272Check if your SoC is listed in `pyOCD Supported Devices`_. 273 274.. _lauterbach-trace32-debug-host-tools: 275 276Lauterbach TRACE32 Debug Host Tools 277*********************************** 278 279`Lauterbach TRACE32`_ is a product line of microprocessor development tools, 280debuggers and real-time tracer with support for JTAG, SWD, NEXUS or ETM over 281multiple core architectures, including Arm Cortex-A/-R/-M, RISC-V, Xtensa, etc. 282Zephyr allows users to develop and program boards with Lauterbach TRACE32 283support using :ref:`west <west-flashing>`. 284 285The runner consists of a wrapper around TRACE32 software, and allows a Zephyr 286board to execute a custom start-up script (Practice Script) for the different 287commands supported, including the ability to pass extra arguments from CMake. 288Is up to the board using this runner to define the actions performed on each 289command. 290 291Install Lauterbach TRACE32 Software 292----------------------------------- 293 294Download Lauterbach TRACE32 software from the `Lauterbach TRACE32 download website`_ 295(registration required) and follow the installation steps described in 296`Lauterbach TRACE32 Installation Guide`_. 297 298Flashing and Debugging 299---------------------- 300 301Set the :ref:`environment variable <env_vars>` :envvar:`T32_DIR` to the TRACE32 302system directory. Then execute ``west flash`` or ``west debug`` commands to 303flash or debug the Zephyr application as detailed in :ref:`west-build-flash-debug`. 304The ``debug`` command launches TRACE32 GUI to allow debug the Zephyr 305application, while the ``flash`` command hides the GUI and perform all 306operations in the background. 307 308By default, the ``t32`` runner will launch TRACE32 using the default 309configuration file named ``config.t32`` located in the TRACE32 system 310directory. To use a different configuration file, supply the argument 311``--config CONFIG`` to the runner, for example: 312 313.. code-block:: console 314 315 west flash --config myconfig.t32 316 317For more options, run ``west flash --context -r t32`` to print the usage. 318 319Zephyr RTOS Awareness 320--------------------- 321 322To enable Zephyr RTOS awareness follow the steps described in 323`Lauterbach TRACE32 Zephyr OS Awareness Manual`_. 324 325 326.. _J-Link Software and Documentation Pack: 327 https://www.segger.com/downloads/jlink/#J-LinkSoftwareAndDocumentationPack 328 329.. _J-Link Supported Devices: 330 https://www.segger.com/downloads/supported-devices.php 331 332.. _Getting OpenOCD: 333 https://openocd.org/pages/getting-openocd.html 334 335.. _OpenOCD Supported Devices: 336 https://github.com/zephyrproject-rtos/openocd/tree/latest/tcl/target 337 338.. _pyOCD Supported Devices: 339 https://github.com/pyocd/pyOCD/tree/main/pyocd/target/builtin 340 341.. _OpenOCD Windows: 342 http://gnutoolchains.com/arm-eabi/openocd/ 343 344.. _Lauterbach TRACE32: 345 https://www.lauterbach.com/ 346 347.. _Lauterbach TRACE32 download website: 348 http://www.lauterbach.com/download_trace32.html 349 350.. _Lauterbach TRACE32 Installation Guide: 351 https://www2.lauterbach.com/pdf/installation.pdf 352 353.. _Lauterbach TRACE32 Zephyr OS Awareness Manual: 354 https://www2.lauterbach.com/pdf/rtos_zephyr.pdf 355 356.. _BOSSA oficial releases: 357 https://github.com/shumatech/BOSSA/releases 358
