Detailed Description

ADC driver interface.

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

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

Operation

The ADC driver operates as a simplified ADC module with only single channel sampling support. It also operates on blocking only mode which means users have to wait the current sampling finished before starting another sampling. The sampling channel needs to be specified in the ADC_open() before calling ADC_convert().

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. User can use the ADC driver or the ADCBuf driver that has more features. But both ADC and ADCBuf cannot be used together in an application.

Opening the driver

ADC_Handle adc;
ADC_Params params;
ADC_Params_init(&params);
adc = ADC_open(Board_ADC0, &params);
if (adc == NULL) {
    // ADC_open() failed
    while (1);
}

Converting

An ADC conversion with a ADC peripheral is started by calling ADC_convert(). The result value is returned by ADC_convert() once the conversion is finished.

int_fast16_t res;
uint_fast16_t adcValue;
res = ADC_convert(adc, &adcValue);
if (res == ADC_STATUS_SUCCESS) {
    //use adcValue
}

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 a ADC_FxnTable.

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

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

Instrumentation

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

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

#include <stdbool.h>
#include <stdint.h>

Include dependency graph for ADC.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	ADC_Params_
	ADC Parameters. More...

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

struct	ADC_Config_
	ADC Global configuration. More...

Macros
#define	ADC_convertRawToMicroVolts ADC_convertToMicroVolts
	Define to support deprecated API ADC_convertRawToMicroVolts. More...

#define	ADC_CMD_RESERVED (32)

#define	ADC_STATUS_RESERVED (-32)


#define	ADC_STATUS_SUCCESS (0)
	Successful status code returned by ADC_control(). More...

#define	ADC_STATUS_ERROR (-1)
	Generic error status code returned by ADC_control(). More...

#define	ADC_STATUS_UNDEFINEDCMD (-2)
	An error status code returned by ADC_control() for undefined command codes. More...

Typedefs
typedef struct ADC_Config_ *	ADC_Handle
	A handle that is returned from a ADC_open() call. More...

typedef struct ADC_Params_	ADC_Params
	ADC Parameters. More...

typedef void(*	ADC_CloseFxn) (ADC_Handle handle)
	A function pointer to a driver specific implementation of ADC_close(). More...

typedef int_fast16_t(*	ADC_ControlFxn) (ADC_Handle handle, uint_fast16_t cmd, void *arg)
	A function pointer to a driver specific implementation of ADC_control(). More...

typedef int_fast16_t(*	ADC_ConvertFxn) (ADC_Handle handle, uint16_t *value)
	A function pointer to a driver specific implementation of ADC_ConvertFxn(). More...

typedef uint32_t(*	ADC_ConvertToMicroVoltsFxn) (ADC_Handle handle, uint16_t adcValue)
	A function pointer to a driver specific implementation of ADC_convertToMicroVolts(). More...

typedef void(*	ADC_InitFxn) (ADC_Handle handle)
	A function pointer to a driver specific implementation of ADC_init(). More...

typedef ADC_Handle(*	ADC_OpenFxn) (ADC_Handle handle, ADC_Params *params)
	A function pointer to a driver specific implementation of ADC_open(). More...

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

typedef struct ADC_Config_	ADC_Config
	ADC Global configuration. More...

Functions
void	ADC_close (ADC_Handle handle)
	Function to close a ADC driver. More...

int_fast16_t	ADC_control (ADC_Handle handle, uint_fast16_t cmd, void *arg)
	Function performs implementation specific features on a given ADC_Handle. More...

int_fast16_t	ADC_convert (ADC_Handle handle, uint16_t *value)
	Function to perform ADC conversion. More...

uint32_t	ADC_convertToMicroVolts (ADC_Handle handle, uint16_t adcValue)
	Function performs conversion from ADC result to actual value in microvolts. More...

void	ADC_init (void)
	Function to initializes the ADC driver. More...

ADC_Handle	ADC_open (uint_least8_t index, ADC_Params *params)
	Function to initialize the ADC peripheral. More...

void	ADC_Params_init (ADC_Params *params)
	Function to initialize the ADC_Params struct to its defaults. More...

Macro Definition Documentation

§ ADC_convertRawToMicroVolts

#define ADC_convertRawToMicroVolts ADC_convertToMicroVolts

Define to support deprecated API ADC_convertRawToMicroVolts.

It is succeeded by the generic ADC_convertToMicroVolts.

Typedef Documentation

§ ADC_Handle

typedef struct ADC_Config_* ADC_Handle

A handle that is returned from a ADC_open() call.

§ ADC_Params

typedef struct ADC_Params_ ADC_Params

ADC Parameters.

ADC parameters are used to with the ADC_open() call. Only custom argument is supported in the parameters. Default values for these parameters are set using ADC_Params_init().

See also: ADC_Params_init()

§ ADC_CloseFxn

typedef void(* ADC_CloseFxn) (ADC_Handle handle)

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

§ ADC_ControlFxn

typedef int_fast16_t(* ADC_ControlFxn) (ADC_Handle handle, uint_fast16_t cmd, void *arg)

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

§ ADC_ConvertFxn

typedef int_fast16_t(* ADC_ConvertFxn) (ADC_Handle handle, uint16_t *value)

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

§ ADC_ConvertToMicroVoltsFxn

typedef uint32_t(* ADC_ConvertToMicroVoltsFxn) (ADC_Handle handle, uint16_t adcValue)

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

§ ADC_InitFxn

typedef void(* ADC_InitFxn) (ADC_Handle handle)

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

§ ADC_OpenFxn

typedef ADC_Handle(* ADC_OpenFxn) (ADC_Handle handle, ADC_Params *params)

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

§ ADC_FxnTable

typedef struct ADC_FxnTable_ ADC_FxnTable

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

§ ADC_Config

typedef struct ADC_Config_ ADC_Config

ADC Global configuration.

The ADC_Config structure contains a set of pointers used to characterize the ADC driver implementation.

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

See also: ADC_init()

Function Documentation

§ ADC_close()

void ADC_close ( ADC_Handle handle )

Function to close a ADC driver.

Precondition: ADC_open() has to be called first.

Parameters

handle An ADC handle returned from ADC_open()

See also: ADC_open()

§ ADC_control()

int_fast16_t ADC_control	(	ADC_Handle	handle,
		uint_fast16_t	cmd,
		void *	arg
	)

Function performs implementation specific features on a given ADC_Handle.

Precondition: ADC_open() has to be called first.

Parameters

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

Returns: Implementation specific return codes. Negative values indicate unsuccessful operations.

See also: ADC_open()

§ ADC_convert()

int_fast16_t ADC_convert	(	ADC_Handle	handle,
		uint16_t *	value
	)

Function to perform ADC conversion.

Function to perform ADC single channel single sample conversion.

Precondition: ADC_open() has been called

Parameters

handle	An ADC_Handle
value	A pointer to the conversion result

Returns: The return value indicates the conversion is succeeded or failed. The value could be ADC_STATUS_SUCCESS or ADC_STATUS_ERROR.

See also: ADC_open(); ADC_close()

§ ADC_convertToMicroVolts()

uint32_t ADC_convertToMicroVolts	(	ADC_Handle	handle,
		uint16_t	adcValue
	)

Function performs conversion from ADC result to actual value in microvolts.

Precondition: ADC_open() and ADC_convert() has to be called first.

Parameters

handle	A ADC handle returned from ADC_open()
adcValue	A sampling result return from ADC_convert()

Returns: The actual sampling result in micro volts unit.

See also: ADC_open()

§ ADC_init()

void ADC_init ( void )

Function to initializes the ADC driver.

Precondition: The ADC_config structure must exist and be persistent before this function can be called. This function must also be called before any other ADC driver APIs.

§ ADC_open()

ADC_Handle ADC_open	(	uint_least8_t	index,
		ADC_Params *	params
	)

Function to initialize the ADC peripheral.

Function to initialize the ADC peripheral specified by the particular index value.

Precondition: ADC_init() has been called

Parameters

index	Logical peripheral number for the ADC indexed into the ADC_config table
params	Pointer to an parameter block, if NULL it will use default values. All the fields in this structure are RO (read-only).

Returns: A ADC_Handle on success or a NULL on an error or if it has been opened already.

See also: ADC_init(); ADC_close()

§ ADC_Params_init()

void ADC_Params_init ( ADC_Params * params )

Function to initialize the ADC_Params struct to its defaults.

Parameters

params An pointer to ADC_Params structure for initialization

Defaults values are: custom = NULL

Detailed Description

Operation

Opening the driver

Converting

Implementation

Instrumentation

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

§ ADC_convertRawToMicroVolts

Typedef Documentation

§ ADC_Handle

§ ADC_Params

§ ADC_CloseFxn

§ ADC_ControlFxn

§ ADC_ConvertFxn

§ ADC_ConvertToMicroVoltsFxn

§ ADC_InitFxn

§ ADC_OpenFxn

§ ADC_FxnTable

§ ADC_Config

Function Documentation

§ ADC_close()

§ ADC_control()

§ ADC_convert()

§ ADC_convertToMicroVolts()

§ ADC_init()

§ ADC_open()

§ ADC_Params_init()