Merge branch 'fix/improve_rng_documentation' into 'master'

fix(docs): Improved RNG documentation

Closes IDFGH-13813

See merge request espressif/esp-idf!36038

docs/_static/esp_rng_noise_source_rf_available.svg

@@ -0,0 +1,77 @@
+<svg width="600" height="200" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <style>
+      .box { fill: #f0f0f0; stroke: #333; stroke-width: 2; }
+      .text { font-family: Arial, sans-serif; font-size: 12px; text-anchor: middle; dominant-baseline: middle; }
+      .small-text { font-family: Arial, sans-serif; font-size: 10px; text-anchor: middle; dominant-baseline: middle; }
+      .wire { stroke: #333; stroke-width: 1.5; fill: none; }
+      .arrow { fill: #333; }
+    </style>
+  </defs>
+
+  <!-- SAR ADC -->
+  <rect x="10" y="15" width="100" height="40" class="box"/>
+  <text x="60" y="35" class="text">SAR ADC</text>
+
+  <!-- High Speed ADC -->
+  <rect x="10" y="80" width="100" height="40" class="box"/>
+  <text x="60" y="95" class="text">High Speed</text>
+  <text x="60" y="110" class="text">ADC</text>
+
+  <!-- RC_FAST_CLK -->
+  <rect x="10" y="140" width="100" height="40" class="box"/>
+  <text x="60" y="160" class="small-text">RC_FAST_CLK</text>
+
+  <!-- Entropy source labels -->
+  <text x="150" y="20" class="small-text">Entropy source</text>
+
+  <text x="150" y="107" class="small-text">Entropy source</text>
+
+  <text x="150" y="155" class="small-text">Entropy source</text>
+
+  <!-- XOR gates -->
+  <!-- First XOR gate -->
+  <path d="M 200 30 Q 210 30 220 40 Q 210 50 200 50 L 180 50 Q 190 40 180 30 Z" class="box"/>
+  <text x="200" y="40" class="small-text">XOR</text>
+
+  <!-- Second XOR gate -->
+  <path d="M 280 70 Q 290 70 300 80 Q 290 90 280 90 L 260 90 Q 270 80 260 70 Z" class="box"/>
+  <text x="280" y="80" class="small-text">XOR</text>
+
+  <!-- Random Number Generator -->
+  <rect x="350" y="60" width="120" height="40" class="box"/>
+  <text x="410" y="75" class="text">Random</text>
+  <text x="410" y="85" class="text">Number</text>
+  <text x="410" y="95" class="text">Generator</text>
+
+  <!-- RNG_DATA_REG output -->
+  <text x="520" y="70" class="text">RNG_DATA_REG</text>
+
+  <!-- Wires -->
+  <!-- SAR ADC to first XOR (top input) -->
+  <line x1="110" y1="35" x2="180" y2="35" class="wire"/>
+
+  <!-- High Speed ADC to first XOR (bottom input) -->
+  <line x1="110" y1="100" x2="140" y2="100" class="wire"/>
+  <line x1="140" y1="100" x2="140" y2="45" class="wire"/>
+  <line x1="140" y1="45" x2="180" y2="45" class="wire"/>
+
+  <!-- RC_FAST_CLK to second XOR (bottom input) -->
+  <line x1="110" y1="160" x2="240" y2="160" class="wire"/>
+  <line x1="240" y1="160" x2="240" y2="85" class="wire"/>
+  <line x1="240" y1="85" x2="260" y2="85" class="wire"/>
+
+  <!-- First XOR to second XOR (top input) -->
+  <line x1="220" y1="40" x2="240" y2="40" class="wire"/>
+  <line x1="240" y1="40" x2="240" y2="75" class="wire"/>
+  <line x1="240" y1="75" x2="260" y2="75" class="wire"/>
+
+  <!-- Second XOR to RNG -->
+  <line x1="300" y1="80" x2="350" y2="80" class="wire"/>
+
+  <!-- RNG to output -->
+  <line x1="470" y1="80" x2="520" y2="80" class="wire"/>
+
+  <!-- Arrow at the end -->
+  <polygon points="520,75 520,85 530,80" class="arrow"/>
+</svg>

docs/_static/esp_rng_noise_source_rf_unavailable.svg

@@ -0,0 +1,57 @@
+<svg width="600" height="200" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <style>
+      .box { fill: #f0f0f0; stroke: #333; stroke-width: 2; }
+      .text { font-family: Arial, sans-serif; font-size: 12px; text-anchor: middle; dominant-baseline: middle; }
+      .small-text { font-family: Arial, sans-serif; font-size: 10px; text-anchor: middle; dominant-baseline: middle; }
+      .wire { stroke: #333; stroke-width: 1.5; fill: none; }
+      .arrow { fill: #333; }
+    </style>
+  </defs>
+
+  <!-- SAR ADC -->
+  <rect x="10" y="50" width="100" height="40" class="box"/>
+  <text x="60" y="70" class="text">SAR ADC</text>
+
+  <!-- RC_FAST_CLK -->
+  <rect x="10" y="110" width="100" height="40" class="box"/>
+  <text x="60" y="130" class="small-text">RC_FAST_CLK</text>
+
+  <!-- Entropy source labels -->
+  <text x="150" y="64" class="small-text">Entropy source</text>
+
+  <text x="150" y="124" class="small-text">Entropy source</text>
+
+  <!-- XOR gate -->
+  <path d="M 220 80 Q 230 80 240 90 Q 230 100 220 100 L 200 100 Q 210 90 200 80 Z" class="box"/>
+  <text x="220" y="90" class="small-text">XOR</text>
+
+  <!-- Random Number Generator -->
+  <rect x="350" y="70" width="120" height="40" class="box"/>
+  <text x="410" y="85" class="text">Random</text>
+  <text x="410" y="95" class="text">Number</text>
+  <text x="410" y="105" class="text">Generator</text>
+
+  <!-- RNG_DATA_REG output -->
+  <text x="520" y="90" class="text">RNG_DATA_REG</text>
+
+  <!-- Wires -->
+  <!-- SAR ADC to XOR (top input) -->
+  <line x1="110" y1="70" x2="160" y2="70" class="wire"/>
+  <line x1="160" y1="70" x2="160" y2="85" class="wire"/>
+  <line x1="160" y1="85" x2="200" y2="85" class="wire"/>
+
+  <!-- RC_FAST_CLK to XOR (bottom input) -->
+  <line x1="110" y1="130" x2="180" y2="130" class="wire"/>
+  <line x1="180" y1="130" x2="180" y2="95" class="wire"/>
+  <line x1="180" y1="95" x2="200" y2="95" class="wire"/>
+
+  <!-- XOR to RNG -->
+  <line x1="240" y1="90" x2="350" y2="90" class="wire"/>
+
+  <!-- RNG to output -->
+  <line x1="470" y1="90" x2="520" y2="90" class="wire"/>
+
+  <!-- Arrow at the end -->
+  <polygon points="520,85 520,95 530,90" class="arrow"/>
+</svg>

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

@@ -8,18 +8,60 @@ Random Number Generation
 
 {IDF_TARGET_NAME} contains a hardware random number generator (RNG). You can use the APIs :cpp:func:`esp_random` and :cpp:func:`esp_fill_random` to obtained random values from it.
 
+Every 32-bit value that the system reads from the RNG_DATA_REG register of the random number generator is a true random number. These true random numbers are generated based on the thermal noise in the system and the asynchronous clock mismatch.
+
+.. only:: SOC_WIFI_SUPPORTED or SOC_IEEE802154_SUPPORTED or SOC_BT_SUPPORTED
+
+    - Thermal noise comes from the high-speed ADC or SAR ADC or both. Whenever the high-speed ADC or SAR ADC is enabled, bit streams will be generated and fed into the random number generator through an XOR logic gate as random seeds.
+
+.. only:: not SOC_WIFI_SUPPORTED and not SOC_IEEE802154_SUPPORTED and not SOC_BT_SUPPORTED
+
+    - Thermal noise comes from the SAR ADC. Whenever the SAR ADC is enabled, bit streams will be generated and fed into the random number generator through an XOR logic gate as random seeds.
+
+.. 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.
+
+The following digram shows the noise sources for the RNG on the {IDF_TARGET_NAME}:
+
+.. 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
+
 The hardware RNG produces true random numbers so long as one or more of the following conditions are met:
 
 .. 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.
+    :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`.
+    - 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.
 
 When any of these conditions are true, samples of physical noise are continuously mixed into the internal hardware RNG state to provide entropy. Consult the **{IDF_TARGET_NAME} Technical Reference Manual** > **Random Number Generator (RNG)** [`PDF <{IDF_TARGET_TRM_EN_URL}#rng>`__] chapter for more details.
 
 If none of the above conditions are true, the output of the RNG should be considered as pseudo-random only.
 
+.. only:: SOC_WIFI_SUPPORTED or SOC_IEEE802154_SUPPORTED or SOC_BT_SUPPORTED
+
+    .. _enabling RF subsystem:
+
+    Enabling RF subsystem
+    ---------------------
+
+    The RF subsystem can be enabled with help of one of the following APIs:
+
+    .. list::
+
+        :SOC_WIFI_SUPPORTED: - Wi-Fi: :cpp:func:`esp_wifi_start`
+        :SOC_BT_SUPPORTED: - Bluetooth (NimBLE): :cpp:func:`nimble_port_init()` which internally calls :cpp:func:`esp_bt_controller_enable()`
+        :SOC_BT_SUPPORTED: - Bluetooth (Bluedroid): :cpp:func:`esp_bt_controller_enable()`
+        :SOC_IEEE802154_SUPPORTED: - Thread/Zigbee: :cpp:func:`esp_openthread_init`
+
 Startup
 -------
 
@@ -27,21 +69,19 @@ 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
 
-    However, after the application starts executing, then normally only pseudo-random numbers are available until the internal entropy source has been enabled again.
+    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:
+    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::
+    .. list::
 
         - ADC
-
         :esp32: - I2S
-
         :SOC_WIFI_SUPPORTED or SOC_IEEE802154_SUPPORTED or SOC_BT_SUPPORTED: - {IDF_TARGET_RF_NAME}
 
 .. note::
@@ -54,6 +94,8 @@ To re-enable the entropy source temporarily during application startup, or for a
 
 .. only:: not esp32
 
+    .. _secondary entropy:
+
     Secondary Entropy
     -----------------