Intel® Quark™ Microcontroller Software Interface 1.4.0 Intel® Quark™ Microcontroller BSP

- Main Page
- Modules
- Data Structures
- Files

- File List

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
45 } clk_sys_div_t;
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. */
57 } clk_sys_mode_t;
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. */
67 } clk_periph_div_t;
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. */
81 } clk_gpio_db_div_t;
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. */
91 } clk_ext_div_t;
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 */
184 int clk_gpio_db_set_div(const clk_gpio_db_div_t div);
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
clk_sys_mode_t
System clock mode type.
Definition: clk.h:51
CLK_EXT_DIV_4
External Crystal Clock Divider = 4.
Definition: clk.h:90
clk_sys_set_mode
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
clk_sys_usb_disable
int clk_sys_usb_disable(void)
Disable the USB Clock mode.
Definition: clk.c:386
CLK_PERIPH_DIV_2
Peripheral Clock Divider = 2.
Definition: clk.h:65
CLK_SYS_DIV_8
Clock Divider = 8.
Definition: clk.h:40
CLK_RTC_DIV_32768
Real Time Clock Divider = 32768.
Definition: clk.h:113
clk_rtc_set_div
int clk_rtc_set_div(const clk_rtc_div_t div)
Change divider value of RTC.
Definition: clk.c:306
clk_periph_enable
int clk_periph_enable(const clk_periph_t clocks)
Enable clocks for peripherals / registers.
Definition: clk.c:319
CLK_PERIPH_DIV_8
Peripheral Clock Divider = 8.
Definition: clk.h:67
get_i2c_clk_freq_in_mhz
uint32_t get_i2c_clk_freq_in_mhz(void)
Get I2C clock frequency in MHz.
Definition: clk.c:381
clk_gpio_db_set_div
int clk_gpio_db_set_div(const clk_gpio_db_div_t div)
Change divider value of GPIO debounce clock.
Definition: clk.c:279
CLK_SYS_CRYSTAL_OSC
Crystal Oscillator Clock.
Definition: clk.h:57
clk_dma_enable
int clk_dma_enable(void)
Enable the DMA clock.
Definition: clk.c:362
CLK_RTC_DIV_2
Real Time Clock Divider = 2.
Definition: clk.h:99
clk_sys_div_t
clk_sys_div_t
System clock divider type.
Definition: clk.h:36
CLK_PERIPH_DIV_1
Peripheral Clock Divider = 1.
Definition: clk.h:64
CLK_GPIO_DB_DIV_2
GPIO Clock Debounce Divider = 2.
Definition: clk.h:75
CLK_EXT_DIV_1
External Crystal Clock Divider = 1.
Definition: clk.h:88
CLK_SYS_HYB_OSC_16MHZ
16MHz Hybrid Oscillator Clock.
Definition: clk.h:53
CLK_GPIO_DB_DIV_4
GPIO Clock Debounce Divider = 4.
Definition: clk.h:76
clk_trim_read
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
clk_periph_div_t
Peripheral clock divider type.
Definition: clk.h:63
CLK_SYS_HYB_OSC_32MHZ
32MHz Hybrid Oscillator Clock.
Definition: clk.h:52
CLK_RTC_DIV_8
Real Time Clock Divider = 8.
Definition: clk.h:101
CLK_RTC_DIV_4096
Real Time Clock Divider = 4096.
Definition: clk.h:110
CLK_GPIO_DB_DIV_128
GPIO Clock Debounce Divider = 128.
Definition: clk.h:81
CLK_EXT_DIV_8
External Crystal Clock Divider = 8.
Definition: clk.h:91
CLK_EXT_DIV_2
External Crystal Clock Divider = 2.
Definition: clk.h:89
CLK_GPIO_DB_DIV_1
GPIO Clock Debounce Divider = 1.
Definition: clk.h:74
clk_gpio_db_div_t
clk_gpio_db_div_t
GPIO clock debounce divider type.
Definition: clk.h:73
clk_rtc_div_t
clk_rtc_div_t
RTC clock divider type.
Definition: clk.h:97
clk_sys_udelay
void clk_sys_udelay(uint32_t microseconds)
Idle loop the processor for at least the value given in microseconds.
Definition: clk.c:352
CLK_SYS_HYB_OSC_8MHZ
8MHz Hybrid Oscillator Clock.
Definition: clk.h:54
CLK_RTC_DIV_16384
Real Time Clock Divider = 16384.
Definition: clk.h:112
clk_sys_get_ticks_per_us
uint32_t clk_sys_get_ticks_per_us(void)
Get number of system ticks per micro second.
Definition: clk.c:347
CLK_GPIO_DB_DIV_64
GPIO Clock Debounce Divider = 64.
Definition: clk.h:80
CLK_SYS_DIV_2
Clock Divider = 2.
Definition: clk.h:38
clk_periph_disable
int clk_periph_disable(const clk_periph_t clocks)
Disable clocks for peripherals / registers.
Definition: clk.c:333
clk_periph_set_div
int clk_periph_set_div(const clk_periph_div_t div)
Change divider value of peripheral clock.
Definition: clk.c:265
CLK_RTC_DIV_1
Real Time Clock Divider = 1.
Definition: clk.h:98
CLK_RTC_DIV_64
Real Time Clock Divider = 64.
Definition: clk.h:104
CLK_SYS_DIV_4
Clock Divider = 4.
Definition: clk.h:39
CLK_RTC_DIV_16
Real Time Clock Divider = 16.
Definition: clk.h:102
clk_trim_apply
int clk_trim_apply(const uint32_t value)
Apply silicon oscillator trim code.
Definition: clk.c:224
CLK_RTC_DIV_256
Real Time Clock Divider = 256.
Definition: clk.h:106
CLK_PERIPH_DIV_4
Peripheral Clock Divider = 4.
Definition: clk.h:66
CLK_RTC_DIV_1024
Real Time Clock Divider = 1024.
Definition: clk.h:108
CLK_RTC_DIV_512
Real Time Clock Divider = 512.
Definition: clk.h:107
CLK_RTC_DIV_128
Real Time Clock Divider = 128.
Definition: clk.h:105
CLK_GPIO_DB_DIV_32
GPIO Clock Debounce Divider = 32.
Definition: clk.h:79
CLK_RTC_DIV_32
Real Time Clock Divider = 32.
Definition: clk.h:103
CLK_GPIO_DB_DIV_16
GPIO Clock Debounce Divider = 16.
Definition: clk.h:78
clk_ext_set_div
int clk_ext_set_div(const clk_ext_div_t div)
Change divider value of external clock.
Definition: clk.c:293
clk_dma_disable
int clk_dma_disable(void)
Disable the DMA clock.
Definition: clk.c:369
CLK_SYS_RTC_OSC
Real Time Clock.
Definition: clk.h:56
CLK_SYS_HYB_OSC_4MHZ
4MHz Hybrid Oscillator Clock.
Definition: clk.h:55
clk_periph_t
clk_periph_t
Peripheral clock register map.
Definition: qm_soc_regs.h:1368
clk_ext_div_t
clk_ext_div_t
External crystal clock divider type.
Definition: clk.h:87
clk_sys_usb_enable
int clk_sys_usb_enable(void)
Enable the USB Clock mode.
Definition: clk.c:356
CLK_GPIO_DB_DIV_8
GPIO Clock Debounce Divider = 8.
Definition: clk.h:77
CLK_RTC_DIV_4
Real Time Clock Divider = 4.
Definition: clk.h:100
CLK_RTC_DIV_2048
Real Time Clock Divider = 2048.
Definition: clk.h:109
CLK_SYS_DIV_1
Clock Divider = 1.
Definition: clk.h:37
CLK_RTC_DIV_8192
Real Time Clock Divider = 8192.
Definition: clk.h:111