blob: c4752af82ea9240cc0214831a9ef23f91910d934 [file] [log] [blame]
/******************************************************************************
* Filename: aux_adc.h
* Revised: 2015-07-16 12:12:04 +0200 (Thu, 16 Jul 2015)
* Revision: 44151
*
* Description: Defines and prototypes for the AUX Analog-to-Digital
* Converter
*
* Copyright (c) 2015 - 2016, 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:
*
* 1) Redistributions of source code must retain the above copyright notice,
* this list of conditions and the following disclaimer.
*
* 2) 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.
*
* 3) Neither the name of the ORGANIZATION 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 HOLDER 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.
*
******************************************************************************/
//*****************************************************************************
//
//! \addtogroup aux_group
//! @{
//! \addtogroup auxadc_api
//! @{
//
//*****************************************************************************
#ifndef __AUX_ADC_H__
#define __AUX_ADC_H__
//*****************************************************************************
//
// If building with a C++ compiler, make all of the definitions in this header
// have a C binding.
//
//*****************************************************************************
#ifdef __cplusplus
extern "C"
{
#endif
#include <stdbool.h>
#include <stdint.h>
#include <inc/hw_types.h>
#include <inc/hw_memmap.h>
#include <inc/hw_event.h>
#include <inc/hw_adi.h>
#include <inc/hw_adi_4_aux.h>
#include <inc/hw_aux_anaif.h>
#include <driverlib/rom.h>
//*****************************************************************************
//
// Support for DriverLib in ROM:
// This section renames all functions that are not "static inline", so that
// calling these functions will default to implementation in flash. At the end
// of this file a second renaming will change the defaults to implementation in
// ROM for available functions.
//
// To force use of the implementation in flash, e.g. for debugging:
// - Globally: Define DRIVERLIB_NOROM at project level
// - Per function: Use prefix "NOROM_" when calling the function
//
//*****************************************************************************
#if !defined(DOXYGEN)
#define AUXADCDisable NOROM_AUXADCDisable
#define AUXADCEnableAsync NOROM_AUXADCEnableAsync
#define AUXADCEnableSync NOROM_AUXADCEnableSync
#define AUXADCDisableInputScaling NOROM_AUXADCDisableInputScaling
#define AUXADCFlushFifo NOROM_AUXADCFlushFifo
#define AUXADCReadFifo NOROM_AUXADCReadFifo
#define AUXADCPopFifo NOROM_AUXADCPopFifo
#define AUXADCGetAdjustmentGain NOROM_AUXADCGetAdjustmentGain
#define AUXADCGetAdjustmentOffset NOROM_AUXADCGetAdjustmentOffset
#define AUXADCValueToMicrovolts NOROM_AUXADCValueToMicrovolts
#define AUXADCMicrovoltsToValue NOROM_AUXADCMicrovoltsToValue
#define AUXADCAdjustValueForGainAndOffset NOROM_AUXADCAdjustValueForGainAndOffset
#define AUXADCUnadjustValueForGainAndOffset NOROM_AUXADCUnadjustValueForGainAndOffset
#endif
//*****************************************************************************
//
// Defines for ADC reference sources.
//
//*****************************************************************************
#define AUXADC_REF_FIXED (0 << ADI_4_AUX_ADCREF0_SRC_S)
#define AUXADC_REF_VDDS_REL (1 << ADI_4_AUX_ADCREF0_SRC_S)
//*****************************************************************************
//
// Defines for the ADC FIFO status bits.
//
//*****************************************************************************
#define AUXADC_FIFO_EMPTY_M (AUX_ANAIF_ADCFIFOSTAT_EMPTY_M)
#define AUXADC_FIFO_ALMOST_FULL_M (AUX_ANAIF_ADCFIFOSTAT_ALMOST_FULL_M)
#define AUXADC_FIFO_FULL_M (AUX_ANAIF_ADCFIFOSTAT_FULL_M)
#define AUXADC_FIFO_UNDERFLOW_M (AUX_ANAIF_ADCFIFOSTAT_UNDERFLOW_M)
#define AUXADC_FIFO_OVERFLOW_M (AUX_ANAIF_ADCFIFOSTAT_OVERFLOW_M)
//*****************************************************************************
//
// Defines for supported ADC triggers.
//
//*****************************************************************************
#define AUXADC_TRIGGER_MANUAL (EVENT_AUXSEL0_EV_NONE)
#define AUXADC_TRIGGER_GPT0A (EVENT_AUXSEL0_EV_GPT0A)
#define AUXADC_TRIGGER_GPT0B (EVENT_AUXSEL0_EV_GPT0B)
#define AUXADC_TRIGGER_GPT1A (EVENT_AUXSEL0_EV_GPT1A)
#define AUXADC_TRIGGER_GPT1B (EVENT_AUXSEL0_EV_GPT1B)
#define AUXADC_TRIGGER_GPT2A (EVENT_AUXSEL0_EV_GPT2A)
#define AUXADC_TRIGGER_GPT2B (EVENT_AUXSEL0_EV_GPT2B)
#define AUXADC_TRIGGER_GPT3A (EVENT_AUXSEL0_EV_GPT3A)
#define AUXADC_TRIGGER_GPT3B (EVENT_AUXSEL0_EV_GPT3B)
//*****************************************************************************
//
// Defines for ADC sampling type for synchronous operation.
//
//*****************************************************************************
#define AUXADC_SAMPLE_TIME_2P7_US 3
#define AUXADC_SAMPLE_TIME_5P3_US 4
#define AUXADC_SAMPLE_TIME_10P6_US 5
#define AUXADC_SAMPLE_TIME_21P3_US 6
#define AUXADC_SAMPLE_TIME_42P6_US 7
#define AUXADC_SAMPLE_TIME_85P3_US 8
#define AUXADC_SAMPLE_TIME_170_US 9
#define AUXADC_SAMPLE_TIME_341_US 10
#define AUXADC_SAMPLE_TIME_682_US 11
#define AUXADC_SAMPLE_TIME_1P37_MS 12
#define AUXADC_SAMPLE_TIME_2P73_MS 13
#define AUXADC_SAMPLE_TIME_5P46_MS 14
#define AUXADC_SAMPLE_TIME_10P9_MS 15
//*****************************************************************************
//
// Equivalent voltages for fixed ADC reference, in microvolts.
//
//*****************************************************************************
#define AUXADC_FIXED_REF_VOLTAGE_NORMAL 4300000
#define AUXADC_FIXED_REF_VOLTAGE_UNSCALED 1478500
//*****************************************************************************
//
// API Functions and prototypes
//
//*****************************************************************************
//*****************************************************************************
//
//! \brief Disables the ADC.
//!
//! This function must be called:
//! - Before re-enabling the ADC using \ref AUXADCEnableAsync() or
//! \ref AUXADCEnableSync()
//! - Before entering system standby
//
//*****************************************************************************
extern void AUXADCDisable(void);
//*****************************************************************************
//
//! \brief Enables the ADC for asynchronous operation.
//!
//! In asynchronous operation, the ADC samples continuously between
//! conversions.
//!
//! The ADC trigger starts the conversion. Note that the first conversion may
//! be invalid if the sampling period is too short.
//!
//! ADC input scaling is enabled by default after device reset, and is also re-
//! enabled by \ref AUXADCDisable(). To disable input scaling, call
//! \ref AUXADCDisableInputScaling() before calling \ref AUXADCEnableAsync().
//!
//! \param refSource
//! ADC reference source:
//! - \ref AUXADC_REF_FIXED (nominally 4.3 V)
//! - \ref AUXADC_REF_VDDS_REL (nominally VDDS)
//! \param trigger
//! ADC conversion trigger:
//! - \ref AUXADC_TRIGGER_MANUAL
//! - \ref AUXADC_TRIGGER_GPT0A
//! - \ref AUXADC_TRIGGER_GPT0B
//! - \ref AUXADC_TRIGGER_GPT1A
//! - \ref AUXADC_TRIGGER_GPT1B
//! - \ref AUXADC_TRIGGER_GPT2A
//! - \ref AUXADC_TRIGGER_GPT2B
//! - \ref AUXADC_TRIGGER_GPT3A
//! - \ref AUXADC_TRIGGER_GPT3B
//
//*****************************************************************************
extern void AUXADCEnableAsync(uint32_t refSource, uint32_t trigger);
//*****************************************************************************
//
//! \brief Enables the ADC for synchronous operation.
//!
//! In synchronous operation, the ADC is idle between a conversion and
//! subsequent samplings.
//!
//! The ADC trigger starts sampling with specified duration, followed by the
//! conversion. Note that the first conversion may be invalid if the initial
//! sampling period is too short.
//!
//! ADC input scaling is enabled by default after device reset, and is also re-
//! enabled by \ref AUXADCDisable(). To disable input scaling, call
//! \ref AUXADCDisableInputScaling() before calling \ref AUXADCEnableSync().
//!
//! \param refSource
//! ADC reference source:
//! - \ref AUXADC_REF_FIXED (nominally 4.3 V)
//! - \ref AUXADC_REF_VDDS_REL (nominally VDDS)
//! \param sampleTime
//! ADC sampling time:
//! - \ref AUXADC_SAMPLE_TIME_2P7_US
//! - \ref AUXADC_SAMPLE_TIME_5P3_US
//! - \ref AUXADC_SAMPLE_TIME_10P6_US
//! - \ref AUXADC_SAMPLE_TIME_21P3_US
//! - \ref AUXADC_SAMPLE_TIME_42P6_US
//! - \ref AUXADC_SAMPLE_TIME_85P3_US
//! - \ref AUXADC_SAMPLE_TIME_170_US
//! - \ref AUXADC_SAMPLE_TIME_341_US
//! - \ref AUXADC_SAMPLE_TIME_682_US
//! - \ref AUXADC_SAMPLE_TIME_1P37_MS
//! - \ref AUXADC_SAMPLE_TIME_2P73_MS
//! - \ref AUXADC_SAMPLE_TIME_5P46_MS
//! - \ref AUXADC_SAMPLE_TIME_10P9_MS
//! \param trigger
//! ADC conversion trigger:
//! - \ref AUXADC_TRIGGER_MANUAL
//! - \ref AUXADC_TRIGGER_GPT0A
//! - \ref AUXADC_TRIGGER_GPT0B
//! - \ref AUXADC_TRIGGER_GPT1A
//! - \ref AUXADC_TRIGGER_GPT1B
//! - \ref AUXADC_TRIGGER_GPT2A
//! - \ref AUXADC_TRIGGER_GPT2B
//! - \ref AUXADC_TRIGGER_GPT3A
//! - \ref AUXADC_TRIGGER_GPT3B
//
//*****************************************************************************
extern void AUXADCEnableSync(uint32_t refSource, uint32_t sampleTime, uint32_t trigger);
//*****************************************************************************
//
//! \brief Disables scaling of the ADC input.
//!
//! By default, the ADC operates internally on a version of the input signal
//! that has been scaled down by a factor <tt>1408 / 4095</tt>. This function
//! disables that scaling, allowing for a trade-off between dynamic range and
//! and resolution.
//!
//! \note This function must only be called while the ADC is disabled, before
//! calling \ref AUXADCEnableSync() or \ref AUXADCEnableAsync().
//! \note Different input maximum ratings apply when input scaling is disabled.
//! Violating these may damage the device.
//
//*****************************************************************************
extern void AUXADCDisableInputScaling(void);
//*****************************************************************************
//
//! \brief Flushes the ADC FIFO.
//!
//! This empties the FIFO and clears the underflow/overflow flags.
//!
//! Note: This function must only be called while the ADC is enabled.
//
//*****************************************************************************
extern void AUXADCFlushFifo(void);
//*****************************************************************************
//
//! \brief Generates a single manual ADC trigger.
//!
//! For synchronous mode, the trigger starts sampling followed by conversion.
//! For asynchronous mode, the trigger starts conversion.
//
//*****************************************************************************
__STATIC_INLINE void
AUXADCGenManualTrigger(void)
{
HWREG(AUX_ANAIF_BASE + AUX_ANAIF_O_ADCTRIG) = 0;
}
//*****************************************************************************
//
//! \brief Returns flags indicating the status of the ADC FIFO.
//!
//! The flags indicate FIFO empty, full and almost full, and whether
//! overflow/underflow has occurred.
//!
//! \return
//! A combination (bitwise OR) of the following flags:
//! - \ref AUXADC_FIFO_EMPTY_M
//! - \ref AUXADC_FIFO_ALMOST_FULL_M
//! - \ref AUXADC_FIFO_FULL_M
//! - \ref AUXADC_FIFO_UNDERFLOW_M
//! - \ref AUXADC_FIFO_OVERFLOW_M
//
//*****************************************************************************
__STATIC_INLINE uint32_t
AUXADCGetFifoStatus(void)
{
return HWREG(AUX_ANAIF_BASE + AUX_ANAIF_O_ADCFIFOSTAT);
}
//*****************************************************************************
//
//! \brief Waits for and returns the first sample in the ADC FIFO.
//!
//! This function waits until there is at least one sample in the ADC FIFO. It
//! then pops and returns the first sample from the FIFO.
//!
//! \note This procedure will deadlock if called without setting up ADC trigger
//! generation in advance. The trigger can either be manual or periodical
//! (using a GPT).
//!
//! \return The first (12-bit) sample from the ADC FIFO
//
//*****************************************************************************
extern uint32_t AUXADCReadFifo(void);
//*****************************************************************************
//
//! \brief Returns the first sample in the ADC FIFO, without waiting.
//!
//! This function does not wait, and must only be called when there is at least
//! one sample in the ADC FIFO. Otherwise the call will generate FIFO underflow
//! (\ref AUXADC_FIFO_UNDERFLOW_M).
//!
//! \return The first (12-bit) sample from the ADC FIFO, or an undefined value
//! if the FIFO is empty
//
//*****************************************************************************
extern uint32_t AUXADCPopFifo(void);
//*****************************************************************************
//
//! \brief Selects internal or external input for the ADC.
//!
//! Note that calling this function also selects the same input for AUX_COMPB.
//!
//! \param input
//! Internal/external input selection:
//! - \ref ADC_COMPB_IN_DCOUPL
//! - \ref ADC_COMPB_IN_VSS
//! - \ref ADC_COMPB_IN_VDDS
//! - \ref ADC_COMPB_IN_AUXIO7
//! - \ref ADC_COMPB_IN_AUXIO6
//! - \ref ADC_COMPB_IN_AUXIO5
//! - \ref ADC_COMPB_IN_AUXIO4
//! - \ref ADC_COMPB_IN_AUXIO3
//! - \ref ADC_COMPB_IN_AUXIO2
//! - \ref ADC_COMPB_IN_AUXIO1
//! - \ref ADC_COMPB_IN_AUXIO0
//
//*****************************************************************************
__STATIC_INLINE void
AUXADCSelectInput(uint32_t input)
{
HapiSelectADCCompBInput(input);
}
//*****************************************************************************
//
//! \brief Returns the gain value used when adjusting for ADC gain/offset.
//!
//! The function returns the gain value to be used with
//! \ref AUXADCAdjustValueForGainAndOffset() or
//! \ref AUXADCUnadjustValueForGainAndOffset(). The gain value is found during
//! chip manufacturing and is stored in the factory configuration, FCFG1.
//!
//! \param refSource
//! ADC reference source:
//! - \ref AUXADC_REF_FIXED (nominally 4.3 V)
//! - \ref AUXADC_REF_VDDS_REL (nominally VDDS)
//!
//! \return
//! The gain value to be used in adjustments
//
//*****************************************************************************
extern int32_t AUXADCGetAdjustmentGain(uint32_t refSource);
//*****************************************************************************
//
//! \brief Returns the offset value used when adjusting for ADC gain/offset.
//!
//! The function returns the offset value to be used with
//! \ref AUXADCAdjustValueForGainAndOffset() or
//! \ref AUXADCUnadjustValueForGainAndOffset(). The offset value is found
//! during chip manufacturing and is stored in the factory configuration,
//! FCFG1.
//!
//! \param refSource
//! ADC reference source:
//! - \ref AUXADC_REF_FIXED (nominally 4.3 V)
//! - \ref AUXADC_REF_VDDS_REL (nominally VDDS)
//!
//! \return
//! The offset value to be used in adjustments
//
//*****************************************************************************
extern int32_t AUXADCGetAdjustmentOffset(uint32_t refSource);
//*****************************************************************************
//
//! \brief Converts an "adjusted" ADC value to microvolts.
//!
//! This function can only be used when measuring with fixed ADC reference
//! (\ref AUXADC_REF_FIXED). The specified reference voltage accounts for
//! whether the sampled ADC input is scaled down before conversion or not.
//!
//! \param fixedRefVoltage
//! Fixed reference voltage, in microvolts
//! - \ref AUXADC_FIXED_REF_VOLTAGE_NORMAL when using scaled input (normal)
//! - \ref AUXADC_FIXED_REF_VOLTAGE_UNSCALED when using unscaled input
//! \param adcValue
//! The ADC value
//!
//! \return
//! The corresponding number of microvolts
//
//*****************************************************************************
extern int32_t AUXADCValueToMicrovolts(int32_t fixedRefVoltage, int32_t adcValue);
//*****************************************************************************
//
//! \brief Converts a number of microvolts to corresponding "adjusted" ADC value.
//!
//! This function can only be used when measuring with fixed ADC reference
//! (\ref AUXADC_REF_FIXED). The specified reference voltage accounts for
//! whether the sampled ADC input is scaled down before conversion or not.
//!
//! \param fixedRefVoltage
//! Fixed reference voltage, in microvolts
//! - \ref AUXADC_FIXED_REF_VOLTAGE_NORMAL when using scaled input (normal)
//! - \ref AUXADC_FIXED_REF_VOLTAGE_UNSCALED when using unscaled input
//! \param microvolts
//! The number of microvolts
//!
//! \return
//! The corresponding expected ADC value (adjusted for ADC gain/offset)
//
//*****************************************************************************
extern int32_t AUXADCMicrovoltsToValue(int32_t fixedRefVoltage, int32_t microvolts);
//*****************************************************************************
//
//! \brief Performs ADC value gain and offset adjustment.
//!
//! This function takes a measured ADC value compensates for the internal gain
//! and offset in the ADC.
//!
//! \param adcValue
//! 12-bit ADC unadjusted value
//! \param gain
//! Gain adjustment value provided by \ref AUXADCGetAdjustmentGain()
//! \param offset
//! Offset adjustment value provided by \ref AUXADCGetAdjustmentOffset()
//!
//! \return
//! 12-bit ADC adjusted value
//
//*****************************************************************************
extern int32_t AUXADCAdjustValueForGainAndOffset(int32_t adcValue, int32_t gain, int32_t offset);
//*****************************************************************************
//
//! \brief Performs the inverse of the ADC value gain and offset adjustment.
//!
//! This function finds the expected measured ADC value, without gain and
//! offset compensation, for a given "ideal" ADC value. The function can for
//! example be used to find ADC value thresholds to be used in Sensor
//! Controller task configurations.
//!
//! \param adcValue
//! 12-bit ADC adjusted value
//! \param gain
//! Gain adjustment value provided by \ref AUXADCGetAdjustmentGain()
//! \param offset
//! Offset adjustment value provided by \ref AUXADCGetAdjustmentOffset()
//!
//! \return
//! 12-bit ADC unadjusted value
//
//*****************************************************************************
extern int32_t AUXADCUnadjustValueForGainAndOffset(int32_t adcValue, int32_t gain, int32_t offset);
//*****************************************************************************
//
// Support for DriverLib in ROM:
// Redirect to implementation in ROM when available.
//
//*****************************************************************************
#if !defined(DRIVERLIB_NOROM) && !defined(DOXYGEN)
#include <driverlib/rom.h>
#ifdef ROM_AUXADCDisable
#undef AUXADCDisable
#define AUXADCDisable ROM_AUXADCDisable
#endif
#ifdef ROM_AUXADCEnableAsync
#undef AUXADCEnableAsync
#define AUXADCEnableAsync ROM_AUXADCEnableAsync
#endif
#ifdef ROM_AUXADCEnableSync
#undef AUXADCEnableSync
#define AUXADCEnableSync ROM_AUXADCEnableSync
#endif
#ifdef ROM_AUXADCDisableInputScaling
#undef AUXADCDisableInputScaling
#define AUXADCDisableInputScaling ROM_AUXADCDisableInputScaling
#endif
#ifdef ROM_AUXADCFlushFifo
#undef AUXADCFlushFifo
#define AUXADCFlushFifo ROM_AUXADCFlushFifo
#endif
#ifdef ROM_AUXADCReadFifo
#undef AUXADCReadFifo
#define AUXADCReadFifo ROM_AUXADCReadFifo
#endif
#ifdef ROM_AUXADCPopFifo
#undef AUXADCPopFifo
#define AUXADCPopFifo ROM_AUXADCPopFifo
#endif
#ifdef ROM_AUXADCGetAdjustmentGain
#undef AUXADCGetAdjustmentGain
#define AUXADCGetAdjustmentGain ROM_AUXADCGetAdjustmentGain
#endif
#ifdef ROM_AUXADCGetAdjustmentOffset
#undef AUXADCGetAdjustmentOffset
#define AUXADCGetAdjustmentOffset ROM_AUXADCGetAdjustmentOffset
#endif
#ifdef ROM_AUXADCValueToMicrovolts
#undef AUXADCValueToMicrovolts
#define AUXADCValueToMicrovolts ROM_AUXADCValueToMicrovolts
#endif
#ifdef ROM_AUXADCMicrovoltsToValue
#undef AUXADCMicrovoltsToValue
#define AUXADCMicrovoltsToValue ROM_AUXADCMicrovoltsToValue
#endif
#ifdef ROM_AUXADCAdjustValueForGainAndOffset
#undef AUXADCAdjustValueForGainAndOffset
#define AUXADCAdjustValueForGainAndOffset ROM_AUXADCAdjustValueForGainAndOffset
#endif
#ifdef ROM_AUXADCUnadjustValueForGainAndOffset
#undef AUXADCUnadjustValueForGainAndOffset
#define AUXADCUnadjustValueForGainAndOffset ROM_AUXADCUnadjustValueForGainAndOffset
#endif
#endif
//*****************************************************************************
//
// Mark the end of the C bindings section for C++ compilers.
//
//*****************************************************************************
#ifdef __cplusplus
}
#endif
#endif // __AUX_ADC_H__
//*****************************************************************************
//
//! Close the Doxygen group.
//! @}
//! @}
//
//*****************************************************************************