Merge branch 'docs/update_cn_trans_dec' into 'master'

Docs: update CN trans for sleep_modes.rst, misc_system_api.rst, migration_guides/peripherals.rst

Closes DOC-4272

See merge request espressif/esp-idf!21617

docs/en/api-reference/system/misc_system_api.rst

@@ -94,7 +94,7 @@ In ESP-IDF, the MAC addresses for the various network interfaces are calculated
 Custom Interface MAC
 ^^^^^^^^^^^^^^^^^^^^
 
-Sometimes you may need to define custom MAC addresses that are not generated from the base MAC address. To set a custom interface MAC address, use the :cpp:func:`esp_iface_mac_addr_set` function. This function allows you to overwrite the MAC addresses of interfaces set (or not yet set) by the base MAC address. Once a MAC address has been set for a particular interface, changing the base MAC address does not affect it.
+Sometimes you may need to define custom MAC addresses that are not generated from the base MAC address. To set a custom interface MAC address, use the :cpp:func:`esp_iface_mac_addr_set` function. This function allows you to overwrite the MAC addresses of interfaces set (or not yet set) by the base MAC address. Once a MAC address has been set for a particular interface, it will not be affected when the base MAC address is changed.
 
 Custom Base MAC
 ^^^^^^^^^^^^^^^
@@ -111,7 +111,7 @@ The custom base MAC addresses should be allocated such that derived MAC addresse
 Custom MAC Address in eFuse
 @@@@@@@@@@@@@@@@@@@@@@@@@@@
 
-When reading custom MAC addresses from eFuse, ESP-IDF provides a helper function :cpp:func:`esp_efuse_mac_get_custom` or use :cpp:func:`esp_read_mac` with the ``ESP_MAC_EFUSE_CUSTOM`` argument. This loads the MAC address from eFuse BLK3. The :cpp:func:`esp_efuse_mac_get_custom` function assumes that the custom base MAC address is stored in the following format:
+When reading custom MAC addresses from eFuse, ESP-IDF provides a helper function :cpp:func:`esp__mac_get_custom`. Users can also use :cpp:func:`esp_read_mac` with the ``ESP_MAC_EFUSE_CUSTOM`` argument. This loads the MAC address from eFuse BLK3. The :cpp:func:`esp__mac_get_custom` function assumes that the custom base MAC address is stored in the following format:
 
 .. only:: esp32
 
@@ -130,11 +130,11 @@ When reading custom MAC addresses from eFuse, ESP-IDF provides a helper function
         * - Reserved
           - 128
           - 183:56
-          - 
+          -
         * - MAC address
           - 48
           - 55:8
-          - 
+          -
         * - MAC address CRC
           - 8
           - 7:0
@@ -159,12 +159,12 @@ When reading custom MAC addresses from eFuse, ESP-IDF provides a helper function
 
     .. note::
 
-        The eFuse BLK3 uses RS-coding during a burn operation, which means that all eFuse fields in this block must be burnt at the same time.
+        The eFuse BLK3 uses RS-coding during burning, which means that all eFuse fields in this block must be burnt at the same time.
 
-Once custom efuse MAC address has been obtained (using cpp:func:`esp_efuse_mac_get_custom` or :cpp:func:`esp_read_mac`) you need to set it as the base MAC address. There is two ways to do it:
+Once custom eFuse MAC address has been obtained (using :cpp:func:`esp_efuse_mac_get_custom` or :cpp:func:`esp_read_mac`), you need to set it as the base MAC address. There are two ways to do it:
 
-1. using an old API, call :cpp:func:`esp_base_mac_addr_set`.
-2. using a new API, call :cpp:func:`esp_iface_mac_addr_set` with the ``ESP_MAC_BASE`` argument.
+1. Use an old API: call :cpp:func:`esp_base_mac_addr_set`.
+2. Use a new API: call :cpp:func:`esp_iface_mac_addr_set` with the ``ESP_MAC_BASE`` argument.
 
 
 .. _local-mac-addresses:

docs/en/api-reference/system/sleep_modes.rst

@@ -102,10 +102,10 @@ RTC peripherals or RTC memories don't need to be powered on during sleep in this
         rtc_gpio_pullup_dis(gpio_num);
         rtc_gpio_pulldown_en(gpio_num);
 
-    .. warning:: 
-        - To use the EXT1 wakeup, the IO pad(s) are configured as RTC IO. Thus if these pads want to be used as digital GPIOs after waking up from sleep, :cpp:func:`rtc_gpio_deinit` needs to be called first.
+    .. warning::
+        - To use the EXT1 wakeup, the IO pad(s) are configured as RTC IO. Therefore, before using these pads as digital GPIOs, users need to reconfigure them by calling the :cpp:func:`rtc_gpio_deinit` function.
 
-        - If the RTC peripherals are configured to be powered down (which is by default), the wakeup IOs will be set to holding state before entering sleep. Therefore, after waking up from Light-sleep, please call `rtc_gpio_hold_dis` to disable the hold function to perform any pin re-configuration. For Deep-sleep wakeup, this is already being handled at the application startup stage.
+        - If the RTC peripherals are configured to be powered down (which is by default), the wakeup IOs will be set to the holding state before entering sleep. Therefore, after the chip wakes up from Light-sleep, please call `rtc_gpio_hold_dis` to disable the hold function to perform any pin re-configuration. For Deep-sleep wakeup, this is already being handled at the application startup stage.
 
     :cpp:func:`esp_sleep_enable_ext1_wakeup` function can be used to enable this wakeup source.
 
@@ -149,9 +149,9 @@ RTC peripherals or RTC memories don't need to be powered on during sleep in this
     GPIO Wakeup
     ^^^^^^^^^^^
 
-    Any IO can be used as the external input to wakeup the chip from Light-sleep. Each pin can be individually configured to trigger wakeup on high or low level using :cpp:func:`gpio_wakeup_enable` function. Then :cpp:func:`esp_sleep_enable_gpio_wakeup` function should be called to enable this wakeup source.
+    Any IO can be used as the external input to wake up the chip from Light-sleep. Each pin can be individually configured to trigger wakeup on high or low level using the :cpp:func:`gpio_wakeup_enable` function. Then the :cpp:func:`esp_sleep_enable_gpio_wakeup` function should be called to enable this wakeup source.
 
-    Additionally, IOs that are powered by the VDD3P3_RTC power domain can be used to wakeup the chip from Deep-sleep. The wakeup pin and wakeup trigger level can be configured by calling :cpp:func:`esp_deep_sleep_enable_gpio_wakeup`. The function will enable the Deep-sleep wakeup for the selected pin.
+    Additionally, IOs that are powered by the VDD3P3_RTC power domain can be used to wake up the chip from Deep-sleep. The wakeup pin and wakeup trigger level can be configured by calling :cpp:func:`esp_deep_sleep_enable_gpio_wakeup`. The function will enable the Deep-sleep wakeup for the selected pin.
 
 UART Wakeup (Light-sleep Only)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

docs/en/migration-guides/release-5.x/5.0/peripherals.rst

@@ -525,7 +525,7 @@ LCD
     TWAI Driver
     -----------
 
-    The deprecated ``CAN`` peripheral driver is removed. Please use ``TWAI`` driver instead (i.e. include ``driver/twai.h`` in your application).
+    The deprecated ``CAN`` peripheral driver is removed. Please use ``TWAI`` driver instead (i.e., include ``driver/twai.h`` in your application).
 
 Register Access Macros
 ----------------------
@@ -544,4 +544,4 @@ To store the value which would have been written into the register, split the op
 To get the value of the register after modification (which may be different from the value written), add an explicit read::
 
     REG_SET_BITS(reg, mask);
-    uint32_t new_val = REG_READ(reg);
+    uint32_t new_val = REG_READ(reg);

docs/en/migration-guides/release-5.x/5.1/peripherals.rst

@@ -8,17 +8,17 @@ Peripherals
     DAC
     ---
 
-    DAC driver has been redesigned (see :doc:`DAC API Reference <../../../api-reference/peripherals/dac>`), which aims to unify and extend the usage of DAC peripheral. Although it's recommended to use the new driver APIs, the legacy driver is still available in the previous include path ``driver/dac.h``. However, by default, including ``driver/dac.h`` will bring a build warning like `The legacy DAC driver is deprecated, please use 'driver/dac_oneshot.h', 'driver/dac_cosine.h' or 'driver/dac_continuous.h' instead`. The warning can be suppressed by the Kconfig option :ref:`CONFIG_DAC_SUPPRESS_DEPRECATE_WARN`.
+    DAC driver has been redesigned (see :doc:`DAC API Reference <../../../api-reference/peripherals/dac>`), which aims to unify the interface and extend the usage of DAC peripheral. Although it is recommended to use the new driver APIs, the legacy driver is still available in the previous include path ``driver/dac.h``. However, by default, including ``driver/dac.h`` will bring a build warning like ``The legacy DAC driver is deprecated, please use 'driver/dac_oneshot.h', 'driver/dac_cosine.h' or 'driver/dac_continuous.h' instead``. The warning can be suppressed by the Kconfig option :ref:`CONFIG_DAC_SUPPRESS_DEPRECATE_WARN`.
 
     The major breaking changes in concept and usage are listed as follows:
 
     Breaking Changes in Concepts
     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    - ``dac_channel_t`` which used to identify the hardware channel are removed from user space, the channel index now starts from ``0``, please use  `DAC_CHAN_0` and `DAC_CHAN_1` instead. And in the new driver, DAC channels can be seleted by :cpp:type:`dac_channel_mask_t`. And these channels can be allocated in a same channel group which is represented by :cpp:type:`dac_channels_handle_t`.
-    - ``dac_cw_scale_t`` is replaced by :cpp:type:`dac_cosine_atten_t`, to decupling the legacy driver and the new driver.
-    - ``dac_cw_phase_t`` is replaced by :cpp:type:`dac_cosine_phase_t`, the enum value is now the phase angle directly.
-    - ``dac_cw_config_t`` is replaced by :cpp:type:`dac_cosine_config_t`, but the ``en_ch`` field is removed because it should be specify while allocate the channel group.
+    - ``dac_channel_t`` which was used to identify the hardware channel are removed from user space. The channel index now starts from ``0``, so please use  `DAC_CHAN_0` and `DAC_CHAN_1` instead. And in the new driver, DAC channels can be selected by using :cpp:type:`dac_channel_mask_t`. And these channels can be allocated in a same channel group which is represented by :cpp:type:`dac_channels_handle_t`.
+    - ``dac_cw_scale_t`` is replaced by :cpp:type:`dac_cosine_atten_t` to decouple the legacy driver and the new driver.
+    - ``dac_cw_phase_t`` is replaced by :cpp:type:`dac_cosine_phase_t`. The enumerate value is now the phase angle directly.
+    - ``dac_cw_config_t`` is replaced by :cpp:type:`dac_cosine_config_t`, but the ``en_ch`` field is removed because it should be specified while allocating the channel group.
 
     .. only:: esp32s2
 
@@ -30,8 +30,8 @@ Peripherals
 
     - ``dac_pad_get_io_num`` is removed.
     - ``dac_output_voltage`` is replaced by :cpp:func:`dac_oneshot_output_voltage`.
-    - ``dac_output_enable`` is removed, for oneshot mode, it will be enabled after the channel allocated.
-    - ``dac_output_disable`` is removed, for oneshot mode, it will be disabled before the channel deleted.
+    - ``dac_output_enable`` is removed. For oneshot mode, it will be enabled after the channel is allocated.
+    - ``dac_output_disable`` is removed. For oneshot mode, it will be disabled before the channel is deleted.
     - ``dac_cw_generator_enable`` is replaced by :cpp:func:`dac_cosine_start`.
     - ``dac_cw_generator_disable`` is replaced by :cpp:func:`dac_cosine_stop`.
     - ``dac_cw_generator_config`` is replaced by :cpp:func:`dac_cosine_new_channel`.

docs/zh_CN/api-reference/system/misc_system_api.rst

@@ -91,6 +91,11 @@ MAC 地址
 
     .. note:: {IDF_TARGET_NAME} 内部未集成以太网 MAC 地址，但仍可以计算得出该地址。不过，以太网 MAC 地址只能与外部以太网接口（如 SPI 以太网设备）一起使用，具体请参阅 :doc:`/api-reference/network/esp_eth`。
 
+自定义接口 MAC
+^^^^^^^^^^^^^^^^
+
+有时用户可能需要自定义 MAC 地址，这些地址并不由基准 MAC 地址生成。如需设置自定义接口 MAC 地址，请使用 :cpp:func:`esp_iface_mac_addr_set` 函数。该函数用于覆盖由基准 MAC 地址设置（或尚未设置）的接口 MAC 地址。一旦设置某个接口 MAC 地址，即使更改基准 MAC 地址，也不会对其产生影响。
+
 自定义基准 MAC
 ^^^^^^^^^^^^^^^
 
@@ -106,7 +111,7 @@ MAC 地址
 eFuse 中的自定义 MAC 地址
 @@@@@@@@@@@@@@@@@@@@@@@@@@@
 
-ESP-IDF 提供了 :cpp:func:`esp_efuse_mac_get_custom` 函数。从 eFuse 读取自定义 MAC 地址时，调用该函数将从 eFuse BLK3 加载 MAC 地址。此函数假定自定义基准 MAC 地址的存储格式如下：
+ESP-IDF 提供了 :cpp:func:`esp_efuse_mac_get_custom` 函数，从 eFuse 读取自定义 MAC 地址时，调用该函数将从 eFuse BLK3 加载 MAC 地址。用户也可以调用 :cpp:func:`esp_read_mac` 函数，此时需使用 ``ESP_MAC_EFUSE_CUSTOM`` 参数。:cpp:func:`esp_efuse_mac_get_custom` 函数假定自定义基准 MAC 地址的存储格式如下：
 
 .. only:: esp32
 
@@ -125,11 +130,11 @@ ESP-IDF 提供了 :cpp:func:`esp_efuse_mac_get_custom` 函数。从 eFuse 读取
         * - Reserved
           - 128
           - 183:56
-          - 
+          -
         * - MAC address
           - 48
           - 55:8
-          - 
+          -
         * - MAC address CRC
           - 8
           - 7:0
@@ -156,7 +161,10 @@ ESP-IDF 提供了 :cpp:func:`esp_efuse_mac_get_custom` 函数。从 eFuse 读取
 
         eFuse BLK3 在烧写时使用 RS 编码，这意味着必须同时烧写该块中的所有 eFuse 字段。
 
-调用 :cpp:func:`esp_efuse_mac_get_custom` 函数获得 MAC 地址后，请调用 :cpp:func:`esp_base_mac_addr_set` 函数将此 MAC 地址设置为基准 MAC 地址。
+调用 :cpp:func:`esp_efuse_mac_get_custom` 或 :cpp:func:`esp_read_mac` 函数获得自定义 eFuse MAC 地址后，请将此 MAC 地址设置为基准 MAC 地址。有以下两种方法：
+
+1. 使用原有 API：调用 :cpp:func:`esp_base_mac_addr_set`。
+2. 使用新 API：调用 :cpp:func:`esp_iface_mac_addr_set`，此时需使用 ``ESP_MAC_BASE`` 参数。
 
 
 .. _local-mac-addresses:

docs/zh_CN/api-reference/system/sleep_modes.rst

@@ -102,7 +102,10 @@ RTC 控制器中内嵌定时器，可用于在预定义的时间到达后唤醒
         gpio_pullup_dis(gpio_num);
         gpio_pulldown_en(gpio_num);
 
-    .. warning:: 从睡眠模式中唤醒后，用于唤醒的 IO pad 将被配置为 RTC IO。因此在将该 pad 用作数字 GPIO 前，请调用 :cpp:func:`rtc_gpio_deinit` 函数对其进行重新配置。
+    .. warning::
+        - 使用 EXT1 唤醒源时，用于唤醒的 IO pad 将被配置为 RTC IO。因此，在将该 pad 用作数字 GPIO 之前，请调用 :cpp:func:`rtc_gpio_deinit` 函数对其进行重新配置。
+
+        - RTC 外设在默认情况下配置为断电，此时，唤醒 IO 在进入睡眠状态前将被设置为保持状态。因此，从 Light-sleep 状态唤醒芯片后，请调用 `rtc_gpio_hold_dis` 来禁用保持功能，以便对管脚进行重新配置。对于 Deep-sleep 唤醒，此问题已经在应用启动阶段解决。
 
     可调用 :cpp:func:`esp_sleep_enable_ext1_wakeup` 函数来启用此唤醒源。
 
@@ -141,6 +144,14 @@ RTC 控制器中内嵌定时器，可用于在预定义的时间到达后唤醒
 
             esp_sleep_pd_config(ESP_PD_DOMAIN_VDDSDIO, ESP_PD_OPTION_ON);
 
+.. only:: not SOC_RTCIO_WAKE_SUPPORTED
+
+    GPIO 唤醒
+    ^^^^^^^^^^^
+
+    任何一个 IO 都可以用作外部输入管脚，将芯片从 Light-sleep 状态唤醒。调用 :cpp:func:`gpio_wakeup_enable` 函数可以将任意管脚单独配置为在高电平或低电平触发唤醒。此后，应调用 :cpp:func:`esp_sleep_enable_gpio_wakeup` 函数来启用此唤醒源。
+
+    此外，可将由 VDD3P3_RTC 电源域供电的 IO 用于芯片的 Deep-sleep 唤醒。调用 :cpp:func:`esp_deep_sleep_enable_gpio_wakeup` 函数可以配置相应的唤醒管脚和唤醒触发电平，该函数用于启用相应管脚的 Deep-sleep 唤醒功能。
 
 UART 唤醒（仅适用于 Light-sleep 模式）
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

docs/zh_CN/migration-guides/release-5.x/5.0/peripherals.rst

@@ -520,6 +520,13 @@ LCD
     7. 通过调用 :cpp:func:`i2s_channel_disable` 可以停止使用 I2S 通道的硬件资源。
     8. 不再使用某通道时，通过调用 :cpp:func:`i2s_del_channel` 可以删除和释放该通道资源，但是删除之前必须先停用该通道。
 
+.. only:: SOC_TWAI_SUPPORTED
+
+    TWAI 驱动程序
+    --------------
+
+    ``CAN`` 外设驱动程序已弃用并被删除，请使用 ``TWAI`` 驱动程序代替（即在应用程序中包括 ``driver/twai.h``）。
+
 用于访问寄存器的宏
 ---------------------------------------------
 
@@ -537,4 +544,4 @@ LCD
 要获得修改后的寄存器的值（该值可能与写入的值不同），要增加一个显示的读取命令::
 
     REG_SET_BITS(reg, mask);
-    uint32_t new_val = REG_READ(reg);
+    uint32_t new_val = REG_READ(reg);

docs/zh_CN/migration-guides/release-5.x/5.1/peripherals.rst

@@ -2,3 +2,48 @@
 ============
 
 :link_to_translation:`en:[English]`
+
+.. only:: SOC_DAC_SUPPORTED
+
+    DAC
+    ---
+
+    DAC 驱动程序已经过重新设计（参考 :doc:`DAC API 参考 <../../../api-reference/peripherals/dac>`），以统一接口并扩展 DAC 外设的使用。建议使用更新后的驱动 API，但用户仍然可以通过包含路径 ``driver/dac.h`` 使用原有驱动。然而默认情况下，在文件中包含 ``driver/dac.h`` 会引发构建警告，例如 ``The legacy DAC driver is deprecated, please use 'driver/dac_oneshot.h', 'driver/dac_cosine.h' or 'driver/dac_continuous.h' instead``。可通过 Kconfig 选项 :ref:`CONFIG_DAC_SUPPRESS_DEPRECATE_WARN` 关闭该警告。
+
+    主要概念和使用方法上的更新如下所示：
+
+    主要概念更新
+    ^^^^^^^^^^^^^^^^^^
+
+    - 用于识别硬件通道的 ``dac_channel_t`` 已从用户空间被删除，更新后通道索引起始为 ``0``，请使用 `DAC_CHAN_0` 和 `DAC_CHAN_1` 代替原来的索引。在新驱动中可通过 :cpp:type:`dac_channel_mask_t` 删除 DAC 通道。这些通道可以被分配到同一个通道组中，由 :cpp:type:`dac_channels_handle_t` 表示。
+    - ``dac_cw_scale_t`` 更新为 :cpp:type:`dac_cosine_atten_t`，以区分原有驱动程序和新驱动程序。
+    - ``dac_cw_phase_t`` 更新为 :cpp:type:`dac_cosine_phase_t`，更新后，枚举值即为相位角。
+    - ``dac_cw_config_t`` 更新为 :cpp:type:`dac_cosine_config_t`，但删除了 ``en_ch`` 字段，因为该字段应在分配通道组时被指定。
+
+    .. only:: esp32s2
+
+        - ``dac_digi_convert_mode_t`` 已被删除。驱动程序现在可以通过调用 :cpp:func:`dac_channels_write_continuously` 或 :cpp:func:`dac_channels_write_cyclically` 以不同方式传输 DMA 数据。
+        - ``dac_digi_config_t`` 更新为 :cpp:type:`dac_continuous_config_t`。
+
+    主要使用方法更新
+    ^^^^^^^^^^^^^^^^^^^^
+
+    - ``dac_pad_get_io_num`` 已被删除。
+    - ``dac_output_voltage`` 更新为 :cpp:func:`dac_oneshot_output_voltage`。
+    - ``dac_output_enable`` 已被删除，单次采样模式下在分配通道后启用。
+    - ``dac_output_disable`` 已被删除，单次采样模式下在删除通道前被禁用。
+    - ``dac_cw_generator_enable`` 更新为 :cpp:func:`dac_cosine_start`。
+    - ``dac_cw_generator_disable`` 更新为 :cpp:func:`dac_cosine_stop`。
+    - ``dac_cw_generator_config`` 更新为  :cpp:func:`dac_cosine_new_channel`。
+
+    .. only:: esp32
+
+        - ``dac_i2s_enable`` 更新为 :cpp:func:`dac_continuous_enable`，但首先需要通过 :cpp:func:`dac_continuous_new_channels` 分配连续 DAC 通道。
+        - ``dac_i2s_disable`` 更新为 :cpp:func:`dac_continuous_disable`。
+
+    .. only:: esp32s2
+
+        - ``dac_digi_init`` 和 ``dac_digi_controller_config`` 合并为 :cpp:func:`dac_continuous_new_channels`。
+        - ``dac_digi_deinit`` 更新为 :cpp:func:`dac_continuous_del_channels`。
+        - ``dac_digi_start``、 ``dac_digi_fifo_reset`` 和 ``dac_digi_reset`` 合并为 :cpp:func:`dac_continuous_enable`。
+        - ``dac_digi_stop`` 更新为 :cpp:func:`dac_continuous_disable`。