New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
doc: debugging: Introduce guide covering debug probes and host tools #14000
Conversation
All checks are passing now. Review history of this comment for details about previous failed status. |
Codecov Report
@@ Coverage Diff @@
## master #14000 +/- ##
=======================================
Coverage 51.96% 51.96%
=======================================
Files 309 309
Lines 45576 45576
Branches 10554 10554
=======================================
Hits 23683 23683
Misses 17083 17083
Partials 4810 4810 Continue to review full report at Codecov.
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks just fine so far... a couple of TODO sections left.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is great! Thanks @MaureenHelm. I've wanted to write a doc like this for a while but never found the time. I have some suggestions for next steps.
@MaureenHelm , is this replacement of doc/guides/tools ? |
Yes |
0573233
to
6cd7ea8
Compare
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>
Reworks the programming and debugging section in the mimxrt1020_evk and mimxrt1050_evk board documents to leverage the new debugging guide covering debug probes and host tools. These boards support both the OpenSDA J-Link onboard debug probe and the J-Link external debug probe. Corrects an error linking to the wrong OpenSDA J-Link firmware. Updates the flashing section to reflect that the ``flash`` build system target is now supported. Signed-off-by: Maureen Helm <maureen.helm@nxp.com>
Reworks the programming and debugging section in the mimxrt1060_evk and mimxrt1064_evk board documents to leverage the new debugging guide covering debug probes and host tools. Neither of these boards have OpenSDA J-Link board-specific firmware, therefore the only debug probe currently supported is the external J-Link. Updates the flashing section to reflect that the ``flash`` build system target is now supported. Signed-off-by: Maureen Helm <maureen.helm@nxp.com>
Reworks the programming and debugging section in the freedom board documents to leverage the new debugging guide covering debug probes and host tools. These boards support OpenSDA DAPLink and OpenSDA J-Link onboard debug probes. They can also support an external J-Link probe, but this requires board modifications (cutting traces) and is therefore not documented. Signed-off-by: Maureen Helm <maureen.helm@nxp.com>
The frdm_kw41z board was originally configured in zephyr to use the jlink runner by default because pyocd didn't yet support the kw41z soc. Support for kw41z was added in pyocd v0.9.0, so we can now default to daplink firmware and pyocd. Now all freedom boards in zephyr consistently use daplink and pyocd. Signed-off-by: Maureen Helm <maureen.helm@nxp.com>
The hexiwear_k64f and hexiwear_kw40z share the same OpenSDA microcontroller on the hexiwear docking station, so make the jlink the default firmware on both for consistency. We use jlink instead of daplink by default because hexiwear_kw40z can only use Segger RTT for the console (there is no UART available). Signed-off-by: Maureen Helm <maureen.helm@nxp.com>
Reworks the programming and debugging section in the hexiwear board documents to leverage the new debugging guide covering debug probes and host tools. Recommends the OpenSDA J-Link debug probe because the k64 and kw40z share the same OpenSDA microcontroller, and the kw40z requires Segger RTT for a console. It is possible to use daplink firmware for the k64, however it is not recommended because it requires switching the firmware back to jlink to access the kw40z. Signed-off-by: Maureen Helm <maureen.helm@nxp.com>
Reworks the programming and debugging section in the lpcxpresso54114 board document to leverage the new debugging guide covering debug probes and host tools. This board supports the LPC-Link2 J-Link onboard debug probe. Signed-off-by: Maureen Helm <maureen.helm@nxp.com>
Reworks the programming and debugging section in the usb_kw24d512 board document to leverage the new debugging guide covering debug probes and host tools. This board does not have an OpenSDA microcontroller, therefore the only debug probe currently supported is the external J-Link. Updates the flashing section to reflect that the ``flash`` build system target is now supported. Signed-off-by: Maureen Helm <maureen.helm@nxp.com>
Updates the 96b_nitrogen board document to link to the new debugging guide instead of the opensda page. Signed-off-by: Maureen Helm <maureen.helm@nxp.com>
This page has been replaced by doc/guides/debugging/probes.rst and doc/guides/debugging/host-tools.rst Signed-off-by: Maureen Helm <maureen.helm@nxp.com>
6cd7ea8
to
498a1f0
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM, ST-Link add-ons pushed in #14747
|
||
Follow the instructions in :ref:`opensda-jlink-onboard-debug-probe` to program | ||
the `OpenSDA J-Link Generic Firmware for V3.2 Bootloader`_. Note that Segger | ||
does provide an OpenSDA J-Link Board-Specific Firmware for this board, however |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
but there is a board specific firmware
https://www.segger.com/downloads/jlink/OpenSDA_FRDM-K64F
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, but it doesn't work with the updated bootloader.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
All my comments are addressed; sorry for the delay!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks good, though there seems to be material repeated in different docs. It's not always the case that the words are the same though, so trying to create an include file that we can plug into each spot might not work. Otherwise, just a few working tweaks...
A debug probe is used for both flashing and debugging the board. This board is | ||
configured by default to use the :ref:`opensda-daplink-onboard-debug-probe`. | ||
|
||
Early versions of this board have an outdated version of the OpenSDA bootloader |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can you say something like, Versions of this board prior to x.y have an outdated...
- :ref:`jlink-debug-host-tools` | ||
- :ref:`openocd-debug-host-tools` | ||
|
||
Before you use this debug probe, make sure to install the debug host tools |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
One more time. This would read better as:
Install the debug host tools before you use this debug probe.
Hmm @nashif, you requested my review and then merged the PR... oh well. |
oops, sorry. |
Incorporates minor documentation edits recommended by David Kinder after PR zephyrproject-rtos#14000 was merged. Signed-off-by: Maureen Helm <maureen.helm@nxp.com>
Incorporates minor documentation edits recommended by David Kinder after PR #14000 was merged. Signed-off-by: Maureen Helm <maureen.helm@nxp.com>
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.
@carlescufi, @erwango what do you think about including sections for ST-LINK and and Nordic here too?
Fixes #13584