1 /*
2 * Copyright (c) 2016, Freescale Semiconductor, Inc.
3 * Copyright 2016-2020 NXP
4 * All rights reserved.
5 *
6 * SPDX-License-Identifier: BSD-3-Clause
7 */
8
9 #ifndef FSL_ADC_H_
10 #define FSL_ADC_H_
11
12 #include "fsl_common.h"
13
14 /*!
15 * @addtogroup adc_12b1msps_sar
16 * @{
17 */
18
19 /*******************************************************************************
20 * Definitions
21 ******************************************************************************/
22 /*! @brief ADC driver version */
23 #define FSL_ADC_DRIVER_VERSION (MAKE_VERSION(2, 0, 4)) /*!< Version 2.0.4. */
24
25 /*!
26 * @brief Converter's status flags.
27 */
28 typedef enum _adc_status_flags
29 {
30 kADC_ConversionActiveFlag = ADC_GS_ADACT_MASK, /*!< Conversion is active,not support w1c. */
31 kADC_CalibrationFailedFlag = ADC_GS_CALF_MASK, /*!< Calibration is failed,support w1c. */
32 kADC_AsynchronousWakeupInterruptFlag =
33 ADC_GS_AWKST_MASK, /*!< Asynchronous wakeup interrupt occurred, support w1c. */
34 } adc_status_flags_t;
35
36 /*!
37 * @brief Reference voltage source.
38 */
39 typedef enum _adc_reference_voltage_source
40 {
41 kADC_ReferenceVoltageSourceAlt0 = 0U, /*!< For external pins pair of VrefH and VrefL. */
42 } adc_reference_voltage_source_t;
43
44 /*!
45 * @brief Sample time duration.
46 */
47 typedef enum _adc_sample_period_mode
48 {
49 /* This group of enumeration is for internal use which is related to register setting. */
50 kADC_SamplePeriod2or12Clocks = 0U, /*!< Long sample 12 clocks or short sample 2 clocks. */
51 kADC_SamplePeriod4or16Clocks = 1U, /*!< Long sample 16 clocks or short sample 4 clocks. */
52 kADC_SamplePeriod6or20Clocks = 2U, /*!< Long sample 20 clocks or short sample 6 clocks. */
53 kADC_SamplePeriod8or24Clocks = 3U, /*!< Long sample 24 clocks or short sample 8 clocks. */
54 /* This group of enumeration is for a public user. */
55 /* For long sample mode. */
56 kADC_SamplePeriodLong12Clcoks = kADC_SamplePeriod2or12Clocks, /*!< Long sample 12 clocks. */
57 kADC_SamplePeriodLong16Clcoks = kADC_SamplePeriod4or16Clocks, /*!< Long sample 16 clocks. */
58 kADC_SamplePeriodLong20Clcoks = kADC_SamplePeriod6or20Clocks, /*!< Long sample 20 clocks. */
59 kADC_SamplePeriodLong24Clcoks = kADC_SamplePeriod8or24Clocks, /*!< Long sample 24 clocks. */
60 /* For short sample mode. */
61 kADC_SamplePeriodShort2Clocks = kADC_SamplePeriod2or12Clocks, /*!< Short sample 2 clocks. */
62 kADC_SamplePeriodShort4Clocks = kADC_SamplePeriod4or16Clocks, /*!< Short sample 4 clocks. */
63 kADC_SamplePeriodShort6Clocks = kADC_SamplePeriod6or20Clocks, /*!< Short sample 6 clocks. */
64 kADC_SamplePeriodShort8Clocks = kADC_SamplePeriod8or24Clocks, /*!< Short sample 8 clocks. */
65 } adc_sample_period_mode_t;
66
67 /*!
68 * @brief Clock source.
69 */
70 typedef enum _adc_clock_source
71 {
72 kADC_ClockSourceIPG = 0U, /*!< Select IPG clock to generate ADCK. */
73 kADC_ClockSourceIPGDiv2 = 1U, /*!< Select IPG clock divided by 2 to generate ADCK. */
74 #if !(defined(FSL_FEATURE_ADC_SUPPORT_ALTCLK_REMOVE) && FSL_FEATURE_ADC_SUPPORT_ALTCLK_REMOVE)
75 kADC_ClockSourceALT = 2U, /*!< Select alternate clock to generate ADCK. */
76 #endif
77 kADC_ClockSourceAD = 3U, /*!< Select Asynchronous clock to generate ADCK. */
78 } adc_clock_source_t;
79
80 /*!
81 * @brief Clock divider for the converter.
82 */
83 typedef enum _adc_clock_drvier
84 {
85 kADC_ClockDriver1 = 0U, /*!< For divider 1 from the input clock to the module. */
86 kADC_ClockDriver2 = 1U, /*!< For divider 2 from the input clock to the module. */
87 kADC_ClockDriver4 = 2U, /*!< For divider 4 from the input clock to the module. */
88 kADC_ClockDriver8 = 3U, /*!< For divider 8 from the input clock to the module. */
89 } adc_clock_driver_t;
90
91 /*!
92 * @brief Converter's resolution.
93 */
94 typedef enum _adc_resolution
95 {
96 kADC_Resolution8Bit = 0U, /*!< Single End 8-bit resolution. */
97 kADC_Resolution10Bit = 1U, /*!< Single End 10-bit resolution. */
98 kADC_Resolution12Bit = 2U, /*!< Single End 12-bit resolution. */
99 } adc_resolution_t;
100
101 /*!
102 * @brief Converter hardware compare mode.
103 */
104 typedef enum _adc_hardware_compare_mode
105 {
106 kADC_HardwareCompareMode0 = 0U, /*!< Compare true if the result is less than the value1. */
107 kADC_HardwareCompareMode1 = 1U, /*!< Compare true if the result is greater than or equal to value1. */
108 kADC_HardwareCompareMode2 = 2U, /*!< Value1 <= Value2, compare true if the result is less than value1 Or
109 the result is Greater than value2.
110 Value1 > Value2, compare true if the result is less than value1 And the
111 result is greater than value2*/
112 kADC_HardwareCompareMode3 = 3U, /*!< Value1 <= Value2, compare true if the result is greater than or equal
113 to value1 And the result is less than or equal to value2.
114 Value1 > Value2, compare true if the result is greater than or equal to
115 value1 Or the result is less than or equal to value2. */
116 } adc_hardware_compare_mode_t;
117
118 /*!
119 * @brief Converter hardware average mode.
120 */
121 typedef enum _adc_hardware_average_mode
122 {
123 kADC_HardwareAverageCount4 = 0U, /*!< For hardware average with 4 samples. */
124 kADC_HardwareAverageCount8 = 1U, /*!< For hardware average with 8 samples. */
125 kADC_HardwareAverageCount16 = 2U, /*!< For hardware average with 16 samples. */
126 kADC_HardwareAverageCount32 = 3U, /*!< For hardware average with 32 samples. */
127 kADC_HardwareAverageDiasable = 4U, /*!< Disable the hardware average function. */
128 } adc_hardware_average_mode_t;
129
130 /*!
131 * @brief Converter configuration.
132 */
133 typedef struct _adc_config
134 {
135 bool enableOverWrite; /*!< Enable the overwriting. */
136 bool enableContinuousConversion; /*!< Enable the continuous conversion mode. */
137 bool enableHighSpeed; /*!< Enable the high-speed mode. */
138 bool enableLowPower; /*!< Enable the low power mode. */
139 bool enableLongSample; /*!< Enable the long sample mode. */
140 bool enableAsynchronousClockOutput; /*!< Enable the asynchronous clock output. */
141 adc_reference_voltage_source_t referenceVoltageSource; /*!< Select the reference voltage source. */
142 adc_sample_period_mode_t samplePeriodMode; /*!< Select the sample period in long sample mode or short mode. */
143 adc_clock_source_t clockSource; /*!< Select the input clock source to generate the internal clock ADCK. */
144 adc_clock_driver_t clockDriver; /*!< Select the divide ratio used by the ADC to generate the internal clock ADCK. */
145 adc_resolution_t resolution; /*!< Select the ADC resolution mode. */
146 } adc_config_t;
147
148 /*!
149 * @brief Converter Offset configuration.
150 */
151 typedef struct _adc_offest_config
152 {
153 bool enableSigned; /*!< if false,The offset value is added with the raw result.
154 if true,The offset value is subtracted from the raw converted value. */
155 uint32_t offsetValue; /*!< User configurable offset value(0-4095). */
156 } adc_offest_config_t;
157
158 /*!
159 * @brief ADC hardware compare configuration.
160 *
161 * In kADC_HardwareCompareMode0, compare true if the result is less than the value1.
162 * In kADC_HardwareCompareMode1, compare true if the result is greater than or equal to value1.
163 * In kADC_HardwareCompareMode2, Value1 <= Value2, compare true if the result is less than value1 Or the result is
164 * Greater than value2.
165 * Value1 > Value2, compare true if the result is less than value1 And the result is
166 * Greater than value2.
167 * In kADC_HardwareCompareMode3, Value1 <= Value2, compare true if the result is greater than or equal to value1 And the
168 * result is less than or equal to value2.
169 * Value1 > Value2, compare true if the result is greater than or equal to value1 Or the
170 * result is less than or equal to value2.
171 */
172 typedef struct _adc_hardware_compare_config
173 {
174 adc_hardware_compare_mode_t hardwareCompareMode; /*!< Select the hardware compare mode.
175 See "adc_hardware_compare_mode_t". */
176 uint16_t value1; /*!< Setting value1(0-4095) for hardware compare mode. */
177 uint16_t value2; /*!< Setting value2(0-4095) for hardware compare mode. */
178 } adc_hardware_compare_config_t;
179
180 /*!
181 * @brief ADC channel conversion configuration.
182 */
183 typedef struct _adc_channel_config
184 {
185 uint32_t channelNumber; /*!< Setting the conversion channel number. The available range is 0-31.
186 See channel connection information for each chip in Reference
187 Manual document. */
188 bool enableInterruptOnConversionCompleted; /*!< Generate an interrupt request once the conversion is completed. */
189 } adc_channel_config_t;
190 /*******************************************************************************
191 * API
192 ******************************************************************************/
193 #if defined(__cplusplus)
194 extern "C" {
195 #endif
196
197 /*!
198 * @name Initialization
199 * @{
200 */
201
202 /*!
203 * @brief Initialize the ADC module.
204 *
205 * @param base ADC peripheral base address.
206 * @param config Pointer to "adc_config_t" structure.
207 */
208 void ADC_Init(ADC_Type *base, const adc_config_t *config);
209
210 /*!
211 * @brief De-initializes the ADC module.
212 *
213 * @param base ADC peripheral base address.
214 */
215 void ADC_Deinit(ADC_Type *base);
216
217 /*!
218 * @brief Gets an available pre-defined settings for the converter's configuration.
219 *
220 * This function initializes the converter configuration structure with available settings. The default values are:
221 * @code
222 * config->enableAsynchronousClockOutput = true;
223 * config->enableOverWrite = false;
224 * config->enableContinuousConversion = false;
225 * config->enableHighSpeed = false;
226 * config->enableLowPower = false;
227 * config->enableLongSample = false;
228 * config->referenceVoltageSource = kADC_ReferenceVoltageSourceAlt0;
229 * config->samplePeriodMode = kADC_SamplePeriod2or12Clocks;
230 * config->clockSource = kADC_ClockSourceAD;
231 * config->clockDriver = kADC_ClockDriver1;
232 * config->resolution = kADC_Resolution12Bit;
233 * @endcode
234 * @param config Pointer to the configuration structure.
235 */
236 void ADC_GetDefaultConfig(adc_config_t *config);
237
238 /*!
239 * @brief Configures the conversion channel.
240 *
241 * This operation triggers the conversion when in software trigger mode. When in hardware trigger mode, this API
242 * configures the channel while the external trigger source helps to trigger the conversion.
243 *
244 * Note that the "Channel Group" has a detailed description.
245 * To allow sequential conversions of the ADC to be triggered by internal peripherals, the ADC has more than one
246 * group of status and control registers, one for each conversion. The channel group parameter indicates which group of
247 * registers are used, for example channel group 0 is for Group A registers and channel group 1 is for Group B
248 * registers. The
249 * channel groups are used in a "ping-pong" approach to control the ADC operation. At any point, only one of
250 * the channel groups is actively controlling ADC conversions. The channel group 0 is used for both software and
251 * hardware
252 * trigger modes. Channel groups 1 and greater indicate potentially multiple channel group registers for
253 * use only in hardware trigger mode. See the chip configuration information in the appropriate MCU reference manual
254 * about the
255 * number of SC1n registers (channel groups) specific to this device. None of the channel groups 1 or greater are used
256 * for software trigger operation. Therefore, writing to these channel groups does not initiate a new conversion.
257 * Updating the channel group 0 while a different channel group is actively controlling a conversion is allowed and
258 * vice versa. Writing any of the channel group registers while that specific channel group is actively controlling a
259 * conversion aborts the current conversion.
260 *
261 * @param base ADC peripheral base address.
262 * @param channelGroup Channel group index.
263 * @param config Pointer to the "adc_channel_config_t" structure for the conversion channel.
264 */
265 void ADC_SetChannelConfig(ADC_Type *base, uint32_t channelGroup, const adc_channel_config_t *config);
266
267 /*!
268 * @brief Gets the conversion value.
269 *
270 * @param base ADC peripheral base address.
271 * @param channelGroup Channel group index.
272 *
273 * @return Conversion value.
274 */
ADC_GetChannelConversionValue(ADC_Type * base,uint32_t channelGroup)275 static inline uint32_t ADC_GetChannelConversionValue(ADC_Type *base, uint32_t channelGroup)
276 {
277 assert(channelGroup < (uint32_t)FSL_FEATURE_ADC_CONVERSION_CONTROL_COUNT);
278
279 return base->R[channelGroup];
280 }
281
282 /*!
283 * @brief Gets the status flags of channel.
284 *
285 * A conversion is completed when the result of the conversion is transferred into the data
286 * result registers. (provided the compare function & hardware averaging is disabled), this is
287 * indicated by the setting of COCOn. If hardware averaging is enabled, COCOn sets only,
288 * if the last of the selected number of conversions is complete. If the compare function is
289 * enabled, COCOn sets and conversion result data is transferred only if the compare
290 * condition is true. If both hardware averaging and compare functions are enabled, then
291 * COCOn sets only if the last of the selected number of conversions is complete and the
292 * compare condition is true.
293 *
294 * @param base ADC peripheral base address.
295 * @param channelGroup Channel group index.
296 *
297 * @return Status flags of channel.return 0 means COCO flag is 0,return 1 means COCOflag is 1.
298 */
ADC_GetChannelStatusFlags(ADC_Type * base,uint32_t channelGroup)299 static inline uint32_t ADC_GetChannelStatusFlags(ADC_Type *base, uint32_t channelGroup)
300 {
301 assert(channelGroup < (uint32_t)FSL_FEATURE_ADC_CONVERSION_CONTROL_COUNT);
302
303 /* If flag is set,return 1,otherwise, return 0. */
304 return (((base->HS) & (1UL << channelGroup)) >> channelGroup);
305 }
306
307 /*!
308 * @brief Automates the hardware calibration.
309 *
310 * This auto calibration helps to adjust the plus/minus side gain automatically.
311 * Execute the calibration before using the converter. Note that the software trigger should be used
312 * during calibration.
313 *
314 * @param base ADC peripheral base address.
315 *
316 * @return Execution status.
317 * @retval kStatus_Success Calibration is done successfully.
318 * @retval kStatus_Fail Calibration has failed.
319 */
320 status_t ADC_DoAutoCalibration(ADC_Type *base);
321
322 /*!
323 * @brief Set user defined offset.
324 *
325 * @param base ADC peripheral base address.
326 * @param config Pointer to "adc_offest_config_t" structure.
327 */
328 void ADC_SetOffsetConfig(ADC_Type *base, const adc_offest_config_t *config);
329
330 /*!
331 * @brief Enables generating the DMA trigger when the conversion is complete.
332 *
333 * @param base ADC peripheral base address.
334 * @param enable Switcher of the DMA feature. "true" means enabled, "false" means not enabled.
335 */
ADC_EnableDMA(ADC_Type * base,bool enable)336 static inline void ADC_EnableDMA(ADC_Type *base, bool enable)
337 {
338 if (enable)
339 {
340 base->GC |= ADC_GC_DMAEN_MASK;
341 }
342 else
343 {
344 base->GC &= ~ADC_GC_DMAEN_MASK;
345 }
346 }
347
348 /*!
349 * @brief Enables the hardware trigger mode.
350 *
351 * @param base ADC peripheral base address.
352 * @param enable Switcher of the trigger mode. "true" means hardware tirgger mode,"false" means software mode.
353 */
354 #if !(defined(FSL_FEATURE_ADC_SUPPORT_HARDWARE_TRIGGER_REMOVE) && FSL_FEATURE_ADC_SUPPORT_HARDWARE_TRIGGER_REMOVE)
ADC_EnableHardwareTrigger(ADC_Type * base,bool enable)355 static inline void ADC_EnableHardwareTrigger(ADC_Type *base, bool enable)
356 {
357 if (enable)
358 {
359 base->CFG |= ADC_CFG_ADTRG_MASK;
360 }
361 else
362 {
363 base->CFG &= ~ADC_CFG_ADTRG_MASK;
364 }
365 }
366 #endif
367
368 /*!
369 * @brief Configures the hardware compare mode.
370 *
371 * The hardware compare mode provides a way to process the conversion result automatically by using hardware. Only the
372 * result
373 * in the compare range is available. To compare the range, see "adc_hardware_compare_mode_t" or the appopriate
374 * reference
375 * manual for more information.
376 *
377 * @param base ADC peripheral base address.
378 * @param config Pointer to "adc_hardware_compare_config_t" structure.
379 *
380 */
381 void ADC_SetHardwareCompareConfig(ADC_Type *base, const adc_hardware_compare_config_t *config);
382
383 /*!
384 * @brief Configures the hardware average mode.
385 *
386 * The hardware average mode provides a way to process the conversion result automatically by using hardware. The
387 * multiple
388 * conversion results are accumulated and averaged internally making them easier to read.
389 *
390 * @param base ADC peripheral base address.
391 * @param mode Setting the hardware average mode. See "adc_hardware_average_mode_t".
392 */
393 void ADC_SetHardwareAverageConfig(ADC_Type *base, adc_hardware_average_mode_t mode);
394
395 /*!
396 * @brief Gets the converter's status flags.
397 *
398 * @param base ADC peripheral base address.
399 *
400 * @return Flags' mask if indicated flags are asserted. See "adc_status_flags_t".
401 */
ADC_GetStatusFlags(ADC_Type * base)402 static inline uint32_t ADC_GetStatusFlags(ADC_Type *base)
403 {
404 return base->GS;
405 }
406
407 /*!
408 * @brief Clears the converter's status falgs.
409 *
410 * @param base ADC peripheral base address.
411 * @param mask Mask value for the cleared flags. See "adc_status_flags_t".
412 */
413 void ADC_ClearStatusFlags(ADC_Type *base, uint32_t mask);
414
415 /*!
416 *@}
417 */
418
419 #if defined(__cplusplus)
420 }
421 #endif
422
423 /*!
424 *@}
425 */
426
427 #endif /* FSL_ADC_H_ */
428
