/**
 * 日期: 2025-11-27
 * 作者: coffee
 * 描述: Flash通用服务模块, 用于保证性Flash操作
 */


#ifndef __H_FLASH_SERVER_H__
#define __H_FLASH_SERVER_H__


///< Flash块大小, 按块操作, 2的幂关系
#ifndef HFLASH_BLOCK_SIZE
#define HFLASH_BLOCK_SIZE  (4096)
#endif

///< 获取缓存内存, 需要大于Flash一块大小
#ifndef HFLASH_MALLOC
#define HFLASH_MALLOC(size) malloc(size)
#endif

///< 释放缓存
#ifndef HFLASH_FREE
#define HFLASH_FREE(ptr) free(ptr)
#endif

#include <stdint.h>
#include <stdlib.h>

///< Flash地址类型
typedef uint32_t HFlashAddr_t;

///< Flash页表信息
typedef union HFlashPageInfo {
    uint8_t reverse[32];    ///< 每页的信息占用32字节
    struct __attribute__((packed)) {
        HFlashAddr_t addr;          ///< 地址
        uint32_t crc32;             ///< 使用大小内容的CRC32
        uint32_t size       : 24;   ///< 大小
        uint32_t useSize    : 24;   ///< 使用大小
        uint16_t version;           ///< 当前页数据的版本
        uint32_t modifyCount;       ///< 修改次数
    };
} HFlashPageInfo;

typedef struct HFlashCacheInfo {
    HFlashPageInfo info;    ///< 页表信息
    uint32_t pos    : 19;   ///< 存储页表信息的位置
    uint32_t heat   : 4;    ///< 热度优先级
} HFlashCacheInfo;


/**
 * @brief HFlashEraseCallback 擦除回调
 * @param addr Flash地址
 * @return 1: 擦除成功 0: 擦除失败
 */
typedef uint8_t (*HFlashEraseCallback)(HFlashAddr_t addr);

/**
 * @brief HFlashReadCallback 读取回调
 * @param addr Flash地址
 * @param data Flash读取写入的缓存数据内存
 * @param size 缓存大小
 * @return 1: 读取成功 0: 读取失败
 */
typedef uint8_t (*HFlashReadCallback)(HFlashAddr_t addr, uint8_t *data, uint32_t size);

/**
 * @brief HFlashWriteCallback 写入回调
 * @param addr Flash地址
 * @param data Flash读取写入的缓存数据内存
 * @param size 缓存大小
 * @return 1: 写入成功 0: 写入失败
 */
typedef uint8_t (*HFlashWriteCallback)(HFlashAddr_t addr, uint8_t *data, uint32_t size);

/**
 * @brief HFlashInitCallback 设置Flash初始化回调
 * @param read 读取回调
 * @param write 写入回调
 * @param erase 擦除回调
 */
void HFlashInitCallback(HFlashReadCallback read, HFlashWriteCallback write, HFlashEraseCallback erase);

/**
 * @brief HFlashSetPageCache 设置页表缓存, 内部不构建内存, 由外部分配
 * @param pageInfo 页表信息缓存
 * @param size 大小
 */
void HFlashSetPageCache(HFlashCacheInfo *pageInfo, uint16_t size);

/**
 * @brief HFlashSetPageAddr 设置页表地址
 * @param addr 地址
 * @param size 大小
 */
void HFlashSetPageAddr(HFlashAddr_t addr, uint32_t size);

/**
 * @brief HFlashSetPageBackupAddr 设置页表备份地址
 * @param addr 地址
 * @param size 大小, 必须和页表地址大小相同
 */
void HFlashSetPageBackupAddr(HFlashAddr_t addr, uint32_t size);

/**
 * @brief HFlashProtectAddr 设置保护地址, 内部会使用双备份区域
 * @param addr 地址
 * @param size 大小
 */
void HFlashProtectAddr(HFlashAddr_t addr, uint32_t size);

/**
 * @brief HFlashProtectBackupAddr 设置保护备份地址
 * @param addr 地址
 * @param size 大小, 必须和保护地址大小相同
 */
void HFlashProtectBackupAddr(HFlashAddr_t addr, uint32_t size);

/**
 * @brief HFlashInitCheck 在HFlashRegister前需要初始化检查, 用于检查页表是否可用, 不可用则需要初始化
 */
void HFlashInitCheck();

/**
 * @brief HFlashRegister 注册地址到页表
 * @param addr 地址
 * @param size 该地址占用的大小
 */
void HFlashRegister(HFlashAddr_t addr, uint32_t size);

/**
 * @brief HFlashWrite 写入Flash, 需要注册的地址
 * @param addr 地址
 * @param data 写入数据
 * @param size 写入数据大小
 */
void HFlashWrite(HFlashAddr_t addr, void *data, uint32_t size);

#endif // __H_FLASH_SERVER_H__