Support JTAG debugging in Arduino IDE 2.0

[me-no-dev]

General Info

• Currently the following debug methods are supported on all boards (menu option is available for the official "Dev Module" boards):
  • ESP32: FTDI Adapter (ESP-Prog or compatible)
  • ESP32-S2: FTDI Adapter (ESP-Prog or compatible)
  • ESP32-S3: Built-In USB JTAG (Requires proper USB Mode to be selected)
  • ESP32-C3: Built-In USB JTAG

Known issues

• Debug sessions can not be restarted (not clear what is the cause yet)
• If debug session is closed or fails, openocd is left running by the IDE and to get around that, you either need to manually kill the process or restart the IDE (Issue seems to be in cortex-debug, but newer "fixed" versions also fail)

To-Do

• Update the release script to update the path to openocd-esp32 in platform.txt
• Update the release script to add tools/ide-debug to the archive
• Update the lib-builder to skip adding -Os to the build flags ref
• Update the lib-builder to remove CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK from ESP32-C3 sdkconfig ref
• Find out what is the issue on C3 and how/when it will be fixed
• Find out why JTAG Port menu can not update the openocd script
• Add default OpenOCD config for all boards
• Find out if it's possible to make debug target restart working

[VojtechBartoska]

Try to find if there is any issues upstream @VojtechBartoska

[VojtechBartoska]

• create a Documentation/Guide, "How to debug in Arduino IDE 2.0".

[VojtechBartoska]

@me-no-dev Can you please add some brief documentation to this? Thanks

[SuGlider]

@me-no-dev
I tested it using Win11, IDE 2.0.3 with these boards:

• ESP32 using FTDI JTAG from ESP-WROVER-KIT
• ESP32S3 and ESP32C3 using USB JTAG

All fine. It debugs using the new IDE.

[P-R-O-C-H-Y]

Overview from my testing. Tested on MacOS Ventura 13.0.1

Test / Device	ESP32 - DevKitC_V4	ESP32S2 - DevKitC-1_V10.1	ESP32C3 - DevKitC-2_V1.1	ESP32S3 - DevKitC-1_V1.0
JTAG used	esp-prog	esp-prog	integrated	integrated
Hit 1st breakpoint after sketch upload and debug start	Yes	Yes	Yes	Yes / sometimes missed (need to reset device and re-set breakpoint while restarting)
Breakpoint hit after device reset (debug restart)	Yes	Yes	Yes	Breakpoints need to be re-set to work
More breakpoints	Sometimes issues when having more than 1 breakpoint	5 breakpoints working and fast	If I have 2 breakpoints set, after device reset, when it should hit the 2nd breakpoint, error of Duplicate Breakpoint address: 0x420000da (BP 20)	Error + warning when 2 breakpoints are set, but no affect on debugging.Error: [esp32s3.cpu0] DSR (8080CC19) indicates DIR instruction generated an overrun!Warn : [esp32s3.cpu0] Failed reading 32 bytes at address 0x420012ec
Debug stop / run debug	Works	Works	Works	Works
Debug stop / upload sketch / run debug	Works	Works	Works	Works
AutoStops in Setup()	Yes	Yes	No	No

[ajsb85]

Hi, I found this error in the new IDE 2.0.3 and the ESP32 platform 2.0.6

Error: 226 175 libusb_helper.c:190 jtag_libusb_open(): libusb_open() failed with LIBUSB_ERROR_NOT_FOUND
Error: 227 177 esp_usb_jtag.c:651 esp_usb_jtag_init(): esp_usb_jtag: could not find or open device!

Error: 230 178 riscv.c:1752 riscv_get_gdb_arch(): Unsupported xlen: -1
Error: 231 178 esp_semihosting.c:78 target_to_esp_semihost_data(): Unknown target arch!

Full log:
https://gist.github.com/ajsb85/b21ace90737a4b946ef53a4982758742

[me-no-dev]

@ajsb85 did you connect the hardware USB port of the C3? Log shows that computer was not able to find the port

[ajsb85]

Yes (ESP32-C3: Built-In USB JTAG)

I changed the driver version after follow this procedure:

https://docs.espressif.com/projects/esp-idf/en/v5.0/esp32c3/api-guides/jtag-debugging/configure-builtin-jtag.html#configure-usb-drivers

BTW this launch.json file looks good for you?
https://gist.github.com/ajsb85/387e10bdc3075d3ba50b2157ab06822f

Now I got this error:

Failed to launch GDB: Remote replied unexpectedly to 'vMustReplyEmpty': PacketSize=4000;qXfer:memory-map:read+;qXfer:features:read+;qXfer:threads:read+;QStartNoAckMode+;vContSupported+ (from target-select extended-remote localhost:50000)

Full logs:

https://gist.github.com/ajsb85/d1a07b71d549d1f02ca01983554a1398

Thank you in advance for the support.

[me-no-dev]

@P-R-O-C-H-Y can you have someone from debug team have a look at the logs?

@ajsb85 that is rather strange. JTAG works well on C3 here without any modifications, though since you are on Windows, I guess fixing WinUSB driver was necessary.

@SuGlider what is your experience?

[Xylopyrographer]

@P-R-O-C-H-Y In this comment: #7295 (comment)

1. Did you need to install any drivers or other components on your Mac to get the ESP-PROG working?
2. Could you confirm the pin-to-pin connections from the ESP-PROG to the ESP32 - DevKitC_V4 and the ESP32S2 - DevKitC-1_V10.1?
3. Confirming, the ESP32 - DevKitC_V4 and ESP32S2 - DevKitC-1_V10.1 boards were connected to your Mac via the board USB connector and concurrently to the ESP-PROG USB ports?
4. Did the power up sequence of the ESP-PROG and the boards seem to matter?
5. Were the ESP-PROG and the boards were powered up before starting the IDE?
6. Could you confirm the Arduino IDE version you tested on?
7. Could you also confirm the version of the arduino-esp32 core it was tested on?
8. Did choosing or not the "Optimize for Debugging" option matter?

I'm having very little success keeping the debugger stable with either an external FTDI device or with an integrated connection. Tested so far on an ESP32-WROOM-32 based kit and -S3 and -C3 boards.

Also keep seeing this crop up in the debugger console logs:
/Users/ficeto/Desktop/ESP32/ESP32S2/esp-idf-public/components/esp_pm/pm_impl.c: No such file or directory. (No account on my machine with user "ficeto" so something is hard coded in there somewhere...)

When this all gets sorted, it'll make good background for the Debugging Tutorial I'll write!

Appreciate your work.