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