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