Intel® Quark™ Microcontroller Software Interface  1.4.0
Intel® Quark™ Microcontroller BSP
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. */
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. */
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. */
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. */
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. */
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. */
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
ADC operating mode type.
Definition: qm_adc.h:49
qm_adc_channel_t * ch
Channel sequence array (1-32 channels).
Definition: qm_adc.h:108
ADC Channel 16.
Definition: qm_adc.h:77
ADC transfer complete.
Definition: qm_adc.h:32
qm_adc_resolution_t resolution
12, 10, 8, 6-bit resolution.
Definition: qm_adc.h:101
ADC Channel 7.
Definition: qm_adc.h:68
ADC transfer type.
Definition: qm_adc.h:107
ADC Channel 12.
Definition: qm_adc.h:73
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
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
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
ADC Channel 18.
Definition: qm_adc.h:79
qm_adc_t
Number of ADC controllers.
Definition: qm_soc_regs.h:1066
qm_adc_status_t
Definition: qm_adc.h:30
ADC Channel 9.
Definition: qm_adc.h:70
ADC Channel 4.
Definition: qm_adc.h:65
ADC Channel 15.
Definition: qm_adc.h:76
ADC Channel 0.
Definition: qm_adc.h:61
Calibration complete callback.
Definition: qm_adc.h:88
Mode change complete callback.
Definition: qm_adc.h:87
qm_adc_cb_source_t
ADC interrupt callback source.
Definition: qm_adc.h:85
uint8_t ch_len
Number of channels in the above array.
Definition: qm_adc.h:109
ADC Channel 10.
Definition: qm_adc.h:71
uint32_t samples_len
Length of sample array.
Definition: qm_adc.h:111
Deep power down mode.
Definition: qm_adc.h:50
void * callback_data
Callback user data.
Definition: qm_adc.h:126
6-bit mode.
Definition: qm_adc.h:40
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
ADC Channel 11.
Definition: qm_adc.h:72
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
ADC Channel 14.
Definition: qm_adc.h:75
Transfer complete or error callback.
Definition: qm_adc.h:86
ADC configuration type.
Definition: qm_adc.h:94
ADC Channel 8.
Definition: qm_adc.h:69
8-bit mode.
Definition: qm_adc.h:41
ADC Channel 5.
Definition: qm_adc.h:66
Standby mode.
Definition: qm_adc.h:52
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
10-bit mode.
Definition: qm_adc.h:42
qm_adc_sample_t * samples
Array to store samples.
Definition: qm_adc.h:110
int qm_adc_calibrate(const qm_adc_t adc)
Calibrate the ADC.
Definition: qm_adc.c:204
ADC Channel 3.
Definition: qm_adc.h:64
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
uint16_t qm_adc_sample_t
ADC sample size type.
Definition: qm_adc.h:23
ADC idle.
Definition: qm_adc.h:31
ADC FIFO overflow error.
Definition: qm_adc.h:33
uint8_t qm_adc_calibration_t
ADC calibration type.
Definition: qm_adc.h:28
ADC Channel 6.
Definition: qm_adc.h:67
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
ADC Channel 1.
Definition: qm_adc.h:62
12-bit mode.
Definition: qm_adc.h:43
qm_adc_resolution_t
ADC resolution type.
Definition: qm_adc.h:39
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
Normal mode, with calibration.
Definition: qm_adc.h:53
ADC Channel 2.
Definition: qm_adc.h:63
qm_adc_channel_t
ADC channels type.
Definition: qm_adc.h:60
ADC Channel 13.
Definition: qm_adc.h:74
ADC Channel 17.
Definition: qm_adc.h:78
Normal mode, no calibration.
Definition: qm_adc.h:54
Power down mode.
Definition: qm_adc.h:51