From 4d4e094d81c364fad1e26e72d638e1e493248c06 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Thu, 6 May 2021 16:59:02 +1000
Subject: [PATCH] esp_hw_support: Clarify the documentation about hardware RNG
 entropy

---
 .../include/bootloader_random.h               | 13 ++++-----
 .../esp_hw_support/include/esp_random.h       | 27 +++++++++++++------
 2 files changed, 26 insertions(+), 14 deletions(-)

diff --git a/components/bootloader_support/include/bootloader_random.h b/components/bootloader_support/include/bootloader_random.h
index 98a7712f33..0c7b61eb9b 100644
--- a/components/bootloader_support/include/bootloader_random.h
+++ b/components/bootloader_support/include/bootloader_random.h
@@ -24,13 +24,14 @@ extern "C" {
  * @brief Enable early entropy source for RNG
  *
  * Uses the SAR ADC to feed entropy into the HWRNG. The ADC is put
- * into a test mode that reads the 1.1V internal reference source and
- * feeds the LSB of data into the HWRNG.
+ * into a test mode that reads an internal reference voltage and
+ * constantly feeds the LSB of data into the HWRNG. Consult the
+ * SoC Technical Reference Manual for more information.
  *
- * Can also be used from app code early during operation, if entropy
- * is required before WiFi stack is initialised. Call this function
- * from app code only if WiFi/BT are not yet enabled and I2S and SAR
- * ADC are not in use.
+ * Can also be used from app code early during operation, if true
+ * random numbers are required before WiFi stack is initialised.
+ * Call this function from app code only if WiFi/BT are not yet
+ * enabled and I2S and ADC are not in use.
  *
  * Call bootloader_random_disable() when done.
  */
diff --git a/components/esp_hw_support/include/esp_random.h b/components/esp_hw_support/include/esp_random.h
index 26756b9db8..7064fa8115 100644
--- a/components/esp_hw_support/include/esp_random.h
+++ b/components/esp_hw_support/include/esp_random.h
@@ -24,16 +24,27 @@ extern "C" {
 /**
  * @brief  Get one random 32-bit word from hardware RNG
  *
- * The hardware RNG is fully functional whenever an RF subsystem is running (ie Bluetooth or WiFi is enabled). For
- * random values, call this function after WiFi or Bluetooth are started.
+ * The hardware RNG produces true random numbers under any of the following conditions:
  *
- * If the RF subsystem is not used by the program, the function bootloader_random_enable() can be called to enable an
- * entropy source. bootloader_random_disable() must be called before RF subsystem or I2S peripheral are used. See these functions'
- * documentation for more details.
+ * - An RF subsystem is running (i.e. Bluetooth or WiFi is enabled)
+ * - An internal entropy source has been enabled by calling bootloader_random_enable()
+ *   and not yet disabled by calling bootloader_random_disable()
+ * - While the ESP-IDF bootloader is running (due to the internal entropy source being enabled
+ *   for the duration of bootloader execution).
  *
- * Any time the app is running without an RF subsystem (or bootloader_random) enabled, RNG hardware should be
- * considered a PRNG. A very small amount of entropy is available due to pre-seeding while the IDF
- * bootloader is running, but this should not be relied upon for any use.
+ * If none of the above conditions are true, the hardware RNG will produce pseudo-random numbers only.
+ *
+ * When the hardware RNG is producing true random numbers, external entropy (noise samples) are
+ * continuously mixed into the internal hardware RNG state. Consult the SoC Technical Reference Manual
+ * for more details.
+ *
+ * This function automatically busy-waits to ensure enough external entropy has been
+ * introduced into the hardware RNG state, before returning a new random number.
+ *
+ * If generating random numbers from an app which has not yet enabled Bluetooth or Wi-Fi, call the
+ * API function bootloader_random_enable() before generating random numbers and then call
+ * bootloader_random_disable() before using any APIs for Bluetooth, Wi-Fi, ADC, or I2S. Consult the
+ * bootloader_random.h header for more details.
  *
  * @return Random value between 0 and UINT32_MAX
  */