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

- Main Page
- Modules
- Data Structures
- Files

- File List

qm_adc.h
1 /*
2 * {% copyright %}
3 */
4
5 #ifndef __QM_ADC_H__
6 #define __QM_ADC_H__
7
8 #include "qm_common.h"
9 #include "qm_soc_regs.h"
10
11 #if (QUARK_D2000)
12
13 /**
14 * Analog to Digital Converter (ADC).
15 *
16 * @defgroup groupADC Quark D2000 ADC
17 * @{
18 */
19
20 /**
21 * ADC sample size type.
22 */
23 typedef uint16_t qm_adc_sample_t;
24
25 /**
26 * ADC calibration type.
27 */
28 typedef uint8_t qm_adc_calibration_t;
29
30 typedef enum {
31 QM_ADC_IDLE, /**< ADC idle. */
32 QM_ADC_COMPLETE, /**< ADC transfer complete. */
33 QM_ADC_OVERFLOW, /**< ADC FIFO overflow error. */
34 } qm_adc_status_t;
35
36 /**
37 * ADC resolution type.
38 */
39 typedef enum {
40 QM_ADC_RES_6_BITS, /**< 6-bit mode. */
41 QM_ADC_RES_8_BITS, /**< 8-bit mode. */
42 QM_ADC_RES_10_BITS, /**< 10-bit mode. */
43 QM_ADC_RES_12_BITS /**< 12-bit mode. */
44 } qm_adc_resolution_t;
45
46 /**
47 * ADC operating mode type.
48 */
49 typedef enum {
50 QM_ADC_MODE_DEEP_PWR_DOWN, /**< Deep power down mode. */
51 QM_ADC_MODE_PWR_DOWN, /**< Power down mode. */
52 QM_ADC_MODE_STDBY, /**< Standby mode. */
53 QM_ADC_MODE_NORM_CAL, /**< Normal mode, with calibration. */
54 QM_ADC_MODE_NORM_NO_CAL /**< Normal mode, no calibration. */
55 } qm_adc_mode_t;
56
57 /**
58 * ADC channels type.
59 */
60 typedef enum {
61 QM_ADC_CH_0, /**< ADC Channel 0. */
62 QM_ADC_CH_1, /**< ADC Channel 1. */
63 QM_ADC_CH_2, /**< ADC Channel 2. */
64 QM_ADC_CH_3, /**< ADC Channel 3. */
65 QM_ADC_CH_4, /**< ADC Channel 4. */
66 QM_ADC_CH_5, /**< ADC Channel 5. */
67 QM_ADC_CH_6, /**< ADC Channel 6. */
68 QM_ADC_CH_7, /**< ADC Channel 7. */
69 QM_ADC_CH_8, /**< ADC Channel 8. */
70 QM_ADC_CH_9, /**< ADC Channel 9. */
71 QM_ADC_CH_10, /**< ADC Channel 10. */
72 QM_ADC_CH_11, /**< ADC Channel 11. */
73 QM_ADC_CH_12, /**< ADC Channel 12. */
74 QM_ADC_CH_13, /**< ADC Channel 13. */
75 QM_ADC_CH_14, /**< ADC Channel 14. */
76 QM_ADC_CH_15, /**< ADC Channel 15. */
77 QM_ADC_CH_16, /**< ADC Channel 16. */
78 QM_ADC_CH_17, /**< ADC Channel 17. */
79 QM_ADC_CH_18 /**< ADC Channel 18. */
80 } qm_adc_channel_t;
81
82 /**
83 * ADC interrupt callback source.
84 */
85 typedef enum {
86 QM_ADC_TRANSFER, /**< Transfer complete or error callback. */
87 QM_ADC_MODE_CHANGED, /**< Mode change complete callback. */
88 QM_ADC_CAL_COMPLETE, /**< Calibration complete callback. */
89 } qm_adc_cb_source_t;
90
91 /**
92 * ADC configuration type.
93 */
94 typedef struct {
95 /**
96 * Sample interval in ADC clock cycles, defines the period to wait
97 * between the start of each sample and can be in the range
98 * [(resolution+2) - 255].
99 */
100 uint8_t window;
101 qm_adc_resolution_t resolution; /**< 12, 10, 8, 6-bit resolution. */
102 } qm_adc_config_t;
103
104 /**
105 * ADC transfer type.
106 */
107 typedef struct {
108 qm_adc_channel_t *ch; /**< Channel sequence array (1-32 channels). */
109 uint8_t ch_len; /**< Number of channels in the above array. */
110 qm_adc_sample_t *samples; /**< Array to store samples. */
111 uint32_t samples_len; /**< Length of sample array. */
112
113 /**
114 * Transfer callback.
115 *
116 * Called when a conversion is performed or an error is detected.
117 *
118 * @param[in] data The callback user data.
119 * @param[in] error 0 on success.
120 * Negative @ref errno for possible error codes.
121 * @param[in] status ADC status.
122 * @param[in] source Interrupt callback source.
123 */
124 void (*callback)(void *data, int error, qm_adc_status_t status,
125 qm_adc_cb_source_t source);
126 void *callback_data; /**< Callback user data. */
127 } qm_adc_xfer_t;
128
129 /**
130 * Switch operating mode of ADC.
131 *
132 * This call is blocking.
133 *
134 * @param[in] adc Which ADC to enable.
135 * @param[in] mode ADC operating mode.
136 *
137 * @return Standard errno return type for QMSI.
138 * @retval 0 on success.
139 * @retval Negative @ref errno for possible error codes.
140 */
141 int qm_adc_set_mode(const qm_adc_t adc, const qm_adc_mode_t mode);
142
143 /**
144 * Switch operating mode of ADC.
145 *
146 * This call is non-blocking and will call the user callback on completion.
147 *
148 * @param[in] adc Which ADC to enable.
149 * @param[in] mode ADC operating mode.
150 * @param[in] callback Callback called on completion.
151 * @param[in] callback_data The callback user data.
152 *
153 * @return Standard errno return type for QMSI.
154 * @retval 0 on success.
155 * @retval Negative @ref errno for possible error codes.
156 */
157 int qm_adc_irq_set_mode(const qm_adc_t adc, const qm_adc_mode_t mode,
158 void (*callback)(void *data, int error,
159 qm_adc_status_t status,
160 qm_adc_cb_source_t source),
161 void *callback_data);
162
163 /**
164 * Calibrate the ADC.
165 *
166 * It is necessary to calibrate if it is intended to use Normal Mode With
167 * Calibration. The calibration must be performed if the ADC is used for the
168 * first time or has been in deep power down mode. This call is blocking.
169 *
170 * @param[in] adc Which ADC to calibrate.
171 *
172 * @return Standard errno return type for QMSI.
173 * @retval 0 on success.
174 * @retval Negative @ref errno for possible error codes.
175 */
176 int qm_adc_calibrate(const qm_adc_t adc);
177
178 /**
179 * Calibrate the ADC.
180 *
181 * It is necessary to calibrate if it is intended to use Normal Mode With
182 * Calibration. The calibration must be performed if the ADC is used for the
183 * first time or has been in deep power down mode. This call is non-blocking
184 * and will call the user callback on completion.
185 *
186 * @param[in] adc Which ADC to calibrate.
187 * @param[in] callback Callback called on completion.
188 * @param[in] callback_data The callback user data.
189 *
190 * @return Standard errno return type for QMSI.
191 * @retval 0 on success.
192 * @retval Negative @ref errno for possible error codes.
193 */
194 int qm_adc_irq_calibrate(const qm_adc_t adc,
195 void (*callback)(void *data, int error,
196 qm_adc_status_t status,
197 qm_adc_cb_source_t source),
198 void *callback_data);
199
200 /**
201 * Set ADC calibration data.
202 *
203 * @param[in] adc Which ADC to set calibration for.
204 * @param[in] cal Calibration data.
205 *
206 * @return Standard errno return type for QMSI.
207 * @retval 0 on success.
208 * @retval Negative @ref errno for possible error codes.
209 */
210 int qm_adc_set_calibration(const qm_adc_t adc, const qm_adc_calibration_t cal);
211
212 /**
213 * Get the current calibration data for an ADC.
214 *
215 * @param[in] adc Which ADC to get calibration for.
216 * @param[out] cal Calibration data. This must not be NULL.
217 *
218 * @return Standard errno return type for QMSI.
219 * @retval 0 on success.
220 * @retval Negative @ref errno for possible error codes.
221 */
222 int qm_adc_get_calibration(const qm_adc_t adc, qm_adc_calibration_t *const cal);
223
224 /**
225 * Set ADC configuration.
226 *
227 * This sets the sample window and resolution.
228 *
229 * @param[in] adc Which ADC to configure.
230 * @param[in] cfg ADC configuration. This must not be NULL.
231 *
232 * @return Standard errno return type for QMSI.
233 * @retval 0 on success.
234 * @retval Negative @ref errno for possible error codes.
235 */
236 int qm_adc_set_config(const qm_adc_t adc, const qm_adc_config_t *const cfg);
237
238 /**
239 * Synchronously read values from the ADC.
240 *
241 * This blocking call can read 1-32 ADC values into the array provided.
242 *
243 * @param[in] adc Which ADC to read.
244 * @param[in,out] xfer Channel and sample info. This must not be NULL.
245 * @param[out] status Get status of the ADC device.
246 *
247 * @return Standard errno return type for QMSI.
248 * @retval 0 on success.
249 * @retval Negative @ref errno for possible error codes.
250 */
251 int qm_adc_convert(const qm_adc_t adc, qm_adc_xfer_t *const xfer,
252 qm_adc_status_t *const status);
253
254 /**
255 * Asynchronously read values from the ADC.
256 *
257 * This is a non-blocking call and will call the user provided callback after
258 * the requested number of samples have been converted.
259 *
260 * @param[in] adc Which ADC to read.
261 * @param[in,out] xfer Channel sample and callback info. This must not be NULL.
262 *
263 * @return Standard errno return type for QMSI.
264 * @retval 0 on success.
265 * @retval Negative @ref errno for possible error codes.
266 */
267 int qm_adc_irq_convert(const qm_adc_t adc, qm_adc_xfer_t *const xfer);
268
269 /**
270 * @}
271 */
272 #endif /* QUARK_D2000 */
273
274 #endif /* __QM_ADC_H__ */
qm_adc_mode_t
qm_adc_mode_t
ADC operating mode type.
Definition: qm_adc.h:49
qm_adc_xfer_t::ch
qm_adc_channel_t * ch
Channel sequence array (1-32 channels).
Definition: qm_adc.h:108
QM_ADC_CH_16
ADC Channel 16.
Definition: qm_adc.h:77
QM_ADC_COMPLETE
ADC transfer complete.
Definition: qm_adc.h:32
qm_adc_config_t::resolution
qm_adc_resolution_t resolution
12, 10, 8, 6-bit resolution.
Definition: qm_adc.h:101
QM_ADC_CH_7
ADC Channel 7.
Definition: qm_adc.h:68
qm_adc_xfer_t
ADC transfer type.
Definition: qm_adc.h:107
QM_ADC_CH_12
ADC Channel 12.
Definition: qm_adc.h:73
qm_adc_irq_set_mode
int qm_adc_irq_set_mode(const qm_adc_t adc, const qm_adc_mode_t mode, void(*callback)(void *data, int error, qm_adc_status_t status, qm_adc_cb_source_t source), void *callback_data)
Switch operating mode of ADC.
Definition: qm_adc.c:302
qm_adc_irq_calibrate
int qm_adc_irq_calibrate(const qm_adc_t adc, void(*callback)(void *data, int error, qm_adc_status_t status, qm_adc_cb_source_t source), void *callback_data)
Calibrate the ADC.
Definition: qm_adc.c:220
qm_adc_get_calibration
int qm_adc_get_calibration(const qm_adc_t adc, qm_adc_calibration_t *const cal)
Get the current calibration data for an ADC.
Definition: qm_adc.c:261
QM_ADC_CH_18
ADC Channel 18.
Definition: qm_adc.h:79
qm_adc_t
qm_adc_t
Number of ADC controllers.
Definition: qm_soc_regs.h:1066
qm_adc_status_t
qm_adc_status_t
Definition: qm_adc.h:30
QM_ADC_CH_9
ADC Channel 9.
Definition: qm_adc.h:70
QM_ADC_CH_4
ADC Channel 4.
Definition: qm_adc.h:65
QM_ADC_CH_15
ADC Channel 15.
Definition: qm_adc.h:76
QM_ADC_CH_0
ADC Channel 0.
Definition: qm_adc.h:61
QM_ADC_CAL_COMPLETE
Calibration complete callback.
Definition: qm_adc.h:88
QM_ADC_MODE_CHANGED
Mode change complete callback.
Definition: qm_adc.h:87
qm_adc_cb_source_t
qm_adc_cb_source_t
ADC interrupt callback source.
Definition: qm_adc.h:85
qm_adc_xfer_t::ch_len
uint8_t ch_len
Number of channels in the above array.
Definition: qm_adc.h:109
QM_ADC_CH_10
ADC Channel 10.
Definition: qm_adc.h:71
qm_adc_xfer_t::samples_len
uint32_t samples_len
Length of sample array.
Definition: qm_adc.h:111
QM_ADC_MODE_DEEP_PWR_DOWN
Deep power down mode.
Definition: qm_adc.h:50
qm_adc_xfer_t::callback_data
void * callback_data
Callback user data.
Definition: qm_adc.h:126
QM_ADC_RES_6_BITS
6-bit mode.
Definition: qm_adc.h:40
qm_adc_irq_convert
int qm_adc_irq_convert(const qm_adc_t adc, qm_adc_xfer_t *const xfer)
Asynchronously read values from the ADC.
Definition: qm_adc.c:391
QM_ADC_CH_11
ADC Channel 11.
Definition: qm_adc.h:72
qm_adc_convert
int qm_adc_convert(const qm_adc_t adc, qm_adc_xfer_t *const xfer, qm_adc_status_t *const status)
Synchronously read values from the ADC.
Definition: qm_adc.c:345
QM_ADC_CH_14
ADC Channel 14.
Definition: qm_adc.h:75
QM_ADC_TRANSFER
Transfer complete or error callback.
Definition: qm_adc.h:86
qm_adc_config_t
ADC configuration type.
Definition: qm_adc.h:94
QM_ADC_CH_8
ADC Channel 8.
Definition: qm_adc.h:69
QM_ADC_RES_8_BITS
8-bit mode.
Definition: qm_adc.h:41
QM_ADC_CH_5
ADC Channel 5.
Definition: qm_adc.h:66
QM_ADC_MODE_STDBY
Standby mode.
Definition: qm_adc.h:52
qm_adc_set_config
int qm_adc_set_config(const qm_adc_t adc, const qm_adc_config_t *const cfg)
Set ADC configuration.
Definition: qm_adc.c:329
QM_ADC_RES_10_BITS
10-bit mode.
Definition: qm_adc.h:42
qm_adc_xfer_t::samples
qm_adc_sample_t * samples
Array to store samples.
Definition: qm_adc.h:110
qm_adc_calibrate
int qm_adc_calibrate(const qm_adc_t adc)
Calibrate the ADC.
Definition: qm_adc.c:204
QM_ADC_CH_3
ADC Channel 3.
Definition: qm_adc.h:64
qm_adc_set_mode
int qm_adc_set_mode(const qm_adc_t adc, const qm_adc_mode_t mode)
Switch operating mode of ADC.
Definition: qm_adc.c:271
qm_adc_sample_t
uint16_t qm_adc_sample_t
ADC sample size type.
Definition: qm_adc.h:23
QM_ADC_IDLE
ADC idle.
Definition: qm_adc.h:31
QM_ADC_OVERFLOW
ADC FIFO overflow error.
Definition: qm_adc.h:33
qm_adc_calibration_t
uint8_t qm_adc_calibration_t
ADC calibration type.
Definition: qm_adc.h:28
QM_ADC_CH_6
ADC Channel 6.
Definition: qm_adc.h:67
qm_adc_set_calibration
int qm_adc_set_calibration(const qm_adc_t adc, const qm_adc_calibration_t cal)
Set ADC calibration data.
Definition: qm_adc.c:242
QM_ADC_CH_1
ADC Channel 1.
Definition: qm_adc.h:62
QM_ADC_RES_12_BITS
12-bit mode.
Definition: qm_adc.h:43
qm_adc_resolution_t
qm_adc_resolution_t
ADC resolution type.
Definition: qm_adc.h:39
qm_adc_config_t::window
uint8_t window
Sample interval in ADC clock cycles, defines the period to wait between the start of each sample and ...
Definition: qm_adc.h:100
QM_ADC_MODE_NORM_CAL
Normal mode, with calibration.
Definition: qm_adc.h:53
QM_ADC_CH_2
ADC Channel 2.
Definition: qm_adc.h:63
qm_adc_channel_t
qm_adc_channel_t
ADC channels type.
Definition: qm_adc.h:60
QM_ADC_CH_13
ADC Channel 13.
Definition: qm_adc.h:74
QM_ADC_CH_17
ADC Channel 17.
Definition: qm_adc.h:78
QM_ADC_MODE_NORM_NO_CAL
Normal mode, no calibration.
Definition: qm_adc.h:54
QM_ADC_MODE_PWR_DOWN
Power down mode.
Definition: qm_adc.h:51