/**
 *  @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_sram.h
 *  @version         1.0
 *  @brief           This file has the declarations for the SRAM diagnostic functions.     
 * 
 *************************************************************************/
/**
 @defgroup functions Functions
 @defgroup errorcodes ErrorCodes
 @defgroup macros Macros
 @defgroup enums Enums
*/
 
#ifndef DIAG_SRAM_H
#define DIAG_SRAM_H

/*Section: Included Files*/
#include <xc.h>
#include <stddef.h>
#include <stdbool.h>
#include "diag.h"

/**
 * @ingroup macros
 * @def DIAG_SRAM_SINGLE_BIT_ERROR_ISR_WAITING
 * @brief Status code indicating the ISR is waiting for a single-bit error event in SRAM.
 */
#define DIAG_SRAM_SINGLE_BIT_ERROR_ISR_WAITING 0x55555555U

/**
 * @ingroup macros
 * @def DIAG_SRAM_SINGLE_BIT_ERROR_ISR_TRIGGERED
 * @brief Status code indicating the ISR has been triggered by a single-bit error event in SRAM.
 */
#define DIAG_SRAM_SINGLE_BIT_ERROR_ISR_TRIGGERED 0xAAAAAAAAU

/**
 * @ingroup macros
 * @def DIAG_SRAM_DOUBLE_BIT_TRAP_WAITING
 * @brief Status code indicating the system is waiting for a double-bit error trap event in SRAM.
 */
#define DIAG_SRAM_DOUBLE_BIT_TRAP_WAITING 0xCCCCCCCCU

/**
 * @ingroup macros
 * @def DIAG_SRAM_DOUBLE_BIT_TRAP_ENTERED
 * @brief Status code indicating the system has entered the double-bit error trap in SRAM.
 */
#define DIAG_SRAM_DOUBLE_BIT_TRAP_ENTERED 0xBBBBBBBBU


/**
 * @ingroup enums
 * @enum DIAG_SRAM_eSramErrorEventType
 * @brief Enumerates the types of SRAM ECC error events.
 *
 * This enumeration defines the possible error event types that can occur in SRAM,
 * such as single-bit and double-bit error events.
 */
typedef enum
{
    SINGLE_BIT_ERROR_EVENT,
    DOUBLE_BIT_ERROR_EVENT        
}DIAG_SRAM_eSramErrorEventType;

/**
 * @ingroup functions
 * @brief Sets the entry status for the SRAM single-bit error ISR.
 *
 * This function updates the status variable that tracks the entry state of the
 * single-bit error interrupt service routine (ISR) for SRAM.
 *
 * @param[in] status  Status value to set (e.g., DIAG_SRAM_SINGLE_BIT_ERROR_ISR_WAITING or DIAG_SRAM_SINGLE_BIT_ERROR_ISR_TRIGGERED).
 * @par
 */
void DIAG_SRAM_SetSramSingleBitIsrEntryStatus(uint32_t status);

/**
 * @ingroup functions
 * @brief Sets the entry status for the SRAM double-bit error trap.
 *
 * This function updates the status variable that tracks the entry state of the
 * double-bit error trap for SRAM.
 *
 * @param[in] status  Status value to set (e.g., DIAG_SRAM_DOUBLE_BIT_TRAP_WAITING or DIAG_SRAM_DOUBLE_BIT_TRAP_ENTERED).
 * @par
 */
void DIAG_SRAM_SetSramDoubleBitTrapEntryStatus(uint32_t status);

/**
 * @ingroup functions
 * @brief **Software Requirement Reference ID : SW_SRAM_ECC_EVENT_INTERRUPT_TEST_01**\n
 *        **Software Requirement Reference ID : SW_SRAM_ECC_SINGLE_DOUBLE_ERROR_DETECTION_TEST_01**\n
 * Test and handle an ECC event interrupt in SRAM.
 *
 * This function simulates or handles an ECC event interrupt for SRAM by invoking
 * the appropriate error handler based on the error type and fault bit value.
 *
 * @param[in]  errorType            Type of ECC error (e.g., single or double bit).
 * @param[in]  sramFaultAddressPtr  Pointer to the address where the fault occurred.
 * @param[in]  faultBitValue        The value of the fault bit.
 *
 * @return Returns a status code indicating the result of the operation.
 *         The value is set by DIAG_SRAM_SetRetValue() and retrieved by DIAG_SRAM_GetRetValue().
 * @par
   Imageref DIAG_SRAM_SingleDoubleErrorDetectionTest_UML.svg "SRAM Single Double Error Detection Sequence Diagram"
   Imageref DIAG_SRAM_SingleDoubleErrorDetectionTest_ActivityDiagram.svg "SRAM Single Double Error Detection Activity Diagram"
 */
uint32_t DIAG_SRAM_SingleDoubleErrorDetectionTest(uint8_t errorType,uint32_t *sramFaultAddressPtr, uint8_t faultBitValue);

/**
 * @ingroup functions
 * @brief **Software Requirement Reference ID : SW_SRAM_REPLICATION_PRACTICE_01**\n
 * Replicates and inverts a block of SRAM data to a backup location.
 *
 * This function copies a block of data from the source address to the backup address,
 * inverting each 32-bit word during the copy. It performs checks for null pointers,
 * valid size, and overlapping memory regions before proceeding.
 *
 * @param[in]  srcAddress      Pointer to the source SRAM memory block.
 * @param[out] backUpAddress   Pointer to the destination (backup) SRAM memory block.
 * @param[in]  size            Number of 32-bit words to replicate and invert.
 *
 * @retval DIAG_PASS           Replication and inversion successful.
 * @retval DIAG_FAIL           Source and backup regions overlap.
 * @retval DIAG_INVALID_PARAM  Invalid parameters (null pointers or invalid size).
 *
 * @return Status code indicating the result of the operation, as set by
 *         DIAG_SRAM_SetRetValue() and retrieved by DIAG_SRAM_GetRetValue().
 * @par
   Imageref DIAG_SRAM_ReplicationWrite_UML.svg "SRAM Replication write Sequence Diagram"
   Imageref DIAG_SRAM_ReplicationWrite_ClassDiagram.svg "SRAM Replication Write Class Diagram"
 */
uint32_t DIAG_SRAM_ReplicationWrite(const uint32_t srcAddress[], uint32_t backUpAddress[], uint8_t size);

/**
 * @ingroup functions
 * @brief Validates that the backed-up SRAM data is the bitwise inverse of the source data.
 *
 * This function checks whether each 32-bit word in the backup memory block is the bitwise
 * inverse of the corresponding word in the source memory block. It performs parameter
 * validation and returns a status code indicating the result.
 *
 * @param[in] srcAddress        Pointer to the source SRAM memory block.
 * @param[in] backedUpAddress   Pointer to the backed-up (inverted) SRAM memory block.
 * @param[in] size              Number of 32-bit words to validate.
 *
 * @retval DIAG_PASS            All backed-up data is a valid bitwise inverse of the source data.
 * @retval DIAG_FAIL            At least one word in the backup is not the bitwise inverse of the source.
 * @retval DIAG_INVALID_PARAM   Invalid parameters (null pointers or invalid size).
 *
 * @return Status code indicating the result of the validation, as set by
 *         DIAG_SRAM_SetRetValue() and retrieved by DIAG_SRAM_GetRetValue().
 * @par
   Imageref DIAG_SRAM_IsBackedUpDataValid_UML.svg "SRAM Backed Up Data Valid Sequence Diagram"
   Imageref DIAG_SRAM_IsBackedUpDataValid_ClassDiagram.svg "SRAM Backed Up Data Valid Class Diagram"
 */
uint32_t DIAG_SRAM_IsBackedUpDataValid(const uint32_t srcAddress[], const uint32_t backedUpAddress[], uint8_t size);


#endif
