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 4b4046c..e2a37c1 100644 --- 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 index 1aef190..add84b7 100644 --- 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 - - +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 index a09234b..8e76979 100644 --- 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] - +[binutils-repo]: https://github.com/espressif/binutils-gdb diff --git a/src/tooling/debugging/vscode.md b/src/tooling/debugging/vscode.md deleted file mode 100644 index aeaef2d..0000000 --- a/src/tooling/debugging/vscode.md +++ /dev/null @@ -1,126 +0,0 @@ -# Debugging in Visual Studio Code - -There is also a possibility to debug with graphical output directly in Visual Studio Code. - -## ESP32 - -### Configuration - -1. Connect an external JTAG adapter: [ESP-Prog][esp-prog] can be used. - -| ESP32 Pin | JTAG Signal | -| :---------: | :---------: | -| MTDO/GPIO15 | TDO | -| MTDI/GPIO12 | TDI | -| MTCK/GPIO13 | TCK | -| MTMS/GPIO14 | TMS | -| 3V3 | VJTAG | -| GND | GND | - -> ⚠️ **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", // attach instead of launch, because otherwise flash write is attempted, but fails - "cwd": "${workspaceRoot}", - "executable": "target/xtensa-esp32-none-elf/debug/.....", - "servertype": "openocd", - "interface": "jtag", - "svdFile": "../../esp-pacs/esp32/svd/esp32.svd", - "toolchainPrefix": "xtensa-esp32-elf", - "openOCDPreConfigLaunchCommands": ["set ESP_RTOS none"], - "serverpath": "C:/Espressif/tools/openocd-esp32/v0.11.0-esp32-20220411/openocd-esp32/bin/openocd.exe", - "configFiles": ["board/esp32-wrover-kit-3.3v.cfg"], - "overrideAttachCommands": [ - "set remote hardware-watchpoint-limit 2", - "mon halt", - "flushregs" - ], - "overrideRestartCommands": ["mon reset halt", "flushregs", "c"] - } - ] -} -``` - -[esp-prog]: https://docs.espressif.com/projects/espressif-esp-iot-solution/en/latest/hw-reference/ESP-Prog_guide.html -[cortex-debug]: https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug - -## ESP32-C3 - -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 -``` - -### Configuration - -1. (**Only for revisions older than 3**) Connect an external JTAG adapter, [ESP-Prog][esp-prog] can be used. - -| ESP32-C3 Pin | JTAG Signal | -| :----------: | :---------: | -| MTDO/GPIO7 | TDO | -| MTDI/GPIO5 | TDI | -| MTCK/GPIO6 | TCK | -| MTMS/GPIO4 | TMS | -| 3V3 | VJTAG | -| GND | GND | - -> ⚠️**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", // attach instead of launch, because otherwise flash write is attempted, but fails - "cwd": "${workspaceRoot}", - "executable": "target/riscv32imc-unknown-none-elf/debug/examples/usb_serial_jtag", // - "servertype": "openocd", - "interface": "jtag", - "svdFile": "../../esp-pacs/esp32c3/svd/esp32c3.svd", - "toolchainPrefix": "riscv32-esp-elf", - "openOCDPreConfigLaunchCommands": ["set ESP_RTOS none"], - "serverpath": "C:/Espressif/tools/openocd-esp32/v0.11.0-esp32-20220411/openocd-esp32/bin/openocd.exe", - "configFiles": ["board/esp32c3-builtin.cfg"], - "overrideAttachCommands": [ - "set remote hardware-watchpoint-limit 2", - "mon halt", - "flushregs" - ], - "overrideRestartCommands": ["mon reset halt", "flushregs", "c"] - } - ] -} -```