From 07aaba7c7b2ecb5525b7e677192536635dc0b687 Mon Sep 17 00:00:00 2001 From: gaoxu Date: Wed, 13 May 2026 15:09:55 +0800 Subject: [PATCH] refactor(rng): move rng read data function to rng_ll.h and update docs of RNG source --- .../include/bootloader_random.h | 4 +-- .../src/bootloader_random.c | 12 +++---- components/esp_hw_support/hw_random.c | 13 +++---- components/hal/esp32/include/hal/rng_ll.h | 24 +++++++++++++ components/hal/esp32c2/include/hal/rng_ll.h | 24 +++++++++++++ components/hal/esp32c3/include/hal/rng_ll.h | 24 +++++++++++++ components/hal/esp32c5/include/hal/rng_ll.h | 14 +++++++- components/hal/esp32c6/include/hal/rng_ll.h | 24 +++++++++++++ components/hal/esp32c61/include/hal/rng_ll.h | 24 +++++++++++++ components/hal/esp32h2/include/hal/rng_ll.h | 24 +++++++++++++ components/hal/esp32h21/include/hal/rng_ll.h | 24 +++++++++++++ components/hal/esp32h4/include/hal/rng_ll.h | 25 ++++++++++++++ components/hal/esp32p4/include/hal/rng_ll.h | 34 +++++++++++++++++++ components/hal/esp32s2/include/hal/rng_ll.h | 24 +++++++++++++ components/hal/esp32s3/include/hal/rng_ll.h | 24 +++++++++++++ components/hal/esp32s31/include/hal/rng_ll.h | 24 +++++++++++++ docs/en/api-reference/system/random.rst | 10 ++++-- docs/zh_CN/api-reference/system/random.rst | 8 +++-- 18 files changed, 338 insertions(+), 22 deletions(-) create mode 100644 components/hal/esp32/include/hal/rng_ll.h create mode 100644 components/hal/esp32c2/include/hal/rng_ll.h create mode 100644 components/hal/esp32c3/include/hal/rng_ll.h create mode 100644 components/hal/esp32c6/include/hal/rng_ll.h create mode 100644 components/hal/esp32c61/include/hal/rng_ll.h create mode 100644 components/hal/esp32h2/include/hal/rng_ll.h create mode 100644 components/hal/esp32h21/include/hal/rng_ll.h create mode 100644 components/hal/esp32h4/include/hal/rng_ll.h create mode 100644 components/hal/esp32p4/include/hal/rng_ll.h create mode 100644 components/hal/esp32s2/include/hal/rng_ll.h create mode 100644 components/hal/esp32s3/include/hal/rng_ll.h create mode 100644 components/hal/esp32s31/include/hal/rng_ll.h diff --git a/components/bootloader_support/include/bootloader_random.h b/components/bootloader_support/include/bootloader_random.h index bbe86d75a03..3e810fdadc4 100644 --- a/components/bootloader_support/include/bootloader_random.h +++ b/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 diff --git a/components/bootloader_support/src/bootloader_random.c b/components/bootloader_support/src/bootloader_random.c index 66fdfb4b6ee..48e4630f265 100644 --- a/components/bootloader_support/src/bootloader_random.c +++ b/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); } diff --git a/components/esp_hw_support/hw_random.c b/components/esp_hw_support/hw_random.c index 8da016be41c..f01a2b5c553 100644 --- a/components/esp_hw_support/hw_random.c +++ b/components/esp_hw_support/hw_random.c @@ -11,7 +11,7 @@ #include #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 } diff --git a/components/hal/esp32/include/hal/rng_ll.h b/components/hal/esp32/include/hal/rng_ll.h new file mode 100644 index 00000000000..3b2e5472457 --- /dev/null +++ b/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 +#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 diff --git a/components/hal/esp32c2/include/hal/rng_ll.h b/components/hal/esp32c2/include/hal/rng_ll.h new file mode 100644 index 00000000000..1770738904a --- /dev/null +++ b/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 +#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 diff --git a/components/hal/esp32c3/include/hal/rng_ll.h b/components/hal/esp32c3/include/hal/rng_ll.h new file mode 100644 index 00000000000..1770738904a --- /dev/null +++ b/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 +#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 diff --git a/components/hal/esp32c5/include/hal/rng_ll.h b/components/hal/esp32c5/include/hal/rng_ll.h index fd3cd432fe3..b59ac71186b 100644 --- a/components/hal/esp32c5/include/hal/rng_ll.h +++ b/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 #include +#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. * diff --git a/components/hal/esp32c6/include/hal/rng_ll.h b/components/hal/esp32c6/include/hal/rng_ll.h new file mode 100644 index 00000000000..d9dd1fa7402 --- /dev/null +++ b/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 +#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 diff --git a/components/hal/esp32c61/include/hal/rng_ll.h b/components/hal/esp32c61/include/hal/rng_ll.h new file mode 100644 index 00000000000..67f9e769f65 --- /dev/null +++ b/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 +#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 diff --git a/components/hal/esp32h2/include/hal/rng_ll.h b/components/hal/esp32h2/include/hal/rng_ll.h new file mode 100644 index 00000000000..d9dd1fa7402 --- /dev/null +++ b/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 +#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 diff --git a/components/hal/esp32h21/include/hal/rng_ll.h b/components/hal/esp32h21/include/hal/rng_ll.h new file mode 100644 index 00000000000..d9dd1fa7402 --- /dev/null +++ b/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 +#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 diff --git a/components/hal/esp32h4/include/hal/rng_ll.h b/components/hal/esp32h4/include/hal/rng_ll.h new file mode 100644 index 00000000000..8a3f170dc39 --- /dev/null +++ b/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 +#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 diff --git a/components/hal/esp32p4/include/hal/rng_ll.h b/components/hal/esp32p4/include/hal/rng_ll.h new file mode 100644 index 00000000000..c956a7fadc3 --- /dev/null +++ b/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 +#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 diff --git a/components/hal/esp32s2/include/hal/rng_ll.h b/components/hal/esp32s2/include/hal/rng_ll.h new file mode 100644 index 00000000000..3b2e5472457 --- /dev/null +++ b/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 +#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 diff --git a/components/hal/esp32s3/include/hal/rng_ll.h b/components/hal/esp32s3/include/hal/rng_ll.h new file mode 100644 index 00000000000..3b2e5472457 --- /dev/null +++ b/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 +#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 diff --git a/components/hal/esp32s31/include/hal/rng_ll.h b/components/hal/esp32s31/include/hal/rng_ll.h new file mode 100644 index 00000000000..11775f8c325 --- /dev/null +++ b/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 +#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 diff --git a/docs/en/api-reference/system/random.rst b/docs/en/api-reference/system/random.rst index 04b8309ad14..a569be287bf 100644 --- a/docs/en/api-reference/system/random.rst +++ b/docs/en/api-reference/system/random.rst @@ -12,11 +12,15 @@ Every 32-bit value that the system reads from the RNG_DATA_REG register of the r .. 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. + - Noise comes from the high-speed ADC, the SAR ADC, or both. When the high-speed ADC or SAR ADC is enabled, the generated bit streams are 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 +.. only:: esp32p4 - - 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. + - Thermal noise comes from count values generated by the ring oscillator (BUF_CHAIN) implemented with BUF_CELL, together with the SAR ADC entropy source. Both act as entropy sources to generate random numbers. + +.. only:: esp32s31 + + - Thermal noise comes from multiple entropy sources, including the ring oscillator (BUF_CHAIN) implemented with BUF_CELL, the RFADC, the SAR ADC, and the 40 MHz clock. Their outputs are continuously processed through CRC32 calculations and fed into the random number generator. .. only:: not esp32 diff --git a/docs/zh_CN/api-reference/system/random.rst b/docs/zh_CN/api-reference/system/random.rst index 54aa87ef809..c0c7f2680c4 100644 --- a/docs/zh_CN/api-reference/system/random.rst +++ b/docs/zh_CN/api-reference/system/random.rst @@ -14,9 +14,13 @@ - 热噪声来自高速 ADC、SAR ADC 或两者。当高速 ADC 或 SAR ADC 被启用时，会生成比特流，并作为随机种子通过 XOR 逻辑门输入到随机数生成器中。 -.. only:: not SOC_WIFI_SUPPORTED and not SOC_IEEE802154_SUPPORTED and not SOC_BT_SUPPORTED +.. only:: esp32p4 - - 热噪声来自 SAR ADC。当 SAR ADC 被启用时，会生成比特流，并作为随机种子通过 XOR 逻辑门输入到随机数生成器中。 + - 热噪声来自缓存单元 （BUF_CELL） 实现的环形振荡器 （BUF_CHAIN） 生成的计数值，以及 SAR ADC 熵源， 二者共同作为熵源生成随机数。 + +.. only:: esp32s31 + + - 热噪声来自多个熵源，包括缓存单元（BUF_CELL）实现的环形振荡器（BUF_CHAIN）、RFADC、SAR ADC 以及 40 MHz 时钟。这些熵源的输出会持续经过 CRC32 计算处理后输入到随机数生成器中。 .. only:: not esp32