Comparator Driver.
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.
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.
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:
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.
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.
Refer to the Driver's Configuration section for driver configuration information.
#include <stdint.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... | |
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 struct Comparator_Config* Comparator_Handle |
A handle that is returned from a Comparator_open() call.
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.
[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:
|
[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:
|
typedef void(* Comparator_CloseFxn) (Comparator_Handle handle) |
A function pointer to a driver specific implementation of Comparator_close().
typedef Comparator_OutputLevel(* Comparator_GetLevelFxn) (Comparator_Handle handle) |
A function pointer to a driver specific implementation of Comparator_getLevel().
typedef Comparator_Trigger(* Comparator_getTriggerFxn) (Comparator_Handle handle) |
A function pointer to a driver specific implementation of Comparator_getLevel().
typedef void(* Comparator_InitFxn) (Comparator_Handle handle) |
A function pointer to a driver specific implementation of Comparator_init().
typedef Comparator_Handle(* Comparator_OpenFxn) (Comparator_Handle handle, Comparator_Params *params) |
A function pointer to a driver specific implementation of Comparator_open().
typedef int_fast16_t(* Comparator_setTriggerFxn) (Comparator_Handle handle, Comparator_Trigger trigger) |
A function pointer to a driver specific implementation of Comparator_open().
typedef int_fast16_t(* Comparator_StartFxn) (Comparator_Handle handle) |
A function pointer to a driver specific implementation of Comparator_start().
typedef void(* Comparator_StopFxn) (Comparator_Handle handle) |
A function pointer to a driver specific implementation of Comparator_stop().
typedef struct Comparator_Config Comparator_Config |
Comparator driver's custom configuration structure.
Comparator output level.
This enum defines the level of the output.
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.
void Comparator_close | ( | Comparator_Handle | handle | ) |
Function to close a Comparator driver instance.
[in] | handle | A Comparator_Handle returned from Comparator_open() |
Comparator_OutputLevel Comparator_getLevel | ( | Comparator_Handle | handle | ) |
Function which returns the level of the comparator output.
[in] | handle | A Comparator handle returned from Comparator_open(). |
Comparator_Trigger Comparator_getTrigger | ( | Comparator_Handle | handle | ) |
Function to get the interrupt trigger of the comparator instance.
[in] | handle | A Comparator_Handle returned from Comparator_open(). |
void Comparator_init | ( | void | ) |
Function to initialize the Comparator driver.
This function must also be called before any other Comparator driver APIs.
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.
[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. |
void Comparator_Params_init | ( | Comparator_Params * | params | ) |
Initialize an Comparator_Params structure to its default values.
[in] | params | A pointer to an Comparator_Params structure. |
Default values are:
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.
[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. |
Comparator_STATUS_SUCCESS | The comparator trigger have been succesfully modified. |
Comparator_STATUS_ERROR | An error occured. |
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().
[in] | handle | A Comparator_Handle returned from Comparator_open(). |
Comparator_STATUS_SUCCESS | The comparator successfully started. |
Comparator_STATUS_ERROR | The comparator failed to start. |
void Comparator_stop | ( | Comparator_Handle | handle | ) |
Function to stop a comparator instance. If the comparator instance is already stopped this function has no effect.
[in] | handle | A Comparator_Handle returned from Comparator_open(). |
const Comparator_Config Comparator_config[] |