Intel® Quark™ Microcontroller Software Interface  1.4.0
Intel® Quark™ Microcontroller BSP
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. */
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. */
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. */
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. */
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. */
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. */
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. */
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  */
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  */
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  */
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  */
314  const qm_ss_adc_context_t *const ctx);
315 
316 /**
317  * @}
318  */
319 #endif /* __QM_ADC_H__ */
uint32_t samples_len
Length of sample array.
Definition: qm_ss_adc.h:115
ADC Channel 1.
Definition: qm_ss_adc.h:66
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
ADC Channel 11.
Definition: qm_ss_adc.h:76
Calibration complete callback.
Definition: qm_ss_adc.h:92
qm_ss_adc_cb_source_t
SS ADC interrupt callback source.
Definition: qm_ss_adc.h:89
Transfer complete or error callback.
Definition: qm_ss_adc.h:90
qm_ss_adc_status_t
SS ADC status.
Definition: qm_ss_adc.h:32
qm_ss_adc_resolution_t
SS ADC resolution type.
Definition: qm_ss_adc.h:43
12-bit mode.
Definition: qm_ss_adc.h:47
ADC Channel 16.
Definition: qm_ss_adc.h:81
6-bit mode.
Definition: qm_ss_adc.h:44
ADC Channel 2.
Definition: qm_ss_adc.h:67
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
void * callback_data
Callback user data.
Definition: qm_ss_adc.h:130
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
ADC Channel 13.
Definition: qm_ss_adc.h:78
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
Normal mode, no calibration.
Definition: qm_ss_adc.h:58
qm_ss_adc_channel_t * ch
Channel sequence array (1-32 channels).
Definition: qm_ss_adc.h:112
ADC Channel 0.
Definition: qm_ss_adc.h:65
Mode change complete callback.
Definition: qm_ss_adc.h:91
ADC Channel 17.
Definition: qm_ss_adc.h:82
qm_ss_adc_mode_t
SS ADC operating mode type.
Definition: qm_ss_adc.h:53
qm_ss_adc_sample_t * samples
Array to store samples.
Definition: qm_ss_adc.h:114
qm_ss_adc_t
Sensor Subsystem ADC.
ADC data available.
Definition: qm_ss_adc.h:34
ADC Channel 7.
Definition: qm_ss_adc.h:72
ADC Channel 3.
Definition: qm_ss_adc.h:68
ADC Channel 12.
Definition: qm_ss_adc.h:77
ADC sequencer error.
Definition: qm_ss_adc.h:37
ADC Channel 4.
Definition: qm_ss_adc.h:69
qm_ss_adc_channel_t
SS ADC channels type.
Definition: qm_ss_adc.h:64
ADC overflow error.
Definition: qm_ss_adc.h:35
ADC Channel 18.
Definition: qm_ss_adc.h:83
ADC Channel 8.
Definition: qm_ss_adc.h:73
ADC Channel 10.
Definition: qm_ss_adc.h:75
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.
8-bit mode.
Definition: qm_ss_adc.h:45
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
ADC Channel 6.
Definition: qm_ss_adc.h:71
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
ADC Channel 5.
Definition: qm_ss_adc.h:70
Deep power down mode.
Definition: qm_ss_adc.h:54
Power down mode.
Definition: qm_ss_adc.h:55
SS ADC configuration type.
Definition: qm_ss_adc.h:98
SS ADC context type.
ADC underflow error.
Definition: qm_ss_adc.h:36
ADC Channel 14.
Definition: qm_ss_adc.h:79
int qm_ss_adc_set_calibration(const qm_ss_adc_t adc, const qm_ss_adc_calibration_t cal)
Set SS ADC calibration data.
ADC idle.
Definition: qm_ss_adc.h:33
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
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
ADC Channel 15.
Definition: qm_ss_adc.h:80
SS ADC transfer type.
Definition: qm_ss_adc.h:111
uint8_t ch_len
Number of channels in the above array.
Definition: qm_ss_adc.h:113
int qm_ss_adc_calibrate(const qm_ss_adc_t adc)
Calibrate the SS ADC.
uint16_t qm_ss_adc_sample_t
SS ADC sample size type.
Definition: qm_ss_adc.h:22
ADC Channel 9.
Definition: qm_ss_adc.h:74
Normal mode, with calibration.
Definition: qm_ss_adc.h:57
10-bit mode.
Definition: qm_ss_adc.h:46
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_resolution_t resolution
12, 10, 8, 6-bit resolution.
Definition: qm_ss_adc.h:105
Standby mode.
Definition: qm_ss_adc.h:56
uint8_t qm_ss_adc_calibration_t
SS ADC calibration type.
Definition: qm_ss_adc.h:27