docs: Update CN translation for docs in jtag-degugging

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

@@ -117,13 +117,17 @@ Setup of OpenOCD
 
 .. highlight:: bash
 
-If you have already set up ESP-IDF with CMake build system according to the :doc:`Getting Started Guide <../../get-started/index>`, then OpenOCD is already installed. After :ref:`setting up the environment <get-started-set-up-env>` in your terminal, you should be able to run OpenOCD. Check this by executing the following command::
+If you have already set up ESP-IDF with CMake build system according to the :doc:`Getting Started Guide <../../get-started/index>`, then OpenOCD is already installed. After :ref:`setting up the environment <get-started-set-up-env>` in your terminal, you should be able to run OpenOCD. Check this by executing the following command:
+
+.. code-block:: none
 
     openocd --version
 
 .. highlight:: none
 
-The output should be as follows (although the version may be more recent than listed here)::
+The output should be as follows (although the version may be more recent than listed here):
+
+.. code-block:: none
 
     Open On-Chip Debugger v0.12.0-esp32-20240318 (2024-03-18-18:25)
     Licensed under GNU GPL v2
@@ -276,7 +280,7 @@ Before proceeding to examples, set up your {IDF_TARGET_NAME} target and load it
 .. _jtag-debugging-building-openocd:
 
 Building OpenOCD from Sources
----------------------------------
+-----------------------------
 
 Please refer to separate documents listed below, that describe build process.
 
@@ -318,7 +322,7 @@ and Windows:
 .. _jtag-debugging-tips-and-quirks:
 
 Tips and Quirks
-------------------
+---------------
 
 This section provides collection of links to all tips and quirks referred to from various parts of this guide.
 
@@ -329,7 +333,7 @@ This section provides collection of links to all tips and quirks referred to fro
 
 
 Related Documents
----------------------
+-----------------
 
 .. toctree::
     :hidden:

docs/en/api-guides/jtag-debugging/using-debugger.rst

@@ -35,6 +35,7 @@ Therefore, it is recommended to use the `ESP-IDF GDB OpenOCD Debugging <https://
 **GDB Hardware Debugging**
 
 .. note::
+
     This approach is recommended only if you are unable to debug using `ESP-IDF GDB OpenOCD Debugging <https://github.com/espressif/idf-eclipse-plugin/blob/master/docs/OpenOCD%20Debugging.md#esp-idf-gdb-openocd-debugging>`_ for some reason.
 
 To install the ``GDB Hardware Debugging`` plugin, open Eclipse and select ``Help`` > ``Install`` New Software.
@@ -75,14 +76,17 @@ After installation is complete, follow these steps to configure the debugging se
 
 8.  The last tab that requires changing the default configuration is ``Startup``. Under ``Initialization Commands`` uncheck ``Reset and Delay (seconds)`` and ``Halt``. Then, in the entry field below, enter the following lines:
 
-    ::
+    .. code-block:: none
 
         mon reset halt
         maintenance flush register-cache
         set remote hardware-watchpoint-limit 2
 
     .. note::
-        To automatically update the image in the flash before starting a new debug session, add the following command lines to the beginning of the ``Initialization Commands`` textbox::
+
+        To automatically update the image in the flash before starting a new debug session, add the following command lines to the beginning of the ``Initialization Commands`` textbox:
+
+        .. code-block:: none
 
             mon reset halt
             mon program_esp ${workspace_loc:blink/build/blink.bin} 0x10000 verify
@@ -131,7 +135,7 @@ Command Line
 
 2.  Open a new terminal session and go to the directory that contains the project for debugging, e.g.,
 
-    ::
+    .. code-block:: none
 
         cd ~/esp/blink
 
@@ -154,7 +158,7 @@ Descriptions of the generated ``.gdbinit`` files:
 
     * ``symbols`` - contains symbol sources for debugging.
     * ``prefix_map`` - configures the prefix map to modify source paths in GDB. For more details, see :ref:`reproducible-builds-and-debugging`.
-* ``py_extensions`` - initializes of Python extensions in GDB. Requires Python built with ``libpython`` and Python version supported in GDB. Verify compatibility with ``{IDF_TARGET_TOOLCHAIN_PREFIX}-gdb --batch-silent --ex "python import os"``, which should complete without error.
+    * ``py_extensions`` - initializes Python extensions in GDB. This requires Python built with ``libpython`` and a version supported by GDB. To verify compatibility, run ``{IDF_TARGET_TOOLCHAIN_PREFIX}-gdb --batch-silent --ex "python import os"``, which should complete without errors.
     * ``connect`` - contains commands necessary for establishing a connection to the target device.
 
     To enhance your debugging experience, you can also create custom ``.gdbinit`` files, used either alongside or in place of the generated configurations.
@@ -163,7 +167,7 @@ To enhance your debugging experience, you can also create custom ``.gdbinit`` fi
 
 4.  Now you are ready to launch GDB. Use the following example command to load symbols and connect to the target (``-q`` option added to minimize startup output):
 
-    ::
+    .. code-block:: none
 
         {IDF_TARGET_TOOLCHAIN_PREFIX}-gdb -q -x build/gdbinit/symbols -x build/gdbinit/prefix_map -x build/gdbinit/connect build/blink.elf
 
@@ -171,7 +175,9 @@ To enhance your debugging experience, you can also create custom ``.gdbinit`` fi
 
 5.  If the previous steps have been done correctly, you will see a similar log concluded with the ``(gdb)`` prompt:
 
-    ::
+    .. code-block:: none
+
+        {IDF_TARGET_TOOLCHAIN_PREFIX}-gdb -q -x build/gdbinit/symbols -x build/gdbinit/prefix_map -x build/gdbinit/connect build/blink.elf
 
         user-name@computer-name:~/esp-idf/examples/get-started/blink$ {IDF_TARGET_TOOLCHAIN_PREFIX}-gdb -q -x build/gdbinit/symbols -x build/gdbinit/connect build/blink.elf
         Reading symbols from build/blink.elf...
@@ -190,7 +196,7 @@ To enhance your debugging experience, you can also create custom ``.gdbinit`` fi
         (gdb)
 
 
-Note the third-to-last line, which shows debugger halting at breakpoint established in ``build/gdbinit/connect`` file at function ``app_main()``. Since the processor is halted, the LED should not be blinking. If this is what you see as well, you are ready to start debugging.
+    Note that the third-to-last line indicates the debugger has halted at a breakpoint established in ``build/gdbinit/connect`` file at function ``app_main()``. Since the processor is halted, the LED should not be blinking. If this matches what you observe, you are ready to start debugging.
 
     If you are not sure how to use GDB, check :ref:`jtag-debugging-examples-command-line` example debugging session in section :ref:`jtag-debugging-examples`.
 
@@ -216,7 +222,7 @@ It is also possible to execute the described debugging tools conveniently from `
 
 2.  ``idf.py gdb``
 
-    Starts the GDB the same way as the :ref:`jtag-debugging-using-debugger-command-line`, uses generated GDB scripts referring to the current project elf file, see :ref:`jtag-debugging-using-debugger-command-line`.
+    Starts GDB in the same way as the :ref:`jtag-debugging-using-debugger-command-line`, using generated GDB scripts referring to the current project's ELF file. For more details, see :ref:`jtag-debugging-using-debugger-command-line`.
 
 
 3. ``idf.py gdbtui``
@@ -231,7 +237,9 @@ It is also possible to execute the described debugging tools conveniently from `
 
     You can combine these debugging actions on a single command line, allowing for convenient setup of blocking and non-blocking actions in one step. ``idf.py`` implements a simple logic to move the background actions (such as openocd) to the beginning and the interactive ones (such as gdb, monitor) to the end of the action list.
 
-    An example of a very useful combination is::
+    An example of a very useful combination is:
+
+    .. code-block:: none
 
         idf.py openocd gdbgui monitor
 

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

@@ -117,13 +117,17 @@ JTAG 调试
 
 .. highlight:: bash
 
-如果已经按照 :doc:`快速入门 <../../get-started/index>` 完成了 ESP-IDF 及其 CMake 构建系统的安装，那么 OpenOCD 已经被默认安装到了你的开发系统中。在 :ref:`设置开发环境 <get-started-set-up-env>` 结束后，应该能够在终端中运行如下 OpenOCD 命令::
+如果已经按照 :doc:`快速入门 <../../get-started/index>` 完成了 ESP-IDF 及其 CMake 构建系统的安装，那么 OpenOCD 已经被默认安装到了你的开发系统中。在 :ref:`设置开发环境 <get-started-set-up-env>` 结束后，应该能够在终端中运行如下 OpenOCD 命令：
+
+.. code-block:: none
 
     openocd --version
 
 .. highlight:: none
 
-终端会输出以下信息（实际版本号可能会更新）::
+终端会输出以下信息（实际版本号可能会更新）：
+
+.. code-block:: none
 
     Open On-Chip Debugger v0.12.0-esp32-20240318 (2024-03-18-18:25)
     Licensed under GNU GPL v2
@@ -174,7 +178,7 @@ OpenOCD 安装完成后就可以配置 {IDF_TARGET_NAME} 目标（即带 JTAG
 
 .. highlight:: bash
 
-打开终端，按照快速入门指南中的 :ref:`设置好开发环境 <get-started-set-up-env>` 章节进行操作，然后运行如下命令，以启动 OpenOCD（该命令适用于 Windows、Linux 和 macOS）:
+打开终端，按照《快速入门指南》中的 :ref:`设置开发环境 <get-started-set-up-env>` 章节进行操作。运行 OpenOCD 时，需要提供与目标开发板相关的配置文件。构建项目后，ESP-IDF 会生成 ``build/project_description.json`` 文件，其中 ``debug_arguments_openocd`` 字段保存了默认的 OpenOCD 配置信息。请运行如下命令，以启动 OpenOCD（该命令适用于 Windows、Linux 和 macOS）：
 
 .. include:: {IDF_TARGET_PATH_NAME}.inc
     :start-after: run-openocd
@@ -318,7 +322,7 @@ Windows 用户的示例如下:
 .. _jtag-debugging-tips-and-quirks:
 
 注意事项和补充内容
---------------------
+------------------
 
 本节列出了上文中提到的所有注意事项和补充内容的链接。
 
@@ -329,7 +333,7 @@ Windows 用户的示例如下:
 
 
 相关文档
-------------
+--------
 
 .. toctree::
     :hidden:

docs/zh_CN/api-guides/jtag-debugging/using-debugger.rst

@@ -35,6 +35,7 @@
 **GDB 硬件调试**
 
 .. note::
+
     只有在无法使用 `ESP-IDF GDB OpenOCD 调试 <https://github.com/espressif/idf-eclipse-plugin/blob/master/docs/OpenOCD%20Debugging.md#esp-idf-gdb-openocd-debugging>`_ 的情况下，才建议使用 GDB 硬件调试。
 
 首先，打开 Eclipse，选择 ``Help`` > ``Install New Software`` 来安装 ``GDB Hardware Debugging`` 插件。
@@ -75,14 +76,17 @@
 
 8.  最后一个需要更改默认配置的选项卡是 ``Startup`` 选项卡。在 ``Initialization Commands`` 下，取消选中 ``Reset and Delay (seconds)`` 和 ``Halt``，然后在下面一栏中输入以下命令：
 
-    ::
+    .. code-block:: none
 
         mon reset halt
         maintenance flush register-cache
         set remote hardware-watchpoint-limit 2
 
     .. note::
-        如果想在启动新的调试会话之前自动更新闪存中的镜像，请在 ``Initialization Commands`` 文本框的开头添加以下命令行::
+
+        如果想在启动新的调试会话之前自动更新闪存中的镜像，请在 ``Initialization Commands`` 文本框的开头添加以下命令行:
+
+        .. code-block:: none
 
             mon reset halt
             mon program_esp ${workspace_loc:blink/build/blink.bin} 0x10000 verify
@@ -131,86 +135,68 @@
 
 2.  打开一个新的终端会话并前往待调试的项目目录，比如：
 
-    ::
+    .. code-block:: none
 
         cd ~/esp/blink
 
 .. highlight:: none
 
-3. 当启动调试器时，通常需要提供几个配置参数和命令，为了避免每次都在命令行中逐行输入这些命令，你可以新建一个配置文件，并将其命名为 ``gdbinit``:
+3.  启动调试器时，通常需要提供一些配置参数和命令。构建系统会生成多个 ``.gdbinit`` 文件，以便进行高效调试。这些文件的路径存储在 ``build/project_description.json`` 文件的 ``gdbinit_files`` 字段部分，具体路径如下所示进行定义：
 
-    ::
+    .. code-block:: json
 
-        target remote :3333
+        "gdbinit_files": {
-        set remote hardware-watchpoint-limit 2
+            "01_symbols": "application_path/build/gdbinit/symbols",
-        mon reset halt
+            "02_prefix_map": "application_path/build/gdbinit/prefix_map",
-        maintenance flush register-cache
+            "03_py_extensions": "application_path/build/gdbinit/py_extensions",
-        thb app_main
+            "04_connect": "application_path/build/gdbinit/connect"
-        c
+        }
 
-    将此文件保存在当前目录中。
+    按照 JSON 键名中的 ``XX_`` 前缀进行排序，并以这种顺序将字段信息提供给 GDB。
 
-    有关 ``gdbinit`` 文件内部的更多详细信息，请参阅 :ref:`jtag-debugging-tip-debugger-startup-commands` 章节。
+    生成的 ``.gdbinit`` 文件具有以下不同功能：
+
+    * ``symbols`` - 包含用于调试的符号来源。
+    * ``prefix_map`` - 配置前缀映射以修改 GDB 中的源路径。详情请参阅 :ref:`reproducible-builds-and-debugging`。
+    * ``py_extensions`` - 初始化 GDB 中的 Python 扩展。请注意，应使用包含 ``libpython`` 库、且受 GDB 支持的 Python 版本。若运行以下命令时没有报错，则说明 GDB 和 Python 兼容：``{IDF_TARGET_TOOLCHAIN_PREFIX}-gdb --batch-silent --ex "python import os"``。
+    * ``connect`` - 包含与目标设备建立连接时所需的命令。
+
+    为增强调试体验，你还可以创建自定义的 ``.gdbinit`` 文件。自定义文件可以与生成的配置文件一起使用，也可以直替换它们。
 
 .. highlight:: bash
 
-4. 准备好启动 GDB，请在终端中输入以下内容：
+4.  准备启动 GDB。请使用以下示例命令加载符号表并连接目标设备（命令中的 ``-q`` 选项用于减少启动输出）：
 
-    ::
+    .. code-block:: none
 
-        {IDF_TARGET_TOOLCHAIN_PREFIX}-gdb -x gdbinit build/blink.elf
+        {IDF_TARGET_TOOLCHAIN_PREFIX}-gdb -q -x build/gdbinit/symbols -x build/gdbinit/prefix_map -x build/gdbinit/connect build/blink.elf
 
 .. highlight:: none
 
 5.  如果前面的步骤已经正确完成，你会看到如下所示的输出日志，在日志的最后会出现 ``(gdb)`` 提示符：
 
-    ::
+    .. code-block:: none
 
-        user-name@computer-name:~/esp/blink$ {IDF_TARGET_TOOLCHAIN_PREFIX}-gdb -x gdbinit build/blink.elf
+        {IDF_TARGET_TOOLCHAIN_PREFIX}-gdb -q -x build/gdbinit/symbols -x build/gdbinit/prefix_map -x build/gdbinit/connect build/blink.elf
-        GNU gdb (crosstool-NG crosstool-ng-1.22.0-61-gab8375a) 7.10
-        Copyright (C) 2015 Free Software Foundation, Inc.
-        License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
-        This is free software: you are free to change and redistribute it.
-        There is NO WARRANTY, to the extent permitted by law.  Type "show copying"
-        and "show warranty" for details.
-        This GDB was configured as "--host=x86_64-build_pc-linux-gnu --target={IDF_TARGET_TOOLCHAIN_PREFIX}".
-        Type "show configuration" for configuration details.
-        For bug reporting instructions, please see:
-        <http://www.gnu.org/software/gdb/bugs/>.
-        Find the GDB manual and other documentation resources online at:
-        <http://www.gnu.org/software/gdb/documentation/>.
-        For help, type "help".
-        Type "apropos word" to search for commands related to "word"...
-        Reading symbols from build/blink.elf...done.
-        0x400d10d8 in esp_vApplicationIdleHook () at /home/user-name/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/./freertos_hooks.c:52
-        52          asm("waiti 0");
-        JTAG tap: {IDF_TARGET_PATH_NAME}.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
-        JTAG tap: {IDF_TARGET_PATH_NAME}.slave tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
-        {IDF_TARGET_PATH_NAME}: Debug controller was reset (pwrstat=0x5F, after clear 0x0F).
-        {IDF_TARGET_PATH_NAME}: Core was reset (pwrstat=0x5F, after clear 0x0F).
-        {IDF_TARGET_PATH_NAME} halted. PRO_CPU: PC=0x5000004B (active)    APP_CPU: PC=0x00000000
-        {IDF_TARGET_PATH_NAME}: target state: halted
-        {IDF_TARGET_PATH_NAME}: Core was reset (pwrstat=0x1F, after clear 0x0F).
-        Target halted. PRO_CPU: PC=0x40000400 (active)    APP_CPU: PC=0x40000400
-        {IDF_TARGET_PATH_NAME}: target state: halted
-        Hardware assisted breakpoint 1 at 0x400db717: file /home/user-name/esp/blink/main/./blink.c, line 43.
-        0x0:    0x00000000
-        Target halted. PRO_CPU: PC=0x400DB717 (active)    APP_CPU: PC=0x400D10D8
-        [New Thread 1073428656]
-        [New Thread 1073413708]
-        [New Thread 1073431316]
-        [New Thread 1073410672]
-        [New Thread 1073408876]
-        [New Thread 1073432196]
-        [New Thread 1073411552]
-        [Switching to Thread 1073411996]
 
-        Temporary breakpoint 1, app_main () at /home/user-name/esp/blink/main/./blink.c:43
+        user-name@computer-name:~/esp-idf/examples/get-started/blink$ {IDF_TARGET_TOOLCHAIN_PREFIX}-gdb -q -x build/gdbinit/symbols -x build/gdbinit/connect build/blink.elf
-        43      xTaskCreate(&blink_task, "blink_task", 512, NULL, 5, NULL);
+        Reading symbols from build/blink.elf...
+        add symbol table from file "/home/user-name/esp-idf/examples/get-started/blink/build/bootloader/bootloader.elf"
+        [Switching to Thread 1070141764]
+        app_main () at /home/user-name/esp-idf/examples/get-started/blink/main/blink_example_main.c:95
+        95          configure_led();
+        add symbol table from file "/home/alex/.espressif/tools/esp-rom-elfs/20241011/{IDF_TARGET_PATH_NAME}_rev0_rom.elf"
+        JTAG tap: {IDF_TARGET_PATH_NAME}.tap0 tap/device found: 0x00005c25 (mfg: 0x612 (Espressif Systems), part: 0x0005, ver: 0x0)
+        [{IDF_TARGET_PATH_NAME}] Reset cause (3) - (Software core reset)
+        Hardware assisted breakpoint 1 at 0x42009436: file /home/user-name/esp-idf/examples/get-started/blink/main/blink_example_main.c, line 92.
+        [Switching to Thread 1070139884]
+
+        Thread 2 "main" hit Temporary breakpoint 1, app_main () at /home/user-name/esp-idf/examples/get-started/blink/main/blink_example_main.c:92
+        92      {
         (gdb)
 
 
-注意上面日志的倒数第三行显示了调试器已经在 ``app_main()`` 函数的断点处停止，该断点在 ``gdbinit`` 文件中设定。由于处理器已经暂停运行，LED 不会再闪烁。如果你的 LED 也停止了闪烁，则可以开始调试。
+    请注意，以上日志的倒数第三行显示调试器已在 ``build/gdbinit/connect`` 函数的断点处停止，该断点在 ``gdbinit`` 文件中设定。由于处理器已暂停，LED 将不再闪烁。如果你的 LED 也停止了闪烁，则可以开始调试。
 
     如果不太了解 GDB 的常用方法，请查阅 :ref:`jtag-debugging-examples-command-line` 文章中的调试示例章节 :ref:`jtag-debugging-examples`。
 
@@ -236,7 +222,7 @@
 
 2.  ``idf.py gdb``
 
-    根据当前项目的 elf 文件自动生成 GDB 启动脚本，然后会按照 :ref:`jtag-debugging-using-debugger-command-line` 中所描述的步骤启动 GDB。
+    根据当前项目的 ELF 文件自动生成 GDB 启动脚本，然后按照 :ref:`jtag-debugging-using-debugger-command-line` 中描述的步骤启动 GDB。详情请参阅 :ref:`jtag-debugging-using-debugger-command-line`。
 
 
 3.  ``idf.py gdbtui``
@@ -251,7 +237,9 @@
 
     上述这些命令也可以合并到一起使用，``idf.py`` 会自动将后台进程（比如 openocd）最先运行，交互式进程（比如 GDB，monitor）最后运行。
 
-    常用的组合命令如下所示::
+    常用的组合命令如下所示：
+
+    .. code-block:: none
 
         idf.py openocd gdbgui monitor