Comparator.h

Go to the documentation of this file.

/*
 * Copyright (c) 2022, Texas Instruments Incorporated
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * *  Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * *  Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * *  Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
/*!****************************************************************************
 *  @file       Comparator.h
 *  @brief      Comparator Driver
 *
 *  @anchor ti_drivers_comparator_Overview
 *  # 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.
 *
 *  <hr>
 *  @anchor ti_drivers_Comparator_Usage
 *  # Usage
 *
 *  This documentation provides a basic @ref ti_drivers_Comparator_Synopsis
 *  "usage summary" and a set of @ref ti_drivers_Comparator_Examples "examples"
 *  in the form of commented code fragments. Detailed descriptions of the
 *  APIs are provided in subsequent sections.
 *
 *  @anchor ti_drivers_Comparator_Synopsis
 *  ## 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.
 *
 *  @anchor ti_drivers_Comparator_Synopsis_Code
 *
 *  @code
 *
 *  #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);
 *  }
 *
 *  @endcode
 *
 *  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.
 *
 *  <hr>
 *  @anchor ti_drivers_Comparator_Examples
 *  # Examples
 *
 *  @li @ref ti_drivers_Comparator_Examples_open "Opening a Comparator instance"
 *
 *  @anchor ti_drivers_Comparator_Examples_open
 *  ## Opening a Comparator instance
 *
 *  @code
 *  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) {}
 *  }
 *  @endcode
 *
 *  <hr>
 *  @anchor ti_drivers_Comparator_Configuration
 *  # Configuration
 *
 *  Refer to the @ref driver_configuration "Driver's Configuration" section
 *  for driver configuration information.
 *  <hr>
 *
 ******************************************************************************
 */

#ifndef ti_drivers_Comparator__include
#define ti_drivers_Comparator__include

#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

#define Comparator_STATUS_RESERVED (-32)

#define Comparator_STATUS_SUCCESS (0)

#define Comparator_STATUS_ERROR (-1)

typedef struct Comparator_Config *Comparator_Handle;

typedef enum
{
    Comparator_OUTPUT_HIGH,         
    Comparator_OUTPUT_LOW,          
    Comparator_OUTPUT_NOT_AVAILABLE 
} Comparator_OutputLevel;

typedef enum
{
    Comparator_TRIGGER_NONE,   
    Comparator_TRIGGER_RISING, 
    Comparator_TRIGGER_FALLING 
} Comparator_Trigger;

typedef void (*Comparator_CallBackFxn)(Comparator_Handle handle, int_fast16_t returnValue, Comparator_Trigger trigger);

typedef struct
{
    Comparator_CallBackFxn callbackFxn;

    Comparator_Trigger trigger;
} Comparator_Params;

typedef void (*Comparator_CloseFxn)(Comparator_Handle handle);

typedef Comparator_OutputLevel (*Comparator_GetLevelFxn)(Comparator_Handle handle);

typedef Comparator_Trigger (*Comparator_getTriggerFxn)(Comparator_Handle handle);

typedef void (*Comparator_InitFxn)(Comparator_Handle handle);

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

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

typedef int_fast16_t (*Comparator_StartFxn)(Comparator_Handle handle);

typedef void (*Comparator_StopFxn)(Comparator_Handle handle);

typedef struct
{
    Comparator_CloseFxn closeFxn;

    Comparator_GetLevelFxn getLevelFxn;

    Comparator_getTriggerFxn getTriggerFxn;

    Comparator_InitFxn initFxn;

    Comparator_OpenFxn openFxn;

    Comparator_setTriggerFxn setTriggerFxn;

    Comparator_StartFxn startFxn;

    Comparator_StopFxn stopFxn;
} Comparator_FxnTable;

typedef struct Comparator_Config
{
    Comparator_FxnTable const *fxnTablePtr;

    void *object;

    void const *hwAttrs;
} Comparator_Config;

extern const Comparator_Config Comparator_config[];

extern void Comparator_close(Comparator_Handle handle);

extern Comparator_OutputLevel Comparator_getLevel(Comparator_Handle handle);

extern Comparator_Trigger Comparator_getTrigger(Comparator_Handle handle);

extern void Comparator_init(void);

extern Comparator_Handle Comparator_open(uint32_t index, Comparator_Params *params);

extern void Comparator_Params_init(Comparator_Params *params);

extern int_fast16_t Comparator_setTrigger(Comparator_Handle handle, Comparator_Trigger trigger);

extern int_fast16_t Comparator_start(Comparator_Handle handle);

extern void Comparator_stop(Comparator_Handle handle);

#ifdef __cplusplus
}
#endif

#endif /* ti_drivers_Comparator__include */