Comparator.h

Go to the documentation of this file.

/*
 * Copyright (c) 2019, 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      <b>PRELIMINARY</b> Comparator Driver Interface
 *
 *  <b>WARNING</b> These APIs are <b>PRELIMINARY</b>, and subject to
 *  change in the next few months.
 *
 *  @anchor ti_drivers_Comparator_Overview
 *  # 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.
  *
 *  <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 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.
 *
 *  @anchor ti_drivers_Comparator_Synopsis_Code
 *
 *  @code
 *
 *  #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);
 *  }
 *
 *  @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_COMP0, &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)

#define Comparator_EVENT_RESERVED                    (32)

#define Comparator_EVENT_OUTPUT_TRIGGERED             (1)

#define Comparator_EVENT_OUTPUT_INVERTED_TRIGGERED    (2)

#define Comparator_EVENT_ERROR                        (-1)

typedef struct Comparator_Config_ *Comparator_Handle;

typedef enum
{
    Comparator_OUTPUT_NORMAL,   
    Comparator_OUTPUT_INVERTED, 
} Comparator_OutputPolarity;

typedef enum
{
    Comparator_OUTPUT_HIGH,           
    Comparator_OUTPUT_LOW,            
    Comparator_OUTPUT_NOT_AVAILABLE, 
} Comparator_OutputLevel;

typedef enum
{
    Comparator_INTERRUPT_NONE,          
    Comparator_INTERRUPT_RISING,        
    Comparator_INTERRUPT_FALLING,       
    Comparator_INTERRUPT_BOTH,          
    Comparator_INTERRUPT_HIGH,          
    Comparator_INTERRUPT_LOW            
} Comparator_InterruptLevel;

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

typedef struct
{
    Comparator_CallBackFxn callbackFxn;

    Comparator_OutputPolarity outputPolarity;

    Comparator_InterruptLevel interruptLevel;

} Comparator_Params;

typedef void (*Comparator_CloseFxn)(Comparator_Handle handle);

typedef uint32_t (*Comparator_GetLevelFxn)(Comparator_Handle handle);

typedef void (*Comparator_InitFxn)(Comparator_Handle handle);

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

typedef int32_t (*Comparator_StartFxn)(Comparator_Handle handle);

typedef void (*Comparator_StopFxn)(Comparator_Handle handle);

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

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

typedef struct
{
    Comparator_CloseFxn closeFxn;

    Comparator_GetLevelFxn getLevelFxn;

    Comparator_InitFxn initFxn;

    Comparator_OpenFxn openFxn;

    Comparator_StartFxn startFxn;

    Comparator_StopFxn stopFxn;

    Comparator_GetParamsFxn getParamsFxn;

    Comparator_SetParamsFxn setParamsFxn;
} Comparator_FxnTable;

typedef struct Comparator_Config_
{
    Comparator_FxnTable const *fxnTablePtr;

    void *object;

    void const *hwAttrs;
} Comparator_Config;

extern void Comparator_close(Comparator_Handle handle);

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

extern Comparator_OutputLevel Comparator_getLevel(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 int32_t Comparator_start(Comparator_Handle handle);

extern void Comparator_stop(Comparator_Handle handle);

extern int32_t Comparator_getParams(Comparator_Handle handle,
                                    Comparator_Params *params);

extern int32_t Comparator_setParams(Comparator_Handle handle,
                                    Comparator_Params *params);

#ifdef __cplusplus
}
#endif

#endif /* ti_drivers_Comparator__include */