Skip to content

Commit 641a245

Browse files
MaureenHelmMaureenHelm
committed
doc: debugging: Introduce guide covering debug probes and host tools
Zephyr boards use a wide range of debug probes and debug host tools that can often be confusing to users. Introduce a new debugging guide that documents all the different variations of debug probes and host tools in one place, including which combinations are valid. Signed-off-by: Maureen Helm <maureen.helm@nxp.com>
1 parent f46e391 commit 641a245

File tree

4 files changed

+270
-0
lines changed

4 files changed

+270
-0
lines changed

‎doc/guides/debugging/host-tools.rst‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
.. _debug-host-tools:
2+
3+
Debug Host Tools
4+
################
5+
6+
This guide describes the software tools you can run on your host workstation to
7+
debug Zephyr applications.
8+
9+
Zephyr's west tool has built-in support for all of these in its ``debug``,
10+
``debugserver``, and ``attach`` commands, provided your board hardware supports
11+
them and your Zephyr board directory's :file:`board.cmake` file declares that
12+
support properly. See :ref:`west-build-flash-debug` for more information on
13+
these commands.
14+
15+
.. _jlink-debug-host-tools:
16+
17+
J-Link Debug Host Tools
18+
***********************
19+
20+
Segger provides a suite of debug host tools for Linux, macOS, and Windows
21+
operating systems:
22+
23+
- J-Link GDB Server: GDB remote debugging
24+
- J-Link Commander: Command-line control and flash programming
25+
- RTT Viewer: RTT terminal input and output
26+
- SystemView: Real-time event visualization and recording
27+
28+
These debug host tools are compatible with the following debug probes:
29+
30+
- :ref:`lpclink2-jlink-onboard-debug-probe`
31+
- :ref:`opensda-jlink-onboard-debug-probe`
32+
- :ref:`jlink-external-debug-probe`
33+
34+
Check if your SoC is listed in `J-Link Supported Devices`_.
35+
36+
Download and install the `J-Link Software and Documentation Pack`_ to get the
37+
J-Link GDB Server and Commander, and to install the associated USB device
38+
drivers. RTT Viewer and SystemView can be downloaded separately, but are not
39+
required.
40+
41+
Note that the J-Link GDB server does not yet support Zephyr RTOS-awareness.
42+
43+
.. _openocd-debug-host-tools:
44+
45+
OpenOCD Debug Host Tools
46+
************************
47+
48+
OpenOCD is a community open source project that provides GDB remote debugging
49+
and flash programming support for a wide range of SoCs. A fork that adds Zephyr
50+
RTOS-awareness is included in the Zephyr SDK; otherwise see `Getting OpenOCD`_
51+
for options to download OpenOCD from official repositories.
52+
53+
These debug host tools are compatible with the following debug probes:
54+
55+
- :ref:`opensda-daplink-onboard-debug-probe`
56+
- :ref:`jlink-external-debug-probe`
57+
58+
Check if your SoC is listed in `OpenOCD Supported Devices`_.
59+
60+
.. _pyocd-debug-host-tools:
61+
62+
pyOCD Debug Host Tools
63+
**********************
64+
65+
pyOCD is an open source project from Arm that provides GDB remote debugging and
66+
flash programming support for Arm Cortex-M SoCs. It is distributed on PyPi and
67+
installed when you complete the :ref:`gs_python_deps` step in the Getting
68+
Started Guide. pyOCD includes support for Zephyr RTOS-awareness.
69+
70+
These debug host tools are compatible with the following debug probes:
71+
72+
- :ref:`opensda-daplink-onboard-debug-probe`
73+
74+
Check if your SoC is listed in `pyOCD Supported Devices`_.
75+
76+
.. _J-Link Software and Documentation Pack:
77+
https://www.segger.com/downloads/jlink/#J-LinkSoftwareAndDocumentationPack
78+
79+
.. _J-Link Supported Devices:
80+
https://www.segger.com/downloads/supported-devices.php
81+
82+
.. _Getting OpenOCD:
83+
http://openocd.org/getting-openocd/
84+
85+
.. _OpenOCD Supported Devices:
86+
https://github.com/zephyrproject-rtos/openocd/tree/master/tcl/target
87+
88+
.. _pyOCD Supported Devices:
89+
https://github.com/mbedmicro/pyOCD/tree/master/pyocd/target/builtin

‎doc/guides/debugging/index.rst‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
.. _debugging:
2+
3+
Debugging
4+
#########
5+
6+
.. toctree::
7+
:maxdepth: 1
8+
9+
host-tools.rst
10+
probes.rst

‎doc/guides/debugging/probes.rst‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
.. _debug-probes:
2+
3+
Debug Probes
4+
############
5+
6+
A *debug probe* is special hardware which allows you to control execution of a
7+
Zephyr application running on a separate board. Debug probes usually allow
8+
reading and writing registers and memory, and support breakpoint debugging of
9+
the Zephyr application on your host workstation using tools like GDB. They may
10+
also support other debug software and more advanced features such as
11+
:ref:`tracing program execution <tracing>`. For details on the related host
12+
software supported by Zephyr, see :ref:`debug-host-tools`.
13+
14+
Debug probes are usually connected to your host workstation via USB; they
15+
are sometimes also accessible via an IP network or other means. They usually
16+
connect to the device running Zephyr using the JTAG or SWD protocols. Debug
17+
probes are either separate hardware devices or circuitry integrated into the same
18+
board which runs Zephyr.
19+
20+
Many supported boards in Zephyr include a second microcontroller that serves as
21+
an onboard debug probe, usb-to-serial adapter, and sometimes a drag-and-drop
22+
flash programmer. This eliminates the need to purchase an external debug probe
23+
and provides a variety of debug host tool options.
24+
25+
Several hardware vendors have their own branded onboard debug probe
26+
implementations: NXP LPC boards have LPC-Link2, NXP Kinetis (former Freescale)
27+
boards have OpenSDA, and ST boards have ST-LINK. Each onboard debug probe
28+
microcontroller can support one or more types of firmware that communicate with
29+
their respective debug host tools. For example, an OpenSDA microcontroller can
30+
be programmed with DAPLink firmware to communicate with pyOCD or OpenOCD debug
31+
host tools, or with J-Link firmware to communicate with J-Link debug host
32+
tools.
33+
34+
Some supported boards in Zephyr do not include an onboard debug probe and
35+
therefore require an external debug probe. In addition, boards that do include
36+
an onboard debug probe often also have an SWD or JTAG header to enable the use
37+
of an external debug probe instead. One reason this may be useful is that the
38+
onboard debug probe may have limitations, such as lack of support for advanced
39+
debuggers or high-speed tracing. You may need to adjust jumpers to prevent the
40+
onboard debug probe from interfering with the external debug probe.
41+
42+
.. _lpclink2-jlink-onboard-debug-probe:
43+
44+
LPC-Link2 J-Link Onboard Debug Probe
45+
************************************
46+
47+
The LPC-Link2 J-Link is an onboard debug probe and usb-to-serial adapter
48+
supported on many NXP LPC and i.MX RT development boards.
49+
50+
This debug probe is compatible with the following debug host tools:
51+
52+
- :ref:`jlink-debug-host-tools`
53+
54+
This probe is realized by programming the LPC-Link2 microcontroller with J-Link
55+
LPC-Link2 firmware. Download and install `LPCScrypt`_ to get the firmware and
56+
programming scripts.
57+
58+
1. Put the LPC-Link2 microcontroller into DFU boot mode by attaching the DFU
59+
jumper, then powering up the board.
60+
61+
#. Run the ``program_JLINK`` script.
62+
63+
#. Remove the DFU jumper and power cycle the board.
64+
65+
.. _opensda-daplink-onboard-debug-probe:
66+
67+
OpenSDA DAPLink Onboard Debug Probe
68+
***********************************
69+
70+
The OpenSDA DAPLink is an onboard debug probe and usb-to-serial adapter
71+
supported on many NXP Kinetis and i.MX RT development boards. It also includes
72+
drag-and-drop flash programming support.
73+
74+
This debug probe is compatible with the following debug host tools:
75+
76+
- :ref:`pyocd-debug-host-tools`
77+
- :ref:`openocd-debug-host-tools`
78+
79+
This probe is realized by programming the OpenSDA microcontroller with DAPLink
80+
OpenSDA firmware. NXP provides `OpenSDA DAPLink Board-Specific Firmwares`_.
81+
82+
Before you program the firmware, make sure to install the debug host tools
83+
first.
84+
85+
As with all OpenSDA debug probes, the steps for programming the firmware are:
86+
87+
1. Put the OpenSDA microcontroller into bootloader mode by holding the reset
88+
button while you power on the board. Note that "bootloader mode" in this
89+
context applies to the OpenSDA microcontroller itself, not the target
90+
microcontroller of your Zephyr application.
91+
92+
#. After you power on the board, release the reset button. A USB mass storage
93+
device called **BOOTLOADER** or **MAINTENANCE** will enumerate.
94+
95+
#. Copy the OpenSDA firmware binary to the USB mass storage device.
96+
97+
#. Power cycle the board, this time without holding the reset button. You
98+
should see three USB devices enumerate: a CDC device (serial port), a HID
99+
device (debug port), and a mass storage device (drag-and-drop flash
100+
programming).
101+
102+
.. _opensda-jlink-onboard-debug-probe:
103+
104+
OpenSDA J-Link Onboard Debug Probe
105+
**********************************
106+
107+
The OpenSDA J-Link is an onboard debug probe and usb-to-serial adapter
108+
supported on many NXP Kinetis and i.MX RT development boards.
109+
110+
This debug probe is compatible with the following debug host tools:
111+
112+
- :ref:`jlink-debug-host-tools`
113+
114+
This probe is realized by programming the OpenSDA microcontroller with J-Link
115+
OpenSDA firmware. Segger provides `OpenSDA J-Link Generic Firmwares`_ and
116+
`OpenSDA J-Link Board-Specific Firmwares`_, where the latter is generally
117+
recommended when available. Board-specific firmwares are required for i.MX RT
118+
boards to support their external flash memories, whereas generic firmwares are
119+
compatible with all Kinetis boards.
120+
121+
Before you program the firmware, make sure to install the debug host tools
122+
first.
123+
124+
As with all OpenSDA debug probes, the steps for programming the firmware are:
125+
126+
1. Put the OpenSDA microcontroller into bootloader mode by holding the reset
127+
button while you power on the board. Note that "bootloader mode" in this
128+
context applies to the OpenSDA microcontroller itself, not the target
129+
microcontroller of your Zephyr application.
130+
131+
#. After you power on the board, release the reset button. A USB mass storage
132+
device called **BOOTLOADER** or **MAINTENANCE** will enumerate.
133+
134+
#. Copy the OpenSDA firmware binary to the USB mass storage device.
135+
136+
#. Power cycle the board, this time without holding the reset button. You
137+
should see two USB devices enumerate: a CDC device (serial port) and a
138+
vendor-specific device (debug port).
139+
140+
.. _jlink-external-debug-probe:
141+
142+
J-Link External Debug Probe
143+
***************************
144+
145+
`Segger J-Link`_ is a family of external debug probes, including J-Link EDU,
146+
J-Link PLUS, J-Link ULTRA+, and J-Link PRO, that support a large number of
147+
devices from different hardware architectures and vendors.
148+
149+
This debug probe is compatible with the following debug host tools:
150+
151+
- :ref:`jlink-debug-host-tools`
152+
- :ref:`openocd-debug-host-tools`
153+
154+
Before you use this debug probe, make sure to install the debug host tools
155+
first.
156+
157+
.. _LPCScrypt:
158+
https://www.nxp.com/lpcscrypt
159+
160+
.. _OpenSDA DAPLink Board-Specific Firmwares:
161+
https://www.nxp.com/opensda
162+
163+
.. _OpenSDA J-Link Generic Firmwares:
164+
https://www.segger.com/downloads/jlink/#JLinkOpenSDAGenericFirmwares
165+
166+
.. _OpenSDA J-Link Board-Specific Firmwares:
167+
https://www.segger.com/downloads/jlink/#JLinkOpenSDABoardSpecificFirmwares
168+
169+
.. _Segger J-Link:
170+
https://www.segger.com/products/debug-probes/j-link/

‎doc/guides/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ User and Developer Guides
1111
../README.rst
1212
coccinelle.rst
1313
code-relocation.rst
14+
debugging/index
1415
device_mgmt/index
1516
device_mgmt/dfu
1617
documentation/index

0 commit comments

Comments
 (0)