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 boards may use 27`OpenSDA <#opensda-onboard-debug-probe>`_, 28`LPC-Link2 <#lpc-link2-onboard-debug-probe>`_, or 29`MCU-Link <#mcu-link-onboard-debug-probe>`_, probes depending on 30the microcontroller the debug probe firmware runs on. 31ST boards have the `ST-LINK probe <#stlink-v21-onboard-debug-probe>`_. Each 32onboard debug probe microcontroller can support one or more types of firmware 33that communicate with their respective debug host tools. For example, an 34OpenSDA microcontroller can be programmed with DAPLink firmware to communicate 35with pyOCD or OpenOCD debug host tools, or with J-Link firmware to communicate 36with J-Link debug host tools. 37 38 39+------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ 40|| *Debug Probes & Host Tools* | Host Tools | 41+| *Compatibility Chart* +--------------------+--------------------+---------------------+--------------------+--------------------+------------------------+ 42| | **J-Link Debug** | **OpenOCD** | **pyOCD** | **NXP S32DS** | **NXP LinkServer** | **ST-LINK GDB Server** | 43+----------------+-------------------------+--------------------+--------------------+---------------------+--------------------+--------------------+------------------------+ 44| | **J-Link External** | ✓ | ✓ | | | | | 45| +-------------------------+--------------------+--------------------+---------------------+--------------------+--------------------+------------------------+ 46| | **LPC-Link2 CMSIS-DAP** | | | | | ✓ | | 47| +-------------------------+--------------------+--------------------+---------------------+--------------------+--------------------+------------------------+ 48| | **LPC-Link2 J-Link** | ✓ | | | | | | 49| +-------------------------+--------------------+--------------------+---------------------+--------------------+--------------------+------------------------+ 50| | **MCU-Link CMSIS-DAP** | | | | | ✓ | | 51| Debug Probes +-------------------------+--------------------+--------------------+---------------------+--------------------+--------------------+------------------------+ 52| | **MCU-Link J-Link** | ✓ | | | | | | 53| +-------------------------+--------------------+--------------------+---------------------+--------------------+--------------------+------------------------+ 54| | **NXP S32 Debug Probe** | | | | ✓ | | | 55| +-------------------------+--------------------+--------------------+---------------------+--------------------+--------------------+------------------------+ 56| | **OpenSDA DAPLink** | | ✓ | ✓ | | ✓ | | 57| +-------------------------+--------------------+--------------------+---------------------+--------------------+--------------------+------------------------+ 58| | **OpenSDA J-Link** | ✓ | | | | | | 59| +-------------------------+--------------------+--------------------+---------------------+--------------------+--------------------+------------------------+ 60| | **ST-LINK/V2-1** | ✓ | ✓ | *some STM32 boards* | | | ✓ | 61+----------------+-------------------------+--------------------+--------------------+---------------------+--------------------+--------------------+------------------------+ 62 63 64Some supported boards in Zephyr do not include an onboard debug probe and 65therefore require an external debug probe. In addition, boards that do include 66an onboard debug probe often also have an SWD or JTAG header to enable the use 67of an external debug probe instead. One reason this may be useful is that the 68onboard debug probe may have limitations, such as lack of support for advanced 69debuggers or high-speed tracing. You may need to adjust jumpers to prevent the 70onboard debug probe from interfering with the external debug probe. 71 72.. _nxp-onboard-debug-probes: 73 74NXP Onboard Debug Probes 75************************ 76 77NXP boards may have one of several onboard debug probes. These probes include 78the :ref:`mcu-link-onboard-debug-probe`, :ref:`lpc-link2-onboard-debug-probe` 79and :ref:`opensda-onboard-debug-probe`. Each of these probes is implemented 80as a secondary microcontroller present on the evaluation board. The specific 81debug probe type present on a given board can be determined based on the 82debug microcontroller SOC: 83 84- LPC55S69: :ref:`mcu-link-onboard-debug-probe` 85- LPC4322: :ref:`lpc-link2-onboard-debug-probe` 86- MK20: :ref:`opensda-onboard-debug-probe` 87 88For example, the :zephyr:board:`frdm_k64f` board has an MK20 debug microcontroller, 89so this board uses the :ref:`opensda-onboard-debug-probe`. 90 91.. _mcu-link-onboard-debug-probe: 92 93MCU-Link Onboard Debug Probe 94**************************** 95 96The MCU-Link onboard debug probe uses an LPC55S69 SOC. This probe supports 97the following firmwares: 98 99- :ref:`mcu-link-cmsis-onboard-debug-probe` (default firmware) 100- :ref:`mcu-link-jlink-onboard-debug-probe` 101 102This probe is programmed using the MCU-Link host tools, which are installed 103with the :ref:`linkserver-debug-host-tools`. NXP recommends using NXP's 104`MCUXpresso Installer`_ to install the Linkserver tools. 105 106.. _mcu-link-cmsis-onboard-debug-probe: 107 108MCU-Link CMSIS-DAP Onboard Debug Probe 109====================================== 110 111This is the default firmware installed on MCU-Link debug probes. The CMSIS-DAP 112debug probes allow debugging from any compatible toolchain, including IAR 113EWARM, Keil MDK, NXP’s MCUXpresso IDE and MCUXpresso extension for VS Code. In 114addition to debug probe functionality, the MCU-Link probes may also provide: 115 1161. SWO trace end point: this virtual device is used by MCUXpresso to retrieve 117 SWO trace data. See the MCUXpresso IDE documentation for more information. 118#. Virtual COM (VCOM) port / UART bridge connected to the target processor 119#. USB to UART, SPI and/or I2C interfaces (depending on MCU-Link 120 type/implementation) 121#. Energy measurements of the target MCU 122 123This debug probe is compatible with the following debug host tools: 124 125- :ref:`linkserver-debug-host-tools` 126 127Once the MCU-Link host tools are installed, the following steps are 128required to program the CMSIS-DAP firmware: 129 1301. Make sure the MCU-Link utility is present on your host machine. This can 131 be done by installing :ref:`linkserver-debug-host-tools`. 132 133#. Put the MCU-Link microcontroller into DFU boot mode by attaching the DFU 134 jumper then connecting to the USB debug port on the board. This jumper may 135 also be referred to as the ISP jumper, and will be connected to ``PIO0_5`` 136 on the LPC55S69. 137 138#. Run the ``program_CMSIS`` script, found in the installed MCU-Link ``scripts`` 139 folder. 140 141#. Remove the DFU jumper and power cycle the board. 142 143.. _mcu-link-jlink-onboard-debug-probe: 144 145MCU-Link JLink Onboard Debug Probe 146================================== 147 148This debug probe firmware provides a JLink compatible debug interface, 149as well as a USB-Serial adapter. It is compatible with the following debug host 150tools: 151 152- :ref:`jlink-debug-host-tools` 153 154These probes do not have JLink firmware installed by default, and must be 155updated. Once the MCU-Link host tools are installed, the following steps are 156required to program the JLink firmware: 157 1581. Make sure the MCU-Link utility is present on your host machine. This can 159 be done by installing :ref:`linkserver-debug-host-tools`. 160 161#. Put the MCU-Link microcontroller into DFU boot mode by attaching the DFU 162 jumper then connecting to the USB debug port on the board. This jumper may 163 also be referred to as the ISP jumper, and will be connected to ``PIO0_5`` 164 on the LPC55S69. 165 166#. Run the ``program_JLINK`` script, found in the installed MCU-Link ``scripts`` 167 folder. 168 169#. Remove the DFU jumper and power cycle the board. 170 171.. _lpc-link2-onboard-debug-probe: 172 173LPC-LINK2 Onboard Debug Probe 174***************************** 175 176The LPC-LINK2 onboard debug probe uses an LPC4322 SOC. This probe supports 177the following firmwares: 178 179- :ref:`lpclink2-cmsis-onboard-debug-probe` 180- :ref:`lpclink2-jlink-onboard-debug-probe` 181- :ref:`lpclink2-daplink-onboard-debug-probe` (default firmware) 182 183This probe is programmed using the LPCScrypt host tools, which are installed 184with the :ref:`linkserver-debug-host-tools`. NXP recommends using NXP's 185`MCUXpresso Installer`_ to install the Linkserver tools. 186 187.. _lpclink2-cmsis-onboard-debug-probe: 188 189LPC-LINK2 CMSIS DAP Onboard Debug Probe 190======================================= 191 192The CMSIS-DAP debug probes allow debugging from any compatible toolchain, 193including IAR EWARM, Keil MDK, as well as NXP’s MCUXpresso IDE and 194MCUXpresso extension for VS Code. 195As well as providing debug probe functionality, the LPC-Link2 probes also 196provide: 197 1981. SWO trace end point: this virtual device is used by MCUXpresso to retrieve 199 SWO trace data. See the MCUXpresso IDE documentation for more information. 2002. Virtual COM (VCOM) port / UART bridge connected to the target processor 2013. LPCSIO bridge that provides communication to I2C and SPI slave devices 202 203This debug probe firmware is compatible with the following debug host tools: 204 205- :ref:`linkserver-debug-host-tools` 206 207The probe may be updated to use CMSIS-DAP firmware with the following steps: 208 2091. Make sure the LPCScrypt utility is present on your host machine. This can 210 be done by installing :ref:`linkserver-debug-host-tools`. 211 212#. Put the LPC-Link2 microcontroller into DFU boot mode by attaching the DFU 213 jumper, then connecting to the USB debug port on the board. This 214 jumper is connected to ``P2_6`` on the LPC4322 SOC. 215 216#. Run the ``program_CMSIS`` script, found in the installed LPCScrypt ``scripts`` 217 folder. 218 219#. Remove the DFU jumper and power cycle the board. 220 221.. _lpclink2-jlink-onboard-debug-probe: 222 223LPC-Link2 J-Link Onboard Debug Probe 224==================================== 225 226.. note:: On some boards, the J-Link probe firmware will no longer power the 227 board via the USB debug port. On these boards, an alternative method 228 of powering the board must be used when this firmware is programmed. 229 230This debug probe firmware provides a JLink compatible debug interface, 231as well as a USB-Serial adapter. It is compatible with the following debug host 232tools: 233 234- :ref:`jlink-debug-host-tools` 235 236The probe may be updated to use the J-Link firmware with the following steps: 237 238.. note:: Verify the firmware supports your board by visiting `Firmware for LPCXpresso`_ 239 2401. Make sure the LPCScrypt utility is present on your host machine. This can 241 be done by installing :ref:`linkserver-debug-host-tools`. 242 243#. Put the LPC-Link2 microcontroller into DFU boot mode by attaching the DFU 244 jumper, then connecting to the USB debug port on the board. This 245 jumper is connected to ``P2_6`` on the LPC4322 SOC. 246 247#. Run the ``program_JLINK`` script, found in the installed LPCScrypt ``scripts`` 248 folder. 249 250#. Remove the DFU jumper and power cycle the board. 251 252.. _lpclink2-daplink-onboard-debug-probe: 253 254LPC-Link2 DAPLink Onboard Debug Probe 255===================================== 256 257The LPC-Link2 DAPLink firmware is the default firmware shipped on LPC-Link2 258based boards, but is not the recommended firmware. Users should update to 259the :ref:`lpclink2-cmsis-onboard-debug-probe` firmware following the 260instructions provided above. For details on programming the DAPLink firmware, 261see `NXP AN13206`_. 262 263.. _opensda-onboard-debug-probe: 264 265OpenSDA Onboard Debug Probe 266*************************** 267 268The OpenSDA onboard debug probe is based on the NXP MK20 SOC. It features 269drag and drop programming supports, and supports the following debug firmwares: 270 271- :ref:`opensda-daplink-onboard-debug-probe` (default firmware) 272- :ref:`opensda-jlink-onboard-debug-probe` 273 274.. _opensda-daplink-onboard-debug-probe: 275 276OpenSDA DAPLink Onboard Debug Probe 277=================================== 278 279This debug probe firmware is compatible with the following debug host tools: 280 281- :ref:`pyocd-debug-host-tools` 282- :ref:`openocd-debug-host-tools` 283- :ref:`linkserver-debug-host-tools` 284 285This probe is realized by programming the OpenSDA microcontroller with DAPLink 286OpenSDA firmware. NXP provides `OpenSDA DAPLink Board-Specific Firmwares`_. 287 288Install the debug host tools before you program the firmware. 289 290As with all OpenSDA debug probes, the steps for programming the firmware are: 291 2921. Put the OpenSDA microcontroller into bootloader mode by holding the reset 293 button while you power on the board. Note that "bootloader mode" in this 294 context applies to the OpenSDA microcontroller itself, not the target 295 microcontroller of your Zephyr application. 296 297#. After you power on the board, release the reset button. A USB mass storage 298 device called **BOOTLOADER** or **MAINTENANCE** will enumerate. If the 299 enumerated device is named **BOOTLOADER**, please first update the bootloader 300 to the latest revision by following the instructions for a 301 `DAPLink Bootloader Update`_. 302 303#. Copy the OpenSDA firmware binary to the USB mass storage device. 304 305#. Power cycle the board, this time without holding the reset button. You 306 should see three USB devices enumerate: a CDC device (serial port), a HID 307 device (debug port), and a mass storage device (drag-and-drop flash 308 programming). 309 310.. _opensda-jlink-onboard-debug-probe: 311 312OpenSDA J-Link Onboard Debug Probe 313================================== 314 315This debug probe is compatible with the following debug host tools: 316 317- :ref:`jlink-debug-host-tools` 318 319This probe is realized by programming the OpenSDA microcontroller with J-Link 320OpenSDA firmware. Segger provides `OpenSDA J-Link Generic Firmwares`_ and 321`OpenSDA J-Link Board-Specific Firmwares`_, where the latter is generally 322recommended when available. Board-specific firmwares are required for i.MX RT 323boards to support their external flash memories, whereas generic firmwares are 324compatible with all Kinetis boards. 325 326Install the debug host tools before you program the firmware. 327 328As with all OpenSDA debug probes, the steps for programming the firmware are: 329 3301. Put the OpenSDA microcontroller into bootloader mode by holding the reset 331 button while you plug a USB into the board's USB debug port. Note that 332 "bootloader mode" in this context applies to the OpenSDA microcontroller 333 itself, not the target microcontroller of your Zephyr application. 334 335#. After you power on the board, release the reset button. A USB mass storage 336 device called **BOOTLOADER** or **MAINTENANCE** will enumerate. If the 337 enumerated device is named **BOOTLOADER**, please first update the bootloader 338 to the latest revision by following the instructions for a 339 `DAPLink Bootloader Update`_. 340 341#. Copy the OpenSDA firmware binary to the USB mass storage device. 342 343#. Power cycle the board, this time without holding the reset button. You 344 should see two USB devices enumerate: a CDC device (serial port) and a 345 vendor-specific device (debug port). 346 347.. _jlink-external-debug-probe: 348 349J-Link External Debug Probe 350*************************** 351 352`Segger J-Link`_ is a family of external debug probes, including J-Link EDU, 353J-Link PLUS, J-Link ULTRA+, and J-Link PRO, that support a large number of 354devices from different hardware architectures and vendors. 355 356This debug probe is compatible with the following debug host tools: 357 358- :ref:`jlink-debug-host-tools` 359- :ref:`openocd-debug-host-tools` 360 361Install the debug host tools before you program the firmware. 362 363.. _stlink-v21-onboard-debug-probe: 364 365ST-LINK/V2-1 Onboard Debug Probe 366******************************** 367 368ST-LINK/V2-1 is a serial and debug adapter built into all Nucleo and Discovery 369boards. It provides a bridge between your computer (or other USB host) and the 370embedded target processor, which can be used for debugging, flash programming, 371and serial communication, all over a simple USB cable. 372 373It is compatible with the following host debug tools: 374 375- :ref:`openocd-debug-host-tools` 376- :ref:`jlink-debug-host-tools` 377- :ref:`stm32cubeclt-host-tools` 378 379For some STM32 based boards, it is also compatible with: 380 381- :ref:`pyocd-debug-host-tools` 382 383While it works out of the box with OpenOCD, it requires some flashing 384to work with J-Link. To do this, SEGGER offers a firmware upgrading the 385ST-LINK/V2-1 on board on the Nucleo and Discovery boards. This firmware makes 386the ST-LINK/V2-1 compatible with J-LinkOB, allowing users to take advantage of 387most J-Link features like the ultra fast flash download and debugging speed or 388the free-to-use GDBServer. 389 390More information about upgrading ST-LINK/V2-1 to JLink or restore ST-Link/V2-1 391firmware please visit: `Segger over ST-Link`_ 392 393Flash and debug with ST-Link 394============================ 395 396.. tabs:: 397 398 .. tab:: Using OpenOCD 399 400 OpenOCD is available by default on ST-Link and configured as the default flash 401 and debug tool. Flash and debug can be done as follows: 402 403 .. zephyr-app-commands:: 404 :zephyr-app: samples/hello_world 405 :goals: flash 406 407 .. zephyr-app-commands:: 408 :zephyr-app: samples/hello_world 409 :goals: debug 410 411 .. tab:: _`Using Segger J-Link` 412 413 Once STLink is flashed with SEGGER FW and J-Link GDB server is installed on your 414 host computer, you can flash and debug as follows: 415 416 Use CMake with ``-DBOARD_FLASH_RUNNER=jlink`` to change the default OpenOCD 417 runner to J-Link. Alternatively, you might add the following line to your 418 application ``CMakeList.txt`` file. 419 420 .. code-block:: cmake 421 422 set(BOARD_FLASH_RUNNER jlink) 423 424 If you use West (Zephyr's meta-tool) you can modify the default runner using 425 the ``--runner`` (or ``-r``) option. 426 427 .. code-block:: console 428 429 west flash --runner jlink 430 431 To attach a debugger to your board and open up a debug console with ``jlink``. 432 433 .. code-block:: console 434 435 west debug --runner jlink 436 437 For more information about West and available options, see :ref:`west`. 438 439 If you configured your Zephyr application to use `Segger RTT`_ console instead, 440 open telnet: 441 442 .. code-block:: console 443 444 $ telnet localhost 19021 445 Trying ::1... 446 Trying 127.0.0.1... 447 Connected to localhost. 448 Escape character is '^]'. 449 SEGGER J-Link V6.30f - Real time terminal output 450 J-Link STLink V21 compiled Jun 26 2017 10:35:16 V1.0, SN=773895351 451 Process: JLinkGDBServerCLExe 452 Zephyr Shell, Zephyr version: 1.12.99 453 Type 'help' for a list of available commands 454 shell> 455 456 If you get no RTT output you might need to disable other consoles which conflict 457 with the RTT one if they are enabled by default in the particular sample or 458 application you are running, such as disable UART_CONSOLE in menuconfig 459 460.. _stlink-adapter-firmware-update: 461 462Updating or restoring ST-Link firmware 463====================================== 464 465ST-Link firmware can be updated using `STM32CubeProgrammer Tool`_. 466It is usually useful when facing flashing issues, for instance when using 467twister's device-testing option. 468 469Once installed, you can update attached board ST-Link firmware with the 470following command 471 472 .. code-block:: console 473 474 s java -jar ~/STMicroelectronics/STM32Cube/STM32CubeProgrammer/Drivers/FirmwareUpgrade/STLinkUpgrade.jar -sn <board_uid> 475 476Where board_uid can be obtained using twister's generate-hardware-map 477option. For more information about twister and available options, see 478:ref:`twister_script`. 479 480OpenOCD Deprecates HLA ST-Link Interface 481======================================== 482 483OpenOCD has deprecated the legacy HLA interface used by ST-Link firmware in favor to the 484generic DAP interface in January 2024 (see `OpenOCD deprecates ST-Link HLA Interface`_) 485in favor of the generic DAP interface. DAP interface is supported by ST-Link firmware 486since 2015 (from version v2j24). 487 488Since OpenOCD deprecation, one using a recent OpenOCD tool (after release tag v0.12.0) 489may experience communication issues when the ST-Link adapter embeds a firmware prior version 490v2j24. In such case, it is recommended to update the ST-Link firmware (refer to 491`ST-LINK firmware update <#_stlink-adapter-firmware-update>`_). 492If it is not possible to update the firmware, one may still use the old HLA interface 493by modifying its OpenOCD configuration script replacing (if applicable) the 2 below lines: 494 495 .. code-block:: 496 497 source [find interface/stlink-dap.cfg] 498 transport select dapdirect_swd 499 500with the 2 following lines: 501 502 .. code-block:: 503 504 source [find interface/stlink-hla.cfg] 505 transport select hla_swd 506 507.. _nxp-s32-debug-probe: 508 509NXP S32 Debug Probe 510******************* 511 512`NXP S32 Debug Probe`_ enables NXP S32 target system debugging via a standard 513debug port while connected to a developer's workstation via USB or remotely via 514Ethernet. 515 516NXP S32 Debug Probe is designed to work in conjunction with NXP S32 Design Studio 517(S32DS) and NXP Automotive microcontrollers and processors. Install the debug 518host tools as in indicated in :ref:`nxp-s32-debug-host-tools` before you program 519the firmware. 520 521.. _black-magic-probe: 522 523Black Magic Probe 524***************** 525 526The Black Magic Probe is an open-source hardware for debugging that is designed 527to be used with `Black Magic Debug`_ firmware. 528The firmware incorporates GDB Server so that you can connect directly from ``gdb`` 529to the target device. 530 531Some of the STM32F103-based boards can run the `Black Magic Debug`_ firmware. 532See `Black Magic Debug supported hardware`_. 533 534.. _LPCScrypt: 535 https://www.nxp.com/lpcscrypt 536 537.. _Firmware for LPCXpresso: 538 https://www.segger.com/products/debug-probes/j-link/models/other-j-links/lpcxpresso-on-board/ 539 540.. _OpenSDA DAPLink Board-Specific Firmwares: 541 https://www.nxp.com/opensda 542 543.. _OpenSDA J-Link Generic Firmwares: 544 https://www.segger.com/downloads/jlink/#JLinkOpenSDAGenericFirmwares 545 546.. _OpenSDA J-Link Board-Specific Firmwares: 547 https://www.segger.com/downloads/jlink/#JLinkOpenSDABoardSpecificFirmwares 548 549.. _Segger J-Link: 550 https://www.segger.com/products/debug-probes/j-link/ 551 552.. _Segger over ST-Link: 553 https://www.segger.com/products/debug-probes/j-link/models/other-j-links/st-link-on-board/ 554 555.. _Segger RTT: 556 https://www.segger.com/jlink-rtt.html 557 558.. _STM32CubeProgrammer Tool: 559 https://www.st.com/en/development-tools/stm32cubeprog.html 560 561.. _OpenOCD deprecates ST-Link HLA Interface: 562 https://sourceforge.net/p/openocd/code/ci/34ec5536c0ba3315bc5a841244bbf70141ccfbb4 563 564.. _MCUXpresso Installer: 565 https://www.nxp.com/lgfiles/updates/mcuxpresso/MCUXpressoInstaller.exe 566 567.. _NXP S32 Debug Probe: 568 https://www.nxp.com/design/software/automotive-software-and-tools/s32-debug-probe:S32-DP 569 570.. _NXP AN13206: 571 https://www.nxp.com/docs/en/application-note/AN13206.pdf 572 573.. _DAPLink Bootloader Update: 574 https://os.mbed.com/blog/entry/DAPLink-bootloader-update/ 575 576.. _Black Magic Debug: 577 https://black-magic.org/index.html 578 579.. _Black Magic Debug supported hardware: 580 https://black-magic.org/hardware.html 581
