Merge branch 'jtag_doc_update' into 'master'

erhankur · erhankur · commit ffdf59a89851 · 2024-10-01T18:03:39.000+08:00
docs(jtag): update OpenOCD related sections

See merge request espressif/esp-idf!33516
diff --git a/components/xtensa/trax/test/gdbinit b/components/xtensa/trax/test/gdbinit
@@ -3,7 +3,7 @@ set confirm off
 
 # Start OpenOCD and run to the entry function
 file test.elf
-target remote | openocd -c "log_output openocd.log; set ESP_RTOS none; set ESP_FLASH_SIZE 0; set ESP32_ONLYCPU 1" -f board/esp32-ethernet-kit-3.3v.cfg -c "gdb_port pipe; init; reset halt"
+target remote | openocd -c "log_output openocd.log; set ESP_RTOS none; set ESP_FLASH_SIZE 0; set ESP_ONLYCPU 1" -f board/esp32-ethernet-kit-3.3v.cfg -c "gdb_port pipe; init; reset halt"
 thb entry
 c
 
diff --git a/docs/en/api-guides/jtag-debugging/esp32.inc b/docs/en/api-guides/jtag-debugging/esp32.inc
@@ -112,7 +112,7 @@
       - Description
     * - ``ESP32_FLASH_VOLTAGE``
       - When using 1.8 V flash ESP32 based modules, set this variable to ``1.8``. Refer to :ref:`jtag-debugging-tip-code-flash-voltage`.
-    * - ``ESP32_ONLYCPU``
+    * - ``ESP_ONLYCPU``
       - For multi-core targets, can be set to ``1`` to only enable single core debugging.
 
 ---
diff --git a/docs/en/api-guides/jtag-debugging/esp32p4.inc b/docs/en/api-guides/jtag-debugging/esp32p4.inc
@@ -29,20 +29,25 @@
     Info : only one transport option; autoselecting 'jtag'
     Info : esp_usb_jtag: VID set to 0x303a and PID to 0x1001
     Info : esp_usb_jtag: capabilities descriptor set to 0x2000
-    adapter speed: 40000 kHz
-    Info : esp_usb_jtag: serial (60:55:F9:F8:80:5C)
+    Info : Listening on port 6666 for tcl connections
+    Info : Listening on port 4444 for telnet connections
+    Info : esp_usb_jtag: serial (60:55:F9:F9:04:AD)
     Info : esp_usb_jtag: Device found. Base speed 24000KHz, div range 1 to 255
     Info : clock speed 24000 kHz
-    Info : JTAG tap: esp32p4.lp.cpu tap/device found: 0x00012c25 (mfg: 0x612 (Espressif Systems), part: 0x0012, ver: 0x0)
-    Info : JTAG tap: esp32p4.hp.cpu tap/device found: 0x00012c25 (mfg: 0x612 (Espressif Systems), part: 0x0012, ver: 0x0)
-    Info : [esp32p4.hp.cpu] datacount=1 progbufsize=2
-    Info : [esp32p4.hp.cpu] Examined RISC-V core; found 2 harts
-    Info : [esp32p4.hp.cpu]  XLEN=32, misa=0x40901125
-    Info : [esp32p4.hp.cpu] Examination succeed
-    Info : starting gdb server for esp32p4.hp.cpu on 3333
+    Info : JTAG tap: esp32p4.tap0 tap/device found: 0x00012c25 (mfg: 0x612 (Espressif Systems), part: 0x0012, ver: 0x0)
+    Info : JTAG tap: esp32p4.tap1 tap/device found: 0x00012c25 (mfg: 0x612 (Espressif Systems), part: 0x0012, ver: 0x0)
+    Info : [esp32p4.hp.cpu0] datacount=1 progbufsize=2
+    Info : [esp32p4.hp.cpu0] Core 0 made part of halt group 1.
+    Info : [esp32p4.hp.cpu0] Examined RISC-V core; found 2 harts
+    Info : [esp32p4.hp.cpu0]  XLEN=32, misa=0x40901125
+    Info : [esp32p4.hp.cpu0] Examination succeed
+    Info : [esp32p4.hp.cpu1] datacount=1 progbufsize=2
+    Info : [esp32p4.hp.cpu1] Core 1 made part of halt group 1.
+    Info : [esp32p4.hp.cpu1] Examined RISC-V core; found 2 harts
+    Info : [esp32p4.hp.cpu1]  XLEN=32, misa=0x40901125
+    Info : [esp32p4.hp.cpu1] Examination succeed
+    Info : [esp32p4.hp.cpu0] starting gdb server on 3333
     Info : Listening on port 3333 for gdb connections
-    Info : Listening on port 6666 for tcl connections
-    Info : Listening on port 4444 for telnet connections
 
 .. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32p4-builtin.cfg``
 
diff --git a/docs/en/api-guides/jtag-debugging/index.rst b/docs/en/api-guides/jtag-debugging/index.rst
@@ -226,6 +226,8 @@ OpenOCD flashing command ``program_esp`` has the following format:
  - ``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``
+ - ``no_clock_boost`` - Optional. Disable setting target clock frequency to its maximum possible value before programming. Clock boost is enabled by default.
+ - ``restore_clock`` - Optional. Restore clock frequency to its initial value after programming. Disabled by default.
 
 You are now ready to start application debugging. Follow the steps described in the section below.
 
diff --git a/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst b/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst
@@ -83,7 +83,7 @@ GDB has a Python extension for FreeRTOS support. ESP-IDF automatically loads thi
 
     The MTDI pin of ESP32, being among four pins used for JTAG communication, is also one of ESP32's bootstrapping pins. On power up ESP32 is sampling binary level on MTDI to set it's internal voltage regulator used to supply power to external SPI flash chip. If binary level on MDTI pin on power up is low, the voltage regulator is set to deliver 3.3 V, if it is high, then the voltage is set to 1.8 V. The MTDI pin should have a pull-up or may rely on internal weak pull down resistor (see `ESP32 Series Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_ for details), depending on the type of SPI chip used. Once JTAG is connected, it overrides the pull-up or pull-down resistor that is supposed to do the bootstrapping.
 
-    To handle this issue OpenOCD's board configuration file (e.g. ``board\esp32-wrover-kit-3.3v.cfg`` for ESP-WROVER-KIT board) provides ``ESP32_FLASH_VOLTAGE`` parameter to set the idle state of the ``TDO`` line to a specified binary level, therefore reducing the chance of a bad bootup of application due to incorrect flash voltage.
+    To handle this issue OpenOCD's board configuration file (e.g. ``board\esp32-wrover-kit-3.3v.cfg`` for ESP-WROVER-KIT board) provides ``ESP32_FLASH_VOLTAGE`` parameter to set the idle state of the ``TDO`` line to a specified binary level, therefore reducing the chance of a bad boot-up of application due to incorrect flash voltage.
 
     Check specification of ESP32 module connected to JTAG, what is the power supply voltage of SPI flash chip. Then set ``ESP32_FLASH_VOLTAGE`` accordingly. Most WROOM modules use 3.3 V flash. WROVER earlier than ESP32-WROVER-B use 1.8 V flash, while ESP32-WROVER-B and -E modules use 3.3 V flash.
 
@@ -178,6 +178,8 @@ It is important to set the variable before including the ESP-specific configurat
       - Set to ``0`` to disable Flash breakpoints support.
     * - ``ESP_SEMIHOST_BASEDIR``
       - Set to the path (on the host) which will be the default directory for semihosting functions.
+    * - ``ESP_ONLYCPU``
+      - For multi-core targets, can be set to ``1`` to only enable single core debugging.
 
 .. include:: {IDF_TARGET_PATH_NAME}.inc
     :start-after: openocd-target-specific-config-vars
diff --git a/docs/zh_CN/api-guides/jtag-debugging/esp32.inc b/docs/zh_CN/api-guides/jtag-debugging/esp32.inc
@@ -112,7 +112,7 @@
       - 描述
     * - ``ESP32_FLASH_VOLTAGE``
       - 如果 ESP32 模组集成的是 1.8 V 的 flash，将该变量设置为 ``1.8``，详情请参考 :ref:`jtag-debugging-tip-code-flash-voltage`
-    * - ``ESP32_ONLYCPU``
+    * - ``ESP_ONLYCPU``
       - 对于多核芯片，将该值设置为 ``1`` 可以仅启用单核调试功能
 
 ---
diff --git a/docs/zh_CN/api-guides/jtag-debugging/esp32p4.inc b/docs/zh_CN/api-guides/jtag-debugging/esp32p4.inc
@@ -29,20 +29,25 @@
     Info : only one transport option; autoselecting 'jtag'
     Info : esp_usb_jtag: VID set to 0x303a and PID to 0x1001
     Info : esp_usb_jtag: capabilities descriptor set to 0x2000
-    adapter speed: 40000 kHz
-    Info : esp_usb_jtag: serial (60:55:F9:F8:80:5C)
+    Info : Listening on port 6666 for tcl connections
+    Info : Listening on port 4444 for telnet connections
+    Info : esp_usb_jtag: serial (60:55:F9:F9:04:AD)
     Info : esp_usb_jtag: Device found. Base speed 24000KHz, div range 1 to 255
     Info : clock speed 24000 kHz
-    Info : JTAG tap: esp32p4.lp.cpu tap/device found: 0x00012c25 (mfg: 0x612 (Espressif Systems), part: 0x0012, ver: 0x0)
-    Info : JTAG tap: esp32p4.hp.cpu tap/device found: 0x00012c25 (mfg: 0x612 (Espressif Systems), part: 0x0012, ver: 0x0)
-    Info : [esp32p4.hp.cpu] datacount=1 progbufsize=2
-    Info : [esp32p4.hp.cpu] Examined RISC-V core; found 2 harts
-    Info : [esp32p4.hp.cpu]  XLEN=32, misa=0x40901125
-    Info : [esp32p4.hp.cpu] Examination succeed
-    Info : starting gdb server for esp32p4.hp.cpu on 3333
+    Info : JTAG tap: esp32p4.tap0 tap/device found: 0x00012c25 (mfg: 0x612 (Espressif Systems), part: 0x0012, ver: 0x0)
+    Info : JTAG tap: esp32p4.tap1 tap/device found: 0x00012c25 (mfg: 0x612 (Espressif Systems), part: 0x0012, ver: 0x0)
+    Info : [esp32p4.hp.cpu0] datacount=1 progbufsize=2
+    Info : [esp32p4.hp.cpu0] Core 0 made part of halt group 1.
+    Info : [esp32p4.hp.cpu0] Examined RISC-V core; found 2 harts
+    Info : [esp32p4.hp.cpu0]  XLEN=32, misa=0x40901125
+    Info : [esp32p4.hp.cpu0] Examination succeed
+    Info : [esp32p4.hp.cpu1] datacount=1 progbufsize=2
+    Info : [esp32p4.hp.cpu1] Core 1 made part of halt group 1.
+    Info : [esp32p4.hp.cpu1] Examined RISC-V core; found 2 harts
+    Info : [esp32p4.hp.cpu1]  XLEN=32, misa=0x40901125
+    Info : [esp32p4.hp.cpu1] Examination succeed
+    Info : [esp32p4.hp.cpu0] starting gdb server on 3333
     Info : Listening on port 3333 for gdb connections
-    Info : Listening on port 6666 for tcl connections
-    Info : Listening on port 4444 for telnet connections
 
 .. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32p4-builtin.cfg``
 
diff --git a/docs/zh_CN/api-guides/jtag-debugging/index.rst b/docs/zh_CN/api-guides/jtag-debugging/index.rst
@@ -226,6 +226,8 @@ OpenOCD 安装完成后就可以配置 {IDF_TARGET_NAME} 目标（即带 JTAG 
 -  ``exit`` - 烧写完成后退出 OpenOCD（可选）
 - ``compress`` - 烧写开始前压缩镜像文件（可选）
 - ``encrypt`` - 烧写到 flash 前加密二进制文件，与 ``idf.py encrypted-flash`` 功能相同（可选）
+- ``no_clock_boost`` - 禁用在烧写前将目标时钟频率设置为其最大可能值（可选）。默认情况下禁用该选项，即默认启用时钟提升。
+- ``restore_clock`` - 可选。烧写完成后将时钟频率恢复到初始值。默认情况下不启用。
 
 现在可以调试应用程序了，请按照以下章节中的步骤进行操作。
 
diff --git a/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst b/docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst
@@ -178,6 +178,8 @@ TCL 语言中为变量赋值的语法是:
       - 设置成 ``0`` 可以关闭对 flash 断点的支持。
     * - ``ESP_SEMIHOST_BASEDIR``
       - 设置 semihosting 在主机端的默认目录。
+    * - ``ESP_ONLYCPU``
+      - 对于多核芯片，将该值设置为 ``1`` 可以仅启用单核调试功能
 
 .. include:: {IDF_TARGET_PATH_NAME}.inc
     :start-after: openocd-target-specific-config-vars

Original file line number	Diff line number	Diff line change
`@@ -3,7 +3,7 @@ set confirm off`
`3`	`3`
`4`	`4`	`# Start OpenOCD and run to the entry function`
`5`	`5`	`file test.elf`
`6`		`-target remote \| openocd -c "log_output openocd.log; set ESP_RTOS none; set ESP_FLASH_SIZE 0; set ESP32_ONLYCPU 1" -f board/esp32-ethernet-kit-3.3v.cfg -c "gdb_port pipe; init; reset halt"`
	`6`	`+target remote \| openocd -c "log_output openocd.log; set ESP_RTOS none; set ESP_FLASH_SIZE 0; set ESP_ONLYCPU 1" -f board/esp32-ethernet-kit-3.3v.cfg -c "gdb_port pipe; init; reset halt"`
`7`	`7`	`thb entry`
`8`	`8`	`c`
`9`	`9`