/**************************************************************************//**
 * @file     EEPROM_Emulate.h
 * @brief    Flash-based EEPROM emulation library for Nuvoton Nano100B series.
 *
 * @note
 * NEW IMPLEMENTATION - reverse-engineered from caller-side API only.
 * NOT BINARY COMPATIBLE with the original (factory) EEPROM_Emulate library.
 * If a board already has data written by the original library, this version
 * will treat that data as invalid and reset all settings to default (0xFF).
 *
 * Public API kept identical to the original so the application code compiles
 * without changes:
 *   - Init_EEPROM(data_size, page_amount)
 *   - Search_Valid_Page()
 *   - Read_Data(index, *data)  -> 0=OK, non-zero=error
 *   - Write_Data(index, value) -> 0=OK, non-zero=error
 *
 * Implementation summary:
 *   - Uses the last 1KB of APROM (2 flash pages, 512 bytes each).
 *   - Append-only entry log inside each page (wear-leveled).
 *   - Each entry is one 32-bit word: [TAG][index][~index][value].
 *   - When active page is full, contents are compacted into the other page.
 *   - RAM mirror of the data array for fast Read_Data().
 *
 ******************************************************************************/
#ifndef __EEPROM_EMULATE_H__
#define __EEPROM_EMULATE_H__

#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/*--------------------------------------------------------------------------*/
/* Configuration                                                             */
/*--------------------------------------------------------------------------*/

/* Maximum number of bytes the EEPROM can hold.
 * Must be >= the largest index your application uses (EEP_SIZE in My_define.h).
 * Current application uses EEP_SIZE = 69, so 128 leaves headroom.            */
#define EEP_DATA_SIZE          128u

/* Number of flash pages used for the emulation (must be >= 2). */
#define EEP_PAGE_COUNT         2u

/* Flash page size on Nano100B series (do not change). */
#define EEP_FLASH_PAGE_SIZE    0x200u   /* 512 bytes */

/* Base address of the EEPROM region inside APROM.
 * Default: last 1 KB of a 64 KB APROM (NANO100SE3BN has 64 KB).
 *
 * IMPORTANT - Linker script must guarantee that application code never
 * occupies this region. With the default linker script provided by Nuvoton
 * BSP this is fine as long as your firmware is < 63 KB. Verify with the
 * map file after build.
 *
 * If your part has a different APROM size, change this:
 *   - 32 KB part : 0x7C00
 *   - 64 KB part : 0xFC00  (default)
 *   - 128 KB part: 0x1FC00
 */
#define EEP_FLASH_BASE         0xFC00u

/*--------------------------------------------------------------------------*/
/* Compatibility: variables expected by the application's main.c            */
/*    Init_EEPROM(eep_data_size, eep_page_amount);                          */
/*--------------------------------------------------------------------------*/
extern const uint32_t eep_data_size;
extern const uint32_t eep_page_amount;

/*--------------------------------------------------------------------------*/
/* Public API                                                                */
/*--------------------------------------------------------------------------*/

/**
 * @brief  Initialize the EEPROM emulation layer.
 * @param  data_size    Logical size in bytes (clamped to EEP_DATA_SIZE).
 * @param  page_amount  Number of physical pages to use (currently fixed = 2).
 *
 * Must be called once before any Read/Write/Search call.
 * Enables FMC and unlocks protected registers.
 */
void     Init_EEPROM(uint32_t data_size, uint32_t page_amount);

/**
 * @brief  Locate the active flash page and load its contents into the RAM
 *         mirror. If no valid page is found, formats page 0 and starts fresh.
 *
 * Must be called once after Init_EEPROM(). After this call, Read_Data()
 * returns the latest committed value for each index.
 */
void     Search_Valid_Page(void);

/**
 * @brief  Read one byte from the EEPROM mirror.
 * @param  index   Index into the data array (0 .. EEP_DATA_SIZE-1).
 * @param  data    Output pointer. Receives 0xFF if the byte was never written.
 * @return 0 on success, non-zero on parameter error.
 */
uint32_t Read_Data(uint8_t index, uint8_t *data);

/**
 * @brief  Write one byte to the EEPROM (RAM mirror + flash).
 * @param  index   Index into the data array (0 .. EEP_DATA_SIZE-1).
 * @param  data    Value to store.
 * @return 0 on success, non-zero on parameter error.
 *
 * If the active flash page becomes full, contents are automatically
 * compacted into the other page.
 *
 * If the value is unchanged, no flash write is performed (saves wear).
 */
uint32_t Write_Data(uint8_t index, uint8_t data);

#ifdef __cplusplus
}
#endif

#endif /* __EEPROM_EMULATE_H__ */