Merge branch 'doc/esp_random' into 'master'

esp_random: Add some documentation about using before RF subsystem is on



See merge request !976

components/esp32/hw_random.c

@@ -24,11 +24,11 @@
 uint32_t IRAM_ATTR esp_random(void)
 {
     /* The PRNG which implements WDEV_RANDOM register gets 2 bits
-     * of extra entropy from a hardware randomness source every APB clock cycle.
-     * To make sure entropy is not drained faster than it is added,
-     * this function needs to wait for at least 16 APB clock cycles after reading
-     * previous word. This implementation may actually wait a bit longer
-     * due to extra time spent in arithmetic and branch statements.
+     * of extra entropy from a hardware randomness source every APB clock cycle
+     * (provided WiFi or BT are enabled). To make sure entropy is not drained
+     * faster than it is added, this function needs to wait for at least 16 APB
+     * clock cycles after reading previous word. This implementation may actually
+     * wait a bit longer due to extra time spent in arithmetic and branch statements.
      *
      * As a (probably unncessary) precaution to avoid returning the
      * RNG state as-is, the result is XORed with additional

components/esp32/include/esp_system.h

@@ -105,7 +105,15 @@ uint32_t esp_get_minimum_free_heap_size( void );
 /**
  * @brief  Get one random 32-bit word from hardware RNG
  *
- * @return random value between 0 and UINT32_MAX
+ * The hardware RNG is fully functional whenever an RF subsystem is running (ie Bluetooth or WiFi is enabled). For secure
+ * random values, call this function after WiFi or Bluetooth are started.
+ *
+ * When the app is running without an RF subsystem enabled, it should be considered a PRNG. To help improve this
+ * situation, the RNG is pre-seeded with entropy while the IDF bootloader is running. However no new entropy is
+ * available during the window of time between when the bootloader exits and an RF subsystem starts. It may be possible
+ * to discern a non-random pattern in a very large amount of output captured during this window of time.
+ *
+ * @return Random value between 0 and UINT32_MAX
  */
 uint32_t esp_random(void);