[Doc] Update ST-Link doc following debugging chapter introduction

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,9 +55,19 @@ 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`_.
 
+.. note:: On Linux, openocd is available though the `Zephyr SDK
+   <https://www.zephyrproject.org/developers/#downloads>`_.
+   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
@@ -70,6 +81,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`_.
 
@@ -87,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/

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