ugfx/include/gadc/lld/gadc_lld.h
2013-07-21 22:20:37 +02:00

191 lines
6.3 KiB
C

/*
* This file is subject to the terms of the GFX License. If a copy of
* the license was not distributed with this file, you can obtain one at:
*
* http://ugfx.org/license.html
*/
/**
* @file include/gadc/lld/gadc_lld.h
* @brief GADC - Periodic ADC driver header file.
*
* @defgroup Driver Driver
* @ingroup GADC
* @{
*/
#ifndef _GADC_LLD_H
#define _GADC_LLD_H
#include "gfx.h"
#if GFX_USE_GADC || defined(__DOXYGEN__)
/*===========================================================================*/
/* Type definitions */
/*===========================================================================*/
/**
* @brief The structure passed to start a timer conversion
* @note We use the structure instead of parameters purely to save
* interrupt stack space which is very limited in some platforms.
* @{
*/
typedef struct GadcLldTimerData_t {
uint32_t physdev; /* @< A value passed to describe which physical ADC devices/channels to use. */
adcsample_t *buffer; /* @< The static buffer to put the ADC samples into. */
size_t count; /* @< The number of conversions to do before doing a callback and stopping the ADC. */
bool_t now; /* @< Trigger the first conversion now rather than waiting for the first timer interrupt (if possible) */
} GadcLldTimerData;
/* @} */
/**
* @brief The structure passed to start a non-timer conversion
* @note We use the structure instead of parameters purely to save
* interrupt stack space which is very limited in some platforms.
* @{
*/
typedef struct GadcLldNonTimerData_t {
uint32_t physdev; /* @< A value passed to describe which physical ADC devices/channels to use. */
adcsample_t *buffer; /* @< The static buffer to put the ADC samples into. */
} GadcLldNonTimerData;
/* @} */
/**
* @brief These routines are the callbacks that the driver uses.
* @details Defined in the high level GADC code.
*
* @notapi
* @{
*/
/**
* @param[in] adcp The ADC driver
* @param[in] buffer The sample buffer
* @param[in] n The amount of samples
*/
extern void GADC_ISR_CompleteI(ADCDriver *adcp, adcsample_t *buffer, size_t n);
/**
* @param[in] adcp The ADC driver
* @param[in] err ADC error
*/
extern void GADC_ISR_ErrorI(ADCDriver *adcp, adcerror_t err);
/**
* @}
*/
/**
* @brief This can be incremented by the low level driver if a timer interrupt is missed.
* @details Defined in the high level GADC code.
*
* @notapi
*/
extern volatile bool_t GADC_Timer_Missed;
/*===========================================================================*/
/* External declarations. */
/*===========================================================================*/
#ifdef __cplusplus
extern "C" {
#endif
/**
* @brief Initialise the driver
*
* @api
*/
void gadc_lld_init(void);
/**
* @brief Get the number of samples in a conversion.
* @details Calculates and returns the number of samples per conversion for the specified physdev.
*
* @note A physdev describing a mono device would return 1, a stereo device would return 2.
* For most ADC's physdev is a bitmap so it is only a matter of counting the bits.
*
* @param[in] physdev A value passed to describe which physical ADC devices/channels to use.
*
* @return Number of samples of the convesion
* @api
*/
size_t gadc_lld_samples_per_conversion(uint32_t physdev);
/**
* @brief Start a periodic timer for high frequency conversions.
*
* @param[in] physdev A value passed to describe which physical ADC devices/channels to use.
* @param[in] frequency The frequency to create ADC conversions
*
* @note The exact meaning of physdev is hardware dependent. It describes the channels
* the will be used later on when a "timer" conversion is actually scheduled.
* @note It is assumed that the timer is capable of free-running even when the ADC
* is stopped or doing something else.
* @details When a timer interrupt occurs a conversion should start if these is a "timer" conversion
* active.
* @note If the ADC is stopped, doesn't have a "timer" conversion active or is currently executing
* a non-timer conversion then the interrupt can be ignored other than (optionally) incrementing
* the GADC_Timer_Missed variable.
*
* @api
*/
void gadc_lld_start_timer(uint32_t physdev, uint32_t frequency);
/**
* @brief Stop the periodic timer for high frequency conversions.
* @details Also stops any current "timer" conversion (but not a current "non-timer" conversion).
*
* @param[in] physdev A value passed to describe which physical ADC devices/channels in use.
*
* @note The exact meaning of physdev is hardware dependent.
*
* @api
*/
void gadc_lld_stop_timer(uint32_t physdev);
/**
* @brief Start a "timer" conversion.
* @details Starts a series of conversions triggered by the timer.
*
* @param[in] pgtd Contains the parameters for the timer conversion.
*
* @note The exact meaning of physdev is hardware dependent. It is likely described in the
* drivers gadc_lld_config.h
* @note Some versions of ChibiOS actually call the callback function more than once, once
* at the half-way point and once on completion. The high level code handles this.
* @note The driver should call @p GADC_ISR_CompleteI() when it completes the operation
* (or at the half-way point), or @p GAD_ISR_ErrorI() on an error.
* @note The high level code ensures that this is not called while a non-timer conversion is in
* progress
*
* @iclass
*/
void gadc_lld_adc_timerI(GadcLldTimerData *pgtd);
/**
* @brief Start a "non-timer" conversion.
* @details Starts a single conversion now.
*
* @param[in] pgntd Contains the parameters for the non-timer conversion.
*
* @note The exact meaning of physdev is hardware dependent. It is likely described in the
* drivers gadc_lld_config.h
* @note The driver should call @p GADC_ISR_CompleteI() when it completes the operation
* or @p GAD_ISR_ErrorI() on an error.
* @note The high level code ensures that this is not called while a timer conversion is in
* progress
*
* @iclass
*/
void gadc_lld_adc_nontimerI(GadcLldNonTimerData *pgntd);
#ifdef __cplusplus
}
#endif
#endif /* GFX_USE_GADC */
#endif /* _GADC_LLD_H */
/** @} */