ADCBufLPF3.h

Go to the documentation of this file.

/*
 * Copyright (c) 2023-2025, 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       ADCBufLPF3.h
 *
 *  @brief      ADCBuf driver implementation for an LPF3 analog-to-digital
 *              converter
 *
 * # Driver include #
 *  The ADCBuf header file should be included in an application as follows:
 *  @code
 *  #include <ti/drivers/ADCBuf.h>
 *  #include <ti/drivers/adc/ADCBufLPF3.h>
 *  @endcode
 *
 * # Overview #
 * This is an LPF3 specific implementation of the generic ADCBuf driver.
 * The generic ADCBuf API specified in @ref ti/drivers/ADCBuf.h should be called
 * by the application, not the device specific implementation in
 * ti/drivers/adcbuf/ADCBufLPF3.c
 *
 * # General Behavior #
 * The internal ADC sample timer is used to generate samples at a specified
 * frequency and the DMA is used to fill a buffer with a specified size in the
 * background. The application may execute other tasks while the hardware
 * handles the conversions. In contrast to the standard ti/drivers/ADC driver,
 * this driver allows for precise sampling of waveforms.
 *
 * | Driver         | Number of samples needed in one call    |
 * |----------------|-----------------------------------------|
 * | ADC.h          | 1                                       |
 * | ADCBuf.h       | > 1                                     |
 *
 * The ADC drivers supports making between 1 and 1024 measurements once or
 * continuous measuring with returned buffer sizes between 1 and 1024
 * measurements.
 *
 * The ADCBuf driver is opened by calling #ADCBuf_open() which will
 * set up interrupts and configure the internal components of the driver.
 * However, the ADCBuf hardware or analog pins are not configured by calling
 * #ADCBuf_open() since other software components might be using the ADC.
 *
 * In order to perform an ADC conversion, the application must call
 * #ADCBuf_convert(). This call will request the ADC resource, configure the
 * ADC, set up the DMA, and perform the requested ADC conversions on the
 * selected DIO or internal signal.
 *
 * @warning If the ADCBUF driver is setup in ADCBuf_RECURRENCE_MODE_CONTINUOUS
 *          mode, the user must assure that the provided callback function is
 *          completed before the next conversion completes. If the next
 *          conversion completes before the callback function finishes, the DMA
 *          will clobber the previous buffer with new data.
 *
 * If the ADC is used by another component when the driver requests it at the
 * start of the #ADCBuf_convert() call, the calling task will be put in blocked
 * state until the ADC is available. If #ADCBuf_convert() is called from ISR
 * context, the call will fail and return #ADCBuf_STATUS_ERROR.
 * The ADC resource may be pre-acquired by calling the
 * #ADCBufLPF3_acquireAdcSemaphore() function. The semaphore must be manually
 * released again when done with the ADC by calling
 * #ADCBufLPF3_releaseAdcSemaphore()
 *
 * # Error handling #
 * The following errors may occur when opening the ADC without assertions enabled:
 * - The ADC handle is already open.
 *
 * The following errors may occur when requesting an ADC conversion:
 * - The ADC is currently already doing a conversion.
 * - The ADC is not available.
 *
 * # Power Management #
 * The TI Power management framework will try to put the device into the
 * most power efficient mode whenever possible. Please see the technical
 * reference manual for further details on each power mode.
 *
 * While converting, the ADCBufLPF3 driver sets a power constraint to keep
 * the device out of standby. When the conversion has finished, the power
 * constraint is released. The driver also sets a dependency on the DMA to
 * enable background transfers from the ADC FIFO to memory.
 * The following statements are valid:
 *      - After #ADCBuf_convert(): the device cannot enter standby.
 *      - After #ADCBuf_convertCancel(): the device can enter standby.
 *      - After a conversion finishes: the device can enter standby.
 *
 *
 * # Supported Functions #
 * | API function                          | Description                                                           |
 * |---------------------------------------|-----------------------------------------------------------------------|
 * | #ADCBuf_init()                        | Initialize ADC driver                                                 |
 * | #ADCBuf_open()                        | Open the ADC driver and configure driver                              |
 * | #ADCBuf_convert()                     | Perform ADC conversion                                                |
 * | #ADCBuf_convertCancel()               | Cancel ongoing ADC conversion                                         |
 * | #ADCBuf_close()                       | Close ADC driver                                                      |
 * | #ADCBuf_Params_init()                 | Initialise ADCBuf_Params structure to default values                  |
 * | #ADCBuf_getResolution()               | Get the resolution of the ADC of the current device                   |
 * | #ADCBuf_adjustRawValues()             | Adjust the values in a returned buffer for manufacturing tolerances   |
 * | #ADCBuf_convertAdjustedToMicroVolts() | Convert a buffer of adjusted values to microvolts                     |
 * | #ADCBufLPF3_acquireAdcSemaphore()     | Manually pre-acquire ADC semaphore                                    |
 * | #ADCBufLPF3_releaseAdcSemaphore()     | Release ADC semaphore previously manually pre-acquired using          |
 *
 * # Supported Sampling Frequencies
 * | Reference        | Resolution | Min Frequency   | Max Frequency |
 * |------------------|------------|-----------------|---------------|
 * | External or VDDS | 8-bit      | 978 sps         | 1600 ksps     |
 * | External or VDDS | 10-bit     | 978 sps         | 1330 ksps     |
 * | External or VDDS | 12-bit     | 977 sps         | 1200 ksps     |
 * | Internal         | 8-bit      | 976 sps         |  400 ksps     |
 * | Internal         | 10-bit     | 975 sps         |  308 ksps     |
 * | Internal         | 12-bit     | 975 sps         |  267 ksps     |
 *
 * # Not Supported Functionality #
 * - Performing conversions on multiple channels simultaneously is not
 *   supported. In other words, the parameter @c channelCount must always be
 *   set to 1 when calling #ADCBuf_convert(). For the same reason, the value
 *   of the @c completedChannel argument in the #ADCBuf_Callback will always
 *   be 0.
 * - It is not supported to have multiple ADCBuf instances open at the same
 *   time. You must close the currently open instance (if any) before trying
 *   to open another instance.
 *   It is suggested to only have one ADCBuf instances.
 *
 * # Used Resources #
 * - The ADC Peripheral
 * - 2 DMA channels
 *   - One "data" channel is used to copy the samples from the ADC to memory
 *     - The channel is selected using the relevant data DMA fields in
 *       #ADCBufLPF3_HWAttrs:
 *       - #ADCBufLPF3_HWAttrs.dataDmaTableEntryPri
 *       - #ADCBufLPF3_HWAttrs.dataDmaTableEntryAlt
 *       - #ADCBufLPF3_HWAttrs.dataDmaChannelMask
 *       - #ADCBufLPF3_HWAttrs.dataDmaSubscriberId
 *   - Another "auxiliary" channel is used to re-configure the ADC to generate
 *     DMA triggers for the data DMA channel after each data DMA transfer. This
 *     is needed because the ADC disables generation of DMA triggers when a DMA
 *     transfer completes. So in continuos mode, the generation of DMA triggers
 *     must be re-enabled, and it must be re-enabled within one sample period to
 *     not cause any overflow. To be able to re-enable triggers quickly enough,
 *     the auxiliary DMA channel is used.
 *     - The channel is selected using the relevant auxiliary DMA fields in
 *       #ADCBufLPF3_HWAttrs:
 *       - #ADCBufLPF3_HWAttrs.auxDmaTableEntryPri
 *       - #ADCBufLPF3_HWAttrs.auxDmaChannelMask
 *       - #ADCBufLPF3_HWAttrs.auxDmaSubscriberId
 *
 ******************************************************************************
 */

#ifndef ti_drivers_adcbuf_adcbufLPF3__include
#define ti_drivers_adcbuf_adcbufLPF3__include

#include <stdint.h>
#include <stdbool.h>

/* Driver includes */
#include <ti/drivers/ADC.h>
#include <ti/drivers/Power.h>
#include <ti/drivers/ADCBuf.h>
#include <ti/drivers/adc/ADCLPF3.h>
#include <ti/drivers/dma/UDMALPF3.h>

/* Kernel includes */
#include <ti/drivers/dpl/HwiP.h>
#include <ti/drivers/dpl/SwiP.h>
#include <ti/drivers/dpl/ClockP.h>
#include <ti/drivers/dpl/SemaphoreP.h>

/* Driverlib includes */
#include <ti/devices/DeviceFamily.h>
#include DeviceFamily_constructPath(inc/hw_memmap.h)
#include DeviceFamily_constructPath(inc/hw_adc.h)
#include DeviceFamily_constructPath(inc/hw_types.h)
#include DeviceFamily_constructPath(driverlib/adc.h)
#include DeviceFamily_constructPath(driverlib/evtsvt.h)

#ifdef __cplusplus
extern "C" {
#endif

#define ADCBufLPF3_STATUS_UNDERFLOW (ADCBuf_STATUS_RESERVED - 0)

#define ADCBufLPF3_STATUS_OVERFLOW (ADCBuf_STATUS_RESERVED - 1)

#define ADCBufLPF3_STATUS_UNDERFLOW_AND_OVERFLOW (ADCBuf_STATUS_RESERVED - 2)

#define ADCBufLPF3_BYTES_PER_SAMPLE 2

/*
 * =============================================================================
 * Constants
 * =============================================================================
 */

/* ADCBuf function table */
extern const ADCBuf_FxnTable ADCBufLPF3_fxnTable;

/*
 * =============================================================================
 * Enumerations
 * =============================================================================
 */

typedef enum
{
    ADCBufLPF3_CONVERSION_NONE = 0,
    ADCBufLPF3_CONVERSION_STARTING,
    ADCBufLPF3_CONVERSION_IN_PROGRESS,
} ADCBufLPF3_ConversionStatus;

/*
 * =============================================================================
 * Structs
 * =============================================================================
 */

typedef struct
{
    uint_fast32_t refVoltage;
    uint8_t adcInputDIO;
    uint8_t internalChannel;
    ADCLPF3_Reference_Source refSource;
} ADCBufLPF3_AdcChannelLutEntry;

typedef struct
{
    volatile uDMAControlTableEntry *dataDmaTableEntryPri;

    volatile uDMAControlTableEntry *dataDmaTableEntryAlt;

    volatile uDMAControlTableEntry *auxDmaTableEntryPri;

    ADCBufLPF3_AdcChannelLutEntry const *adcChannelLut;

    ADCLPF3_Resolution_Bits resolutionBits;

    uint32_t dataDmaChannelMask;

    uint32_t auxDmaChannelMask;

    uint32_t dataDmaSubscriberId;

    uint32_t auxDmaSubscriberId;

    uint8_t intPriority;

    uint8_t adcRefPosDIO;

    uint8_t adcRefNegDIO;
} ADCBufLPF3_HWAttrs;

typedef struct
{
    SemaphoreP_Struct conversionSemaphore;
    ADCBuf_Conversion *currentConversion;
    HwiP_Struct hwi;
    ADCBuf_Callback callbackFxn;
    uint32_t *activeSampleBuffer;
    uint32_t semaphoreTimeout;
    uint32_t samplingFrequency;
    ADCBufLPF3_ConversionStatus conversionStatus;
    ADCBuf_Return_Mode returnMode;
    ADCBuf_Recurrence_Mode recurrenceMode;
    bool isOpen;
    bool userAcquiredAdcSemaphore;
} ADCBufLPF3_Object, *ADCBufLPF3_Handle;

/*
 * =============================================================================
 * Functions
 * =============================================================================
 */

bool ADCBufLPF3_acquireAdcSemaphore(ADCBuf_Handle handle, uint32_t timeout);

bool ADCBufLPF3_releaseAdcSemaphore(ADCBuf_Handle handle);

#ifdef __cplusplus
}
#endif

#endif /* ti_drivers_adcbuf_ADCBufLPF3__include */