From 6669604ab39ccca17488222341b5dcb74c1b5648 Mon Sep 17 00:00:00 2001 From: Sergio Gasquez Date: Fri, 3 Nov 2023 16:58:18 +0100 Subject: [PATCH] feat: Update openOCD section --- src/SUMMARY.md | 1 - src/tooling/debugging/index.md | 19 +++++---- src/tooling/debugging/openocd.md | 67 ++++++++++++++++++++++++++----- src/tooling/debugging/probe-rs.md | 4 +- src/tooling/debugging/vscode.md | 53 ------------------------ 5 files changed, 68 insertions(+), 76 deletions(-) delete mode 100644 src/tooling/debugging/vscode.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 06eb0a3..2bf6847 100644 --- 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 index 48c8719..895d0bb 100644 --- a/src/tooling/debugging/index.md +++ b/src/tooling/debugging/index.md @@ -4,15 +4,15 @@ 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 @@ -28,7 +28,6 @@ Some of our recent products contain the `USB-JTAG-SERIAL` peripheral that allows # or espflash board-info ``` - - [ESP32-C6][esp32c6-docs] - [ESP32-H2][esp32h2-docs] - [ESP32-S3][esp32s3-docs] diff --git a/src/tooling/debugging/openocd.md b/src/tooling/debugging/openocd.md index 1aef190..ad0aeaf 100644 --- a/src/tooling/debugging/openocd.md +++ b/src/tooling/debugging/openocd.md @@ -1,19 +1,11 @@ # 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 - - - -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 @@ -24,3 +16,58 @@ For other configurations it may require specifying the chip and the interface, f ```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 +[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 + "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 index 5ff8e45..52e8a50 100644 --- a/src/tooling/debugging/probe-rs.md +++ b/src/tooling/debugging/probe-rs.md @@ -126,6 +126,6 @@ There is a `probe-rs` extension in VS Code, see `probe-rs` [VS Code documentatio [cargo-embed]: https://probe.rs/docs/tools/cargo-embed/ [cargo-embed-config]: https://probe.rs/docs/tools/cargo-embed/#configuration -## Using `probe-rs` as an OpenOCD Replacement +## GDB Integration -`probe-rs` has a `gdb` command that runs a GDB server, by default in port, `1337` +`probe-rs` includes a GDB stub to integrate into your usual workflow with common tools. The `gdb` command runs a GDB server, by default in port, `1337`. diff --git a/src/tooling/debugging/vscode.md b/src/tooling/debugging/vscode.md deleted file mode 100644 index b8749b7..0000000 --- a/src/tooling/debugging/vscode.md +++ /dev/null @@ -1,53 +0,0 @@ -# `cortex-debug` VS Code Extension - -The [`cortex-debug`][cortex-debug] VS Code extension also allows debugging Espressif products. Products containing the [`USB-JTAG-SERIAL` peripheral][usb-jtag-serial] do'nt require any external hardware, but other products -may use an external JTAG debugger, like [ESP-Prog][esp-prog]. - - -[cortex-debug]: https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug -[usb-jtag-serial]: index.md#usb-jtag-serial-peripheral -[esp-prog]: https://docs.espressif.com/projects/espressif-esp-iot-solution/en/latest/hw-reference/ESP-Prog_guide.html - -### 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 - "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 -