Adc.h

Go to the documentation of this file.

/*
*
* Copyright (c) 2023 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 design requirements which are met by this ADC
 * driver which can't be mapped to a particular source ID
 */
/*
 * Design: MCAL-5723,MCAL-5861
 */

/*
 * Below are the ADC's module environment design requirements which can't
 * be mapped to this driver
 */
/*
 * Design: MCAL-5805,MCAL-5708,MCAL-5739,MCAL-5748
 */

 /*
  * Note: MCAL-5700,MCAL-5834 are prerequisites which are done by SBL/GEL files.
  */


#ifndef ADC_H_
#define ADC_H_

/* ========================================================================== */
/*                             Include Files                                  */
/* ========================================================================== */
#include "Std_Types.h"
#include "Adc_Cfg.h"

#ifdef __cplusplus
extern "C"
{
#endif

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

#define ADC_SW_MAJOR_VERSION            (9U)

#define ADC_SW_MINOR_VERSION            (0U)

#define ADC_SW_PATCH_VERSION            (0U)

/* @} */

#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_DEF_CHANNEL_RESOLUTION      ((uint8) 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: MCAL-5687
 */
#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: MCAL-5852
 */
typedef uint8   Adc_ChannelType;

/*
 * Design: MCAL-5702
 */
typedef uint8   Adc_GroupType;

/*
 * Design: MCAL-5881,MCAL-5856
 */
typedef uint32  Adc_ValueGroupType;

/*
 * Design: MCAL-5709
 */
typedef uint32  Adc_PrescaleType;

/*
 * Design: MCAL-5822
 */
typedef uint16  Adc_ConversionTimeType;

/*
 * Design: MCAL-5855
 */
typedef uint16  Adc_SamplingTimeType;

/*
 * Design: MCAL-5800
 */
typedef uint8   Adc_ResolutionType;

/*
 * Design: MCAL-5712
 */
typedef uint8   Adc_GroupPriorityType;

/*
 * Design: MCAL-5817
 */
typedef uint32  Adc_GroupDefType;

/*
 * Design: MCAL-5826
 */
typedef uint16  Adc_StreamNumSampleType;

/*
 * Design: MCAL-5858
 */
typedef uint8   Adc_HwTriggerTimerType;

typedef uint8   Adc_HWUnitType;

#if (STD_ON == ADC_INTERNAL_DIAGNOSTIC_DEBUG_MODE_API)

typedef uint8   Adc_RefSelType;
#endif

#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);

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

/*
 * Design: MCAL-5836
 */
typedef enum
{
    ADC_TRIGG_SRC_SW,
    ADC_TRIGG_SRC_HW
} Adc_TriggerSourceType;

/*
 * Design: MCAL-5735
 */
typedef enum
{
    ADC_CONV_MODE_ONESHOT,
    ADC_CONV_MODE_CONTINUOUS
} Adc_GroupConvModeType;

/*
 * Design: MCAL-5742
 */
typedef enum
{
    ADC_STREAM_BUFFER_LINEAR,
    ADC_STREAM_BUFFER_CIRCULAR
} Adc_StreamBufferModeType;

/*
 * Design: MCAL-5769
 */
typedef enum
{
    ADC_ACCESS_MODE_SINGLE,
    ADC_ACCESS_MODE_STREAMING
} Adc_GroupAccessModeType;

/*
 * Design: MCAL-5871
 */
typedef enum
{
    ADC_HW_TRIG_RISING_EDGE,
    ADC_HW_TRIG_FALLING_EDGE,
    ADC_HW_TRIG_BOTH_EDGES
} Adc_HwTriggerSignalType;

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

/*
 * Design: MCAL-5732
 */
typedef enum
{
    ADC_GROUP_REPL_ABORT_RESTART,
    ADC_GROUP_REPL_SUSPEND_RESUME,
} Adc_GroupReplacementType;

/*
 * Design: MCAL-5703
 */
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;

/*
 * Design: MCAL-5843
 */
typedef enum
{
    ADC_ALIGN_LEFT,
    ADC_ALIGN_RIGHT
} Adc_ResultAlignmentType;

/*
 * Design: MCAL-5829
 */
typedef enum
{
    ADC_FULL_POWER,
    ADC_ZERO_POWER
} Adc_PowerStateType;

/*
 * Design: MCAL-5705
 */
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;

typedef struct
{
    uint32              hwChannelId;
    uint32              openDelay;
    uint32              sampleDelay;
    uint32              rangeCheckEnable;
    Adc_AveragingMode   averagingMode;
} Adc_ChannelConfigType;

/*
 *Design: MCAL-5865,MCAL-5764,MCAL-5756,MCAL-5889,MCAL-5801,MCAL-5883,MCAL-5845,MCAL-5814,MCAL-5757,MCAL-5768
 */
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;
    uint32              baseAddr;
} Adc_HwUnitConfigType;

/*
 * Design: MCAL-5716,MCAL-5760,MCAL-5690
 */
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);

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)

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) */

#if (STD_ON == ADC_INTERNAL_DIAGNOSTIC_DEBUG_MODE_API)

FUNC(Std_ReturnType, ADC_CODE) Adc_EnableInternalDiagnostic(
    Adc_GroupType Group, Adc_RefSelType RefSelect);

FUNC(Std_ReturnType, ADC_CODE) Adc_DisableInternalDiagnostic(
    Adc_GroupType Group);
#endif  /* #if (STD_ON == ADC_INTERNAL_DIAGNOSTIC_DEBUG_MODE_API) */

#ifdef __cplusplus
}
#endif

#endif  /* #ifndef ADC_H_ */

/* @} */