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