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