Detailed Description

ADCBuf driver interface.

============================================================================

The ADCBuf header file should be included in an application as follows:

Operation

The ADCBuf driver in TI-RTOS samples an analogue waveform at a specified frequency. The resulting samples are transferred to 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.

The APIs in this driver serve as an interface to a typical TI-RTOS application. The specific peripheral implementations are responsible to create all the SYS/BIOS specific primitives to allow for thread-safe operation.

Opening the driver

ADCBuf_Handle adcBufHandle;
ADCBuf_Params adcBufParams;
ADCBuf_Params_init(&adcBufParams);
adcBufHandle = ADCBuf_open(Board_ADCBuf0, &adcBufParams);

Making a conversion

In this context, a conversion refers to taking multiple ADC samples and transferring them to an application-provided buffer. To start a conversion, the application must configure an ADCBuf_Conversion struct and call ADCBuf_convert(). In blocking mode, ADCBuf_convert() will return when the conversion is finished and the desired number of samples have been made. In callback mode, ADCBuf_convert() will return immediately and the application will get a callback when the conversion is done.

ADCBuf_Conversion blockingConversion;
blockingConversion.arg = NULL;
blockingConversion.adcChannel = Board_ADCCHANNEL_A1;
blockingConversion.sampleBuffer = sampleBufferOnePtr;
blockingConversion.sampleBufferTwo = NULL;
blockingConversion.samplesRequestedCount = ADCBUFFERSIZE;
if (!ADCBuf_convert(adcBuf, &continuousConversion, 1)) {
    // handle error
}

Canceling a conversion

ADCBuf_convertCancel() is used to cancel an ADCBuf conversion when the driver is used in ADCBuf_RETURN_MODE_CALLBACK.

Calling this API while no conversion is in progress has no effect. If a conversion is in progress, it is canceled and the provided callback function is called.

In ADCBuf_RECURRENCE_MODE_CONTINUOUS, this function must be called to stop the conversion. The driver will continue providing callbacks with fresh samples until thie ADCBuf_convertCancel() function is called. The callback function is not called after ADCBuf_convertCancel() while in ADCBuf_RECURRENCE_MODE_CONTINUOUS.

Implementation

This module serves as the main interface for TI-RTOS applications. Its purpose is to redirect the module's APIs to specific peripheral implementations which are specified using a pointer to an ADCBuf_FxnTable.

The ADCBuf driver interface module is joined (at link time) to a NULL-terminated array of ADCBuf_Config data structures named ADCBuf_config. ADCBuf_config is implemented in the application with each entry being an instance of an ADCBuf peripheral. Each entry in ADCBuf_config contains a:

(ADCBuf_FxnTable *) to a set of functions that implement an ADCBuf peripheral
(void *) data object that is associated with the ADCBuf_FxnTable
(void *) hardware attributes that are associated to the ADCBuf_FxnTable

Instrumentation

The ADCBuf driver interface produces log statements if instrumentation is enabled.

Diagnostics Mask	Log details
Diags_USER1	basic operations performed
Diags_USER2	detailed operations performed

#include <stdint.h>
#include <stdbool.h>
#include <stddef.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
	An ADCBuf_Conversion data structure is used with ADCBuf_convert(). It indicates which channel to perform the ADC conversion on, how many conversions to make, and where to put them. The arg variable is an user-definable argument which gets passed to the ADCBuf_Callback when the ADC driver is in ADCBuf_RETURN_MODE_CALLBACK. More...

struct	ADCBuf_Params
	ADC Parameters. 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
	ADCBuf Global configuration. 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...

Typedefs
typedef struct ADCBuf_Config *	ADCBuf_Handle
	A handle that is returned from an ADCBuf_open() call. More...

typedef struct ADCBuf_Conversion	ADCBuf_Conversion
	An ADCBuf_Conversion data structure is used with ADCBuf_convert(). It indicates which channel to perform the ADC conversion on, how many conversions to make, and where to put them. The arg variable is an user-definable argument which gets passed to the ADCBuf_Callback when the ADC driver is in ADCBuf_RETURN_MODE_CALLBACK. More...

typedef void(*	ADCBuf_Callback) (ADCBuf_Handle handle, ADCBuf_Conversion conversion, void completedADCBuffer, uint32_t completedChannel)
	The definition of a callback function used by the ADC driver when used in ADCBuf_RETURN_MODE_CALLBACK. It is called in a HWI or SWI context depending on the device specific implementation. More...

typedef enum ADCBuf_Recurrence_Mode	ADCBuf_Recurrence_Mode
	ADC trigger mode settings. More...

typedef enum ADCBuf_Return_Mode	ADCBuf_Return_Mode
	ADC return mode settings. More...

typedef struct ADCBuf_Params	ADCBuf_Params
	ADC Parameters. More...

typedef void(*	ADCBuf_CloseFxn) (ADCBuf_Handle handle)
	A function pointer to a driver specific implementation of ADCBuf_close(). More...

typedef ADCBuf_Handle(*	ADCBuf_OpenFxn) (ADCBuf_Handle handle, ADCBuf_Params *params)
	A function pointer to a driver specific implementation of ADCBuf_open(). More...

typedef int_fast16_t(*	ADCBuf_ControlFxn) (ADCBuf_Handle handle, uint_fast8_t cmd, void *arg)
	A function pointer to a driver specific implementation of ADCBuf_control(). More...

typedef void(*	ADCBuf_InitFxn) (ADCBuf_Handle handle)
	A function pointer to a driver specific implementation of ADCBuf_init(). More...

typedef int_fast16_t(*	ADCBuf_ConvertFxn) (ADCBuf_Handle handle, ADCBuf_Conversion conversions[], uint_fast8_t channelCount)
	A function pointer to a driver specific implementation of ADCBuf_convert(). More...

typedef int_fast16_t(*	ADCBuf_ConvertCancelFxn) (ADCBuf_Handle handle)
	A function pointer to a driver specific implementation of ADCBuf_convertCancel(). More...

typedef uint_fast8_t(*	ADCBuf_GetResolutionFxn) (ADCBuf_Handle handle)
	A function pointer to a driver specific implementation of ADCBuf_GetResolution();. More...

typedef int_fast16_t(*	ADCBuf_adjustRawValuesFxn) (ADCBuf_Handle handle, void *sampleBuffer, uint_fast16_t sampleCount, uint32_t adcChannel)
	A function pointer to a driver specific implementation of ADCBuf_adjustRawValues();. More...

typedef int_fast16_t(*	ADCBuf_convertAdjustedToMicroVoltsFxn) (ADCBuf_Handle handle, uint32_t adcChannel, void *adjustedSampleBuffer, uint32_t outputMicroVoltBuffer[], uint_fast16_t sampleCount)
	A function pointer to a driver specific implementation of ADCBuf_convertAdjustedToMicroVolts();. More...

typedef struct ADCBuf_FxnTable	ADCBuf_FxnTable
	The definition of an ADCBuf function table that contains the required set of functions to control a specific ADC driver implementation. More...

typedef struct ADCBuf_Config	ADCBuf_Config
	ADCBuf Global configuration. More...

Enumerations
enum	ADCBuf_Recurrence_Mode { ADCBuf_RECURRENCE_MODE_ONE_SHOT, ADCBuf_RECURRENCE_MODE_CONTINUOUS }
	ADC trigger mode settings. More...

enum	ADCBuf_Return_Mode { ADCBuf_RETURN_MODE_BLOCKING, ADCBuf_RETURN_MODE_CALLBACK }
	ADC return mode settings. More...

Functions
void	ADCBuf_close (ADCBuf_Handle handle)
	Function to close an ADC peripheral specified by the ADC handle. More...

int_fast16_t	ADCBuf_control (ADCBuf_Handle handle, uint_fast8_t cmd, void *arg)
	Function performs implementation specific features on a given ADCBuf_Handle. More...

void	ADCBuf_init (void)
	This function initializes the ADC module. This function must. More...

void	ADCBuf_Params_init (ADCBuf_Params *params)
	This function sets all fields of a specified ADCBuf_Params structure to their default values. More...

ADCBuf_Handle	ADCBuf_open (uint_fast8_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)
	This function starts a set of conversions on one or more channels. More...

int_fast16_t	ADCBuf_convertCancel (ADCBuf_Handle handle)
	This function cancels an ADC conversion that is in progress. More...

uint_fast8_t	ADCBuf_getResolution (ADCBuf_Handle handle)
	This function returns the resolution in bits of the specified ADC. More...

int_fast16_t	ADCBuf_adjustRawValues (ADCBuf_Handle handle, void *sampleBuffer, uint_fast16_t sampleCount, uint32_t adcChannel)
	This function adjusts a raw ADC output buffer such that the result is comparable between devices of the same make. The function does the adjustment in-place. More...

int_fast16_t	ADCBuf_convertAdjustedToMicroVolts (ADCBuf_Handle handle, uint32_t adcChannel, void *adjustedSampleBuffer, uint32_t outputMicroVoltBuffer[], uint_fast16_t sampleCount)
	This function converts a raw ADC output value to a value scaled in micro volts. More...

Macro Definition Documentation

#define ADCBuf_CMD_RESERVED 32

Common ADCBuf_control command code reservation offset. ADC driver implementations should offset command codes with ADCBuf_CMD_RESERVED growing positively

Example implementation specific command codes:

1 #define ADCXYZ_COMMAND0 ADCBuf_CMD_RESERVED + 0

2 #define ADCXYZ_COMMAND1 ADCBuf_CMD_RESERVED + 1

#define ADCBuf_STATUS_RESERVED -32

Common ADCBuf_control status code reservation offset. ADC driver implementations should offset status codes with ADCBuf_STATUS_RESERVED growing negatively.

Example implementation specific status codes:

 #define ADCXYZ_STATUS_ERROR0    ADCBuf_STATUS_RESERVED - 0
 #define ADCXYZ_STATUS_ERROR1    ADCBuf_STATUS_RESERVED - 1
 #define ADCXYZ_STATUS_ERROR2    ADCBuf_STATUS_RESERVED - 2

#define ADCBuf_STATUS_SUCCESS 0

Success status code returned by: ADCBuf_control()

Functions return ADCBuf_STATUS_SUCCESS if the call was executed successfully.

#define ADCBuf_STATUS_ERROR -1

Generic error status code returned by ADCBuf_control().

ADCBuf_control() returns ADCBuf_STATUS_ERROR if the control code was not executed successfully.

#define ADCBuf_STATUS_UNDEFINEDCMD -2

An error status code returned by ADCBuf_control() for undefined command codes.

ADCBuf_control() returns ADCBuf_STATUS_UNDEFINEDCMD if the control code is not recognized by the driver implementation.

Typedef Documentation

typedef struct ADCBuf_Config* ADCBuf_Handle

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

typedef struct ADCBuf_Conversion ADCBuf_Conversion

An ADCBuf_Conversion data structure is used with ADCBuf_convert(). It indicates which channel to perform the ADC conversion on, how many conversions to make, and where to put them. The arg variable is an user-definable argument which gets passed to the ADCBuf_Callback when the ADC driver is in ADCBuf_RETURN_MODE_CALLBACK.

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

The definition of a callback function used by the ADC driver when used in ADCBuf_RETURN_MODE_CALLBACK. It is called in a HWI or SWI context depending on the device specific implementation.

typedef enum ADCBuf_Recurrence_Mode ADCBuf_Recurrence_Mode

ADC trigger mode settings.

This enum defines if the driver should make n conversions and return or run indefinitely and run a callback function every n conversions.

typedef enum ADCBuf_Return_Mode ADCBuf_Return_Mode

ADC return mode settings.

This enum defines how the ADCBuf_convert() function returns. It either blocks or returns immediately and calls a callback function when the provided buffer has been filled.

typedef struct ADCBuf_Params ADCBuf_Params

ADC Parameters.

ADC Parameters are used to with the ADCBuf_open() call. Default values for these parameters are set using ADCBuf_Params_init().

See also: ADCBuf_Params_init()

typedef void(* ADCBuf_CloseFxn) (ADCBuf_Handle handle)

A function pointer to a driver specific implementation of ADCBuf_close().

typedef ADCBuf_Handle(* ADCBuf_OpenFxn) (ADCBuf_Handle handle, ADCBuf_Params *params)

A function pointer to a driver specific implementation of ADCBuf_open().

typedef int_fast16_t(* ADCBuf_ControlFxn) (ADCBuf_Handle handle, uint_fast8_t cmd, void *arg)

A function pointer to a driver specific implementation of ADCBuf_control().

typedef void(* ADCBuf_InitFxn) (ADCBuf_Handle handle)

A function pointer to a driver specific implementation of ADCBuf_init().

typedef int_fast16_t(* ADCBuf_ConvertFxn) (ADCBuf_Handle handle, ADCBuf_Conversion conversions[], uint_fast8_t channelCount)

A function pointer to a driver specific implementation of ADCBuf_convert().

typedef int_fast16_t(* ADCBuf_ConvertCancelFxn) (ADCBuf_Handle handle)

A function pointer to a driver specific implementation of ADCBuf_convertCancel().

typedef uint_fast8_t(* ADCBuf_GetResolutionFxn) (ADCBuf_Handle handle)

A function pointer to a driver specific implementation of ADCBuf_GetResolution();.

typedef int_fast16_t(* ADCBuf_adjustRawValuesFxn) (ADCBuf_Handle handle, void *sampleBuffer, uint_fast16_t sampleCount, uint32_t adcChannel)

A function pointer to a driver specific implementation of ADCBuf_adjustRawValues();.

typedef int_fast16_t(* ADCBuf_convertAdjustedToMicroVoltsFxn) (ADCBuf_Handle handle, uint32_t adcChannel, void *adjustedSampleBuffer, uint32_t outputMicroVoltBuffer[], uint_fast16_t sampleCount)

A function pointer to a driver specific implementation of ADCBuf_convertAdjustedToMicroVolts();.

typedef struct ADCBuf_FxnTable ADCBuf_FxnTable

The definition of an ADCBuf function table that contains the required set of functions to control a specific ADC driver implementation.

typedef struct ADCBuf_Config ADCBuf_Config

ADCBuf Global configuration.

The ADCBuf_Config structure contains a set of pointers used to characterise the ADC driver implementation.

This structure needs to be defined before calling ADCBuf_init() and it must not be changed thereafter.

See also: ADCBuf_init()

Enumeration Type Documentation

enum ADCBuf_Recurrence_Mode

ADC trigger mode settings.

This enum defines if the driver should make n conversions and return or run indefinitely and run a callback function every n conversions.

Enumerator
ADCBuf_RECURRENCE_MODE_ONE_SHOT	The driver makes n measurements and returns or runs a callback function depending on the ADCBuf_Return_Mode setting.
ADCBuf_RECURRENCE_MODE_CONTINUOUS	The driver makes n measurements and then runs a callback function. This process happens until the application calls ADCBuf_ConvertCancelFxn(). This setting can only be used in ADCBuf_RETURN_MODE_CALLBACK.

enum ADCBuf_Return_Mode

ADC return mode settings.

This enum defines how the ADCBuf_convert() function returns. It either blocks or returns immediately and calls a callback function when the provided buffer has been filled.

Enumerator

ADCBuf_RETURN_MODE_BLOCKING

Uses a semaphore to block while ADC conversions are performed. Context of the call must be a Task.

Note: Blocking return mode cannot be used in combination with ADCBuf_RECURRENCE_MODE_CONTINUOUS

ADCBuf_RETURN_MODE_CALLBACK

Non-blocking and will return immediately. When the conversion is finished the configured callback function is called.

Function Documentation

void ADCBuf_close ( ADCBuf_Handle handle )

Function to close an ADC peripheral specified by the ADC handle.

Precondition: ADCBuf_open() has to be called first.; In ADCBuf_RECURRENCE_MODE_CONTINUOUS, the application must call ADCBuf_convertCancel() first.

Parameters

handle An ADCBuf handle returned from ADCBuf_open()

See also: ADCBuf_open()

int_fast16_t ADCBuf_control	(	ADCBuf_Handle	handle,
		uint_fast8_t	cmd,
		void *	arg
	)

Function performs implementation specific features on a given ADCBuf_Handle.

Precondition: ADCBuf_open() has to be called first.

Parameters

handle	An ADCBuf handle returned from ADCBuf_open()
cmd	A command value defined by the driver specific implementation
arg	A pointer to an optional R/W (read/write) argument that is accompanied with cmd

Returns: An ADCBuf_Status describing an error or success state. Negative values indicates an error.

See also: ADCBuf_open()

void ADCBuf_init ( void )

This function initializes the ADC module. This function must.

Precondition: The ADCBuf_Config structure must exist and be persistent before this function can be called. This function call does not modify any peripheral registers. Function should only be called once.

void ADCBuf_Params_init ( ADCBuf_Params * params )

This function sets all fields of a specified ADCBuf_Params structure to their default values.

Parameters

params A pointer to ADCBuf_Params structure for initialization

Default values are: returnMode = ADCBuf_RETURN_MODE_BLOCKING, blockingTimeout = 25000, callbackFxn = NULL, recurrenceMode = ADCBuf_RECURRENCE_MODE_ONE_SHOT, samplingFrequency = 10000, custom = NULL

ADCBuf_Params::blockingTimeout should be set large enough to allow for the desired number of samples to be collected with the specified frequency.

ADCBuf_Handle ADCBuf_open	(	uint_fast8_t	index,
		ADCBuf_Params *	params
	)

This function opens a given ADCBuf peripheral.

Parameters

index	Logical peripheral number for the ADCBuf indexed into the ADCBuf_config table
params	Pointer to an parameter block, if NULL it will use default values.

Returns: An ADCBuf_Handle on success or a NULL on an error or if it has been opened already. If NULL is returned further ADC API calls will result in undefined behaviour.

See also: ADCBuf_close()

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

This function starts a set of conversions on one or more channels.

Parameters

handle	An ADCBuf handle returned from ADCBuf_open()
conversions	A pointer to an array of ADCBuf_Conversion structs with the specific parameters for each channel. Only use one ADCBuf_Conversion struct per channel.
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.

Returns: ADCBuf_STATUS_SUCCESS if the operation was successful. ADCBuf_STATUS_ERROR or a device specific status is returned otherwise.

Precondition: ADCBuf_open() must have been called prior.

See also: ADCBuf_convertCancel()

int_fast16_t ADCBuf_convertCancel ( ADCBuf_Handle handle )

This function cancels an ADC conversion that is in progress.

This function must be called before calling ADCBuf_close().

Parameters

handle An ADCBuf handle returned from ADCBuf_open()

Returns: ADCBuf_STATUS_SUCCESS if the operation was successful. ADCBuf_STATUS_ERROR or a device specific status is returned otherwise.

See also: ADCBuf_convert()

uint_fast8_t ADCBuf_getResolution ( ADCBuf_Handle handle )

This function returns the resolution in bits of the specified ADC.

Parameters

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.

int_fast16_t ADCBuf_adjustRawValues	(	ADCBuf_Handle	handle,
		void *	sampleBuffer,
		uint_fast16_t	sampleCount,
		uint32_t	adcChannel
	)

This function adjusts a raw ADC output buffer such that the result is comparable between devices of the same make. The function does the adjustment in-place.

Parameters

handle	An ADCBuf handle returned from ADCBuf_open().
sampleBuffer	A buffer full of raw sample values.
sampleCount	The number of samples to adjust.
adcChannel	The channel the buffer was sampled on.

Returns: A buffer full of adjusted samples contained in sampleBuffer.; ADCBuf_STATUS_SUCCESS if the operation was successful. ADCBuf_STATUS_ERROR or a device specific status is returned otherwise.

Precondition: ADCBuf_open() must have been called prior.

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

This function converts a raw ADC output value to a value scaled in micro volts.

Parameters

handle	An ADCBuf handle returned from ADCBuf_open()
adcChannel	The ADC channel the samples stem from. This parameter is only necessary for certain devices. See device specific implementation for details.
adjustedSampleBuffer	A buffer full of adjusted samples.
outputMicroVoltBuffer	The output buffer. The conversion does not occur in place due to the differing data type sizes.
sampleCount	The number of samples to convert.

Returns: A number of measurements scaled in micro volts inside outputMicroVoltBuffer.; ADCBuf_STATUS_SUCCESS if the operation was successful. ADCBuf_STATUS_ERROR or a device specific status is returned otherwise.

Precondition: ADCBuf_open() must have been called prior.; ADCBuf_adjustRawValues() must be called on adjustedSampleBuffer prior.

Detailed Description

Operation

Opening the driver

Making a conversion

Canceling a conversion

Implementation

Instrumentation

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation