refactor(rng): move rng read data function to rng_ll.h and update docs of RNG source

components/bootloader_support/include/bootloader_random.h

@@ -15,8 +15,8 @@ extern "C" {
 /**
  * @brief Enable an entropy source for RNG if RF subsystem is disabled
  *
- * @warning This function is not safe to use if any other subsystem is accessing the RF subsystem or
- *          the ADC at the same time!
+ * @warning If use ADC as entropy source, this function is not safe
+ * if any other subsystem is accessing the RF subsystem or the ADC at the same time!
  *
  * The exact internal entropy source mechanism depends on the chip in use but
  * all SoCs use the SAR ADC to continuously mix random bits (an internal

components/bootloader_support/src/bootloader_random.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2010-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2010-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -7,7 +7,7 @@
 #include "esp_log.h"
 #include "bootloader_random.h"
 #include "esp_cpu.h"
-#include "soc/wdev_reg.h"
+#include "hal/rng_ll.h"
 
 #include "hal/rtc_timer_hal.h"
 
@@ -46,10 +46,10 @@
 
     for (size_t i = 0; i < length; i++) {
 #if !SOC_RTC_TIMER_V1
-        random = REG_READ(WDEV_RND_REG);
+        random = rng_ll_read_data();
         start = esp_cpu_get_cycle_count();
         do {
-            random ^= REG_READ(WDEV_RND_REG);
+            random ^= rng_ll_read_data();
             now = esp_cpu_get_cycle_count();
         } while (now - start < RNG_CPU_WAIT_CYCLE_NUM);
 
@@ -68,10 +68,10 @@
                as-is, we repeatedly read the RNG register and XOR all
                values.
             */
-            random = REG_READ(WDEV_RND_REG);
+            random = rng_ll_read_data();
             start = esp_cpu_get_cycle_count();
             do {
-                random ^= REG_READ(WDEV_RND_REG);
+                random ^= rng_ll_read_data();
                 now = esp_cpu_get_cycle_count();
             } while (now - start < RNG_CPU_WAIT_CYCLE_NUM);
         }

components/esp_hw_support/hw_random.c

@@ -11,7 +11,7 @@
 #include <sys/param.h>
 #include "esp_attr.h"
 #include "esp_cpu.h"
-#include "soc/wdev_reg.h"
+#include "hal/rng_ll.h"
 #include "esp_private/esp_clk.h"
 #include "soc/soc_caps.h"
 #include "esp_log.h"
@@ -24,9 +24,6 @@
 
 #if SOC_RNG_CLOCK_IS_INDEPENDENT
 #include "hal/lp_clkrst_ll.h"
-#if SOC_RNG_BUF_CHAIN_ENTROPY_SOURCE || SOC_RNG_RTC_TIMER_ENTROPY_SOURCE
-#include "hal/rng_ll.h"
-#endif
 #endif
 
 #if defined CONFIG_IDF_TARGET_ESP32S3
@@ -62,7 +59,7 @@ uint32_t IRAM_ATTR esp_random(void)
     // Return a fixed pattern for bringup purposes
     return 0x5A5A5A5A;
 #else
-    /* The PRNG which implements WDEV_RANDOM register gets 2 bits
+    /* The PRNG which implements the hardware RNG data register gets 2 bits
      * 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
@@ -71,7 +68,7 @@ uint32_t IRAM_ATTR esp_random(void)
      *
      * As a (probably unnecessary) precaution to avoid returning the
      * RNG state as-is, the result is XORed with additional
-     * WDEV_RND_REG reads while waiting.
+     * hardware RNG register reads while waiting.
      */
 
     /* This code does not run in a critical section, so CPU frequency switch may
@@ -88,7 +85,7 @@ uint32_t IRAM_ATTR esp_random(void)
     for (size_t i = 0; i < sizeof(result); i++) {
         do {
             ccount = esp_cpu_get_cycle_count();
-            result ^= REG_READ(WDEV_RND_REG);
+            result ^= rng_ll_read_data();
         } while (ccount - last_ccount < cpu_to_apb_freq_ratio * APB_CYCLE_WAIT_NUM);
 #if SOC_RTC_TIMER_SUPPORTED
         uint32_t current_rtc_timer_counter = (rtc_timer_hal_get_cycle_count(0) & 0xFF);
@@ -96,7 +93,7 @@ uint32_t IRAM_ATTR esp_random(void)
 #endif
     }
     last_ccount = ccount;
-    return result ^ REG_READ(WDEV_RND_REG);
+    return result ^ rng_ll_read_data();
 #endif // CONFIG_ESP_BRINGUP_BYPASS_RANDOM_SETTING
 }
 

components/hal/esp32/include/hal/rng_ll.h

@@ -0,0 +1,24 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include <stdint.h>
+#include "soc/soc.h"
+#include "soc/wdev_reg.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+static inline uint32_t rng_ll_read_data(void)
+{
+    return REG_READ(WDEV_RND_REG);
+}
+
+#ifdef __cplusplus
+}
+#endif

components/hal/esp32c2/include/hal/rng_ll.h

@@ -0,0 +1,24 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include <stdint.h>
+#include "soc/soc.h"
+#include "soc/syscon_reg.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+static inline uint32_t rng_ll_read_data(void)
+{
+    return REG_READ(RNG_DATA_REG);
+}
+
+#ifdef __cplusplus
+}
+#endif

components/hal/esp32c3/include/hal/rng_ll.h

@@ -0,0 +1,24 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include <stdint.h>
+#include "soc/soc.h"
+#include "soc/syscon_reg.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+static inline uint32_t rng_ll_read_data(void)
+{
+    return REG_READ(RNG_DATA_REG);
+}
+
+#ifdef __cplusplus
+}
+#endif

components/hal/esp32c5/include/hal/rng_ll.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2025-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -8,6 +8,8 @@
 
 #include <stdbool.h>
 #include <stdint.h>
+#include "soc/soc.h"
+#include "soc/lpperi_reg.h"
 #include "soc/lpperi_struct.h"
 #include "hal/lp_clkrst_ll.h"
 
@@ -17,6 +19,16 @@
 extern "C" {
 #endif
 
+/**
+ * @brief Read random data from RNG
+ *
+ * @return 32-bit random data
+ */
+static inline uint32_t rng_ll_read_data(void)
+{
+    return REG_READ(LPPERI_RNG_DATA_SYNC_REG);
+}
+
 /**
  * @brief Enable or disable RNG sampling.
  *

components/hal/esp32c6/include/hal/rng_ll.h

@@ -0,0 +1,24 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include <stdint.h>
+#include "soc/soc.h"
+#include "soc/lpperi_reg.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+static inline uint32_t rng_ll_read_data(void)
+{
+    return REG_READ(LPPERI_RNG_DATA_REG);
+}
+
+#ifdef __cplusplus
+}
+#endif

components/hal/esp32c61/include/hal/rng_ll.h

@@ -0,0 +1,24 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include <stdint.h>
+#include "soc/soc.h"
+#include "soc/lpperi_reg.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+static inline uint32_t rng_ll_read_data(void)
+{
+    return REG_READ(LPPERI_RNG_DATA_SYNC_REG);
+}
+
+#ifdef __cplusplus
+}
+#endif

components/hal/esp32h2/include/hal/rng_ll.h

@@ -0,0 +1,24 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include <stdint.h>
+#include "soc/soc.h"
+#include "soc/lpperi_reg.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+static inline uint32_t rng_ll_read_data(void)
+{
+    return REG_READ(LPPERI_RNG_DATA_REG);
+}
+
+#ifdef __cplusplus
+}
+#endif

components/hal/esp32h21/include/hal/rng_ll.h

@@ -0,0 +1,24 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include <stdint.h>
+#include "soc/soc.h"
+#include "soc/lpperi_reg.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+static inline uint32_t rng_ll_read_data(void)
+{
+    return REG_READ(LPPERI_RNG_DATA_REG);
+}
+
+#ifdef __cplusplus
+}
+#endif

components/hal/esp32h4/include/hal/rng_ll.h

@@ -0,0 +1,25 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include <stdint.h>
+#include "soc/soc.h"
+#include "soc/wdev_reg.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+static inline uint32_t rng_ll_read_data(void)
+{
+    // return REG_READ(WDEV_RND_REG); // TODO: IDF-12265
+    return 0;
+}
+
+#ifdef __cplusplus
+}
+#endif

components/hal/esp32p4/include/hal/rng_ll.h

@@ -0,0 +1,34 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include <stdint.h>
+#include "hal/config.h"
+#include "soc/soc.h"
+#include "soc/lp_system_reg.h"
+#if HAL_CONFIG(CHIP_SUPPORT_MIN_REV) >= 300
+    #include "soc/trng_reg.h"
+#else
+    #include "soc/lp_system_reg.h"
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+static inline uint32_t rng_ll_read_data(void)
+{
+#if HAL_CONFIG(CHIP_SUPPORT_MIN_REV) >= 300
+    return REG_READ(RNG_DATA_REG);
+#else
+    return REG_READ(LP_SYSTEM_REG_RNG_DATA_REG);
+#endif
+}
+
+#ifdef __cplusplus
+}
+#endif

components/hal/esp32s2/include/hal/rng_ll.h

@@ -0,0 +1,24 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include <stdint.h>
+#include "soc/soc.h"
+#include "soc/wdev_reg.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+static inline uint32_t rng_ll_read_data(void)
+{
+    return REG_READ(WDEV_RND_REG);
+}
+
+#ifdef __cplusplus
+}
+#endif

components/hal/esp32s3/include/hal/rng_ll.h

@@ -0,0 +1,24 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include <stdint.h>
+#include "soc/soc.h"
+#include "soc/wdev_reg.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+static inline uint32_t rng_ll_read_data(void)
+{
+    return REG_READ(WDEV_RND_REG);
+}
+
+#ifdef __cplusplus
+}
+#endif

components/hal/esp32s31/include/hal/rng_ll.h

@@ -0,0 +1,24 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include <stdint.h>
+#include "soc/soc.h"
+#include "soc/trng_reg.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+static inline uint32_t rng_ll_read_data(void)
+{
+    return REG_READ(TRNG_CRC_SYNC_DATA_REG);
+}
+
+#ifdef __cplusplus
+}
+#endif