Merge branch 'docs/backport_random_to_v5.5' into 'release/v5.5'

docs: Backport random.rst to v5.5

See merge request espressif/esp-idf!42667

Author: suda-morris

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

@@ -20,9 +20,9 @@ Every 32-bit value that the system reads from the RNG_DATA_REG register of the r
 
 .. only:: not esp32
 
-    - RC_FAST_CLK is an asynchronous clock source and it increases the RNG entropy by introducing circuit metastability. See the :ref:`secondary entropy` section for more details.
+    - RC_FAST_CLK is an asynchronous clock source, and it increases the RNG entropy by introducing circuit metastability. See the :ref:`secondary entropy` section for more details.
 
-The following digram shows the noise sources for the RNG on the {IDF_TARGET_NAME}:
+The following diagram shows the noise sources for the RNG on the {IDF_TARGET_NAME}:
 
 .. only:: SOC_WIFI_SUPPORTED or SOC_IEEE802154_SUPPORTED or SOC_BT_SUPPORTED
 
@@ -38,7 +38,7 @@ The hardware RNG produces true random numbers so long as one or more of the foll
 
 .. list::
 
-    :SOC_WIFI_SUPPORTED or SOC_IEEE802154_SUPPORTED or SOC_BT_SUPPORTED: - RF subsystem is enabled. i.e., {IDF_TARGET_RF_NAME} {IDF_TARGET_RF_IS} enabled. When enabled, the RF subsystem internally enables the High Speed ADC that can be used as the entropy source. The High Speed ADC may only be available when the respective RF subsystem is active (e.g., not in sleep mode). See the :ref:`enabling RF subsystem` section for more details.
+    :SOC_WIFI_SUPPORTED or SOC_IEEE802154_SUPPORTED or SOC_BT_SUPPORTED: - RF subsystem is enabled, i.e., {IDF_TARGET_RF_NAME} {IDF_TARGET_RF_IS} enabled. When enabled, the RF subsystem internally enables the High Speed ADC that can be used as the entropy source. The High Speed ADC may only be available when the respective RF subsystem is active (e.g., not in sleep mode). See the :ref:`enabling RF subsystem` section for more details.
     - The internal entropy source SAR ADC has been enabled by calling :cpp:func:`bootloader_random_enable` and not yet disabled by calling :cpp:func:`bootloader_random_disable`.
     - While the ESP-IDF :ref:`second-stage-bootloader` is running. This is because the default ESP-IDF bootloader implementation calls :cpp:func:`bootloader_random_enable` when the bootloader starts, and :cpp:func:`bootloader_random_disable` before executing the application.
 
@@ -69,13 +69,12 @@ During startup, the ESP-IDF bootloader temporarily enables the non-RF internal e
 
 .. only:: not SOC_WIFI_SUPPORTED and not SOC_IEEE802154_SUPPORTED and not SOC_BT_SUPPORTED
 
-    For {IDF_TARGET_NAME}, the High Speed ADC is not available. Hence the non-RF internal entropy source (SAR ADC) is kept enabled by default at the time of application startup.
+    For {IDF_TARGET_NAME}, the High Speed ADC is not available. Hence, the non-RF internal entropy source (SAR ADC) is kept enabled by default at the time of application startup.
 
 .. only:: SOC_WIFI_SUPPORTED or SOC_IEEE802154_SUPPORTED or SOC_BT_SUPPORTED
 
     However, after the application starts executing, then normally only pseudo-random numbers are available until {IDF_TARGET_RF_NAME} {IDF_TARGET_RF_IS} initialized or until the internal entropy source has been enabled again.
 
-
     To re-enable the entropy source temporarily during application startup, or for an application that does not use {IDF_TARGET_RF_NAME}, call the function :cpp:func:`bootloader_random_enable` to re-enable the internal entropy source. The function :cpp:func:`bootloader_random_disable` must be called to disable the entropy source again before using any of the following features:
 
     .. list::

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

@@ -8,41 +8,80 @@
 
 {IDF_TARGET_NAME} 中包含一个硬件随机数发生器 (RNG)，可以调用 API :cpp:func:`esp_random` 和 :cpp:func:`esp_fill_random` 从中获取随机数值。
 
+系统从随机数生成器的 RNG_DATA_REG 寄存器中读取的每一个 32 位数值都是一个真正的随机数。这些真正的随机数是基于系统中的热噪声和异步时钟失配生成的。
+
+.. only:: SOC_WIFI_SUPPORTED or SOC_IEEE802154_SUPPORTED or SOC_BT_SUPPORTED
+
+    - 热噪声来自高速 ADC、SAR ADC 或两者。当高速 ADC 或 SAR ADC 被启用时，会生成比特流，并作为随机种子通过 XOR 逻辑门输入到随机数生成器中。
+
+.. only:: not SOC_WIFI_SUPPORTED and not SOC_IEEE802154_SUPPORTED and not SOC_BT_SUPPORTED
+
+    - 热噪声来自 SAR ADC。当 SAR ADC 被启用时，会生成比特流，并作为随机种子通过 XOR 逻辑门输入到随机数生成器中。
+
+.. only:: not esp32
+
+    - RC_FAST_CLK 是一种异步时钟源，它通过引入电路亚稳态来增加 RNG 的熵值。详细信息请参阅 :ref:`secondary entropy` 部分。
+
+下图展示了 {IDF_TARGET_NAME} 上 RNG 的噪声来源：
+
+.. only:: SOC_WIFI_SUPPORTED or SOC_IEEE802154_SUPPORTED or SOC_BT_SUPPORTED
+
+    .. image:: /../_static/esp_rng_noise_source_rf_available.svg
+        :align: center
+
+.. only:: not SOC_WIFI_SUPPORTED and not SOC_IEEE802154_SUPPORTED and not SOC_BT_SUPPORTED
+
+    .. image:: /../_static/esp_rng_noise_source_rf_unavailable.svg
+        :align: center
+
 满足下列任意一个或多个条件时，硬件 RNG 会产生真随机数：
 
 .. list::
 
-    :SOC_WIFI_SUPPORTED or SOC_IEEE802154_SUPPORTED or SOC_BT_SUPPORTED: - RF 子系统已启用，即 {IDF_TARGET_RF_NAME} {IDF_TARGET_RF_IS}。
+    :SOC_WIFI_SUPPORTED or SOC_IEEE802154_SUPPORTED or SOC_BT_SUPPORTED: - RF 子系统，即 {IDF_TARGET_RF_NAME} {IDF_TARGET_RF_IS}。启用后，RF 子系统会在内部启用高速 ADC，该 ADC 可用作熵源。高速 ADC 可能仅在相应的 RF 子系统处于活动状态（例如未处于睡眠模式）时可用。详细信息请参阅 :ref:`enabling RF subsystem` 部分。
     - 调用 :cpp:func:`bootloader_random_enable` 启用了内部熵源 (SAR ADC)，且熵源尚未被 :cpp:func:`bootloader_random_disable` 禁用。
     - 在 :ref:`second-stage-bootloader` 运行时。这是因为默认的 ESP-IDF 引导加载程序启动时会调用 :cpp:func:`bootloader_random_enable`，并在执行应用程序前调用 :cpp:func:`bootloader_random_disable`。
 
 当上述任一条件为真时，物理噪声样本会连续混合到内部硬件 RNG 状态中来提供熵。如需了解详情，请参阅 **{IDF_TARGET_NAME} 技术参考手册** > **随机数发生器 (RNG)** [`PDF <{IDF_TARGET_TRM_CN_URL}#rng>`__] 章节。
 
 如果上述条件都不满足，那么 RNG 的输出仅应被看作伪随机数。
 
+.. only:: SOC_WIFI_SUPPORTED or SOC_IEEE802154_SUPPORTED or SOC_BT_SUPPORTED
+
+    .. _enabling RF subsystem:
+
+    启用 RF 子系统
+    ---------------
+
+    可以通过以下任一 API 来启用 RF 子系统：
+
+    .. list::
+
+        :SOC_WIFI_SUPPORTED: - Wi-Fi: :cpp:func:`esp_wifi_start`
+        :SOC_BT_SUPPORTED: - 蓝牙 (NimBLE): :cpp:func:`nimble_port_init()` 会在内部调用 :cpp:func:`esp_bt_controller_enable()`
+        :SOC_BT_SUPPORTED: - 蓝牙 (Bluedroid): :cpp:func:`esp_bt_controller_enable()`
+        :SOC_IEEE802154_SUPPORTED: - Thread/Zigbee: :cpp:func:`esp_openthread_init`
+
 启动
 -------
 
 在启动过程中，ESP-IDF 引导加载程序暂时会启用一个非 RF 内部熵源（SAR ADC 使用内部参考电压噪声），为首次生成的启动密钥提供熵。
 
 .. only:: not SOC_WIFI_SUPPORTED and not SOC_IEEE802154_SUPPORTED and not SOC_BT_SUPPORTED
 
-    但是，当应用程序开始执行后，一直到内部熵源再次被启用前，通常只有伪随机数可用。
+    对于 {IDF_TARGET_NAME}，高速 ADC 不可用。因此，在应用启动时，非 RF 内部熵源 (SAR ADC) 默认保持启用状态。
 
 .. only:: SOC_WIFI_SUPPORTED or SOC_IEEE802154_SUPPORTED or SOC_BT_SUPPORTED
 
     但是，当应用程序开始执行后，一直到 {IDF_TARGET_RF_NAME} 初始化完成前或内部熵源再次被启用前，通常只有伪随机数可用。
 
+    如需在应用程序启动期间临时重启熵源，或为不使用 {IDF_TARGET_RF_NAME} 的应用程序临时重启熵源，请调用函数 :cpp:func:`bootloader_random_enable` 重启内部熵源。在使用下列任一功能前，必须调用函数 :cpp:func:`bootloader_random_disable` 以禁用熵源。
 
-如需在应用程序启动期间临时重启熵源，或为不使用 {IDF_TARGET_RF_NAME} 的应用程序临时重启熵源，请调用函数 :cpp:func:`bootloader_random_enable` 重启内部熵源。在使用下列任一功能前，必须调用函数 :cpp:func:`bootloader_random_disable` 以禁用熵源。
-
-.. list::
+    .. list::
 
-    - ADC
-
-    :esp32: - I2S
-
-    :SOC_WIFI_SUPPORTED or SOC_IEEE802154_SUPPORTED or SOC_BT_SUPPORTED: - {IDF_TARGET_RF_NAME}
+        - ADC
+        :esp32: - I2S
+        :SOC_WIFI_SUPPORTED or SOC_IEEE802154_SUPPORTED or SOC_BT_SUPPORTED: - {IDF_TARGET_RF_NAME}
 
 .. note::
 
@@ -54,6 +93,8 @@
 
 .. only:: not esp32
 
+    .. _secondary entropy:
+
     二级熵源
     -----------------