1 /*
2  * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 
7 #include <stdint.h>
8 #include "esp_rom_sys.h"
9 #include "hal/clk_tree_ll.h"
10 #include "hal/rtc_cntl_ll.h"
11 #include "soc/rtc.h"
12 #include "soc/timer_periph.h"
13 #include "esp_hw_log.h"
14 
15 static const char* TAG = "rtc_time";
16 
17 /* Calibration of RTC_SLOW_CLK is performed using a special feature of TIMG0.
18  * This feature counts the number of XTAL clock cycles within a given number of
19  * RTC_SLOW_CLK cycles.
20  *
21  * Slow clock calibration feature has two modes of operation: one-off and cycling.
22  * In cycling mode (which is enabled by default on SoC reset), counting of XTAL
23  * cycles within RTC_SLOW_CLK cycle is done continuously. Cycling mode is enabled
24  * using TIMG_RTC_CALI_START_CYCLING bit. In one-off mode counting is performed
25  * once, and TIMG_RTC_CALI_RDY bit is set when counting is done. One-off mode is
26  * enabled using TIMG_RTC_CALI_START bit.
27  */
28 
29 /**
30  * @brief Clock calibration function used by rtc_clk_cal and rtc_clk_cal_ratio
31  * @param cal_clk which clock to calibrate
32  * @param slowclk_cycles number of slow clock cycles to count. Max value is 32766.
33  * @return number of XTAL clock cycles within the given number of slow clock cycles
34  */
rtc_clk_cal_internal(rtc_cal_sel_t cal_clk,uint32_t slowclk_cycles)35 static uint32_t rtc_clk_cal_internal(rtc_cal_sel_t cal_clk, uint32_t slowclk_cycles)
36 {
37     assert(slowclk_cycles < 32767);
38     /* Enable requested clock (150k clock is always on) */
39     bool dig_32k_xtal_enabled = clk_ll_xtal32k_digi_is_enabled();
40     if (cal_clk == RTC_CAL_32K_XTAL && !dig_32k_xtal_enabled) {
41         clk_ll_xtal32k_digi_enable();
42     }
43 
44     bool rc_fast_enabled = clk_ll_rc_fast_is_enabled();
45     bool rc_fast_d256_enabled = clk_ll_rc_fast_d256_is_enabled();
46     if (cal_clk == RTC_CAL_8MD256) {
47         rtc_clk_8m_enable(true, true);
48         clk_ll_rc_fast_d256_digi_enable();
49     }
50     /* Prepare calibration */
51     REG_SET_FIELD(TIMG_RTCCALICFG_REG(0), TIMG_RTC_CALI_CLK_SEL, cal_clk);
52     CLEAR_PERI_REG_MASK(TIMG_RTCCALICFG_REG(0), TIMG_RTC_CALI_START_CYCLING);
53     REG_SET_FIELD(TIMG_RTCCALICFG_REG(0), TIMG_RTC_CALI_MAX, slowclk_cycles);
54     /* Figure out how long to wait for calibration to finish */
55     uint32_t expected_freq;
56     soc_rtc_slow_clk_src_t slow_clk_src = rtc_clk_slow_src_get();
57     if (cal_clk == RTC_CAL_32K_XTAL ||
58         (cal_clk == RTC_CAL_RTC_MUX && slow_clk_src == SOC_RTC_SLOW_CLK_SRC_XTAL32K)) {
59         expected_freq = SOC_CLK_XTAL32K_FREQ_APPROX; /* standard 32k XTAL */
60     } else if (cal_clk == RTC_CAL_8MD256 ||
61             (cal_clk == RTC_CAL_RTC_MUX && slow_clk_src == SOC_RTC_SLOW_CLK_SRC_RC_FAST_D256)) {
62         expected_freq = SOC_CLK_RC_FAST_D256_FREQ_APPROX;
63     } else {
64         expected_freq = SOC_CLK_RC_SLOW_FREQ_APPROX; /* 150k internal oscillator */
65     }
66     uint32_t us_time_estimate = (uint32_t) (((uint64_t) slowclk_cycles) * MHZ / expected_freq);
67     /* Check if the required number of slowclk_cycles may result in an overflow of TIMG_RTC_CALI_VALUE */
68     rtc_xtal_freq_t xtal_freq = rtc_clk_xtal_freq_get();
69     if (xtal_freq == RTC_XTAL_FREQ_AUTO) {
70         /* XTAL frequency is not known yet; assume worst case (40 MHz) */
71         xtal_freq = RTC_XTAL_FREQ_40M;
72     }
73     const uint32_t us_timer_max =  TIMG_RTC_CALI_VALUE / (uint32_t) xtal_freq;
74     if (us_time_estimate >= us_timer_max) {
75         ESP_HW_LOGE(TAG, "slowclk_cycles value too large, possible overflow");
76         return 0;
77     }
78     /* Start calibration */
79     CLEAR_PERI_REG_MASK(TIMG_RTCCALICFG_REG(0), TIMG_RTC_CALI_START);
80     SET_PERI_REG_MASK(TIMG_RTCCALICFG_REG(0), TIMG_RTC_CALI_START);
81     /* Wait the expected time calibration should take.
82      * TODO: if running under RTOS, and us_time_estimate > RTOS tick, use the
83      * RTOS delay function.
84      */
85     esp_rom_delay_us(us_time_estimate);
86     /* Wait for calibration to finish up to another us_time_estimate */
87     int timeout_us = us_time_estimate;
88     while (!GET_PERI_REG_MASK(TIMG_RTCCALICFG_REG(0), TIMG_RTC_CALI_RDY) &&
89             timeout_us > 0) {
90         timeout_us--;
91         esp_rom_delay_us(1);
92     }
93 
94     /* if dig_32k_xtal was originally off and enabled due to calibration, then set back to off state */
95     if (cal_clk == RTC_CAL_32K_XTAL && !dig_32k_xtal_enabled) {
96         clk_ll_xtal32k_digi_disable();
97     }
98 
99     if (cal_clk == RTC_CAL_8MD256) {
100         clk_ll_rc_fast_d256_digi_disable();
101         rtc_clk_8m_enable(rc_fast_enabled, rc_fast_d256_enabled);
102     }
103     if (timeout_us == 0) {
104         /* timed out waiting for calibration */
105         return 0;
106     }
107 
108     return REG_GET_FIELD(TIMG_RTCCALICFG1_REG(0), TIMG_RTC_CALI_VALUE);
109 }
110 
rtc_clk_cal_ratio(rtc_cal_sel_t cal_clk,uint32_t slowclk_cycles)111 uint32_t rtc_clk_cal_ratio(rtc_cal_sel_t cal_clk, uint32_t slowclk_cycles)
112 {
113     assert(slowclk_cycles);
114     uint64_t xtal_cycles = rtc_clk_cal_internal(cal_clk, slowclk_cycles);
115     uint64_t ratio_64 = ((xtal_cycles << RTC_CLK_CAL_FRACT)) / slowclk_cycles;
116     uint32_t ratio = (uint32_t)(ratio_64 & UINT32_MAX);
117     return ratio;
118 }
119 
rtc_clk_cal_32k_valid(rtc_xtal_freq_t xtal_freq,uint32_t slowclk_cycles,uint64_t actual_xtal_cycles)120 static inline bool rtc_clk_cal_32k_valid(rtc_xtal_freq_t xtal_freq, uint32_t slowclk_cycles, uint64_t actual_xtal_cycles)
121 {
122     uint64_t expected_xtal_cycles = (xtal_freq * 1000000ULL * slowclk_cycles) >> 15; // xtal_freq(hz) * slowclk_cycles / 32768
123     uint64_t delta = expected_xtal_cycles / 2000;                                    // 5/10000
124     return (actual_xtal_cycles >= (expected_xtal_cycles - delta)) && (actual_xtal_cycles <= (expected_xtal_cycles + delta));
125 }
126 
rtc_clk_cal(rtc_cal_sel_t cal_clk,uint32_t slowclk_cycles)127 uint32_t rtc_clk_cal(rtc_cal_sel_t cal_clk, uint32_t slowclk_cycles)
128 {
129     assert(slowclk_cycles);
130     rtc_xtal_freq_t xtal_freq = rtc_clk_xtal_freq_get();
131     uint64_t xtal_cycles = rtc_clk_cal_internal(cal_clk, slowclk_cycles);
132 
133     if ((cal_clk == RTC_CAL_32K_XTAL) && !rtc_clk_cal_32k_valid(xtal_freq, slowclk_cycles, xtal_cycles)) {
134         return 0;
135     }
136 
137     uint64_t divider = ((uint64_t)xtal_freq) * slowclk_cycles;
138     uint64_t period_64 = ((xtal_cycles << RTC_CLK_CAL_FRACT) + divider / 2 - 1) / divider;
139     uint32_t period = (uint32_t)(period_64 & UINT32_MAX);
140     return period;
141 }
142 
rtc_time_us_to_slowclk(uint64_t time_in_us,uint32_t period)143 uint64_t rtc_time_us_to_slowclk(uint64_t time_in_us, uint32_t period)
144 {
145     assert(period);
146     /* Overflow will happen in this function if time_in_us >= 2^45, which is about 400 days.
147      * TODO: fix overflow.
148      */
149     return (time_in_us << RTC_CLK_CAL_FRACT) / period;
150 }
151 
rtc_time_slowclk_to_us(uint64_t rtc_cycles,uint32_t period)152 uint64_t rtc_time_slowclk_to_us(uint64_t rtc_cycles, uint32_t period)
153 {
154     return (rtc_cycles * period) >> RTC_CLK_CAL_FRACT;
155 }
156 
rtc_time_get(void)157 uint64_t rtc_time_get(void)
158 {
159     return rtc_cntl_ll_get_rtc_time();
160 }
161 
rtc_clk_wait_for_slow_cycle(void)162 void rtc_clk_wait_for_slow_cycle(void)
163 {
164     REG_CLR_BIT(TIMG_RTCCALICFG_REG(0), TIMG_RTC_CALI_START_CYCLING | TIMG_RTC_CALI_START);
165     REG_CLR_BIT(TIMG_RTCCALICFG_REG(0), TIMG_RTC_CALI_RDY);
166     REG_SET_FIELD(TIMG_RTCCALICFG_REG(0), TIMG_RTC_CALI_CLK_SEL, RTC_CAL_RTC_MUX);
167     /* Request to run calibration for 0 slow clock cycles.
168      * RDY bit will be set on the nearest slow clock cycle.
169      */
170     REG_SET_FIELD(TIMG_RTCCALICFG_REG(0), TIMG_RTC_CALI_MAX, 0);
171     REG_SET_BIT(TIMG_RTCCALICFG_REG(0), TIMG_RTC_CALI_START);
172     esp_rom_delay_us(1); /* RDY needs some time to go low */
173     int attempts = 1000;
174     while (!GET_PERI_REG_MASK(TIMG_RTCCALICFG_REG(0), TIMG_RTC_CALI_RDY)) {
175         esp_rom_delay_us(1);
176         if (attempts) {
177             if (--attempts == 0 && clk_ll_xtal32k_digi_is_enabled()) {
178                 ESP_HW_LOGE(TAG, "32kHz xtal has been stopped");
179             }
180         }
181     }
182 }
183 
rtc_clk_freq_cal(uint32_t cal_val)184 uint32_t rtc_clk_freq_cal(uint32_t cal_val)
185 {
186     if (cal_val == 0) {
187         return 0;   // cal_val will be denominator, return 0 as the symbol of failure.
188     }
189     return 1000000ULL * (1 << RTC_CLK_CAL_FRACT) / cal_val;
190 }
191