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

- Main Page
- Modules
- Data Structures
- Files

- File List

qm_ss_adc.h
1 /*
2 * {% copyright %}
3 */
4
5 #ifndef __QM_SS_ADC_H__
6 #define __QM_SS_ADC_H__
7
8 #include "qm_common.h"
9 #include "qm_soc_regs.h"
10 #include "qm_sensor_regs.h"
11
12 /**
13 * Analog to Digital Converter (ADC) for the Sensor Subsystem.
14 *
15 * @defgroup groupSSADC SS ADC
16 * @{
17 */
18
19 /**
20 * SS ADC sample size type.
21 */
22 typedef uint16_t qm_ss_adc_sample_t;
23
24 /**
25 * SS ADC calibration type.
26 */
27 typedef uint8_t qm_ss_adc_calibration_t;
28
29 /**
30 * SS ADC status.
31 */
32 typedef enum {
33 QM_SS_ADC_IDLE = 0x0, /**< ADC idle. */
34 QM_SS_ADC_COMPLETE = 0x1, /**< ADC data available. */
35 QM_SS_ADC_OVERFLOW = 0x2, /**< ADC overflow error. */
36 QM_SS_ADC_UNDERFLOW = 0x4, /**< ADC underflow error. */
37 QM_SS_ADC_SEQERROR = 0x8 /**< ADC sequencer error. */
38 } qm_ss_adc_status_t;
39
40 /**
41 * SS ADC resolution type.
42 */
43 typedef enum {
44 QM_SS_ADC_RES_6_BITS = 0x5, /**< 6-bit mode. */
45 QM_SS_ADC_RES_8_BITS = 0x7, /**< 8-bit mode. */
46 QM_SS_ADC_RES_10_BITS = 0x9, /**< 10-bit mode. */
47 QM_SS_ADC_RES_12_BITS = 0xB /**< 12-bit mode. */
48 } qm_ss_adc_resolution_t;
49
50 /**
51 * SS ADC operating mode type.
52 */
53 typedef enum {
54 QM_SS_ADC_MODE_DEEP_PWR_DOWN, /**< Deep power down mode. */
55 QM_SS_ADC_MODE_PWR_DOWN, /**< Power down mode. */
56 QM_SS_ADC_MODE_STDBY, /**< Standby mode. */
57 QM_SS_ADC_MODE_NORM_CAL, /**< Normal mode, with calibration. */
58 QM_SS_ADC_MODE_NORM_NO_CAL /**< Normal mode, no calibration. */
59 } qm_ss_adc_mode_t;
60
61 /**
62 * SS ADC channels type.
63 */
64 typedef enum {
65 QM_SS_ADC_CH_0, /**< ADC Channel 0. */
66 QM_SS_ADC_CH_1, /**< ADC Channel 1. */
67 QM_SS_ADC_CH_2, /**< ADC Channel 2. */
68 QM_SS_ADC_CH_3, /**< ADC Channel 3. */
69 QM_SS_ADC_CH_4, /**< ADC Channel 4. */
70 QM_SS_ADC_CH_5, /**< ADC Channel 5. */
71 QM_SS_ADC_CH_6, /**< ADC Channel 6. */
72 QM_SS_ADC_CH_7, /**< ADC Channel 7. */
73 QM_SS_ADC_CH_8, /**< ADC Channel 8. */
74 QM_SS_ADC_CH_9, /**< ADC Channel 9. */
75 QM_SS_ADC_CH_10, /**< ADC Channel 10. */
76 QM_SS_ADC_CH_11, /**< ADC Channel 11. */
77 QM_SS_ADC_CH_12, /**< ADC Channel 12. */
78 QM_SS_ADC_CH_13, /**< ADC Channel 13. */
79 QM_SS_ADC_CH_14, /**< ADC Channel 14. */
80 QM_SS_ADC_CH_15, /**< ADC Channel 15. */
81 QM_SS_ADC_CH_16, /**< ADC Channel 16. */
82 QM_SS_ADC_CH_17, /**< ADC Channel 17. */
83 QM_SS_ADC_CH_18 /**< ADC Channel 18. */
84 } qm_ss_adc_channel_t;
85
86 /**
87 * SS ADC interrupt callback source.
88 */
89 typedef enum {
90 QM_SS_ADC_TRANSFER, /**< Transfer complete or error callback. */
91 QM_SS_ADC_MODE_CHANGED, /**< Mode change complete callback. */
92 QM_SS_ADC_CAL_COMPLETE, /**< Calibration complete callback. */
93 } qm_ss_adc_cb_source_t;
94
95 /**
96 * SS ADC configuration type.
97 */
98 typedef struct {
99 /**
100 * Sample interval in ADC clock cycles, defines the period to wait
101 * between the start of each sample and can be in the range
102 * [(resolution+2) - 255].
103 */
104 uint8_t window;
105 qm_ss_adc_resolution_t resolution; /**< 12, 10, 8, 6-bit resolution. */
106 } qm_ss_adc_config_t;
107
108 /**
109 * SS ADC transfer type.
110 */
111 typedef struct {
112 qm_ss_adc_channel_t *ch; /**< Channel sequence array (1-32 channels). */
113 uint8_t ch_len; /**< Number of channels in the above array. */
114 qm_ss_adc_sample_t *samples; /**< Array to store samples. */
115 uint32_t samples_len; /**< Length of sample array. */
116
117 /**
118 * Transfer callback.
119 *
120 * Called when a conversion is performed or an error is detected.
121 *
122 * @param[in] data The callback user data.
123 * @param[in] error 0 on success.
124 * Negative @ref errno for possible error codes.
125 * @param[in] status ADC status.
126 * @param[in] source Interrupt callback source.
127 */
128 void (*callback)(void *data, int error, qm_ss_adc_status_t status,
129 qm_ss_adc_cb_source_t source);
130 void *callback_data; /**< Callback user data. */
131 } qm_ss_adc_xfer_t;
132
133 /**
134 * Switch operating mode of SS ADC.
135 *
136 * This call is blocking.
137 *
138 * @param[in] adc Which ADC to enable.
139 * @param[in] mode ADC operating mode.
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 qm_ss_adc_set_mode(const qm_ss_adc_t adc, const qm_ss_adc_mode_t mode);
146
147 /**
148 * Switch operating mode of SS ADC.
149 *
150 * This call is non-blocking and will call the user callback on completion. An
151 * interrupt will not be generated if the user requests the same mode the ADC
152 * is currently in (default mode on boot is deep power down).
153 *
154 * @param[in] adc Which ADC to enable.
155 * @param[in] mode ADC operating mode.
156 * @param[in] callback Callback called on completion.
157 * @param[in] callback_data The callback user data.
158 *
159 * @return Standard errno return type for QMSI.
160 * @retval 0 on success.
161 * @retval Negative @ref errno for possible error codes.
162 */
163 int qm_ss_adc_irq_set_mode(const qm_ss_adc_t adc, const qm_ss_adc_mode_t mode,
164 void (*callback)(void *data, int error,
165 qm_ss_adc_status_t status,
166 qm_ss_adc_cb_source_t source),
167 void *callback_data);
168
169 /**
170 * Calibrate the SS ADC.
171 *
172 * It is necessary to calibrate if it is intended to use Normal Mode With
173 * Calibration. The calibration must be performed if the ADC is used for the
174 * first time or has been in deep power down mode. This call is blocking.
175 *
176 * @param[in] adc Which ADC to calibrate.
177 *
178 * @return Standard errno return type for QMSI.
179 * @retval 0 on success.
180 * @retval Negative @ref errno for possible error codes.
181 */
182 int qm_ss_adc_calibrate(const qm_ss_adc_t adc);
183
184 /**
185 * Calibrate the SS ADC.
186 *
187 * It is necessary to calibrate if it is intended to use Normal Mode With
188 * Calibration. The calibration must be performed if the ADC is used for the
189 * first time or has been in deep power down mode. This call is non-blocking
190 * and will call the user callback on completion.
191 *
192 * @param[in] adc Which ADC to calibrate.
193 * @param[in] callback Callback called on completion.
194 * @param[in] callback_data The callback user data.
195 *
196 * @return Standard errno return type for QMSI.
197 * @retval 0 on success.
198 * @retval Negative @ref errno for possible error codes.
199 */
200 int qm_ss_adc_irq_calibrate(const qm_ss_adc_t adc,
201 void (*callback)(void *data, int error,
202 qm_ss_adc_status_t status,
203 qm_ss_adc_cb_source_t source),
204 void *callback_data);
205
206 /**
207 * Set SS ADC calibration data.
208 *
209 * @param[in] adc Which ADC to set calibration for.
210 * @param[in] cal Calibration data.
211 *
212 * @return Standard errno return type for QMSI.
213 * @retval 0 on success.
214 * @retval Negative @ref errno for possible error codes.
215 */
216 int qm_ss_adc_set_calibration(const qm_ss_adc_t adc,
217 const qm_ss_adc_calibration_t cal);
218
219 /**
220 * Get the current calibration data for an SS ADC.
221 *
222 * @param[in] adc Which ADC to get calibration for.
223 * @param[out] cal Calibration data. This must not be NULL.
224 *
225 * @return Standard errno return type for QMSI.
226 * @retval 0 on success.
227 * @retval Negative @ref errno for possible error codes.
228 */
229 int qm_ss_adc_get_calibration(const qm_ss_adc_t adc,
230 qm_ss_adc_calibration_t *const cal);
231
232 /**
233 * Set SS ADC configuration.
234 *
235 * This sets the sample window and resolution.
236 *
237 * @param[in] adc Which ADC to configure.
238 * @param[in] cfg ADC configuration. This must not be NULL.
239 *
240 * @return Standard errno return type for QMSI.
241 * @retval 0 on success.
242 * @retval Negative @ref errno for possible error codes.
243 */
244 int qm_ss_adc_set_config(const qm_ss_adc_t adc,
245 const qm_ss_adc_config_t *const cfg);
246
247 /**
248 * Synchronously read values from the ADC.
249 *
250 * This blocking call can read 1-32 ADC values into the array provided.
251 *
252 * @param[in] adc Which ADC to read.
253 * @param[in,out] xfer Channel and sample info. This must not be NULL.
254 * @param[out] status Get status of the adc device.
255 *
256 * @return Standard errno return type for QMSI.
257 * @retval 0 on success.
258 * @retval Negative @ref errno for possible error codes.
259 */
260 int qm_ss_adc_convert(const qm_ss_adc_t adc, qm_ss_adc_xfer_t *const xfer,
261 qm_ss_adc_status_t *const status);
262
263 /**
264 * Asynchronously read values from the SS ADC.
265 *
266 * This is a non-blocking call and will call the user provided callback after
267 * the requested number of samples have been converted.
268 *
269 * @param[in] adc Which ADC to read.
270 * @param[in,out] xfer Channel sample and callback info. This must not be NULL.
271 *
272 * @return Standard errno return type for QMSI.
273 * @retval 0 on success.
274 * @retval Negative @ref errno for possible error codes.
275 */
276 int qm_ss_adc_irq_convert(const qm_ss_adc_t adc, qm_ss_adc_xfer_t *const xfer);
277
278 /**
279 * Save SS ADC context.
280 *
281 * Save the configuration of the specified ADC peripheral before entering sleep.
282 *
283 * Note: Calibration data is not saved with this function. The value of the
284 * ADC_ENA bit in the ADC Control register is also not saved with this function.
285 *
286 * @param[in] adc SS ADC port index.
287 * @param[out] ctx SS ADC context structure. This must not be NULL.
288 *
289 * @return Standard errno return type for QMSI.
290 * @retval 0 on success.
291 * @retval Negative @ref errno for possible error codes.
292 */
293 int qm_ss_adc_save_context(const qm_ss_adc_t adc,
294 qm_ss_adc_context_t *const ctx);
295
296 /**
297 * Restore SS ADC context.
298 *
299 * Restore the configuration of the specified ADC peripheral after exiting
300 * sleep.
301 *
302 * Note: Previous calibration data is not restored with this function, the user
303 * may need to recalibrate the ADC. The user will need to set the ADC_ENA bit
304 * in the ADC Control register as it is initialized to 0.
305 *
306 * @param[in] adc SS ADC port index.
307 * @param[in] ctx SS ADC context structure. This must not be NULL.
308 *
309 * @return Standard errno return type for QMSI.
310 * @retval 0 on success.
311 * @retval Negative @ref errno for possible error codes.
312 */
313 int qm_ss_adc_restore_context(const qm_ss_adc_t adc,
314 const qm_ss_adc_context_t *const ctx);
315
316 /**
317 * @}
318 */
319 #endif /* __QM_ADC_H__ */
qm_ss_adc_xfer_t::samples_len
uint32_t samples_len
Length of sample array.
Definition: qm_ss_adc.h:115
QM_SS_ADC_CH_1
ADC Channel 1.
Definition: qm_ss_adc.h:66
qm_ss_adc_convert
int qm_ss_adc_convert(const qm_ss_adc_t adc, qm_ss_adc_xfer_t *const xfer, qm_ss_adc_status_t *const status)
Synchronously read values from the ADC.
Definition: qm_ss_adc.c:564
QM_SS_ADC_CH_11
ADC Channel 11.
Definition: qm_ss_adc.h:76
QM_SS_ADC_CAL_COMPLETE
Calibration complete callback.
Definition: qm_ss_adc.h:92
qm_ss_adc_cb_source_t
qm_ss_adc_cb_source_t
SS ADC interrupt callback source.
Definition: qm_ss_adc.h:89
QM_SS_ADC_TRANSFER
Transfer complete or error callback.
Definition: qm_ss_adc.h:90
qm_ss_adc_status_t
qm_ss_adc_status_t
SS ADC status.
Definition: qm_ss_adc.h:32
qm_ss_adc_resolution_t
qm_ss_adc_resolution_t
SS ADC resolution type.
Definition: qm_ss_adc.h:43
QM_SS_ADC_RES_12_BITS
12-bit mode.
Definition: qm_ss_adc.h:47
QM_SS_ADC_CH_16
ADC Channel 16.
Definition: qm_ss_adc.h:81
QM_SS_ADC_RES_6_BITS
6-bit mode.
Definition: qm_ss_adc.h:44
QM_SS_ADC_CH_2
ADC Channel 2.
Definition: qm_ss_adc.h:67
qm_ss_adc_irq_set_mode
int qm_ss_adc_irq_set_mode(const qm_ss_adc_t adc, const qm_ss_adc_mode_t mode, void(*callback)(void *data, int error, qm_ss_adc_status_t status, qm_ss_adc_cb_source_t source), void *callback_data)
Switch operating mode of SS ADC.
Definition: qm_ss_adc.c:405
qm_ss_adc_xfer_t::callback_data
void * callback_data
Callback user data.
Definition: qm_ss_adc.h:130
qm_ss_adc_irq_convert
int qm_ss_adc_irq_convert(const qm_ss_adc_t adc, qm_ss_adc_xfer_t *const xfer)
Asynchronously read values from the SS ADC.
Definition: qm_ss_adc.c:638
QM_SS_ADC_CH_13
ADC Channel 13.
Definition: qm_ss_adc.h:78
qm_ss_adc_set_mode
int qm_ss_adc_set_mode(const qm_ss_adc_t adc, const qm_ss_adc_mode_t mode)
Switch operating mode of SS ADC.
Definition: qm_ss_adc.c:361
QM_SS_ADC_MODE_NORM_NO_CAL
Normal mode, no calibration.
Definition: qm_ss_adc.h:58
qm_ss_adc_xfer_t::ch
qm_ss_adc_channel_t * ch
Channel sequence array (1-32 channels).
Definition: qm_ss_adc.h:112
QM_SS_ADC_CH_0
ADC Channel 0.
Definition: qm_ss_adc.h:65
QM_SS_ADC_MODE_CHANGED
Mode change complete callback.
Definition: qm_ss_adc.h:91
QM_SS_ADC_CH_17
ADC Channel 17.
Definition: qm_ss_adc.h:82
qm_ss_adc_mode_t
qm_ss_adc_mode_t
SS ADC operating mode type.
Definition: qm_ss_adc.h:53
qm_ss_adc_xfer_t::samples
qm_ss_adc_sample_t * samples
Array to store samples.
Definition: qm_ss_adc.h:114
qm_ss_adc_t
qm_ss_adc_t
Sensor Subsystem ADC.
Definition: qm_sensor_regs.h:551
QM_SS_ADC_COMPLETE
ADC data available.
Definition: qm_ss_adc.h:34
QM_SS_ADC_CH_7
ADC Channel 7.
Definition: qm_ss_adc.h:72
QM_SS_ADC_CH_3
ADC Channel 3.
Definition: qm_ss_adc.h:68
QM_SS_ADC_CH_12
ADC Channel 12.
Definition: qm_ss_adc.h:77
QM_SS_ADC_SEQERROR
ADC sequencer error.
Definition: qm_ss_adc.h:37
QM_SS_ADC_CH_4
ADC Channel 4.
Definition: qm_ss_adc.h:69
qm_ss_adc_channel_t
qm_ss_adc_channel_t
SS ADC channels type.
Definition: qm_ss_adc.h:64
QM_SS_ADC_OVERFLOW
ADC overflow error.
Definition: qm_ss_adc.h:35
QM_SS_ADC_CH_18
ADC Channel 18.
Definition: qm_ss_adc.h:83
QM_SS_ADC_CH_8
ADC Channel 8.
Definition: qm_ss_adc.h:73
QM_SS_ADC_CH_10
ADC Channel 10.
Definition: qm_ss_adc.h:75
qm_ss_adc_get_calibration
int qm_ss_adc_get_calibration(const qm_ss_adc_t adc, qm_ss_adc_calibration_t *const cal)
Get the current calibration data for an SS ADC.
QM_SS_ADC_RES_8_BITS
8-bit mode.
Definition: qm_ss_adc.h:45
qm_ss_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_ss_adc.h:104
QM_SS_ADC_CH_6
ADC Channel 6.
Definition: qm_ss_adc.h:71
qm_ss_adc_restore_context
int qm_ss_adc_restore_context(const qm_ss_adc_t adc, const qm_ss_adc_context_t *const ctx)
Restore SS ADC context.
Definition: qm_ss_adc.c:712
QM_SS_ADC_CH_5
ADC Channel 5.
Definition: qm_ss_adc.h:70
QM_SS_ADC_MODE_DEEP_PWR_DOWN
Deep power down mode.
Definition: qm_ss_adc.h:54
QM_SS_ADC_MODE_PWR_DOWN
Power down mode.
Definition: qm_ss_adc.h:55
qm_ss_adc_config_t
SS ADC configuration type.
Definition: qm_ss_adc.h:98
qm_ss_adc_context_t
SS ADC context type.
Definition: qm_sensor_regs.h:564
QM_SS_ADC_UNDERFLOW
ADC underflow error.
Definition: qm_ss_adc.h:36
QM_SS_ADC_CH_14
ADC Channel 14.
Definition: qm_ss_adc.h:79
qm_ss_adc_set_calibration
int qm_ss_adc_set_calibration(const qm_ss_adc_t adc, const qm_ss_adc_calibration_t cal)
Set SS ADC calibration data.
QM_SS_ADC_IDLE
ADC idle.
Definition: qm_ss_adc.h:33
qm_ss_adc_save_context
int qm_ss_adc_save_context(const qm_ss_adc_t adc, qm_ss_adc_context_t *const ctx)
Save SS ADC context.
Definition: qm_ss_adc.c:685
qm_ss_adc_irq_calibrate
int qm_ss_adc_irq_calibrate(const qm_ss_adc_t adc, void(*callback)(void *data, int error, qm_ss_adc_status_t status, qm_ss_adc_cb_source_t source), void *callback_data)
Calibrate the SS ADC.
Definition: qm_ss_adc.c:479
QM_SS_ADC_CH_15
ADC Channel 15.
Definition: qm_ss_adc.h:80
qm_ss_adc_xfer_t
SS ADC transfer type.
Definition: qm_ss_adc.h:111
qm_ss_adc_xfer_t::ch_len
uint8_t ch_len
Number of channels in the above array.
Definition: qm_ss_adc.h:113
qm_ss_adc_calibrate
int qm_ss_adc_calibrate(const qm_ss_adc_t adc)
Calibrate the SS ADC.
qm_ss_adc_sample_t
uint16_t qm_ss_adc_sample_t
SS ADC sample size type.
Definition: qm_ss_adc.h:22
QM_SS_ADC_CH_9
ADC Channel 9.
Definition: qm_ss_adc.h:74
QM_SS_ADC_MODE_NORM_CAL
Normal mode, with calibration.
Definition: qm_ss_adc.h:57
QM_SS_ADC_RES_10_BITS
10-bit mode.
Definition: qm_ss_adc.h:46
qm_ss_adc_set_config
int qm_ss_adc_set_config(const qm_ss_adc_t adc, const qm_ss_adc_config_t *const cfg)
Set SS ADC configuration.
Definition: qm_ss_adc.c:335
qm_ss_adc_config_t::resolution
qm_ss_adc_resolution_t resolution
12, 10, 8, 6-bit resolution.
Definition: qm_ss_adc.h:105
QM_SS_ADC_MODE_STDBY
Standby mode.
Definition: qm_ss_adc.h:56
qm_ss_adc_calibration_t
uint8_t qm_ss_adc_calibration_t
SS ADC calibration type.
Definition: qm_ss_adc.h:27