Skip to content

esp32c3: add support for GDB debugging #2143

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 2, 2021
Merged

esp32c3: add support for GDB debugging #2143

merged 1 commit into from
Oct 2, 2021

Conversation

aykevl
Copy link
Member

@aykevl aykevl commented Sep 26, 2021

You can now debug the ESP32-C3 from the TinyGo command line, like this:

tinygo flash -target=esp32c3 examples/serial
tinygo gdb -target=esp32c3 examples/serial

It's important to flash before running tinygo gdb, because loading a
new firmware from GDB has not yet been implemented.

Probably the easiest way to connect to the ESP32-C3 is by using the
built-in JTAG connection. See:
https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/api-guides/jtag-debugging/configure-builtin-jtag.html

Screenshot from 2021-09-26 22-32-10

You will need to make sure that the openocd command in your $PATH is
the one from Espressif. Otherwise GDB will hang. You can debug this by
supplying the -ocd-output flag:

$ tinygo gdb -target=esp32c3 -ocd-output examples/serial
Open On-Chip Debugger 0.10.0
openocd: Licensed under GNU GPL v2
openocd: For bug reports, read
openocd: 	http://openocd.org/doc/doxygen/bugs.html
openocd: embedded:startup.tcl:60: Error: Can't find interface/esp_usb_jtag.cfg
openocd: in procedure 'script'
openocd: at file "embedded:startup.tcl", line 60

Make sure to configure OpenOCD correctly, until you get the correct
version (that includes the string "esp32"):

$ openocd --version
Open On-Chip Debugger  v0.10.0-esp32-20210721 (2021-07-21-13:33)
Licensed under GNU GPL v2
For bug reports, read
    http://openocd.org/doc/doxygen/bugs.html

If you are on Linux, you may also get the following error:

$ tinygo gdb -target=esp32c3 -ocd-output examples/serial
Open On-Chip Debugger  v0.10.0-esp32-20210721 (2021-07-21-13:33)
openocd: Licensed under GNU GPL v2
openocd: For bug reports, read
openocd: 	http://openocd.org/doc/doxygen/bugs.html
openocd: Info : only one transport option; autoselect 'jtag'
openocd: adapter speed: 40000 kHz
openocd:
openocd: Warn : Transport "jtag" was already selected
openocd: Info : Listening on port 6666 for tcl connections
openocd: Info : Listening on port 4444 for telnet connections
openocd: Error: libusb_open() failed with LIBUSB_ERROR_ACCESS
openocd: Error: esp_usb_jtag: could not find or open device!

The error LIBUSB_ERROR_ACCESS means that there is a permission error.
You can fix this by creating the following file:

$ cat /etc/udev/rules.d/50-esp.rules
# ESP32-C3
SUBSYSTEMS=="usb", ATTRS{idVendor}=="303a", ATTRS{idProduct}=="1001", MODE="0666"

For more details, see:
https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/api-guides/jtag-debugging/index.html

You can now debug the ESP32-C3 from the TinyGo command line, like this:

    tinygo flash -target=esp32c3 examples/serial
    tinygo gdb -target=esp32c3 examples/serial

It's important to flash before running `tinygo gdb`, because loading a
new firmware from GDB has not yet been implemented.

Probably the easiest way to connect to the ESP32-C3 is by using the
built-in JTAG connection. See:
https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/api-guides/jtag-debugging/configure-builtin-jtag.html

You will need to make sure that the `openocd` command in your $PATH is
the one from Espressif. Otherwise GDB will hang. You can debug this by
supplying the -ocd-output flag:

    $ tinygo gdb -target=esp32c3 -ocd-output examples/serial
    Open On-Chip Debugger 0.10.0
    openocd: Licensed under GNU GPL v2
    openocd: For bug reports, read
    openocd: 	http://openocd.org/doc/doxygen/bugs.html
    openocd: embedded:startup.tcl:60: Error: Can't find interface/esp_usb_jtag.cfg
    openocd: in procedure 'script'
    openocd: at file "embedded:startup.tcl", line 60

Make sure to configure OpenOCD correctly, until you get the correct
version (that includes the string "esp32"):

    $ openocd --version
    Open On-Chip Debugger  v0.10.0-esp32-20210721 (2021-07-21-13:33)
    Licensed under GNU GPL v2
    For bug reports, read
        http://openocd.org/doc/doxygen/bugs.html

If you are on Linux, you may also get the following error:

    $ tinygo gdb -target=esp32c3 -ocd-output examples/serial
    Open On-Chip Debugger  v0.10.0-esp32-20210721 (2021-07-21-13:33)
    openocd: Licensed under GNU GPL v2
    openocd: For bug reports, read
    openocd: 	http://openocd.org/doc/doxygen/bugs.html
    openocd: Info : only one transport option; autoselect 'jtag'
    openocd: adapter speed: 40000 kHz
    openocd:
    openocd: Warn : Transport "jtag" was already selected
    openocd: Info : Listening on port 6666 for tcl connections
    openocd: Info : Listening on port 4444 for telnet connections
    openocd: Error: libusb_open() failed with LIBUSB_ERROR_ACCESS
    openocd: Error: esp_usb_jtag: could not find or open device!

The error LIBUSB_ERROR_ACCESS means that there is a permission error.
You can fix this by creating the following file:

    $ cat /etc/udev/rules.d/50-esp.rules
    # ESP32-C3
    SUBSYSTEMS=="usb", ATTRS{idVendor}=="303a", ATTRS{idProduct}=="1001", MODE="0666"

For more details, see:
https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/api-guides/jtag-debugging/index.html
@aykevl
Copy link
Member Author

aykevl commented Sep 26, 2021

This PR also includes "serial-port": ["acm:303a:1001"] which avoids errors with multiple serial ports and makes sure to flash over the built-in USB-to-serial converter at port 18 and 19 of the ESP32-C3 (both would work, but adding this serial port makes sure only one is picked).

@deadprogram
Copy link
Member

🐛 thanks @aykevl now merging.

@deadprogram deadprogram merged commit 2b453db into dev Oct 2, 2021
@deadprogram deadprogram deleted the esp32c3-gdb branch October 2, 2021 07:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants