| .. _debug-probes: |
| |
| Debug Probes |
| ############ |
| |
| A *debug probe* is special hardware which allows you to control execution of a |
| Zephyr application running on a separate board. Debug probes usually allow |
| reading and writing registers and memory, and support breakpoint debugging of |
| the Zephyr application on your host workstation using tools like GDB. They may |
| also support other debug software and more advanced features such as |
| :ref:`tracing program execution <tracing>`. For details on the related host |
| software supported by Zephyr, see :ref:`flash-debug-host-tools`. |
| |
| Debug probes are usually connected to your host workstation via USB; they |
| are sometimes also accessible via an IP network or other means. They usually |
| connect to the device running Zephyr using the JTAG or SWD protocols. Debug |
| probes are either separate hardware devices or circuitry integrated into the same |
| board which runs Zephyr. |
| |
| Many supported boards in Zephyr include a second microcontroller that serves as |
| an onboard debug probe, usb-to-serial adapter, and sometimes a drag-and-drop |
| flash programmer. This eliminates the need to purchase an external debug probe |
| and provides a variety of debug host tool options. |
| |
| Several hardware vendors have their own branded onboard debug probe |
| implementations: NXP boards may use |
| `OpenSDA <#opensda-onboard-debug-probe>`_, |
| `LPC-Link2 <#lpc-link2-onboard-debug-probe>`_, or |
| `MCU-Link <#mcu-link-onboard-debug-probe>`_, probes depending on |
| the microcontroller the debug probe firmware runs on. |
| ST boards have the `ST-LINK probe <#stlink-v21-onboard-debug-probe>`_. Each |
| onboard debug probe microcontroller can support one or more types of firmware |
| that communicate with their respective debug host tools. For example, an |
| OpenSDA microcontroller can be programmed with DAPLink firmware to communicate |
| with pyOCD or OpenOCD debug host tools, or with J-Link firmware to communicate |
| with J-Link debug host tools. |
| |
| |
| +------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ |
| || *Debug Probes & Host Tools* | Host Tools | |
| +| *Compatibility Chart* +--------------------+--------------------+---------------------+--------------------+--------------------+------------------------+ |
| | | **J-Link Debug** | **OpenOCD** | **pyOCD** | **NXP S32DS** | **NXP LinkServer** | **ST-LINK GDB Server** | |
| +----------------+-------------------------+--------------------+--------------------+---------------------+--------------------+--------------------+------------------------+ |
| | | **J-Link External** | ✓ | ✓ | | | | | |
| | +-------------------------+--------------------+--------------------+---------------------+--------------------+--------------------+------------------------+ |
| | | **LPC-Link2 CMSIS-DAP** | | | | | ✓ | | |
| | +-------------------------+--------------------+--------------------+---------------------+--------------------+--------------------+------------------------+ |
| | | **LPC-Link2 J-Link** | ✓ | | | | | | |
| | +-------------------------+--------------------+--------------------+---------------------+--------------------+--------------------+------------------------+ |
| | | **MCU-Link CMSIS-DAP** | | | | | ✓ | | |
| | Debug Probes +-------------------------+--------------------+--------------------+---------------------+--------------------+--------------------+------------------------+ |
| | | **MCU-Link J-Link** | ✓ | | | | | | |
| | +-------------------------+--------------------+--------------------+---------------------+--------------------+--------------------+------------------------+ |
| | | **NXP S32 Debug Probe** | | | | ✓ | | | |
| | +-------------------------+--------------------+--------------------+---------------------+--------------------+--------------------+------------------------+ |
| | | **OpenSDA DAPLink** | | ✓ | ✓ | | ✓ | | |
| | +-------------------------+--------------------+--------------------+---------------------+--------------------+--------------------+------------------------+ |
| | | **OpenSDA J-Link** | ✓ | | | | | | |
| | +-------------------------+--------------------+--------------------+---------------------+--------------------+--------------------+------------------------+ |
| | | **ST-LINK/V2-1** | ✓ | ✓ | *some STM32 boards* | | | ✓ | |
| +----------------+-------------------------+--------------------+--------------------+---------------------+--------------------+--------------------+------------------------+ |
| |
| |
| Some supported boards in Zephyr do not include an onboard debug probe and |
| therefore require an external debug probe. In addition, boards that do include |
| an onboard debug probe often also have an SWD or JTAG header to enable the use |
| of an external debug probe instead. One reason this may be useful is that the |
| onboard debug probe may have limitations, such as lack of support for advanced |
| debuggers or high-speed tracing. You may need to adjust jumpers to prevent the |
| onboard debug probe from interfering with the external debug probe. |
| |
| .. _nxp-onboard-debug-probes: |
| |
| NXP Onboard Debug Probes |
| ************************ |
| |
| NXP boards may have one of several onboard debug probes. These probes include |
| the :ref:`mcu-link-onboard-debug-probe`, :ref:`lpc-link2-onboard-debug-probe` |
| and :ref:`opensda-onboard-debug-probe`. Each of these probes is implemented |
| as a secondary microcontroller present on the evaluation board. The specific |
| debug probe type present on a given board can be determined based on the |
| debug microcontroller SOC: |
| |
| - LPC55S69: :ref:`mcu-link-onboard-debug-probe` |
| - LPC4322: :ref:`lpc-link2-onboard-debug-probe` |
| - MK20: :ref:`opensda-onboard-debug-probe` |
| |
| For example, the :zephyr:board:`frdm_k64f` board has an MK20 debug microcontroller, |
| so this board uses the :ref:`opensda-onboard-debug-probe`. |
| |
| .. _mcu-link-onboard-debug-probe: |
| |
| MCU-Link Onboard Debug Probe |
| **************************** |
| |
| The MCU-Link onboard debug probe uses an LPC55S69 SOC. This probe supports |
| the following firmwares: |
| |
| - :ref:`mcu-link-cmsis-onboard-debug-probe` (default firmware) |
| - :ref:`mcu-link-jlink-onboard-debug-probe` |
| |
| This probe is programmed using the MCU-Link host tools, which are installed |
| with the :ref:`linkserver-debug-host-tools`. NXP recommends using NXP's |
| `MCUXpresso Installer`_ to install the Linkserver tools. |
| |
| .. _mcu-link-cmsis-onboard-debug-probe: |
| |
| MCU-Link CMSIS-DAP Onboard Debug Probe |
| ====================================== |
| |
| This is the default firmware installed on MCU-Link debug probes. The CMSIS-DAP |
| debug probes allow debugging from any compatible toolchain, including IAR |
| EWARM, Keil MDK, NXP’s MCUXpresso IDE and MCUXpresso extension for VS Code. In |
| addition to debug probe functionality, the MCU-Link probes may also provide: |
| |
| 1. SWO trace end point: this virtual device is used by MCUXpresso to retrieve |
| SWO trace data. See the MCUXpresso IDE documentation for more information. |
| #. Virtual COM (VCOM) port / UART bridge connected to the target processor |
| #. USB to UART, SPI and/or I2C interfaces (depending on MCU-Link |
| type/implementation) |
| #. Energy measurements of the target MCU |
| |
| This debug probe is compatible with the following debug host tools: |
| |
| - :ref:`linkserver-debug-host-tools` |
| |
| Once the MCU-Link host tools are installed, the following steps are |
| required to program the CMSIS-DAP firmware: |
| |
| 1. Make sure the MCU-Link utility is present on your host machine. This can |
| be done by installing :ref:`linkserver-debug-host-tools`. |
| |
| #. Put the MCU-Link microcontroller into DFU boot mode by attaching the DFU |
| jumper then connecting to the USB debug port on the board. This jumper may |
| also be referred to as the ISP jumper, and will be connected to ``PIO0_5`` |
| on the LPC55S69. |
| |
| #. Run the ``program_CMSIS`` script, found in the installed MCU-Link ``scripts`` |
| folder. |
| |
| #. Remove the DFU jumper and power cycle the board. |
| |
| .. _mcu-link-jlink-onboard-debug-probe: |
| |
| MCU-Link JLink Onboard Debug Probe |
| ================================== |
| |
| This debug probe firmware provides a JLink compatible debug interface, |
| as well as a USB-Serial adapter. It is compatible with the following debug host |
| tools: |
| |
| - :ref:`jlink-debug-host-tools` |
| |
| These probes do not have JLink firmware installed by default, and must be |
| updated. Once the MCU-Link host tools are installed, the following steps are |
| required to program the JLink firmware: |
| |
| 1. Make sure the MCU-Link utility is present on your host machine. This can |
| be done by installing :ref:`linkserver-debug-host-tools`. |
| |
| #. Put the MCU-Link microcontroller into DFU boot mode by attaching the DFU |
| jumper then connecting to the USB debug port on the board. This jumper may |
| also be referred to as the ISP jumper, and will be connected to ``PIO0_5`` |
| on the LPC55S69. |
| |
| #. Run the ``program_JLINK`` script, found in the installed MCU-Link ``scripts`` |
| folder. |
| |
| #. Remove the DFU jumper and power cycle the board. |
| |
| .. _lpc-link2-onboard-debug-probe: |
| |
| LPC-LINK2 Onboard Debug Probe |
| ***************************** |
| |
| The LPC-LINK2 onboard debug probe uses an LPC4322 SOC. This probe supports |
| the following firmwares: |
| |
| - :ref:`lpclink2-cmsis-onboard-debug-probe` |
| - :ref:`lpclink2-jlink-onboard-debug-probe` |
| - :ref:`lpclink2-daplink-onboard-debug-probe` (default firmware) |
| |
| This probe is programmed using the LPCScrypt host tools, which are installed |
| with the :ref:`linkserver-debug-host-tools`. NXP recommends using NXP's |
| `MCUXpresso Installer`_ to install the Linkserver tools. |
| |
| .. _lpclink2-cmsis-onboard-debug-probe: |
| |
| LPC-LINK2 CMSIS DAP Onboard Debug Probe |
| ======================================= |
| |
| The CMSIS-DAP debug probes allow debugging from any compatible toolchain, |
| including IAR EWARM, Keil MDK, as well as NXP’s MCUXpresso IDE and |
| MCUXpresso extension for VS Code. |
| As well as providing debug probe functionality, the LPC-Link2 probes also |
| provide: |
| |
| 1. SWO trace end point: this virtual device is used by MCUXpresso to retrieve |
| SWO trace data. See the MCUXpresso IDE documentation for more information. |
| 2. Virtual COM (VCOM) port / UART bridge connected to the target processor |
| 3. LPCSIO bridge that provides communication to I2C and SPI slave devices |
| |
| This debug probe firmware is compatible with the following debug host tools: |
| |
| - :ref:`linkserver-debug-host-tools` |
| |
| The probe may be updated to use CMSIS-DAP firmware with the following steps: |
| |
| 1. Make sure the LPCScrypt utility is present on your host machine. This can |
| be done by installing :ref:`linkserver-debug-host-tools`. |
| |
| #. Put the LPC-Link2 microcontroller into DFU boot mode by attaching the DFU |
| jumper, then connecting to the USB debug port on the board. This |
| jumper is connected to ``P2_6`` on the LPC4322 SOC. |
| |
| #. Run the ``program_CMSIS`` script, found in the installed LPCScrypt ``scripts`` |
| folder. |
| |
| #. Remove the DFU jumper and power cycle the board. |
| |
| .. _lpclink2-jlink-onboard-debug-probe: |
| |
| LPC-Link2 J-Link Onboard Debug Probe |
| ==================================== |
| |
| .. note:: On some boards, the J-Link probe firmware will no longer power the |
| board via the USB debug port. On these boards, an alternative method |
| of powering the board must be used when this firmware is programmed. |
| |
| This debug probe firmware provides a JLink compatible debug interface, |
| as well as a USB-Serial adapter. It is compatible with the following debug host |
| tools: |
| |
| - :ref:`jlink-debug-host-tools` |
| |
| The probe may be updated to use the J-Link firmware with the following steps: |
| |
| .. note:: Verify the firmware supports your board by visiting `Firmware for LPCXpresso`_ |
| |
| 1. Make sure the LPCScrypt utility is present on your host machine. This can |
| be done by installing :ref:`linkserver-debug-host-tools`. |
| |
| #. Put the LPC-Link2 microcontroller into DFU boot mode by attaching the DFU |
| jumper, then connecting to the USB debug port on the board. This |
| jumper is connected to ``P2_6`` on the LPC4322 SOC. |
| |
| #. Run the ``program_JLINK`` script, found in the installed LPCScrypt ``scripts`` |
| folder. |
| |
| #. Remove the DFU jumper and power cycle the board. |
| |
| .. _lpclink2-daplink-onboard-debug-probe: |
| |
| LPC-Link2 DAPLink Onboard Debug Probe |
| ===================================== |
| |
| The LPC-Link2 DAPLink firmware is the default firmware shipped on LPC-Link2 |
| based boards, but is not the recommended firmware. Users should update to |
| the :ref:`lpclink2-cmsis-onboard-debug-probe` firmware following the |
| instructions provided above. For details on programming the DAPLink firmware, |
| see `NXP AN13206`_. |
| |
| .. _opensda-onboard-debug-probe: |
| |
| OpenSDA Onboard Debug Probe |
| *************************** |
| |
| The OpenSDA onboard debug probe is based on the NXP MK20 SOC. It features |
| drag and drop programming supports, and supports the following debug firmwares: |
| |
| - :ref:`opensda-daplink-onboard-debug-probe` (default firmware) |
| - :ref:`opensda-jlink-onboard-debug-probe` |
| |
| .. _opensda-daplink-onboard-debug-probe: |
| |
| OpenSDA DAPLink Onboard Debug Probe |
| =================================== |
| |
| This debug probe firmware is compatible with the following debug host tools: |
| |
| - :ref:`pyocd-debug-host-tools` |
| - :ref:`openocd-debug-host-tools` |
| - :ref:`linkserver-debug-host-tools` |
| |
| This probe is realized by programming the OpenSDA microcontroller with DAPLink |
| OpenSDA firmware. NXP provides `OpenSDA DAPLink Board-Specific Firmwares`_. |
| |
| Install the debug host tools before you program the firmware. |
| |
| As with all OpenSDA debug probes, the steps for programming the firmware are: |
| |
| 1. Put the OpenSDA microcontroller into bootloader mode by holding the reset |
| button while you power on the board. Note that "bootloader mode" in this |
| context applies to the OpenSDA microcontroller itself, not the target |
| microcontroller of your Zephyr application. |
| |
| #. After you power on the board, release the reset button. A USB mass storage |
| device called **BOOTLOADER** or **MAINTENANCE** will enumerate. If the |
| enumerated device is named **BOOTLOADER**, please first update the bootloader |
| to the latest revision by following the instructions for a |
| `DAPLink Bootloader Update`_. |
| |
| #. Copy the OpenSDA firmware binary to the USB mass storage device. |
| |
| #. Power cycle the board, this time without holding the reset button. You |
| should see three USB devices enumerate: a CDC device (serial port), a HID |
| device (debug port), and a mass storage device (drag-and-drop flash |
| programming). |
| |
| .. _opensda-jlink-onboard-debug-probe: |
| |
| OpenSDA J-Link Onboard Debug Probe |
| ================================== |
| |
| This debug probe is compatible with the following debug host tools: |
| |
| - :ref:`jlink-debug-host-tools` |
| |
| This probe is realized by programming the OpenSDA microcontroller with J-Link |
| OpenSDA firmware. Segger provides `OpenSDA J-Link Generic Firmwares`_ and |
| `OpenSDA J-Link Board-Specific Firmwares`_, where the latter is generally |
| recommended when available. Board-specific firmwares are required for i.MX RT |
| boards to support their external flash memories, whereas generic firmwares are |
| compatible with all Kinetis boards. |
| |
| Install the debug host tools before you program the firmware. |
| |
| As with all OpenSDA debug probes, the steps for programming the firmware are: |
| |
| 1. Put the OpenSDA microcontroller into bootloader mode by holding the reset |
| button while you plug a USB into the board's USB debug port. Note that |
| "bootloader mode" in this context applies to the OpenSDA microcontroller |
| itself, not the target microcontroller of your Zephyr application. |
| |
| #. After you power on the board, release the reset button. A USB mass storage |
| device called **BOOTLOADER** or **MAINTENANCE** will enumerate. If the |
| enumerated device is named **BOOTLOADER**, please first update the bootloader |
| to the latest revision by following the instructions for a |
| `DAPLink Bootloader Update`_. |
| |
| #. Copy the OpenSDA firmware binary to the USB mass storage device. |
| |
| #. Power cycle the board, this time without holding the reset button. You |
| should see two USB devices enumerate: a CDC device (serial port) and a |
| vendor-specific device (debug port). |
| |
| .. _jlink-external-debug-probe: |
| |
| J-Link External Debug Probe |
| *************************** |
| |
| `Segger J-Link`_ is a family of external debug probes, including J-Link EDU, |
| J-Link PLUS, J-Link ULTRA+, and J-Link PRO, that support a large number of |
| devices from different hardware architectures and vendors. |
| |
| This debug probe is compatible with the following debug host tools: |
| |
| - :ref:`jlink-debug-host-tools` |
| - :ref:`openocd-debug-host-tools` |
| |
| Install the debug host tools before you program the firmware. |
| |
| .. _stlink-v21-onboard-debug-probe: |
| |
| ST-LINK/V2-1 Onboard Debug Probe |
| ******************************** |
| |
| ST-LINK/V2-1 is a serial and debug adapter built into all Nucleo and Discovery |
| boards. It provides a bridge between your computer (or other USB host) and the |
| embedded target processor, which can be used for debugging, flash programming, |
| and serial communication, all over a simple USB cable. |
| |
| It is compatible with the following host debug tools: |
| |
| - :ref:`openocd-debug-host-tools` |
| - :ref:`jlink-debug-host-tools` |
| - :ref:`stm32cubeclt-host-tools` |
| |
| For some STM32 based boards, it is also compatible with: |
| |
| - :ref:`pyocd-debug-host-tools` |
| |
| While it works out of the box with OpenOCD, it requires some flashing |
| to work with J-Link. To do this, SEGGER offers a firmware upgrading the |
| ST-LINK/V2-1 on board on the Nucleo and Discovery boards. This firmware makes |
| the ST-LINK/V2-1 compatible with J-LinkOB, allowing users to take advantage of |
| most J-Link features like the ultra fast flash download and debugging speed or |
| the free-to-use GDBServer. |
| |
| More information about upgrading ST-LINK/V2-1 to JLink or restore ST-Link/V2-1 |
| firmware please visit: `Segger over ST-Link`_ |
| |
| Flash and debug with ST-Link |
| ============================ |
| |
| .. tabs:: |
| |
| .. tab:: Using OpenOCD |
| |
| OpenOCD is available by default on ST-Link and configured as the default flash |
| and debug tool. Flash and debug can be done as follows: |
| |
| .. zephyr-app-commands:: |
| :zephyr-app: samples/hello_world |
| :goals: flash |
| |
| .. zephyr-app-commands:: |
| :zephyr-app: samples/hello_world |
| :goals: debug |
| |
| .. tab:: _`Using Segger J-Link` |
| |
| Once STLink is flashed with SEGGER FW and J-Link GDB server is installed on your |
| host computer, you can flash and debug as follows: |
| |
| Use CMake with ``-DBOARD_FLASH_RUNNER=jlink`` to change the default OpenOCD |
| runner to J-Link. Alternatively, you might add the following line to your |
| application ``CMakeList.txt`` file. |
| |
| .. code-block:: cmake |
| |
| set(BOARD_FLASH_RUNNER jlink) |
| |
| If you use West (Zephyr's meta-tool) you can modify the default runner using |
| the ``--runner`` (or ``-r``) option. |
| |
| .. code-block:: console |
| |
| west flash --runner jlink |
| |
| To attach a debugger to your board and open up a debug console with ``jlink``. |
| |
| .. code-block:: console |
| |
| west debug --runner jlink |
| |
| For more information about West and available options, see :ref:`west`. |
| |
| If you configured your Zephyr application to use `Segger RTT`_ console instead, |
| open telnet: |
| |
| .. code-block:: console |
| |
| $ telnet localhost 19021 |
| Trying ::1... |
| Trying 127.0.0.1... |
| Connected to localhost. |
| Escape character is '^]'. |
| SEGGER J-Link V6.30f - Real time terminal output |
| J-Link STLink V21 compiled Jun 26 2017 10:35:16 V1.0, SN=773895351 |
| Process: JLinkGDBServerCLExe |
| Zephyr Shell, Zephyr version: 1.12.99 |
| Type 'help' for a list of available commands |
| shell> |
| |
| If you get no RTT output you might need to disable other consoles which conflict |
| with the RTT one if they are enabled by default in the particular sample or |
| application you are running, such as disable UART_CONSOLE in menuconfig |
| |
| Updating or restoring ST-Link firmware |
| ====================================== |
| |
| ST-Link firmware can be updated using `STM32CubeProgrammer Tool`_. |
| It is usually useful when facing flashing issues, for instance when using |
| twister's device-testing option. |
| |
| Once installed, you can update attached board ST-Link firmware with the |
| following command |
| |
| .. code-block:: console |
| |
| s java -jar ~/STMicroelectronics/STM32Cube/STM32CubeProgrammer/Drivers/FirmwareUpgrade/STLinkUpgrade.jar -sn <board_uid> |
| |
| Where board_uid can be obtained using twister's generate-hardware-map |
| option. For more information about twister and available options, see |
| :ref:`twister_script`. |
| |
| .. _nxp-s32-debug-probe: |
| |
| NXP S32 Debug Probe |
| ******************* |
| |
| `NXP S32 Debug Probe`_ enables NXP S32 target system debugging via a standard |
| debug port while connected to a developer's workstation via USB or remotely via |
| Ethernet. |
| |
| NXP S32 Debug Probe is designed to work in conjunction with NXP S32 Design Studio |
| (S32DS) and NXP Automotive microcontrollers and processors. Install the debug |
| host tools as in indicated in :ref:`nxp-s32-debug-host-tools` before you program |
| the firmware. |
| |
| .. _black-magic-probe: |
| |
| Black Magic Probe |
| ***************** |
| |
| The Black Magic Probe is an open-source hardware for debugging that is designed |
| to be used with `Black Magic Debug`_ firmware. |
| The firmware incorporates GDB Server so that you can connect directly from ``gdb`` |
| to the target device. |
| |
| Some of the STM32F103-based boards can run the `Black Magic Debug`_ firmware. |
| See `Black Magic Debug supported hardware`_. |
| |
| .. _LPCScrypt: |
| https://www.nxp.com/lpcscrypt |
| |
| .. _Firmware for LPCXpresso: |
| https://www.segger.com/products/debug-probes/j-link/models/other-j-links/lpcxpresso-on-board/ |
| |
| .. _OpenSDA DAPLink Board-Specific Firmwares: |
| https://www.nxp.com/opensda |
| |
| .. _OpenSDA J-Link Generic Firmwares: |
| https://www.segger.com/downloads/jlink/#JLinkOpenSDAGenericFirmwares |
| |
| .. _OpenSDA J-Link Board-Specific Firmwares: |
| https://www.segger.com/downloads/jlink/#JLinkOpenSDABoardSpecificFirmwares |
| |
| .. _Segger J-Link: |
| https://www.segger.com/products/debug-probes/j-link/ |
| |
| .. _Segger over ST-Link: |
| https://www.segger.com/products/debug-probes/j-link/models/other-j-links/st-link-on-board/ |
| |
| .. _Segger RTT: |
| https://www.segger.com/jlink-rtt.html |
| |
| .. _STM32CubeProgrammer Tool: |
| https://www.st.com/en/development-tools/stm32cubeprog.html |
| |
| .. _MCUXpresso Installer: |
| https://www.nxp.com/lgfiles/updates/mcuxpresso/MCUXpressoInstaller.exe |
| |
| .. _NXP S32 Debug Probe: |
| https://www.nxp.com/design/software/automotive-software-and-tools/s32-debug-probe:S32-DP |
| |
| .. _NXP AN13206: |
| https://www.nxp.com/docs/en/application-note/AN13206.pdf |
| |
| .. _DAPLink Bootloader Update: |
| https://os.mbed.com/blog/entry/DAPLink-bootloader-update/ |
| |
| .. _Black Magic Debug: |
| https://black-magic.org/index.html |
| |
| .. _Black Magic Debug supported hardware: |
| https://black-magic.org/hardware.html |
