ChibiOS/HAL
7.0.3
|
Generic ADC Driver. More...
![]() |
Generic ADC Driver.
This module implements a generic ADC (Analog to Digital Converter) driver supporting a variety of buffer and conversion modes.
HAL_USE_ADC
option must be enabled in halconf.h
.The driver implements a state machine internally, not all the driver functionalities can be used in any moment, any transition not explicitly shown in the following diagram has to be considered an error and shall be captured by an assertion (if enabled).
The ADC driver is quite complex, an explanation of the terminology and of the operational details follows.
The ADCConversionGroup
is the objects that specifies a physical conversion operation. This structure contains some standard fields and several implementation-dependent fields.
The standard fields define the CG mode, the number of channels belonging to the CG and the optional callbacks.
The implementation-dependent fields specify the physical ADC operation mode, the analog channels belonging to the group and any other implementation-specific setting. Usually the extra fields just mirror the physical ADC registers, please refer to the vendor's MCU Reference Manual for details about the available settings. Details are also available into the documentation of the ADC low level drivers and in the various sample applications.
The driver supports several conversion modes:
The driver is able to invoke callbacks during the conversion process. A callback is invoked when the operation has been completed or, in circular mode, when the buffer has been filled and the operation is restarted. In circular mode a callback is also invoked when the buffer is half filled.
The "half filled" and "filled" callbacks in circular mode allow to implement "streaming processing" of the sampled data, while the driver is busy filling one half of the buffer the application can process the other half, this allows for continuous interleaved operations.
The driver is not thread safe for performance reasons, if you need to access the ADC bus from multiple threads then use the adcAcquireBus()
and adcReleaseBus()
APIs in order to gain exclusive access.
Macros | |
#define | adc_lld_driver_fields |
Low level fields of the ADC driver structure. More... | |
#define | adc_lld_config_fields |
Low level fields of the ADC configuration structure. More... | |
#define | adc_lld_configuration_group_fields |
Low level fields of the ADC configuration structure. More... | |
ADC configuration options | |
#define | ADC_USE_WAIT TRUE |
Enables synchronous APIs. More... | |
#define | ADC_USE_MUTUAL_EXCLUSION TRUE |
Enables the adcAcquireBus() and adcReleaseBus() APIs. More... | |
Macro Functions | |
#define | adcIsBufferComplete(adcp) ((bool)((adcp)->state == ADC_COMPLETE)) |
Buffer state. More... | |
Low level driver helper macros | |
#define | _adc_reset_i(adcp) osalThreadResumeI(&(adcp)->thread, MSG_RESET) |
Resumes a thread waiting for a conversion completion. More... | |
#define | _adc_reset_s(adcp) osalThreadResumeS(&(adcp)->thread, MSG_RESET) |
Resumes a thread waiting for a conversion completion. More... | |
#define | _adc_wakeup_isr(adcp) |
Wakes up the waiting thread. More... | |
#define | _adc_timeout_isr(adcp) |
Wakes up the waiting thread with a timeout message. More... | |
#define | _adc_isr_half_code(adcp) |
Common ISR code, half buffer event. More... | |
#define | _adc_isr_full_code(adcp) |
Common ISR code, full buffer event. More... | |
#define | _adc_isr_error_code(adcp, err) |
Common ISR code, error event. More... | |
PLATFORM configuration options | |
#define | PLATFORM_ADC_USE_ADC1 FALSE |
ADC1 driver enable switch. More... | |
Typedefs | |
typedef struct hal_adc_driver | ADCDriver |
Type of a structure representing an ADC driver. More... | |
typedef struct hal_adc_config | ADCConfig |
Type of a structure representing an ADC driver configuration. More... | |
typedef struct hal_adc_configuration_group | ADCConversionGroup |
Conversion group configuration structure. More... | |
typedef void(* | adccallback_t) (ADCDriver *adcp) |
Type of an ADC notification callback. More... | |
typedef void(* | adcerrorcallback_t) (ADCDriver *adcp, adcerror_t err) |
Type of an ADC error callback. More... | |
typedef uint16_t | adcsample_t |
ADC sample data type. More... | |
typedef uint16_t | adc_channels_num_t |
Channels number in a conversion group. More... | |
Data Structures | |
struct | hal_adc_configuration_group |
Conversion group configuration structure. More... | |
struct | hal_adc_config |
Driver configuration structure. More... | |
struct | hal_adc_driver |
Structure representing an ADC driver. More... | |
Functions | |
void | adcInit (void) |
ADC Driver initialization. More... | |
void | adcObjectInit (ADCDriver *adcp) |
Initializes the standard part of a ADCDriver structure. More... | |
void | adcStart (ADCDriver *adcp, const ADCConfig *config) |
Configures and activates the ADC peripheral. More... | |
void | adcStop (ADCDriver *adcp) |
Deactivates the ADC peripheral. More... | |
void | adcStartConversion (ADCDriver *adcp, const ADCConversionGroup *grpp, adcsample_t *samples, size_t depth) |
Starts an ADC conversion. More... | |
void | adcStartConversionI (ADCDriver *adcp, const ADCConversionGroup *grpp, adcsample_t *samples, size_t depth) |
Starts an ADC conversion. More... | |
void | adcStopConversion (ADCDriver *adcp) |
Stops an ongoing conversion. More... | |
void | adcStopConversionI (ADCDriver *adcp) |
Stops an ongoing conversion. More... | |
msg_t | adcConvert (ADCDriver *adcp, const ADCConversionGroup *grpp, adcsample_t *samples, size_t depth) |
Performs an ADC conversion. More... | |
void | adcAcquireBus (ADCDriver *adcp) |
Gains exclusive access to the ADC peripheral. More... | |
void | adcReleaseBus (ADCDriver *adcp) |
Releases exclusive access to the ADC peripheral. More... | |
void | adc_lld_init (void) |
Low level ADC driver initialization. More... | |
void | adc_lld_start (ADCDriver *adcp) |
Configures and activates the ADC peripheral. More... | |
void | adc_lld_stop (ADCDriver *adcp) |
Deactivates the ADC peripheral. More... | |
void | adc_lld_start_conversion (ADCDriver *adcp) |
Starts an ADC conversion. More... | |
void | adc_lld_stop_conversion (ADCDriver *adcp) |
Stops an ongoing conversion. More... | |
Enumerations |
Variables | |
ADCDriver | ADCD1 |
ADC1 driver identifier. More... | |
#define ADC_USE_WAIT TRUE |
#define ADC_USE_MUTUAL_EXCLUSION TRUE |
Enables the adcAcquireBus()
and adcReleaseBus()
APIs.
#define adcIsBufferComplete | ( | adcp | ) | ((bool)((adcp)->state == ADC_COMPLETE)) |
Buffer state.
[in] | adcp | pointer to the ADCDriver object |
false | if the driver filled/sent the first half of the buffer. |
true | if the driver filled/sent the second half of the buffer. |
#define _adc_reset_i | ( | adcp | ) | osalThreadResumeI(&(adcp)->thread, MSG_RESET) |
Resumes a thread waiting for a conversion completion.
[in] | adcp | pointer to the ADCDriver object |
Definition at line 235 of file hal_adc.h.
Referenced by adcStopConversionI().
#define _adc_reset_s | ( | adcp | ) | osalThreadResumeS(&(adcp)->thread, MSG_RESET) |
Resumes a thread waiting for a conversion completion.
[in] | adcp | pointer to the ADCDriver object |
Definition at line 245 of file hal_adc.h.
Referenced by adcStopConversion().
#define _adc_wakeup_isr | ( | adcp | ) |
Wakes up the waiting thread.
[in] | adcp | pointer to the ADCDriver object |
#define _adc_timeout_isr | ( | adcp | ) |
Wakes up the waiting thread with a timeout message.
[in] | adcp | pointer to the ADCDriver object |
#define _adc_isr_half_code | ( | adcp | ) |
Common ISR code, half buffer event.
This code handles the portable part of the ISR code:
[in] | adcp | pointer to the ADCDriver object |
#define _adc_isr_full_code | ( | adcp | ) |
Common ISR code, full buffer event.
This code handles the portable part of the ISR code:
[in] | adcp | pointer to the ADCDriver object |
#define _adc_isr_error_code | ( | adcp, | |
err | |||
) |
Common ISR code, error event.
This code handles the portable part of the ISR code:
[in] | adcp | pointer to the ADCDriver object |
[in] | err | platform dependent error code |
#define PLATFORM_ADC_USE_ADC1 FALSE |
ADC1 driver enable switch.
If set to TRUE
the support for ADC1 is included.
FALSE
. Definition at line 48 of file hal_adc_lld.h.
#define adc_lld_driver_fields |
Low level fields of the ADC driver structure.
Definition at line 88 of file hal_adc_lld.h.
#define adc_lld_config_fields |
Low level fields of the ADC configuration structure.
Definition at line 95 of file hal_adc_lld.h.
#define adc_lld_configuration_group_fields |
Low level fields of the ADC configuration structure.
Definition at line 102 of file hal_adc_lld.h.
typedef struct hal_adc_driver ADCDriver |
typedef struct hal_adc_config ADCConfig |
typedef struct hal_adc_configuration_group ADCConversionGroup |
Conversion group configuration structure.
This implementation-dependent structure describes a conversion operation.
typedef void(* adccallback_t) (ADCDriver *adcp) |
typedef void(* adcerrorcallback_t) (ADCDriver *adcp, adcerror_t err) |
typedef uint16_t adcsample_t |
ADC sample data type.
Definition at line 63 of file hal_adc_lld.h.
typedef uint16_t adc_channels_num_t |
Channels number in a conversion group.
Definition at line 68 of file hal_adc_lld.h.
enum adcstate_t |
enum adcerror_t |
Possible ADC failure causes.
Enumerator | |
---|---|
ADC_ERR_DMAFAILURE |
DMA operations failure. |
ADC_ERR_OVERFLOW |
ADC overflow condition. |
ADC_ERR_AWD |
Analog watchdog triggered. |
Definition at line 75 of file hal_adc_lld.h.
void adcInit | ( | void | ) |
ADC Driver initialization.
halInit()
, there is no need to explicitly initialize the driver.Definition at line 56 of file hal_adc.c.
References adc_lld_init().
Referenced by halInit().
void adcObjectInit | ( | ADCDriver * | adcp | ) |
Initializes the standard part of a ADCDriver
structure.
[out] | adcp | pointer to the ADCDriver object |
Definition at line 68 of file hal_adc.c.
References ADC_STOP, hal_adc_driver::config, hal_adc_driver::depth, hal_adc_driver::grpp, hal_adc_driver::mutex, osalMutexObjectInit(), hal_adc_driver::samples, hal_adc_driver::state, and hal_adc_driver::thread.
Referenced by adc_lld_init().
Configures and activates the ADC peripheral.
[in] | adcp | pointer to the ADCDriver object |
[in] | config | pointer to the ADCConfig object. Depending on the implementation the value can be NULL . |
Definition at line 95 of file hal_adc.c.
References adc_lld_start(), ADC_READY, ADC_STOP, hal_adc_driver::config, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), and hal_adc_driver::state.
void adcStop | ( | ADCDriver * | adcp | ) |
Deactivates the ADC peripheral.
[in] | adcp | pointer to the ADCDriver object |
Definition at line 115 of file hal_adc.c.
References adc_lld_stop(), ADC_READY, ADC_STOP, hal_adc_driver::config, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), and hal_adc_driver::state.
void adcStartConversion | ( | ADCDriver * | adcp, |
const ADCConversionGroup * | grpp, | ||
adcsample_t * | samples, | ||
size_t | depth | ||
) |
Starts an ADC conversion.
Starts an asynchronous conversion operation.
[in] | adcp | pointer to the ADCDriver object |
[in] | grpp | pointer to a ADCConversionGroup object |
[out] | samples | pointer to the samples buffer |
[in] | depth | buffer depth (matrix rows number). The buffer depth must be one or an even number. |
Definition at line 147 of file hal_adc.c.
References adcStartConversionI(), osalSysLock(), and osalSysUnlock().
void adcStartConversionI | ( | ADCDriver * | adcp, |
const ADCConversionGroup * | grpp, | ||
adcsample_t * | samples, | ||
size_t | depth | ||
) |
Starts an ADC conversion.
Starts an asynchronous conversion operation.
[in] | adcp | pointer to the ADCDriver object |
[in] | grpp | pointer to a ADCConversionGroup object |
[out] | samples | pointer to the samples buffer |
[in] | depth | buffer depth (matrix rows number). The buffer depth must be one or an even number. |
Definition at line 175 of file hal_adc.c.
References ADC_ACTIVE, ADC_ERROR, adc_lld_start_conversion(), ADC_READY, hal_adc_driver::depth, hal_adc_driver::grpp, osalDbgAssert, osalDbgCheck, osalDbgCheckClassI, hal_adc_driver::samples, and hal_adc_driver::state.
Referenced by adcConvert(), and adcStartConversion().
void adcStopConversion | ( | ADCDriver * | adcp | ) |
Stops an ongoing conversion.
This function stops the currently ongoing conversion and returns the driver in the ADC_READY
state. If there was no conversion being processed then the function does nothing.
[in] | adcp | pointer to the ADCDriver object |
Definition at line 204 of file hal_adc.c.
References _adc_reset_s, ADC_ACTIVE, adc_lld_stop_conversion(), ADC_READY, hal_adc_driver::grpp, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), and hal_adc_driver::state.
void adcStopConversionI | ( | ADCDriver * | adcp | ) |
Stops an ongoing conversion.
This function stops the currently ongoing conversion and returns the driver in the ADC_READY
state. If there was no conversion being processed then the function does nothing.
[in] | adcp | pointer to the ADCDriver object |
Definition at line 230 of file hal_adc.c.
References _adc_reset_i, ADC_ACTIVE, ADC_COMPLETE, adc_lld_stop_conversion(), ADC_READY, hal_adc_driver::grpp, osalDbgAssert, osalDbgCheck, osalDbgCheckClassI, and hal_adc_driver::state.
msg_t adcConvert | ( | ADCDriver * | adcp, |
const ADCConversionGroup * | grpp, | ||
adcsample_t * | samples, | ||
size_t | depth | ||
) |
Performs an ADC conversion.
Performs a synchronous conversion operation.
[in] | adcp | pointer to the ADCDriver object |
[in] | grpp | pointer to a ADCConversionGroup object |
[out] | samples | pointer to the samples buffer |
[in] | depth | buffer depth (matrix rows number). The buffer depth must be one or an even number. |
MSG_OK | Conversion finished. |
MSG_RESET | The conversion has been stopped using acdStopConversion() or acdStopConversionI() , the result buffer may contain incorrect data. |
MSG_TIMEOUT | The conversion has been stopped because an hardware error. |
Definition at line 271 of file hal_adc.c.
References adcStartConversionI(), osalDbgAssert, osalSysLock(), osalSysUnlock(), osalThreadSuspendS(), and hal_adc_driver::thread.
void adcAcquireBus | ( | ADCDriver * | adcp | ) |
Gains exclusive access to the ADC peripheral.
This function tries to gain ownership to the ADC bus, if the bus is already being used then the invoking thread is queued.
ADC_USE_MUTUAL_EXCLUSION
must be enabled.[in] | adcp | pointer to the ADCDriver object |
Definition at line 298 of file hal_adc.c.
References hal_adc_driver::mutex, osalDbgCheck, and osalMutexLock().
void adcReleaseBus | ( | ADCDriver * | adcp | ) |
Releases exclusive access to the ADC peripheral.
ADC_USE_MUTUAL_EXCLUSION
must be enabled.[in] | adcp | pointer to the ADCDriver object |
Definition at line 314 of file hal_adc.c.
References hal_adc_driver::mutex, osalDbgCheck, and osalMutexUnlock().
void adc_lld_init | ( | void | ) |
Low level ADC driver initialization.
Definition at line 65 of file hal_adc_lld.c.
References adcObjectInit().
Referenced by adcInit().
void adc_lld_start | ( | ADCDriver * | adcp | ) |
Configures and activates the ADC peripheral.
[in] | adcp | pointer to the ADCDriver object |
Definition at line 80 of file hal_adc_lld.c.
References ADC_STOP, and hal_adc_driver::state.
Referenced by adcStart().
void adc_lld_stop | ( | ADCDriver * | adcp | ) |
Deactivates the ADC peripheral.
[in] | adcp | pointer to the ADCDriver object |
Definition at line 101 of file hal_adc_lld.c.
References ADC_READY, and hal_adc_driver::state.
Referenced by adcStop().
void adc_lld_start_conversion | ( | ADCDriver * | adcp | ) |
Starts an ADC conversion.
[in] | adcp | pointer to the ADCDriver object |
Definition at line 122 of file hal_adc_lld.c.
Referenced by adcStartConversionI().
void adc_lld_stop_conversion | ( | ADCDriver * | adcp | ) |
Stops an ongoing conversion.
[in] | adcp | pointer to the ADCDriver object |
Definition at line 134 of file hal_adc_lld.c.
Referenced by adcStopConversion(), and adcStopConversionI().
ADCDriver ADCD1 |
ADC1 driver identifier.
Definition at line 41 of file hal_adc_lld.c.