/**
 * 日期: 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

// Flash内存大小, 需要4k倍数
#ifndef HFLASH_MEM_SIZE
#define HFLASH_MEM_SIZE (4096 * 3)
#endif

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

///< 内存缓存页, 配置需和 (memSize / 4096) 大小一致
typedef struct HFlashMemCache
{
    uint32_t addr;                  ///< 地址
    uint16_t offset;                ///< 内存偏移
    uint16_t eraseStatus    : 2;    ///< 擦除状态
    uint16_t isDirty        : 1;    ///< 是否脏页
} 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
    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 读取长度
 */
uint8_t HFlashMemRead(uint32_t addr, void *buf, uint32_t len);

/**
 * @brief 写入Flash
 * @param addr 写入地址
 * @param buf 写入数据
 * @param len 写入长度
 */
uint8_t HFlashMemWrite(uint32_t addr, const void *buf, uint32_t len);

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

#endif // __H_FLASH_MEM_H__