Add information about using Segger RTT with the Debug Probe (raspberrypi#383)

Relates to raspberrypi#4284

Co-authored-by: Martin Crossley <dev@crossleys.biz>

Author: katshann-raspberry

documentation/asciidoc/microcontrollers/debug-probe/uart-connection.adoc

@@ -57,3 +57,78 @@ For terminal programs that support it, a description of the USB serial UART is a
 image::images/description.jpg[width="60%"]
 
 The unique serial number in this description means that on Windows your COM port numbering is "sticky" per device, and will allow you to write `udev` rules to associate a named device node with a particular Debug Probe.
+
+== RTT connections
+
+You can also configure your application to send its output directly over the SWD interface without the need for a UART connection. This uses a mechanism called Segger Real-Time Transport (RTT).
+
+To do this, you must enable the RTT stdio driver in your application and connect to RTT with the Debug Probe.
+
+NOTE: You must use a *debug build* of your application to send output over SWD.
+
+=== Enabling the RTT stdio driver
+
+The C/C++ SDK provides a stdio driver for RTT just like the ones for UART and USB. For more information, see xref:../pico-sdk/runtime.adoc#group_pico_stdio_rtt[pico_stdio_rtt].
+
+To enable the driver in your build, include the following line in your *CMakeLists.txt* file (or link with *pico_stdio_rtt* which does the same thing):
+
+[source,console]
+----
+pico_enable_stdio_rtt(<your_project_name> 1)
+----
+
+After calling `stdio_init_all()`, any output that your application sends with `printf()` is sent to RTT. If you want to copy your output to the UART as well, you can enable that too.
+
+=== Connecting to RTT from VSCode
+
+RTT is supported by OpenOCD and the VSCode https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug[Cortex-Debug] extension; both of these are set up as part of xref:../microcontrollers/debug-probe.adoc#install-tools[installing the tools].
+
+To enable RTT for a debug session add a section to its launch configuration. Open your project's `.vscode` folder and add the following lines to the `launch.json` file, putting them in the appropriate configuration section, such as `"Pico Debug (Cortex-Debug)"`:
+
+[source,json]
+----
+"rttConfig": {
+    "enabled": true,
+    "address": "auto",
+    "decoders": [
+        {
+            "label": "",
+            "port": 0,
+            "type": "console"
+        }
+    ]
+}
+----
+
+For more information, see https://github.com/Marus/cortex-debug/blob/master/debug_attributes.md[cortex-debug launch attributes].
+
+If you now launch a debug session on an RTT-enabled application and open the *TERMINAL* tab, you see a list on the right that includes `RTT Ch:0 console`. Select this to see the output that your application sends to the `pico_stdio_rtt` driver.
+
+=== Connecting to RTT in a standalone debug session
+
+If you are using a standalone debug session as described in xref:../microcontrollers/debug-probe.adoc#standalone-debug-session[Starting a Debug Session], you can connect to RTT by completing the following steps:
+
+. Build and upload your RTT-enabled application.
+. Connect the Debug Probe and start `openocd` and `gdb` in separate terminals. For more information, see xref:../microcontrollers/debug-probe.adoc#standalone-debug-session[Standalone debug session].
+
+. At the `gdb` prompt enter the following commands:
++
+[source,console]
+----
+(gdb) target remote localhost:3333
+(gdb) monitor reset init
+(gdb) monitor rtt setup 0x20000000 2048 "SEGGER RTT"
+(gdb) monitor rtt start
+(gdb) monitor rtt server start 60000 0
+(gdb) continue
+----+
+NOTE: The `gdb` commands prefixed with `monitor` are passed through to `openocd`. For more information about the commands used here, see https://openocd.org/doc/html/General-Commands.html[section 15.6] of the OpenOCD Manual.
++
+OpenOCD searches for an RTT control block on the target and then creates a local TCP socket on port 60000.
+
+. Open a third window and connect to the local socket with a tool like `nc` (netcat) or equivalent to see the RTT output from your application:
++
+[source,console]
+----
+$ nc localhost 60000
+----

documentation/asciidoc/microcontrollers/debug-probe/updating-firmware.adoc

@@ -5,18 +5,20 @@ Firmware for the Debug Probe is available as a UF2 file distributed by Raspberry
 The latest version of the Debug Probe firmware is version 2.2.3. If you're running an older version, or if you have accidentally overwritten the firmware on your Debug Probe, you can find the latest release of the firmware in https://github.com/raspberrypi/debugprobe/releases/latest[the debugprobe GitHub repository].
 
 To check the firmware version of your Debug Probe, run:
+
 [source, console]
 ----
 $ lsusb -v -d 2e8a:000c | grep bcdDevice
 ----
-This will report `bcdDevice 2.23` for Debug Probe firmware version 2.2.3.
+
+This reports `bcdDevice 2.23` for Debug Probe firmware version 2.2.3.
 
 NOTE: The `Info : CMSIS-DAP: FW Version = 2.0.0` line reported by `openocd` only refers to the CMSIS-DAP protocol level (which is different to the Debug Probe firmware version).
 
 To update the firmware version of your Debug Probe:
 
-1. Download `debugprobe.uf2` from the latest release.
-1. Pinch to remove the top of the Debug Probe enclosure.
-1. Push and hold the BOOTSEL button as you plug the Debug Probe into your computer, to mount a volume called "RPI-RP2".
-1. Copy `debugprobe.uf2` onto the "RPI-RP2" volume. The volume will dismount automatically after the file finishes copying onto the device.
-1. Your Debug Probe will reboot and now runs an updated version of the Debug Probe firmware. It is now ready for debugging.
+. Download `debugprobe.uf2` from the latest release.
+. Pinch to remove the top of the Debug Probe enclosure.
+. Push and hold the BOOTSEL button as you plug the Debug Probe into your computer, to mount a volume called "RPI-RP2".
+. Copy `debugprobe.uf2` onto the "RPI-RP2" volume. The volume will dismount automatically after the file finishes copying onto the device.
+. Your Debug Probe reboots and now runs an updated version of the Debug Probe firmware. It is now ready for debugging.