ADCBuf.h

Go to the documentation of this file.

/*
 * Copyright (c) 2016-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       ADCBuf.h
 *  @brief      Analog to Digital Conversion Buffer (ADCBuf) Input Driver
 *
 *  @anchor ti_drivers_ADCBuf_Overview
 *  # Overview
 *
 *  The ADCBuf driver allows you to sample and convert analog signals
 *  at a specified frequency. The resulting samples are placed in
 *  a buffer provided by the application. The driver can either take @p N
 *  samples once or continuously sample by double-buffering and providing a
 *  callback to process each finished buffer.
 *
 *  <hr>
 *  @anchor ti_drivers_ADCBuf_Usage
 *  # Usage
 *
 *  This documentation provides a basic @ref ti_drivers_ADCBuf_Synopsis
 *  "usage summary" and a set of @ref ti_drivers_ADCBuf_Examples "examples"
 *  in the form of commented code fragments. Detailed descriptions of the
 *  APIs are provided in subsequent sections.
 *
 *  @anchor ti_drivers_ADCBuf_Synopsis
 *  ## Synopsis
 *  @anchor ti_drivers_ADCBuf_Synopsis_Code
 *  @code
 *  // Import ADCBuf Driver definitions
 *  #include <ti/drivers/ADCBuf.h>
 *
 *  // Define name for ADCBuf channel index
 *  #define PIEZOMETER_OUT    0
 *
 *  // Create buffer for samples
 *  #define ADCBUFFERSIZE     10
 *  uint16_t buffer[ADCBUFFERSIZE];
 *  uint32_t microvoltBuffer[ADCBUFFERSIZE];
 *
 *  // One time init of ADCBuf driver
 *  ADCBuf_init();
 *
 *  // Initialize optional ADCBuf parameters
 *  ADCBuf_Params params;
 *  ADCBuf_Params_init(&params);
 *  params.returnMode = ADCBuf_RETURN_MODE_BLOCKING;
 *  params.recurrenceMode = ADCBuf_RECURRENCE_MODE_ONE_SHOT;
 *
 *  // Open ADCBuf driver
 *  adcBuf = ADCBuf_open(CONFIG_ADCBUF0, &params);
 *
 *  // Setup conversion structure
 *  ADCBuf_Conversion conversion = {0};
 *  conversion.samplesRequestedCount = ADCBUFFERSIZE;
 *  conversion.sampleBuffer = buffer;
 *  conversion.adcChannel = PIEZOMETER_OUT;
 *
 *  // Start ADCBuf conversion
 *  ADCBuf_convert(adcBuf, &conversion, 1)
 *
 *  // Adjust raw ADC values and convert them to microvolts
 *  ADCBuf_adjustRawValues(handle, buffer, ADCBUFFERSIZE, PIEZOMETER_OUT);
 *  ADCBuf_convertAdjustedToMicroVolts(handle, PIEZOMETER_OUT, buffer,
 *                                     microvoltBuffer, ADCBUFFERSIZE);
 *
 *  // Close ADCBuf driver
 *  ADCBuf_close(adcbuf);
 *  @endcode
 *
 *  <hr>
 *  @anchor ti_drivers_ADCBuf_Examples
 *  # Examples
 *
 *  @li @ref ti_drivers_ADCBuf_Examples_open "Opening an ADCBuf instance"
 *  @li @ref ti_drivers_ADCBuf_Examples_blocking "Using a blocking conversion"
 *  @li @ref ti_drivers_ADCBuf_Examples_callback "Using a callback conversion"
 *
 *  @anchor ti_drivers_ADCBuf_Examples_open
 *  ## Opening an ADCBuf instance
 *
 *  @code
 *  ADCBuf_Handle adcBufHandle;
 *  ADCBuf_Params adcBufParams;
 *
 *  ADCBuf_init();
 *
 *  ADCBuf_Params_init(&adcBufParams);
 *
 *  adcBufHandle = ADCBuf_open(0, &adcBufParams);
 *  if (adcBufHandle == NULL)
 *  {
 *      //ADCBuf_open() failed.
 *      while (1) {}
 *  }
 *  @endcode
 *
 *  @anchor ti_drivers_ADCBuf_Examples_blocking
 *  ## Using a blocking conversion
 *
 *  @code
 *  ADCBuf_Handle adcbuf;
 *  ADCBuf_Params params;
 *
 *  ADCBuf_init();
 *
 *  ADCBuf_Params_init(&params);
 *  params.returnMode = ADCBuf_RETURN_MODE_BLOCKING;
 *  params.recurrenceMode = ADCBuf_RECURRENCE_MODE_ONE_SHOT;
 *  adcbuf = ADCBuf_open(0, &params);
 *  if (adcbuf != NULL)
 *  {
 *      ADCBuf_Conversion conversion = {0};
 *      conversion.adcChannel = PIEZOMETER_OUT;
 *      conversion.sampleBuffer = buffer;
 *      conversion.samplesRequestedCount = ADCBUFFERSIZE;
 *
 *      if (ADCBuf_convert(adcbuf, &conversion, 1) != ADCBuf_STATUS_SUCCESS)
 *      {
 *          // ADCBuf_conver() failed
 *      }
 *  }
 *  @endcode
 *
 *  @anchor ti_drivers_ADCBuf_Examples_callback
 *  ## Using a callback conversion
 *
 *  @code
 *  // ADCBuf callback function
 *  void adcBufCallbackFxn(ADCBuf_Handle handle, ADCBuf_Conversion *conversion,
 *                         void *buffer, uint32_t channel);
 *
 *  main()
 *  {
 *      ADCBuf_Handle adcbuf;
 *      ADCBuf_Params params;
 *
 *      ADCBuf_init();
 *
 *      ADCBuf_Params_init(&params);
 *      params.returnMode = ADCBuf_RETURN_MODE_CALLBACK;
 *      params.recurrenceMode = ADCBuf_RECURRENCE_MODE_ONE_SHOT;
 *      params.callbackFxn = adcBufCallbackFxn;
 *      adcbuf = ADCBuf_open(0, &params);
 *
 *      ADCBuf_Conversion conversion = {0};
 *      conversion.adcChannel = PIEZOMETER_OUT;
 *      conversion.sampleBuffer = buffer;
 *      conversion.samplesRequestedCount = ADCBUFFERSIZE;
 *
 *      if (ADCBuf_convert(adcbuf, &conversion, 1) != ADCBuf_STATUS_SUCCESS)
 *      {
 *          // ADCBuf_convert() failed
 *      }
 *
 *      // Pend on a semaphore
 *  }
 *
 *  void adcBufCallbackFxn(ADCBuf_Handle handle, ADCBuf_Conversion *conversion,
 *      void *buffer, uint32_t channel)
 *  {
 *      // Adjust raw ADC values and convert them to microvolts
 *      ADCBuf_adjustRawValues(handle, buffer, ADCBUFFERSIZE,
 *          channel);
 *      ADCBuf_convertAdjustedToMicroVolts(handle, channel,
 *          buffer, microvoltBuffer, ADCBUFFERSIZE);
 *
 *      // Post a semaphore
 *  }
 *
 *  @endcode
 *
 *  <hr>
 *  @anchor ti_drivers_ADCBuf_Configuration
 *  # Configuration
 *
 *  Refer to the @ref driver_configuration "Driver's Configuration" section
 *  for driver configuration information.
 *  <hr>
 ******************************************************************************
 */

#ifndef ti_drivers_adcbuf__include
#define ti_drivers_adcbuf__include

#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

#define ADCBuf_CMD_RESERVED             (32)

#define ADCBuf_STATUS_RESERVED          (-32)

#define ADCBuf_STATUS_SUCCESS           (0)

#define ADCBuf_STATUS_ERROR             (-1)

#define ADCBuf_STATUS_UNDEFINEDCMD      (-2)

#define ADCBuf_STATUS_UNSUPPORTED      (-3)

/* Add ADCBuf_CMD_<commands> here */

typedef struct ADCBuf_Config_ *ADCBuf_Handle;

typedef struct
{
    uint16_t samplesRequestedCount;

    void     *sampleBuffer;

    void     *sampleBufferTwo;

    void     *arg;

    uint32_t adcChannel;
} ADCBuf_Conversion;

typedef void (*ADCBuf_Callback) (ADCBuf_Handle handle,
                                 ADCBuf_Conversion *conversion,
                                 void *completedADCBuffer,
                                 uint32_t completedChannel);

typedef enum
{
    ADCBuf_RECURRENCE_MODE_ONE_SHOT,

    ADCBuf_RECURRENCE_MODE_CONTINUOUS
} ADCBuf_Recurrence_Mode;

typedef enum
{
    ADCBuf_RETURN_MODE_BLOCKING,

    ADCBuf_RETURN_MODE_CALLBACK
} ADCBuf_Return_Mode;

typedef struct
{
    uint32_t               blockingTimeout;

    uint32_t               samplingFrequency;

    ADCBuf_Return_Mode     returnMode;

    ADCBuf_Callback        callbackFxn;

    ADCBuf_Recurrence_Mode recurrenceMode;

    void *custom;
} ADCBuf_Params;

typedef void (*ADCBuf_CloseFxn) (ADCBuf_Handle handle);

typedef ADCBuf_Handle (*ADCBuf_OpenFxn) (ADCBuf_Handle handle,
                                         const ADCBuf_Params *params);

typedef int_fast16_t (*ADCBuf_ControlFxn) (ADCBuf_Handle handle,
                                           uint_fast8_t cmd,
                                           void *arg);
typedef void (*ADCBuf_InitFxn) (ADCBuf_Handle handle);

typedef int_fast16_t (*ADCBuf_ConvertFxn) (ADCBuf_Handle handle,
                                           ADCBuf_Conversion conversions[],
                                           uint_fast8_t channelCount);
typedef int_fast16_t (*ADCBuf_ConvertCancelFxn)(ADCBuf_Handle handle);

typedef uint_fast8_t (*ADCBuf_GetResolutionFxn) (ADCBuf_Handle handle);

typedef int_fast16_t (*ADCBuf_adjustRawValuesFxn)(ADCBuf_Handle handle,
                                                  void *sampleBuffer,
                                                  uint_fast16_t sampleCount,
                                                  uint32_t adcChannel);

typedef int_fast16_t (*ADCBuf_convertAdjustedToMicroVoltsFxn) (
                                               ADCBuf_Handle handle,
                                               uint32_t adcChannel,
                                               void *adjustedSampleBuffer,
                                               uint32_t outputMicroVoltBuffer[],
                                               uint_fast16_t sampleCount);

typedef struct
{
    ADCBuf_CloseFxn                       closeFxn;
    ADCBuf_ControlFxn                     controlFxn;
    ADCBuf_InitFxn                        initFxn;
    ADCBuf_OpenFxn                        openFxn;
    ADCBuf_ConvertFxn                     convertFxn;
    ADCBuf_ConvertCancelFxn               convertCancelFxn;
    ADCBuf_GetResolutionFxn               getResolutionFxn;
    ADCBuf_adjustRawValuesFxn             adjustRawValuesFxn;
    ADCBuf_convertAdjustedToMicroVoltsFxn convertAdjustedToMicroVoltsFxn;
} ADCBuf_FxnTable;

typedef struct ADCBuf_Config_
{
    const ADCBuf_FxnTable *fxnTablePtr;

    void                  *object;

    void const            *hwAttrs;
} ADCBuf_Config;

extern void ADCBuf_close(ADCBuf_Handle handle);

extern int_fast16_t ADCBuf_control(ADCBuf_Handle handle,
                                   uint_fast16_t cmd,
                                   void *cmdArg);

extern void ADCBuf_init(void);

extern void ADCBuf_Params_init(ADCBuf_Params *params);

extern ADCBuf_Handle ADCBuf_open(uint_least8_t index, ADCBuf_Params *params);

extern int_fast16_t ADCBuf_convert(ADCBuf_Handle handle,
                                   ADCBuf_Conversion conversions[],
                                   uint_fast8_t channelCount);

extern int_fast16_t ADCBuf_convertCancel(ADCBuf_Handle handle);

extern uint_fast8_t ADCBuf_getResolution(ADCBuf_Handle handle);

extern int_fast16_t ADCBuf_adjustRawValues(ADCBuf_Handle handle,
                                           void *sampleBuf,
                                           uint_fast16_t sampleCount,
                                           uint32_t adcChan);

extern int_fast16_t ADCBuf_convertAdjustedToMicroVolts(
                                            ADCBuf_Handle handle,
                                            uint32_t  adcChan,
                                            void *adjustedSampleBuffer,
                                            uint32_t outputMicroVoltBuffer[],
                                            uint_fast16_t sampleCount);

#ifdef __cplusplus
}
#endif
#endif /* ti_drivers_adcbuf__include */