docs: Add random number generation to the API Reference System section

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

@@ -27,6 +27,7 @@ System API
     Over The Air Updates (OTA) <ota>
     :CONFIG_IDF_TARGET_ARCH_XTENSA: Performance Monitor <perfmon>
     Power Management <power_management>
+    Random Number Generation <random>
     Sleep Modes <sleep_modes>
     Watchdogs <wdts>
     System Time <system_time>

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

@@ -0,0 +1,49 @@
+Random Number Generation
+========================
+
+{IDF_TARGET_RF_NAME: default="Wi-Fi or Bluetooth", esp32s2="Wi-Fi"}
+{IDF_TARGET_RF_IS: default="are", esp32s2="is"}
+{IDF_TARGET_BOOTLOADER_RANDOM_INCOMPATIBLE: default="", esp32="I2S, "}
+
+{IDF_TARGET_NAME} contains a hardware random number generator, values from it can be obtained using the APIs :cpp:func:`esp_random` and :cpp:func:`esp_fill_random`.
+
+The hardware RNG produces true random numbers under any of the following conditions:
+
+- RF subsystem is enabled (i.e. {IDF_TARGET_RF_NAME} {IDF_TARGET_RF_IS} enabled).
+- An internal entropy source 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 app.
+
+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 pseudo-random only.
+
+Startup
+-------
+
+During startup, ESP-IDF bootloader temporarily enables a non-RF entropy source (internal reference voltage noise) that provides entropy for any first boot key generation. However, after the app starts executing then normally only pseudo-random numbers are available until {IDF_TARGET_RF_NAME} {IDF_TARGET_RF_IS} initialized.
+
+To re-enable the entropy source temporarily during app 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 ADC, {IDF_TARGET_BOOTLOADER_RANDOM_INCOMPATIBLE}{IDF_TARGET_RF_NAME}.
+
+.. note::
+
+   The entropy source enabled during the boot process by the ESP-IDF Second Stage Bootloader will seed the internal RNG state with some entropy. However, the internal hardware RNG state is not large enough to provide a continuous stream of true random numbers. This is why a continuous entropy source must be enabled whenever true random numbers are required.
+
+.. note::
+
+   If an application requires a source of true random numbers but it is not possible to permanently enable a hardware entropy source, consider using a strong software DRBG implementation such as the mbedTLS CTR-DRBG or HMAC-DRBG, with an initial seed of entropy from hardware RNG true random numbers.
+
+.. only:: not esp32
+
+    Secondary Entropy
+    -----------------
+
+    {IDF_TARGET_NAME} RNG contains a secondary entropy source, based on sampling an asynchronous 8MHz internal oscillator (see the Technical Reference Manual for details). This entropy source is always enabled in ESP-IDF and continuously mixed into the RNG state by hardware. In testing, this secondary entropy source was sufficient to pass the `Dieharder`_ random number test suite without the main entropy source enabled (test input was created by concatenating short samples from a continuously resetting {IDF_TARGET_NAME}). However, it is currently only guaranteed that true random numbers will be produced when the main entropy source is also enabled as described above.
+
+API Reference
+-------------
+
+.. include-build-file:: inc/esp_random.inc
+.. include-build-file:: inc/bootloader_random.inc
+
+.. _Dieharder: https://webhome.phy.duke.edu/~rgb/General/dieharder.php
+

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

@@ -25,13 +25,6 @@ Two heap memory related functions are provided:
 
 Note that ESP-IDF supports multiple heaps with different capabilities. Functions mentioned in this section return the size of heap memory which can be allocated using ``malloc`` family of functions. For further information about heap memory see :doc:`Heap Memory Allocation <mem_alloc>`.
 
-Random number generation
-------------------------
-
-{IDF_TARGET_NAME} contains a hardware random number generator, values from it can be obtained using :cpp:func:`esp_random`.
-
-When Wi-Fi or Bluetooth are enabled, numbers returned by hardware random number generator (RNG) can be considered true random numbers. Without Wi-Fi or Bluetooth enabled, hardware RNG is a pseudo-random number generator. At startup, ESP-IDF bootloader seeds the hardware RNG with entropy, but care must be taken when reading random values between the start of ``app_main`` and initialization of Wi-Fi or Bluetooth drivers.
-
 .. _MAC-Address-Allocation:
 
 MAC Address
@@ -189,12 +182,9 @@ To set version in your project manually you need to set ``PROJECT_VER`` variable
 
 If :ref:`CONFIG_APP_PROJECT_VER_FROM_CONFIG` option is set, the value of :ref:`CONFIG_APP_PROJECT_VER` will be used. Otherwise if ``PROJECT_VER`` variable is not set in the project then it will be retrieved from either ``$(PROJECT_PATH)/version.txt`` file (if present) else using git command ``git describe``. If neither is available then ``PROJECT_VER`` will be set to "1". Application can make use of this by calling :cpp:func:`esp_ota_get_app_description` or :cpp:func:`esp_ota_get_partition_description` functions.
 
-
-
 API Reference
 -------------
 
 .. include-build-file:: inc/esp_system.inc
 .. include-build-file:: inc/esp_idf_version.inc
 
-