Data Structures | Macros | Typedefs | Enumerations | Functions
ADCBuf.h File Reference

Detailed Description

Analog to Digital Conversion Buffer (ADCBuf) Input Driver.


Overview

The ADCBuf driver allows you to sample and convert analog signals at a specified frequency. The resulting samples are placed in a buffer provided by the application. The driver can either take N samples once or continuously sample by double-buffering and providing a callback to process each finished buffer.


Usage

This documentation provides a basic usage summary and a set of examples in the form of commented code fragments. Detailed descriptions of the APIs are provided in subsequent sections.

Synopsis

// Import ADCBuf Driver definitions
// Define name for ADCBuf channel index
#define PIEZOMETER_OUT 0
// Create buffer for samples
#define ADCBUFFERSIZE 10
uint16_t buffer[ADCBUFFERSIZE];
uint32_t microvoltBuffer[ADCBUFFERSIZE];
// One time init of ADCBuf driver
// Initialize optional ADCBuf parameters
// Open ADCBuf driver
adcBuf = ADCBuf_open(CONFIG_ADCBUF0, &params);
// Setup conversion structure
ADCBuf_Conversion conversion = {0};
conversion.samplesRequestedCount = ADCBUFFERSIZE;
conversion.sampleBuffer = buffer;
conversion.adcChannel = PIEZOMETER_OUT;
// Start ADCBuf conversion
ADCBuf_convert(adcBuf, &conversion, 1)
// Adjust raw ADC values and convert them to microvolts
ADCBuf_adjustRawValues(handle, buffer, ADCBUFFERSIZE, PIEZOMETER_OUT);
ADCBuf_convertAdjustedToMicroVolts(handle, PIEZOMETER_OUT, buffer,
microvoltBuffer, ADCBUFFERSIZE);
// Close ADCBuf driver
ADCBuf_close(adcbuf);

Examples

Opening an ADCBuf instance

ADCBuf_Handle adcBufHandle;
ADCBuf_Params adcBufParams;
ADCBuf_Params_init(&adcBufParams);
adcBufHandle = ADCBuf_open(0, &adcBufParams);
if (adcBufHandle == NULL)
{
//ADCBuf_open() failed.
while (1) {}
}

Using a blocking conversion

adcbuf = ADCBuf_open(0, &params);
if (adcbuf != NULL)
{
ADCBuf_Conversion conversion = {0};
conversion.adcChannel = PIEZOMETER_OUT;
conversion.sampleBuffer = buffer;
conversion.samplesRequestedCount = ADCBUFFERSIZE;
if (ADCBuf_convert(adcbuf, &conversion, 1) != ADCBuf_STATUS_SUCCESS)
{
// ADCBuf_conver() failed
}
}

Using a callback conversion

// ADCBuf callback function
void adcBufCallbackFxn(ADCBuf_Handle handle, ADCBuf_Conversion *conversion,
void *buffer, uint32_t channel, int_fast16_t status);
main()
{
ADCBuf_Handle adcbuf;
params.callbackFxn = adcBufCallbackFxn;
adcbuf = ADCBuf_open(0, &params);
ADCBuf_Conversion conversion = {0};
conversion.adcChannel = PIEZOMETER_OUT;
conversion.sampleBuffer = buffer;
conversion.samplesRequestedCount = ADCBUFFERSIZE;
if (ADCBuf_convert(adcbuf, &conversion, 1) != ADCBuf_STATUS_SUCCESS)
{
// ADCBuf_convert() failed
}
// Pend on a semaphore
}
void adcBufCallbackFxn(ADCBuf_Handle handle, ADCBuf_Conversion *conversion,
void *buffer, uint32_t channel, int_fast16_t status)
{
// Adjust raw ADC values and convert them to microvolts
ADCBuf_adjustRawValues(handle, buffer, ADCBUFFERSIZE,
channel);
buffer, microvoltBuffer, ADCBUFFERSIZE);
// Post a semaphore
}

Configuration

Refer to the Driver's Configuration section for driver configuration information.


#include <stdint.h>
Include dependency graph for ADCBuf.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  ADCBuf_Conversion
 Defines a conversion to be used with ADCBuf_convert(). More...
 
struct  ADCBuf_Params
 ADCBuf parameters used with ADCBuf_open(). More...
 
struct  ADCBuf_FxnTable
 The definition of an ADCBuf function table that contains the required set of functions to control a specific ADC driver implementation. More...
 
struct  ADCBuf_Config_
 ADC driver's custom configuration structure. More...
 

Macros

#define ADCBuf_CMD_RESERVED   (32)
 
#define ADCBuf_STATUS_RESERVED   (-32)
 
#define ADCBuf_STATUS_SUCCESS   (0)
 Success status code returned by: ADCBuf_control() More...
 
#define ADCBuf_STATUS_ERROR   (-1)
 Generic error status code returned by ADCBuf_control(). More...
 
#define ADCBuf_STATUS_UNDEFINEDCMD   (-2)
 An error status code returned by ADCBuf_control() for undefined command codes. More...
 
#define ADCBuf_STATUS_UNSUPPORTED   (-3)
 An error status code returned if the function is not supported by a particular driver implementation. More...
 

Typedefs

typedef struct ADCBuf_Config_ADCBuf_Handle
 A handle that is returned from an ADCBuf_open() call. More...
 
typedef void(* ADCBuf_Callback) (ADCBuf_Handle handle, ADCBuf_Conversion *conversion, void *completedADCBuffer, uint32_t completedChannel, int_fast16_t status)
 The definition of a callback function. More...
 
typedef struct ADCBuf_Config_ ADCBuf_Config
 ADC driver's custom configuration structure. More...
 

Enumerations

enum  ADCBuf_Recurrence_Mode { ADCBuf_RECURRENCE_MODE_ONE_SHOT, ADCBuf_RECURRENCE_MODE_CONTINUOUS }
 Recurrence behavior of a ADCBuf_Conversion specified in the ADCBuf_Params. More...
 
enum  ADCBuf_Return_Mode { ADCBuf_RETURN_MODE_BLOCKING, ADCBuf_RETURN_MODE_CALLBACK }
 Return behavior for ADCBuf_convert() specified in the ADCBuf_Params. More...
 

Functions

void ADCBuf_close (ADCBuf_Handle handle)
 Function to close an ADCBuf driver instance. More...
 
int_fast16_t ADCBuf_control (ADCBuf_Handle handle, uint_fast16_t cmd, void *cmdArg)
 Function performs implementation specific features on a driver instance. More...
 
void ADCBuf_init (void)
 Function to initialize the ADCBuf driver. More...
 
void ADCBuf_Params_init (ADCBuf_Params *params)
 Initialize an ADCBuf_Params structure to its default values. More...
 
ADCBuf_Handle ADCBuf_open (uint_least8_t index, ADCBuf_Params *params)
 This function opens a given ADCBuf peripheral. More...
 
int_fast16_t ADCBuf_convert (ADCBuf_Handle handle, ADCBuf_Conversion conversions[], uint_fast8_t channelCount)
 Starts ADCBuf conversions on one or more channels. More...
 
int_fast16_t ADCBuf_convertCancel (ADCBuf_Handle handle)
 Cancels all ADCBuf conversions in progress. More...
 
uint_fast8_t ADCBuf_getResolution (ADCBuf_Handle handle)
 Returns the resolution in bits of the specified ADCBuf instance. More...
 
int_fast16_t ADCBuf_adjustRawValues (ADCBuf_Handle handle, void *sampleBuf, uint_fast16_t sampleCount, uint32_t adcChan)
 Adjust a raw ADC output buffer. The function does the adjustment in-place. More...
 
int_fast16_t ADCBuf_convertAdjustedToMicroVolts (ADCBuf_Handle handle, uint32_t adcChan, void *adjustedSampleBuffer, uint32_t outputMicroVoltBuffer[], uint_fast16_t sampleCount)
 Convert an adjusted ADC output buffer to microvolts. More...
 

Typedef Documentation

§ ADCBuf_Handle

typedef struct ADCBuf_Config_* ADCBuf_Handle

A handle that is returned from an ADCBuf_open() call.

§ ADCBuf_Callback

typedef void(* ADCBuf_Callback) (ADCBuf_Handle handle, ADCBuf_Conversion *conversion, void *completedADCBuffer, uint32_t completedChannel, int_fast16_t status)

The definition of a callback function.

When operating in ADCBuf_RETURN_MODE_CALLBACK, the callback function is called when an ADCBuf_Conversion completes. The application is responsible for declaring a ADCBuf_Callback and providing a pointer in ADCBuf_Params.callbackFxn.

Warning
The callback function is called from an interrupt context.
Parameters
[out]handleADCBuf_Handle used with the initial call to ADCBuf_convert()
[out]conversionPointer to the ADCBuf_Conversion structure used with the initial call to ADCBuf_convert(). This structure also contains the custom argument specified by conversion.arg.
[out]completedADCBufferPointer to a buffer containing conversion.samplesRequestedCount ADC samples.
[out]completedChannelADCBuf channel the samples were performed on.
[out]statusStatus of the ADCBuf driver during an interrupt.
See also
ADCBuf_convert()
ADCBuf_Conversion
ADCBuf_Recurrence_Mode
ADCBuf_RETURN_MODE_CALLBACK

§ ADCBuf_Config

typedef struct ADCBuf_Config_ ADCBuf_Config

ADC driver's custom configuration structure.

See also
ADCBuf_init()
ADCBuf_open()

Enumeration Type Documentation

§ ADCBuf_Recurrence_Mode

Recurrence behavior of a ADCBuf_Conversion specified in the ADCBuf_Params.

This enumeration defines the recurrence mode of a ADCBuf_Conversion. After a call to ADCBuf_convert(), ADCBuf_Conversion may either be done once or reoccur.

Enumerator
ADCBuf_RECURRENCE_MODE_ONE_SHOT 

When operating in ADCBuf_RECURRENCE_MODE_ONE_SHOT, calls to ADCBuf_convert() will pend on a semaphore until ADCBuf_Conversion.samplesRequestedCount samples are completed or after a duration of ADCBuf_Params.blockingTimeout.

Note
When using ADCBuf_RECURRENCE_MODE_ONE_SHOT, ADCBuf_convert() must be called from a thread context. ADCBuf_RECURRENCE_MODE_ONE_SHOT can only be used in combination with ADCBuf_RETURN_MODE_BLOCKING.
ADCBuf_RECURRENCE_MODE_CONTINUOUS 

When operating in ADCBuf_RECURRENCE_MODE_CONTINUOUS, calls to ADCBuf_convert() will return immediately. The driver will continuously perform ADCBuf_Conversion.samplesRequestedCount samples and call the ADCBuf_Callback function when completed. The driver will automatically alternate between ADCBuf_Conversion.sampleBuffer and ADCBuf_Conversion.sampleBufferTwo. A ADCBuf_RECURRENCE_MODE_CONTINUOUS conversion can only be terminated using ADCBuf_convertCancel().

Note
ADCBuf_RECURRENCE_MODE_CONTINUOUS can only be used in combination with ADCBuf_RETURN_MODE_CALLBACK.
See also
ADCBuf_RETURN_MODE_CALLBACK
ADCBuf_convertCancel()

§ ADCBuf_Return_Mode

Return behavior for ADCBuf_convert() specified in the ADCBuf_Params.

This enumeration defines the return behavior for ADCBuf_convert(). A call to ADCBuf_convert() may either block or return immediately.

See also
ADCBuf_convert
Enumerator
ADCBuf_RETURN_MODE_BLOCKING 

When operating in ADCBuf_RETURN_MODE_BLOCKING, calls to ADCBuf_convert() will pend on a semaphore until ADCBuf_Conversion.samplesRequestedCount samples are completed or after a duration of ADCBuf_Params.blockingTimeout.

Note
When using ADCBuf_RETURN_MODE_BLOCKING, ADCBuf_convert() must be called from a thread context. ADCBuf_RETURN_MODE_BLOCKING can only be used in combination with ADCBuf_RECURRENCE_MODE_ONE_SHOT.
ADCBuf_RETURN_MODE_CALLBACK 

When operating in ADCBuf_RETURN_MODE_CALLBACK, calls to ADCBuf_convert() will return immediately. When ADCBuf_Conversion.samplesRequestedCount samples are completed, the ADCBuf_Params.callbackFxn function is called.

Note
ADCBuf_RECURRENCE_MODE_CONTINUOUS can only be used in combination with ADCBuf_RETURN_MODE_CALLBACK.
See also
ADCBuf_RECURRENCE_MODE_CONTINUOUS

Function Documentation

§ ADCBuf_close()

void ADCBuf_close ( ADCBuf_Handle  handle)

Function to close an ADCBuf driver instance.

Precondition
ADCBuf_open() has to be called first.
In ADCBuf_RECURRENCE_MODE_CONTINUOUS, the application must call ADCBuf_convertCancel() first.
Parameters
[in]handleAn ADCBuf_Handle returned from ADCBuf_open()

§ ADCBuf_control()

int_fast16_t ADCBuf_control ( ADCBuf_Handle  handle,
uint_fast16_t  cmd,
void *  cmdArg 
)

Function performs implementation specific features on a driver instance.

Precondition
ADCBuf_open() has to be called first.
Parameters
[in]handleAn ADCBuf_Handle returned from ADCBuf_open()
[in]cmdA command value defined by the device specific implementation
[in]cmdArgAn optional R/W (read/write) argument that is accompanied with cmd
Returns
Implementation specific return codes. Negative values indicate unsuccessful operations.
Return values
ADCBuf_STATUS_SUCCESSThe call was successful.
ADCBuf_STATUS_UNDEFINEDCMDThe cmd value is not supported by the device specific implementation.

§ ADCBuf_init()

void ADCBuf_init ( void  )

Function to initialize the ADCBuf driver.

This function must also be called before any other ADCBuf driver APIs.

§ ADCBuf_Params_init()

void ADCBuf_Params_init ( ADCBuf_Params params)

Initialize an ADCBuf_Params structure to its default values.

Parameters
[in]paramsA pointer to ADCBuf_Params structure for initialization

Default values are:

§ ADCBuf_open()

ADCBuf_Handle ADCBuf_open ( uint_least8_t  index,
ADCBuf_Params params 
)

This function opens a given ADCBuf peripheral.

Parameters
[in]indexIndex in the ADCBuf_Config[] array.
[in]paramsPointer to an initialized ADCBuf_Params structure. If NULL, the default ADCBuf_Params values are used.
Returns
An ADCBuf_Handle on success or NULL on error.
See also
ADCBuf_close()

§ ADCBuf_convert()

int_fast16_t ADCBuf_convert ( ADCBuf_Handle  handle,
ADCBuf_Conversion  conversions[],
uint_fast8_t  channelCount 
)

Starts ADCBuf conversions on one or more channels.

Note
When using ADCBuf_RETURN_MODE_BLOCKING, this must be called from a thread context.
Parameters
[in]handleAn ADCBuf handle returned from ADCBuf_open()
[in]conversionsA pointer to an array of ADCBuf_Conversion structures.
[in]channelCountThe number of channels to convert on in this call. Should be the length of the conversions array. Depending on the device, multiple simultaneous conversions may not be supported. See device specific implementation.
Return values
ADCBuf_STATUS_SUCCESSThe conversion was successful.
ADCBuf_STATUS_ERRORThe conversion failed.
Precondition
ADCBuf_open() must have been called.
See also
ADCBuf_convertCancel()
ADCBuf_Return_Mode
ADCBuf_Recurrence_Mode
ADCBuf_Conversion

§ ADCBuf_convertCancel()

int_fast16_t ADCBuf_convertCancel ( ADCBuf_Handle  handle)

Cancels all ADCBuf conversions in progress.

Parameters
[in]handleAn ADCBuf_Handle returned from ADCBuf_open()
Return values
ADCBuf_STATUS_SUCCESSThe cancel was successful.
ADCBuf_STATUS_ERRORThe cancel failed.
See also
ADCBuf_convert()

§ ADCBuf_getResolution()

uint_fast8_t ADCBuf_getResolution ( ADCBuf_Handle  handle)

Returns the resolution in bits of the specified ADCBuf instance.

Parameters
[in]handleAn ADCBuf_Handle returned from ADCBuf_open().
Returns
The resolution in bits of the specified ADC.
Precondition
ADCBuf_open() must have been called prior.

§ ADCBuf_adjustRawValues()

int_fast16_t ADCBuf_adjustRawValues ( ADCBuf_Handle  handle,
void *  sampleBuf,
uint_fast16_t  sampleCount,
uint32_t  adcChan 
)

Adjust a raw ADC output buffer. The function does the adjustment in-place.

Parameters
[in]handleAn ADCBuf_Handle returned from ADCBuf_open().
[in,out]sampleBufA buffer full of raw sample values.
[in]sampleCountThe number of samples to adjust.
[in]adcChanThe channel the buffer was sampled on.
Return values
ADCBuf_STATUS_SUCCESSThe operation was successful. sampleBuf contains valid values.
ADCBuf_STATUS_ERRORif an error occurred.
ADCBuf_STATUS_UNSUPPORTEDThe function is not supported by the device specific implementation.
Precondition
ADCBuf_convert() must have returned a valid buffer with samples.

§ ADCBuf_convertAdjustedToMicroVolts()

int_fast16_t ADCBuf_convertAdjustedToMicroVolts ( ADCBuf_Handle  handle,
uint32_t  adcChan,
void *  adjustedSampleBuffer,
uint32_t  outputMicroVoltBuffer[],
uint_fast16_t  sampleCount 
)

Convert an adjusted ADC output buffer to microvolts.

Parameters
[in]handleAn ADCBuf_Handle returned from ADCBuf_open()
[in]adcChanThe ADC channel the samples were performed on.
[in]adjustedSampleBufferA buffer full of adjusted samples.
[in,out]outputMicroVoltBufferThe output buffer.
[in]sampleCountThe number of samples to convert.
Return values
ADCBuf_STATUS_SUCCESSThe operation was successful. outputMicroVoltBuffer contains valid values.
ADCBuf_STATUS_ERRORThe operation failed.
Precondition
ADCBuf_adjustRawValues() must be called on adjustedSampleBuffer.
© Copyright 1995-2022, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale