ESP32-C3 Tips and Tricks for Eclipse / Built in JTAG Debugging

[BrianP]

I have been working on getting ESP32-C3 with built in USB JTAG to work reliably with Eclipse. Unfortunately, there are significant gaps and errors in the documentation so I thought I would document workarounds I have discovered. Hopefully these will be fixed over time. I suspect that most of these issues are cross-platform. Obviously the OpenOCD-esp32 binary and DLLs are Windows only, so you may have to build a version of OpenOCD (the instructions do not work for Windows).

Some of these issue may also affect ESP-IDF function but I do not know which ones.


Use master version of ESP-IDF
At this time the release versions of ESP-IDF do not support ESP32-C3 so set up the Eclipse plugin to use the master versions (this is at the end of the list of versions). Set it up, install the tools, etc..

Update openocd-esp32
The master version of openocd-esp32 supports ESP32-C3 but does not allow you to flash the device. This interacts with a variety of other bugs and problems so you need to upgrade OpenOCD. For other OSs you might be able to build it according to the directions but these do not work in Windows, so for Windows in a command window, download the June build of OpenOCD-esp32
https://github.com/espressif/openocd-es ... e1302b.zip and unzip it to (eg) NewOCD

After you build/download OpenOCD-esp32

Copy NewOCD/bin/OpenOCD.exe to whereever your ESP-IDF tools are
.espressif\tools\openocd-esp32\v0.10.0-esp32-20210401\openocd-esp32\bin
and NewOCD/share/scripts/esp32c3*.cfg to
.espressif\tools\openocd-esp32\v0.10.0-esp32-20210401\openocd-esp32\share\openocd\scripts\target\esp32c3.cfg"

note that if you ever update the Eclipse plugin, install tools, etc, you will have to update openocd-esp32, at least until they start distributing the fixed version

In theory changing Eclipse Window->Preferences->Epressif->Global OpenOCD Path to the new version should work but I haven’t figured out how to get it to find the OpenOCD scripts as it always want to look in .espressif\tools\openocd-esp32\v0.10.0-esp32-20210401

Windows: Make sure riscv32-esp-elf-gdb are DLLs present
The master version of riscv32-esp-elf-gdb does not include certain dlls. Check to make sure .espressif\tools\riscv32-esp-elf\esp-2021r1-8.4.0\riscv32-esp-elf\bin\riscv32-esp-elf-gdb works. If you run riscv32-esp-elf-gdb.exe from the command line and you get an error regarding missing dlls you need to install them. I found them in my copy of Msys64

copy
C:\msys64\mingw64\bin\libwinpthread-1.dll, libgcc_s_seh-1.dll, libstdc++-6.dll to
.espressif\tools\riscv32-esp-elf\esp-2021r1-8.4.0\riscv32-esp-elf\bin\

Run Eclipse
Now you can open Eclipse and import an ESP-IDF example project.


Create an ESP-IDF Debug Configuration
Note: If you ever close Eclipse you have to delete the debug configurations and make another one or you will not be able to build the project.

Delete all debug configurations Debug Configurations (Run > Debug Configurations), select all, click the red ‘X’ then double click ESP-IDF GDB OpenOCD Debugging.

The Eclipse plugin does not set up the debug configuration properly for ESP32-C3.

Debugger Tab -> Config Options
-s ${openocd_path}/share/openocd/scripts -f board/esp32c3-builtin.cfg -c "program_esp build/blink.bin 0x10000 verify"

note: change blink.bin to whatever your project name is

Debugger Tab -> Actual Executable
.espressif\tools\riscv32-esp-elf\esp-2021r1-8.4.0\riscv32-esp-elf\bin\riscv32-esp-elf-gdb.exe

Debugger Tab -> GDB Client Setup/Other Commands add
set arch riscv:rv32


Unresolved Includes
Changing Run to Debug configurations or vice-versa may result in "unresolved includes". If so, delete the project build directory and rebuild.

Using the USB Port as stdio
If you want to use the USB port as stdio, open sdkconfig
component config -> ESP System Settings -> Channel for console output -> USB Serial/JTAG

Save and rebuild the project.

Using USB as stdio can cause JTAG debugger to appear to hang
The JTAG debugger breaks at app_main(), which is after the initialization of FreeRTOS. As a result, if you enable the USB Serial/JTAG port without having a terminal open for the port, the debugger will appear to "hang" because the initialization code is waiting on the USB port.

Using USB as stdio causes Break at address "0x40000000" with no debug information available
I have no idea why. I just close the window.