![]() |
![]() |
TI-RTOS Drivers
tidrivers_full_2_20_01_10
|
ADCBuf driver interface.
============================================================================
The ADCBuf header file should be included in an application as follows:
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.
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_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.
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:
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>
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... | |
#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:
#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 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 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().
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.
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.
|
ADCBuf_RETURN_MODE_CALLBACK |
Non-blocking and will return immediately. When the conversion is finished the configured callback function is called. |
void ADCBuf_close | ( | ADCBuf_Handle | handle | ) |
Function to close an ADC peripheral specified by the ADC handle.
handle | An ADCBuf handle returned from 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.
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 |
void ADCBuf_init | ( | void | ) |
This function initializes the ADC module. This function must.
void ADCBuf_Params_init | ( | ADCBuf_Params * | params | ) |
This function sets all fields of a specified ADCBuf_Params structure to their default values.
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.
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. |
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.
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. |
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().
handle | An ADCBuf handle returned from ADCBuf_open() |
uint_fast8_t ADCBuf_getResolution | ( | ADCBuf_Handle | handle | ) |
This function returns the resolution in bits of the specified ADC.
handle | An ADCBuf handle returned from ADCBuf_open(). |
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.
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. |
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.
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. |