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** |
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
378For some STM32 based boards, it is also compatible with:
379
380- :ref:`pyocd-debug-host-tools`
381
382While it works out of the box with OpenOCD, it requires some flashing
383to work with J-Link. To do this, SEGGER offers a firmware upgrading the
384ST-LINK/V2-1 on board on the Nucleo and Discovery boards. This firmware makes
385the ST-LINK/V2-1 compatible with J-LinkOB, allowing users to take advantage of
386most J-Link features like the ultra fast flash download and debugging speed or
387the free-to-use GDBServer.
388
389More information about upgrading ST-LINK/V2-1 to JLink or restore ST-Link/V2-1
390firmware please visit: `Segger over ST-Link`_
391
392Flash and debug with ST-Link
393============================
394
395.. tabs::
396
397    .. tab:: Using OpenOCD
398
399        OpenOCD is available by default on ST-Link and configured as the default flash
400        and debug tool. Flash and debug can be done as follows:
401
402          .. zephyr-app-commands::
403             :zephyr-app: samples/hello_world
404             :goals: flash
405
406          .. zephyr-app-commands::
407             :zephyr-app: samples/hello_world
408             :goals: debug
409
410    .. tab:: _`Using Segger J-Link`
411
412        Once STLink is flashed with SEGGER FW and J-Link GDB server is installed on your
413        host computer, you can flash and debug as follows:
414
415        Use CMake with ``-DBOARD_FLASH_RUNNER=jlink`` to change the default OpenOCD
416        runner to J-Link. Alternatively, you might add the following line to your
417        application ``CMakeList.txt`` file.
418
419          .. code-block:: cmake
420
421             set(BOARD_FLASH_RUNNER jlink)
422
423        If you use West (Zephyr's meta-tool) you can modify the default runner using
424        the ``--runner`` (or ``-r``) option.
425
426          .. code-block:: console
427
428             west flash --runner jlink
429
430        To attach a debugger to your board and open up a debug console with ``jlink``.
431
432          .. code-block:: console
433
434             west debug --runner jlink
435
436        For more information about West and available options, see :ref:`west`.
437
438        If you configured your Zephyr application to use `Segger RTT`_ console instead,
439        open telnet:
440
441          .. code-block:: console
442
443             $ telnet localhost 19021
444             Trying ::1...
445             Trying 127.0.0.1...
446             Connected to localhost.
447             Escape character is '^]'.
448             SEGGER J-Link V6.30f - Real time terminal output
449             J-Link STLink V21 compiled Jun 26 2017 10:35:16 V1.0, SN=773895351
450             Process: JLinkGDBServerCLExe
451             Zephyr Shell, Zephyr version: 1.12.99
452             Type 'help' for a list of available commands
453             shell>
454
455        If you get no RTT output you might need to disable other consoles which conflict
456        with the RTT one if they are enabled by default in the particular sample or
457        application you are running, such as disable UART_CONSOLE in menuconfig
458
459Updating or restoring ST-Link firmware
460======================================
461
462ST-Link firmware can be updated using `STM32CubeProgrammer Tool`_.
463It is usually useful when facing flashing issues, for instance when using
464twister's device-testing option.
465
466Once installed, you can update attached board ST-Link firmware with the
467following command
468
469  .. code-block:: console
470
471     s java -jar ~/STMicroelectronics/STM32Cube/STM32CubeProgrammer/Drivers/FirmwareUpgrade/STLinkUpgrade.jar -sn <board_uid>
472
473Where board_uid can be obtained using twister's generate-hardware-map
474option. For more information about twister and available options, see
475:ref:`twister_script`.
476
477.. _nxp-s32-debug-probe:
478
479NXP S32 Debug Probe
480*******************
481
482`NXP S32 Debug Probe`_ enables NXP S32 target system debugging via a standard
483debug port while connected to a developer's workstation via USB or remotely via
484Ethernet.
485
486NXP S32 Debug Probe is designed to work in conjunction with NXP S32 Design Studio
487(S32DS) and NXP Automotive microcontrollers and processors. Install the debug
488host tools as in indicated in :ref:`nxp-s32-debug-host-tools` before you program
489the firmware.
490
491.. _LPCScrypt:
492   https://www.nxp.com/lpcscrypt
493
494.. _Firmware for LPCXpresso:
495   https://www.segger.com/products/debug-probes/j-link/models/other-j-links/lpcxpresso-on-board/
496
497.. _OpenSDA DAPLink Board-Specific Firmwares:
498   https://www.nxp.com/opensda
499
500.. _OpenSDA J-Link Generic Firmwares:
501   https://www.segger.com/downloads/jlink/#JLinkOpenSDAGenericFirmwares
502
503.. _OpenSDA J-Link Board-Specific Firmwares:
504   https://www.segger.com/downloads/jlink/#JLinkOpenSDABoardSpecificFirmwares
505
506.. _Segger J-Link:
507   https://www.segger.com/products/debug-probes/j-link/
508
509.. _Segger over ST-Link:
510   https://www.segger.com/products/debug-probes/j-link/models/other-j-links/st-link-on-board/
511
512.. _Segger RTT:
513    https://www.segger.com/jlink-rtt.html
514
515.. _STM32CubeProgrammer Tool:
516    https://www.st.com/en/development-tools/stm32cubeprog.html
517
518.. _MCUXpresso Installer:
519	https://www.nxp.com/lgfiles/updates/mcuxpresso/MCUXpressoInstaller.exe
520
521.. _NXP S32 Debug Probe:
522   https://www.nxp.com/design/software/automotive-software-and-tools/s32-debug-probe:S32-DP
523
524.. _NXP AN13206:
525   https://www.nxp.com/docs/en/application-note/AN13206.pdf
526
527.. _DAPLink Bootloader Update:
528   https://os.mbed.com/blog/entry/DAPLink-bootloader-update/
529