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