1 /* 2 * SPDX-FileCopyrightText: 2015-2021 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 <stddef.h> 11 #include <stdint.h> 12 #include "stubs.h" 13 #include "soc/soc.h" 14 #include "soc/clk_tree_defs.h" 15 16 #ifdef __cplusplus 17 extern "C" { 18 #endif 19 20 /** 21 * @file rtc.h 22 * @brief Low-level RTC power, clock, and sleep functions. 23 * 24 * Functions in this file facilitate configuration of ESP32's RTC_CNTL peripheral. 25 * RTC_CNTL peripheral handles many functions: 26 * - enables/disables clocks and power to various parts of the chip; this is 27 * done using direct register access (forcing power up or power down) or by 28 * allowing state machines to control power and clocks automatically 29 * - handles sleep and wakeup functions 30 * - maintains a 48-bit counter which can be used for timekeeping 31 * 32 * These functions are not thread safe, and should not be viewed as high level 33 * APIs. For example, while this file provides a function which can switch 34 * CPU frequency, this function is on its own is not sufficient to implement 35 * frequency switching in ESP-IDF context: some coordination with RTOS, 36 * peripheral drivers, and WiFi/BT stacks is also required. 37 * 38 * These functions will normally not be used in applications directly. 39 * ESP-IDF provides, or will provide, drivers and other facilities to use 40 * RTC subsystem functionality. 41 * 42 * The functions are loosely split into the following groups: 43 * - rtc_clk: clock switching, calibration 44 * - rtc_time: reading RTC counter, conversion between counter values and time 45 * - rtc_sleep: entry into sleep modes 46 * - rtc_init: initialization 47 */ 48 49 #define RTC_SLOW_CLK_X32K_CAL_TIMEOUT_THRES(cycles) (cycles << 12) 50 #define RTC_SLOW_CLK_8MD256_CAL_TIMEOUT_THRES(cycles) (cycles << 12) 51 #define RTC_SLOW_CLK_150K_CAL_TIMEOUT_THRES(cycles) (cycles << 10) 52 53 #define OTHER_BLOCKS_POWERUP 1 54 #define OTHER_BLOCKS_WAIT 1 55 56 /* Approximate mapping of voltages to RTC_CNTL_DBIAS_WAK, RTC_CNTL_DBIAS_SLP, 57 * RTC_CNTL_DIG_DBIAS_WAK, RTC_CNTL_DIG_DBIAS_SLP values. 58 */ 59 #define RTC_CNTL_DBIAS_SLP 5 ///< sleep dig_dbias & rtc_dbias 60 #define RTC_CNTL_DBIAS_0V90 13 ///< digital voltage 61 #define RTC_CNTL_DBIAS_0V95 16 62 #define RTC_CNTL_DBIAS_1V00 18 63 #define RTC_CNTL_DBIAS_1V05 20 64 #define RTC_CNTL_DBIAS_1V10 23 65 #define RTC_CNTL_DBIAS_1V15 25 66 #define RTC_CNTL_DBIAS_1V20 28 67 #define RTC_CNTL_DBIAS_1V25 30 68 #define RTC_CNTL_DBIAS_1V30 31 ///< voltage is about 1.34v in fact 69 70 /* Delays for various clock sources to be enabled/switched. 71 * All values are in microseconds. 72 */ 73 #define SOC_DELAY_RTC_FAST_CLK_SWITCH 3 74 #define SOC_DELAY_RTC_SLOW_CLK_SWITCH 300 75 #define SOC_DELAY_RC_FAST_ENABLE 50 76 #define SOC_DELAY_RC_FAST_DIGI_SWITCH 5 77 78 /* Core voltage needs to be increased in two cases: 79 * 1. running at 240 MHz 80 * 2. running with 80MHz or 120M Flash frequency 81 */ 82 #if CONFIG_ESPTOOLPY_FLASHFREQ_80M || CONFIG_ESPTOOLPY_FLASHFREQ_120M 83 #define DIG_DBIAS_80M_160M RTC_CNTL_DBIAS_1V25 84 #else 85 #define DIG_DBIAS_80M_160M RTC_CNTL_DBIAS_1V10 86 #endif 87 #define DIG_DBIAS_240M RTC_CNTL_DBIAS_1V25 88 #define DIG_DBIAS_XTAL RTC_CNTL_DBIAS_1V10 89 #define DIG_DBIAS_2M RTC_CNTL_DBIAS_1V00 90 91 #define RTC_CNTL_PLL_BUF_WAIT_DEFAULT 20 92 #define RTC_CNTL_XTL_BUF_WAIT_DEFAULT 100 93 #define RTC_CNTL_CK8M_WAIT_DEFAULT 20 94 #define RTC_CK8M_ENABLE_WAIT_DEFAULT 5 95 96 /* Various delays to be programmed into power control state machines */ 97 #define RTC_CNTL_XTL_BUF_WAIT_SLP_US (250) 98 #define RTC_CNTL_PLL_BUF_WAIT_SLP_CYCLES (1) 99 #define RTC_CNTL_CK8M_WAIT_SLP_CYCLES (4) 100 #define RTC_CNTL_WAKEUP_DELAY_CYCLES (4) 101 #define RTC_CNTL_MIN_SLP_VAL_MIN (2) 102 103 #define RTC_CNTL_CK8M_DFREQ_DEFAULT 100 104 #define RTC_CNTL_SCK_DCAP_DEFAULT 255 105 106 #define RTC_CNTL_ULPCP_TOUCH_START_WAIT_IN_SLEEP (0xFF) 107 #define RTC_CNTL_ULPCP_TOUCH_START_WAIT_DEFAULT (0x10) 108 109 /* 110 set sleep_init default param 111 */ 112 #define RTC_CNTL_DBG_ATTEN_LIGHTSLEEP_DEFAULT 5 113 #define RTC_CNTL_DBG_ATTEN_LIGHTSLEEP_NODROP 0 114 #define RTC_CNTL_DBG_ATTEN_DEEPSLEEP_DEFAULT 14 115 #define RTC_CNTL_DBG_ATTEN_DEEPSLEEP_ULTRA_LOW 15 116 #define RTC_CNTL_DBG_ATTEN_DEEPSLEEP_NODROP 0 117 #define RTC_CNTL_BIASSLP_SLEEP_DEFAULT 1 118 #define RTC_CNTL_BIASSLP_SLEEP_ON 0 119 #define RTC_CNTL_PD_CUR_SLEEP_DEFAULT 1 120 #define RTC_CNTL_PD_CUR_SLEEP_ON 0 121 #define RTC_CNTL_DG_VDD_DRV_B_SLP_DEFAULT 0xf 122 123 #define RTC_CNTL_DBG_ATTEN_MONITOR_DEFAULT 0 124 #define RTC_CNTL_BIASSLP_MONITOR_DEFAULT 1 125 #define RTC_CNTL_BIASSLP_MONITOR_ON 0 126 #define RTC_CNTL_PD_CUR_MONITOR_DEFAULT 1 127 #define RTC_CNTL_PD_CUR_MONITOR_ON 0 128 129 /* 130 The follow value is used to get a reasonable rtc voltage dbias value according to digital dbias & some other value 131 storing in efuse 132 */ 133 #define K_RTC_MID_MUL10000 198 134 #define K_DIG_MID_MUL10000 211 135 #define V_RTC_MID_MUL10000 10181 136 #define V_DIG_MID_MUL10000 10841 137 138 /* 139 set LDO slave during CPU switch 140 */ 141 #define DEFAULT_LDO_SLAVE 0x7 142 143 144 145 /** 146 * @brief Possible main XTAL frequency values. 147 * 148 * Enum values should be equal to frequency in MHz. 149 */ 150 typedef enum { 151 RTC_XTAL_FREQ_32M = 32, 152 RTC_XTAL_FREQ_40M = 40, //!< 40 MHz XTAL 153 } rtc_xtal_freq_t; 154 155 /** 156 * @brief CPU clock configuration structure 157 */ 158 typedef struct rtc_cpu_freq_config_s { 159 soc_cpu_clk_src_t source; //!< The clock from which CPU clock is derived 160 uint32_t source_freq_mhz; //!< Source clock frequency 161 uint32_t div; //!< Divider, freq_mhz = source_freq_mhz / div 162 uint32_t freq_mhz; //!< CPU clock frequency 163 } rtc_cpu_freq_config_t; 164 165 #define RTC_CLK_CAL_FRACT 19 //!< Number of fractional bits in values returned by rtc_clk_cal 166 167 #define RTC_VDDSDIO_TIEH_1_8V 0 //!< TIEH field value for 1.8V VDDSDIO 168 #define RTC_VDDSDIO_TIEH_3_3V 1 //!< TIEH field value for 3.3V VDDSDIO 169 170 /** 171 * @brief Clock source to be calibrated using rtc_clk_cal function 172 */ 173 typedef enum { 174 RTC_CAL_RTC_MUX = 0, //!< Currently selected RTC SLOW_CLK 175 RTC_CAL_8MD256 = 1, //!< Internal 8 MHz RC oscillator, divided by 256 176 RTC_CAL_32K_XTAL = 2, //!< External 32 kHz XTAL 177 RTC_CAL_INTERNAL_OSC = 3 //!< Internal 150 kHz oscillator 178 } rtc_cal_sel_t; 179 180 /** 181 * Initialization parameters for rtc_clk_init 182 */ 183 typedef struct { 184 rtc_xtal_freq_t xtal_freq : 8; //!< Main XTAL frequency 185 uint32_t cpu_freq_mhz : 10; //!< CPU frequency to set, in MHz 186 soc_rtc_fast_clk_src_t fast_clk_src : 2; //!< RTC_FAST_CLK clock source to choose 187 soc_rtc_slow_clk_src_t slow_clk_src : 2; //!< RTC_SLOW_CLK clock source to choose 188 uint32_t clk_rtc_clk_div : 8; 189 uint32_t clk_8m_clk_div : 3; //!< RTC 8M clock divider (division is by clk_8m_div+1, i.e. 0 means 8MHz frequency) 190 uint32_t slow_clk_dcap : 8; //!< RTC 150k clock adjustment parameter (higher value leads to lower frequency) 191 uint32_t clk_8m_dfreq : 8; //!< RTC 8m clock adjustment parameter (higher value leads to higher frequency) 192 } rtc_clk_config_t; 193 194 /** 195 * Default initializer for rtc_clk_config_t 196 */ 197 #define RTC_CLK_CONFIG_DEFAULT() { \ 198 .xtal_freq = CONFIG_XTAL_FREQ, \ 199 .cpu_freq_mhz = 80, \ 200 .fast_clk_src = SOC_RTC_FAST_CLK_SRC_RC_FAST, \ 201 .slow_clk_src = SOC_RTC_SLOW_CLK_SRC_RC_SLOW, \ 202 .clk_rtc_clk_div = 0, \ 203 .clk_8m_clk_div = 0, \ 204 .slow_clk_dcap = RTC_CNTL_SCK_DCAP_DEFAULT, \ 205 .clk_8m_dfreq = RTC_CNTL_CK8M_DFREQ_DEFAULT, \ 206 } 207 208 typedef struct { 209 uint16_t wifi_powerup_cycles : 7; 210 uint16_t wifi_wait_cycles : 9; 211 uint16_t bt_powerup_cycles : 7; 212 uint16_t bt_wait_cycles : 9; 213 uint16_t rtc_powerup_cycles : 7; 214 uint16_t rtc_wait_cycles : 9; 215 uint16_t cpu_top_powerup_cycles : 7; 216 uint16_t cpu_top_wait_cycles : 9; 217 uint16_t dg_wrap_powerup_cycles : 7; 218 uint16_t dg_wrap_wait_cycles : 9; 219 uint16_t dg_peri_powerup_cycles : 7; 220 uint16_t dg_peri_wait_cycles : 9; 221 uint16_t rtc_mem_powerup_cycles : 7; 222 uint16_t rtc_mem_wait_cycles : 9; 223 } rtc_init_config_t; 224 225 #define RTC_INIT_CONFIG_DEFAULT() { \ 226 .wifi_powerup_cycles = OTHER_BLOCKS_POWERUP, \ 227 .wifi_wait_cycles = OTHER_BLOCKS_WAIT, \ 228 .bt_powerup_cycles = OTHER_BLOCKS_POWERUP, \ 229 .bt_wait_cycles = OTHER_BLOCKS_WAIT, \ 230 .rtc_powerup_cycles = OTHER_BLOCKS_POWERUP, \ 231 .rtc_wait_cycles = OTHER_BLOCKS_WAIT, \ 232 .cpu_top_powerup_cycles = OTHER_BLOCKS_POWERUP, \ 233 .cpu_top_wait_cycles = OTHER_BLOCKS_WAIT, \ 234 .dg_wrap_powerup_cycles = OTHER_BLOCKS_POWERUP, \ 235 .dg_wrap_wait_cycles = OTHER_BLOCKS_WAIT, \ 236 .dg_peri_powerup_cycles = OTHER_BLOCKS_POWERUP, \ 237 .dg_peri_wait_cycles = OTHER_BLOCKS_WAIT, \ 238 .rtc_mem_powerup_cycles = OTHER_BLOCKS_POWERUP, \ 239 .rtc_mem_wait_cycles = OTHER_BLOCKS_WAIT, \ 240 } 241 242 void rtc_clk_divider_set(uint32_t div); 243 244 void rtc_clk_8m_divider_set(uint32_t div); 245 246 /** 247 * Initialize clocks and set CPU frequency 248 * 249 * @param cfg clock configuration as rtc_clk_config_t 250 */ 251 void rtc_clk_init(rtc_clk_config_t cfg); 252 253 /** 254 * @brief Get main XTAL frequency 255 * 256 * This is the value stored in RTC register RTC_XTAL_FREQ_REG by the bootloader. As passed to 257 * rtc_clk_init function 258 * 259 * @return XTAL frequency, one of rtc_xtal_freq_t 260 */ 261 rtc_xtal_freq_t rtc_clk_xtal_freq_get(void); 262 263 /** 264 * @brief Update XTAL frequency 265 * 266 * Updates the XTAL value stored in RTC_XTAL_FREQ_REG. Usually this value is ignored 267 * after startup. 268 * 269 * @param xtal_freq New frequency value 270 */ 271 void rtc_clk_xtal_freq_update(rtc_xtal_freq_t xtal_freq); 272 273 /** 274 * @brief Enable or disable 32 kHz XTAL oscillator 275 * @param en true to enable, false to disable 276 */ 277 void rtc_clk_32k_enable(bool en); 278 279 /** 280 * @brief Configure 32 kHz XTAL oscillator to accept external clock signal 281 */ 282 void rtc_clk_32k_enable_external(void); 283 284 /** 285 * @brief Get the state of 32k XTAL oscillator 286 * @return true if 32k XTAL oscillator has been enabled 287 */ 288 bool rtc_clk_32k_enabled(void); 289 290 /** 291 * @brief Enable 32k oscillator, configuring it for fast startup time. 292 * Note: to achieve higher frequency stability, rtc_clk_32k_enable function 293 * must be called one the 32k XTAL oscillator has started up. This function 294 * will initially disable the 32k XTAL oscillator, so it should not be called 295 * when the system is using 32k XTAL as RTC_SLOW_CLK. 296 * 297 * @param cycle Number of 32kHz cycles to bootstrap external crystal. 298 * If 0, no square wave will be used to bootstrap crystal oscillation. 299 */ 300 void rtc_clk_32k_bootstrap(uint32_t cycle); 301 302 /** 303 * @brief Enable or disable 8 MHz internal oscillator 304 * 305 * Output from 8 MHz internal oscillator is passed into a configurable 306 * divider, which by default divides the input clock frequency by 256. 307 * Output of the divider may be used as RTC_SLOW_CLK source. 308 * Output of the divider is referred to in register descriptions and code as 309 * 8md256 or simply d256. Divider values other than 256 may be configured, but 310 * this facility is not currently needed, so is not exposed in the code. 311 * 312 * When 8MHz/256 divided output is not needed, the divider should be disabled 313 * to reduce power consumption. 314 * 315 * @param clk_8m_en true to enable 8MHz generator 316 * @param d256_en true to enable /256 divider 317 */ 318 void rtc_clk_8m_enable(bool clk_8m_en, bool d256_en); 319 320 /** 321 * @brief Get the state of 8 MHz internal oscillator 322 * @return true if the oscillator is enabled 323 */ 324 bool rtc_clk_8m_enabled(void); 325 326 /** 327 * @brief Get the state of /256 divider which is applied to 8MHz clock 328 * @return true if the divided output is enabled 329 */ 330 bool rtc_clk_8md256_enabled(void); 331 332 /** 333 * @brief Select source for RTC_SLOW_CLK 334 * @param clk_src clock source (one of soc_rtc_slow_clk_src_t values) 335 */ 336 void rtc_clk_slow_src_set(soc_rtc_slow_clk_src_t clk_src); 337 338 /** 339 * @brief Get the RTC_SLOW_CLK source 340 * @return currently selected clock source (one of soc_rtc_slow_clk_src_t values) 341 */ 342 soc_rtc_slow_clk_src_t rtc_clk_slow_src_get(void); 343 344 /** 345 * @brief Get the approximate frequency of RTC_SLOW_CLK, in Hz 346 * 347 * - if SOC_RTC_SLOW_CLK_SRC_RC_SLOW is selected, returns ~150000 348 * - if SOC_RTC_SLOW_CLK_SRC_XTAL32K is selected, returns 32768 349 * - if SOC_RTC_SLOW_CLK_SRC_RC_FAST_D256 is selected, returns ~68000 350 * 351 * rtc_clk_cal function can be used to get more precise value by comparing 352 * RTC_SLOW_CLK frequency to the frequency of main XTAL. 353 * 354 * @return RTC_SLOW_CLK frequency, in Hz 355 */ 356 uint32_t rtc_clk_slow_freq_get_hz(void); 357 358 /** 359 * @brief Select source for RTC_FAST_CLK 360 * @param clk_src clock source (one of soc_rtc_fast_clk_src_t values) 361 */ 362 void rtc_clk_fast_src_set(soc_rtc_fast_clk_src_t clk_src); 363 364 /** 365 * @brief Get the RTC_FAST_CLK source 366 * @return currently selected clock source (one of soc_rtc_fast_clk_src_t values) 367 */ 368 soc_rtc_fast_clk_src_t rtc_clk_fast_src_get(void); 369 370 /** 371 * @brief Get CPU frequency config for a given frequency 372 * @param freq_mhz Frequency in MHz 373 * @param[out] out_config Output, CPU frequency configuration structure 374 * @return true if frequency can be obtained, false otherwise 375 */ 376 bool rtc_clk_cpu_freq_mhz_to_config(uint32_t freq_mhz, rtc_cpu_freq_config_t *out_config); 377 378 /** 379 * @brief Switch CPU frequency 380 * 381 * This function sets CPU frequency according to the given configuration 382 * structure. It enables PLLs, if necessary. 383 * 384 * @note This function in not intended to be called by applications in FreeRTOS 385 * environment. This is because it does not adjust various timers based on the 386 * new CPU frequency. 387 * 388 * @param config CPU frequency configuration structure 389 */ 390 void rtc_clk_cpu_freq_set_config(const rtc_cpu_freq_config_t *config); 391 392 /** 393 * @brief Switch CPU frequency (optimized for speed) 394 * 395 * This function is a faster equivalent of rtc_clk_cpu_freq_set_config. 396 * It works faster because it does not disable PLLs when switching from PLL to 397 * XTAL and does not enabled them when switching back. If PLL is not already 398 * enabled when this function is called to switch from XTAL to PLL frequency, 399 * or the PLL which is enabled is the wrong one, this function will fall back 400 * to calling rtc_clk_cpu_freq_set_config. 401 * 402 * Unlike rtc_clk_cpu_freq_set_config, this function relies on static data, 403 * so it is less safe to use it e.g. from a panic handler (when memory might 404 * be corrupted). 405 * 406 * @note This function in not intended to be called by applications in FreeRTOS 407 * environment. This is because it does not adjust various timers based on the 408 * new CPU frequency. 409 * 410 * @param config CPU frequency configuration structure 411 */ 412 void rtc_clk_cpu_freq_set_config_fast(const rtc_cpu_freq_config_t *config); 413 414 /** 415 * @brief Get the currently used CPU frequency configuration 416 * @param[out] out_config Output, CPU frequency configuration structure 417 */ 418 void rtc_clk_cpu_freq_get_config(rtc_cpu_freq_config_t *out_config); 419 420 /** 421 * @brief Switch CPU clock source to XTAL 422 * 423 * Short form for filling in rtc_cpu_freq_config_t structure and calling 424 * rtc_clk_cpu_freq_set_config when a switch to XTAL is needed. 425 * Assumes that XTAL frequency has been determined — don't call in startup code. 426 * 427 * @note This function always disables BBPLL after switching the CPU clock source to XTAL for power saving purpose. 428 * If this is unwanted, please use rtc_clk_cpu_freq_set_config. It helps to check whether USB Serial JTAG is in use, 429 * if so, then BBPLL will not be turned off. 430 */ 431 void rtc_clk_cpu_freq_set_xtal(void); 432 433 /** 434 * @brief Store new APB frequency value in RAM 435 * 436 * This function doesn't change any hardware clocks. 437 * 438 * Functions which perform frequency switching and change APB frequency call 439 * this function to update the value of APB frequency stored in RAM. 440 * (This should not normally be called from application code.) 441 * 442 * @param apb_freq new APB frequency, in Hz 443 */ 444 void rtc_clk_apb_freq_update(uint32_t apb_freq); 445 446 /** 447 * @brief Get the current stored APB frequency. 448 * @return The APB frequency value as last set via rtc_clk_apb_freq_update(), in Hz. 449 */ 450 uint32_t rtc_clk_apb_freq_get(void); 451 452 uint32_t rtc_clk_cal_internal(rtc_cal_sel_t cal_clk, uint32_t slowclk_cycles); 453 454 /** 455 * @brief Measure RTC slow clock's period, based on main XTAL frequency 456 * 457 * This function will time out and return 0 if the time for the given number 458 * of cycles to be counted exceeds the expected time twice. This may happen if 459 * 32k XTAL is being calibrated, but the oscillator has not started up (due to 460 * incorrect loading capacitance, board design issue, or lack of 32 XTAL on board). 461 * 462 * @note When 32k CLK is being calibrated, this function will check the accuracy 463 * of the clock. Since the xtal 32k or ext osc 32k is generally very stable, if 464 * the check fails, then consider this an invalid 32k clock and return 0. This 465 * check can filter some jamming signal. 466 * 467 * @param cal_clk clock to be measured 468 * @param slow_clk_cycles number of slow clock cycles to average 469 * @return average slow clock period in microseconds, Q13.19 fixed point format, 470 * or 0 if calibration has timed out 471 */ 472 uint32_t rtc_clk_cal(rtc_cal_sel_t cal_clk, uint32_t slow_clk_cycles); 473 474 /** 475 * @brief Measure ratio between XTAL frequency and RTC slow clock frequency 476 * @param cal_clk slow clock to be measured 477 * @param slow_clk_cycles number of slow clock cycles to average 478 * @return average ratio between XTAL frequency and slow clock frequency, 479 * Q13.19 fixed point format, or 0 if calibration has timed out. 480 */ 481 uint32_t rtc_clk_cal_ratio(rtc_cal_sel_t cal_clk, uint32_t slow_clk_cycles); 482 483 /** 484 * @brief Convert time interval from microseconds to RTC_SLOW_CLK cycles 485 * @param time_in_us Time interval in microseconds 486 * @param slow_clk_period Period of slow clock in microseconds, Q13.19 487 * fixed point format (as returned by rtc_slowck_cali). 488 * @return number of slow clock cycles 489 */ 490 uint64_t rtc_time_us_to_slowclk(uint64_t time_in_us, uint32_t period); 491 492 /** 493 * @brief Convert time interval from RTC_SLOW_CLK to microseconds 494 * @param time_in_us Time interval in RTC_SLOW_CLK cycles 495 * @param slow_clk_period Period of slow clock in microseconds, Q13.19 496 * fixed point format (as returned by rtc_slowck_cali). 497 * @return time interval in microseconds 498 */ 499 uint64_t rtc_time_slowclk_to_us(uint64_t rtc_cycles, uint32_t period); 500 501 /** 502 * @brief Get current value of RTC counter 503 * 504 * RTC has a 48-bit counter which is incremented by 2 every 2 RTC_SLOW_CLK 505 * cycles. Counter value is not writable by software. The value is not adjusted 506 * when switching to a different RTC_SLOW_CLK source. 507 * 508 * Note: this function may take up to 1 RTC_SLOW_CLK cycle to execute 509 * 510 * @return current value of RTC counter 511 */ 512 uint64_t rtc_time_get(void); 513 514 /** 515 * @brief Busy loop until next RTC_SLOW_CLK cycle 516 * 517 * This function returns not earlier than the next RTC_SLOW_CLK clock cycle. 518 * In some cases (e.g. when RTC_SLOW_CLK cycle is very close), it may return 519 * one RTC_SLOW_CLK cycle later. 520 */ 521 void rtc_clk_wait_for_slow_cycle(void); 522 523 /** 524 * @brief Enable the rtc digital 8M clock 525 * 526 * This function is used to enable the digital rtc 8M clock to support peripherals. 527 * For enabling the analog 8M clock, using `rtc_clk_8M_enable` function above. 528 */ 529 void rtc_dig_clk8m_enable(void); 530 531 /** 532 * @brief Disable the rtc digital 8M clock 533 * 534 * This function is used to disable the digital rtc 8M clock, which is only used to support peripherals. 535 */ 536 void rtc_dig_clk8m_disable(void); 537 538 /** 539 * @brief Get whether the rtc digital 8M clock is enabled 540 */ 541 bool rtc_dig_8m_enabled(void); 542 543 /** 544 * @brief Calculate the real clock value after the clock calibration 545 * 546 * @param cal_val Average slow clock period in microseconds, fixed point value as returned from `rtc_clk_cal` 547 * @return Frequency of the clock in Hz 548 */ 549 uint32_t rtc_clk_freq_cal(uint32_t cal_val); 550 551 /** 552 * @brief Power up flags for rtc_sleep_pd function 553 */ 554 typedef struct { 555 uint32_t dig_fpu : 1; //!< Set to 1 to power UP digital part in sleep 556 uint32_t rtc_fpu : 1; //!< Set to 1 to power UP RTC memories in sleep 557 uint32_t cpu_fpu : 1; //!< Set to 1 to power UP digital memories and CPU in sleep 558 uint32_t i2s_fpu : 1; //!< Set to 1 to power UP I2S in sleep 559 uint32_t bb_fpu : 1; //!< Set to 1 to power UP WiFi in sleep 560 uint32_t nrx_fpu : 1; //!< Set to 1 to power UP WiFi in sleep 561 uint32_t fe_fpu : 1; //!< Set to 1 to power UP WiFi in sleep 562 uint32_t sram_fpu : 1; //!< Set to 1 to power UP SRAM in sleep 563 uint32_t rom_ram_fpu : 1; //!< Set to 1 to power UP ROM/IRAM0_DRAM0 in sleep 564 } rtc_sleep_pu_config_t; 565 566 /** 567 * Initializer for rtc_sleep_pu_config_t which sets all flags to the same value 568 */ 569 #define RTC_SLEEP_PU_CONFIG_ALL(val) {\ 570 .dig_fpu = (val), \ 571 .rtc_fpu = (val), \ 572 .cpu_fpu = (val), \ 573 .i2s_fpu = (val), \ 574 .bb_fpu = (val), \ 575 .nrx_fpu = (val), \ 576 .fe_fpu = (val), \ 577 .sram_fpu = (val), \ 578 .rom_ram_fpu = (val), \ 579 } 580 581 void rtc_sleep_pu(rtc_sleep_pu_config_t cfg); 582 583 /** 584 * @brief sleep configuration for rtc_sleep_init function 585 */ 586 typedef struct { 587 uint32_t lslp_mem_inf_fpu : 1; //!< force normal voltage in sleep mode (digital domain memory) 588 uint32_t rtc_mem_inf_follow_cpu : 1;//!< keep low voltage in sleep mode (even if ULP/touch is used) 589 uint32_t rtc_fastmem_pd_en : 1; //!< power down RTC fast memory 590 uint32_t rtc_slowmem_pd_en : 1; //!< power down RTC slow memory 591 uint32_t rtc_peri_pd_en : 1; //!< power down RTC peripherals 592 uint32_t modem_pd_en : 1; //!< power down Modem(wifi and ble) 593 uint32_t cpu_pd_en : 1; //!< power down CPU, but not restart when lightsleep. 594 uint32_t int_8m_pd_en : 1; //!< Power down Internal 8M oscillator 595 uint32_t dig_peri_pd_en : 1; //!< power down digital peripherals 596 uint32_t deep_slp : 1; //!< power down digital domain 597 uint32_t wdt_flashboot_mod_en : 1; //!< enable WDT flashboot mode 598 uint32_t dig_dbias_slp : 5; //!< set bias for digital domain, in sleep mode 599 uint32_t rtc_dbias_slp : 5; //!< set bias for RTC domain, in sleep mode 600 uint32_t bias_sleep_monitor : 1; //!< circuit control parameter, in monitor mode 601 uint32_t dbg_atten_slp : 4; //!< voltage parameter, in sleep mode 602 uint32_t bias_sleep_slp : 1; //!< circuit control parameter, in sleep mode 603 uint32_t pd_cur_monitor : 1; //!< circuit control parameter, in monitor mode 604 uint32_t pd_cur_slp : 1; //!< circuit control parameter, in sleep mode 605 uint32_t vddsdio_pd_en : 1; //!< power down VDDSDIO regulator 606 uint32_t xtal_fpu : 1; //!< keep main XTAL powered up in sleep 607 uint32_t rtc_regulator_fpu : 1; //!< keep rtc regulator powered up in sleep 608 uint32_t deep_slp_reject : 1; //!< enable deep sleep reject 609 uint32_t light_slp_reject : 1; //!< enable light sleep reject 610 } rtc_sleep_config_t; 611 612 #define RTC_SLEEP_PD_DIG BIT(0) //!< Deep sleep (power down digital domain) 613 #define RTC_SLEEP_PD_RTC_PERIPH BIT(1) //!< Power down RTC peripherals 614 #define RTC_SLEEP_PD_RTC_SLOW_MEM BIT(2) //!< Power down RTC SLOW memory 615 #define RTC_SLEEP_PD_RTC_FAST_MEM BIT(3) //!< Power down RTC FAST memory 616 #define RTC_SLEEP_PD_RTC_MEM_FOLLOW_CPU BIT(4) //!< RTC FAST and SLOW memories are automatically powered up and down along with the CPU 617 #define RTC_SLEEP_PD_VDDSDIO BIT(5) //!< Power down VDDSDIO regulator 618 #define RTC_SLEEP_PD_MODEM BIT(6) //!< Power down Modem(wifi and ble) 619 #define RTC_SLEEP_PD_CPU BIT(8) //!< Power down CPU when in lightsleep, but not restart 620 #define RTC_SLEEP_PD_DIG_PERIPH BIT(9) //!< Power down DIG peripherals 621 #define RTC_SLEEP_PD_INT_8M BIT(10) //!< Power down Internal 8M oscillator 622 #define RTC_SLEEP_PD_XTAL BIT(11) //!< Power down main XTAL 623 624 //These flags are not power domains, but will affect some sleep parameters 625 #define RTC_SLEEP_DIG_USE_8M BIT(16) 626 #define RTC_SLEEP_USE_ADC_TESEN_MONITOR BIT(17) 627 #define RTC_SLEEP_NO_ULTRA_LOW BIT(18) //!< Avoid using ultra low power in deep sleep, in which RTCIO cannot be used as input, and RTCMEM can't work under high temperature 628 629 /** 630 * Default initializer for rtc_sleep_config_t 631 * 632 * This initializer sets all fields to "reasonable" values (e.g. suggested for 633 * production use) based on a combination of RTC_SLEEP_PD_x flags. 634 * 635 * @param RTC_SLEEP_PD_x flags combined using bitwise OR 636 */ 637 void rtc_sleep_get_default_config(uint32_t sleep_flags, rtc_sleep_config_t *out_config); 638 639 /** 640 * @brief Prepare the chip to enter sleep mode 641 * 642 * This function configures various power control state machines to handle 643 * entry into light sleep or deep sleep mode, switches APB and CPU clock source 644 * (usually to XTAL), and sets bias voltages for digital and RTC power domains. 645 * 646 * This function does not actually enter sleep mode; this is done using 647 * rtc_sleep_start function. Software may do some other actions between 648 * rtc_sleep_init and rtc_sleep_start, such as set wakeup timer and configure 649 * wakeup sources. 650 * @param cfg sleep mode configuration 651 */ 652 void rtc_sleep_init(rtc_sleep_config_t cfg); 653 654 /** 655 * @brief Low level initialize for rtc state machine waiting cycles after waking up 656 * 657 * This function configures the cycles chip need to wait for internal 8MHz 658 * oscillator and external 40MHz crystal. As we configure fixed time for waiting 659 * crystal, we need to pass period to calculate cycles. Now this function only 660 * used in lightsleep mode. 661 * 662 * @param slowclk_period re-calibrated slow clock period 663 */ 664 void rtc_sleep_low_init(uint32_t slowclk_period); 665 666 #define RTC_EXT0_TRIG_EN BIT(0) //!< EXT0 GPIO wakeup 667 #define RTC_EXT1_TRIG_EN BIT(1) //!< EXT1 GPIO wakeup 668 #define RTC_GPIO_TRIG_EN BIT(2) //!< GPIO wakeup (light sleep only) 669 #define RTC_TIMER_TRIG_EN BIT(3) //!< Timer wakeup 670 #define RTC_SDIO_TRIG_EN BIT(4) //!< SDIO wakeup (light sleep only) 671 #define RTC_WIFI_TRIG_EN BIT(5) //!< WIFI wakeup (light sleep only) 672 #define RTC_UART0_TRIG_EN BIT(6) //!< UART0 wakeup (light sleep only) 673 #define RTC_UART1_TRIG_EN BIT(7) //!< UART1 wakeup (light sleep only) 674 #define RTC_TOUCH_TRIG_EN BIT(8) //!< Touch wakeup 675 #define RTC_ULP_TRIG_EN BIT(9) //!< ULP wakeup 676 #define RTC_BT_TRIG_EN BIT(10) //!< BT wakeup (light sleep only) 677 #define RTC_COCPU_TRIG_EN BIT(11) 678 #define RTC_XTAL32K_DEAD_TRIG_EN BIT(12) 679 #define RTC_COCPU_TRAP_TRIG_EN BIT(13) 680 #define RTC_USB_TRIG_EN BIT(14) 681 682 /** 683 * RTC_SLEEP_REJECT_MASK records sleep reject sources supported by chip 684 */ 685 #define RTC_SLEEP_REJECT_MASK (RTC_EXT0_TRIG_EN | \ 686 RTC_EXT1_TRIG_EN | \ 687 RTC_GPIO_TRIG_EN | \ 688 RTC_TIMER_TRIG_EN | \ 689 RTC_SDIO_TRIG_EN | \ 690 RTC_WIFI_TRIG_EN | \ 691 RTC_UART0_TRIG_EN | \ 692 RTC_UART1_TRIG_EN | \ 693 RTC_TOUCH_TRIG_EN | \ 694 RTC_ULP_TRIG_EN | \ 695 RTC_BT_TRIG_EN | \ 696 RTC_COCPU_TRIG_EN | \ 697 RTC_XTAL32K_DEAD_TRIG_EN | \ 698 RTC_COCPU_TRAP_TRIG_EN | \ 699 RTC_USB_TRIG_EN) 700 701 /** 702 * @brief Enter deep or light sleep mode 703 * 704 * This function enters the sleep mode previously configured using rtc_sleep_init 705 * function. Before entering sleep, software should configure wake up sources 706 * appropriately (set up GPIO wakeup registers, timer wakeup registers, 707 * and so on). 708 * 709 * If deep sleep mode was configured using rtc_sleep_init, and sleep is not 710 * rejected by hardware (based on reject_opt flags), this function never returns. 711 * When the chip wakes up from deep sleep, CPU is reset and execution starts 712 * from ROM bootloader. 713 * 714 * If light sleep mode was configured using rtc_sleep_init, this function 715 * returns on wakeup, or if sleep is rejected by hardware. 716 * 717 * @param wakeup_opt bit mask wake up reasons to enable (RTC_xxx_TRIG_EN flags 718 * combined with OR) 719 * @param reject_opt bit mask of sleep reject reasons: 720 * - RTC_CNTL_GPIO_REJECT_EN 721 * - RTC_CNTL_SDIO_REJECT_EN 722 * These flags are used to prevent entering sleep when e.g. 723 * an external host is communicating via SDIO slave 724 * @param lslp_mem_inf_fpu If non-zero then the low power config is restored 725 * immediately on wake. Recommended for light sleep, 726 * has no effect if the system goes into deep sleep. 727 * 728 * @return non-zero if sleep was rejected by hardware 729 */ 730 uint32_t rtc_sleep_start(uint32_t wakeup_opt, uint32_t reject_opt, uint32_t lslp_mem_inf_fpu); 731 732 /** 733 * @brief Enter deep sleep mode 734 * 735 * Similar to rtc_sleep_start(), but additionally uses hardware to calculate the CRC value 736 * of RTC FAST memory. On wake, this CRC is used to determine if a deep sleep wake 737 * stub is valid to execute (if a wake address is set). 738 * 739 * No RAM is accessed while calculating the CRC and going into deep sleep, which makes 740 * this function safe to use even if the caller's stack is in RTC FAST memory. 741 * 742 * @note If no deep sleep wake stub address is set then calling rtc_sleep_start() will 743 * have the same effect and takes less time as CRC calculation is skipped. 744 * 745 * @note This function should only be called after rtc_sleep_init() has been called to 746 * configure the system for deep sleep. 747 * 748 * @param wakeup_opt - same as for rtc_sleep_start 749 * @param reject_opt - same as for rtc_sleep_start 750 * 751 * @return non-zero if sleep was rejected by hardware 752 */ 753 uint32_t rtc_deep_sleep_start(uint32_t wakeup_opt, uint32_t reject_opt); 754 755 /** 756 * RTC power and clock control initialization settings 757 */ 758 typedef struct { 759 uint32_t ck8m_wait : 8; //!< Number of rtc_fast_clk cycles to wait for 8M clock to be ready 760 uint32_t xtal_wait : 8; //!< Number of rtc_fast_clk cycles to wait for XTAL clock to be ready 761 uint32_t pll_wait : 8; //!< Number of rtc_fast_clk cycles to wait for PLL to be ready 762 uint32_t clkctl_init : 1; //!< Perform clock control related initialization 763 uint32_t pwrctl_init : 1; //!< Perform power control related initialization 764 uint32_t rtc_dboost_fpd : 1; //!< Force power down RTC_DBOOST 765 uint32_t xtal_fpu : 1; 766 uint32_t bbpll_fpu : 1; 767 uint32_t cpu_waiti_clk_gate : 1; 768 uint32_t cali_ocode : 1; //!< Calibrate Ocode to make bangap voltage more precise. 769 } rtc_config_t; 770 771 /** 772 * Default initializer of rtc_config_t. 773 * 774 * This initializer sets all fields to "reasonable" values (e.g. suggested for 775 * production use). 776 */ 777 #define RTC_CONFIG_DEFAULT() {\ 778 .ck8m_wait = RTC_CNTL_CK8M_WAIT_DEFAULT, \ 779 .xtal_wait = RTC_CNTL_XTL_BUF_WAIT_DEFAULT, \ 780 .pll_wait = RTC_CNTL_PLL_BUF_WAIT_DEFAULT, \ 781 .clkctl_init = 1, \ 782 .pwrctl_init = 1, \ 783 .rtc_dboost_fpd = 1, \ 784 .xtal_fpu = 0, \ 785 .bbpll_fpu = 0, \ 786 .cpu_waiti_clk_gate = 1, \ 787 .cali_ocode = 0 \ 788 } 789 790 /** 791 * Initialize RTC clock and power control related functions 792 * @param cfg configuration options as rtc_config_t 793 */ 794 void rtc_init(rtc_config_t cfg); 795 796 /** 797 * Structure describing vddsdio configuration 798 */ 799 typedef struct { 800 uint32_t force : 1; //!< If 1, use configuration from RTC registers; if 0, use EFUSE/bootstrapping pins. 801 uint32_t enable : 1; //!< Enable VDDSDIO regulator 802 uint32_t tieh : 1; //!< Select VDDSDIO voltage. One of RTC_VDDSDIO_TIEH_1_8V, RTC_VDDSDIO_TIEH_3_3V 803 uint32_t drefh : 2; //!< Tuning parameter for VDDSDIO regulator 804 uint32_t drefm : 2; //!< Tuning parameter for VDDSDIO regulator 805 uint32_t drefl : 2; //!< Tuning parameter for VDDSDIO regulator 806 } rtc_vddsdio_config_t; 807 808 /** 809 * Get current VDDSDIO configuration 810 * If VDDSDIO configuration is overridden by RTC, get values from RTC 811 * Otherwise, if VDDSDIO is configured by EFUSE, get values from EFUSE 812 * Otherwise, use default values and the level of MTDI bootstrapping pin. 813 * @return currently used VDDSDIO configuration 814 */ 815 rtc_vddsdio_config_t rtc_vddsdio_get_config(void); 816 817 /** 818 * Set new VDDSDIO configuration using RTC registers. 819 * If config.force == 1, this overrides configuration done using bootstrapping 820 * pins and EFUSE. 821 * 822 * @param config new VDDSDIO configuration 823 */ 824 void rtc_vddsdio_set_config(rtc_vddsdio_config_t config); 825 826 827 // -------------------------- CLOCK TREE DEFS ALIAS ---------------------------- 828 // **WARNING**: The following are only for backwards compatibility. 829 // Please use the declarations in soc/clk_tree_defs.h instead. 830 /** 831 * @brief CPU clock source 832 */ 833 typedef soc_cpu_clk_src_t rtc_cpu_freq_src_t; 834 #define RTC_CPU_FREQ_SRC_XTAL SOC_CPU_CLK_SRC_XTAL //!< XTAL 835 #define RTC_CPU_FREQ_SRC_PLL SOC_CPU_CLK_SRC_PLL //!< PLL (480M or 320M) 836 #define RTC_CPU_FREQ_SRC_8M SOC_CPU_CLK_SRC_RC_FAST //!< Internal 17.5M RTC oscillator 837 838 /** 839 * @brief RTC SLOW_CLK frequency values 840 */ 841 typedef soc_rtc_slow_clk_src_t rtc_slow_freq_t; 842 #define RTC_SLOW_FREQ_RTC SOC_RTC_SLOW_CLK_SRC_RC_SLOW //!< Internal 150 kHz RC oscillator 843 #define RTC_SLOW_FREQ_32K_XTAL SOC_RTC_SLOW_CLK_SRC_XTAL32K //!< External 32 kHz XTAL 844 #define RTC_SLOW_FREQ_8MD256 SOC_RTC_SLOW_CLK_SRC_RC_FAST_D256 //!< Internal 17.5 MHz RC oscillator, divided by 256 845 846 /** 847 * @brief RTC FAST_CLK frequency values 848 */ 849 typedef soc_rtc_fast_clk_src_t rtc_fast_freq_t; 850 #define RTC_FAST_FREQ_XTALD4 SOC_RTC_FAST_CLK_SRC_XTAL_DIV //!< Main XTAL, divided by 2 851 #define RTC_FAST_FREQ_8M SOC_RTC_FAST_CLK_SRC_RC_FAST //!< Internal 17.5 MHz RC oscillator 852 853 /* Alias of frequency related macros */ 854 #define RTC_FAST_CLK_FREQ_APPROX SOC_CLK_RC_FAST_FREQ_APPROX 855 #define RTC_FAST_CLK_FREQ_8M SOC_CLK_RC_FAST_FREQ_APPROX 856 #define RTC_SLOW_CLK_FREQ_150K SOC_CLK_RC_SLOW_FREQ_APPROX 857 #define RTC_SLOW_CLK_FREQ_8MD256 SOC_CLK_RC_FAST_D256_FREQ_APPROX 858 #define RTC_SLOW_CLK_FREQ_32K SOC_CLK_XTAL32K_FREQ_APPROX 859 860 /* Alias of deprecated function names */ 861 #define rtc_clk_slow_freq_set(slow_freq) rtc_clk_slow_src_set(slow_freq) 862 #define rtc_clk_slow_freq_get() rtc_clk_slow_src_get() 863 #define rtc_clk_fast_freq_set(fast_freq) rtc_clk_fast_src_set(fast_freq) 864 #define rtc_clk_fast_freq_get() rtc_clk_fast_src_get() 865 866 #ifdef __cplusplus 867 } 868 #endif 869
