Skip to content
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

Merged
merged 11 commits into from Mar 30, 2019

Conversation

MaureenHelm
Copy link
Member

@MaureenHelm MaureenHelm commented Mar 1, 2019

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

@zephyrbot
Copy link
Collaborator

zephyrbot commented Mar 1, 2019

All checks are passing now.

Review history of this comment for details about previous failed status.
Note that some checks might have not completed yet.

@codecov-io
Copy link

codecov-io commented Mar 1, 2019

Codecov Report

Merging #14000 into master will not change coverage.
The diff coverage is n/a.

Impacted file tree graph

@@           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.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 100287d...498a1f0. Read the comment docs.

Copy link
Contributor

@dbkinder dbkinder left a 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.

Copy link
Contributor

@mbolivar mbolivar left a 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.

doc/guides/debugging/host-tools.rst Show resolved Hide resolved
doc/guides/debugging/host-tools.rst Outdated Show resolved Hide resolved
doc/guides/debugging/host-tools.rst Outdated Show resolved Hide resolved
doc/guides/debugging/host-tools.rst Show resolved Hide resolved
doc/guides/debugging/host-tools.rst Outdated Show resolved Hide resolved
doc/guides/debugging/probes.rst Show resolved Hide resolved
doc/guides/debugging/probes.rst Show resolved Hide resolved
doc/guides/debugging/probes.rst Outdated Show resolved Hide resolved
doc/guides/debugging/probes.rst Show resolved Hide resolved
doc/guides/debugging/probes.rst Show resolved Hide resolved
@erwango
Copy link
Member

erwango commented Mar 5, 2019

@MaureenHelm , is this replacement of doc/guides/tools ?

@MaureenHelm
Copy link
Member Author

@MaureenHelm , is this replacement of doc/guides/tools ?

Yes

@MaureenHelm MaureenHelm marked this pull request as ready for review March 15, 2019 20:55
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>
@MaureenHelm MaureenHelm added this to the v1.14.0 milestone Mar 15, 2019
@MaureenHelm MaureenHelm added the bug The issue is a bug, or the PR is fixing a bug label Mar 15, 2019
@MaureenHelm
Copy link
Member Author

@dbkinder @mbolivar Please revisit. I filled in all the previously marked TODO sections, and moved the PR out of draft state.

Copy link
Member

@erwango erwango left a 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
Copy link
Collaborator

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

Copy link
Member Author

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.

Copy link
Contributor

@mbolivar mbolivar left a 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!

@nashif nashif requested a review from dbkinder March 30, 2019 02:43
@nashif nashif merged commit dfd779c into zephyrproject-rtos:master Mar 30, 2019
Copy link
Contributor

@dbkinder dbkinder left a 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...

boards/arm/frdm_k64f/doc/index.rst Show resolved Hide resolved
boards/arm/frdm_k64f/doc/index.rst Show resolved Hide resolved
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
Copy link
Contributor

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...

doc/guides/debugging/probes.rst Show resolved Hide resolved
doc/guides/debugging/probes.rst Show resolved Hide resolved
- :ref:`jlink-debug-host-tools`
- :ref:`openocd-debug-host-tools`

Before you use this debug probe, make sure to install the debug host tools
Copy link
Contributor

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.

@dbkinder
Copy link
Contributor

Hmm @nashif, you requested my review and then merged the PR... oh well.

@nashif
Copy link
Member

nashif commented Apr 1, 2019

Hmm @nashif, you requested my review and then merged the PR... oh well.

oops, sorry.

MaureenHelm added a commit to nxp-zephyr/zephyr that referenced this pull request Apr 1, 2019
Incorporates minor documentation edits recommended by David Kinder after
PR zephyrproject-rtos#14000 was merged.

Signed-off-by: Maureen Helm <maureen.helm@nxp.com>
@MaureenHelm MaureenHelm deleted the doc-debugging branch April 1, 2019 17:06
galak pushed a commit that referenced this pull request Apr 1, 2019
Incorporates minor documentation edits recommended by David Kinder after
PR #14000 was merged.

Signed-off-by: Maureen Helm <maureen.helm@nxp.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area: Documentation bug The issue is a bug, or the PR is fixing a bug
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

9 participants