/**
 * 日期: 2025-12-05
 * 作者: coffee
 * 描述: Flash内存映射, 使用脏页机制加速Flash
 */

#ifndef __H_FLASH_MEM_H__
#define __H_FLASH_MEM_H__


#include <stdint.h>


// 使用定时器任务ID
#ifndef HFLASH_TIMER_ID
#define HFLASH_TIMER_ID 0
#endif

///< 以下IO指令必须实现
enum eHFlashMemIO
{
    kHFlashMemIOErase,      ///< 请求该地址擦除, 异步非阻塞(addr, cmd, NULL)
    kHFlashMemIOCheckErase, ///< 检查是否已擦除完成(0, cmd, uint8_t *status) status设置为0:未擦除, 1:已擦除
    kHFlashMemIOSyncErase,  ///< 请求该地址擦除, 同步阻塞到完成(addr, cmd, NULL)
};

///< 内存缓存页, 配置需和 (memSize / 4096) 大小一致
typedef struct HFlashMemCache
{
    uint32_t addr;                  ///< 地址
    uint16_t offset;                ///< 内存偏移
    uint16_t eraseStatus    : 2;    ///< 擦除状态
    uint16_t isDirty        : 1;    ///< 是否脏页
    uint16_t heat           : 4;    ///< 热度优先级
} HFlashMemCache;

///< 内存操作, 回调返回0表示失败
typedef struct HFlashMemOpts
{
    uint8_t (*read)(uint32_t addr, void *buf, uint32_t len);        ///< 读取Flash
    uint8_t (*write)(uint32_t addr, const void *buf, uint32_t len); ///< 写入Flash
    uint8_t (*ioctl)(uint32_t aadr, uint32_t cmd, void *arg);       ///< 控制Flash, 需要外部实现以上eHFlashMemIO指令
    uint8_t *mem;                                                   ///< Flash映射内存, 需要4k倍数
    HFlashMemCache *cache;                                          ///< 内存缓存
    uint16_t memSize;                                               ///< Flash映射内存大小
    uint16_t cacheSize;                                             ///< 内存缓存大小
} HFlashMemOpts;

/**
 * @brief 初始化Flash内存映射
 * @param opts 内存操作信息
 */
void HFlashMemInit(HFlashMemOpts *opts);

/**
 * @brief 读取Flash
 * @param addr 读取地址
 * @param buf 读取数据写入缓存的内存
 * @param len 读取长度
 * @return 成功返回1, 失败返回0
 */
uint8_t HFlashMemRead(uint32_t addr, void *buf, uint32_t len);

/**
 * @brief 写入Flash
 * @param addr 写入地址
 * @param buf 写入数据
 * @param len 写入长度
 * @return 成功返回1, 失败返回0
 */
uint8_t HFlashMemWrite(uint32_t addr, const void *buf, uint32_t len);

/**
 * @brief 设置Flash值
 * @param addr 写入地址
 * @param value 写入值
 * @param len 写入长度
 * @return 成功返回1, 失败返回0
 */
uint8_t HFlashMemSetValue(uint32_t addr, uint8_t value, uint32_t len);

/**
 * @brief Flash数据拷贝
 * @param srcAddr 源地址
 * @param destAddr 目标地址
 * @param len 拷贝长度
 */
uint8_t HFlashMemAddrCopy(uint32_t srcAddr, uint32_t destAddr, uint32_t len);

/**
 * @brief Flash数据映射回调
 * @param addr 地址
 * @param call 回调函数, 终止继续读取返回非0, 每次按页读取, 请根据偏移进行判断
 * @param arg 回调函数参数
 * @return call返回值
 */
uint8_t HFlashMemMMapCall(uint32_t addr, uint8_t(*call)(uint32_t addr, uint32_t offset, const uint8_t *data, uint16_t len, void *arg), void *arg);

/**
 * @brief 同步脏页写入Flash
 */
void HFlashMemSync();

/**
 * @brief 释放缓存页
 */
void HFlashFreeCache();

#endif // __H_FLASH_MEM_H__