JTAG debugging over USB cable

[jeancf]

Espressif documentation mentions that the ESP32-C3 has built-in JTAG functionality and that "JTAG debugging is through an USB cable connected to the D+/D- USB pins of ESP32-C3. No need for an external JTAG adapter and extra wiring / cable to connect JTAG to ESP32-C3."

When I launch openocd -f board/esp32c3-builtin.cfg with the USB cable connected however I get:

Open On-Chip Debugger  v0.10.0-esp32-20210401 (2021-04-01-15:45)
Licensed under GNU GPL v2
For bug reports, read
	http://openocd.org/doc/doxygen/bugs.html
Info : only one transport option; autoselect 'jtag'
Warn : Transport "jtag" was already selected
force hard breakpoints
Info : Listening on port 6666 for tcl connections
Info : Listening on port 4444 for telnet connections
Error: esp_usb_jtag: could not find or open device!

Am I using the wrong openocd config? How does this work?

Thanks.

[gigamegawatts]

The USB JTAG support works well on the OI-PLUS for me, but I'm using a commercial product that makes things easy, VisualGDB.

I just did a quick test with ESP-IDF 4.3. Debugging works for me, using the same command and version of openocd as you, but flashing doesn't. Apparently the flashing problem is fixed in a later release of openocd -- https://github.com/espressif/openocd-esp32/releases/tag/v0.10.0-esp32-20210721.

Are you using the USB port on the OI-PLUS? I don't think that can be made to work. Instead, you need to connect a USB breakout board to 5V, GND, GPIO18 and GPIO19, as described here: https://visualgdb.com/tutorials/esp32/esp32-c3/.

Also, you need to use a WinUSB driver from Espressif, as described here: https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/api-guides/jtag-debugging/configure-builtin-jtag.html. I had to manually switch to their driver using this tool: https://visualgdb.com/UsbDriverTool/.

I hope that helps.

Dan.

[jeancf]

Thanks for your response Dan.

Are you using the USB port on the OI-PLUS?

I was. Thanks to you I re-read the instructions and now realise that I am suposed to connect with a USB cable through a USB-to_TTL adapter to GPIO18, GPIO19, 5V and GND pins of the board.

I also updated openocd-esp32 to the version that you mentioned (2021-07-21). I am using linux therefore I do not need a driver. However the command openocd -f board/esp32c3-builtin.cfg still returns the same Error: esp_usb_jtag: could not find or open device!. I tried swapping the wires connected to GPIO18 and GPIO19 witth the same result.

Do you have to specify somehow to which COM device the USB adapter is connected? Otherwise, how would openocd know where to find it...

Thanks.

[gigamegawatts]

Hi,

I just tried running on Linux, specifically Ubuntu 20.04.

It works for me. I suspect the difference is that I (unintentionally) installed the 4.4-dev version of ESP-IDF. Based on my Googling, it seems that USB JTAG support is flaky in ESP-IDF 4.3.x.

Other than that, the only problem I had to deal with was the udev settings. I think you've already done that, since you didn't get any LIBUSB errors, but you definitely need the udev rules in order for openocd to work. The udev rules I used are from https://github.com/espressif/openocd-esp32/blob/master/contrib/60-openocd.rules.

I also had problems once I connected with gdb: the gdb session timed out, and the openocd session would have a lot of "usb received only x out of y bytes". I fixed that by lowering the adapter speed setting.

The openocd command line I ended up using is: openocd -f interface/esp_usb_jtag.cfg -c "adapter_khz 3000" -f target/esp32c3.cfg

I actually don't know openocd at all - I just copied this from what VisualGDB uses. Maybe the board parm would work, and maybe the interface parm isn't needed, but the above works for me.

Flashing still doesn't work for me. I found that you can disconnect the 5V cable on the USB breakout board (the one used for JTAG), then connect a second cable to the OI-PLUS's USB C port, then flash the code through USB.

I hope that helps.

Dan.

[jeancf]

The problem is that I kept trying to connect to the GPIO18 and GPIO19 port through a USB-to TTL adapter. Actually the link that you provided (https://visualgdb.com/tutorials/esp32/esp32-c3/) shows that the USB wires have to be directly connected to the pins. Also, the data sheet specifies that GPIO18 and GPIO19 pins provide USB D+/D- signals, not UART TX/RX.

That option is a lot less appealing than my original expectation of debugging through the USB-C connector of the board. I am going to try to use an external JTAG probe instead (and burn the corresponding fuse).

Anyway, thanks a lot for your help. I hope that flashing gets resolved soon to simplify your process.

Thanks.

EDIT: I built a USB cable out of curiosity and tested it. I get openocd to establish a connection with the board but gdb target remote:3333 returns errors:

Remote debugging using :3333
Ignoring packet error, continuing...
warning: unrecognized item "timeout" in "qSupported" response
Ignoring packet error, continuing...
Remote replied unexpectedly to 'vMustReplyEmpty': timeout

[gigamegawatts]

For what it's worth, flashing through the USB JTAG connection does work for me now. I actually don't know what changed from when it failed on Saturday, so this feature might be flaky, or maybe just user error.

Here's what worked for flashing the hello-world sample - it's the same as in the Espressif docs. As mentioned, I'm using the 4.4dev version of ESP-IDF, so the openocd version is more recent than the one I linked to earlier.

openocd -f board/esp32c3-builtin.cfg -c "program_esp build/hello-world.bin 0x10000 verify exit"

Output:

Open On-Chip Debugger  v0.10.0-esp32-20210902 (2021-09-02-09:38)
Licensed under GNU GPL v2
For bug reports, read
        http://openocd.org/doc/doxygen/bugs.html
Info : only one transport option; autoselect 'jtag'
Warn : Transport "jtag" was already selected
Info : esp_usb_jtag: Device found. Base speed 40000KHz, div range 1 to 255
Info : clock speed 40000 kHz
Info : JTAG tap: esp32c3.cpu tap/device found: 0x00005c25 (mfg: 0x612 (Espressif Systems), part: 0x0005, ver: 0x0)
Info : datacount=2 progbufsize=16
Info : Examined RISC-V core; found 1 harts
Info :  hart 0: XLEN=32, misa=0x40101104
Info : Listening on port 3333 for gdb connections
Info : JTAG tap: esp32c3.cpu tap/device found: 0x00005c25 (mfg: 0x612 (Espressif Systems), part: 0x0005, ver: 0x0)
Info : Flash mapping 0: 0x10020 -> 0x3c020020, 24 KB
Info : Flash mapping 1: 0x20020 -> 0x42000020, 87 KB
Info : Auto-detected flash bank 'esp32c3.flash' size 4096 KB
Info : Using flash bank 'esp32c3.flash' size 4096 KB
** Programming Started **
Info : PROF: Data transferred in 2726.99 ms @ 58.6727 KB/s
** Programming Finished **
** Verify Started **
** Verified OK **
shutdown command invoked

To clarify the type of USB connection I'm using, it's a simple breakout board like this one: https://www.adafruit.com/product/1764. I think a breakout cable like this would also work, though I don't own one: https://www.adafruit.com/product/4448

[jeancf]

I did not want to wait for the delivery of a breakout adapter so I built a frankencable with an old usb cable that cut and soldered to 4 Dupont wires.

On the software side, I deleted the complete esp-idf installation and restarted from scratch with the master branch. After a few hiccups, I managed to get it installed correctly. Like you, I am now able to do build and upload the binary over the built-in JTAG interface at last. I am not able to debug it yet though. Launching idf.py gdb fails with

Executing action: gdb
riscv32-esp-elf-gdb: error while loading shared libraries: libpython2.7.so.1.0: cannot open shared object file: No such file or directory

This sounds like riscv32-esp-elf-gdb is built with python 2.7 but I only have python 3.9 installed. I don´t feel like installing python 2.7 just for this. Do you have python 2.7 installed?

[gigamegawatts]

Yes, I do: Python 2.7.18. That library was installed by the libpython2.7 package.

I had no idea Python 2.7 was prereq for riscv32-esp-elf-gdb or any other part of ESP-IDF -- there's no mention of it in the ESP-IDF prereqs page. I must have installed Python 2.7 a long time ago for some other project.

Seems like yet another bug in the ESP-IDF support for this chip, though I don't see any issues about it on the ESP-IDF Github. If you don't want to install Python 2.7 (or maybe installing just libpython2.7 would work?), maybe you should open an issue on the ESP-IDF Github - they might provide a fix or workaround.

[jeancf]

I installed python 2.7 for now and this problem is resolved. I reported the issue to Espressif (https://github.com/espressif/openocd-esp32/issues/181).

Now when I start gdb I get:

Ignoring packet error, continuing...
warning: unrecognized item "timeout" in "qSupported" response
/home/jeancf/Documents/esp32c3/hello_world/build/gdbinit:2: Error in sourced command file:
Remote replied unexpectedly to 'vMustReplyEmpty': PacketSize=4000;qXfer:memory-map:read+;qXfer:features:read+;qXfer:threads:read+;QStartNoAckMode+;vContSupported+

At the same time, on the side of openocd I see:

Info : accepting 'gdb' connection on tcp/3333
Warn : No symbols for FreeRTOS!
Info : Flash mapping 0: 0x10020 -> 0x3c020020, 26 KB
Info : Flash mapping 1: 0x20020 -> 0x42000020, 88 KB
Info : Auto-detected flash bank 'esp32c3.flash' size 2048 KB
Info : Using flash bank 'esp32c3.flash' size 2048 KB
Info : Flash mapping 0: 0x10020 -> 0x3c020020, 26 KB
Info : Flash mapping 1: 0x20020 -> 0x42000020, 88 KB
Info : Using flash bank 'esp32c3.irom' size 92 KB
Info : Flash mapping 0: 0x10020 -> 0x3c020020, 26 KB
Info : Flash mapping 1: 0x20020 -> 0x42000020, 88 KB
Info : Using flash bank 'esp32c3.drom' size 28 KB
Warn : negative reply, retrying
Warn : negative reply, retrying
Warn : negative reply, retrying
Error: GDB missing ack(2) - assumed good
Error: GDB missing ack(2) - assumed good
Error: GDB missing ack(2) - assumed good
Info : dropped 'gdb' connection

gdbinit file:

file /home/jeancf/Documents/esp32c3/hello_world/build/hello-world.elf
target remote :3333
mon reset halt
flushregs
thb app_main
c

Neverending nightmare...

[gigamegawatts]

That "Error in sourced command file" might be the cause.

I'm using a slightly different gdbinit without the file command -- I copied it from the docs:

target remote :3333
set remote hardware-watchpoint-limit 2
mon reset halt
flushregs
thb app_main
c

I specify the .elf file in the gdb command line instead:

riscv32-esp-elf-gdb -x gdbinit build/hello-world.elf

[jeancf]

I filed an issue with Espressif and I am waiting for a reaction.