esp32: add some implementation comments

diff --git a/components/esp32/hw_random.c b/components/esp32/hw_random.c
index 2c6e2cf5f8b0949ff200f5d36b01abc3fa984a52..11c7af936b6b7ab4e92be239a5c3161b729fbe48 100644 (file)
--- a/components/esp32/hw_random.c
+++ b/components/esp32/hw_random.c
@@ -23,6 +23,14 @@
 
 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.
+     */
+
     static uint32_t last_ccount = 0;
     uint32_t ccount;
     do {

diff --git a/components/esp32/lib_printf.c b/components/esp32/lib_printf.c
index 8a537ffbf952527f006d91bfc67be27bfff43d59..135faa4f9c0183dce9bcbbbd74b9a99cfef2816a 100644 (file)
--- a/components/esp32/lib_printf.c
+++ b/components/esp32/lib_printf.c
@@ -12,6 +12,18 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+/**
+ * @file lib_printf.c
+ *
+ * This file contains library-specific printf functions
+ * used by WiFi libraries in the `lib` directory.
+ * These function are used to catch any output which gets printed
+ * by libraries, and redirect it to ESP_LOG macros.
+ *
+ * Eventually WiFi libraries will use ESP_LOG functions internally
+ * and these definitions will be removed.
+ */
+
 #include <stdio.h>
 #include <stdlib.h>
 #include "esp_log.h"

diff --git a/components/esp32/rtc.h b/components/esp32/rtc.h
index 2ac3139c2194411e272252f3a292c41de2a23aa9..e1cf33522d1ca2a9920f471603a2cf8b6f6ce1cd 100644 (file)
--- a/components/esp32/rtc.h
+++ b/components/esp32/rtc.h
@@ -12,6 +12,18 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+/**
+ * @file rtc.h
+ * @brief Declarations of APIs provided by librtc.a
+ *
+ * This file is not in the include directory of esp32 component, so it is not
+ * part of the public API. As the source code of librtc.a is gradually moved
+ * into the ESP-IDF, some of these APIs will be exposed to applications.
+ *
+ * For now, only esp_deep_sleep function declared in esp_deepsleep.h
+ * is part of public API.
+ */
+
 #pragma once
 #include <stdint.h>
 #include <stddef.h>