docs: Improve information about debugging for Espressif SoCs

Provide more information on how to properly use OpenOCD and gdb to
debug Espressif SoCs on NuttX.
This commit is contained in:
Tiago Medicci 2024-08-14 13:18:04 -03:00 committed by Xiang Xiao
parent b3f1871bc3
commit 3ae30d00ea
7 changed files with 263 additions and 47 deletions

View File

@ -110,35 +110,75 @@ Note that this step is required only one time. Once the bootloader and partitio
table are flashed, we don't need to flash them again. So subsequent builds
would just require: ``make flash ESPTOOL_PORT=/dev/ttyUSBXX``
Debugging with OpenOCD
======================
Debugging with ``openocd`` and ``gdb``
======================================
Download and build OpenOCD from Espressif, that can be found in
https://github.com/espressif/openocd-esp32
Espressif uses a specific version of OpenOCD to support ESP32-C3: `openocd-esp32 <https://github.com/espressif/>`_.
If you have an ESP32-C3 ECO3, no external JTAG is required to debug, the ESP32-C3
integrates a USB-to-JTAG adapter.
Please check `Building OpenOCD from Sources <https://docs.espressif.com/projects/esp-idf/en/release-v5.1/esp32c3/api-guides/jtag-debugging/index.html#jtag-debugging-building-openocd>`_
for more information on how to build OpenOCD for ESP32-C3.
ESP32-C3 has a built-in JTAG circuitry and can be debugged without any additional chip.
Only an USB cable connected to the D+/D- pins is necessary:
============ ==========
ESP32-C3 Pin USB Signal
============ ==========
GPIO18 D-
GPIO19 D+
5V V_BUS
GND Ground
============ ==========
.. note:: One must configure the USB drivers to enable JTAG communication. Please check
`Configure USB Drivers <https://docs.espressif.com/projects/esp-idf/en/release-v5.1/esp32c3/api-guides/jtag-debugging/configure-builtin-jtag.html#configure-usb-drivers>`_
for more information.
OpenOCD can then be used::
openocd -c 'set ESP_RTOS none' -f board/esp32c3-builtin.cfg
For versions prior to ESP32-C3 ECO3, an external JTAG adapter is needed.
It can be connected as follows::
If you want to debug with an external JTAG adapter it can
be connected as follows:
TMS -> GPIO4
TDI -> GPIO5
TCK -> GPIO6
TDO -> GPIO7
============ ===========
ESP32-C6 Pin JTAG Signal
============ ===========
GPIO4 TMS
GPIO5 TDI
GPIO6 TCK
GPIO7 TDO
============ ===========
Furthermore, an efuse needs to be burnt to be able to debug::
espefuse.py -p <port> burn_efuse DIS_USB_JTAG
.. warning:: Burning eFuses is an irreversible operation, so please
consider the above option before starting the process.
OpenOCD can then be used::
openocd -c 'set ESP_RTOS none' -f board/esp32c3-ftdi.cfg
Once OpenOCD is running, you can use GDB to connect to it and debug your application::
riscv-none-elf-gdb -x gdbinit nuttx
whereas the content of the ``gdbinit`` file is::
target remote :3333
set remote hardware-watchpoint-limit 2
mon reset halt
flushregs
monitor reset halt
thb nsh_main
c
.. note:: ``nuttx`` is the ELF file generated by the build process. Please note that ``CONFIG_DEBUG_SYMBOLS`` must be enabled in the ``menuconfig``.
Please refer to :doc:`/quickstart/debugging` for more information about debugging techniques.
Peripheral Support
==================

View File

@ -120,35 +120,75 @@ Where ``<port>`` is typically ``/dev/ttyUSB0`` or similar and ``./`` is
the path to the folder containing the externally-built 2nd stage bootloader for
the ESP32-C3 as explained above.
Debugging with OpenOCD
======================
Debugging with ``openocd`` and ``gdb``
======================================
Espressif uses a specific version of OpenOCD to support ESP32-C3: `openocd-esp32 <https://github.com/espressif/>`_.
Please check `Building OpenOCD from Sources <https://docs.espressif.com/projects/esp-idf/en/release-v5.1/esp32c3/api-guides/jtag-debugging/index.html#jtag-debugging-building-openocd>`_
for more information on how to build OpenOCD for ESP32-C3.
If you have an ESP32-C3 ECO3, no external JTAG is required to debug, the ESP32-C3
integrates a USB-to-JTAG adapter.
ESP32-C3 has a built-in JTAG circuitry and can be debugged without any additional chip.
Only an USB cable connected to the D+/D- pins is necessary:
============ ==========
ESP32-C3 Pin USB Signal
============ ==========
GPIO18 D-
GPIO19 D+
5V V_BUS
GND Ground
============ ==========
.. note:: One must configure the USB drivers to enable JTAG communication. Please check
`Configure USB Drivers <https://docs.espressif.com/projects/esp-idf/en/release-v5.1/esp32c3/api-guides/jtag-debugging/configure-builtin-jtag.html#configure-usb-drivers>`_
for more information.
OpenOCD can then be used::
openocd -c 'set ESP_RTOS hwthread; set ESP_FLASH_SIZE 0' -f board/esp32c3-builtin.cfg
For versions prior to ESP32-C3 ECO3, an external JTAG adapter is needed.
It can be connected as follows::
If you want to debug with an external JTAG adapter it can
be connected as follows:
TMS -> GPIO4
TDI -> GPIO5
TCK -> GPIO6
TDO -> GPIO7
============ ===========
ESP32-C6 Pin JTAG Signal
============ ===========
GPIO4 TMS
GPIO5 TDI
GPIO6 TCK
GPIO7 TDO
============ ===========
Furthermore, an efuse needs to be burnt to be able to debug::
espefuse.py -p <port> burn_efuse DIS_USB_JTAG
.. warning:: Burning eFuses is an irreversible operation, so please
consider the above option before starting the process.
OpenOCD can then be used::
openocd -c 'set ESP_RTOS hwthread; set ESP_FLASH_SIZE 0' -f board/esp32c3-ftdi.cfg
Once OpenOCD is running, you can use GDB to connect to it and debug your application::
riscv-none-elf-gdb -x gdbinit nuttx
whereas the content of the ``gdbinit`` file is::
target remote :3333
set remote hardware-watchpoint-limit 2
mon reset halt
flushregs
monitor reset halt
thb nsh_main
c
.. note:: ``nuttx`` is the ELF file generated by the build process. Please note that ``CONFIG_DEBUG_SYMBOLS`` must be enabled in the ``menuconfig``.
Please refer to :doc:`/quickstart/debugging` for more information about debugging techniques.
Peripheral Support
==================

View File

@ -119,35 +119,66 @@ Where ``<port>`` is typically ``/dev/ttyUSB0`` or similar and ``./`` is
the path to the folder containing the externally-built 2nd stage bootloader for
the ESP32-C6 as explained above.
Debugging with OpenOCD
======================
Debugging with ``openocd`` and ``gdb``
======================================
Download and build OpenOCD from Espressif, that can be found in
https://github.com/espressif/openocd-esp32
Espressif uses a specific version of OpenOCD to support ESP32-C6: `openocd-esp32 <https://github.com/espressif/>`_.
Please check `Building OpenOCD from Sources <https://docs.espressif.com/projects/esp-idf/en/release-v5.1/esp32c6/api-guides/jtag-debugging/index.html#jtag-debugging-building-openocd>`_
for more information on how to build OpenOCD for ESP32-C6.
You do not need an external JTAG to debug, the ESP32-C6 integrates a
USB-to-JTAG adapter.
.. note:: One must configure the USB drivers to enable JTAG communication. Please check
`Configure USB Drivers <https://docs.espressif.com/projects/esp-idf/en/release-v5.1/esp32c6/api-guides/jtag-debugging/configure-builtin-jtag.html#configure-usb-drivers>`_
for more information.
OpenOCD can then be used::
openocd -c 'set ESP_RTOS hwthread; set ESP_FLASH_SIZE 0' -f board/esp32c6-builtin.cfg
If you want to debug with an external JTAG adapter it can
be connected as follows::
be connected as follows:
TMS -> GPIO4
TDI -> GPIO5
TCK -> GPIO6
TDO -> GPIO7
============ ===========
ESP32-C6 Pin JTAG Signal
============ ===========
GPIO4 TMS
GPIO5 TDI
GPIO6 TCK
GPIO7 TDO
============ ===========
Furthermore, an efuse needs to be burnt to be able to debug::
espefuse.py -p <port> burn_efuse DIS_USB_JTAG
.. warning:: Burning eFuses is an irreversible operation, so please
consider the above option before starting the process.
OpenOCD can then be used::
openocd -c 'set ESP_RTOS hwtread; set ESP_FLASH_SIZE 0' -f board/esp32c6-ftdi.cfg
Once OpenOCD is running, you can use GDB to connect to it and debug your application::
riscv-none-elf-gdb -x gdbinit nuttx
whereas the content of the ``gdbinit`` file is::
target remote :3333
set remote hardware-watchpoint-limit 2
mon reset halt
flushregs
monitor reset halt
thb nsh_main
c
.. note:: ``nuttx`` is the ELF file generated by the build process. Please note that ``CONFIG_DEBUG_SYMBOLS`` must be enabled in the ``menuconfig``.
Please refer to :doc:`/quickstart/debugging` for more information about debugging techniques.
Peripheral Support
==================

View File

@ -119,35 +119,66 @@ Where ``<port>`` is typically ``/dev/ttyUSB0`` or similar and ``./`` is
the path to the folder containing the externally-built 2nd stage bootloader for
the ESP32-H2 as explained above.
Debugging with OpenOCD
======================
Debugging with ``openocd`` and ``gdb``
======================================
Download and build OpenOCD from Espressif, that can be found in
https://github.com/espressif/openocd-esp32
Espressif uses a specific version of OpenOCD to support ESP32-H2: `openocd-esp32 <https://github.com/espressif/>`_.
You don not need an external JTAG is to debug, the ESP32-H2 integrates a
Please check `Building OpenOCD from Sources <https://docs.espressif.com/projects/esp-idf/en/release-v5.1/esp32h2/api-guides/jtag-debugging/index.html#jtag-debugging-building-openocd>`_
for more information on how to build OpenOCD for ESP32-H2.
You do not need an external JTAG to debug, the ESP32-H2 integrates a
USB-to-JTAG adapter.
.. note:: One must configure the USB drivers to enable JTAG communication. Please check
`Configure USB Drivers <https://docs.espressif.com/projects/esp-idf/en/release-v5.1/esp32h2/api-guides/jtag-debugging/configure-builtin-jtag.html#configure-usb-drivers>`_
for more information.
OpenOCD can then be used::
openocd -c 'set ESP_RTOS hwthread; set ESP_FLASH_SIZE 0' -f board/esp32h2-builtin.cfg
If you want to debug with an external JTAG adapter it can
be connected as follows::
be connected as follows:
TMS -> GPIO2
TDI -> GPIO5
TCK -> GPIO5
TDO -> GPIO3
============ ===========
ESP32-H2 Pin JTAG Signal
============ ===========
GPIO2 TMS
GPIO5 TDI
GPIO4 TCK
GPIO3 TDO
============ ===========
Furthermore, an efuse needs to be burnt to be able to debug::
espefuse.py -p <port> burn_efuse DIS_USB_JTAG
.. warning:: Burning eFuses is an irreversible operation, so please
consider the above option before starting the process.
OpenOCD can then be used::
openocd -c 'set ESP_RTOS hwthread; set ESP_FLASH_SIZE 0' -f board/esp32h2-ftdi.cfg
Once OpenOCD is running, you can use GDB to connect to it and debug your application::
riscv-none-elf-gdb -x gdbinit nuttx
whereas the content of the ``gdbinit`` file is::
target remote :3333
set remote hardware-watchpoint-limit 2
mon reset halt
flushregs
monitor reset halt
thb nsh_main
c
.. note:: ``nuttx`` is the ELF file generated by the build process. Please note that ``CONFIG_DEBUG_SYMBOLS`` must be enabled in the ``menuconfig``.
Please refer to :doc:`/quickstart/debugging` for more information about debugging techniques.
Peripheral Support
==================

View File

@ -142,8 +142,10 @@ externally-built 2nd stage bootloader and the partition table (if applicable): w
``make bootloader``, these files are placed into ``nuttx`` folder. ``ESPTOOL_BAUD`` is able to
change the flash baud rate if desired.
Debugging with OpenOCD
======================
Debugging with ``openocd`` and ``gdb``
======================================
Espressif uses a specific version of OpenOCD to support ESP32: `openocd-esp32 <https://github.com/espressif/>`_.
Please check `Building OpenOCD from Sources <https://docs.espressif.com/projects/esp-idf/en/release-v5.1/esp32/api-guides/jtag-debugging/index.html#jtag-debugging-building-openocd>`_
for more information on how to build OpenOCD for ESP32.
@ -165,10 +167,33 @@ Some boards, like :ref:`ESP32-Ethernet-Kit V1.2 <platforms/xtensa/esp32/boards/e
Other boards that don't have any built-in JTAG debugger can be debugged using an external JTAG debugger, like the one
described for the :ref:`ESP32-DevKitC <platforms/xtensa/esp32/boards/esp32-devkitc/index:Debugging with OpenOCD>`.
.. note:: One must configure the USB drivers to enable JTAG communication. Please check
`Configure USB Drivers <https://docs.espressif.com/projects/esp-idf/en/release-v5.1/esp32/api-guides/jtag-debugging/configure-ft2232h-jtag.html#configure-usb-drivers>`_
for configuring the JTAG adapter of the :ref:`ESP32-Ethernet-Kit V1.2 <platforms/xtensa/esp32/boards/esp32-ethernet-kit/index:ESP32-Ethernet-Kit V1.2>` and
:ref:`ESP-WROVER-KIT <platforms/xtensa/esp32/boards/esp32-wrover-kit/index:ESP-WROVER-KIT>` boards and other FT2232-based JTAG adapters.
OpenOCD can then be used::
openocd -c 'set ESP_RTOS hwthread; set ESP_FLASH_SIZE 0' -f board/esp32-wrover-kit-1.8v.cfg
Once OpenOCD is running, you can use GDB to connect to it and debug your application::
xtensa-esp32-elf-gdb -x gdbinit nuttx
whereas the content of the ``gdbinit`` file is::
target remote :3333
set remote hardware-watchpoint-limit 2
mon reset halt
flushregs
monitor reset halt
thb nsh_main
c
.. note:: ``nuttx`` is the ELF file generated by the build process. Please note that ``CONFIG_DEBUG_SYMBOLS`` must be enabled in the ``menuconfig``.
Please refer to :doc:`/quickstart/debugging` for more information about debugging techniques.
Peripheral Support
==================

View File

@ -135,8 +135,10 @@ externally-built 2nd stage bootloader and the partition table (if applicable): w
``make bootloader``, these files are placed into ``nuttx`` folder. ``ESPTOOL_BAUD`` is able to
change the flash baud rate if desired.
Debugging with OpenOCD
======================
Debugging with ``openocd`` and ``gdb``
======================================
Espressif uses a specific version of OpenOCD to support ESP32-S2: `openocd-esp32 <https://github.com/espressif/>`_.
Please check `Building OpenOCD from Sources <https://docs.espressif.com/projects/esp-idf/en/release-v5.1/esp32s2/api-guides/jtag-debugging/index.html#jtag-debugging-building-openocd>`_
for more information on how to build OpenOCD for ESP32-S2.
@ -157,10 +159,33 @@ Some boards, like :ref:`ESP32-S2-Kaluga-1 Kit v1.3 <platforms/xtensa/esp32s2/boa
Other boards that don't have any built-in JTAG debugger can be debugged using an external JTAG debugger being connected
directly to the ESP32-S2 JTAG pins.
.. note:: One must configure the USB drivers to enable JTAG communication. Please check
`Configure USB Drivers <https://docs.espressif.com/projects/esp-idf/en/release-v5.1/esp32s2/api-guides/jtag-debugging/configure-ft2232h-jtag.html?highlight=udev#configure-usb-drivers>`_
for configuring the JTAG adapter of the :ref:`ESP32-S2-Kaluga-1 <platforms/xtensa/esp32s2/boards/esp32s2-kaluga-1/index:ESP32-S2-Kaluga-1 Kit v1.3>` board
and other FT2232-based JTAG adapters.
OpenOCD can then be used::
openocd -c 'set ESP_RTOS hwthread; set ESP_FLASH_SIZE 0' -f board/esp32s2-kaluga-1.cfg
Once OpenOCD is running, you can use GDB to connect to it and debug your application::
xtensa-esp32s2-elf-gdb -x gdbinit nuttx
whereas the content of the ``gdbinit`` file is::
target remote :3333
set remote hardware-watchpoint-limit 2
mon reset halt
flushregs
monitor reset halt
thb nsh_main
c
.. note:: ``nuttx`` is the ELF file generated by the build process. Please note that ``CONFIG_DEBUG_SYMBOLS`` must be enabled in the ``menuconfig``.
Please refer to :doc:`/quickstart/debugging` for more information about debugging techniques.
Peripheral Support
==================

View File

@ -142,8 +142,10 @@ externally-built 2nd stage bootloader and the partition table (if applicable): w
``make bootloader``, these files are placed into ``nuttx`` folder. ``ESPTOOL_BAUD`` is able to
change the flash baud rate if desired.
Debugging with OpenOCD
======================
Debugging with ``openocd`` and ``gdb``
======================================
Espressif uses a specific version of OpenOCD to support ESP32-S3: `openocd-esp32 <https://github.com/espressif/>`_.
Please check `Building OpenOCD from Sources <https://docs.espressif.com/projects/esp-idf/en/release-v5.1/esp32s3/api-guides/jtag-debugging/index.html#jtag-debugging-building-openocd>`_
for more information on how to build OpenOCD for ESP32-S3.
@ -154,10 +156,32 @@ extra wiring/cable to connect JTAG to ESP32-S3. Most of the ESP32-S3 boards have
USB connector that can be used for JTAG debugging.
This is the case for the :ref:`ESP32-S3-DevKit <platforms/xtensa/esp32s3/boards/esp32s3-devkit/index:ESP32S3-DevKit>` board.
.. note:: One must configure the USB drivers to enable JTAG communication. Please check
`Configure USB Drivers <https://docs.espressif.com/projects/esp-idf/en/release-v5.1/esp32s3/api-guides/jtag-debugging/configure-builtin-jtag.html?highlight=udev#configure-usb-drivers>`_
for more information.
OpenOCD can then be used::
openocd -c 'set ESP_RTOS hwthread; set ESP_FLASH_SIZE 0' -f board/esp32s3-builtin.cfg
Once OpenOCD is running, you can use GDB to connect to it and debug your application::
xtensa-esp32s3-elf-gdb -x gdbinit nuttx
whereas the content of the ``gdbinit`` file is::
target remote :3333
set remote hardware-watchpoint-limit 2
mon reset halt
flushregs
monitor reset halt
thb nsh_main
c
.. note:: ``nuttx`` is the ELF file generated by the build process. Please note that ``CONFIG_DEBUG_SYMBOLS`` must be enabled in the ``menuconfig``.
Please refer to :doc:`/quickstart/debugging` for more information about debugging techniques.
Peripheral Support
==================