Detailed Description

Comparator Driver.

Overview

The comparator driver allows you to manage the voltage comparator peripheral via simple and portable APIs. This driver supports monitoring of analog voltages on external pins to allow event generation when the voltage crosses a defined threshold.

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.

Device-specific capabilities such as input voltage division or output analog filtering 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 (internal or external) 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:

Returning the output level on request.
Providing a user callback function invoked upon a Comparator trigger event.

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 opposite 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 events to the calling user application. The user callback is selected through the Comparator_Params.callbackFxn field. If a non-null function pointer is provided to the callbackFxn configuration parameter, 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, however error events can also be passed through this callback. Since the user's callback may be called in the context of a hardware interrupt, the callback function must not make any RTOS blocking calls.

Note that accessing the output level is compatible with callback mode and can be mixed accordingly. For example a user callback can be provided and the Comparator_getLevel() API can still be called when needed.

#include <ti/drivers/Comparator.h>
void comparatorCallback(Comparator_Handle handle,
                        int_fast16_t returnValue,
                        Comparator_Trigger trigger)
{
    // React to Comparator event
    sem_post(&someSemaphore);
}
void someComparatorFunction()
{
    Comparator_Handle    handle;
    Comparator_Params    params;
    Comparator_Params_init(&params);
    params.callbackFxn = &comparatorCallback;
    params.trigger     = Comparator_TRIGGER_RISING;
    handle = Comparator_open(CONFIG_COMPARATOR_0, &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_COMPARATOR_0, &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:

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

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

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, int_fast16_t returnValue, Comparator_Trigger trigger)
	Comparator callback function. More...

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

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

typedef Comparator_Trigger(*	Comparator_getTriggerFxn) (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 int_fast16_t(*	Comparator_setTriggerFxn) (Comparator_Handle handle, Comparator_Trigger trigger)
	A function pointer to a driver specific implementation of Comparator_open(). More...

typedef int_fast16_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 struct Comparator_Config	Comparator_Config
	Comparator driver's custom configuration structure. More...

Enumerations
enum	Comparator_OutputLevel { Comparator_OUTPUT_HIGH, Comparator_OUTPUT_LOW, Comparator_OUTPUT_NOT_AVAILABLE }
	Comparator output level. More...

enum	Comparator_Trigger { Comparator_TRIGGER_NONE, Comparator_TRIGGER_RISING, Comparator_TRIGGER_FALLING }
	Comparator interrupt trigger. More...

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

Comparator_OutputLevel	Comparator_getLevel (Comparator_Handle handle)
	Function which returns the level of the comparator output. More...

Comparator_Trigger	Comparator_getTrigger (Comparator_Handle handle)
	Function to get the interrupt trigger of the comparator instance. 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)
	Initialize an Comparator_Params structure to its default values. More...

int_fast16_t	Comparator_setTrigger (Comparator_Handle handle, Comparator_Trigger trigger)
	Function to set at run-time the interrupt trigger. More...

int_fast16_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...

Variables
const Comparator_Config	Comparator_config []

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, int_fast16_t returnValue, Comparator_Trigger trigger)

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 to the calling application.

Parameters

[in]	handle	The handle of the Comparator instance that generated the callback.
[in]	returnValue	The result of the Comparator operation. Depending on the device-specific implementation it may contain an error code. Informs the application of why the callback function was called. The generic return values, common to all implementations, are listed below: Comparator_STATUS_SUCCESS Comparator_STATUS_ERROR

Note: Refer to the device-specific implementation header file for additional status codes.

Parameters

[in]

trigger

The trigger currently selected for the Comparator instance that generated the callback. The supported trigger values that can be received by the callback function are:

Comparator_TRIGGER_NONE
Comparator_TRIGGER_FALLING
Comparator_TRIGGER_RISING

Note: When Comparator_TRIGGER_NONE is selected, a callback can only be invoked due to a comparator error, on devices supporting this type of return value.

§ Comparator_CloseFxn

typedef void(* Comparator_CloseFxn) (Comparator_Handle handle)

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

§ Comparator_GetLevelFxn

typedef Comparator_OutputLevel(* Comparator_GetLevelFxn) (Comparator_Handle handle)

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

§ Comparator_getTriggerFxn

typedef Comparator_Trigger(* Comparator_getTriggerFxn) (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_setTriggerFxn

typedef int_fast16_t(* Comparator_setTriggerFxn) (Comparator_Handle handle, Comparator_Trigger trigger)

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

§ Comparator_StartFxn

typedef int_fast16_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_Config

typedef struct Comparator_Config Comparator_Config

Comparator driver's custom configuration structure.

See also: Comparator_init()

Enumeration Type Documentation

§ Comparator_OutputLevel

enum Comparator_OutputLevel

Comparator output level.

This enum defines the level of the output.

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_Trigger

enum Comparator_Trigger

Comparator interrupt trigger.

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_TRIGGER_NONE	The comparator module should not trigger an interrupt
Comparator_TRIGGER_RISING	A rising edge on the comparator output will trigger an interrupt
Comparator_TRIGGER_FALLING	A falling edge on the 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()

§ Comparator_getLevel()

Comparator_OutputLevel Comparator_getLevel ( Comparator_Handle handle )

Function which returns the level of the comparator output.

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_getTrigger()

Comparator_Trigger Comparator_getTrigger ( Comparator_Handle handle )

Function to get the interrupt trigger of the comparator instance.

Precondition: Comparator_open() has been called.

Parameters

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

Returns: A value of type Comparator_Trigger describing the output condition of the comparator that will generate an interrupt.

See also: Comparator_getTrigger()

§ 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. Comparator_open() will only setup the Comparator instance but it will not enable it. It is required to subsequently call Comparator_start() to make the instance operational.

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 error.

See also: Comparator_init(); Comparator_close()

§ Comparator_Params_init()

void Comparator_Params_init ( Comparator_Params * params )

Initialize an Comparator_Params structure to its default values.

Parameters

[in] params A pointer to an Comparator_Params structure.

Default values are:

Comparator_Params.callbackFxn = NULL
Comparator_Params.trigger = Comparator_TRIGGER_RISING

§ Comparator_setTrigger()

int_fast16_t Comparator_setTrigger	(	Comparator_Handle	handle,
		Comparator_Trigger	trigger
	)

Function to set at run-time the interrupt trigger.

This functions sets the Comparator trigger at run-time. In case the comparator is running, following a call to Comparator_start(), this function will temporarily stop the Comparator instance, modify the trigger value and then restart it once again.

Precondition: Comparator_open() has been called.

Parameters

[in]	handle	A Comparator_Handle returned from Comparator_open().
[in]	trigger	A value of type Comparator_Trigger describing the output condition of the comparator that will generate an interrupt.

Return values

Comparator_STATUS_SUCCESS	The comparator trigger have been succesfully modified.
Comparator_STATUS_ERROR	An error occured.

Note: The return codes listed above are generic and common to all implementations. Refer to the device-specific implementation header file for additional status codes.

See also: Comparator_getTrigger()

§ Comparator_start()

int_fast16_t Comparator_start ( Comparator_Handle handle )

Function to start the comparator instance.

This function enables the Comparator instance. After this function has been called the Comparator will start generating a valid output and events. After Comparator_start has been called, the Comparator's output can be read using Comparator_getLevel().

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.

Note: The return codes listed above are generic and common to all implementations. Refer to the device-specific implementation header file for additional status codes.

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()

Variable Documentation

§ Comparator_config

const Comparator_Config Comparator_config[]

Detailed Description

Overview

Usage

Synopsis

Examples

Opening a Comparator instance

Configuration

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Typedef Documentation

§ Comparator_Handle

§ Comparator_CallBackFxn

§ Comparator_CloseFxn

§ Comparator_GetLevelFxn

§ Comparator_getTriggerFxn

§ Comparator_InitFxn

§ Comparator_OpenFxn

§ Comparator_setTriggerFxn

§ Comparator_StartFxn

§ Comparator_StopFxn

§ Comparator_Config

Enumeration Type Documentation

§ Comparator_OutputLevel

§ Comparator_Trigger

Function Documentation

§ Comparator_close()

§ Comparator_getLevel()

§ Comparator_getTrigger()

§ Comparator_init()

§ Comparator_open()

§ Comparator_Params_init()

§ Comparator_setTrigger()

§ Comparator_start()

§ Comparator_stop()

Variable Documentation

§ Comparator_config