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
#include <ti/drivers/ADCBuf.h>
// 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
ADCBuf_init();
// Initialize optional ADCBuf parameters
ADCBuf_Params params;
ADCBuf_Params_init(&params);
params.returnMode = ADCBuf_RETURN_MODE_BLOCKING;
params.recurrenceMode = ADCBuf_RECURRENCE_MODE_ONE_SHOT;
// 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_init();
ADCBuf_Params_init(&adcBufParams);
adcBufHandle = ADCBuf_open(0, &adcBufParams);
if (adcBufHandle == NULL)
{
    //ADCBuf_open() failed.
    while (1) {}
}

Using a blocking conversion

ADCBuf_Handle adcbuf;
ADCBuf_Params params;
ADCBuf_init();
ADCBuf_Params_init(&params);
params.returnMode = ADCBuf_RETURN_MODE_BLOCKING;
params.recurrenceMode = ADCBuf_RECURRENCE_MODE_ONE_SHOT;
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);
main()
{
    ADCBuf_Handle adcbuf;
    ADCBuf_Params params;
    ADCBuf_init();
    ADCBuf_Params_init(&params);
    params.returnMode = ADCBuf_RETURN_MODE_CALLBACK;
    params.recurrenceMode = ADCBuf_RECURRENCE_MODE_ONE_SHOT;
    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)
{
    // Adjust raw ADC values and convert them to microvolts
    ADCBuf_adjustRawValues(handle, buffer, ADCBUFFERSIZE,
        channel);
    ADCBuf_convertAdjustedToMicroVolts(handle, 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)
	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)

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]	handle	ADCBuf_Handle used with the initial call to ADCBuf_convert()
[out]	conversion	Pointer 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]	completedADCBuffer	Pointer to a buffer containing `conversion.samplesRequestedCount` ADC samples.
[out]	completedChannel	ADCBuf channel the samples were performed on.

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

enum 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

enum 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] handle An 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]	handle	An ADCBuf_Handle returned from ADCBuf_open()
[in]	cmd	A command value defined by the device specific implementation
[in]	cmdArg	An 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_SUCCESS	The call was successful.
ADCBuf_STATUS_UNDEFINEDCMD	The `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] params A pointer to ADCBuf_Params structure for initialization

Default values are:

ADCBuf_Params.returnMode = ADCBuf_RETURN_MODE_BLOCKING,
ADCBuf_Params.blockingTimeout = 25000,
ADCBuf_Params.callbackFxn = NULL,
ADCBuf_Params.recurrenceMode = ADCBuf_RECURRENCE_MODE_ONE_SHOT,
ADCBuf_Params.samplingFrequency = 10000,
ADCBuf_Params.custom = NULL

§ ADCBuf_open()

ADCBuf_Handle ADCBuf_open	(	uint_least8_t	index,
		ADCBuf_Params *	params
	)

This function opens a given ADCBuf peripheral.

Parameters

[in]	index	Index in the `ADCBuf_Config`[] array.
[in]	params	Pointer 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]	handle	An ADCBuf handle returned from ADCBuf_open()
[in]	conversions	A pointer to an array of ADCBuf_Conversion structures.
[in]	channelCount	The 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_SUCCESS	The conversion was successful.
ADCBuf_STATUS_ERROR	The 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] handle An ADCBuf_Handle returned from ADCBuf_open()

Return values

ADCBuf_STATUS_SUCCESS	The cancel was successful.
ADCBuf_STATUS_ERROR	The 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] handle An 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]	handle	An ADCBuf_Handle returned from ADCBuf_open().
[in,out]	sampleBuf	A buffer full of raw sample values.
[in]	sampleCount	The number of samples to adjust.
[in]	adcChan	The channel the buffer was sampled on.

Return values

ADCBuf_STATUS_SUCCESS	The operation was successful. `sampleBuf` contains valid values.
ADCBuf_STATUS_ERROR	if an error occurred.
ADCBuf_STATUS_UNSUPPORTED	The 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]	handle	An ADCBuf_Handle returned from ADCBuf_open()
[in]	adcChan	The ADC channel the samples were performed on.
[in]	adjustedSampleBuffer	A buffer full of adjusted samples.
[in,out]	outputMicroVoltBuffer	The output buffer.
[in]	sampleCount	The number of samples to convert.

Return values

ADCBuf_STATUS_SUCCESS	The operation was successful. `outputMicroVoltBuffer` contains valid values.
ADCBuf_STATUS_ERROR	The operation failed.

Precondition: ADCBuf_adjustRawValues() must be called on adjustedSampleBuffer.

Detailed Description

Overview

Usage

Synopsis

Examples

Opening an ADCBuf instance

Using a blocking conversion

Using a callback conversion

Configuration

Data Structures

Macros

Typedefs

Enumerations

Functions

Typedef Documentation

§ ADCBuf_Handle

§ ADCBuf_Callback

§ ADCBuf_Config

Enumeration Type Documentation

§ ADCBuf_Recurrence_Mode

§ ADCBuf_Return_Mode

Function Documentation

§ ADCBuf_close()

§ ADCBuf_control()

§ ADCBuf_init()

§ ADCBuf_Params_init()

§ ADCBuf_open()

§ ADCBuf_convert()

§ ADCBuf_convertCancel()

§ ADCBuf_getResolution()

§ ADCBuf_adjustRawValues()

§ ADCBuf_convertAdjustedToMicroVolts()