This is an automated email from the ASF dual-hosted git repository.
xiaoxiang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
The following commit(s) were added to refs/heads/master by this push:
new 3ae30d00ea docs: Improve information about debugging for Espressif SoCs
3ae30d00ea is described below
commit 3ae30d00ea41738d025221552f5d569ba2f77611
Author: Tiago Medicci <[email protected]>
AuthorDate: Wed Aug 14 13:18:04 2024 -0300
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.
---
.../platforms/risc-v/esp32c3-legacy/index.rst | 64 ++++++++++++++++++----
Documentation/platforms/risc-v/esp32c3/index.rst | 60 ++++++++++++++++----
Documentation/platforms/risc-v/esp32c6/index.rst | 49 ++++++++++++++---
Documentation/platforms/risc-v/esp32h2/index.rst | 51 +++++++++++++----
Documentation/platforms/xtensa/esp32/index.rst | 29 +++++++++-
Documentation/platforms/xtensa/esp32s2/index.rst | 29 +++++++++-
Documentation/platforms/xtensa/esp32s3/index.rst | 28 +++++++++-
7 files changed, 263 insertions(+), 47 deletions(-)
diff --git a/Documentation/platforms/risc-v/esp32c3-legacy/index.rst
b/Documentation/platforms/risc-v/esp32c3-legacy/index.rst
index 074d86919f..756c0925fd 100644
--- a/Documentation/platforms/risc-v/esp32c3-legacy/index.rst
+++ b/Documentation/platforms/risc-v/esp32c3-legacy/index.rst
@@ -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
==================
diff --git a/Documentation/platforms/risc-v/esp32c3/index.rst
b/Documentation/platforms/risc-v/esp32c3/index.rst
index c08d990757..e8c68758b8 100644
--- a/Documentation/platforms/risc-v/esp32c3/index.rst
+++ b/Documentation/platforms/risc-v/esp32c3/index.rst
@@ -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
==================
diff --git a/Documentation/platforms/risc-v/esp32c6/index.rst
b/Documentation/platforms/risc-v/esp32c6/index.rst
index 72891f568d..6a51d3cf8e 100644
--- a/Documentation/platforms/risc-v/esp32c6/index.rst
+++ b/Documentation/platforms/risc-v/esp32c6/index.rst
@@ -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
==================
diff --git a/Documentation/platforms/risc-v/esp32h2/index.rst
b/Documentation/platforms/risc-v/esp32h2/index.rst
index a06b036bbb..38bff47fb1 100644
--- a/Documentation/platforms/risc-v/esp32h2/index.rst
+++ b/Documentation/platforms/risc-v/esp32h2/index.rst
@@ -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
==================
diff --git a/Documentation/platforms/xtensa/esp32/index.rst
b/Documentation/platforms/xtensa/esp32/index.rst
index d8559a71b1..115159d646 100644
--- a/Documentation/platforms/xtensa/esp32/index.rst
+++ b/Documentation/platforms/xtensa/esp32/index.rst
@@ -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
==================
diff --git a/Documentation/platforms/xtensa/esp32s2/index.rst
b/Documentation/platforms/xtensa/esp32s2/index.rst
index 47037b72e6..93aa992b4a 100644
--- a/Documentation/platforms/xtensa/esp32s2/index.rst
+++ b/Documentation/platforms/xtensa/esp32s2/index.rst
@@ -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
==================
diff --git a/Documentation/platforms/xtensa/esp32s3/index.rst
b/Documentation/platforms/xtensa/esp32s3/index.rst
index a16c2659ac..23d64b3a51 100644
--- a/Documentation/platforms/xtensa/esp32s3/index.rst
+++ b/Documentation/platforms/xtensa/esp32s3/index.rst
@@ -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
==================
