From 50f178c1ce0b60b37506ac348c7988d64bc22a19 Mon Sep 17 00:00:00 2001
From: Ivan Grokhotkov <ivan@espressif.com>
Date: Wed, 23 Nov 2016 12:55:49 +0800
Subject: [PATCH] esp32: add some implementation comments

---
 components/esp32/hw_random.c  |  8 ++++++++
 components/esp32/lib_printf.c | 12 ++++++++++++
 components/esp32/rtc.h        | 12 ++++++++++++
 3 files changed, 32 insertions(+)

diff --git a/components/esp32/hw_random.c b/components/esp32/hw_random.c
index 2c6e2cf5f8..11c7af936b 100644
--- 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 8a537ffbf9..135faa4f9c 100644
--- 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 2ac3139c21..e1cf33522d 100644
--- 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>
-- 
2.40.0