ChibiOS/HAL  7.0.3
ADC Driver

Generic ADC Driver. More...

Collaboration diagram for ADC Driver:

Detailed Description

Generic ADC Driver.

This module implements a generic ADC (Analog to Digital Converter) driver supporting a variety of buffer and conversion modes.

Precondition
In order to use the ADC driver the HAL_USE_ADC option must be enabled in halconf.h.

Driver State Machine

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).

dot_inline_dotgraph_1.png

ADC Operations

The ADC driver is quite complex, an explanation of the terminology and of the operational details follows.

ADC Conversion Groups

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.

ADC Conversion Modes

The driver supports several conversion modes:

ADC Callbacks

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...
 

Macro Definition Documentation

#define ADC_USE_WAIT   TRUE

Enables synchronous APIs.

Note
Disabling this option saves both code and data space.

Definition at line 47 of file hal_adc.h.

#define ADC_USE_MUTUAL_EXCLUSION   TRUE

Enables the adcAcquireBus() and adcReleaseBus() APIs.

Note
Disabling this option saves both code and data space.

Definition at line 55 of file hal_adc.h.

#define adcIsBufferComplete (   adcp)    ((bool)((adcp)->state == ADC_COMPLETE))

Buffer state.

Note
This function is meant to be called from the ADC callback only.
Parameters
[in]adcppointer to the ADCDriver object
Returns
The buffer state.
Return values
falseif the driver filled/sent the first half of the buffer.
trueif the driver filled/sent the second half of the buffer.
Function Class:Special function, this function has special requirements see the notes.

Definition at line 220 of file hal_adc.h.

#define _adc_reset_i (   adcp)    osalThreadResumeI(&(adcp)->thread, MSG_RESET)

Resumes a thread waiting for a conversion completion.

Parameters
[in]adcppointer to the ADCDriver object
Function Class:Not an API, this function is for internal use only.

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.

Parameters
[in]adcppointer to the ADCDriver object
Function Class:Not an API, this function is for internal use only.

Definition at line 245 of file hal_adc.h.

Referenced by adcStopConversion().

#define _adc_wakeup_isr (   adcp)
Value:
{ \
osalThreadResumeI(&(adcp)->thread, MSG_OK); \
}
static void osalSysLockFromISR(void)
Enters a critical zone from ISR context.
Definition: osal.h:550
static void osalSysUnlockFromISR(void)
Leaves a critical zone from ISR context.
Definition: osal.h:560
void osalThreadResumeI(thread_reference_t *trp, msg_t msg)
Wakes up a thread waiting on a thread reference object.
Definition: osal.c:230

Wakes up the waiting thread.

Parameters
[in]adcppointer to the ADCDriver object
Function Class:Not an API, this function is for internal use only.

Definition at line 255 of file hal_adc.h.

#define _adc_timeout_isr (   adcp)
Value:
{ \
osalThreadResumeI(&(adcp)->thread, MSG_TIMEOUT); \
}
static void osalSysLockFromISR(void)
Enters a critical zone from ISR context.
Definition: osal.h:550
static void osalSysUnlockFromISR(void)
Leaves a critical zone from ISR context.
Definition: osal.h:560
void osalThreadResumeI(thread_reference_t *trp, msg_t msg)
Wakes up a thread waiting on a thread reference object.
Definition: osal.c:230

Wakes up the waiting thread with a timeout message.

Parameters
[in]adcppointer to the ADCDriver object
Function Class:Not an API, this function is for internal use only.

Definition at line 268 of file hal_adc.h.

#define _adc_isr_half_code (   adcp)
Value:
{ \
if ((adcp)->grpp->end_cb != NULL) { \
(adcp)->grpp->end_cb(adcp); \
} \
}

Common ISR code, half buffer event.

This code handles the portable part of the ISR code:

  • Callback invocation.
Note
This macro is meant to be used in the low level drivers implementation only.
Parameters
[in]adcppointer to the ADCDriver object
Function Class:Not an API, this function is for internal use only.

Definition at line 293 of file hal_adc.h.

#define _adc_isr_full_code (   adcp)
Value:
{ \
if ((adcp)->grpp->circular) { \
/* Callback handling.*/ \
if ((adcp)->grpp->end_cb != NULL) { \
(adcp)->state = ADC_COMPLETE; \
(adcp)->grpp->end_cb(adcp); \
if ((adcp)->state == ADC_COMPLETE) { \
(adcp)->state = ADC_ACTIVE; \
} \
} \
} \
else { \
/* End conversion.*/ \
if ((adcp)->grpp->end_cb != NULL) { \
(adcp)->state = ADC_COMPLETE; \
(adcp)->grpp->end_cb(adcp); \
if ((adcp)->state == ADC_COMPLETE) { \
(adcp)->state = ADC_READY; \
(adcp)->grpp = NULL; \
} \
} \
else { \
(adcp)->state = ADC_READY; \
(adcp)->grpp = NULL; \
} \
} \
}
#define _adc_wakeup_isr(adcp)
Wakes up the waiting thread.
Definition: hal_adc.h:255
void adc_lld_stop_conversion(ADCDriver *adcp)
Stops an ongoing conversion.
Definition: hal_adc_lld.c:134

Common ISR code, full buffer event.

This code handles the portable part of the ISR code:

  • Callback invocation.
  • Waiting thread wakeup, if any.
  • Driver state transitions.
Note
This macro is meant to be used in the low level drivers implementation only.
Parameters
[in]adcppointer to the ADCDriver object
Function Class:Not an API, this function is for internal use only.

Definition at line 313 of file hal_adc.h.

#define _adc_isr_error_code (   adcp,
  err 
)
Value:
{ \
if ((adcp)->grpp->error_cb != NULL) { \
(adcp)->state = ADC_ERROR; \
(adcp)->grpp->error_cb(adcp, err); \
if ((adcp)->state == ADC_ERROR) \
(adcp)->state = ADC_READY; \
(adcp)->grpp = NULL; \
} \
else { \
(adcp)->state = ADC_READY; \
(adcp)->grpp = NULL; \
} \
}
#define _adc_timeout_isr(adcp)
Wakes up the waiting thread with a timeout message.
Definition: hal_adc.h:268
void adc_lld_stop_conversion(ADCDriver *adcp)
Stops an ongoing conversion.
Definition: hal_adc_lld.c:134

Common ISR code, error event.

This code handles the portable part of the ISR code:

  • Callback invocation.
  • Waiting thread timeout signaling, if any.
  • Driver state transitions.
Note
This macro is meant to be used in the low level drivers implementation only.
Parameters
[in]adcppointer to the ADCDriver object
[in]errplatform dependent error code
Function Class:Not an API, this function is for internal use only.

Definition at line 358 of file hal_adc.h.

#define PLATFORM_ADC_USE_ADC1   FALSE

ADC1 driver enable switch.

If set to TRUE the support for ADC1 is included.

Note
The default is FALSE.

Definition at line 48 of file hal_adc_lld.h.

#define adc_lld_driver_fields
Value:
/* Dummy field, it is not needed.*/ \
uint32_t dummy

Low level fields of the ADC driver structure.

Definition at line 88 of file hal_adc_lld.h.

#define adc_lld_config_fields
Value:
/* Dummy configuration, it is not needed.*/ \
uint32_t dummy

Low level fields of the ADC configuration structure.

Definition at line 95 of file hal_adc_lld.h.

#define adc_lld_configuration_group_fields
Value:
/* Dummy configuration, it is not needed.*/ \
uint32_t dummy

Low level fields of the ADC configuration structure.

Definition at line 102 of file hal_adc_lld.h.

Typedef Documentation

typedef struct hal_adc_driver ADCDriver

Type of a structure representing an ADC driver.

Definition at line 82 of file hal_adc.h.

typedef struct hal_adc_config ADCConfig

Type of a structure representing an ADC driver configuration.

Definition at line 87 of file hal_adc.h.

Conversion group configuration structure.

This implementation-dependent structure describes a conversion operation.

Note
The use of this configuration structure requires knowledge of STM32 ADC cell registers interface, please refer to the STM32 reference manual for details.

Definition at line 97 of file hal_adc.h.

typedef void(* adccallback_t) (ADCDriver *adcp)

Type of an ADC notification callback.

Parameters
[in]adcppointer to the ADCDriver object triggering the

Definition at line 108 of file hal_adc.h.

typedef void(* adcerrorcallback_t) (ADCDriver *adcp, adcerror_t err)

Type of an ADC error callback.

Parameters
[in]adcppointer to the ADCDriver object triggering the callback
[in]errADC error code

Definition at line 117 of file hal_adc.h.

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.

Enumeration Type Documentation

enum adcstate_t

Driver state machine possible states.

Enumerator
ADC_UNINIT 

Not initialized.

ADC_STOP 

Stopped.

ADC_READY 

Ready.

ADC_ACTIVE 

Converting.

ADC_COMPLETE 

Conversion complete.

ADC_ERROR 

Conversion error.

Definition at line 70 of file hal_adc.h.

enum adcerror_t

Possible ADC failure causes.

Note
Error codes are architecture dependent and should not relied upon.
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.

Function Documentation

void adcInit ( void  )

ADC Driver initialization.

Note
This function is implicitly invoked by halInit(), there is no need to explicitly initialize the driver.
Function Class:Initializer, this function just initializes an object and can be invoked before the kernel is initialized.

Definition at line 56 of file hal_adc.c.

References adc_lld_init().

Referenced by halInit().

Here is the call graph for this function:

void adcObjectInit ( ADCDriver adcp)

Initializes the standard part of a ADCDriver structure.

Parameters
[out]adcppointer to the ADCDriver object
Function Class:Initializer, this function just initializes an object and can be invoked before the kernel is initialized.

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().

Here is the call graph for this function:

void adcStart ( ADCDriver adcp,
const ADCConfig config 
)

Configures and activates the ADC peripheral.

Parameters
[in]adcppointer to the ADCDriver object
[in]configpointer to the ADCConfig object. Depending on the implementation the value can be NULL.
Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

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.

Here is the call graph for this function:

void adcStop ( ADCDriver adcp)

Deactivates the ADC peripheral.

Parameters
[in]adcppointer to the ADCDriver object
Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

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.

Here is the call graph for this function:

void adcStartConversion ( ADCDriver adcp,
const ADCConversionGroup grpp,
adcsample_t samples,
size_t  depth 
)

Starts an ADC conversion.

Starts an asynchronous conversion operation.

Note
The buffer is organized as a matrix of M*N elements where M is the channels number configured into the conversion group and N is the buffer depth. The samples are sequentially written into the buffer with no gaps.
Parameters
[in]adcppointer to the ADCDriver object
[in]grpppointer to a ADCConversionGroup object
[out]samplespointer to the samples buffer
[in]depthbuffer depth (matrix rows number). The buffer depth must be one or an even number.
Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 147 of file hal_adc.c.

References adcStartConversionI(), osalSysLock(), and osalSysUnlock().

Here is the call graph for this function:

void adcStartConversionI ( ADCDriver adcp,
const ADCConversionGroup grpp,
adcsample_t samples,
size_t  depth 
)

Starts an ADC conversion.

Starts an asynchronous conversion operation.

Postcondition
The callbacks associated to the conversion group will be invoked on buffer fill and error events.
Note
The buffer is organized as a matrix of M*N elements where M is the channels number configured into the conversion group and N is the buffer depth. The samples are sequentially written into the buffer with no gaps.
Parameters
[in]adcppointer to the ADCDriver object
[in]grpppointer to a ADCConversionGroup object
[out]samplespointer to the samples buffer
[in]depthbuffer depth (matrix rows number). The buffer depth must be one or an even number.
Function Class:This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

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().

Here is the call graph for this function:

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.

Parameters
[in]adcppointer to the ADCDriver object
Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

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.

Here is the call graph for this function:

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.

Parameters
[in]adcppointer to the ADCDriver object
Function Class:This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

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.

Here is the call graph for this function:

msg_t adcConvert ( ADCDriver adcp,
const ADCConversionGroup grpp,
adcsample_t samples,
size_t  depth 
)

Performs an ADC conversion.

Performs a synchronous conversion operation.

Note
The buffer is organized as a matrix of M*N elements where M is the channels number configured into the conversion group and N is the buffer depth. The samples are sequentially written into the buffer with no gaps.
Parameters
[in]adcppointer to the ADCDriver object
[in]grpppointer to a ADCConversionGroup object
[out]samplespointer to the samples buffer
[in]depthbuffer depth (matrix rows number). The buffer depth must be one or an even number.
Returns
The operation result.
Return values
MSG_OKConversion finished.
MSG_RESETThe conversion has been stopped using acdStopConversion() or acdStopConversionI(), the result buffer may contain incorrect data.
MSG_TIMEOUTThe conversion has been stopped because an hardware error.
Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 271 of file hal_adc.c.

References adcStartConversionI(), osalDbgAssert, osalSysLock(), osalSysUnlock(), osalThreadSuspendS(), and hal_adc_driver::thread.

Here is the call graph for this function:

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.

Precondition
In order to use this function the option ADC_USE_MUTUAL_EXCLUSION must be enabled.
Parameters
[in]adcppointer to the ADCDriver object
Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 298 of file hal_adc.c.

References hal_adc_driver::mutex, osalDbgCheck, and osalMutexLock().

Here is the call graph for this function:

void adcReleaseBus ( ADCDriver adcp)

Releases exclusive access to the ADC peripheral.

Precondition
In order to use this function the option ADC_USE_MUTUAL_EXCLUSION must be enabled.
Parameters
[in]adcppointer to the ADCDriver object
Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 314 of file hal_adc.c.

References hal_adc_driver::mutex, osalDbgCheck, and osalMutexUnlock().

Here is the call graph for this function:

void adc_lld_init ( void  )

Low level ADC driver initialization.

Function Class:Not an API, this function is for internal use only.

Definition at line 65 of file hal_adc_lld.c.

References adcObjectInit().

Referenced by adcInit().

Here is the call graph for this function:

void adc_lld_start ( ADCDriver adcp)

Configures and activates the ADC peripheral.

Parameters
[in]adcppointer to the ADCDriver object
Function Class:Not an API, this function is for internal use only.

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.

Parameters
[in]adcppointer to the ADCDriver object
Function Class:Not an API, this function is for internal use only.

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.

Parameters
[in]adcppointer to the ADCDriver object
Function Class:Not an API, this function is for internal use only.

Definition at line 122 of file hal_adc_lld.c.

Referenced by adcStartConversionI().

void adc_lld_stop_conversion ( ADCDriver adcp)

Stops an ongoing conversion.

Parameters
[in]adcppointer to the ADCDriver object
Function Class:Not an API, this function is for internal use only.

Definition at line 134 of file hal_adc_lld.c.

Referenced by adcStopConversion(), and adcStopConversionI().

Variable Documentation

ADCDriver ADCD1

ADC1 driver identifier.

Definition at line 41 of file hal_adc_lld.c.