Skip to content

Troubleshooting FAQ

Jump to bottom
Erhan Kurubas edited this page Jan 13, 2024 · 13 revisions

Generic Issues

OpenOCD crashes at startup with message 'jtag_checks: Assertion `jtag_trst == 0' failed.'

OpenOCD log looks like the below.

Error: no device found
Error: unable to open ftdi device with vid 0403, pid 6010, description '*', serial '*' at bus location '*'
Error: no device found
Error: unable to open ftdi device with vid 0403, pid 6014, description '*', serial '*' at bus location '*'

Reason 1

No debug adapter is connected.

Solution

Check that the debug adapter USB device is present in the system.

OS Actions
Windows Go to Device Dispatcher and check that device is detected by the system.
Linux Use lsusb to list all connected USB devices.
MacOS system_profiler SPUSBDataType or brew install lsusb and use lsusb to list all connected USB devices

Reason 2

Debug adapter's driver was installed incorrectly.

Reported issues

https://github.com/espressif/openocd-esp32/issues/174

Solution

OS Actions
Windows Install driver using IDF Tools Installer
Linux https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/configure-ft2232h-jtag.html#linux
MacOS https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/configure-ft2232h-jtag.html#macos

OpenOCD reports 'JTAG scan chain interrogation failed'

OpenOCD log looks like the below.

Error: JTAG scan chain interrogation failed: all zeroes
Error: Check JTAG interface, timings, target power, etc.
Error: Trying to use configured scan chain anyway...

Reason 1

JTAG wires are connected improperly.

Solution

Check JTAG wires are connected.

ESP32 ESP32-S2(S3) ESP32-C2(C3)
TDI GPIO12 GPIO41 GPIO5
TCK GPIO13 GPIO39 GPIO6
TMS GPIO14 GPIO42 GPIO4
TDO GPIO15 GPIO40 GPIO7
GND GND GND GND

Reason 2

Application reconfigured JTAG pins for other purposes (e.g. SPI or SDMMC).

Solution

If possible make your application using other pins.

Reason 3

JTAG wires are too long or bad.

Solution

Try to use shorter wires for JTAG or lower the adapter speed with -c 'adapter speed <speed_in_khz>' command.

Uploading FW via JTAG does not work

OpenOCD log at startup looks like the below.

WARNING: ESP flash support is disabled!
WARNING: ESP flash support is disabled!

Reason 1

Flash support is disabled because it has not been implemented for that chip yet.

Solution

Flash FW over UART.

Reason 2

Flash support is disabled via OpenOCD command line by option -c 'set ESP_FLASH_SIZE 0'.

Solution

Flash FW over UART.

GDB reports 'unrecognized item "timeout" in "qSupported" response'

GDB output looks like below.

Ignoring packet error, continuing...
warning: unrecognized item "timeout" in "qSupported" response
Remote replied unexpectedly to 'vMustReplyEmpty': PacketSize=4000;qXfer:memory-map:read+;qXfer:features:read+;qXfer:threads:read+;QStartNoAckMode+;vContSupported+

Reason

OpenOCD becomes unresponsive due to:

Solution

Possible solutions:

  • Increase GDB remote timeout.
  • Increase debug adapter speed by adding -c adapter_khz XXX at the end of OpenOCD command line or change it in the config file

libusb_get_string_descriptor_ascii() failed with -9

Error: 113 485 libusb_helper.c:373 jtag_libusb_get_serial(): libusb_get_string_descriptor_ascii() failed with -9

Reason

The error code "-9" corresponds to LIBUSB_ERROR_PIPE, which generally indicates that the target can not respond to the OpenOCD command.

Possible reasons for this failure:

  • USB Connection Issues: Ensure that the USB cable is properly connected between the host computer and the chip. Check for any physical damage to the USB cable or connectors.
  • Driver Issues: Make sure that the appropriate USB drivers are installed for the chip on the host computer. Verify that the USB drivers are up-to-date.
  • Power Supply: Insufficient power supply to the chip might lead to USB communication problems. Ensure that the chip is adequately powered.
  • Floating bootstrap pins: For some chips (eg. ESP32-C3) floating bootstrap pins can cause USB communication problems. Ensure that the bootstrap pins are not left in the float mode for proper functionality.

Solution

There is no unique solution. Check all possible reasons and take action for all.

Non-Espressif Debug Adapters

TBD

Chip-Specific Issues

OpenOCD reports a flasher stub running problem because of the application binary location.

Mostly, warnings can be seen in 2 different forms.

Warn : Failed to get flash maps (-8)!
Warn : Invalid magic number in app image!
Warn : Failed to get flash mappings (-4)!

or

Warn : Failed to get flash maps (-6)!
Warn : Application image is invalid! Check configured binary flash offset 'appimage_offset'.
Warn : Failed to get flash mappings (-4)!

Reason 1

The partition table offset is not 0x8000, so flash mappings can not be read from the partition table.

Solution

Set application image offset explicitly with the OpenOCD command.

openocd -s <tcl_path> -f <board_config> -c "init; halt; esp appimage_offset <new_app_binary_offset>"

Reason 2

Application is not loaded to flash or unexpected magic number read from the partition table flash location

Solution 1

Load the application and try again.

Solution 2

Set application image offset explicitly with the OpenOCD command.

Application Level Tracing fails RISCV chips

OpenOCD log at startup looks like the below.

Error: Failed to get max trace block size!
Error: Failed to init cmd ctx (-4)!

Reason

For Espressif RISCV chips you need to reset the target after OpenOCD is connected to trigger apptrace control info transfer from the target to OpenOCD. It is done by invoking a special syscall when apptrace is initialized on the target during startup.

Solution

Reset chip after OpenOCD is connected.

ESP32-C3 and ESP32-S3 builtin USB_JTAG gets stuck after HW reset

OpenOCD log after target HW reset looks like below.

Error: esp_usb_jtag: usb sent only 0 out of 31 bytes.
Error: missing data from bitq interface
Error: esp_usb_jtag: usb sent only 0 out of 50 bytes.
Error: missing data from bitq interface
Error: Failed to exec JTAG queue!
Error: Failed to read debug stubs address location (-104)!

Reason

Known issue 1 Known issue 2

Solution

Solved by commit.

ESP32-S3 flash access problem using builtin USB_JTAG

OpenOCD log looks like below when flash is accessed (e.g. upon GDB connect).

Error: esp_usb_jtag: usb sent only 0 out of 31 bytes.
Error: missing data from bitq interface
Error: esp_usb_jtag: usb sent only 0 out of 50 bytes.
Error: missing data from bitq interface
Error: Failed to exec JTAG queue!
Error: Failed to read debug stubs address location (-104)!

Reason

This is a known issue.

Solution

The workaround is to use an external JTAG adapter or run OpenOCD with disabled flash support with option -c 'set ESP_FLASH_SIZE 0'.

ESP32-C3 'JTAG_SEL_ENABLE' efuse does not work in silicon rev3

This is known issue of rev3 silicon. https://github.com/espressif/esp-idf/issues/7836

General OpenOCD Features

Profiling: xtensa-esp-elf-gprof: can't find .text section in X.elf

https://github.com/espressif/openocd-esp32/issues/312

Reason

gprof searches for a .text section in the compiled binary to generate a report. However, ESP-IDF application ELF files have a .flash.text section.

Solution

To resolve this, replace .flash.text with .text using the following command:

xtensa-esp32s3-elf-objcopy -I elf32-xtensa-le --rename-section .flash.text=.text <app.elf>
Clone this wiki locally