From 3f3eb1ccc040a23b7e7258963f8f2d78761baaed Mon Sep 17 00:00:00 2001 From: Erwan Gouriou Date: Wed, 20 Mar 2019 15:52:44 +0100 Subject: [PATCH 1/2] doc/guides: debugging: Add ST-Link to probes Add ST-Link chapter in probes page and reference in host-tool openocd section. Signed-off-by: Erwan Gouriou --- doc/guides/debugging/host-tools.rst | 3 + doc/guides/debugging/probes.rst | 97 +++++++++++++++++++ doc/guides/tools/stlink-v21.rst | 138 ---------------------------- 3 files changed, 100 insertions(+), 138 deletions(-) delete mode 100644 doc/guides/tools/stlink-v21.rst diff --git a/doc/guides/debugging/host-tools.rst b/doc/guides/debugging/host-tools.rst index 108b36ce50c65d..6cf328834985c9 100644 --- a/doc/guides/debugging/host-tools.rst +++ b/doc/guides/debugging/host-tools.rst @@ -30,6 +30,7 @@ These debug host tools are compatible with the following debug probes: - :ref:`lpclink2-jlink-onboard-debug-probe` - :ref:`opensda-jlink-onboard-debug-probe` - :ref:`jlink-external-debug-probe` +- :ref:`stlink-v21-onboard-debug-probe` Check if your SoC is listed in `J-Link Supported Devices`_. @@ -54,6 +55,7 @@ These debug host tools are compatible with the following debug probes: - :ref:`opensda-daplink-onboard-debug-probe` - :ref:`jlink-external-debug-probe` +- :ref:`stlink-v21-onboard-debug-probe` Check if your SoC is listed in `OpenOCD Supported Devices`_. @@ -70,6 +72,7 @@ Started Guide. pyOCD includes support for Zephyr RTOS-awareness. These debug host tools are compatible with the following debug probes: - :ref:`opensda-daplink-onboard-debug-probe` +- :ref:`stlink-v21-onboard-debug-probe` Check if your SoC is listed in `pyOCD Supported Devices`_. diff --git a/doc/guides/debugging/probes.rst b/doc/guides/debugging/probes.rst index 2d8750d6a412b8..33bc914e34f83d 100644 --- a/doc/guides/debugging/probes.rst +++ b/doc/guides/debugging/probes.rst @@ -137,6 +137,97 @@ As with all OpenSDA debug probes, the steps for programming the firmware are: should see two USB devices enumerate: a CDC device (serial port) and a vendor-specific device (debug port). +.. _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` + +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 informations 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 +============================ + +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 + + +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 the CMake ``flash`` target with the argument ``STLINK_FW=jlink`` to +build your Zephyr application. + + .. zephyr-app-commands:: + :zephyr-app: samples/hello_world + :gen-args: -DSTLINK_FW=jlink + :goals: flash + +Use the CMake ``debug`` target with the argument ``STLINK_FW=jlink`` to build +your Zephyr application, invoke the J-Link GDB server, attach a GDB client, and +program your Zephyr application to flash. It will leave you at a GDB prompt. + + .. zephyr-app-commands:: + :zephyr-app: samples/hello_world + :gen-args: -DSTLINK_FW=jlink + :goals: debug + +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 menucon + .. _jlink-external-debug-probe: J-Link External Debug Probe @@ -168,3 +259,9 @@ first. .. _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 diff --git a/doc/guides/tools/stlink-v21.rst b/doc/guides/tools/stlink-v21.rst deleted file mode 100644 index 2137ec01497d05..00000000000000 --- a/doc/guides/tools/stlink-v21.rst +++ /dev/null @@ -1,138 +0,0 @@ -:orphan: - -.. _stlink-v21: - -ST-LINK/V2-1 -############ - -Overview -******** - -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. - -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-Link -OB, 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 informations about upgrading ST-LINK/V2-1 to JLink or restore ST-Link/V2-1 -firmware please visit: `SEGGER`_ - -Zephyr supports the following debug tools through ST-LINK/V2-1: - -* :ref:`st_ST-LINK/V2-1_stlink` -* :ref:`st_ST-LINK/V2-1_jlink` - -.. _st_ST-LINK/V2-1_stlink: - -ST-LINK/V2-1 -************ - -ST-Link tool is available by default, flash and debug could be done as follows. - -Flashing -======== - - .. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :goals: flash - -Debugging -========= - - .. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :goals: debug - -.. note:: ST-Link relies on openocd for flashing and debugging. - On Linux, openocd is available though the `Zephyr SDK - `_. - Windows users should use the following steps to install - openocd: - - - Download openocd for Windows from here: `OpenOCD Windows`_ - - Copy bin and share dirs to ``C:\Program Files\OpenOCD\`` - - Add ``C:\Program Files\OpenOCD\bin`` to 'Path' - -.. _st_ST-LINK/V2-1_jlink: - -Segger J-Link -************* - -Host Tools and Firmware -======================= - -Download and install the `Segger J-Link Software and Documentation Pack`_ to -get the J-Link GDB server for your host computer. - -Flashing -======== - -Use the CMake ``flash`` target with the argument ``STLINK_FW=jlink`` to -build your Zephyr application. - - .. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :gen-args: -DSTLINK_FW=jlink - :goals: flash - -Debugging -========= - -Use the CMake ``debug`` target with the argument ``STLINK_FW=jlink`` to build -your Zephyr application, invoke the J-Link GDB server, attach a GDB client, and -program your Zephyr application to flash. It will leave you at a GDB prompt. - - .. zephyr-app-commands:: - :zephyr-app: samples/hello_world - :gen-args: -DSTLINK_FW=jlink - :goals: debug - -Console -======= - -If you configured your Zephyr application to use a UART console (most boards -enable this by default), open a serial terminal (minicom, putty, etc.) with the -following settings: - -- Speed: 115200 -- Data: 8 bits -- Parity: None -- Stop bits: 1 - -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. - - -.. _SEGGER: - https://www.segger.com/products/debug-probes/j-link/models/other-j-links/st-link-on-board/ - -.. _Segger J-Link Software and Documentation Pack: - https://www.segger.com/downloads/jlink - -.. _Segger RTT: - https://www.segger.com/jlink-rtt.html - -.. _OpenOCD Windows: - http://gnutoolchains.com/arm-eabi/openocd/ From b5e4185589df00b29f65be4aebf3c0f0dba16a3d Mon Sep 17 00:00:00 2001 From: Erwan Gouriou Date: Fri, 29 Mar 2019 16:10:43 +0100 Subject: [PATCH 2/2] doc/guides/debugging: Add node for openocd support on windows Add a note to mention how to get openocd working on windows. This is taken from stlink-v21.rst file before its reformatting. Signed-off-by: Erwan Gouriou --- doc/guides/debugging/host-tools.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/doc/guides/debugging/host-tools.rst b/doc/guides/debugging/host-tools.rst index 6cf328834985c9..a6e6c42640ee55 100644 --- a/doc/guides/debugging/host-tools.rst +++ b/doc/guides/debugging/host-tools.rst @@ -59,6 +59,15 @@ These debug host tools are compatible with the following debug probes: Check if your SoC is listed in `OpenOCD Supported Devices`_. +.. note:: On Linux, openocd is available though the `Zephyr SDK + `_. + Windows users should use the following steps to install + openocd: + + - Download openocd for Windows from here: `OpenOCD Windows`_ + - Copy bin and share dirs to ``C:\Program Files\OpenOCD\`` + - Add ``C:\Program Files\OpenOCD\bin`` to 'Path' + .. _pyocd-debug-host-tools: pyOCD Debug Host Tools @@ -90,3 +99,6 @@ Check if your SoC is listed in `pyOCD Supported Devices`_. .. _pyOCD Supported Devices: https://github.com/mbedmicro/pyOCD/tree/master/pyocd/target/builtin + +.. _OpenOCD Windows: + http://gnutoolchains.com/arm-eabi/openocd/