From: Ivan Grokhotkov <ivan@espressif.com>
Date: Wed, 23 Nov 2016 04:55:49 +0000 (+0800)
Subject: esp32: add some implementation comments
X-Git-Tag: v1.0~26^2~1
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=50f178c1ce0b60b37506ac348c7988d64bc22a19;p=esp-idf

esp32: add some implementation comments
---

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>