1.. _debug-probes: 2 3Debug Probes 4############ 5 6A *debug probe* is special hardware which allows you to control execution of a 7Zephyr application running on a separate board. Debug probes usually allow 8reading and writing registers and memory, and support breakpoint debugging of 9the Zephyr application on your host workstation using tools like GDB. They may 10also support other debug software and more advanced features such as 11:ref:`tracing program execution <tracing>`. For details on the related host 12software supported by Zephyr, see :ref:`flash-debug-host-tools`. 13 14Debug probes are usually connected to your host workstation via USB; they 15are sometimes also accessible via an IP network or other means. They usually 16connect to the device running Zephyr using the JTAG or SWD protocols. Debug 17probes are either separate hardware devices or circuitry integrated into the same 18board which runs Zephyr. 19 20Many supported boards in Zephyr include a second microcontroller that serves as 21an onboard debug probe, usb-to-serial adapter, and sometimes a drag-and-drop 22flash programmer. This eliminates the need to purchase an external debug probe 23and provides a variety of debug host tool options. 24 25Several hardware vendors have their own branded onboard debug probe 26implementations: NXP LPC boards have `LPC-Link2 <#lpclink2-jlink-onboard-debug-probe>`_, 27NXP Kinetis (former Freescale) boards have `OpenSDA <#opensda-daplink-onboard-debug-probe>`_, 28and ST boards have `ST-LINK <#stlink-v21-onboard-debug-probe>`_. Each onboard debug probe 29microcontroller can support one or more types of firmware that communicate with 30their respective debug host tools. For example, an OpenSDA microcontroller can 31be programmed with DAPLink firmware to communicate with pyOCD or OpenOCD debug 32host tools, or with J-Link firmware to communicate with J-Link debug host 33tools. 34 35 36+------------------------------------------+------------------------------------------------------------------------------------+ 37|| *Debug Probes & Host Tools* | Host Tools | 38+| *Compatibility Chart* +--------------------+--------------------+---------------------+--------------------+ 39| | **J-Link Debug** | **OpenOCD** | **pyOCD** | **NXP S32DS** | 40+----------------+-------------------------+--------------------+--------------------+---------------------+--------------------+ 41| | **LPC-Link2 J-Link** | ✓ | | | | 42| +-------------------------+--------------------+--------------------+---------------------+--------------------+ 43| | **OpenSDA DAPLink** | | ✓ | ✓ | | 44| +-------------------------+--------------------+--------------------+---------------------+--------------------+ 45| Debug Probes | **OpenSDA J-Link** | ✓ | | | | 46| +-------------------------+--------------------+--------------------+---------------------+--------------------+ 47| | **J-Link External** | ✓ | ✓ | | | 48| +-------------------------+--------------------+--------------------+---------------------+--------------------+ 49| | **ST-LINK/V2-1** | ✓ | ✓ | *some STM32 boards* | | 50| +-------------------------+--------------------+--------------------+---------------------+--------------------+ 51| | **NXP S32 Debug Probe** | | | | ✓ | 52+----------------+-------------------------+--------------------+--------------------+---------------------+--------------------+ 53 54 55Some supported boards in Zephyr do not include an onboard debug probe and 56therefore require an external debug probe. In addition, boards that do include 57an onboard debug probe often also have an SWD or JTAG header to enable the use 58of an external debug probe instead. One reason this may be useful is that the 59onboard debug probe may have limitations, such as lack of support for advanced 60debuggers or high-speed tracing. You may need to adjust jumpers to prevent the 61onboard debug probe from interfering with the external debug probe. 62 63.. _mcu-link-cmsis-onboard-debug-probe: 64 65MCU-Link CMSIS-DAP Onboard Debug Probe 66*************************************** 67 68The CMSIS-DAP debug probes allow debugging from any compatible toolchain, 69including IAR EWARM, Keil MDK, NXP’s MCUXpresso IDE and 70MCUXpresso extension for VS Code. In addition to debug probe functionality, the 71MCU-Link probes may also provide: 72 731. SWO trace end point: this virtual device is used by MCUXpresso to retrieve 74 SWO trace data. See the MCUXpresso IDE documentation for more information. 75#. Virtual COM (VCOM) port / UART bridge connected to the target processor 76#. USB to UART, SPI and/or I2C interfaces (depending on MCU-Link 77 type/implementation) 78#. Energy measurements of the target MCU 79 80This debug probe is compatible with the following debug host tools: 81 82- :ref:`linkserver-debug-host-tools` 83 84This probe is realized by programming the MCU-Link microcontroller with the 85CMSIS-DAP MCU-Link firmware, which is already installed by default. NXP 86recommends using NXP's `MCUXpresso Installer`_, which installs both the MCU-Link 87host tools plus the :ref:`linkserver-debug-host-tools`. 88 891. Put the MCU-Link microcontroller into DFU boot mode by attaching the DFU 90 jumper, then powering up the board. 91 92#. Run the ``program_CMSIS`` script, found in the installed MCU-Link ``scripts`` 93 folder. 94 95#. Remove the DFU jumper and power cycle the board. 96 97.. _mcu-link-jlink-onboard-debug-probe: 98 99MCU-Link JLink Onboard Debug Probe 100************************************ 101 102The MCU-Link J-Link is an onboard debug probe and usb-to-serial adapter 103supported on many NXP development boards. 104 105This debug probe is compatible with the following debug host tools: 106 107- :ref:`jlink-debug-host-tools` 108 109These probes do not have JLink firmware installed by default, and must be 110updated. NXP recommends using NXP's `MCUXpresso Installer`_, which installs both 111the :ref:`jlink-debug-host-tools` plus the MCU-Link host tools. 112 1131. Put the MCU-Link microcontroller into DFU boot mode by attaching the DFU 114 jumper, then powering up the board. 115 116#. Run the ``program_JLINK`` script, found in the installed MCU-Link ``scripts`` 117 folder. 118 119#. Remove the DFU jumper and power cycle the board. 120 121.. _lpclink2-cmsis-onboard-debug-probe: 122 123LPC-LINK2 CMSIS DAP Onboard Debug Probe 124*************************************** 125 126The CMSIS-DAP debug probes allow debugging from any compatible toolchain, 127including IAR EWARM, Keil MDK, as well as NXP’s MCUXpresso IDE and 128MCUXpresso extension for VS Code. 129As well as providing debug probe functionality, the LPC-Link2 probes also 130provide: 131 1321. SWO trace end point: this virtual device is used by MCUXpresso to retrieve 133 SWO trace data. See the MCUXpresso IDE documentation for more information. 1342. Virtual COM (VCOM) port / UART bridge connected to the target processor 1353. LPCSIO bridge that provides communication to I2C and SPI slave devices 136 137This probe is realized by programming the LPC-Link2 microcontroller with the CMSIS-DAP 138LPC-Link2 firmware. Download and install `LPCScrypt`_ to get the firmware and 139programming scripts. 140 141.. note:: Verify the firmware supports your board by visiting `Firmware for LPCXpresso`_ 142 1431. Put the LPC-Link2 microcontroller into DFU boot mode by attaching the DFU 144 jumper, then powering up the board. 145 146#. Run the ``program_CMSIS`` script. 147 148#. Remove the DFU jumper and power cycle the board. 149 150.. _lpclink2-jlink-onboard-debug-probe: 151 152LPC-Link2 J-Link Onboard Debug Probe 153************************************ 154 155The LPC-Link2 J-Link is an onboard debug probe and usb-to-serial adapter 156supported on many NXP LPC and i.MX RT development boards. 157 158This debug probe is compatible with the following debug host tools: 159 160- :ref:`jlink-debug-host-tools` 161 162This probe is realized by programming the LPC-Link2 microcontroller with J-Link 163LPC-Link2 firmware. Download and install `LPCScrypt`_ to get the firmware and 164programming scripts. 165 166.. note:: Verify the firmware supports your board by visiting `Firmware for LPCXpresso`_ 167 1681. Put the LPC-Link2 microcontroller into DFU boot mode by attaching the DFU 169 jumper, then powering up the board. 170 171#. Run the ``program_JLINK`` script. 172 173#. Remove the DFU jumper and power cycle the board. 174 175.. _opensda-daplink-onboard-debug-probe: 176 177OpenSDA DAPLink Onboard Debug Probe 178*********************************** 179 180The OpenSDA DAPLink is an onboard debug probe and usb-to-serial adapter 181supported on many NXP Kinetis and i.MX RT development boards. It also includes 182drag-and-drop flash programming support. 183 184This debug probe is compatible with the following debug host tools: 185 186- :ref:`pyocd-debug-host-tools` 187- :ref:`openocd-debug-host-tools` 188 189This probe is realized by programming the OpenSDA microcontroller with DAPLink 190OpenSDA firmware. NXP provides `OpenSDA DAPLink Board-Specific Firmwares`_. 191 192Install the debug host tools before you program the firmware. 193 194As with all OpenSDA debug probes, the steps for programming the firmware are: 195 1961. Put the OpenSDA microcontroller into bootloader mode by holding the reset 197 button while you power on the board. Note that "bootloader mode" in this 198 context applies to the OpenSDA microcontroller itself, not the target 199 microcontroller of your Zephyr application. 200 201#. After you power on the board, release the reset button. A USB mass storage 202 device called **BOOTLOADER** or **MAINTENANCE** will enumerate. 203 204#. Copy the OpenSDA firmware binary to the USB mass storage device. 205 206#. Power cycle the board, this time without holding the reset button. You 207 should see three USB devices enumerate: a CDC device (serial port), a HID 208 device (debug port), and a mass storage device (drag-and-drop flash 209 programming). 210 211.. _opensda-jlink-onboard-debug-probe: 212 213OpenSDA J-Link Onboard Debug Probe 214********************************** 215 216The OpenSDA J-Link is an onboard debug probe and usb-to-serial adapter 217supported on many NXP Kinetis and i.MX RT development boards. 218 219This debug probe is compatible with the following debug host tools: 220 221- :ref:`jlink-debug-host-tools` 222 223This probe is realized by programming the OpenSDA microcontroller with J-Link 224OpenSDA firmware. Segger provides `OpenSDA J-Link Generic Firmwares`_ and 225`OpenSDA J-Link Board-Specific Firmwares`_, where the latter is generally 226recommended when available. Board-specific firmwares are required for i.MX RT 227boards to support their external flash memories, whereas generic firmwares are 228compatible with all Kinetis boards. 229 230Install the debug host tools before you program the firmware. 231 232As with all OpenSDA debug probes, the steps for programming the firmware are: 233 2341. Put the OpenSDA microcontroller into bootloader mode by holding the reset 235 button while you power on the board. Note that "bootloader mode" in this 236 context applies to the OpenSDA microcontroller itself, not the target 237 microcontroller of your Zephyr application. 238 239#. After you power on the board, release the reset button. A USB mass storage 240 device called **BOOTLOADER** or **MAINTENANCE** will enumerate. 241 242#. Copy the OpenSDA firmware binary to the USB mass storage device. 243 244#. Power cycle the board, this time without holding the reset button. You 245 should see two USB devices enumerate: a CDC device (serial port) and a 246 vendor-specific device (debug port). 247 248.. _jlink-external-debug-probe: 249 250J-Link External Debug Probe 251*************************** 252 253`Segger J-Link`_ is a family of external debug probes, including J-Link EDU, 254J-Link PLUS, J-Link ULTRA+, and J-Link PRO, that support a large number of 255devices from different hardware architectures and vendors. 256 257This debug probe is compatible with the following debug host tools: 258 259- :ref:`jlink-debug-host-tools` 260- :ref:`openocd-debug-host-tools` 261 262Install the debug host tools before you program the firmware. 263 264.. _stlink-v21-onboard-debug-probe: 265 266ST-LINK/V2-1 Onboard Debug Probe 267******************************** 268 269ST-LINK/V2-1 is a serial and debug adapter built into all Nucleo and Discovery 270boards. It provides a bridge between your computer (or other USB host) and the 271embedded target processor, which can be used for debugging, flash programming, 272and serial communication, all over a simple USB cable. 273 274It is compatible with the following host debug tools: 275 276- :ref:`openocd-debug-host-tools` 277- :ref:`jlink-debug-host-tools` 278 279For some STM32 based boards, it is also compatible with: 280 281- :ref:`pyocd-debug-host-tools` 282 283While it works out of the box with OpenOCD, it requires some flashing 284to work with J-Link. To do this, SEGGER offers a firmware upgrading the 285ST-LINK/V2-1 on board on the Nucleo and Discovery boards. This firmware makes 286the ST-LINK/V2-1 compatible with J-LinkOB, allowing users to take advantage of 287most J-Link features like the ultra fast flash download and debugging speed or 288the free-to-use GDBServer. 289 290More information about upgrading ST-LINK/V2-1 to JLink or restore ST-Link/V2-1 291firmware please visit: `Segger over ST-Link`_ 292 293Flash and debug with ST-Link 294============================ 295 296.. tabs:: 297 298 .. tab:: Using OpenOCD 299 300 OpenOCD is available by default on ST-Link and configured as the default flash 301 and debug tool. Flash and debug can be done as follows: 302 303 .. zephyr-app-commands:: 304 :zephyr-app: samples/hello_world 305 :goals: flash 306 307 .. zephyr-app-commands:: 308 :zephyr-app: samples/hello_world 309 :goals: debug 310 311 .. tab:: _`Using Segger J-Link` 312 313 Once STLink is flashed with SEGGER FW and J-Link GDB server is installed on your 314 host computer, you can flash and debug as follows: 315 316 Use CMake with ``-DBOARD_FLASH_RUNNER=jlink`` to change the default OpenOCD 317 runner to J-Link. Alternatively, you might add the following line to your 318 application ``CMakeList.txt`` file. 319 320 .. code-block:: cmake 321 322 set(BOARD_FLASH_RUNNER jlink) 323 324 If you use West (Zephyr's meta-tool) you can modify the default runner using 325 the ``--runner`` (or ``-r``) option. 326 327 .. code-block:: console 328 329 west flash --runner jlink 330 331 To attach a debugger to your board and open up a debug console with ``jlink``. 332 333 .. code-block:: console 334 335 west debug --runner jlink 336 337 For more information about West and available options, see :ref:`west`. 338 339 If you configured your Zephyr application to use `Segger RTT`_ console instead, 340 open telnet: 341 342 .. code-block:: console 343 344 $ telnet localhost 19021 345 Trying ::1... 346 Trying 127.0.0.1... 347 Connected to localhost. 348 Escape character is '^]'. 349 SEGGER J-Link V6.30f - Real time terminal output 350 J-Link STLink V21 compiled Jun 26 2017 10:35:16 V1.0, SN=773895351 351 Process: JLinkGDBServerCLExe 352 Zephyr Shell, Zephyr version: 1.12.99 353 Type 'help' for a list of available commands 354 shell> 355 356 If you get no RTT output you might need to disable other consoles which conflict 357 with the RTT one if they are enabled by default in the particular sample or 358 application you are running, such as disable UART_CONSOLE in menuconfig 359 360Updating or restoring ST-Link firmware 361====================================== 362 363ST-Link firmware can be updated using `STM32CubeProgrammer Tool`_. 364It is usually useful when facing flashing issues, for instance when using 365twister's device-testing option. 366 367Once installed, you can update attached board ST-Link firmware with the 368following command 369 370 .. code-block:: console 371 372 s java -jar ~/STMicroelectronics/STM32Cube/STM32CubeProgrammer/Drivers/FirmwareUpgrade/STLinkUpgrade.jar -sn <board_uid> 373 374Where board_uid can be obtained using twister's generate-hardware-map 375option. For more information about twister and available options, see 376:ref:`twister_script`. 377 378.. _nxp-s32-debug-probe: 379 380NXP S32 Debug Probe 381******************* 382 383`NXP S32 Debug Probe`_ enables NXP S32 target system debugging via a standard 384debug port while connected to a developer's workstation via USB or remotely via 385Ethernet. 386 387NXP S32 Debug Probe is designed to work in conjunction with NXP S32 Design Studio 388(S32DS) and NXP Automotive microcontrollers and processors. Install the debug 389host tools as in indicated in :ref:`nxp-s32-debug-host-tools` before you program 390the firmware. 391 392.. _LPCScrypt: 393 https://www.nxp.com/lpcscrypt 394 395.. _Firmware for LPCXpresso: 396 https://www.segger.com/products/debug-probes/j-link/models/other-j-links/lpcxpresso-on-board/ 397 398.. _OpenSDA DAPLink Board-Specific Firmwares: 399 https://www.nxp.com/opensda 400 401.. _OpenSDA J-Link Generic Firmwares: 402 https://www.segger.com/downloads/jlink/#JLinkOpenSDAGenericFirmwares 403 404.. _OpenSDA J-Link Board-Specific Firmwares: 405 https://www.segger.com/downloads/jlink/#JLinkOpenSDABoardSpecificFirmwares 406 407.. _Segger J-Link: 408 https://www.segger.com/products/debug-probes/j-link/ 409 410.. _Segger over ST-Link: 411 https://www.segger.com/products/debug-probes/j-link/models/other-j-links/st-link-on-board/ 412 413.. _Segger RTT: 414 https://www.segger.com/jlink-rtt.html 415 416.. _STM32CubeProgrammer Tool: 417 https://www.st.com/en/development-tools/stm32cubeprog.html 418 419.. _MCUXpresso Installer: 420 https://www.nxp.com/lgfiles/updates/mcuxpresso/MCUXpressoInstaller.exe 421 422.. _NXP S32 Debug Probe: 423 https://www.nxp.com/design/software/automotive-software-and-tools/s32-debug-probe:S32-DP 424
