/**
*   @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_delay.h
 *  @version       	1.0
 *  @brief     		This file has the implementation for the delay routine
 *                  in assembly with wrappers provided for millisecond and
 *                  microsecond delay.
 *************************************************************************/

/**
 * @defgroup functions Functions
 * @defgroup macros Macros
 * @defgroup enums Enums
*/

#ifndef DIAG_DELAY_H
#define	DIAG_DELAY_H

#include <stdint.h>

/**
 * @ingroup macros
 * @def DIAG_DELAY_MICROSECOND_DIVIDER
 * @brief Divider value to convert clock frequency to microseconds.
 * @details Used to calculate the number of clock cycles in one microsecond based on the system clock frequency.
 */
#define DIAG_DELAY_MICROSECOND_DIVIDER 1000000U

/**
 * @ingroup macros
 * @def DIAG_DELAY_MILLISECOND_DIVIDER
 * @brief Divider value to convert clock frequency to milliseconds.
 * @details Used to calculate the number of clock cycles in one millisecond based on the system clock frequency.
 */
#define DIAG_DELAY_MILLISECOND_DIVIDER 1000U

/**
 * @ingroup functions
 * @brief Sets the system clock frequency for delay calculations.
 * @param clockfreq System clock frequency in Hz.
 * @par
 * @details Stores the provided clock frequency and calculates the number of instruction cycles required for 1 microsecond and 1 millisecond delays. These values are used by the delay functions to generate accurate timing.
 */
/*LDRA_EXCLUDE 63 D : <justification start> Function definition is present in corresponding source file, violation ignored <justification end> */
void DIAG_SetClockFreq(uint32_t clockfreq);

/**
 * @ingroup functions
 * @brief Delays execution for a specified number of milliseconds.
 * @param msdelay Number of milliseconds to delay.
 * @details Multiplies the millisecond delay value by the pre-calculated instruction count for one millisecond, then calls DIAG_delayInstrCount() to perform the actual delay using a repeat-nop loop.
 */
/*LDRA_EXCLUDE 63 D : <justification start> Function definition is present in corresponding source file, violation ignored <justification end> */
void DIAG_delayMs(uint32_t msdelay);

/**
 * @ingroup functions
 * @brief Delays execution for a specified number of microseconds.
 * @param usdelay Number of microseconds to delay.
 * @details Multiplies the microsecond delay value by the pre-calculated instruction count for one microsecond, then calls DIAG_delayInstrCount() to perform the actual delay using a repeat-nop loop.
 */
/*LDRA_EXCLUDE 63 D : <justification start> Function definition is present in corresponding source file, violation ignored <justification end> */
void DIAG_delayUs(uint32_t usdelay);

/**
 * @ingroup functions
 * @brief Delays execution for a specified number of instruction cycles.
 * @param count Number of instruction cycles to delay.
 * @par
 * @details Uses an inline assembly loop to execute a "repeat-nop" instruction sequence for the specified number of cycles, providing a precise delay based on the system clock.
 */
/*LDRA_EXCLUDE 63 D : <justification start> Function definition is present in corresponding source file, violation ignored <justification end> */
void DIAG_delayInstrCount(uint32_t count);

/**
 * @ingroup functions
 * @brief Gets the current system clock frequency.
 * @return Current system clock frequency in Hz.
 * @details Returns the value stored by DIAG_SetClockFreq(), representing the clock frequency used for delay calculations.
 */
/*LDRA_EXCLUDE 63 D : <justification start> Function definition is present in corresponding source file, violation ignored <justification end> */
uint32_t DIAG_GetClockFreq(void);


#endif	/* DIAG_DELAY_H */

