Detailed Description

PRELIMINARY Comparator Driver Interface

WARNING These APIs are PRELIMINARY, and subject to change in the next few months.

Overview

The Comparator driver serves as the main interface for a typical RTOS application. Its purpose is to redirect the Comparator APIs to device specific implementations which are specified using a pointer to a Comparator_FxnTable. The device specific implementations are responsible for creating all the RTOS specific primitives to allow for thread-safe operation.

The Comparator driver is an analog driver that accepts a configuration of two analog input signals, compares those values, and then outputs high on the output signal if the positive input is more positive than that of the negative input terminal. This output signal can be configured in either inverted or non-inverted based off the user configuration.

Device specific capabilities such as output analog filters and programmable hysteresis are configured via the implementation specific hwAttrs configuration structure. This top level driver provides all APIs needed to provide a uniform and generic Comparator driver experience regardless of the underlying peripheral implementation.

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

The Comparator driver is used to monitor two input analog signals and generate an output if the potential of the positive input terminal is greater than that of the negative input channel. This is commonly used for power supply supervision as well as precision slope analog-to-digital conversions. The code below sets up two arbitrary input signals to the Comparator driver and handles triggers of the voltage crossing in the appropriate callback function.

The Comparator driver supports two distinct methods of accessing/utilizing the underlying comparator peripheral's output signal: accessing the output level dynamically and providing a user callback function.

Accessing the output level directly can be done by calling the Comparator_getLevel() API after the driver has been successfully opened and started. This function will return a Comparator_OUTPUT_HIGH if the positive input terminal is more positive than the negative terminal and Comparator_OUTPUT_LOW if the reverse is true. If the output level of the comparator peripheral cannot be determined or the device is in an error state a value of Comparator_OUTPUT_NOT_AVAILABLE is returned.

The user callback functionality provides a way for the Comparator driver and its underlying implementation to communicate functional events as well as errors to the calling user application. If a non-null function pointer is provided to the callbackFxn configuration parameter a call to the callback will be invoked whenever a relevant event occurs in the driver. Primarily this callback will be invoked when the output of the comparator is triggered (or inversely triggered), however error events can also be passed through this callback.

Note that these programming models are compatible with each other and can be mixed accordingly. For example a user callback can be provided and the Comparator_getLevel() API can be called in any scenario.

#include <ti/drivers/Comparator.h>
void comparatorCallback(Comparator_Handle handle, int32_t event)
{
    switch (event)
    {
    case Comparator_EVENT_OUTPUT_TRIGGERED:
        // Output triggered
        sem_post(&someSemaphore);
        break;
    case Comparator_EVENT_OUTPUT_INVERTED_TRIGGERED:
        // Output triggered in the other direction
        sem_post(&someSemaphore);
        break;
    case Comparator_EVENT_ERROR:
        __breakpoint(0);
        break;
    default:
        break;
    }
}
void someComparatorFunction()
{
    Comparator_Handle    handle;
    Comparator_Params    params;
    Comparator_Params_init(&params);
    params.callbackFxn = &comparatorCallback;
    params.interruptLevel = Comparator_INTERRUPT_RISING;
    handle = Comparator_open(CONFIG_COMPARATOR0, &params);
    if (handle == NULL)
    {
        //Comparator_open() failed
        while(1);
    }
    status = Comparator_start(handle);
    if (status == Comparator_STATUS_ERROR)
    {
        //Comparator_start() failed
        while(1);
    }
    // Waiting for some output event to signal from the callback
    sem_wait(&someSemaphore);
    Comparator_stop(handle);
}

Note that while the code above operates with a callback function provided, if a NULL value is given as the callbackFxn parameter the Comparator_getLevel() function can be invoked to dynamically get the output level of an initialized/started Comparator driver instance.

Examples

Opening a Comparator instance

Opening a Comparator instance

Comparator_Handle comparator;
Comparator_Params params;
Comparator_Params_init(&params);
comparator = Comparator_open(CONFIG_COMP0, &params);
if (comparator == NULL)
{
    // Comparator_open() failed
    while (1);
}

Configuration

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

#include <stdint.h>

Include dependency graph for Comparator.h:

Go to the source code of this file.

Data Structures
struct	Comparator_Params
	Comparator Parameters. More...

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

struct	Comparator_Config_
	Comparator driver's custom configuration structure. More...

Macros
#define	Comparator_STATUS_RESERVED (-32)

#define	Comparator_STATUS_SUCCESS (0)
	Successful status code. More...

#define	Comparator_STATUS_ERROR (-1)
	Generic error status code. More...

#define	Comparator_EVENT_RESERVED (32)


#define	Comparator_EVENT_OUTPUT_TRIGGERED (1)
	The comparator output triggered in the positive direction. More...

#define	Comparator_EVENT_OUTPUT_INVERTED_TRIGGERED (2)
	The comparator output triggered in the inverted direction. More...

#define	Comparator_EVENT_ERROR (-1)
	An error occurred with the underlying comparator driver. More...

Typedefs
typedef struct Comparator_Config_ *	Comparator_Handle
	A handle that is returned from a Comparator_open() call. More...

typedef void(*	Comparator_CallBackFxn) (Comparator_Handle handle, int32_t event)
	Comparator callback function. More...

typedef void(*	Comparator_CloseFxn) (Comparator_Handle handle)
	A function pointer to a driver specific implementation of Comparator_close(). More...

typedef uint32_t(*	Comparator_GetLevelFxn) (Comparator_Handle handle)
	A function pointer to a driver specific implementation of Comparator_getLevel(). More...

typedef void(*	Comparator_InitFxn) (Comparator_Handle handle)
	A function pointer to a driver specific implementation of Comparator_init(). More...

typedef Comparator_Handle(*	Comparator_OpenFxn) (Comparator_Handle handle, Comparator_Params *params)
	A function pointer to a driver specific implementation of Comparator_open(). More...

typedef int32_t(*	Comparator_StartFxn) (Comparator_Handle handle)
	A function pointer to a driver specific implementation of Comparator_start(). More...

typedef void(*	Comparator_StopFxn) (Comparator_Handle handle)
	A function pointer to a driver specific implementation of Comparator_stop(). More...

typedef int32_t(*	Comparator_GetParamsFxn) (Comparator_Handle handle, Comparator_Params *params)
	A function pointer to a driver specific implementation of Comparator_getParams(). More...

typedef int32_t(*	Comparator_SetParamsFxn) (Comparator_Handle handle, Comparator_Params *params)
	A function pointer to a driver specific implementation of Comparator_setParams(). More...

typedef struct Comparator_Config_	Comparator_Config
	Comparator driver's custom configuration structure. More...

Enumerations
enum	Comparator_OutputPolarity { Comparator_OUTPUT_NORMAL, Comparator_OUTPUT_INVERTED }
	Comparator Output Polarity. More...

enum	Comparator_OutputLevel { Comparator_OUTPUT_HIGH, Comparator_OUTPUT_LOW, Comparator_OUTPUT_NOT_AVAILABLE }
	Comparator Output Level. More...

enum	Comparator_InterruptLevel { Comparator_INTERRUPT_NONE, Comparator_INTERRUPT_RISING, Comparator_INTERRUPT_FALLING, Comparator_INTERRUPT_BOTH, Comparator_INTERRUPT_HIGH, Comparator_INTERRUPT_LOW }
	Comparator Interrupt Level. More...

Functions
void	Comparator_close (Comparator_Handle handle)
	Function to close a Comparator driver instance. More...

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

Comparator_OutputLevel	Comparator_getLevel (Comparator_Handle handle)
	Function returns the level of the comparator output. The output level correlates to the polarity specified by the parameter passed into the Comparator_Params.outputPolarity parameter while opening the device with Comparator_open(). More...

void	Comparator_init (void)
	Function to initialize the Comparator driver. More...

Comparator_Handle	Comparator_open (uint32_t index, Comparator_Params *params)
	Function to initialize the Comparator peripheral. More...

void	Comparator_Params_init (Comparator_Params *params)
	Function to initialize the Comparator_Params structure to its default values. More...

int32_t	Comparator_start (Comparator_Handle handle)
	Function to start the comparator instance. More...

void	Comparator_stop (Comparator_Handle handle)
	Function to stop a comparator instance. If the comparator instance is already stopped this function has no effect. More...

int32_t	Comparator_getParams (Comparator_Handle handle, Comparator_Params *params)
	Function to get the parameters of a comparator instance. More...

int32_t	Comparator_setParams (Comparator_Handle handle, Comparator_Params *params)
	Function to get the parameters of a comparator instance. More...

Typedef Documentation

§ Comparator_Handle

typedef struct Comparator_Config_* Comparator_Handle

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

§ Comparator_CallBackFxn

typedef void(* Comparator_CallBackFxn) (Comparator_Handle handle, int32_t event)

Comparator callback function.

Callback from the Comparator driver. This will be called when the driver is setup with a callback function pointer provided to the Comparator_Params.callbackFxn parameter and is used to communicate events and errors to the calling application.

Parameters

[out]	handle	Comparator_Handle
[out]	event	Events that can occur as part of the Comparator driver operation.

§ Comparator_CloseFxn

typedef void(* Comparator_CloseFxn) (Comparator_Handle handle)

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

§ Comparator_GetLevelFxn

typedef uint32_t(* Comparator_GetLevelFxn) (Comparator_Handle handle)

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

§ Comparator_InitFxn

typedef void(* Comparator_InitFxn) (Comparator_Handle handle)

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

§ Comparator_OpenFxn

typedef Comparator_Handle(* Comparator_OpenFxn) (Comparator_Handle handle, Comparator_Params *params)

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

§ Comparator_StartFxn

typedef int32_t(* Comparator_StartFxn) (Comparator_Handle handle)

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

§ Comparator_StopFxn

typedef void(* Comparator_StopFxn) (Comparator_Handle handle)

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

§ Comparator_GetParamsFxn

typedef int32_t(* Comparator_GetParamsFxn) (Comparator_Handle handle, Comparator_Params *params)

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

§ Comparator_SetParamsFxn

typedef int32_t(* Comparator_SetParamsFxn) (Comparator_Handle handle, Comparator_Params *params)

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

§ Comparator_Config

typedef struct Comparator_Config_ Comparator_Config

Comparator driver's custom configuration structure.

See also: Comparator_init()

Enumeration Type Documentation

§ Comparator_OutputPolarity

enum Comparator_OutputPolarity

Comparator Output Polarity.

This enum defines the polarity of the comparator output (inverted/normal)

Enumerator
Comparator_OUTPUT_NORMAL	Comparator output is normal (output logical one when the positive input terminal is more positive than the negative input terminal)
Comparator_OUTPUT_INVERTED	Comparator output is normal (output logical zero when the positive input terminal is more positive than the negative input terminal)

§ Comparator_OutputLevel

enum Comparator_OutputLevel

Comparator Output Level.

This enum defines the level of the output. This level has a direct correlation to the by the outputPolarity parameter passed into the Comparator_Params while opening the device with Comparator_open().

Enumerator
Comparator_OUTPUT_HIGH	Positive input terminal is more positive than the negative input terminal
Comparator_OUTPUT_LOW	Negative input terminal is more positive than the positive input terminal
Comparator_OUTPUT_NOT_AVAILABLE	Output level cannot be determined (possibly due to error or it not being ready)

§ Comparator_InterruptLevel

enum Comparator_InterruptLevel

Comparator Interrupt Level.

This enum defines the comparator output condition that will trigger an interrupt. Not all output conditions are supported on all devices, refer to the device documentation to see which interrupt levels are supported.

Enumerator
Comparator_INTERRUPT_NONE	The comparator module should not trigger an interrupt
Comparator_INTERRUPT_RISING	A rising edge on the comparator output will trigger an interrupt
Comparator_INTERRUPT_FALLING	A falling edge on the comparator output will trigger an interrupt
Comparator_INTERRUPT_BOTH	Either a rising or falling edge on the comparator output will trigger an interrupt
Comparator_INTERRUPT_HIGH	A high comparator output will trigger an interrupt
Comparator_INTERRUPT_LOW	A low comparator output will trigger an interrupt

Function Documentation

§ Comparator_close()

void Comparator_close ( Comparator_Handle handle )

Function to close a Comparator driver instance.

Precondition: Comparator_open() has been called.

Parameters

[in] handle A Comparator_Handle returned from Comparator_open().

See also: Comparator_open()

§ Comparator_control()

int_fast16_t Comparator_control	(	Comparator_Handle	handle,
		uint_fast16_t	cmd,
		void *	arg
	)

Function performs implementation specific features on a given Comparator_Handle.

Precondition: Comparator_open() has been called.

Parameters

[in]	handle	A Comparator_Handle returned from Comparator_open().
[in]	cmd	A command value defined by the driver specific implementation.
[in]	arg	A pointer to an optional R/W (read/write) argument that is accompanied with cmd.

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

§ Comparator_getLevel()

Comparator_OutputLevel Comparator_getLevel ( Comparator_Handle handle )

Function returns the level of the comparator output. The output level correlates to the polarity specified by the parameter passed into the Comparator_Params.outputPolarity parameter while opening the device with Comparator_open().

Precondition: Comparator_open() and Comparator_start() have been called.

Parameters

[in] handle A Comparator handle returned from Comparator_open().

Returns: A value of type Comparator_OutputLevel describing the output state of the comparator peripheral.

See also: Comparator_start()

§ Comparator_init()

void Comparator_init ( void )

Function to initialize the Comparator driver.

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

§ Comparator_open()

Comparator_Handle Comparator_open	(	uint32_t	index,
		Comparator_Params *	params
	)

Function to initialize the Comparator peripheral.

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

Precondition: Comparator_init() has been called.

Parameters

[in]	index	Index in the `Comparator_Config`[] array.
[in]	params	Pointer to an initialized Comparator_Params structure. If NULL, the default Comparator_Params values are used.

Returns: A Comparator_Handle on success or NULL on an error.

See also: Comparator_init(); Comparator_close()

§ Comparator_Params_init()

void Comparator_Params_init ( Comparator_Params * params )

Function to initialize the Comparator_Params structure to its default values.

Parameters

[in] params A pointer to Comparator_Params structure for initialization.

Defaults values are:

Comparator_Params.callbackFxn = NULL
Comparator_Params.outputPolarity = Comparator_OUTPUT_NORMAL

§ Comparator_start()

int32_t Comparator_start ( Comparator_Handle handle )

Function to start the comparator instance.

Precondition: Comparator_open() has been called.

Parameters

[in] handle A Comparator_Handle returned from Comparator_open().

Return values

Comparator_STATUS_SUCCESS	The comparator successfully started.
Comparator_STATUS_ERROR	The comparator failed to start.

See also: Comparator_stop()

§ Comparator_stop()

void Comparator_stop ( Comparator_Handle handle )

Function to stop a comparator instance. If the comparator instance is already stopped this function has no effect.

Precondition: Comparator_open() has been called.

Parameters

[in] handle A Comparator_Handle returned from Comparator_open().

See also: Comparator_start()

§ Comparator_getParams()

int32_t Comparator_getParams	(	Comparator_Handle	handle,
		Comparator_Params *	params
	)

Function to get the parameters of a comparator instance.

Precondition: Comparator_open() has been called

Parameters

[in]	handle	A Comparator_Handle returned from Comparator_open().
[in]	params	A pointer to a Comparator_Params structure to be filled with the current comparator settings.

Return values

Comparator_STATUS_SUCCESS	The params were obtained successfully.
Comparator_STATUS_ERROR	The params were unable to be obtained.

See also: Comparator_getParams()

§ Comparator_setParams()

int32_t Comparator_setParams	(	Comparator_Handle	handle,
		Comparator_Params *	params
	)

Function to get the parameters of a comparator instance.

Precondition: Comparator_open() has been called

Parameters

[in]	handle	A Comparator_Handle returned from Comparator_open().
[in]	params	A pointer to a Comparator_Params structure holding the new comparator settings.

Return values

Comparator_STATUS_SUCCESS	The params were set successfully.
Comparator_STATUS_ERROR	The params were unable to be set.

See also: Comparator_setParams()

Detailed Description

Overview

Usage

Synopsis

Examples

Opening a Comparator instance

Configuration

Data Structures

Macros

Typedefs

Enumerations

Functions

Typedef Documentation

§ Comparator_Handle

§ Comparator_CallBackFxn

§ Comparator_CloseFxn

§ Comparator_GetLevelFxn

§ Comparator_InitFxn

§ Comparator_OpenFxn

§ Comparator_StartFxn

§ Comparator_StopFxn

§ Comparator_GetParamsFxn

§ Comparator_SetParamsFxn

§ Comparator_Config

Enumeration Type Documentation

§ Comparator_OutputPolarity

§ Comparator_OutputLevel

§ Comparator_InterruptLevel

Function Documentation

§ Comparator_close()

§ Comparator_control()

§ Comparator_getLevel()

§ Comparator_init()

§ Comparator_open()

§ Comparator_Params_init()

§ Comparator_start()

§ Comparator_stop()

§ Comparator_getParams()

§ Comparator_setParams()