espressif/esp-idf
1
0
Fork 1
mirror of https://github.com/espressif/esp-idf.git synced 2026-05-05 20:35:08 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: Update CN translation for random.rst

Browse Source
This commit is contained in:
Shen Mengjing
2025-09-24 16:45:55 +08:00
parent b614744808
commit 10b4e56dca
2 changed files with 55 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/en/api-reference/system/random.rst
+4 -5
View File
@@ -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
+51 -10
View File
@@ -8,11 +8,37 @@
{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`。
@@ -20,6 +46,22 @@
如果上述条件都不满足，那么 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`
启动
-------
@@ -27,22 +69,19 @@
.. 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:
二级熵源
-----------------