Merge branch 'doc_update_esp32c6_jtag' into 'master'

docs: JTAG debugging update for ESP32C6 Closes IDF-6033 See merge request espressif/esp-idf!22028
espressif · Jan 18, 2023 · 9d63833 · 9d63833
2 parents fa33755 + 7cb79db
commit 9d63833
Show file tree

Hide file tree

Showing 7 changed files with 92 additions and 50 deletions.
diff --git a/docs/docs_not_updated/esp32c6.txt b/docs/docs_not_updated/esp32c6.txt
@@ -6,17 +6,6 @@ api-guides/performance/speed
 api-guides/performance/size
 api-guides/performance/ram-usage
 api-guides/performance/index
-api-guides/jtag-debugging
-api-guides/jtag-debugging/debugging-examples
-api-guides/jtag-debugging/configure-ft2232h-jtag
-api-guides/jtag-debugging/tips-and-quirks
-api-guides/jtag-debugging/using-debugger
-api-guides/jtag-debugging/building-openocd-macos
-api-guides/jtag-debugging/building-openocd-linux
-api-guides/jtag-debugging/configure-other-jtag
-api-guides/jtag-debugging/building-openocd-windows
-api-guides/jtag-debugging/index
-api-guides/jtag-debugging/configure-builtin-jtag
 api-guides/partition-tables
 api-guides/app_trace
 api-guides/thread-local-storage

diff --git a/docs/en/api-guides/jtag-debugging/configure-builtin-jtag.rst b/docs/en/api-guides/jtag-debugging/configure-builtin-jtag.rst
@@ -6,8 +6,8 @@
 Configure {IDF_TARGET_NAME} built-in JTAG Interface
 ===================================================
 
-{IDF_TARGET_JTAG_PIN_Dneg:default="Not Updated!", esp32c3="GPIO18", esp32s3="GPIO19"} 
-{IDF_TARGET_JTAG_PIN_Dpos:default="Not Updated!", esp32c3="GPIO19", esp32s3="GPIO20"} 
+{IDF_TARGET_JTAG_PIN_Dneg:default="Not Updated!", esp32c3="GPIO18", esp32c6="GPIO12", esp32s3="GPIO19"}
+{IDF_TARGET_JTAG_PIN_Dpos:default="Not Updated!", esp32c3="GPIO19", esp32c6="GPIO13", esp32s3="GPIO20"}
 
 {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.
 

diff --git a/docs/en/api-guides/jtag-debugging/configure-other-jtag.rst b/docs/en/api-guides/jtag-debugging/configure-other-jtag.rst
@@ -2,31 +2,25 @@ Configure Other JTAG Interfaces
 ===============================
 :link_to_translation:`zh_CN:[中文]`
 
-For guidance about which JTAG interface to select when using OpenOCD with {IDF_TARGET_NAME}, refer to the section :ref:`jtag-debugging-selecting-jtag-adapter`. Then follow the configuration steps below to get it working.
+{IDF_TARGET_JTAG_SEL_EFUSE:default="Not Updated!", esp32s3="STRAP_JTAG_SEL", esp32c6="JTAG_SEL_ENABLE"}
 
+For guidance about which JTAG interface to select when using OpenOCD with {IDF_TARGET_NAME}, refer to the section :ref:`jtag-debugging-selecting-jtag-adapter`. Then follow the configuration steps below to get it working.
 
-.. only:: SOC_USB_SERIAL_JTAG_SUPPORTED and not esp32c3
+.. only:: SOC_USB_SERIAL_JTAG_SUPPORTED
 
     Configure eFuses
     ^^^^^^^^^^^^^^^^
 
     By default, {IDF_TARGET_NAME} JTAG interface is connected to the :doc:`built-in USB_SERIAL_JTAG peripheral <configure-builtin-jtag>`. To use an external JTAG adapter instead, you need to switch the JTAG interface to the GPIO pins. This can be done by burning eFuses using ``espefuse.py`` tool.
 
-    - Burning ``DIS_USB_JTAG`` eFuse will permanently disable the connection between USB_SERIAL_JTAG and the JTAG port of the CPU. JTAG interface can then be connected to |jtag-gpio-list|. Note that USB CDC functionality of USB_SERIAL_JTAG will still be usable, i.e., flashing and monitoring over USB CDC will still work.
-    - Burning ``STRAP_JTAG_SEL`` eFuse will enable selection of JTAG interface by a strapping pin, |jtag-sel-gpio|. If the strapping pin is low when {IDF_TARGET_NAME} is reset, JTAG interface will use |jtag-gpio-list|. If the strapping pin is high, USB_SERIAL_JTAG will be used as the JTAG interface.
-
-    .. warning::
-        Burning eFuses is an irreversible operation, so please consider the above options before starting the process.
-
+    .. only:: esp32c3
 
-.. only:: esp32c3
+    Burning ``DIS_USB_JTAG`` eFuse will permanently disable the connection between USB_SERIAL_JTAG and the JTAG port of the {IDF_TARGET_NAME}. JTAG interface can then be connected to |jtag-gpio-list|. Note that USB CDC functionality of USB_SERIAL_JTAG will still be usable, i.e., flashing and monitoring over USB CDC will still work.
 
-    Configure eFuses
-    ^^^^^^^^^^^^^^^^
-
-    By default, {IDF_TARGET_NAME} JTAG interface is connected to the :doc:`built-in USB_SERIAL_JTAG peripheral <configure-builtin-jtag>`. To use an external JTAG adapter instead, you need to switch the JTAG interface to the GPIO pins. This can be done by burning eFuses using ``espefuse.py`` tool.
+    .. only:: esp32s3 or esp32c6
 
-    Burning ``DIS_USB_JTAG`` eFuse will permanently disable the connection between USB_SERIAL_JTAG and the JTAG port of the CPU. JTAG interface can then be connected to |jtag-gpio-list|. Note that USB CDC functionality of USB_SERIAL_JTAG will still be usable, i.e., flashing and monitoring over USB CDC will still work.
+    - Burning ``DIS_USB_JTAG`` eFuse will permanently disable the connection between USB_SERIAL_JTAG and the JTAG port of the {IDF_TARGET_NAME}. JTAG interface can then be connected to |jtag-gpio-list|. Note that USB CDC functionality of USB_SERIAL_JTAG will still be usable, i.e., flashing and monitoring over USB CDC will still work.
+    - Burning ``{IDF_TARGET_JTAG_SEL_EFUSE}`` eFuse will enable selection of JTAG interface by a strapping pin, |jtag-sel-gpio|. If the strapping pin is low when {IDF_TARGET_NAME} is reset, JTAG interface will use |jtag-gpio-list|. If the strapping pin is high, USB_SERIAL_JTAG will be used as the JTAG interface.
 
     .. warning::
         Burning eFuses is an irreversible operation, so please consider the above option before starting the process.

diff --git a/docs/en/api-guides/jtag-debugging/esp32c6.inc b/docs/en/api-guides/jtag-debugging/esp32c6.inc
@@ -6,7 +6,6 @@
 .. (defined in RST, not in Python) inside code blocks. If that is ever implemented,
 .. These code blocks can be moved back to the main .rst files, with target-specific
 .. file names being replaced by substitutions.
-.. TODO IDF-6033
 
 .. run-openocd
 
@@ -22,7 +21,28 @@
 
 ::
 
-    TO BE UPDATED
+    user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32c6-builtin.cfg
+    Open On-Chip Debugger v0.11.0-esp32-20221026-85-g0718fffd (2023-01-12-07:28)
+    Licensed under GNU GPL v2
+    For bug reports, read
+            http://openocd.org/doc/doxygen/bugs.html
+    Info : only one transport option; autoselect 'jtag'
+    Info : esp_usb_jtag: VID set to 0x303a and PID to 0x1001
+    Info : esp_usb_jtag: capabilities descriptor set to 0x2000
+    Warn : Transport "jtag" was already selected
+    WARNING: ESP flash support is disabled!
+    force hard breakpoints
+    Info : Listening on port 6666 for tcl connections
+    Info : Listening on port 4444 for telnet connections
+    Info : esp_usb_jtag: serial (60:55:F9:F6:03:3C)
+    Info : esp_usb_jtag: Device found. Base speed 24000KHz, div range 1 to 255
+    Info : clock speed 24000 kHz
+    Info : JTAG tap: esp32c6.cpu tap/device found: 0x0000dc25 (mfg: 0x612 (Espressif Systems), part: 0x000d, ver: 0x0)
+    Info : datacount=2 progbufsize=16
+    Info : Examined RISC-V core; found 2 harts
+    Info :  hart 0: XLEN=32, misa=0x40903105
+    Info : starting gdb server for esp32c6 on 3333
+    Info : Listening on port 3333 for gdb connections
 
 .. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32c6-builtin.cfg``
 
@@ -68,14 +88,22 @@
 
 .. openocd-cfg-files
 
-.. list-table:: OpenOCD configuration files for ESP32-C3
+.. list-table:: OpenOCD configuration files for ESP32-C6
     :widths: 25 75
     :header-rows: 1
 
     * - Name
       - Description
-    * - TO BE UPDATED
-      - TO BE UPDATED
+    * - ``board/esp32c6-builtin.cfg``
+      - Board configuration file for ESP32-C6 through built-in USB, includes target and adapter configuration.
+    * - ``board/esp32c6-ftdi.cfg``
+      - Board configuration file for ESP32-C6 for via externally connected FTDI-based probe like ESP-Prog, includes target and adapter configuration.
+    * - ``target/esp32c6.cfg``
+      - ESP32-C6 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-C6.
+    * - ``interface/ftdi/esp32_devkitj_v1.cfg``
+      - JTAG adapter configuration file for ESP-Prog boards.
 
 ---
 
@@ -93,17 +121,17 @@
 
     * - ESP32-C6 Pin
       - JTAG Signal
-    * - MTDO
+    * - MTDO / GPIO7
       - TDO
-    * - MTDI
+    * - MTDI / GPIO5
       - TDI
-    * - MTCK
+    * - MTCK / GPIO6
       - TCK
-    * - MTMS
+    * - MTMS / GPIO4
       - TMS
 
-.. |jtag-sel-gpio| replace:: TO BE UPDATED
-.. |jtag-gpio-list| replace:: TO BE UPDATED
+.. |jtag-sel-gpio| replace:: GPIO15
+.. |jtag-gpio-list| replace:: GPIO4-GPIO7
 
 ---
 

diff --git a/docs/en/api-guides/jtag-debugging/index.rst b/docs/en/api-guides/jtag-debugging/index.rst
@@ -206,13 +206,15 @@ Another option is to write application image to flash using OpenOCD via JTAG wit
 
 OpenOCD flashing command ``program_esp`` has the following format:
 
-``program_esp <image_file> <offset> [verify] [reset] [exit]``
+``program_esp <image_file> <offset> [verify] [reset] [exit] [compress] [encrypt]``
 
  - ``image_file`` - Path to program image file.
  - ``offset`` - Offset in flash bank to write image.
  - ``verify`` - Optional. Verify flash contents after writing.
  - ``reset`` - Optional. Reset target after programing.
  - ``exit`` - Optional. Finally exit OpenOCD.
+ - ``compress`` - Optional. Compress image file before programming.
+ - ``encrypt`` - Optional. Encrypt binary before writing to flash. Same functionality with ``idf.py encrypted-flash``
 
 You are now ready to start application debugging. Follow the steps described in the section below.
 

diff --git a/docs/zh_CN/api-guides/jtag-debugging/esp32c6.inc b/docs/zh_CN/api-guides/jtag-debugging/esp32c6.inc
@@ -6,7 +6,6 @@
 .. (defined in RST, not in Python) inside code blocks. If that is ever implemented,
 .. These code blocks can be moved back to the main .rst files, with target-specific
 .. file names being replaced by substitutions.
-.. TODO IDF-6033
 
 .. run-openocd
 
@@ -22,7 +21,28 @@
 
 ::
 
-    TO BE UPDATED
+    user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32c6-builtin.cfg
+    Open On-Chip Debugger v0.11.0-esp32-20221026-85-g0718fffd (2023-01-12-07:28)
+    Licensed under GNU GPL v2
+    For bug reports, read
+            http://openocd.org/doc/doxygen/bugs.html
+    Info : only one transport option; autoselect 'jtag'
+    Info : esp_usb_jtag: VID set to 0x303a and PID to 0x1001
+    Info : esp_usb_jtag: capabilities descriptor set to 0x2000
+    Warn : Transport "jtag" was already selected
+    WARNING: ESP flash support is disabled!
+    force hard breakpoints
+    Info : Listening on port 6666 for tcl connections
+    Info : Listening on port 4444 for telnet connections
+    Info : esp_usb_jtag: serial (60:55:F9:F6:03:3C)
+    Info : esp_usb_jtag: Device found. Base speed 24000KHz, div range 1 to 255
+    Info : clock speed 24000 kHz
+    Info : JTAG tap: esp32c6.cpu tap/device found: 0x0000dc25 (mfg: 0x612 (Espressif Systems), part: 0x000d, ver: 0x0)
+    Info : datacount=2 progbufsize=16
+    Info : Examined RISC-V core; found 2 harts
+    Info :  hart 0: XLEN=32, misa=0x40903105
+    Info : starting gdb server for esp32c6 on 3333
+    Info : Listening on port 3333 for gdb connections
 
 .. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32c6-builtin.cfg``
 
@@ -68,14 +88,22 @@
 
 .. openocd-cfg-files
 
-.. list-table:: OpenOCD configuration files for ESP32-C3
+.. list-table:: OpenOCD configuration files for ESP32-C6
     :widths: 25 75
     :header-rows: 1
 
     * - Name
       - Description
-    * - TO BE UPDATED
-      - TO BE UPDATED
+    * - ``board/esp32c6-builtin.cfg``
+      - Board configuration file for ESP32-C6 through built-in USB, includes target and adapter configuration.
+    * - ``board/esp32c6-ftdi.cfg``
+      - Board configuration file for ESP32-C6 for via externally connected FTDI-based probe like ESP-Prog, includes target and adapter configuration.
+    * - ``target/esp32c6.cfg``
+      - ESP32-C6 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-C6.
+    * - ``interface/ftdi/esp32_devkitj_v1.cfg``
+      - JTAG adapter configuration file for ESP-Prog boards.
 
 ---
 
@@ -93,17 +121,17 @@
 
     * - ESP32-C6 Pin
       - JTAG Signal
-    * - MTDO
+    * - MTDO / GPIO7
       - TDO
-    * - MTDI
+    * - MTDI / GPIO5
       - TDI
-    * - MTCK
+    * - MTCK / GPIO6
       - TCK
-    * - MTMS
+    * - MTMS / GPIO4
       - TMS
 
-.. |jtag-sel-gpio| replace:: TO BE UPDATED
-.. |jtag-gpio-list| replace:: TO BE UPDATED
+.. |jtag-sel-gpio| replace:: GPIO15
+.. |jtag-gpio-list| replace:: GPIO4-GPIO7
 
 ---
 

diff --git a/tools/idf_py_actions/constants.py b/tools/idf_py_actions/constants.py
@@ -41,4 +41,5 @@
     'esp32s2': '-f board/esp32s2-kaluga-1.cfg',
     'esp32c3': '-f board/esp32c3-builtin.cfg',
     'esp32s3': '-f board/esp32s3-builtin.cfg',
+    'esp32c6': '-f board/esp32c6-builtin.cfg',
 }