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 `_. -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 `_ +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 `_ + 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 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 ```` 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 `_. Please check `Building OpenOCD from Sources `_ 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 `_ + 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 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 ```` 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 `_. + +Please check `Building OpenOCD from Sources `_ +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 `_ + 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 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 ```` 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 `_. -You don not need an external JTAG is to debug, the ESP32-H2 integrates a +Please check `Building OpenOCD from Sources `_ +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 `_ + 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 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 `_. Please check `Building OpenOCD from Sources `_ for more information on how to build OpenOCD for ESP32. @@ -165,10 +167,33 @@ Some boards, like :ref:`ESP32-Ethernet-Kit V1.2 `. +.. note:: One must configure the USB drivers to enable JTAG communication. Please check + `Configure USB Drivers `_ + for configuring the JTAG adapter of the :ref:`ESP32-Ethernet-Kit V1.2 ` and + :ref:`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 `_. Please check `Building OpenOCD from Sources `_ 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 `_ + for configuring the JTAG adapter of the :ref:`ESP32-S2-Kaluga-1 ` 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 `_. Please check `Building OpenOCD from Sources `_ 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 ` board. +.. note:: One must configure the USB drivers to enable JTAG communication. Please check + `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 ==================