/**
*   @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_flash.h
 *  @version       	1.0
 *  @brief     		This file has the declarations for the FLASH diagnostic 
 *					functions.
 *************************************************************************/

/**
 * @defgroup functions Functions
 * @defgroup macros Macros
 * @defgroup errorcodes ErrorCodes
 * @defgroup enums Enums
*/
 
#ifndef DIAG_FLASH_H
#define DIAG_FLASH_H

/*Section: Included Files*/
#include <stdint.h>
#include "diag.h"

/* Enumerations */

/* Structure definitions */
/**
 @struct DIAG_FLASH_DATA_WRITE
 Maintains the necessary structure to handle flash write and read
 @var  DIAG_FLASH_DATA_WRITE::data
 Array to handle flash word data
*/
typedef struct
{
    uint32_t data[4];
}DIAG_FLASH_DATA_WRITE;

/* Function Declarations */
/**
 @ingroup functions
 @brief **Software Requirement Reference ID : SW_FLASH_ECC_SINGLE_DOUBLE_ERROR_DETECTION_TEST_01**\n
 The diagnostic API is aimed to verify the functionality of the hardware 
 detecting a single or a double-bit error. The faults are induced using the ECC
 fault mechanics. On successful detection the diagnostics returns a pass 
 otherwise fail.
 @param *location - Pointer to the Flash location
 @return @ref DIAG_PASS \n
 @return @ref DIAG_FAIL \n
 @return @ref DIAG_INVALID_PARAM \n

 @par
Imageref DIAG_FLASH_SingleDoubleErrorDetectionTest_UML.svg "FLASH Single Double Error Detection Test" 
Imageref DIAG_FLASH_SingleDoubleErrorDetectionTest_ClassDiagram.svg "FLASH Single Double Error Detection Test Class Diagram"
 */
uint32_t DIAG_FLASH_SingleDoubleErrorDetectionTest(uint32_t *location);

/**
 @ingroup functions
 @brief **Software Requirement Reference ID : SW_FLASH_INTEGRITY_READ_PRACTICE_01**\n
 The diagnostic API is aimed to verify the data integrity. The flash location 
 which is of interest is accessed using a read operation to check for data 
 integrity. If any errors are detected by the ECC the diagnostics returns a fail
 and if no errors detected the diagnostics returns a pass.
 @param *location - Pointer to the Flash location
 @return @ref DIAG_PASS \n
 @return @ref DIAG_FAIL \n
 @return @ref DIAG_INVALID_PARAM \n
  
 @par
Imageref DIAG_FLASH_IntegrityReadPractice_UML.svg "FLASH Integrity Read Practice" 
Imageref DIAG_FLASH_IntegrityReadPractice_ClassDiagram.svg "FLASH Integrity Read Practice Class Diagram"
 */
uint32_t DIAG_FLASH_IntegrityReadPractice(uint32_t *location);

/**
 @ingroup functions
 @brief **Software Requirement Reference ID : SW_FLASH_WRITE_VERIFY_PRACTICE_01**\n
 The diagnostic API is aimed to verify the data authenticity. The flash location 
 which is of interest is accessed using a read operation and compared with the
 user data for authenticity. The diagnostics return pass on data match otherwise
 returns fail.
 @param *location - Pointer to the Flash location
 @param dataToAuthenticate - Data for comparison
 @return @ref DIAG_PASS \n
 @return @ref DIAG_FAIL \n
 @return @ref DIAG_INVALID_PARAM \n

 @par
Imageref DIAG_FLASH_WriteVerifyPractice_UML.svg "FLASH Write Verify Practice" 
Imageref DIAG_FLASH_WriteVerifyPractice_ClassDiagram.svg "FLASH Write Verify Practice Class Diagram"
 */
uint32_t DIAG_FLASH_WriteVerifyPractice(uint32_t *location, DIAG_FLASH_DATA_WRITE dataToAuthenticate);

/**
 @ingroup functions
 @brief **Software Requirement Reference ID : SW_FLASH_MEMORY_CRC_PRACTICE_01**\n
 The API calculates the CRC value for the flash block using the NVM CRC.
 @param *flashBlockStart - Pointer to starting address of the flash block for testing
 @param *flashBlockEnd - Pointer to end address of the flash block for testing
 @return Calculated CRC for the flash block
 */
uint32_t DIAG_FLASH_CRCCalculate(uint32_t *flashBlockStart, uint32_t *flashBlockEnd);

/**
 @ingroup functions
 @brief **Software Requirement Reference ID : SW_FLASH_MEMORY_CRC_PRACTICE_01**\n
 The diagnostic API calculates the CRC value for the flash block using the NVM CRC
 and compares with previous calculated CRC to check for authenticity. The 
 diagnostics shall return pass on success full authentication otherwise returns fail.
 @param *flashBlockStart - Pointer to starting address of the flash block for testing
 @param *flashBlockEnd - Pointer to end address of the flash block for testing
 @param previousCRC - Previously calculated CRC value for the same block
 @return @ref DIAG_PASS \n
 @return @ref DIAG_FAIL \n
 @return @ref DIAG_INVALID_PARAM \n
 
 @par
Imageref DIAG_FLASH_CRCPractice_UML.svg "FLASH CRC Practice" 
Imageref DIAG_FLASH_CRCPractice_ClassDiagram.svg "FLASH CRC Practice Class Diagram"
 */
uint32_t DIAG_FLASH_CRCPractice(uint32_t *flashBlockStart, uint32_t *flashBlockEnd, uint32_t previousCRC);

#endif /* DIAG_FLASH_H */
