docs: Update JTAG debugging guides for ESP32-C3

docs/conf_common.py

@@ -166,6 +166,10 @@ USB_DOCS = ['api-reference/peripherals/usb.rst',
             'api-guides/usb-console.rst',
             'api-guides/dfu.rst']
 
+FTDI_JTAG_DOCS = ['api-guides/jtag-debugging/configure-ft2232h-jtag.rst']
+
+BUILTIN_JTAG_DOCS = ['api-guides/jtag-debugging/configure-builtin-jtag.rst']
+
 ULP_DOCS = ['api-guides/ulp.rst', 'api-guides/ulp_macros.rst']
 
 RISCV_COPROC_DOCS = ['api-guides/ulp-risc-v.rst',]
@@ -183,7 +187,7 @@ ESP32_DOCS = ['api-guides/ulp_instruction_set.rst',
               'security/secure-boot-v1.rst',
               'api-reference/peripherals/secure_element.rst',
               'api-reference/peripherals/dac.rst',
-              'hw-reference/esp32/**'] + LEGACY_DOCS
+              'hw-reference/esp32/**'] + LEGACY_DOCS + FTDI_JTAG_DOCS
 
 ESP32S2_DOCS = ['hw-reference/esp32s2/**',
                 'api-guides/ulps2_instruction_set.rst',
@@ -194,9 +198,9 @@ ESP32S2_DOCS = ['hw-reference/esp32s2/**',
                 'api-reference/peripherals/temp_sensor.rst',
                 'api-reference/system/async_memcpy.rst',
                 'api-reference/peripherals/touch_element.rst',
-                'api-reference/peripherals/dac.rst']
+                'api-reference/peripherals/dac.rst'] + FTDI_JTAG_DOCS
 
-ESP32C3_DOCS = ['hw-reference/esp32c3/**']
+ESP32C3_DOCS = ['hw-reference/esp32c3/**'] + BUILTIN_JTAG_DOCS
 
 # format: {tag needed to include: documents to included}, tags are parsed from sdkconfig and peripheral_caps.h headers
 conditional_include_dict = {'SOC_BT_SUPPORTED':BT_DOCS,

docs/en/api-guides/jtag-debugging/configure-builtin-jtag.rst

@@ -0,0 +1,36 @@
+.. include:: {IDF_TARGET_PATH_NAME}.inc
+   :start-after: devkit-defs
+   :end-before: ---
+
+
+Configure {IDF_TARGET_NAME} built-in JTAG Interface
+===================================================
+
+{IDF_TARGET_NAME} 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. The necessary connections are shown in the following section.
+
+Configure Hardware
+^^^^^^^^^^^^^^^^^^
+
+.. list-table:: ESP32-C3 pins and USB signals
+    :widths: 25 75
+    :header-rows: 1
+
+    * - ESP32-C3 Pin
+      - USB Signal
+    * - GPIO18
+      - D-
+    * - GPIO19
+      - D+
+    * - 5V
+      - V_BUS
+    * - GND
+      - Ground
+
+Please verify that the {IDF_TARGET_NAME} pins used for USB communication are not connected to some other HW that may disturb the JTAG operation.
+
+Configure USB Drivers
+^^^^^^^^^^^^^^^^^^^^^
+
+JTAG communication should work out-of-box on Linux and macOS. Windows users might get `LIBUSB_ERROR_NOT_FOUND` errors.
+This is a known issue and will be addressed soon.

docs/en/api-guides/jtag-debugging/esp32c3.inc

@@ -7,14 +7,13 @@
 .. These code blocks can be moved back to the main .rst files, with target-specific
 .. file names being replaced by substitutions.
 
-
 .. run-openocd
 
 ::
 
-    openocd -f board/Xcfg
+    openocd -f board/esp32c3-builtin.cfg
 
-.. |run-openocd-device-name| replace:: ESP32-S2-Kaluga-1 board
+.. |run-openocd-device-name| replace:: ESP32-C3 through built-in USB connection
 
 ---
 
@@ -22,21 +21,25 @@
 
 ::
 
-    user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32s2-kaluga-1.cfg
+    user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32c3-builtin.cfg
-    Open On-Chip Debugger  v0.10.0-esp32-20200420 (2020-04-20-16:15)
+    Open On-Chip Debugger v0.10.0-esp32-20201202-26-g05a036c2 (2021-03-15-17:18)
     Licensed under GNU GPL v2
     For bug reports, read
-            http://openocd.org/doc/doxygen/bugs.html
+        http://openocd.org/doc/doxygen/bugs.html
-    none separate
+    Info : only one transport option; autoselect 'jtag'
-    adapter speed: 20000 kHz
+    Warn : Transport "jtag" was already selected
     force hard breakpoints
-    Info : ftdi: if you experience problems at higher adapter clocks, try the command "ftdi_tdo_sample_edge falling"
+    Info : Listening on port 6666 for tcl connections
-    Info : clock speed 20000 kHz
+    Info : Listening on port 4444 for telnet connections
-    Info : JTAG tap: esp32s2.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
+    Info : esp_usb_jtag: Device found. Base speed 40000KHz, div range 1 to 255
-    Info : esp32s2: Debug controller was reset (pwrstat=0x5F, after clear 0x0F).
+    Info : clock speed 40000 kHz
-    Info : esp32s2: Core was reset (pwrstat=0x5F, after clear 0x0F).
+    Info : JTAG tap: esp32c3.cpu tap/device found: 0x00005c25 (mfg: 0x612 (Espressif Systems), part: 0x0005, ver: 0x0)
+    Info : datacount=2 progbufsize=16
+    Info : Examined RISC-V core; found 1 harts
+    Info :  hart 0: XLEN=32, misa=0x40101104
+    Info : Listening on port 3333 for gdb connections
 
-.. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32s2-kaluga-1.cfg``
+.. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32c3-builtin.cfg``
 
 ---
 
@@ -44,7 +47,7 @@
 
 ::
 
-    openocd -f board/esp32s2-kaluga-1.cfg -c "program_esp filename.bin 0x10000 verify exit"
+    openocd -f board/esp32c3-builtin.cfg -c "program_esp filename.bin 0x10000 verify exit"
 
 ---
 
@@ -52,7 +55,7 @@
 
 .. code-block:: bash
 
-    src/openocd -f board/esp32s2-kaluga-1.cfg
+    src/openocd -f board/esp32c3-builtin.cfg
 
 ---
 
@@ -60,13 +63,13 @@
 
 .. code-block:: batch
 
-    src\openocd -f board/esp32s2-kaluga-1.cfg
+    src\openocd -f board/esp32c3-builtin.cfg
 
 ---
 
 .. idf-py-openocd-default-cfg
 
-.. |idf-py-def-cfg| replace:: ``-f board/esp32s2-kaluga-1.cfg``
+.. |idf-py-def-cfg| replace:: ``-f board/esp32c3-builtin.cfg``
 
 ---
 
@@ -74,24 +77,26 @@
 
 ::
 
-    openocd -f board/esp32s2-kaluga-1.cfg -c "init; halt; esp appimage_offset 0x210000"
+    openocd -f board/esp32c3-builtin.cfg -c "init; halt; esp appimage_offset 0x210000"
 
 ---
 
 .. openocd-cfg-files
 
-.. list-table:: OpenOCD configuration files for ESP32-S2
+.. list-table:: OpenOCD configuration files for ESP32-C3
     :widths: 25 75
     :header-rows: 1
 
     * - Name
       - Description
-    * - ``board/esp32s2-kaluga-1.cfg``
+    * - ``board/esp32c3-builtin.cfg``
-      - Board configuration file for ESP32-S2-Kaluga-1, includes target and adapter configuration.
+      - Board configuration file for ESP32-C3 through built-in USB, includes target and adapter configuration.
-    * - ``target/esp32s2.cfg``
+    * - ``board/esp32c3-ftdi.cfg``
-      - ESP32-S2 target configuration file. Can be used together with one of the ``interface/`` configuration files.
+      - Board configuration file for ESP32-C3 debug through an ESP-Prog compatible FTDI, includes target and adapter configuration.
-    * - ``interface/ftdi/esp32s2_kaluga_v1.cfg``
+    * - ``target/esp32c3.cfg``
-      - JTAG adapter configuration file for ESP32-S2-Kaluga-1 board.
+      - ESP32-C3 target configuration file. Can be used together with one of the ``interface/`` configuration files.
+    * - ``interface/esp_usb_jtag.cfg``
+      - JTAG adapter configuration file for ESP32-C3.
     * - ``interface/ftdi/esp32_devkitj_v1.cfg``
       - JTAG adapter configuration file for ESP-Prog boards.
 
@@ -105,19 +110,19 @@
 
 .. jtag-pins
 
-.. list-table:: ESP32-S2 pins and JTAG signals
+.. list-table:: ESP32-C3 pins and JTAG signals
     :widths: 25 75
     :header-rows: 1
 
-    * - ESP32-S2 Pin
+    * - ESP32-C3 Pin
       - JTAG Signal
-    * - MTDO / GPIO40
+    * - MTDO / GPIO7
       - TDO
-    * - MTDI / GPIO41
+    * - MTDI / GPIO5
       - TDI
-    * - MTCK / GPIO39
+    * - MTCK / GPIO6
       - TCK
-    * - MTMS / GPIO42
+    * - MTMS / GPIO4
       - TMS
 
 ---
@@ -126,7 +131,7 @@
 
 ::
 
-    openocd -l openocd_log.txt -d3 -f board/esp32s2-kaluga-1.cfg
+    openocd -l openocd_log.txt -d3 -f board/esp32c3-builtin.cfg
 
 ---
 
@@ -134,7 +139,7 @@
 
 ::
 
-    openocd -d3 -f board/esp32s2-kaluga-1.cfg 2>&1 | tee openocd.log
+    openocd -d3 -f board/esp32c3-builtin.cfg 2>&1 | tee openocd.log
 
 ---
 
@@ -142,19 +147,19 @@
 
 ::
 
-    xtensa-esp32s2-elf-gdb -ex "set remotelogfile gdb_log.txt" <all other options>
+    riscv32-esp-elf-gdb -ex "set remotelogfile gdb_log.txt" <all other options>
 
 ---
 
 .. devkit-defs
 
-.. |devkit-name| replace:: ESP-S2-Kaluga-1
+.. |devkit-name| replace:: ESP32-C3
-.. |devkit-name-with-link| replace:: :doc:`ESP-S2-Kaluga-1 <../../hw-reference/modules-and-boards>`
+.. |devkit-name-with-link| replace:: :doc:`ESP32-C3 <../../hw-reference/modules-and-boards>`
 
 ---
 
 .. devkit-hw-config
 
-* Out of the box, ESP32-S2-Kaluga-1 doesn't need any additional hardware configuration for JTAG debugging. However if you are experiencing issues, check that switches 2-5 of the "JTAG" DIP switch block are in "ON" position.
+* Out of the box, ESP32-C3 doesn't need any additional hardware configuration for JTAG debugging.
 
 ---

docs/en/api-guides/jtag-debugging/index.rst

@@ -66,7 +66,17 @@ Under "Application Loading and Monitoring" there is another software and hardwar
 
 Debugging using JTAG and application loading / monitoring is integrated under the `Eclipse <https://www.eclipse.org/>`_ environment, to provide quick and easy transition from writing, compiling and loading the code to debugging, back to writing the code, and so on. All the software is available for Windows, Linux and MacOS platforms.
 
-If the |devkit-name-with-link| is used, then connection from PC to {IDF_TARGET_NAME} is done effectively with a single USB cable. This is made possible by the FT2232H chip, which provides two USB channels, one for JTAG and the one for UART connection.
+.. only:: not esp32c3
+
+    If the |devkit-name-with-link| is used, then connection from PC to {IDF_TARGET_NAME} is done effectively with a single USB cable. This is made possible by the FT2232H chip, which provides two USB channels, one for JTAG and the one for UART connection.
+
+.. only:: esp32c3
+
+    The connection from PC to {IDF_TARGET_NAME} is done effectively with a single USB cable. This is made possible by the {IDF_TARGET_NAME} chip itself, which provides two USB channels, one for JTAG and one for the USB terminal connection. The USB cable should be connected the D+/D- USB pins of {IDF_TARGET_NAME} and not to the serial RxD/TxD throught an USB-to-UART chip. The proper connection is explained later in subsection :ref:`jtag-debugging-configuring-target`.
+
+    .. note::
+
+        Debugging through the USB interface implemented in {IDF_TARGET_NAME} requires to have a chip with revision 3 or newer. Please use other debugging options (e.g. with ESP-Prog) for chip revision 1 and 2. The easiest way to determine the chip revision is to look for the `Chip is ESP32-C3 (revision 3)` message near the end of a successful chip flashing done by `idf.py flash`.
 
 Depending on user preferences, both `debugger` and `idf.py build` can be operated directly from terminal/command line, instead from Eclipse.
 
@@ -76,7 +86,13 @@ Depending on user preferences, both `debugger` and `idf.py build` can be operate
 Selecting JTAG Adapter
 ----------------------
 
-The quickest and most convenient way to start with JTAG debugging is by using |devkit-name-with-link|. Each version of this development board has JTAG interface already build in. No need for an external JTAG adapter and extra wiring / cable to connect JTAG to {IDF_TARGET_NAME}. |devkit-name| is using FT2232H JTAG interface operating at 20 MHz clock speed, which is difficult to achieve with an external adapter.
+.. only:: not esp32c3
+
+    The quickest and most convenient way to start with JTAG debugging is by using |devkit-name-with-link|. Each version of this development board has JTAG interface already built in. No need for an external JTAG adapter and extra wiring / cable to connect JTAG to {IDF_TARGET_NAME}. |devkit-name| is using FT2232H JTAG interface operating at 20 MHz clock speed, which is difficult to achieve with an external adapter.
+
+.. only:: esp32c3
+
+    The quickest and most convenient way to start with JTAG debugging is through an USB cable connected to the D+/D- USB pins of {IDF_TARGET_NAME}. No need for an external JTAG adapter and extra wiring / cable to connect JTAG to {IDF_TARGET_NAME}.
 
 If you decide to use separate JTAG adapter, look for one that is compatible with both the voltage levels on the {IDF_TARGET_NAME} as well as with the OpenOCD software. The JTAG port on the {IDF_TARGET_NAME} is an industry-standard JTAG port which lacks (and does not need) the TRST pin. The JTAG I/O pins all are powered from the VDD_3P3_RTC pin (which normally would be powered by a 3.3 V rail) so the JTAG adapter needs to be able to work with JTAG pins in that voltage range.
 
@@ -84,6 +100,7 @@ On the software side, OpenOCD supports a fair amount of JTAG adapters. See http:
 
 The minimal signalling to get a working JTAG connection are TDI, TDO, TCK, TMS and GND. Some JTAG debuggers also need a connection from the {IDF_TARGET_NAME} power line to a line called e.g. Vtar to set the working voltage. SRST can optionally be connected to the CH_PD of the {IDF_TARGET_NAME}, although for now, support in OpenOCD for that line is pretty minimal.
 
+`ESP-Prog <https://docs.espressif.com/projects/espressif-esp-iot-solution/en/latest/hw-reference/ESP-Prog_guide.html>`_ is an example for using an external board for debugging by connecting it to the JTAG pins of {IDF_TARGET_NAME}.
 
 .. _jtag-debugging-setup-openocd:
 
@@ -133,7 +150,9 @@ This step depends on JTAG and {IDF_TARGET_NAME} board you are using - see the tw
 .. toctree::
     :maxdepth: 1
 
-    configure-ft2232h-jtag
+    :esp32: configure-ft2232h-jtag
+    :esp32s2: configure-ft2232h-jtag
+    :esp32c3: configure-builtin-jtag
     configure-other-jtag
 
 
@@ -156,6 +175,11 @@ Open a terminal and set it up for using the ESP-IDF as described in the :ref:`se
 
     The files provided after ``-f`` above are specific for |run-openocd-device-name|. You may need to provide different files depending on used hardware. For guidance see :ref:`jtag-debugging-tip-openocd-configure-target`.
 
+    .. only:: esp32c3
+
+    For example, ``board/esp32c3-ftdi.cfg`` can be used for a custom board with an FT2232H or FT232H chip used for JTAG connection,
+    or with ESP-Prog.
+
 .. highlight:: none
 
 You should now see similar output (this log is for |run-openocd-device-name|):

docs/zh_CN/api-guides/jtag-debugging/configure-builtin-jtag.rst

@@ -0,0 +1 @@
+.. include:: ../../../en/api-guides/jtag-debugging/configure-builtin-jtag.rst

docs/zh_CN/api-guides/jtag-debugging/index.rst

@@ -133,7 +133,9 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G
 .. toctree::
     :maxdepth: 1
 
-    configure-ft2232h-jtag
+    :esp32: configure-ft2232h-jtag
+    :esp32s2: configure-ft2232h-jtag
+    :esp32c3: configure-builtin-jtag
     configure-other-jtag
 
 
@@ -302,4 +304,4 @@ Windows 用户:
 - :doc:`debugging-examples`
 - :doc:`tips-and-quirks`
 - :doc:`../app_trace`
-- `ESP-Prog 调试板介绍 <https://docs.espressif.com/projects/espressif-esp-iot-solution/zh_CN/latest/hw-reference/ESP-Prog_guide.html>`__ 
+- `ESP-Prog 调试板介绍 <https://docs.espressif.com/projects/espressif-esp-iot-solution/zh_CN/latest/hw-reference/ESP-Prog_guide.html>`__