1 /*
2  * SPDX-FileCopyrightText: 2010-2022 Espressif Systems (Shanghai) CO LTD
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 
7 #ifndef _ROM_RTC_H_
8 #define _ROM_RTC_H_
9 
10 #include "ets_sys.h"
11 
12 #include <stdbool.h>
13 #include <stdint.h>
14 #include "esp_assert.h"
15 
16 #include "soc/soc.h"
17 #include "soc/rtc_cntl_reg.h"
18 #include "soc/reset_reasons.h"
19 
20 #ifdef __cplusplus
21 extern "C" {
22 #endif
23 
24 /** \defgroup rtc_apis, rtc registers and memory related apis
25   * @brief rtc apis
26   */
27 
28 /** @addtogroup rtc_apis
29   * @{
30   */
31 
32 /**************************************************************************************
33   *                                       Note:                                       *
34   *       Some Rtc memory and registers are used, in ROM or in internal library.      *
35   *          Please do not use reserved or used rtc memory or registers.              *
36   *                                                                                   *
37   *************************************************************************************
38   *                          RTC  Memory & Store Register usage
39   *************************************************************************************
40   *     rtc memory addr         type    size            usage
41   *     0x3f421000(0x50000000)  Slow    SIZE_CP         Co-Processor code/Reset Entry
42   *     0x3f421000+SIZE_CP      Slow    8192-SIZE_CP
43   *
44   *     0x3ff80000(0x40070000)  Fast    8192            deep sleep entry code
45   *
46   *************************************************************************************
47   *     RTC store registers     usage
48   *     RTC_CNTL_STORE0_REG     Reserved
49   *     RTC_CNTL_STORE1_REG     RTC_SLOW_CLK calibration value
50   *     RTC_CNTL_STORE2_REG     Boot time, low word
51   *     RTC_CNTL_STORE3_REG     Boot time, high word
52   *     RTC_CNTL_STORE4_REG     External XTAL frequency
53   *     RTC_CNTL_STORE5_REG     APB bus frequency
54   *     RTC_CNTL_STORE6_REG     FAST_RTC_MEMORY_ENTRY
55   *     RTC_CNTL_STORE7_REG     FAST_RTC_MEMORY_CRC
56   *************************************************************************************
57   */
58 
59 #define RTC_SLOW_CLK_CAL_REG    RTC_CNTL_STORE1_REG
60 #define RTC_BOOT_TIME_LOW_REG   RTC_CNTL_STORE2_REG
61 #define RTC_BOOT_TIME_HIGH_REG  RTC_CNTL_STORE3_REG
62 #define RTC_XTAL_FREQ_REG       RTC_CNTL_STORE4_REG
63 #define RTC_APB_FREQ_REG        RTC_CNTL_STORE5_REG
64 #define RTC_ENTRY_ADDR_REG      RTC_CNTL_STORE6_REG
65 #define RTC_RESET_CAUSE_REG     RTC_CNTL_STORE6_REG
66 #define RTC_MEMORY_CRC_REG      RTC_CNTL_STORE7_REG
67 
68 #define RTC_DISABLE_ROM_LOG ((1 << 0) | (1 << 16)) //!< Disable logging from the ROM code.
69 
70 typedef enum {
71     AWAKE = 0,             //<CPU ON
72     LIGHT_SLEEP = BIT0,    //CPU waiti, PLL ON.  We don't need explicitly set this mode.
73     DEEP_SLEEP  = BIT1     //CPU OFF, PLL OFF, only specific timer could wake up
74 } SLEEP_MODE;
75 
76 typedef enum {
77     NO_MEAN                =  0,
78     POWERON_RESET          =  1,    /**<1, Vbat power on reset*/
79     RTC_SW_SYS_RESET       =  3,    /**<3, Software reset digital core*/
80     DEEPSLEEP_RESET        =  5,    /**<5, Deep Sleep reset digital core*/
81     TG0WDT_SYS_RESET       =  7,    /**<7, Timer Group0 Watch dog reset digital core*/
82     TG1WDT_SYS_RESET       =  8,    /**<8, Timer Group1 Watch dog reset digital core*/
83     RTCWDT_SYS_RESET       =  9,    /**<9, RTC Watch dog Reset digital core*/
84     INTRUSION_RESET        = 10,    /**<10, Instrusion tested to reset CPU*/
85     TG0WDT_CPU_RESET       = 11,    /**<11, Time Group0 reset CPU*/
86     RTC_SW_CPU_RESET       = 12,    /**<12, Software reset CPU*/
87     RTCWDT_CPU_RESET       = 13,    /**<13, RTC Watch dog Reset CPU*/
88     RTCWDT_BROWN_OUT_RESET = 15,    /**<15, Reset when the vdd voltage is not stable*/
89     RTCWDT_RTC_RESET       = 16,    /**<16, RTC Watch dog reset digital core and rtc module*/
90     TG1WDT_CPU_RESET       = 17,    /**<17, Time Group1 reset CPU*/
91     SUPER_WDT_RESET        = 18,    /**<18, super watchdog reset digital core and rtc module*/
92     GLITCH_RTC_RESET       = 19,    /**<19, glitch reset digital core and rtc module*/
93     EFUSE_RESET            = 20,    /**<20, efuse reset digital core*/
94 } RESET_REASON;
95 
96 // Check if the reset reason defined in ROM is compatible with soc/reset_reasons.h
97 ESP_STATIC_ASSERT((soc_reset_reason_t)POWERON_RESET == RESET_REASON_CHIP_POWER_ON, "POWERON_RESET != RESET_REASON_CHIP_POWER_ON");
98 ESP_STATIC_ASSERT((soc_reset_reason_t)RTC_SW_SYS_RESET == RESET_REASON_CORE_SW, "RTC_SW_SYS_RESET != RESET_REASON_CORE_SW");
99 ESP_STATIC_ASSERT((soc_reset_reason_t)DEEPSLEEP_RESET == RESET_REASON_CORE_DEEP_SLEEP, "DEEPSLEEP_RESET != RESET_REASON_CORE_DEEP_SLEEP");
100 ESP_STATIC_ASSERT((soc_reset_reason_t)TG0WDT_SYS_RESET == RESET_REASON_CORE_MWDT0, "TG0WDT_SYS_RESET != RESET_REASON_CORE_MWDT0");
101 ESP_STATIC_ASSERT((soc_reset_reason_t)TG1WDT_SYS_RESET == RESET_REASON_CORE_MWDT1, "TG1WDT_SYS_RESET != RESET_REASON_CORE_MWDT1");
102 ESP_STATIC_ASSERT((soc_reset_reason_t)RTCWDT_SYS_RESET == RESET_REASON_CORE_RTC_WDT, "RTCWDT_SYS_RESET != RESET_REASON_CORE_RTC_WDT");
103 ESP_STATIC_ASSERT((soc_reset_reason_t)TG0WDT_CPU_RESET == RESET_REASON_CPU0_MWDT0, "TG0WDT_CPU_RESET != RESET_REASON_CPU0_MWDT0");
104 ESP_STATIC_ASSERT((soc_reset_reason_t)RTC_SW_CPU_RESET == RESET_REASON_CPU0_SW, "RTC_SW_CPU_RESET != RESET_REASON_CPU0_SW");
105 ESP_STATIC_ASSERT((soc_reset_reason_t)RTCWDT_CPU_RESET == RESET_REASON_CPU0_RTC_WDT, "RTCWDT_CPU_RESET != RESET_REASON_CPU0_RTC_WDT");
106 ESP_STATIC_ASSERT((soc_reset_reason_t)RTCWDT_BROWN_OUT_RESET == RESET_REASON_SYS_BROWN_OUT, "RTCWDT_BROWN_OUT_RESET != RESET_REASON_SYS_BROWN_OUT");
107 ESP_STATIC_ASSERT((soc_reset_reason_t)RTCWDT_RTC_RESET == RESET_REASON_SYS_RTC_WDT, "RTCWDT_RTC_RESET != RESET_REASON_SYS_RTC_WDT");
108 ESP_STATIC_ASSERT((soc_reset_reason_t)TG1WDT_CPU_RESET == RESET_REASON_CPU0_MWDT1, "TG1WDT_CPU_RESET != RESET_REASON_CPU0_MWDT1");
109 ESP_STATIC_ASSERT((soc_reset_reason_t)SUPER_WDT_RESET == RESET_REASON_SYS_SUPER_WDT, "SUPER_WDT_RESET != RESET_REASON_SYS_SUPER_WDT");
110 ESP_STATIC_ASSERT((soc_reset_reason_t)GLITCH_RTC_RESET == RESET_REASON_SYS_CLK_GLITCH, "GLITCH_RTC_RESET != RESET_REASON_SYS_CLK_GLITCH");
111 ESP_STATIC_ASSERT((soc_reset_reason_t)EFUSE_RESET == RESET_REASON_CORE_EFUSE_CRC, "EFUSE_RESET != RESET_REASON_CORE_EFUSE_CRC");
112 
113 typedef enum {
114     NO_SLEEP        = 0,
115     EXT_EVENT0_TRIG = BIT0,
116     EXT_EVENT1_TRIG = BIT1,
117     GPIO_TRIG       = BIT2,
118     TIMER_EXPIRE    = BIT3,
119     SDIO_TRIG       = BIT4,
120     MAC_TRIG        = BIT5,
121     UART0_TRIG      = BIT6,
122     UART1_TRIG      = BIT7,
123     TOUCH_TRIG      = BIT8,
124     SAR_TRIG        = BIT9,
125     BT_TRIG         = BIT10,
126     RISCV_TRIG      = BIT11,
127     XTAL_DEAD_TRIG  = BIT12,
128     RISCV_TRAP_TRIG = BIT13,
129     USB_TRIG        = BIT14
130 } WAKEUP_REASON;
131 
132 typedef enum {
133     DISEN_WAKEUP       = NO_SLEEP,
134     EXT_EVENT0_TRIG_EN = EXT_EVENT0_TRIG,
135     EXT_EVENT1_TRIG_EN = EXT_EVENT1_TRIG,
136     GPIO_TRIG_EN       = GPIO_TRIG,
137     TIMER_EXPIRE_EN    = TIMER_EXPIRE,
138     SDIO_TRIG_EN       = SDIO_TRIG,
139     MAC_TRIG_EN        = MAC_TRIG,
140     UART0_TRIG_EN      = UART0_TRIG,
141     UART1_TRIG_EN      = UART1_TRIG,
142     TOUCH_TRIG_EN      = TOUCH_TRIG,
143     SAR_TRIG_EN        = SAR_TRIG,
144     BT_TRIG_EN         = BT_TRIG,
145     RISCV_TRIG_EN      = RISCV_TRIG,
146     XTAL_DEAD_TRIG_EN  = XTAL_DEAD_TRIG,
147     RISCV_TRAP_TRIG_EN = RISCV_TRAP_TRIG,
148     USB_TRIG_EN        = USB_TRIG
149 } WAKEUP_ENABLE;
150 
151 /**
152   * @brief  Get the reset reason for CPU.
153   *
154   * @param  int cpu_no : CPU no.
155   *
156   * @return RESET_REASON
157   */
158 RESET_REASON rtc_get_reset_reason(int cpu_no);
159 
160 /**
161   * @brief  Get the wakeup cause for CPU.
162   *
163   * @param  int cpu_no : CPU no.
164   *
165   * @return WAKEUP_REASON
166   */
167 WAKEUP_REASON rtc_get_wakeup_cause(void);
168 
169 
170 /**
171   * @brief Set CRC of Fast RTC memory 0-0x7ff into RTC STORE7.
172   *
173   * @param  None
174   *
175   * @return None
176   */
177 void set_rtc_memory_crc(void);
178 
179 /**
180   * @brief Suppress ROM log by setting specific RTC control register.
181   * @note This is not a permanent disable of ROM logging since the RTC register can not retain after chip reset.
182   *
183   * @param  None
184   *
185   * @return None
186   */
rtc_suppress_rom_log(void)187 static inline void rtc_suppress_rom_log(void)
188 {
189     /* To disable logging in the ROM, only the least significant bit of the register is used,
190      * but since this register is also used to store the frequency of the main crystal (RTC_XTAL_FREQ_REG),
191      * you need to write to this register in the same format.
192      * Namely, the upper 16 bits and lower should be the same.
193      */
194     REG_SET_BIT(RTC_CNTL_STORE4_REG, RTC_DISABLE_ROM_LOG);
195 }
196 
197 /**
198   * @brief Fetch entry from RTC memory and RTC STORE reg
199   *
200   * @param uint32_t * entry_addr : the address to save entry
201   *
202   * @param RESET_REASON reset_reason : reset reason this time
203   *
204   * @return None
205   */
206 void rtc_boot_control(uint32_t * entry_addr, RESET_REASON reset_reason);
207 
208 /**
209   * @brief Software Reset digital core.
210   *
211   * It is not recommended to use this function in esp-idf, use
212   * esp_restart() instead.
213   *
214   * @param  None
215   *
216   * @return None
217   */
218 void software_reset(void);
219 
220 /**
221   * @brief Software Reset digital core.
222   *
223   * It is not recommended to use this function in esp-idf, use
224   * esp_restart() instead.
225   *
226   * @param  int cpu_no : The CPU to reset, 0 for PRO CPU, 1 for APP CPU.
227   *
228   * @return None
229   */
230 void software_reset_cpu(int cpu_no);
231 
232 /**
233   * @}
234   */
235 
236 #ifdef __cplusplus
237 }
238 #endif
239 
240 #endif /* _ROM_RTC_H_ */
241