version 2.8
GADC

Detailed Description

Module to abstract the very variable ADC interfaces of the underlying systems.

The reason why uGFX has it's own ADC abstraction is because the Chibi-OS drivers are very CPU specific and do not provide a way across all hardware platforms to create periodic ADC conversions. There are also issues with devices with different characteristics or periodic requirements on the same ADC device (but different channels). This layer attempts to solve these problems to provide a architecture neutral API. It also provides extra features such as multi-buffer chaining for high speed ADC sources. It provides one high speed virtual ADC device (eg a microphone) and numerous low speed (less than 100Hz) virtual ADC devices (eg dials, temperature sensors etc). The high speed device has timer based polling to ensure exact conversion periods and a buffer management system. The low speed devices are assumed to be non-critical timing devices and do not have any buffer management. Note that while only one high speed device has been provided it can be used to read multiple physical ADC channels on the one physical ADC device. All callback routines are thread based unlike the Chibi-OS interrupt based routines.

Data Structures

struct  GEventADC_t
 The High Speed ADC event structure. More...
 

Modules

 Driver
 Driver interface for the GADC module.
 

Functions

void gadcHighSpeedInit (uint32_t physdev, uint32_t frequency)
 Initialise the high speed ADC. More...
 
GSourceHandle gadcHighSpeedGetSource (void)
 Turn on sending results to the GEVENT sub-system. More...
 
void gadcHighSpeedSetISRCallback (GADCISRCallbackFunction isrfn)
 Allow retrieving of results from the high speed ADC using an ISR callback. More...
 
void gadcHighSpeedStart (void)
 Start the high speed ADC conversions. More...
 
void gadcHighSpeedStop (void)
 Stop the high speed ADC conversions. More...
 
void gadcLowSpeedGet (uint32_t physdev, adcsample_t *buffer)
 Perform a single low speed ADC conversion. More...
 
bool_t gadcLowSpeedStart (uint32_t physdev, adcsample_t *buffer, GADCCallbackFunction fn, void *param)
 Perform a low speed ADC conversion with callback (in a thread context) More...
 
typedef struct GEventADC_t GEventADC
 The High Speed ADC event structure. More...
 
GDataBuffergadcHighSpeedGetData (delaytime_t ms)
 Get a filled buffer from the ADC. More...
 

GADC Optional Sizing Parameters

#define GADC_MAX_HIGH_SPEED_SAMPLERATE   44000
 The maximum GADC sample rate. More...
 

Typedefs

typedef void(* GADCCallbackFunction) (adcsample_t *buffer, void *param)
 A callback function (executed in a thread context) for a low speed conversion. More...
 
typedef void(* GADCISRCallbackFunction) (void)
 A callback function (executed in an ISR context) for a high speed conversion. More...
 

Function Documentation

GDataBuffer* gadcHighSpeedGetData ( delaytime_t  ms)

Get a filled buffer from the ADC.

Returns
A GDataBuffer pointer or NULL if the timeout is exceeded
Parameters
[in]msThe maximum amount of time in milliseconds to wait for data if some is not currently available.
Note
After processing the data, your application must return the buffer to the free-list so that it can be used again. This can be done using gfxBufferRelease().
A buffer may be returned to the free-list before you have finished processing it provided you finish processing it before GADC re-uses it. This is useful when RAM usage is critical to reduce the number of buffers required. It works before the free list is a FIFO queue and therefore buffers are kept in the queue as long as possible before they are re-used.
The function ending with "I" is the interrupt class function.
Function Class:
Normal API, this function can be invoked by regular system threads.
GSourceHandle gadcHighSpeedGetSource ( void  )

Turn on sending results to the GEVENT sub-system.

Returns a GSourceHandle to listen for GEVENT_ADC events.

Note
The high speed ADC will not use the GEVENT system unless this is called first. This saves processing time if the application does not want to use the GEVENT sub-system for the high speed ADC. Once turned on it can only be turned off by calling gadcHighSpeedInit() again.
The high speed ADC is capable of signalling via this method, an ISR callback and a binary semaphore at the same time.
Returns
The GSourceHandle
Function Class:
Normal API, this function can be invoked by regular system threads.
void gadcHighSpeedInit ( uint32_t  physdev,
uint32_t  frequency 
)

Initialise the high speed ADC.

Initialises but does not start the conversions.

Parameters
[in]physdevA value passed to describe which physical ADC devices/channels to use.
[in]frequencyThe frequency to create ADC conversions
Note
If the high speed ADC is running it will be stopped. The Event subsystem is disconnected from the high speed ADC and any binary semaphore event is forgotten.
ChibiOS ONLY: Due to a bug in ChibiOS each buffer on the free-list must contain an even number of samples and for multi-channel devices it must hold a number of samples that is evenly divisible by 2 times the number of active channels.
The physdev parameter may be used to turn on more than one ADC channel. Each channel is then interleaved into the provided buffer. Make sure your buffers all hold a number of samples evenly divisible by the number of active channels. As an example, if physdev turns on 2 devices then the buffer contains alternate device samples and the buffer must contain multiples of 2 samples. The exact meaning of physdev is hardware dependent.
While the high speed ADC is running, low speed conversions can only occur at the frequency of the high speed events. Thus if high speed events are being created at 50Hz (eg 100 samples/buffer, frequency = 5kHz) then the maximum frequency for low speed conversions will be 50Hz.
Only a single sample format is supported - that provided by the GADC driver. That sample format applies to both high speed and low speed sampling.
Function Class:
Normal API, this function can be invoked by regular system threads.
void gadcHighSpeedSetISRCallback ( GADCISRCallbackFunction  isrfn)

Allow retrieving of results from the high speed ADC using an ISR callback.

Parameters
[in]isrfnThe callback function (called in an ISR context).
Note
Passing a NULL for isrfn will turn off signalling via this method as will calling gadcHighSpeedInit().
The high speed ADC is capable of signalling via this method, a blocked thread and the GEVENT sub-system at the same time.
Function Class:
Normal API, this function can be invoked by regular system threads.
void gadcHighSpeedStart ( void  )

Start the high speed ADC conversions.

Precondition
It must have been initialised first with gadcHighSpeedInit()
Function Class:
Normal API, this function can be invoked by regular system threads.
void gadcHighSpeedStop ( void  )

Stop the high speed ADC conversions.

Function Class:
Normal API, this function can be invoked by regular system threads.
void gadcLowSpeedGet ( uint32_t  physdev,
adcsample_t *  buffer 
)

Perform a single low speed ADC conversion.

Blocks until the conversion is complete

Precondition
This should not be called from within a GTimer callback as this routine blocks until the conversion is ready.
Parameters
[in]physdevA value passed to describe which physical ADC devices/channels to use.
[in]bufferThe static buffer to put the ADC samples into.
Note
This may take a while to complete if the high speed ADC is running as the conversion is interleaved with the high speed ADC conversions on a buffer completion.
The result buffer must be large enough to store one sample per device described by the 'physdev' parameter.
Specifying more than one device in physdev is possible but discouraged as the calculations to ensure the high speed ADC correctness will be incorrect. Symptoms from over-running the high speed ADC include high speed device stalling or samples being lost.
Function Class:
Normal API, this function can be invoked by regular system threads.
bool_t gadcLowSpeedStart ( uint32_t  physdev,
adcsample_t *  buffer,
GADCCallbackFunction  fn,
void *  param 
)

Perform a low speed ADC conversion with callback (in a thread context)

Returns FALSE if internal memory allocation fails

Parameters
[in]physdevA value passed to describe which physical ADC devices/channels to use.
[in]bufferThe static buffer to put the ADC samples into.
[in]fnThe callback function to call when the conversion is complete.
[in]paramA parameter to pass to the callback function.
Returns
FALSE if no free low speed ADC slots.
Note
This may be safely called from within a GTimer callback.
The callback may take a while to occur if the high speed ADC is running as the conversion is interleaved with the high speed ADC conversions on a buffer completion.
The result buffer must be large enough to store one sample per device described by the 'physdev' parameter.
Specifying more than one device in physdev is possible but discouraged as the calculations to ensure the high speed ADC correctness will be incorrect. Symptoms from over-running the high speed ADC include high speed samples being lost.
Function Class:
Normal API, this function can be invoked by regular system threads.

Macro Definition Documentation

#define GADC_MAX_HIGH_SPEED_SAMPLERATE   44000

The maximum GADC sample rate.

Defaults to 44000

Note
This value must be less than half the maximum sample rate allowed by the CPU. This is to ensure there is time between high speed samples to perform low speed device sampling.

Definition at line 37 of file gadc_options.h.

Typedef Documentation

typedef void(* GADCCallbackFunction) (adcsample_t *buffer, void *param)

A callback function (executed in a thread context) for a low speed conversion.

Definition at line 86 of file gadc.h.

typedef void(* GADCISRCallbackFunction) (void)

A callback function (executed in an ISR context) for a high speed conversion.

Definition at line 91 of file gadc.h.

typedef struct GEventADC_t GEventADC

The High Speed ADC event structure.