Intel® Quark™ Microcontroller Software Interface  1.4.0
Intel® Quark™ Microcontroller BSP
clk.h
1 /*
2  * {% copyright %}
3  */
4 
5 #ifndef __CLK_H__
6 #define __CLK_H__
7 
8 #include "qm_common.h"
9 #include "qm_soc_regs.h"
10 #if (QM_SENSOR)
11 #include "qm_sensor_regs.h"
12 #endif
13 
14 /**
15  * Clock Management.
16  *
17  * @defgroup groupCLK Clock Management
18  * @{
19  */
20 
21 /*
22  * When using an external crystal, this value must be set to the number of
23  * system ticks per micro second. The expected value is 32 ticks for a 32MHz
24  * crystal.
25  */
26 #define SYS_TICKS_PER_US_XTAL (32)
27 /* System ticks per microseconds for a 32MHz oscillator. */
28 #define SYS_TICKS_PER_US_32MHZ (32)
29 /* System ticks per microseconds for a 16MHz oscillator. */
30 #define SYS_TICKS_PER_US_16MHZ (16)
31 /* System ticks per microseconds for a 8MHz oscillator. */
32 #define SYS_TICKS_PER_US_8MHZ (8)
33 /* System ticks per microseconds for a 4MHz oscillator. */
34 #define SYS_TICKS_PER_US_4MHZ (4)
35 
36 /**
37  * System clock divider type.
38  */
39 typedef enum {
40  CLK_SYS_DIV_1, /**< Clock Divider = 1. */
41  CLK_SYS_DIV_2, /**< Clock Divider = 2. */
42  CLK_SYS_DIV_4, /**< Clock Divider = 4. */
43  CLK_SYS_DIV_8, /**< Clock Divider = 8. */
44  CLK_SYS_DIV_NUM
46 
47 /**
48  * System clock mode type.
49  */
50 typedef enum {
51  CLK_SYS_HYB_OSC_32MHZ = 0, /**< 32MHz Hybrid Oscillator Clock. */
52  CLK_SYS_HYB_OSC_16MHZ = 1, /**< 16MHz Hybrid Oscillator Clock. */
53  CLK_SYS_HYB_OSC_8MHZ = 2, /**< 8MHz Hybrid Oscillator Clock. */
54  CLK_SYS_HYB_OSC_4MHZ = 3, /**< 4MHz Hybrid Oscillator Clock. */
55  CLK_SYS_RTC_OSC = 4, /**< Real Time Clock. */
56  CLK_SYS_CRYSTAL_OSC = 5 /**< Crystal Oscillator Clock. */
58 
59 /**
60  * Peripheral clock divider type.
61  */
62 typedef enum {
63  CLK_PERIPH_DIV_1, /**< Peripheral Clock Divider = 1. */
64  CLK_PERIPH_DIV_2, /**< Peripheral Clock Divider = 2. */
65  CLK_PERIPH_DIV_4, /**< Peripheral Clock Divider = 4. */
66  CLK_PERIPH_DIV_8 /**< Peripheral Clock Divider = 8. */
68 
69 /**
70  * GPIO clock debounce divider type.
71  */
72 typedef enum {
73  CLK_GPIO_DB_DIV_1, /**< GPIO Clock Debounce Divider = 1. */
74  CLK_GPIO_DB_DIV_2, /**< GPIO Clock Debounce Divider = 2. */
75  CLK_GPIO_DB_DIV_4, /**< GPIO Clock Debounce Divider = 4. */
76  CLK_GPIO_DB_DIV_8, /**< GPIO Clock Debounce Divider = 8. */
77  CLK_GPIO_DB_DIV_16, /**< GPIO Clock Debounce Divider = 16. */
78  CLK_GPIO_DB_DIV_32, /**< GPIO Clock Debounce Divider = 32. */
79  CLK_GPIO_DB_DIV_64, /**< GPIO Clock Debounce Divider = 64. */
80  CLK_GPIO_DB_DIV_128 /**< GPIO Clock Debounce Divider = 128. */
82 
83 /**
84  * External crystal clock divider type.
85  */
86 typedef enum {
87  CLK_EXT_DIV_1, /**< External Crystal Clock Divider = 1. */
88  CLK_EXT_DIV_2, /**< External Crystal Clock Divider = 2. */
89  CLK_EXT_DIV_4, /**< External Crystal Clock Divider = 4. */
90  CLK_EXT_DIV_8 /**< External Crystal Clock Divider = 8. */
92 
93 /**
94  * RTC clock divider type.
95  */
96 typedef enum {
97  CLK_RTC_DIV_1, /**< Real Time Clock Divider = 1. */
98  CLK_RTC_DIV_2, /**< Real Time Clock Divider = 2. */
99  CLK_RTC_DIV_4, /**< Real Time Clock Divider = 4. */
100  CLK_RTC_DIV_8, /**< Real Time Clock Divider = 8. */
101  CLK_RTC_DIV_16, /**< Real Time Clock Divider = 16. */
102  CLK_RTC_DIV_32, /**< Real Time Clock Divider = 32. */
103  CLK_RTC_DIV_64, /**< Real Time Clock Divider = 64. */
104  CLK_RTC_DIV_128, /**< Real Time Clock Divider = 128. */
105  CLK_RTC_DIV_256, /**< Real Time Clock Divider = 256. */
106  CLK_RTC_DIV_512, /**< Real Time Clock Divider = 512. */
107  CLK_RTC_DIV_1024, /**< Real Time Clock Divider = 1024. */
108  CLK_RTC_DIV_2048, /**< Real Time Clock Divider = 2048. */
109  CLK_RTC_DIV_4096, /**< Real Time Clock Divider = 4096. */
110  CLK_RTC_DIV_8192, /**< Real Time Clock Divider = 8192. */
111  CLK_RTC_DIV_16384, /**< Real Time Clock Divider = 16384. */
112  CLK_RTC_DIV_32768 /**< Real Time Clock Divider = 32768. */
113 } clk_rtc_div_t;
114 
115 /**
116  * Set clock mode and divisor.
117  *
118  * Change the operating mode and clock divisor of the system
119  * clock source. Changing this clock speed affects all
120  * peripherals.
121  * This applies the correct trim code if available.
122  *
123  * If trim code is not available, it is not computed
124  * and previous trim code is not modified.
125  *
126  * @param[in] mode System clock source operating mode.
127  * @param[in] div System clock divisor.
128  *
129  * @return Standard errno return type for QMSI.
130  * @retval 0 on success.
131  * @retval Negative @ref errno for possible error codes.
132  */
133 int clk_sys_set_mode(const clk_sys_mode_t mode, const clk_sys_div_t div);
134 
135 /**
136  * Read the silicon oscillator trim code for the current frequency.
137  *
138  * @param[out] value Pointer to store the trim code.
139  *
140  * @return Standard errno return type for QMSI.
141  * @retval 0 on success.
142  * @retval Negative @ref errno for possible error codes.
143  */
144 int clk_trim_read(uint32_t *const value);
145 
146 /**
147  * Apply silicon oscillator trim code.
148  *
149  * @param[in] value Trim code to apply.
150  *
151  * @return Standard errno return type for QMSI.
152  * @retval 0 on success.
153  * @retval Negative @ref errno for possible error codes.
154  */
155 int clk_trim_apply(const uint32_t value);
156 
157 /**
158  * Change divider value of peripheral clock.
159  *
160  * Change Peripheral clock divider value.
161  * The maximum divisor is /8.
162  * Refer to the list of supported peripherals for your SoC.
163  *
164  * @param[in] div Divider value for the peripheral clock.
165  *
166  * @return Standard errno return type for QMSI.
167  * @retval 0 on success.
168  * @retval Negative @ref errno for possible error codes.
169  */
170 int clk_periph_set_div(const clk_periph_div_t div);
171 
172 /**
173  * Change divider value of GPIO debounce clock.
174  *
175  * Change GPIO debounce clock divider value.
176  * The maximum divisor is /128.
177  *
178  * @param[in] div Divider value for the GPIO debounce clock.
179  *
180  * @return Standard errno return type for QMSI.
181  * @retval 0 on success.
182  * @retval Negative @ref errno for possible error codes.
183  */
185 
186 /**
187  * Change divider value of external clock.
188  *
189  * Change External clock divider value.
190  * The maximum divisor is /8.
191  *
192  * @param[in] div Divider value for the external clock.
193  *
194  * @return Standard errno return type for QMSI.
195  * @retval 0 on success.
196  * @retval Negative @ref errno for possible error codes.
197  */
198 int clk_ext_set_div(const clk_ext_div_t div);
199 
200 /**
201  * Change divider value of RTC.
202  *
203  * Change RTC divider value.
204  * The maximum divisor is /32768.
205  *
206  * @param[in] div Divider value for the RTC.
207  *
208  * @return Standard errno return type for QMSI.
209  * @retval 0 on success.
210  * @retval Negative @ref errno for possible error codes.
211  */
212 int clk_rtc_set_div(const clk_rtc_div_t div);
213 
214 /**
215  * Enable clocks for peripherals / registers.
216  *
217  * @param[in] clocks Which peripheral and register clocks to enable.
218  *
219  * @return Standard errno return type for QMSI.
220  * @retval 0 on success.
221  * @retval Negative @ref errno for possible error codes.
222  */
223 int clk_periph_enable(const clk_periph_t clocks);
224 
225 /**
226  * Disable clocks for peripherals / registers.
227  *
228  * @param[in] clocks Which peripheral and register clocks to disable.
229  *
230  * @return Standard errno return type for QMSI.
231  * @retval 0 on success.
232  * @retval Negative @ref errno for possible error codes.
233  */
234 int clk_periph_disable(const clk_periph_t clocks);
235 
236 /**
237  * Get number of system ticks per micro second.
238  *
239  * @return uint32_t Number of system ticks per micro second.
240  */
241 uint32_t clk_sys_get_ticks_per_us(void);
242 
243 /**
244  * Idle loop the processor for at least the value given in microseconds.
245  *
246  * This function will wait until at least the given number of microseconds has
247  * elapsed since calling this function.
248  *
249  * Note:
250  * It is dependent on the system clock speed.
251  * The delay parameter does not include, calling the function, returning
252  * from it, calculation setup and while loops.
253  *
254  * @param[in] microseconds Minimum number of micro seconds to delay for.
255  */
256 void clk_sys_udelay(uint32_t microseconds);
257 
258 /**
259  * Enable the USB Clock mode.
260  *
261  * For Quark SE, this function will set the system clock to CLK_SYS_CRYSTAL_OSC
262  * mode with CLK_SYS_DIV_1 divisor. It then will enable the USB Clock and PLL,
263  * blocking execution until the USB PLL lock is ready.
264  *
265  * Note:
266  * Application must retain the original system clock mode / divisor in case it
267  * will need to restore it after disabling the usb clock.
268  *
269  * @return Standard errno return type for QMSI.
270  * @retval 0 on success.
271  * @retval Negative @ref errno for possible error codes.
272  */
273 int clk_sys_usb_enable(void);
274 
275 /**
276  * Disable the USB Clock mode.
277  *
278  * This function will disable the USB Clock and PLL.
279  * The system clock will remain as CLK_SYS_CRYSTAL_OSC mode and CLK_SYS_DIV_1
280  * divider.
281  *
282  * Note:
283  * If the application must restore the original system clock mode / divisor
284  * it must explictly call clk_sys_set_mode() restoring the previous config.
285  * This can only be done after the USB clock mode is disabled.
286  *
287  * @return Standard errno return type for QMSI.
288  * @retval 0 on success.
289  * @retval Negative @ref errno for possible error codes.
290  */
291 int clk_sys_usb_disable(void);
292 
293 /**
294  * Enable the DMA clock.
295  *
296  * Enable the DMA clock by setting the corresponding bit in the AHB Control
297  * register. By default the DMA clock is disabled.
298  *
299  * @return Standard errno return type for QMSI.
300  * @retval 0 on success.
301  * @retval Negative @ref errno for possible error codes.
302  */
303 int clk_dma_enable(void);
304 
305 /**
306  * Disable the DMA clock.
307  *
308  * Disable the DMA clock by clearing the corresponding bit in the AHB Control
309  * register.
310  *
311  * @return Standard errno return type for QMSI.
312  * @retval 0 on success.
313  * @retval Negative @ref errno for possible error codes.
314  */
315 int clk_dma_disable(void);
316 
317 /**
318  * Get I2C clock frequency in MHz.
319  *
320  * @return [uint32_t] I2C freq_in_mhz.
321  */
322 uint32_t get_i2c_clk_freq_in_mhz(void);
323 
324 /**
325  * @}
326  */
327 
328 #endif /* __CLK_H__ */
clk_sys_mode_t
System clock mode type.
Definition: clk.h:51
External Crystal Clock Divider = 4.
Definition: clk.h:90
int clk_sys_set_mode(const clk_sys_mode_t mode, const clk_sys_div_t div)
Set clock mode and divisor.
Definition: clk.c:100
int clk_sys_usb_disable(void)
Disable the USB Clock mode.
Definition: clk.c:386
Peripheral Clock Divider = 2.
Definition: clk.h:65
Clock Divider = 8.
Definition: clk.h:40
Real Time Clock Divider = 32768.
Definition: clk.h:113
int clk_rtc_set_div(const clk_rtc_div_t div)
Change divider value of RTC.
Definition: clk.c:306
int clk_periph_enable(const clk_periph_t clocks)
Enable clocks for peripherals / registers.
Definition: clk.c:319
Peripheral Clock Divider = 8.
Definition: clk.h:67
uint32_t get_i2c_clk_freq_in_mhz(void)
Get I2C clock frequency in MHz.
Definition: clk.c:381
int clk_gpio_db_set_div(const clk_gpio_db_div_t div)
Change divider value of GPIO debounce clock.
Definition: clk.c:279
Crystal Oscillator Clock.
Definition: clk.h:57
int clk_dma_enable(void)
Enable the DMA clock.
Definition: clk.c:362
Real Time Clock Divider = 2.
Definition: clk.h:99
clk_sys_div_t
System clock divider type.
Definition: clk.h:36
Peripheral Clock Divider = 1.
Definition: clk.h:64
GPIO Clock Debounce Divider = 2.
Definition: clk.h:75
External Crystal Clock Divider = 1.
Definition: clk.h:88
16MHz Hybrid Oscillator Clock.
Definition: clk.h:53
GPIO Clock Debounce Divider = 4.
Definition: clk.h:76
int clk_trim_read(uint32_t *const value)
Read the silicon oscillator trim code for the current frequency.
Definition: clk.c:214
clk_periph_div_t
Peripheral clock divider type.
Definition: clk.h:63
32MHz Hybrid Oscillator Clock.
Definition: clk.h:52
Real Time Clock Divider = 8.
Definition: clk.h:101
Real Time Clock Divider = 4096.
Definition: clk.h:110
GPIO Clock Debounce Divider = 128.
Definition: clk.h:81
External Crystal Clock Divider = 8.
Definition: clk.h:91
External Crystal Clock Divider = 2.
Definition: clk.h:89
GPIO Clock Debounce Divider = 1.
Definition: clk.h:74
clk_gpio_db_div_t
GPIO clock debounce divider type.
Definition: clk.h:73
clk_rtc_div_t
RTC clock divider type.
Definition: clk.h:97
void clk_sys_udelay(uint32_t microseconds)
Idle loop the processor for at least the value given in microseconds.
Definition: clk.c:352
8MHz Hybrid Oscillator Clock.
Definition: clk.h:54
Real Time Clock Divider = 16384.
Definition: clk.h:112
uint32_t clk_sys_get_ticks_per_us(void)
Get number of system ticks per micro second.
Definition: clk.c:347
GPIO Clock Debounce Divider = 64.
Definition: clk.h:80
Clock Divider = 2.
Definition: clk.h:38
int clk_periph_disable(const clk_periph_t clocks)
Disable clocks for peripherals / registers.
Definition: clk.c:333
int clk_periph_set_div(const clk_periph_div_t div)
Change divider value of peripheral clock.
Definition: clk.c:265
Real Time Clock Divider = 1.
Definition: clk.h:98
Real Time Clock Divider = 64.
Definition: clk.h:104
Clock Divider = 4.
Definition: clk.h:39
Real Time Clock Divider = 16.
Definition: clk.h:102
int clk_trim_apply(const uint32_t value)
Apply silicon oscillator trim code.
Definition: clk.c:224
Real Time Clock Divider = 256.
Definition: clk.h:106
Peripheral Clock Divider = 4.
Definition: clk.h:66
Real Time Clock Divider = 1024.
Definition: clk.h:108
Real Time Clock Divider = 512.
Definition: clk.h:107
Real Time Clock Divider = 128.
Definition: clk.h:105
GPIO Clock Debounce Divider = 32.
Definition: clk.h:79
Real Time Clock Divider = 32.
Definition: clk.h:103
GPIO Clock Debounce Divider = 16.
Definition: clk.h:78
int clk_ext_set_div(const clk_ext_div_t div)
Change divider value of external clock.
Definition: clk.c:293
int clk_dma_disable(void)
Disable the DMA clock.
Definition: clk.c:369
Real Time Clock.
Definition: clk.h:56
4MHz Hybrid Oscillator Clock.
Definition: clk.h:55
clk_periph_t
Peripheral clock register map.
Definition: qm_soc_regs.h:1368
clk_ext_div_t
External crystal clock divider type.
Definition: clk.h:87
int clk_sys_usb_enable(void)
Enable the USB Clock mode.
Definition: clk.c:356
GPIO Clock Debounce Divider = 8.
Definition: clk.h:77
Real Time Clock Divider = 4.
Definition: clk.h:100
Real Time Clock Divider = 2048.
Definition: clk.h:109
Clock Divider = 1.
Definition: clk.h:37
Real Time Clock Divider = 8192.
Definition: clk.h:111