From d63a341c4c8fa4090637a00030bfdf46bffcd022 Mon Sep 17 00:00:00 2001
From: Angus Gratton <gus@projectgus.com>
Date: Fri, 20 Nov 2015 17:49:46 +1100
Subject: [PATCH] RTC registers: Add some notes about other register values

Still patchy, but more towards #8.
---
 core/include/esp/rtc_regs.h | 48 +++++++++++++++++++++++++++++++++++--
 1 file changed, 46 insertions(+), 2 deletions(-)

diff --git a/core/include/esp/rtc_regs.h b/core/include/esp/rtc_regs.h
index ff79e9d..4acb2a3 100644
--- a/core/include/esp/rtc_regs.h
+++ b/core/include/esp/rtc_regs.h
@@ -3,6 +3,16 @@
  * ESP8266 RTC register definitions
  *
  * Not compatible with ESP SDK register access code.
+ *
+ * RTC peripheral remains powered during deep sleep, and RTC clock
+ * is used to wake from deep sleep when RTC.COUNTER == RTC.COUNTER_ALARM.
+ *
+ * "GPIO16" is a special GPIO pin connected to the RTC subsystem,
+ * GPIO16 must be connected to reset to allow wake from deep sleep.
+ *
+ * The contents of scratch registers RTC.SCRATCH[] are preserved
+ * across reset, including wake from sleep (unconfirmed). Contents of
+ * RTCMEM are also preserved.
  */
 
 #ifndef _ESP_RTC_REGS_H
@@ -18,7 +28,7 @@
 // Note: GPIO_CFG[3] is also known as PAD_XPD_DCDC_CONF in eagle_soc.h
 
 struct RTC_REGS {
-    uint32_t volatile _unknown0;        // 0x00
+    uint32_t volatile CTRL0;        // 0x00
     uint32_t volatile COUNTER_ALARM;    // 0x04
     uint32_t volatile RESET_REASON0;    // 0x08       //FIXME: need better name
     uint32_t volatile _unknownc[2];     // 0x0c - 0x10
@@ -42,6 +52,14 @@ struct RTC_REGS {
 
 _Static_assert(sizeof(struct RTC_REGS) == 0xac, "RTC_REGS is the wrong size");
 
+/* Details for CTRL0 register */
+
+/* Writing this bit causes a software reset but
+   the device then fails in ets_main.c (needs other parameters set?) */
+#define RTC_CTRL0_BIT31 BIT(31)
+
+/* Details for RESET_REASONx registers */
+
 /* The following are used in sdk_rtc_get_reset_reason().  Details are still a
  * bit sketchy regarding exactly what they mean/do.. */
 
@@ -51,6 +69,32 @@ _Static_assert(sizeof(struct RTC_REGS) == 0xac, "RTC_REGS is the wrong size");
 #define RTC_RESET_REASON2_CODE_M  0x0000003f
 #define RTC_RESET_REASON2_CODE_S  8
 
-#define RTC_RESET_REASON0_SOMETHING  BIT(21)
+/* Writing this bit causes the ESP to go into some kind of unrecoverable boot loop */
+#define RTC_RESET_REASON0_BIT20 BIT(20)
+
+/* Both bits 20 & 21 can be set & cleared from software,
+   BIT21 appears to be checked inside sdk_rtc_get_reset_reason() */
+#define RTC_RESET_REASON0_BIT21 BIT(21)
+#define RTC_RESET_REASON0_BIT22 BIT(22)
+
+/* Details for GPIO_CONF register */
+
+#define RTC_GPIO_CONF_OUT_ENABLE BIT(0)
+
+/* Details for GPIO_CFG[3] register controlling GPIO16 (possibly others?) */
+
+#define RTC_GPIO_CFG3_PIN_PULLUP          BIT(2)
+#define RTC_GPIO_CFG3_PIN_PULLDOWN        BIT(3)
+#define RTC_GPIO_CFG3_PIN_PULLUP_SLEEP    BIT(4)
+#define RTC_GPIO_CFG3_PIN_PULLDOWN_SLEEP  BIT(5)
+
+/* The PIN_FUNC values here are probably similar to the
+   values used to set the iomux registers...? */
+#define RTC_GPIO_CFG3_PIN_FUNC_M 0x00000043
+#define RTC_GPIO_CFG3_PIN_FUNC_S 0
+
+/* This should be the function value needed to have GPIO16 be the alarm
+   output from the RTC. FIXME: Needs to be validated. */
+#define RTC_GPIO_CFG3_PIN_FUNC_RTC_GPIO0  BIT(0)
 
 #endif /* _ESP_RTC_REGS_H */