From 7cb79db71e89a4b676d7e4c8f2e5c122ae8ee530 Mon Sep 17 00:00:00 2001 From: Erhan Kurubas Date: Thu, 12 Jan 2023 07:31:46 +0100 Subject: [PATCH] docs: JTAG debugging update for ESP32C6 --- docs/docs_not_updated/esp32c6.txt | 11 ---- .../jtag-debugging/configure-builtin-jtag.rst | 4 +- .../jtag-debugging/configure-other-jtag.rst | 22 +++----- docs/en/api-guides/jtag-debugging/esp32c6.inc | 50 +++++++++++++++---- docs/en/api-guides/jtag-debugging/index.rst | 4 +- .../api-guides/jtag-debugging/esp32c6.inc | 50 +++++++++++++++---- tools/idf_py_actions/constants.py | 1 + 7 files changed, 92 insertions(+), 50 deletions(-) diff --git a/docs/docs_not_updated/esp32c6.txt b/docs/docs_not_updated/esp32c6.txt index d69f218a22..daf64f9c7c 100644 --- 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 index 028c9242f4..21512c2aec 100644 --- 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 index 13c66c0d8a..9b2fd4b1c5 100644 --- 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:[中文]` +{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 `. 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. + .. only:: esp32c3 - .. warning:: - Burning eFuses is an irreversible operation, so please consider the above options before starting the process. + 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. + .. only:: esp32s3 or esp32c6 -.. only:: esp32c3 - - Configure eFuses - ^^^^^^^^^^^^^^^^ - - By default, {IDF_TARGET_NAME} JTAG interface is connected to the :doc:`built-in USB_SERIAL_JTAG peripheral `. 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 ``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 index 563b64b939..3f7ae0920a 100644 --- 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 index a2187d7dfb..d32fd61ef4 100644 --- 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 [verify] [reset] [exit]`` +``program_esp [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 index 563b64b939..3f7ae0920a 100644 --- 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 index d060823fb8..a9299c0744 100644 --- a/tools/idf_py_actions/constants.py +++ b/tools/idf_py_actions/constants.py @@ -41,4 +41,5 @@ OPENOCD_TAGET_CONFIG: Dict[str, str] = { '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', }