/*********************************************************************************************************
 *  ------------------------------------------------------------------------------------------------------
 *  file description
 *  ------------------------------------------------------------------------------------------------------
 *         \file  ramt.h
 *         \unit  ramt
 *        \brief  This is a simple ram test module for C language
 *       \author  Lamdonn
 *      \version  v0.1.0
 *      \license  GPL-2.0
 *    \copyright  Copyright (C) 2023 Lamdonn.
 ********************************************************************************************************/
#ifndef __ramt_H
#define __ramt_H

#include <stdio.h>
#include <stdint.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>

/* Version infomation */
#define RAMT_V_MAJOR                        0
#define RAMT_V_MINOR                        1
#define RAMT_V_PATCH                        0

// Define different RAM test modes
#define RAMT_MODE_NORMAL                    ((uint32_t)0x00000001) // Normal read/write test
#define RAMT_MODE_BOUNDARY                  ((uint32_t)0x00000002) // Boundary test
#define RAMT_MODE_PATTERN                   ((uint32_t)0x00000004) // Data pattern test
#define RAMT_MODE_RANDOM                    ((uint32_t)0x00000008) // Random access test
#define RAMT_MODE_INVERSION                 ((uint32_t)0x00000010) // Inversion test
#define RAMT_MODE_CLEARING                  ((uint32_t)0x00000020) // Clearing test
#define RAMT_MODE_SPECIFIC                  ((uint32_t)0x00000040) // Specific data test

// RAM structure definition
typedef struct 
{
    void *base;                             // Pointer to the simulated RAM
    uint32_t size;                          // Size of the RAM
    uint32_t private[4];                    // Private data, modification not allowed
} RAMT;

/** 
 *  \brief Initialize RAMT structure
 *  \param[in] ramt: Pointer to the RAMT structure to be initialized
 *  \return 1 if initialization is successful, 0 if it fails
 */
int ramt_init(RAMT *ramt);

/** 
 *  \brief Start the RAM testing with specified mode and duration
 *  \param[in] ramt: Pointer to the RAMT structure
 *  \param[in] mode: The mode of the RAM test, see RAMT_MODE_XXX define
 *  \param[in] duration: The duration for which the RAM test should run, 0xFFFFFFFF continuous running
 *  \return 1 if the operation is successful, 0 if it fails
 */
int ramt_start(RAMT *ramt, uint32_t mode, uint32_t duration);

/** 
 *  \brief Stop the RAM testing
 *  \param[in] ramt: Pointer to the RAMT structure
 *  \return 1 if the operation is successful, 0 if it fails
 */
int ramt_stop(RAMT *ramt);

/** 
 *  \brief Retrieve the historical result of the RAM test
 *  \param[in] ramt: Pointer to the RAMT structure
 *  \return The result history if successful, 0xFFFFFFFF if it invalid, fail mask see RAMT_MODE_XXX define
 */
uint32_t ramt_result(RAMT *ramt);

/** 
 *  \brief Retrieve the latest result of the RAM test
 *  \param[in] ramt: Pointer to the RAMT structure
 *  \return The latest result if successful, 0xFFFFFFFF if it invalid, fail mask see RAMT_MODE_XXX define
 */
uint32_t ramt_result_latest(RAMT *ramt);

/** 
 *  \brief Periodically execute RAM testing tasks based on the mode and duration
 *  \param[in] ramt: Pointer to the RAMT structure
 */
void ramt_task(RAMT *ramt);

#endif