Adc.h

Go to the documentation of this file.

/*
*
* Copyright (c) 2019 Texas Instruments Incorporated
*
* All rights reserved not granted herein.
*
* Limited License.
*
* Texas Instruments Incorporated grants a world-wide, royalty-free, non-exclusive
* license under copyrights and patents it now or hereafter owns or controls to make,
* have made, use, import, offer to sell and sell ("Utilize") this software subject to the
* terms herein.  With respect to the foregoing patent license, such license is granted
* solely to the extent that any such patent is necessary to Utilize the software alone.
* The patent license shall not apply to any combinations which include this software,
* other than combinations with devices manufactured by or for TI ("TI Devices").
* No hardware patent is licensed hereunder.
*
* Redistributions must preserve existing copyright notices and reproduce this license
* (including the above copyright notice and the disclaimer and (if applicable) source
* code license limitations below) in the documentation and/or other materials provided
* with the distribution
*
* Redistribution and use in binary form, without modification, are permitted provided
* that the following conditions are met:
*
* *       No reverse engineering, decompilation, or disassembly of this software is
* permitted with respect to any software provided in binary form.
*
* *       any redistribution and use are licensed by TI for use only with TI Devices.
*
* *       Nothing shall obligate TI to provide you with source code for the software
* licensed and provided to you in object code.
*
* If software source code is provided to you, modification and redistribution of the
* source code are permitted provided that the following conditions are met:
*
* *       any redistribution and use of the source code, including any resulting derivative
* works, are licensed by TI for use only with TI Devices.
*
* *       any redistribution and use of any object code compiled from the source code
* and any resulting derivative works, are licensed by TI for use only with TI Devices.
*
* Neither the name of Texas Instruments Incorporated nor the names of its suppliers
*
* may be used to endorse or promote products derived from this software without
* specific prior written permission.
*
* DISCLAIMER.
*
* THIS SOFTWARE IS PROVIDED BY TI AND TI'S LICENSORS "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 TI AND TI'S LICENSORS 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.
*
*/

/*
 * Below are the global requirements which are met by this ADC
 * driver which can't be mapped to a particular source ID
 */
/* Design : DES_ADC_001, DES_ADC_016 */
/*
 * Requirements : MCAL-3172, MCAL-3185, MCAL-3206, MCAL-3207,
 *                MCAL-3228, MCAL-3417, MCAL-3430, MCAL-3471, MCAL-981
 *                MCAL-4473
 */

/*
 * Below are the ADC's module environment requirements which can't be mapped
 * to this driver
 */
/*
 * Requirements : MCAL-3186, MCAL-3208, MCAL-3209, MCAL-3272,
 *                MCAL-3273, MCAL-3281, MCAL-3289, MCAL-3372,
 *                MCAL-3381, MCAL-3419,
 */

#ifndef ADC_H_
#define ADC_H_

/* ========================================================================== */
/*                             Include Files                                  */
/* ========================================================================== */

#include "Std_Types.h"
/* Design : DES_ADC_011 */
#include "Adc_Cfg.h"
#include "Adc_Irq.h"

#ifdef __cplusplus
extern "C"
{
#endif

/* ========================================================================== */
/*                           Macros & Typedefs                                */
/* ========================================================================== */

#define ADC_SW_MAJOR_VERSION            (1U)

#define ADC_SW_MINOR_VERSION            (3U)

#define ADC_SW_PATCH_VERSION            (2U)
/* @} */

#define ADC_AR_RELEASE_MAJOR_VERSION    (4U)

#define ADC_AR_RELEASE_MINOR_VERSION    (3U)

#define ADC_AR_RELEASE_REVISION_VERSION (1U)
/* @} */

#define ADC_VENDOR_ID                   ((uint16) 44U)

#define ADC_MODULE_ID                   ((uint16) 123U)

#define ADC_INSTANCE_ID                 ((uint8) 0U)
/* @} */

#define ADC_UNIT_0                      ((Adc_HWUnitType) 0U)

#define ADC_UNIT_1                      ((Adc_HWUnitType) 1U)
/* @} */

#if defined (SOC_J721E)
#define ADC_HW_UNIT_CNT                 (2U)
#elif defined (SOC_J7200)
#define ADC_HW_UNIT_CNT                 (1U)
#endif

#define ADC_DEF_CHANNEL_RESOLUTION      (12U)

#define ADC_NUM_CHANNEL                 (10U)

#define ADC_MIN_CHANNEL_ID              (0U)

#define ADC_MAX_CHANNEL_ID              (ADC_NUM_CHANNEL - 1U)

#define ADC_NUM_HW_CHANNEL              (10U)

#define ADC_MIN_HW_CHANNEL_ID           (0U)

#define ADC_MAX_HW_CHANNEL_ID           (ADC_NUM_HW_CHANNEL - 1U)

#define ADC_MIN_OPEN_DELAY              (0x00U)

#define ADC_MAX_OPEN_DELAY              (0x3FFFFU)

#define ADC_MIN_SAMPLE_DELAY            (0x00U)

#define ADC_MAX_SAMPLE_DELAY            (0xFFU)

#define ADC_MIN_RANGE                   (0x00U)

#define ADC_MAX_RANGE                   (0xFFFU)

/* Design : DES_ADC_014 */
/* Requirements : MCAL-3464, MCAL-4478 */

#ifndef ADC_E_UNINIT

#define ADC_E_UNINIT                    ((uint8) 0x0AU)
#endif
#ifndef ADC_E_BUSY

#define ADC_E_BUSY                      ((uint8) 0x0BU)
#endif
#ifndef ADC_E_IDLE

#define ADC_E_IDLE                      ((uint8) 0x0CU)
#endif
#ifndef ADC_E_ALREADY_INITIALIZED

#define ADC_E_ALREADY_INITIALIZED       ((uint8) 0x0DU)
#endif
#ifndef ADC_E_PARAM_CONFIG

#define ADC_E_PARAM_CONFIG              ((uint8) 0x0EU)
#endif
#ifndef ADC_E_PARAM_POINTER

#define ADC_E_PARAM_POINTER             ((uint8) 0x14U)
#endif
#ifndef ADC_E_PARAM_GROUP

#define ADC_E_PARAM_GROUP               ((uint8) 0x15U)
#endif
#ifndef ADC_E_WRONG_CONV_MODE

#define ADC_E_WRONG_CONV_MODE           ((uint8) 0x16U)
#endif
#ifndef ADC_E_WRONG_TRIGG_SRC

#define ADC_E_WRONG_TRIGG_SRC           ((uint8) 0x17U)
#endif
#ifndef ADC_E_NOTIF_CAPABILITY

#define ADC_E_NOTIF_CAPABILITY          ((uint8) 0x18U)
#endif
#ifndef ADC_E_BUFFER_UNINIT

#define ADC_E_BUFFER_UNINIT             ((uint8) 0x19U)
#endif
#ifndef ADC_E_NOT_DISENGAGED

#define ADC_E_NOT_DISENGAGED            ((uint8) 0x1AU)
#endif
#ifndef ADC_E_POWER_STATE_NOT_SUPPORTED

#define ADC_E_POWER_STATE_NOT_SUPPORTED ((uint8) 0x1BU)
#endif
#ifndef ADC_E_TRANSITION_NOT_POSSIBLE

#define ADC_E_TRANSITION_NOT_POSSIBLE   ((uint8) 0x1CU)
#endif
#ifndef ADC_E_PERIPHERAL_NOT_PREPARED

#define ADC_E_PERIPHERAL_NOT_PREPARED   ((uint8) 0x1DU)
#endif
/* @} */

/* Design : DES_ADC_017 */
/* Requirements : MCAL-3230 */
typedef uint8   Adc_ChannelType;

/* Design : DES_ADC_017 */
/* Requirements : MCAL-3231 */
typedef uint8   Adc_GroupType;

/* Design : DES_ADC_017 */
/* Requirements : MCAL-3232, MCAL-3235 */
typedef uint32  Adc_ValueGroupType;

/* Design : DES_ADC_017 */
/* Requirements : MCAL-3236 */
typedef uint32  Adc_PrescaleType;

/* Design : DES_ADC_017 */
/* Requirements : MCAL-3237 */
typedef uint16  Adc_ConversionTimeType;

/* Design : DES_ADC_017 */
/* Requirements : MCAL-3238 */
typedef uint16  Adc_SamplingTimeType;

/* Requirements : MCAL-3239 */
typedef uint8   Adc_ResolutionType;

/* Design : DES_ADC_017 */
/* Requirements : MCAL-3193, MCAL-3243 */
typedef uint8   Adc_GroupPriorityType;

/* Design : DES_ADC_017 */
/* Requirements : MCAL-3244 */
typedef uint32  Adc_GroupDefType;

/* Design : DES_ADC_017 */
/* Requirements : MCAL-3245 */
typedef uint16  Adc_StreamNumSampleType;

/* Design : DES_ADC_017 */
/* Requirements : MCAL-3249 */
typedef uint8   Adc_HwTriggerTimerType;

typedef uint8   Adc_HWUnitType;

#define ADC_SID_INIT                        ((uint8) 0x00U)

#define ADC_SID_DEINIT                      ((uint8) 0x01U)

#define ADC_SID_START_GROUP_CONVERSION      ((uint8) 0x02U)

#define ADC_SID_STOP_GROUP_CONVERSION       ((uint8) 0x03U)

#define ADC_SID_READ_GROUP                  ((uint8) 0x04U)

#define ADC_SID_ENABLE_HARDWARE_TRIGGER     ((uint8) 0x05U)

#define ADC_SID_DISABLE_HARDWARE_TRIGGER    ((uint8) 0x06U)

#define ADC_SID_ENABLE_GROUP_NOTIFICATION   ((uint8) 0x07U)

#define ADC_SID_DISABLE_GROUP_NOTIFICATION  ((uint8) 0x08U)

#define ADC_SID_GET_GROUP_STATUS            ((uint8) 0x09U)

#define ADC_SID_GET_VERSION_INFO            ((uint8) 0x0AU)

#define ADC_SID_GET_STREAM_LAST_POINTER     ((uint8) 0x0BU)

#define ADC_SID_SETUP_RESULT_BUFFER         ((uint8) 0x0CU)

#define ADC_SID_SET_POWER_STATE             ((uint8) 0x10U)

#define ADC_SID_GET_CURRENT_POWER_STATE     ((uint8) 0x11U)

#define ADC_SID_GET_TARGET_POWER_STATE      ((uint8) 0x12U)

#define ADC_SID_PREPARE_POWER_STATE         ((uint8) 0x13U)

#define ADC_SID_MAIN_POWER_TRANSITION_MANAGER       ((uint8) 0x14U)

#define ADC_SID_IOHWAB_NOTIFICATION                 ((uint8) 0x20U)

#define ADC_SID_IOHWAB_NOTIFY_READY_FOR_POWER_STATE ((uint8) 0x70U)
/* @} */

/* ========================================================================== */
/*                         Structures and Enums                               */
/* ========================================================================== */

typedef P2FUNC(void, ADC_APPL_CODE, Adc_GroupEndNotifyType)(void);

/* Requirements : MCAL-3240 */
typedef enum
{
    ADC_IDLE,
    ADC_BUSY,
    ADC_COMPLETED,
    ADC_STREAM_COMPLETED
} Adc_StatusType;

/* Requirements : MCAL-3241 */
/* Design : DES_ADC_005, DES_ADC_006 */
typedef enum
{
    ADC_TRIGG_SRC_SW,
    ADC_TRIGG_SRC_HW
} Adc_TriggerSourceType;

/* Requirements : MCAL-3242 */
/* Design : DES_ADC_003, DES_ADC_004 */
typedef enum
{
    ADC_CONV_MODE_ONESHOT,
    ADC_CONV_MODE_CONTINUOUS
} Adc_GroupConvModeType;

/* Requirements : MCAL-3246 */
typedef enum
{
    ADC_STREAM_BUFFER_LINEAR,
    ADC_STREAM_BUFFER_CIRCULAR
} Adc_StreamBufferModeType;

/* Requirements : MCAL-3247 */
typedef enum
{
    ADC_ACCESS_MODE_SINGLE,
    ADC_ACCESS_MODE_STREAMING
} Adc_GroupAccessModeType;

/* Requirements : MCAL-3248 */
typedef enum
{
    ADC_HW_TRIG_RISING_EDGE,
    ADC_HW_TRIG_FALLING_EDGE,
    ADC_HW_TRIG_BOTH_EDGES
} Adc_HwTriggerSignalType;

/* Requirements : MCAL-3250 */
/* Design : DES_ADC_009 */
typedef enum
{
    ADC_PRIORITY_NONE,
    ADC_PRIORITY_HW,
    ADC_PRIORITY_HW_SW
} Adc_PriorityImplementationType;

/* Requirements : MCAL-3251 */
typedef enum
{
    ADC_GROUP_REPL_ABORT_RESTART,
    ADC_GROUP_REPL_SUSPEND_RESUME,
} Adc_GroupReplacementType;

/* Requirements : MCAL-3252 */
typedef enum
{
    ADC_RANGE_UNDER_LOW,
    ADC_RANGE_BETWEEN,
    ADC_RANGE_OVER_HIGH,
    ADC_RANGE_ALWAYS,
    ADC_RANGE_NOT_UNDER_LOW,
    ADC_RANGE_NOT_BETWEEN,
    ADC_RANGE_NOT_OVER_HIGH
} Adc_ChannelRangeSelectType;

/* Requirements : MCAL-3253 */
typedef enum
{
    ADC_ALIGN_LEFT,
    ADC_ALIGN_RIGHT
} Adc_ResultAlignmentType;

/* Requirements : MCAL-3254 */
typedef enum
{
    ADC_FULL_POWER,
    ADC_ZERO_POWER
} Adc_PowerStateType;

/* Requirements : MCAL-3255 */
typedef enum
{
    ADC_SERVICE_ACCEPTED,
    ADC_NOT_INIT,
    ADC_SEQUENCE_ERROR,
    ADC_HW_FAILURE,
    ADC_POWER_STATE_NOT_SUPP,
    ADC_TRANS_NOT_POSSIBLE,
} Adc_PowerStateRequestResultType;

typedef enum
{
    ADC_AVERAGING_MODE_NONE,
    ADC_AVERAGING_MODE_2_SAMPLES,
    ADC_AVERAGING_MODE_4_SAMPLES,
    ADC_AVERAGING_MODE_8_SAMPLES,
    ADC_AVERAGING_MODE_16_SAMPLES
} Adc_AveragingMode;

/* Design : DES_ADC_017 */
typedef struct
{
    uint32              hwChannelId;
    uint32              openDelay;
    uint32              sampleDelay;
    uint32              rangeCheckEnable;
    Adc_AveragingMode   averagingMode;
} Adc_ChannelConfigType;

/* Design : DES_ADC_018 */
/* Requirements : MCAL-3173, MCAL-3176, MCAL-3177, MCAL-3180,
 *                MCAL-3181, MCAL-3178, MCAL-3182, MCAL-3420,
 *                MCAL-3423, MCAL-3425, MCAL-3428, MCAL-3187,
 *                MCAL-3190,
 */
typedef struct
{
    Adc_GroupType                   groupId;
    Adc_GroupPriorityType           groupPriority;
    Adc_HWUnitType                  hwUnitId;
    Adc_GroupEndNotifyType          Adc_GroupEndNotification;
    Adc_StreamNumSampleType         streamNumSamples;
    Adc_ResolutionType              resolution;
    Adc_GroupConvModeType           convMode;
    Adc_TriggerSourceType           triggSrc;
    Adc_GroupAccessModeType         accessMode;
    Adc_StreamBufferModeType        streamBufMode;
    Adc_HwTriggerSignalType         hwTrigSignal;
    Adc_HwTriggerTimerType          hwTrigTimer;
    Adc_GroupReplacementType        groupReplacement;
    uint32                          highRange;
    uint32                          lowRange;
    uint32                          numChannels;
    Adc_ChannelConfigType           channelConfig[ADC_NUM_CHANNEL];
} Adc_GroupConfigType;

typedef struct
{
    Adc_HWUnitType      hwUnitId;
} Adc_HwUnitConfigType;

/* Design : DES_ADC_019 */
/* Requirements : MCAL-3229, MCAL-3429 */
typedef struct Adc_ConfigType_s
{
    uint8                   maxGroup;
    uint8                   maxHwUnit;
    Adc_GroupConfigType     groupCfg[ADC_MAX_GROUP];
    Adc_HwUnitConfigType    hwUnitCfg[ADC_MAX_HW_UNIT];
} Adc_ConfigType;

#if (STD_ON == ADC_REGISTER_READBACK_API)

typedef struct
{
    /*
     * ADC related registers
     */
    uint32      adcRev;
    uint32      adcCtrl;
    uint32      adcMisc;
} Adc_RegisterReadbackType;
#endif  /* #if (STD_ON == ADC_REGISTER_READBACK_API) */

/* @} */

/* ========================================================================== */
/*                          Function Declarations                             */
/* ========================================================================== */

FUNC(void, ADC_CODE) Adc_Init(
                    P2CONST(Adc_ConfigType, AUTOMATIC, ADC_PBCFG) CfgPtr);

#if (STD_ON == ADC_DEINIT_API)

FUNC(void, ADC_CODE) Adc_DeInit(void);
#endif  /* #if (STD_ON == ADC_DEINIT_API) */

FUNC(Std_ReturnType, ADC_CODE) Adc_SetupResultBuffer(
                                    Adc_GroupType Group,
                                    const Adc_ValueGroupType *DataBufferPtr);

FUNC(Adc_StatusType, ADC_CODE) Adc_GetGroupStatus(Adc_GroupType Group);

/* Design : DES_ADC_007 */
FUNC(Adc_StreamNumSampleType, ADC_CODE) Adc_GetStreamLastPointer(
        Adc_GroupType Group,
        Adc_ValueGroupType **PtrToSamplePtr);

#if (STD_ON == ADC_ENABLE_START_STOP_GROUP_API)

FUNC(void, ADC_CODE) Adc_StartGroupConversion(Adc_GroupType Group);

FUNC(void, ADC_CODE) Adc_StopGroupConversion(Adc_GroupType Group);
#endif  /* #if (STD_ON == ADC_ENABLE_START_STOP_GROUP_API) */

#if (STD_ON == ADC_READ_GROUP_API)

/* Design : DES_ADC_008 */
FUNC(Std_ReturnType, ADC_CODE) Adc_ReadGroup(
            Adc_GroupType Group,
            Adc_ValueGroupType *DataBufferPtr);
#endif  /* #if (STD_ON == ADC_READ_GROUP_API) */

#if (STD_ON == ADC_GRP_NOTIF_CAPABILITY_API)

FUNC(void, ADC_CODE) Adc_EnableGroupNotification(Adc_GroupType Group);

FUNC(void, ADC_CODE) Adc_DisableGroupNotification(Adc_GroupType Group);
#endif  /* #if (STD_ON == ADC_GRP_NOTIF_CAPABILITY_API) */

#if (STD_ON == ADC_VERSION_INFO_API)

FUNC(void, ADC_CODE) Adc_GetVersionInfo(
        P2VAR(Std_VersionInfoType, AUTOMATIC, ADC_APPL_DATA) versioninfo);
#endif  /* #if (STD_ON == ADC_VERSION_INFO_API) */

#if (STD_ON == ADC_REGISTER_READBACK_API)

FUNC(Std_ReturnType, ADC_CODE) Adc_RegisterReadback(
    Adc_HWUnitType HWUnit,
    P2VAR(Adc_RegisterReadbackType, AUTOMATIC, ADC_APPL_DATA) RegRbPtr);
#endif  /* #if (STD_ON == ADC_REGISTER_READBACK_API) */

#ifdef __cplusplus
}
#endif

#endif  /* #ifndef ADC_H_ */

/* @} */