/**
*   @copyright       © 2026 Microchip Technology Inc.
    Microchip Technology Inc. and its subsidiaries. You may use this
    software and any derivatives exclusively with Microchip products.

    THIS SOFTWARE IS SUPPLIED BY MICROCHIP "AS IS". NO WARRANTIES, WHETHER
    EXPRESS, IMPLIED OR STATUTORY, APPLY TO THIS SOFTWARE, INCLUDING ANY IMPLIED
    WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY, AND FITNESS FOR A
    PARTICULAR PURPOSE, OR ITS INTERACTION WITH MICROCHIP PRODUCTS, COMBINATION
    WITH ANY OTHER PRODUCTS, OR USE IN ANY APPLICATION.

    IN NO EVENT WILL MICROCHIP BE LIABLE FOR ANY INDIRECT, SPECIAL, PUNITIVE,
    INCIDENTAL OR CONSEQUENTIAL LOSS, DAMAGE, COST OR EXPENSE OF ANY KIND
    WHATSOEVER RELATED TO THE SOFTWARE, HOWEVER CAUSED, EVEN IF MICROCHIP HAS
    BEEN ADVISED OF THE POSSIBILITY OR THE DAMAGES ARE FORESEEABLE. TO THE
    FULLEST EXTENT ALLOWED BY LAW, MICROCHIP'S TOTAL LIABILITY ON ALL CLAIMS IN
    ANY WAY RELATED TO THIS SOFTWARE WILL NOT EXCEED THE AMOUNT OF FEES, IF ANY,
    THAT YOU HAVE PAID DIRECTLY TO MICROCHIP FOR THIS SOFTWARE.

    MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE
    TERMS. 
*
*************************************************************************/

/**
 *  @file       diag_utility_timer.h
 *  @version   	1.0
 *  @brief  	This file has the definitions and declarations to be used by all 
 *              the Diagnostic modules, which may need to configure and read 
 *				values from the Timer module
 * 
 *************************************************************************/

/**
 * @defgroup functions Functions
 * @defgroup macros Macros
 * @defgroup enums Enums
 * @defgroup global_variables Global Variables
*/

#ifndef DIAG_UTILITY_TIMER_H
#define DIAG_UTILITY_TIMER_H

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

/* Macros*/
/**
 @ingroup macros
 @def DIAG_UTILITY_TIMER_TOTAL
 Total timers available. 
 */
#define DIAG_UTILITY_TIMER_TOTAL 5U

/* Structures*/
/**
 @struct DIAG_UTILITY_TIMER_DATA_LOOKUP
 Maintains the lookup for the necessary addresses for an timer instance.
 @var  DIAG_UTILITY_TIMER_DATA_LOOKUP::baseAddress
 Base address of the timer.
 @var  DIAG_UTILITY_TIMER_DATA_LOOKUP::periodOffsetAddress
 Period offset address of the timer.
 @var  DIAG_UTILITY_TIMER_DATA_LOOKUP::timerOffsetAddress
 TMR offset address of the timer.
 @var  DIAG_UTILITY_TIMER_DATA_LOOKUP::prescalerOffsetAddress
 Prescaler offset address of the timer.
 @var  DIAG_UTILITY_TIMER_DATA_LOOKUP::prescalerMask
 Prescaler mask of the timer.
 @var  DIAG_UTILITY_TIMER_DATA_LOOKUP::prescalerDataPosition
 Prescaler data position of the timer.
 @var  DIAG_UTILITY_TIMER_DATA_LOOKUP::timerEnableOffsetAddress
 Enable offset address of the timer.
 @var  DIAG_UTILITY_TIMER_DATA_LOOKUP::timerEnableMask
 Enable mask of the timer.
 @var  DIAG_UTILITY_TIMER_DATA_LOOKUP::interruptEnableAddress
 Interrupt enable address of the timer.
 @var  DIAG_UTILITY_TIMER_DATA_LOOKUP::interruptEnableMask
 Interrupt enable mask of the timer.
 @var  DIAG_UTILITY_TIMER_DATA_LOOKUP::interruptFlagAddress
 Interrupt flag address of the timer.
 @var  DIAG_UTILITY_TIMER_DATA_LOOKUP::interruptFlagMask
 Interrupt flag mask of the timer.
*/
typedef struct
{
    uint32_t baseAddress;
    uint32_t periodOffsetAddress;
    uint32_t timerOffsetAddress;
    uint32_t prescalerOffsetAddress;
    uint32_t prescalerMask;
    uint32_t prescalerDataPosition;
    uint32_t timerEnableOffsetAddress;
    uint32_t timerEnableMask;
    uint32_t interruptEnableAddress;
    uint32_t interruptEnableMask;
    uint32_t interruptFlagAddress;
    uint32_t interruptFlagMask;
}DIAG_UTILITY_TIMER_DATA_LOOKUP;

/** 
* @ingroup global_variables
* @brief This structure hold the look up data for all the available
* timer instances
*/
extern const DIAG_UTILITY_TIMER_DATA_LOOKUP timerDataLookup[DIAG_UTILITY_TIMER_TOTAL];

/* Enumerations */
/**
 @ingroup enums
 @enum DIAG_UTILITY_TIMER_INSTANCE
 The Ids which refer to timers available in the device.
 @var  DIAG_UTILITY_TIMER_INSTANCE::DIAG_UTILITY_TIMER_TMR1
 @var  DIAG_UTILITY_TIMER_INSTANCE::DIAG_UTILITY_TIMER_SCCP1
 @var  DIAG_UTILITY_TIMER_INSTANCE::DIAG_UTILITY_TIMER_SCCP2
 @var  DIAG_UTILITY_TIMER_INSTANCE::DIAG_UTILITY_TIMER_SCCP3
 @var  DIAG_UTILITY_TIMER_INSTANCE::DIAG_UTILITY_TIMER_SCCP4
*/
typedef enum
{
    DIAG_UTILITY_TIMER_TMR1,
    DIAG_UTILITY_TIMER_SCCP1,
    DIAG_UTILITY_TIMER_SCCP2,
    DIAG_UTILITY_TIMER_SCCP3,
    DIAG_UTILITY_TIMER_SCCP4
}DIAG_UTILITY_TIMER_INSTANCE;

/**
 @ingroup functions
 @brief ** DIAG_UTIL_TIMER_GetPeriodCount **\n
 Implements the function which returns value of the period count set for the 
 timer instance specified
 @param tmrInstance - Timer ID from the instances available on the device 
 @return -  Period count value set for the timer module
*/
/*LDRA_EXCLUDE 63 D : <justification start> Function definition is present in corresponding source file, violation ignored <justification end> */
uint32_t DIAG_UTIL_TIMER_GetPeriodCount(DIAG_UTILITY_TIMER_INSTANCE tmrInstance);

/**
 @ingroup functions
 @brief ** DIAG_UTIL_TIMER_GetTMRValue **\n
 Implements the function which returns value of the TMRx register for the timer
 instance specified
 @param tmrInstance - Timer ID from the instances available on the device  
 @return - TMRX value for the timer instance specified
*/
/*LDRA_EXCLUDE 63 D : <justification start> Function definition is present in corresponding source file, violation ignored <justification end> */
uint32_t DIAG_UTIL_TIMER_GetTMRValue(DIAG_UTILITY_TIMER_INSTANCE tmrInstance);

/**
 @ingroup functions
 @brief ** DIAG_UTIL_TIMER_GetPrescaler **\n
 Implements the function which returns value of the prescaler settings for the timer
 instance specified
 @param tmrInstance - Timer ID from the instances available on the device  
 @return - Prescaler value for the timer instance specified
*/
/*LDRA_EXCLUDE 63 D : <justification start> Function definition is present in corresponding source file, violation ignored <justification end> */
uint32_t DIAG_UTIL_TIMER_GetPrescaler(DIAG_UTILITY_TIMER_INSTANCE tmrInstance);

/**
 @ingroup functions
 @brief ** DIAG_UTIL_TIMER_SetPeriodCount **\n
 Implements the function which sets the period count for the timer instance 
 specified
 @param tmrInstance - Timer ID from the instances available on the device 
 @param prVal - Value of the period to be set for the timer instance specified
 @return void
*/
/*LDRA_EXCLUDE 63 D : <justification start> Function definition is present in corresponding source file, violation ignored <justification end> */
void DIAG_UTIL_TIMER_SetPeriodCount(DIAG_UTILITY_TIMER_INSTANCE tmrInstance, uint32_t prVal);

/**
 @ingroup functions
 @brief ** DIAG_UTIL_TIMER_SetPrescaler **\n
 Implements the function which sets the prescaler for the timer instance 
 specified
 @param tmrInstance - Timer ID from the instances available on the device 
 @param preScaleSetting - One of the available prescaler settings for the timer
 @return void
*/
/*LDRA_EXCLUDE 63 D : <justification start> Function definition is present in corresponding source file, violation ignored <justification end> */
void DIAG_UTIL_TIMER_SetPrescaler(DIAG_UTILITY_TIMER_INSTANCE tmrInstance, uint32_t preScaleSetting);

/**
 @ingroup functions
 @brief ** DIAG_UTIL_TIMER_SetTMRValue **\n
 Implements the function which sets the TMRx value for the timer instance 
 specified
 @param tmrInstance - Timer ID from the instances available on the device 
 @param tmrVal - Value to be set on the TMRx register
 @return void
*/
/*LDRA_EXCLUDE 63 D : <justification start> Function definition is present in corresponding source file, violation ignored <justification end> */
void DIAG_UTIL_TIMER_SetTMRValue(DIAG_UTILITY_TIMER_INSTANCE tmrInstance, uint32_t tmrVal);

/**
 @ingroup functions
 @brief ** DIAG_UTIL_TIMER_EnableTimer **\n
 Based on the Timer ID provided, this function enables that particular
 timer
 @param tmrInstance - Timer ID from the instances available on the device 
 @return void
*/
/*LDRA_EXCLUDE 63 D : <justification start> Function definition is present in corresponding source file, violation ignored <justification end> */
void DIAG_UTIL_TIMER_EnableTimer(DIAG_UTILITY_TIMER_INSTANCE tmrInstance);

/**
 @ingroup functions
 @brief ** DIAG_UTIL_TIMER_DisableTimer **\n
 Based on the Timer ID provided, this function disables that particular
 timer 
 @param tmrInstance - Timer ID from the instances available on the device 
 @return void
*/
/*LDRA_EXCLUDE 63 D : <justification start> Function definition is present in corresponding source file, violation ignored <justification end> */
void DIAG_UTIL_TIMER_DisableTimer(DIAG_UTILITY_TIMER_INSTANCE tmrInstance);

/**
 @ingroup functions
 @brief ** DIAG_UTIL_TIMER_DisableTimer **\n
 Based on the Timer ID provided, this function disables that particular
 timer interrupt
 @param tmrInstance - Timer ID from the instances available on the device 
 @return void
*/
/*LDRA_EXCLUDE 63 D : <justification start> Function definition is present in corresponding source file, violation ignored <justification end> */
void DIAG_UTIL_TIMER_DisableInterrupt(DIAG_UTILITY_TIMER_INSTANCE tmrInstance);

/**
 @ingroup functions
 @brief ** DIAG_UTIL_TIMER_EnableInterrupt **\n
 Based on the Timer ID provided, this function enables that particular
 timer interrupt.
 @param tmrInstance - Timer ID from the instances available on the device 
 @return void
*/
/*LDRA_EXCLUDE 63 D : <justification start> Function definition is present in corresponding source file, violation ignored <justification end> */
void DIAG_UTIL_TIMER_EnableInterrupt(DIAG_UTILITY_TIMER_INSTANCE tmrInstance);

/**
 @ingroup functions
 @brief ** DIAG_UTIL_TIMER_GetInterruptEnableStatus **\n
 Based on the Timer ID provided, this function returns the interrupt status 
 of that particular timer.
 @param tmrInstance - Timer ID from the instances available on the device 
 @return - true if interrupt is enabled, false otherwise.
*/
/*LDRA_EXCLUDE 63 D : <justification start> Function definition is present in corresponding source file, violation ignored <justification end> */
uint32_t DIAG_UTIL_TIMER_GetInterruptEnableStatus(DIAG_UTILITY_TIMER_INSTANCE tmrInstance);

/**
 @ingroup functions
 @brief ** DIAG_UTIL_TIMER_GetInterruptFlagStatus **\n
 Based on the Timer ID provided, this function returns the interrupt flag status 
 of that particular timer.
 @param tmrInstance - Timer ID from the instances available on the device 
 @return - true if interrupt flag is set, false otherwise.
*/
/*LDRA_EXCLUDE 63 D : <justification start> Function definition is present in corresponding source file, violation ignored <justification end> */
uint32_t DIAG_UTIL_TIMER_GetInterruptFlagStatus(DIAG_UTILITY_TIMER_INSTANCE tmrInstance);

#endif /* DIAG_UTILITY_TIMER_H */
