Update debug section (#128)

* feat: Initial update of probe-rs * feat: Add some small sections * feat: Update VS Code section * feat: Update openOCD section * fix: Grammarly corrections * docs: Address review comments * docs: Add links to binutils * docs: Update probe-rs support * docs: Remove direct-boot * docs: Update probe-rs link * docs: FIx code snippet
esp-rs · Nov 22, 2023 · fee396b · fee396b
1 parent ad5dda0
commit fee396b
Show file tree

Hide file tree

Showing 5 changed files with 204 additions and 169 deletions.
diff --git a/src/SUMMARY.md b/src/SUMMARY.md
@@ -22,7 +22,6 @@
   - [Debugging](./tooling/debugging/index.md)
     - [probe-rs](./tooling/debugging/probe-rs.md)
     - [OpenOCD](./tooling/debugging/openocd.md)
-    - [Debugging in Visual Studio Code](./tooling/debugging/vscode.md)
   - [Simulating](./tooling/simulating/index.md)
     - [Wokwi](./tooling/simulating/wokwi.md)
     - [QEMU](tooling/simulating/qemu.md)

diff --git a/src/tooling/debugging/index.md b/src/tooling/debugging/index.md
@@ -4,12 +4,36 @@ Debugging Rust applications is also possible using different tools that will be
 
 Refer to the table below to see which chip is supported in every debugging method:
 
-|              | **probe-rs** | **OpenOCD** | **VS Code** |
-| :----------: | :----------: | :---------: | :---------: |
-|  **ESP32**   |      ❌       |      ✅      |      ✅      |
-| **ESP32-C2** |      ✅       |      ✅      |      ✅      |
-| **ESP32-C3** |      ✅       |      ✅      |      ✅      |
-| **ESP32-C6** |      ✅       |      ✅      |      ✅      |
-| **ESP32-H2** |      ✅       |      ✅      |      ✅      |
-| **ESP32-S2** |      ❌       |      ✅      |      ✅      |
-| **ESP32-S3** |      ❌       |      ✅      |      ✅      |
+|              | **probe-rs** | **OpenOCD** |
+| :----------: | :----------: | :---------: |
+|  **ESP32**   |      ⏳       |      ✅      |
+| **ESP32-C2** |      ✅       |      ✅      |
+| **ESP32-C3** |      ✅       |      ✅      |
+| **ESP32-C6** |      ✅       |      ✅      |
+| **ESP32-H2** |      ✅       |      ✅      |
+| **ESP32-S2** |      ⏳       |      ✅      |
+| **ESP32-S3** |      ⏳       |      ✅      |
+
+## `USB-JTAG-SERIAL` Peripheral
+
+Some of our recent products contain the `USB-JTAG-SERIAL` peripheral that allows for debugging without any external hardware debugger. More info on configuring the interface can be found in the official documentation for the chips that support this peripheral:
+- [ESP32-C3][esp32c3-docs]
+    - The availability of built-in JTAG interface depends on the ESP32-C3 revision:
+      - Revisions older than 3 **don't** a have built-in JTAG interface.
+      - Revisions 3 (and newer) **do** have a built-in JTAG interface, and you don't have to connect an external device to be able to debug.
+
+    To find your ESP32-C3 revision, run:
+    ```shell
+    cargo espflash board-info
+    # or
+    espflash board-info
+    ```
+- [ESP32-C6][esp32c6-docs]
+- [ESP32-H2][esp32h2-docs]
+- [ESP32-S3][esp32s3-docs]
+
+[esp32c3-docs]: https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/api-guides/jtag-debugging/configure-builtin-jtag.html
+[esp32c6-docs]: https://docs.espressif.com/projects/esp-idf/en/latest/esp32c6/api-guides/jtag-debugging/configure-builtin-jtag.html
+[esp32h2-docs]: https://docs.espressif.com/projects/esp-idf/en/latest/esp32h2/api-guides/jtag-debugging/configure-builtin-jtag.html
+[esp32s3-docs]: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-guides/jtag-debugging/configure-builtin-jtag.html
+
diff --git a/src/tooling/debugging/openocd.md b/src/tooling/debugging/openocd.md
@@ -1,26 +1,77 @@
 
 # OpenOCD
 
-Similar to [`probe-rs`][probe-rs], OpenOCD doesn't have support for the `Xtensa` architecture. However, Espressif does maintain a fork of OpenOCD under [espressif/openocd-esp32][espressif-openocd-esp32] which has support for Espressif's chips.
+Similar to [`probe-rs`][probe-rs], OpenOCD doesn't have support for the `Xtensa` architecture. However, Espressif does maintain a fork of OpenOCD under [`espressif/openocd-esp32`][espressif-openocd-esp32] which has support for Espressif's chips.
 
 Instructions on how to install `openocd-esp32` for your platform can be found in [the Espressif documentation][espressif-documentation].
 
-[probe-rs]: ./probe-rs.md
-[espressif-openocd-esp32]: https://github.com/espressif/openocd-esp32
-[espressif-documentation]: https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/api-guides/jtag-debugging/index.html#setup-of-openocd
-
-## Setup for Espressif Chips
-
-<!-- how to choose interface & chip -->
+GDB with all the Espressif products supported can be obtained in [`espressif/binutils-gdb`][binutils-repo].
 
-Once installed, it's as simple as running `openocd` with the correct scripts. For chips with the built-in USB JTAG, there is normally a config that will work out of the box, for example on the ESP32-C3:
+Once installed, it's as simple as running `openocd` with the correct arguments. For chips with the built-in  [`USB-JTAG-SERIAL` peripheral][usb-jtag-serial], there is normally a config file that will work out of the box, for example on the ESP32-C3:
 
 ```shell
 openocd -f board/esp32c3-builtin.cfg
 ```
 
-For other configurations it may require specifying the chip and the interface, for example, ESP32 with a J-Link:
+For other configurations, it may require specifying the chip and the interface, for example, ESP32 with a J-Link:
 
 ```shell
 openocd -f interface/jlink.cfg -f target/esp32.cfg
 ```
+
+[probe-rs]: ./probe-rs.md
+[espressif-openocd-esp32]: https://github.com/espressif/openocd-esp32
+[espressif-documentation]: https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/api-guides/jtag-debugging/index.html#setup-of-openocd
+[binutils-repo]: https://github.com/espressif/binutils-gdb
+[usb-jtag-serial]: index.md#usb-jtag-serial-peripheral
+
+## VS Code Extension
+
+OpenOCD can be used in VS Code via the [`cortex-debug`][cortex-debug] extension to debug Espressif products.
+
+[cortex-debug]: https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug
+
+### Configuration
+
+1. If required, connect the external JTAG adapter.
+   1. See Configure Other JTAG Interfaces section of ESP-IDF Programming Guide. Eg: [Section for ESP32][jtag-interfaces-esp32]
+> ⚠️ **Note**: On Windows, `USB Serial Converter A 0403 6010 00` driver should be WinUSB.
+2. Set up VSCode
+   1. Install [Cortex-Debug][cortex-debug] extension for VS Code.
+   2. Create the `.vscode/launch.json` file in the project tree you want to debug.
+   3. Update `executable`, `svdFile`, `serverpath` paths, and `toolchainPrefix` fields.
+
+```json
+{
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+    {
+      // more info at: https://github.com/Marus/cortex-debug/blob/master/package.json
+      "name": "Attach",
+      "type": "cortex-debug",
+      "request": "attach", // launch will fail when attempting to download the app into the target
+      "cwd": "${workspaceRoot}",
+      "executable": "target/xtensa-esp32-none-elf/debug/.....", //!MODIFY
+      "servertype": "openocd",
+      "interface": "jtag",
+      "toolchainPrefix": "xtensa-esp32-elf", //!MODIFY
+      "openOCDPreConfigLaunchCommands": ["set ESP_RTOS none"],
+      "serverpath": "C:/Espressif/tools/openocd-esp32/v0.11.0-esp32-20220411/openocd-esp32/bin/openocd.exe", //!MODIFY
+      "gdbPath": "C:/Espressif/tools/riscv32-esp-elf-gdb/riscv32-esp-elf-gdb/bin/riscv32-esp-elf-gdb.exe", //!MODIFY
+      "configFiles": ["board/esp32-wrover-kit-3.3v.cfg"], //!MODIFY
+      "overrideAttachCommands": [
+        "set remote hardware-watchpoint-limit 2",
+        "mon halt",
+        "flushregs"
+      ],
+      "overrideRestartCommands": ["mon reset halt", "flushregs", "c"]
+    }
+  ]
+}
+```
+
+[jtag-interfaces-esp32]: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/configure-other-jtag.html
+
diff --git a/src/tooling/debugging/probe-rs.md b/src/tooling/debugging/probe-rs.md
@@ -6,46 +6,133 @@ The [`probe-rs`][probe-rs] project is a set of tools to interact with embedded M
   - GDB support.
   - CLI for interactive debugging.
   - VS Code extension.
-- Real Time Transfer (RTT)
-  - Similar to app_trace component of IDF.
+- [Real Time Transfer (RTT)][rtt]
+  - Similar to [`app_trace` component of IDF][app-trace-idf].
 - Flashing algorithms
 
-More info about probe-rs & how to set up a project can be found on the [probe-rs] website.
+Follow the [installation][prober-rs-installation] and [setup][prober-rs-setup] instructions at the [`probe-rs`][probe-rs] website.
+
+Espressif products containing the [`USB-JTAG-SERIAL` peripheral][usb-jtag-serial] can use `probe-rs` without any external hardware.
 
 [probe-rs]: https://probe.rs/
 [openocd]: https://openocd.org/
 [pyocd]: https://pyocd.io/
 [segger-tools]: https://www.segger.com/
+[app-trace-idf]: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/app_trace.html
+[rtt]: https://wiki.segger.com/RTT
+[prober-rs-installation]: https://probe.rs/docs/getting-started/installation/
+[prober-rs-setup]: https://probe.rs/docs/getting-started/probe-setup/
+[usb-jtag-serial]: index.md#usb-jtag-serial-peripheral
 
-## `USB-JTAG-SERIAL` Peripheral for ESP32-C3
+## Flashing with `probe-rs`
 
-Starting from `probe-rs` v0.12, it is possible to flash and debug the ESP32-C3 with the built-in `USB-JTAG-SERIAL` peripheral, no need for any external hardware debugger. More info on configuring the interface can be found in the [official documentation][official-documentation].
+`probe-rs` can be used to flash applications to your target since it supports the [ESP-IDF image format][idf-image] via the `--format idf` argument.
+  - Example command for flashing an ESP32-C3: `probe-rs run --chip esp32c3 --format idf`
 
-[official-documentation]: https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/api-guides/jtag-debugging/configure-builtin-jtag.html
+The flashing command can be set as a custom Cargo runner by adding the following to your project's `.cargo/config.toml` file:
 
-## Support for Espressif Chips
+```toml
+[target.'cfg(any(target_arch = "riscv32", target_arch = "xtensa"))']
+runner = "probe-rs run --chip esp32c3 --format idf"
+```
 
-`probe-rs` currently only supports `ARM` & `RISC-V`, therefore this limits the number of Espressif chips that can be used at the moment.
+With this configuration, you can flash and monitor your application using `cargo run`.
+
+[idf-image]: https://docs.espressif.com/projects/esptool/en/latest/esp32c3/advanced-topics/firmware-image-format.html
+
+## VS Code Extension
+
+There is a `probe-rs` extension in VS Code, see `probe-rs` [VS Code documentation][probe-rs-vscode] for details on how to install, configure and use it.
+
+### Example `launch.json`
+
+```json
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "type": "probe-rs-debug",
+            "request": "launch",
+            "name": "Launch",
+            "cwd": "${workspaceFolder}",
+            "chip": "esp32c3", //!MODIFY
+            "flashingConfig": {
+                "flashingEnabled": true,
+                "resetAfterFlashing": true,
+                "haltAfterReset": true,
+                "formatOptions": {
+                    "format": "idf" //!MODIFY (or remove). Valid values are: 'elf'(default), 'idf'
+                }
+            },
+            "coreConfigs": [
+                {
+                    "coreIndex": 0,
+                    "programBinary": "./target/riscv32imc-unknown-none-elf/debug/${workspaceFolderBasename}", //!MODIFY
+                    "rttEnabled": true,
+                    "rttChannelFormats": [
+                        {
+                            "channelNumer": "0",
+                            "dataFormat": "String",
+                            "showTimestamp": true,
+                        }
+                    ]
+                }
+            ]
+        },
+        {
+            "type": "probe-rs-debug",
+            "request": "attach",
+            "name": "Attach",
+            "cwd": "${workspaceFolder}",
+            "chip": "esp32c3", //!MODIFY
+            "coreConfigs": [
+                {
+                    "coreIndex": 0,
+                    "programBinary": "./target/riscv32imc-unknown-none-elf/debug/${workspaceFolderBasename}", //!MODIFY
+                    "rttEnabled": true,
+                    "rttChannelFormats": [
+                        {
+                            "channelNumer": "0",
+                            "dataFormat": "String",
+                            "showTimestamp": true,
+                        }
+                    ]
+                }
+            ]
+        }
+    ]
+}
+```
 
-|   Chip   | Flashing | Debugging |
-| :------: | :------: | :-------: |
-| ESP32-C3 |    ✅     |     ⚠️     |
+> ⚠️ **Note**: The example `launch.json` uses `rtt`, which may require enabling such feature in some crates, like [`esp-println`][esp-println] and [`esp-backtrace`][esp-backtrace]
+> Eg: ESP32-C3 `no_std` project that uses `esp-println` and `esp-backtrace`:
+> ```toml
+> esp-backtrace = { version = "0.9.0", features = ["esp32c3", "panic-handler", "exception-handler", "print-rtt"] }
+> esp-println = { version = "0.7.0", features = ["esp32c3", "rtt"], default-features = flase }
+> ```
 
-> ⚠️ **Note**: _Items marked with ⚠️ are currently work in progress, usable but expect bugs._
+The `Launch` configuration will flash the device and start debugging process while `Attach` will start the debugging in the already running application of the device. See VS Code documentation on [differences between launch and attach][vscode-configs] for more details.
 
-## Permissions - Linux
 
-On Linux, you may run into permission issues trying to interact with Espressif probes. Installing the following `udev` rules and reloading should fix that issue.
+[probe-rs-vscode]: https://probe.rs/docs/tools/debugger/
+[esp-println]: https://github.com/esp-rs/esp-println
+[esp-backtrace]: https://github.com/esp-rs/esp-backtrace?tab=readme-ov-file#features
+[vscode-configs]: https://code.visualstudio.com/docs/editor/debugging#_launch-versus-attach-configurations
 
-```text
-# Espressif dev kit FTDI
-ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6010", MODE="660", GROUP="plugdev", TAG+="uaccess"
+## `cargo-flash` and `cargo-embed`
 
-# Espressif USB JTAG/serial debug unit
-ATTRS{idVendor}=="303a", ATTRS{idProduct}=="1001", MODE="660", GROUP="plugdev", TAG+="uaccess"
+`probe-rs` comes along with these two tools:
+- [`cargo-flash`][cargo-flash]: A flash tool that downloads your binary to the target and runs it.
+- [`cargo-embed`][cargo-embed]: Superset of `cargo-flash` that also allows opening an RTT terminal or a GDB server. A [configuration file][cargo-embed-config] can used to define the behavior.
 
-# Espressif USB Bridge
-ATTRS{idVendor}=="303a", ATTRS{idProduct}=="1002", MODE="660", GROUP="plugdev", TAG+="uaccess"
-```
+[cargo-flash]: https://probe.rs/docs/tools/cargo-flash/
+[cargo-embed]: https://probe.rs/docs/tools/cargo-embed/
+[cargo-embed-config]: https://probe.rs/docs/tools/cargo-embed/#configuration
+
+## GDB Integration
+
+`probe-rs` includes a GDB stub to integrate into your usual workflow with common tools. The `probe-rs gdb` command runs a GDB server, by default in port, `1337`.
+
+GDB with all the Espressif products supported can be obtained in [`espressif/binutils-gdb`][binutils-repo]
 
-<!-- TODO: when probe-rs can actually debug at least a C3 with decent back traces etc, add a section here with an example config: see https://github.com/probe-rs/probe-rs/issues/877 -->
+[binutils-repo]: https://github.com/espressif/binutils-gdb