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.

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
+Espressif uses a specific version of OpenOCD to support ESP32-C3: `openocd-esp32 <https://github.com/espressif/>`_.
-https://github.com/espressif/openocd-esp32
 
-If you have an ESP32-C3 ECO3, no external JTAG is required to debug, the ESP32-C3
+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>`_
-integrates a USB-to-JTAG adapter.
+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.
+If you want to debug with an external JTAG adapter it can
-It can be connected as follows::
+be connected as follows:
 
-  TMS -> GPIO4
+============ ===========
-  TDI -> GPIO5
+ESP32-C6 Pin JTAG Signal
-  TCK -> GPIO6
+============ ===========
-  TDO -> GPIO7
+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
 ==================
 

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
+ESP32-C3 has a built-in JTAG circuitry and can be debugged without any additional chip.
-integrates a USB-to-JTAG adapter.
+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.
+If you want to debug with an external JTAG adapter it can
-It can be connected as follows::
+be connected as follows:
 
-  TMS -> GPIO4
+============ ===========
-  TDI -> GPIO5
+ESP32-C6 Pin JTAG Signal
-  TCK -> GPIO6
+============ ===========
-  TDO -> GPIO7
+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
 ==================
 

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
+Espressif uses a specific version of OpenOCD to support ESP32-C6: `openocd-esp32 <https://github.com/espressif/>`_.
-https://github.com/espressif/openocd-esp32
+
+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
+ESP32-C6 Pin JTAG Signal
-  TCK -> GPIO6
+============ ===========
-  TDO -> GPIO7
+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
 ==================
 

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
+Espressif uses a specific version of OpenOCD to support ESP32-H2: `openocd-esp32 <https://github.com/espressif/>`_.
-https://github.com/espressif/openocd-esp32
 
-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
+ESP32-H2 Pin JTAG Signal
-  TCK -> GPIO5
+============ ===========
-  TDO -> GPIO3
+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
 ==================
 

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
 ==================
 

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
 ==================
 

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
 ==================