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

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:

One Shot, the driver performs a single group conversion then stops.
Linear Buffer, the driver performs a series of group conversions then stops. This mode is like a one shot conversion repeated N times, the buffer pointer increases after each conversion. The buffer is organized as an S(CG)*N samples matrix, when S(CG) is the conversion group size (number of channels) and N is the buffer depth (number of repeated conversions).
Circular Buffer, much like the linear mode but the operation does not stop when the buffer is filled, it is automatically restarted with the buffer pointer wrapping back to the buffer base.

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.

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

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 uint16_t	adcsample_t
	ADC sample data type. More...

typedef uint16_t	adc_channels_num_t
	Channels number in a conversion group. More...

typedef struct ADCDriver	ADCDriver
	Type of a structure representing an ADC driver. More...

typedef void(*	adccallback_t) (ADCDriver adcp, adcsample_t buffer, size_t n)
	ADC notification callback type. More...

typedef void(*	adcerrorcallback_t) (ADCDriver *adcp, adcerror_t err)
	ADC error callback type. More...

Data Structures
struct	ADCConversionGroup
	Conversion group configuration structure. More...

struct	ADCConfig
	Driver configuration structure. More...

struct	ADCDriver
	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 _adc_reset_i ( adcp ) osalThreadResumeI(&(adcp)->thread, MSG_RESET)

Resumes a thread waiting for a conversion completion.

Parameters

[in] adcp pointer to the ADCDriver object

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

Definition at line 97 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] adcp pointer to the ADCDriver object

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

Definition at line 107 of file hal_adc.h.

Referenced by adcStopConversion().

#define _adc_wakeup_isr ( adcp )

Value:

{                                             \
  osalSysLockFromISR();                                                     \
  osalThreadResumeI(&(adcp)->thread, MSG_OK);                               \
  osalSysUnlockFromISR();                                                   \
}

Wakes up the waiting thread.

Parameters

[in] adcp pointer to the ADCDriver object

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

Definition at line 117 of file hal_adc.h.

#define _adc_timeout_isr ( adcp )

Value:

{                                            \
  osalSysLockFromISR();                                                     \
  osalThreadResumeI(&(adcp)->thread, MSG_TIMEOUT);                          \
  osalSysUnlockFromISR();                                                   \
}

Wakes up the waiting thread with a timeout message.

Parameters

[in] adcp pointer to the ADCDriver object

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

Definition at line 130 of file hal_adc.h.

#define _adc_isr_half_code ( adcp )

Value:

{                                          \
  if ((adcp)->grpp->end_cb != NULL) {                                       \
    (adcp)->grpp->end_cb(adcp, (adcp)->samples, (adcp)->depth / 2);         \
  }                                                                         \
}

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] adcp pointer to the ADCDriver object

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

Definition at line 155 of file hal_adc.h.

#define _adc_isr_full_code ( adcp )

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] adcp pointer to the ADCDriver object

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

Definition at line 175 of file hal_adc.h.

#define _adc_isr_error_code	(	adcp,
		err
	)

Value:

{                                    \
  adc_lld_stop_conversion(adcp);                                            \
  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;                                                    \
  }                                                                         \
  _adc_timeout_isr(adcp);                                                   \
}

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]	adcp	pointer to the `ADCDriver` object
[in]	err	platform dependent error code

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

Definition at line 226 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.

Typedef Documentation

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.

typedef struct ADCDriver ADCDriver

Type of a structure representing an ADC driver.

Definition at line 84 of file hal_adc_lld.h.

typedef void(* adccallback_t) (ADCDriver *adcp, adcsample_t *buffer, size_t n)

ADC notification callback type.

Parameters

[in]	adcp	pointer to the `ADCDriver` object triggering the callback
[in]	buffer	pointer to the most recent samples data
[in]	n	number of buffer rows available starting from `buffer`

Definition at line 94 of file hal_adc_lld.h.

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

ADC error callback type.

Parameters

[in]	adcp	pointer to the `ADCDriver` object triggering the callback
[in]	err	ADC error code

Definition at line 103 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] adcp pointer 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, ADCDriver::config, ADCDriver::depth, ADCDriver::grpp, ADCDriver::mutex, osalMutexObjectInit(), ADCDriver::samples, ADCDriver::state, and ADCDriver::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]	adcp	pointer to the `ADCDriver` object
[in]	config	pointer 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, ADCDriver::config, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), and ADCDriver::state.

Here is the call graph for this function:

void adcStop ( ADCDriver * adcp )

Deactivates the ADC peripheral.

Parameters

[in] adcp pointer 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, ADCDriver::config, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), and ADCDriver::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]	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.

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

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_COMPLETE, ADC_ERROR, adc_lld_start_conversion(), ADC_READY, ADCDriver::depth, ADCDriver::grpp, osalDbgAssert, osalDbgCheck, osalDbgCheckClassI, ADCDriver::samples, and ADCDriver::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] adcp pointer 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 205 of file hal_adc.c.

References _adc_reset_s, ADC_ACTIVE, adc_lld_stop_conversion(), ADC_READY, ADCDriver::grpp, osalDbgAssert, osalDbgCheck, osalSysLock(), osalSysUnlock(), and ADCDriver::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] adcp pointer 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 231 of file hal_adc.c.

References _adc_reset_i, ADC_ACTIVE, ADC_COMPLETE, adc_lld_stop_conversion(), ADC_READY, ADCDriver::grpp, osalDbgAssert, osalDbgCheck, osalDbgCheckClassI, and ADCDriver::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]	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.

Returns: The operation result.

Return values

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.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 272 of file hal_adc.c.

References adcStartConversionI(), osalDbgAssert, osalSysLock(), osalSysUnlock(), osalThreadSuspendS(), and ADCDriver::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] adcp pointer 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 299 of file hal_adc.c.

References ADCDriver::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] adcp pointer 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 315 of file hal_adc.c.

References ADCDriver::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] adcp pointer 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 ADCDriver::state.

Referenced by adcStart().

void adc_lld_stop ( ADCDriver * adcp )

Deactivates the ADC peripheral.

Parameters

[in] adcp pointer 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 ADCDriver::state.

Referenced by adcStop().

void adc_lld_start_conversion ( ADCDriver * adcp )

Starts an ADC conversion.

Parameters

[in] adcp pointer 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] adcp pointer 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.

Detailed Description

Driver State Machine

ADC Operations

ADC Conversion Groups

ADC Conversion Modes

ADC Callbacks

ADC configuration options

Low level driver helper macros

PLATFORM configuration options

Typedefs

Data Structures

Functions

Enumerations

Variables

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation