Merge branch 'docs/update_CN_trans' into 'master'

Docs/update cn trans for memory-types and tips-and-quirks

Closes DOC-4267

See merge request espressif/esp-idf!21827

docs/en/api-guides/jtag-debugging/tips-and-quirks.rst

@@ -10,16 +10,16 @@ This section provides collection of all tips and quirks referred to from various
 
 .. _jtag-debugging-tip-breakpoints:
 
-Breakpoints and watchpoints available
+Breakpoints and Watchpoints Available
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-{IDF_TARGET_NAME} debugger supports {IDF_TARGET_CPU_BREAKPOINT_NUM} hardware implemented breakpoints and 64 software ones. Hardware breakpoints are implemented by {IDF_TARGET_NAME} chip's logic and can be set anywhere in the code: either in flash or IRAM program's regions. Additionally there are 2 types of software breakpoints implemented by OpenOCD: flash (up to 32) and IRAM (up to 32) breakpoints. Currently GDB can not set software breakpoints in flash. So until this limitation is removed those breakpoints have to be emulated by OpenOCD as hardware ones (see :ref:`below <jtag-debugging-tip-where-breakpoints>` for details). {IDF_TARGET_NAME} also supports {IDF_TARGET_CPU_WATCHPOINT_NUM} watchpoints, so {IDF_TARGET_CPU_WATCHPOINT_NUM} variables can be watched for change or read by the GDB command ``watch myVariable``. Note that menuconfig option :ref:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` uses the last watchpoint and will not provide expected results, if you also try to use it within OpenOCD / GDB. See menuconfig's help for detailed description.
+{IDF_TARGET_NAME} debugger supports {IDF_TARGET_CPU_BREAKPOINT_NUM} hardware implemented breakpoints and 64 software ones. Hardware breakpoints are implemented by {IDF_TARGET_NAME} chip's logic and can be set anywhere in the code: either in flash or IRAM program's regions. Additionally there are 2 types of software breakpoints implemented by OpenOCD: flash (up to 32) and IRAM (up to 32) breakpoints. Currently GDB can not set software breakpoints in flash. So until this limitation is removed those breakpoints have to be emulated by OpenOCD as hardware ones (see :ref:`below <jtag-debugging-tip-where-breakpoints>` for details). {IDF_TARGET_NAME} also supports {IDF_TARGET_CPU_WATCHPOINT_NUM} watchpoints, so {IDF_TARGET_CPU_WATCHPOINT_NUM} variables can be watched for change or read by the GDB command ``watch myVariable``. Note that menuconfig option :ref:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` uses the last watchpoint and will not provide expected results, if you also try to use it within OpenOCD/GDB. See menuconfig's help for detailed description.
 
 
 .. _jtag-debugging-tip-where-breakpoints:
 
-What else should I know about breakpoints?
+What Else Should I Know About Breakpoints?
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Emulating part of hardware breakpoints using software flash ones means that the GDB command ``hb myFunction`` which is invoked for function in flash will use pure hardware breakpoint if it is avalable otherwise one of the 32 software flash breakpoints is used. The same rule applies to ``b myFunction``-like commands. In this case GDB will decide what type of breakpoint to set itself. If ``myFunction`` is resided in writable region (IRAM) software IRAM breakpoint will be used otherwise hardware or software flash breakpoint is used as it is done for ``hb`` command.
 
@@ -49,7 +49,7 @@ Offset should be in hex format. To reset to the default behaviour you can specif
 
 .. _jtag-debugging-tip-why-next-works-as-step:
 
-Why stepping with "next" does not bypass subroutine calls?
+Why Stepping with "next" Does Not Bypass Subroutine Calls?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 When stepping through the code with ``next`` command, GDB is internally setting a breakpoint (one out of two available) ahead in the code to bypass the subroutine calls. This functionality will not work, if the two available breakpoints are already set elsewhere in the code. If this is the case, delete breakpoints to have one "spare". With both breakpoints already used, stepping through the code with ``next`` command will work as like with ``step`` command and debugger will step inside subroutine calls.
@@ -57,7 +57,7 @@ When stepping through the code with ``next`` command, GDB is internally setting
 
 .. _jtag-debugging-tip-code-options:
 
-Support options for OpenOCD at compile time
+Support Options for OpenOCD at Compile Time
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 ESP-IDF has some support options for OpenOCD debugging which can be set at compile time:
@@ -70,7 +70,7 @@ Please see the :ref:`project configuration menu <get-started-configure>` menu fo
 
 .. _jtag-debugging-tip-freertos-support:
 
-FreeRTOS support
+FreeRTOS Support
 ^^^^^^^^^^^^^^^^
 
 OpenOCD has explicit support for the ESP-IDF FreeRTOS. GDB can see FreeRTOS tasks as threads. Viewing them all can be done using the GDB ``i threads`` command, changing to a certain task is done with ``thread n``, with ``n`` being the number of the thread. FreeRTOS detection can be disabled in target's configuration. For more details see :ref:`jtag-debugging-tip-openocd-configure-target`.
@@ -81,7 +81,7 @@ GDB has a Python extension for FreeRTOS support. ESP-IDF automatically loads thi
 
     .. _jtag-debugging-tip-code-flash-voltage:
 
-    Why to set SPI flash voltage in OpenOCD configuration?
+    Why to Set SPI Flash Voltage in OpenOCD Configuration?
     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
     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.
@@ -96,23 +96,23 @@ GDB has a Python extension for FreeRTOS support. ESP-IDF automatically loads thi
 
     .. _jtag-debugging-tip-optimize-jtag-speed:
 
-Optimize JTAG speed
+Optimize JTAG Speed
 ^^^^^^^^^^^^^^^^^^^
 
 In order to achieve higher data rates and minimize number of dropped packets it is recommended to optimize setting of JTAG clock frequency, so it is at maximum and still provides stable operation of JTAG. To do so use the following tips.
 
 1.  The upper limit of JTAG clock frequency is 20 MHz if CPU runs at 80 MHz, or 26 MHz if CPU runs at 160 MHz or 240 MHz.
-2.  Depending on particular JTAG adapter and the length of connecting cables, you may need to reduce JTAG frequency below 20 / 26 MHz.
+2.  Depending on particular JTAG adapter and the length of connecting cables, you may need to reduce JTAG frequency below 20 MHz or 26 MHz.
 3.  In particular reduce frequency, if you get DSR/DIR errors (and they do not relate to OpenOCD trying to read from a memory range without physical memory being present there).
-4.  ESP-WROVER-KIT operates stable at 20 / 26 MHz.
+4.  ESP-WROVER-KIT operates stable at 20 MHz or 26 MHz.
 
 
 .. _jtag-debugging-tip-debugger-startup-commands:
 
-What is the meaning of debugger's startup commands?
+What is the Meaning of Debugger's Startup Commands?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-On startup, debugger is issuing sequence of commands to reset the chip and halt it at specific line of code. This sequence (shown below) is user defined to pick up at most convenient / appropriate line and start debugging.
+On startup, debugger is issuing sequence of commands to reset the chip and halt it at specific line of code. This sequence (shown below) is user defined to pick up at most convenient/appropriate line and start debugging.
 
 * ``set remote hardware-watchpoint-limit 2`` — Restrict GDB to using two hardware watchpoints supported by the chip, 2 for {IDF_TARGET_NAME}. For more information see https://sourceware.org/gdb/onlinedocs/gdb/Remote-Configuration.html.
 * ``mon reset halt`` — reset the chip and keep the CPUs halted
@@ -123,7 +123,7 @@ On startup, debugger is issuing sequence of commands to reset the chip and halt
 
 .. _jtag-debugging-tip-openocd-configure-target:
 
-Configuration of OpenOCD for specific target
+Configuration of OpenOCD for Specific Target
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 There are several kinds of OpenOCD configuration files (``*.cfg``). All configuration files are located in subdirectories of ``share/openocd/scripts`` directory of OpenOCD distribution (or ``tcl/scripts`` directory of the source repository). For the purposes of this guide, the most important ones are ``board``, ``interface`` and ``target``.
@@ -143,14 +143,14 @@ If you are using one of the boards which have a pre-defined configuration file,
 
 If you are using a board not listed here, you need to specify both the interface configuration file and target configuration file.
 
-Custom configuration files
+Custom Configuration Files
 """"""""""""""""""""""""""
 
 OpenOCD configuration files are written in TCL, and include a variety of choices for customization and scripting. This can be useful for non-standard debugging situations. Please refer to `OpenOCD Manual`_ for the TCL scripting reference.
 
 .. _jtag-debugging-tip-openocd-config-vars:
 
-OpenOCD configuration variables
+OpenOCD Configuration Variables
 """""""""""""""""""""""""""""""
 
 The following variables can be optionally set before including the ESP-specific target configuration file. This can be done either in a custom configuration file, or from the command line.
@@ -188,7 +188,7 @@ It is important to set the variable before including the ESP-specific configurat
 
 .. _jtag-debugging-tip-reset-by-debugger:
 
-How debugger resets {IDF_TARGET_NAME}?
+How Debugger Resets {IDF_TARGET_NAME}?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The board can be reset by entering ``mon reset`` or ``mon reset halt`` into GDB.
@@ -196,7 +196,7 @@ The board can be reset by entering ``mon reset`` or ``mon reset halt`` into GDB.
 
 .. _jtag-debugging-tip-jtag-pins-reconfigured:
 
-Can JTAG pins be used for other purposes?
+Can JTAG Pins be Used for Other Purposes?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. only:: SOC_USB_SERIAL_JTAG_SUPPORTED
@@ -250,7 +250,7 @@ To disable software breakpoints while using JTAG, add an extra argument ``-c 'se
 
 .. only:: esp32
 
-    JTAG and ESP32-WROOM-32 AT firmware Compatibility Issue
+    JTAG and ESP32-WROOM-32 AT Firmware Compatibility Issue
     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
     The ESP32-WROOM series of modules come pre-flashed with AT firmware. This firmware configures the pins GPIO12 to GPIO15 as SPI slave interface, which makes using JTAG impossible.
@@ -259,7 +259,7 @@ To disable software breakpoints while using JTAG, add an extra argument ``-c 'se
 
 .. _jtag-debugging-tip-reporting-issues:
 
-Reporting issues with OpenOCD / GDB
+Reporting Issues with OpenOCD/GDB
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 In case you encounter a problem with OpenOCD or GDB programs itself and do not find a solution searching available resources on the web, open an issue in the OpenOCD issue tracker under https://github.com/espressif/openocd-esp32/issues.

docs/en/api-guides/memory-types.rst

@@ -25,8 +25,8 @@ Non-constant static data (.data) and zero-initialized data (.bss) is placed by t
    The available size of the internal DRAM region is reduced by 64 KB (by shifting start address to ``0x3FFC0000``) if Bluetooth stack is used. Length of this region is also reduced by 16 KB or 32 KB if trace memory is used. Due to some memory fragmentation issues caused by ROM, it is also not possible to use all available DRAM for static allocations - however the remaining DRAM is still available as heap at runtime.
 
    .. note::
-   
+
-    There is 520KB of available SRAM (320KB of DRAM and 200KB of IRAM) on the esp32. However, due to a technical limitation, the maximum statically allocated DRAM usage is 160KB. The remaining 160KB (for a total of 320KB of DRAM) can only be allocated at runtime as heap.
+    There is 520 KB of available SRAM (320 KB of DRAM and 200 KB of IRAM) on the ESP32. However, due to a technical limitation, the maximum statically allocated DRAM usage is 160 KB. The remaining 160 KB (for a total of 320 KB of DRAM) can only be allocated at runtime as heap.
 
 .. only:: not esp32
 
@@ -71,7 +71,7 @@ IRAM (Instruction RAM)
         Any internal SRAM which is not used for Instruction RAM will be made available as :ref:`dram` for static data and dynamic allocation (heap).
 
 
-When to place code in IRAM
+When to Place Code in IRAM
 ================================
 
 Cases when parts of the application should be placed into IRAM:
@@ -83,7 +83,7 @@ Cases when parts of the application should be placed into IRAM:
 
 .. _how-to-place-code-in-iram:
 
-How to place code in IRAM
+How to Place Code in IRAM
 =========================
 
 Some code is automatically placed into the IRAM region using the linker script.
@@ -213,7 +213,7 @@ Or::
 
 It is also possible to allocate DMA-capable memory buffers dynamically by using the :ref:`MALLOC_CAP_DMA <dma-capable-memory>` capabilities flag.
 
-DMA Buffer in the stack
+DMA Buffer in the Stack
 ^^^^^^^^^^^^^^^^^^^^^^^
 
 Placing DMA buffers in the stack is possible but discouraged. If doing so, pay attention to the following:

docs/en/api-guides/partition-tables.rst

@@ -7,8 +7,7 @@ Overview
 
 A single {IDF_TARGET_NAME}'s flash can contain multiple apps, as well as many different kinds of data (calibration data, filesystems, parameter storage, etc). For this reason a partition table is flashed to (:ref:`default offset <CONFIG_PARTITION_TABLE_OFFSET>`) 0x8000 in the flash.
 
-The partition table length is 0xC00 bytes, as we allow a maximum of 95 entries. An MD5 checksum, used for checking the integrity of the partition table at runtime, is appended after the table data. Thus, the partition table occupies an entire flash sector, which size is 0x1000 (4KB). As a result, any partition following it must be at least located at (:ref:`default offset <CONFIG_PARTITION_TABLE_OFFSET>`) + 0x1000.
+The partition table length is 0xC00 bytes, as we allow a maximum of 95 entries. An MD5 checksum, used for checking the integrity of the partition table at runtime, is appended after the table data. Thus, the partition table occupies an entire flash sector, which size is 0x1000 (4 KB). As a result, any partition following it must be at least located at (:ref:`default offset <CONFIG_PARTITION_TABLE_OFFSET>`) + 0x1000.
-
 
 Each entry in the partition table has a name (label), type (app, data, or something else), subtype and the offset in flash where the partition is loaded.
 
@@ -140,11 +139,11 @@ A component can define a new partition subtype by setting the ``EXTRA_PARTITION_
 Offset & Size
 ~~~~~~~~~~~~~
 
-The offset represents the partition address in the SPI flash, which sector size is 0x1000 (4KB). Thus, the offset must be a multiple of 4KB.
+The offset represents the partition address in the SPI flash, which sector size is 0x1000 (4 KB). Thus, the offset must be a multiple of 4 KB.
 
 Partitions with blank offsets in the CSV file will start after the previous partition, or after the partition table in the case of the first partition.
 
-Partitions of type ``app`` have to be placed at offsets aligned to 0x10000 (64K). If you leave the offset field blank,  ``gen_esp32part.py`` will automatically align the partition. If you specify an unaligned offset for an app partition, the tool will return an error.
+Partitions of type ``app`` have to be placed at offsets aligned to 0x10000 (64 K). If you leave the offset field blank,  ``gen_esp32part.py`` will automatically align the partition. If you specify an unaligned offset for an app partition, the tool will return an error.
 
 Sizes and offsets can be specified as decimal numbers, hex numbers with the prefix 0x, or size multipliers K or M (1024 and 1024*1024 bytes).
 

docs/en/get-started/start-project.rst

@@ -1,6 +1,6 @@
 {IDF_TARGET_CORE_NUM:default="2", esp32s2="1", esp32c3="1", esp32c2="1", esp32c6="1"}
 
-{IDF_TARGET_FEATURES:default="[NEEDS TO BE UPDATED]", esp32="WiFi/BT/BLE, silicon revision 1, 2MB external flash", esp32s2="WiFi, silicon revision 0, 2MB external flash", esp32s3="This is esp32s3 chip with 2 CPU core(s), WiFi/BLE, silicon revision 0, 2MB external flash", esp32c2="WiFi/BLE, silicon revision 0, 2MB embedded flash", esp32c3="WiFi/BLE, silicon revision 0, 2MB external flash", esp32c6="WiFi/BLE, 802.15.4 (Zigbee/Thread), silicon revision v0.0, 2MB external flash"}
+{IDF_TARGET_FEATURES:default="[NEEDS TO BE UPDATED]", esp32="WiFi/BT/BLE, silicon revision 1, 2 MB external flash", esp32s2="WiFi, silicon revision 0, 2 MB external flash", esp32s3="This is esp32s3 chip with 2 CPU core(s), WiFi/BLE, silicon revision 0, 2 MB external flash", esp32c2="WiFi/BLE, silicon revision 0, 2 MB embedded flash", esp32c3="WiFi/BLE, silicon revision 0, 2 MB external flash", esp32c6="WiFi/BLE, 802.15.4 (Zigbee/Thread), silicon revision v0.0, 2 MB external flash"}
 
 {IDF_TARGET_HEAP_SIZE:default="[NEEDS TO BE UPDATED]", esp32="298968", esp32s2="253900", esp32s3="390684", esp32c2="203888", esp32c3="337332", esp32c6="337332"}
 
@@ -270,7 +270,6 @@ When flashing, you will see the output log similar to the following:
         Hard resetting via RTS pin...
         Done
 
-
 .. only:: esp32c6
 
     .. code-block:: none

docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst

@@ -13,7 +13,7 @@
 可用的断点和观察点
 ^^^^^^^^^^^^^^^^^^
 
-{IDF_TARGET_NAME} 调试器支持 {IDF_TARGET_CPU_BREAKPOINT_NUM} 个硬件断点和 64 个软件断点。硬件断点是由 {IDF_TARGET_NAME} 芯片内部的逻辑电路实现的，能够设置在代码的任何位置：闪存或者 IRAM 的代码区域。除此以外，OpenOCD 实现了两种软件断点：闪存断点（最多 32 个）和 IRAM 断点（最多 32 个）。目前 GDB 无法在闪存中设置软件断点，因此除非解决此限制，否则这些断点只能由 OpenOCD 模拟为硬件断点（详细信息可以参阅 :ref:`下面 <jtag-debugging-tip-where-breakpoints>`）。{IDF_TARGET_NAME} 还支持 {IDF_TARGET_CPU_WATCHPOINT_NUM} 个观察点，所以可以观察 {IDF_TARGET_CPU_WATCHPOINT_NUM} 个变量的变化或者通过 GDB 命令 ``watch myVariable`` 来读取变量的值。请注意 menuconfig 中的 :ref:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` 选项会使用最后一个观察点，如果你想在 OpenOCD 或者 GDB 中再次尝试使用这个观察点，可能不会得到预期的结果。详情请查看 menuconfig 中的帮助文档。
+{IDF_TARGET_NAME} 调试器支持 {IDF_TARGET_CPU_BREAKPOINT_NUM} 个硬件断点和 64 个软件断点。硬件断点是由 {IDF_TARGET_NAME} 芯片内部的逻辑电路实现的，能够设置在代码的任何位置：flash 或者 IRAM 的代码区域。除此以外，OpenOCD 实现了两种软件断点：flash 断点（最多 32 个）和 IRAM 断点（最多 32 个）。目前 GDB 无法在 flash 中设置软件断点，因此除非解决此限制，否则这些断点只能由 OpenOCD 模拟为硬件断点（详细信息可以参阅 :ref:`下面 <jtag-debugging-tip-where-breakpoints>`）。{IDF_TARGET_NAME} 还支持 {IDF_TARGET_CPU_WATCHPOINT_NUM} 个观察点，所以可以观察 {IDF_TARGET_CPU_WATCHPOINT_NUM} 个变量的变化或者通过 GDB 命令 ``watch myVariable`` 来读取变量的值。请注意 menuconfig 中的 :ref:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` 选项会使用最后一个观察点，如果你想在 OpenOCD 或者 GDB 中再次尝试使用这个观察点，可能不会得到预期的结果。详情请查看 menuconfig 中的帮助文档。
 
 
 .. _jtag-debugging-tip-where-breakpoints:
@@ -21,15 +21,15 @@
 关于断点的补充知识
 ^^^^^^^^^^^^^^^^^^
 
-使用软件闪存模拟部分硬件断点的意思就是当使用 GDB 命令 ``hb myFunction`` 给某个函数设置硬件断点时，如果该函数位于闪存中，并且此时还有可用的硬件断点，那调试器就会使用硬件断点，否则就使用 32 个软件闪存断点中的一个来模拟。这个规则同样适用于 ``b myFunction`` 之类的命令，在这种情况下，GDB 会自己决定该使用哪种类型的断点。如果 ``myFunction`` 位于可写区域（IRAM），那就会使用软件 IRAM 断点，否则就会像处理 ``hb`` 命令一样使用硬件断点或者软件闪存断点。
+使用软件 flash 模拟部分硬件断点的意思就是当使用 GDB 命令 ``hb myFunction`` 给某个函数设置硬件断点时，如果该函数位于 flash 中，并且此时还有可用的硬件断点，那调试器就会使用硬件断点，否则就使用 32 个软件 flash 断点中的一个来模拟。这个规则同样适用于 ``b myFunction`` 之类的命令，在这种情况下，GDB 会自己决定该使用哪种类型的断点。如果 ``myFunction`` 位于可写区域 (IRAM)，那就会使用软件 IRAM 断点，否则就会像处理 ``hb`` 命令一样使用硬件断点或者软件 flash 断点。
 
 
 .. _jtag-debugging-tip-flash-mappings:
 
-闪存映射 vs 软件闪存断点
+flash 映射 vs 软件 flash 断点
-^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-为了在闪存中设置或者清除软件断点，OpenOCD 需要知道它们在闪存中的地址。为了完成从 {IDF_TARGET_NAME} 的地址空间到闪存地址的转换，OpenOCD 使用闪存中程序代码区域的映射。这些映射被保存在程序映像的头部，位于二进制数据（代码段和数据段）之前，并且特定于写入闪存的每一个应用程序的映像。因此，为了支持软件闪存断点，OpenOCD 需要知道待调试的应用程序映像在闪存中的位置。默认情况下，OpenOCD 会在 0x8000 处读取分区表并使用第一个找到的应用程序映像的映射，但是也可能会存在无法工作的情况，比如分区表不在标准的闪存位置，甚至可能有多个映像：一个出厂映像和两个 OTA 映像，你可能想要调试其中的任意一个。为了涵盖所有可能的调试情况，OpenOCD 支持特殊的命令，用于指定待调试的应用程序映像在闪存中的具体位置。该命令具有以下格式：
+为了在 flash 中设置或者清除软件断点，OpenOCD 需要知道它们在 flash 中的地址。为了完成从 {IDF_TARGET_NAME} 的地址空间到 flash 地址的转换，OpenOCD 使用 flash 中程序代码区域的映射。这些映射被保存在程序映像的头部，位于二进制数据（代码段和数据段）之前，并且特定于写入 flash 的每一个应用程序的映像。因此，为了支持软件 flash 断点，OpenOCD 需要知道待调试的应用程序映像在 flash 中的位置。默认情况下，OpenOCD 会在 0x8000 处读取分区表并使用第一个找到的应用程序映像的映射，但是也可能会存在无法工作的情况，比如分区表不在标准的 flash 位置，甚至可能有多个映像：一个出厂映像和两个 OTA 映像，你可能想要调试其中的任意一个。为了涵盖所有可能的调试情况，OpenOCD 支持特殊的命令，用于指定待调试的应用程序映像在 flash 中的具体位置。该命令具有以下格式：
 
 ``esp appimage_offset <offset>``
 
@@ -81,14 +81,14 @@ GDB 具有 FreeRTOS 支持的 Python 扩展模块。在系统要求满足的情
 
     .. _jtag-debugging-tip-code-flash-voltage:
 
-    在 OpenOCD 的配置文件中设置 SPI 闪存的工作电压
+    在 OpenOCD 的配置文件中设置 SPI flash 的工作电压
-    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-    ESP32 的 MTDI 管脚是用于 JTAG 通信的四个管脚之一，同时也是 ESP32 的 bootstrapping 管脚。上电时，ESP32 会在 MTDI 管脚上采样二进制电平，据此来设置内部的稳压器，用于给外部的 SPI 闪存芯片供电。如果上电时 MTDI 管脚上的二进制电平为低电平，则稳压器会被设置为 3.3 V；如果 MTDI 管脚为高电平，则稳压器会被设置为 1.8 V。MTDI 管脚通常需要一个上拉电阻或者直接使能内部的弱下拉电阻（详见 `ESP32 系列芯片技术规格书 <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_cn.pdf>`_ ），具体取决于所使用的 SPI 芯片的类型。但是一旦连接上 JTAG 后，原来用于实现 bootstrapping 功能的上拉或者下拉电阻都会被覆盖掉。
+    ESP32 的 MTDI 管脚是用于 JTAG 通信的四个管脚之一，同时也是 ESP32 的 bootstrapping 管脚。上电时，ESP32 会在 MTDI 管脚上采样二进制电平，据此来设置内部的稳压器，用于给外部的 SPI flash 芯片供电。如果上电时 MTDI 管脚上的二进制电平为低电平，则稳压器会被设置为 3.3 V；如果 MTDI 管脚为高电平，则稳压器会被设置为 1.8 V。MTDI 管脚通常需要一个上拉电阻或者直接使能内部的弱下拉电阻（详见 `ESP32 系列芯片技术规格书 <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_cn.pdf>`_ ），具体取决于所使用的 SPI 芯片的类型。但是一旦连接上 JTAG 后，原来用于实现 bootstrapping 功能的上拉或者下拉电阻都会被覆盖掉。
 
-    为了解决这个问题，OpenOCD 的板级配置文件（例如 ESP-WROVER-KIT 开发板的 ``board\esp32-wrover-kit-3.3v.cfg``）提供了 ``ESP32_FLASH_VOLTAGE`` 参数来设置 ``TDO`` 信号线在空闲状态下的二进制电平，这样就可以减少由于闪存电压不正确而导致的应用程序启动不良的几率。
+    为了解决这个问题，OpenOCD 的板级配置文件（例如 ESP-WROVER-KIT 开发板的 ``board\esp32-wrover-kit-3.3v.cfg``）提供了 ``ESP32_FLASH_VOLTAGE`` 参数来设置 ``TDO`` 信号线在空闲状态下的二进制电平，这样就可以减少由于 flash 电压不正确而导致的应用程序启动不良的几率。
 
-    查看 JTAG 连接的 ESP32 模组的规格书，检查其 SPI 闪存芯片的供电电压值，然后再相应的设置 ``ESP32_FLASH_VOLTAGE``。大多数WROOM模块使用 3.3 V 的闪存芯片。 早于 ESP32-WROVER-B 的 WROVER 模块使用 1.8 V 闪存芯片，而ESP32-WROVER-B和-E模块使用 3.3 V 闪存芯片。
+    查看 JTAG 连接的 ESP32 模组的规格书，检查其 SPI flash 芯片的供电电压值，然后再相应的设置 ``ESP32_FLASH_VOLTAGE``。大多数WROOM模块使用 3.3 V 的 flash 芯片。 早于 ESP32-WROVER-B 的 WROVER 模块使用 1.8 V flash 芯片，而ESP32-WROVER-B和-E模块使用 3.3 V flash 芯片。
 
     .. _jtag-debugging-tip-optimize-jtag-speed:
 
@@ -97,20 +97,20 @@ GDB 具有 FreeRTOS 支持的 Python 扩展模块。在系统要求满足的情
     .. _jtag-debugging-tip-optimize-jtag-speed:
 
 优化 JTAG 的速度
-^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^
 
 为了实现更高的数据通信速率同时最小化丢包数，建议优化 JTAG 时钟频率的设置，使其达到 JTAG 能稳定运行的最大值。为此，请参考以下建议。
 
 1.  如果 CPU 以 80 MHz 运行，则 JTAG 时钟频率的上限为 20 MHz；如果 CPU 以 160 MHz 或者 240 MHz 运行，则上限为 26 MHz。
-2.  根据特定的 JTAG 适配器和连接线缆的长度，你可能需要将 JTAG 的工作频率降低至 20 / 26 MHz 以下。
+2.  根据特定的 JTAG 适配器和连接线缆的长度，你可能需要将 JTAG 的工作频率降低至 20 MHz 或 26 MHz 以下。
 3.  在某些特殊情况下，如果你看到 DSR/DIR 错误（并且它并不是由 OpenOCD 试图从一个没有物理存储器映射的地址空间读取数据而导致的），请降低 JTAG 的工作频率。
-4.  ESP-WROVER-KIT 能够稳定运行在 20 / 26 MHz 频率下。
+4.  ESP-WROVER-KIT 能够稳定运行在 20 MHz 或 26 MHz 频率下。
 
 
 .. _jtag-debugging-tip-debugger-startup-commands:
 
 调试器的启动命令的含义
-^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 在启动时，调试器发出一系列命令来复位芯片并使其在特定的代码行停止运行。这个命令序列（如下所示）支持自定义，用户可以选择在最方便合适的代码行开始调试工作。
 
@@ -124,7 +124,7 @@ GDB 具有 FreeRTOS 支持的 Python 扩展模块。在系统要求满足的情
 .. _jtag-debugging-tip-openocd-configure-target:
 
 根据目标芯片配置 OpenOCD
-^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 OpenOCD 有很多种配置文件（``*.cfg``），它们位于 OpenOCD 安装目录的 ``share/openocd/scripts`` 子目录中（或者在 OpenOCD 源码目录的 ``tcl/scripts`` 目录中）。本文主要介绍 ``board``，``interface`` 和 ``target`` 这三个目录。
 
@@ -196,40 +196,50 @@ TCL 语言中为变量赋值的语法是:
 
 .. _jtag-debugging-tip-jtag-pins-reconfigured:
 
-不要将 JTAG 管脚用于其他功能
+JTAG 管脚是否能用于其他功能
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+.. only:: SOC_USB_SERIAL_JTAG_SUPPORTED
+
+    {IDF_TARGET_NAME} 包含一个可用于调试的 USB Serial/JTAG 控制器。 默认情况下，{IDF_TARGET_NAME} JTAG 接口连接到内置的外设 USB Serial/JTAG。 详细信息可参阅 :doc:`配置 {IDF_TARGET_NAME} 内置 JTAG 接口 <../jtag-debugging/configure-builtin-jtag>`。
+
+    如果 USB Serial/JTAG 控制器用于调试，|jtag-gpio-list| 可用于其他功能。
+
+    如果用户通过烧录 eFuse 将 USB JTAG 接口切换为 GPIO，|jtag-gpio-list| 则可用于 JTAG 调试，但用于 JTAG 调试的 |jtag-gpio-list| 不能再用于其他功能。
+
 如果除了 {IDF_TARGET_NAME} 模组和 JTAG 适配器之外的其他硬件也连接到了 JTAG 管脚，那么 JTAG 的操作可能会受到干扰。{IDF_TARGET_NAME} JTAG 使用以下管脚：
 
 .. include:: {IDF_TARGET_PATH_NAME}.inc
     :start-after: jtag-pins
     :end-before: ---
 
-如果用户应用程序更改了 JTAG 管脚的配置，JTAG 通信可能会失败。如果 OpenOCD 正确初始化（检测到两个 Tensilica 内核），但在程序运行期间失去了同步并报出大量 DTR/DIR 错误，则应用程序可能将 JTAG 管脚重新配置为其他功能或者用户忘记将 Vtar 连接到 JTAG 适配器。
+如果用户应用程序更改了 JTAG 管脚的配置，JTAG 通信可能会失败。如果 OpenOCD 正确初始化（检测到芯片全部 CPU 内核），但在程序运行期间失去了同步并报出大量 DTR/DIR 错误，原因可能是应用程序将 JTAG 管脚重新配置为其他功能或者用户忘记将 Vtar 连接到 JTAG 适配器。
 
-.. highlight:: none
+.. only:: esp32
 
-下面是 GDB 在应用程序进入重新配置 MTDO/GPIO15 作为输入代码后报告的一系列错误摘录::
+    .. highlight:: none
 
-    cpu0: xtensa_resume (line 431): DSR (FFFFFFFF) indicates target still busy!
+    以下是应用程序进入重新配置 MTDO 作为输入代码后，双核 {IDF_TARGET_NAME} GDB 报告的一系列错误摘录::
-    cpu0: xtensa_resume (line 431): DSR (FFFFFFFF) indicates DIR instruction generated an exception!
+
-    cpu0: xtensa_resume (line 431): DSR (FFFFFFFF) indicates DIR instruction generated an overrun!
+        cpu0: xtensa_resume (line 431): DSR (FFFFFFFF) indicates target still busy!
-    cpu1: xtensa_resume (line 431): DSR (FFFFFFFF) indicates target still busy!
+        cpu0: xtensa_resume (line 431): DSR (FFFFFFFF) indicates DIR instruction generated an exception!
-    cpu1: xtensa_resume (line 431): DSR (FFFFFFFF) indicates DIR instruction generated an exception!
+        cpu0: xtensa_resume (line 431): DSR (FFFFFFFF) indicates DIR instruction generated an overrun!
-    cpu1: xtensa_resume (line 431): DSR (FFFFFFFF) indicates DIR instruction generated an overrun!
+        cpu1: xtensa_resume (line 431): DSR (FFFFFFFF) indicates target still busy!
+        cpu1: xtensa_resume (line 431): DSR (FFFFFFFF) indicates DIR instruction generated an exception!
+        cpu1: xtensa_resume (line 431): DSR (FFFFFFFF) indicates DIR instruction generated an overrun!
 
 .. _jtag-debugging-security-features:
 
-JTAG 与闪存加密和安全引导
+JTAG 与 flash 加密和安全引导
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-默认情况下，开启了闪存加密和（或者）安全引导后，系统在首次启动时，引导程序会烧写 eFuse 的某个比特，从而将 JTAG 永久关闭。
+默认情况下，开启了 flash 加密和（或者）安全引导后，系统在首次启动时，引导程序会烧写 eFuse 的某个比特，从而将 JTAG 永久关闭。
 
-Kconfig 配置项 :ref:`CONFIG_SECURE_BOOT_ALLOW_JTAG` 可以改变这个默认行为，使得用户即使开启了安全引导或者闪存加密，仍会保留 JTAG 的功能。
+Kconfig 配置项 :ref:`CONFIG_SECURE_BOOT_ALLOW_JTAG` 可以改变这个默认行为，使得用户即使开启了安全引导或者 flash 加密，仍会保留 JTAG 的功能。
 
 然而，因为设置 :ref:`软件断点 <jtag-debugging-tip-where-breakpoints>` 的需要，OpenOCD 会尝试自动读写 flash 中的内容，这会带来两个问题：
 
-- 软件断点和闪存加密是不兼容的，目前 OpenOCD 尚不支持对 flash 中的内容进行加密和解密。
+- 软件断点和 flash 加密是不兼容的，目前 OpenOCD 尚不支持对 flash 中的内容进行加密和解密。
 - 如果开启了安全引导功能，设置软件断点会改变被签名的程序的摘要，从而使得签名失效。这也意味着，如果设置了软件断点，系统会在下次重启时的签名验证阶段失败，导致无法启动。
 
 关闭 JTAG 的软件断点功能，可以在启动 OpenOCD 时在命令行额外加一项配置参数 ``-c 'set ESP_FLASH_SIZE 0'``，请参考 :ref:`jtag-debugging-tip-openocd-config-vars`。
@@ -249,7 +259,7 @@ Kconfig 配置项 :ref:`CONFIG_SECURE_BOOT_ALLOW_JTAG` 可以改变这个默认
 
 .. _jtag-debugging-tip-reporting-issues:
 
-报告 OpenOCD / GDB 的问题
+报告 OpenOCD/GDB 的问题
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
 如果你遇到 OpenOCD 或者 GDB 程序本身的问题，并且在网上没有找到可用的解决方案，请前往 https://github.com/espressif/openocd-esp32/issues 新建一个议题。

docs/zh_CN/api-guides/memory-types.rst

@@ -24,6 +24,10 @@ DRAM（数据 RAM）
 
    如果使用蓝牙堆栈，内部 DRAM 区域的可用大小将减少 64 KB（由于起始地址移动到 ``0x3FFC0000``）。如果使用内存跟踪功能，该区域的长度还会减少 16 KB 或 32 KB。由于 ROM 引起的一些内存碎片问题，不可能将所有可用的 DRAM 用于静态分配，但是剩余的 DRAM 在运行时仍可用作堆。
 
+   .. note::
+
+    ESP32 上有 520 KB 的可用 SRAM（320 KB 的 DRAM 和 200 KB 的 IRAM）。 但是，由于技术限制，用于静态分配的 DRAM 最多可为 160 KB。 剩余的 160 KB（DRAM 总共 320 KB）只能在运行时分配为堆。
+
 .. only:: not esp32
 
    .. note::

docs/zh_CN/api-guides/partition-tables.rst

@@ -7,7 +7,7 @@
 
 每片 {IDF_TARGET_NAME} 的 flash 可以包含多个应用程序，以及多种不同类型的数据（例如校准数据、文件系统数据、参数存储数据等）。因此，我们在 flash 的 :ref:`默认偏移地址 <CONFIG_PARTITION_TABLE_OFFSET>` 0x8000 处烧写一张分区表。
 
-分区表的长度为 0xC00 字节（最多可以保存 95 条分区表条目）。分区表数据后还保存着该表的 MD5 校验和，用于验证分区表的完整性。此外，如果芯片使能了 :doc:`安全启动 </security/secure-boot-v2>` 功能，则该分区表后还会保存签名信息。
+分区表的长度为 0xC00 字节，最多可以保存 95 条分区表条目。MD5 校验和附加在分区表之后，用于在运行时验证分区表的完整性。分区表占据了整个 flash 扇区，大小为 0x1000 (4 KB)。因此，它后面的任何分区至少需要位于 (:ref:`默认偏移地址 <CONFIG_PARTITION_TABLE_OFFSET>`) + 0x1000 处。
 
 分区表中的每个条目都包括以下几个部分：Name（标签）、Type（app、data 等）、SubType 以及在 flash 中的偏移量（分区的加载地址）。
 
@@ -43,7 +43,7 @@
   ota_0,    app,  ota_0,   0x110000, 1M,
   ota_1,    app,  ota_1,   0x210000, 1M,
 
--  分区表中定义了三个应用程序分区，这三个分区的类型都被设置为 “app”，但具体 app 类型不同。其中，位于 0x10000 偏移地址处的为出厂应用程序（factory），其余两个为 OTA 应用程序（ota_0，ota_1）。
+-  分区表中定义了三个应用程序分区，这三个分区的类型都被设置为 “app”，但具体 app 类型不同。其中，位于 0x10000 偏移地址处的为出厂应用程序 (factory)，其余两个为 OTA 应用程序（ota_0，ota_1）。
 -  新增了一个名为 “otadata” 的数据分区，用于保存 OTA 升级时需要的数据。启动加载器会查询该分区的数据，以判断该从哪个 OTA 应用程序分区加载程序。如果 “otadata” 分区为空，则会执行出厂程序。
 
 创建自定义分区表
@@ -88,7 +88,7 @@ Type 字段可以指定为 app (0x00) 或者 data (0x01)，也可以直接使用
 
 SubType 字段
 ~~~~~~~~~~~~
-{IDF_TARGET_ESP_PHY_REF:default = ":ref:`CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION`", esp32c6 = "(not updated yet)"}
+{IDF_TARGET_ESP_PHY_REF:default = ":ref:`CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION`"}
 
 SubType 字段长度为 8 bit，内容与具体分区 Type 有关。目前，esp-idf 仅仅规定了 “app” 和 “data” 两种分区类型的子类型含义。
 
@@ -136,12 +136,14 @@ SubType 字段长度为 8 bit，内容与具体分区 Type 有关。目前，esp
 
 组件可以通过设置 ``EXTRA_PARTITION_SUBTYPES`` 属性来定义额外的分区子类型。 ``EXTRA_PARTITION_SUBTYPES`` 是一个 CMake 列表，其中的每个条目由字符串组成，以逗号为分隔，格式为 ``<type>, <subtype>, <value>``。构建系统通过该属性会自动添加额外的子类型，并在 :cpp:type:`esp_partition_subtype_t` 中插入名为 ``ESP_PARTITION_SUBTYPE_<type>_<subtype>`` 的字段。项目可以使用这个子类型来定义分区表 CSV 文件中的分区，并使用 :cpp:type:`esp_partition_subtype_t` 中的新字段。
 
-Offset 和 Size 字段
+偏移地址 (Offset) 和 Size 字段
-~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+偏移地址表示 SPI flash 中的分区地址，扇区大小为 0x1000 (4 KB)。 因此，偏移地址必须是 4 KB 的倍数。
 
 分区若偏移地址为空，则会紧跟着前一个分区之后开始；若为首个分区，则将紧跟着分区表开始。
 
-app 分区的偏移地址必须要与 0x10000 (64K) 对齐，如果将偏移字段留空，``gen_esp32part.py`` 工具会自动计算得到一个满足对齐要求的偏移地址。如果 app 分区的偏移地址没有与 0x10000 (64K) 对齐，则该工具会报错。
+app 分区的偏移地址必须要与 0x10000 (64 K) 对齐，如果将偏移字段留空，``gen_esp32part.py`` 工具会自动计算得到一个满足对齐要求的偏移地址。如果 app 分区的偏移地址没有与 0x10000 (64 K) 对齐，则该工具会报错。
 
 app 分区的大小和偏移地址可以采用十进制数、以 0x 为前缀的十六进制数，且支持 K 或 M 的倍数单位（分别代表 1024 和 1024*1024 字节）。
 

docs/zh_CN/get-started/start-project.rst

@@ -1,6 +1,6 @@
 {IDF_TARGET_CORE_NUM:default="2", esp32s2="1", esp32c3="1", esp32c2="1", esp32c6="1"}
 
-{IDF_TARGET_FEATURES:default="[NEEDS TO BE UPDATED]", esp32="WiFi/BT/BLE, silicon revision 1, 2MB external flash", esp32s2="WiFi, silicon revision 0, 2MB external flash", esp32s3="This is esp32s3 chip with 2 CPU core(s), WiFi/BLE, silicon revision 0, 2MB external flash", esp32c2="WiFi/BLE, silicon revision 0, 2MB embedded flash", esp32c3="WiFi/BLE, silicon revision 0, 2MB external flash", esp32c6="WiFi/BLE, 802.15.4 (Zigbee/Thread), silicon revision v0.0, 2MB external flash"}
+{IDF_TARGET_FEATURES:default="[NEEDS TO BE UPDATED]", esp32="WiFi/BT/BLE, silicon revision 1, 2 MB external flash", esp32s2="WiFi, silicon revision 0, 2 MB external flash", esp32s3="This is esp32s3 chip with 2 CPU core(s), WiFi/BLE, silicon revision 0, 2 MB external flash", esp32c2="WiFi/BLE, silicon revision 0, 2 MB embedded flash", esp32c3="WiFi/BLE, silicon revision 0, 2 MB external flash", esp32c6="WiFi/BLE, 802.15.4 (Zigbee/Thread), silicon revision v0.0, 2 MB external flash"}
 
 {IDF_TARGET_HEAP_SIZE:default="[NEEDS TO BE UPDATED]", esp32="298968", esp32s2="253900", esp32s3="390684", esp32c2="203888", esp32c3="337332", esp32c6="337332"}