/*
 * LittleFS block device adapter for W25QXX SPI Flash
 *
 * Maps littlefs read/prog/erase/sync callbacks to the W25QXX driver:
 *   read  -> W25QXX_Read
 *   prog  -> W25QXX_Write_NoCheck  (littleFS guarantees erase-before-prog)
 *   erase -> W25QXX_Erase_Sector   (4 KiB sector)
 *   sync  -> W25QXX_Wait_Busy
 */
#ifndef LFS_FLASHBD_H
#define LFS_FLASHBD_H

#include "lfs.h"
#include "lfs_util.h"
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/* W25QXX 扇区大小固定为 4096 字节 */
#define LFS_FLASHBD_SECTOR_SIZE  4096

/* Flash 块设备配置 */
struct lfs_flashbd_config {
    /* Flash 起始偏移地址（字节），必须 4096 对齐 */
    uint32_t base_addr;

    /* 使用的块（扇区）数量 */
    uint32_t block_count;
};

/* Flash 块设备状态 */
typedef struct lfs_flashbd {
    const struct lfs_flashbd_config *cfg;
} lfs_flashbd_t;


/* 初始化块设备（内部调用 W25QXX_Init） */
int lfs_flashbd_create(const struct lfs_config *cfg,
        const struct lfs_flashbd_config *bdcfg);

/* 销毁块设备（当前为空操作） */
int lfs_flashbd_destroy(const struct lfs_config *cfg);

/* 读取一个块的区域 */
int lfs_flashbd_read(const struct lfs_config *cfg, lfs_block_t block,
        lfs_off_t off, void *buffer, lfs_size_t size);

/* 编程一个块的区域（块必须已擦除） */
int lfs_flashbd_prog(const struct lfs_config *cfg, lfs_block_t block,
        lfs_off_t off, const void *buffer, lfs_size_t size);

/* 擦除一个块（4 KiB 扇区） */
int lfs_flashbd_erase(const struct lfs_config *cfg, lfs_block_t block);

/* 同步块设备（等待 Flash 空闲） */
int lfs_flashbd_sync(const struct lfs_config *cfg);


/*
 * 便捷函数：用 W25QXX 默认参数填充 lfs_config 和 flashbd 配置。
 *
 * 调用者需提供 lfs_config、lfs_flashbd_t、lfs_flashbd_config 结构体
 * （可以是在栈上或静态分配），以及 Flash 起始地址和使用的块数量。
 *
 * 如果 read_buffer / prog_buffer / lookahead_buffer 为 NULL，
 * littleFS 会通过 lfs_malloc 动态分配缓存。
 * 静态 lookahead_buffer 大小需 >= lookahead_size = ceil(block_count / 8) 字节。
 *
 * 典型用法（W25Q80，从地址 0 开始使用全部 1 MB）：
 *
 *   lfs_t lfs;
 *   lfs_flashbd_t bd;
 *   struct lfs_flashbd_config bd_cfg;
 *   struct lfs_config cfg;
 *   uint8_t read_buf[256], prog_buf[256], lookahead_buf[32]; // 256 块 -> 32 字节
 *
 *   lfs_flashbd_default_config(&cfg, &bd, &bd_cfg, 0, 256,
 *       read_buf, prog_buf, lookahead_buf);
 *   lfs_format(&lfs, &cfg);   // 首次使用需格式化
 *   lfs_mount(&lfs, &cfg);
 */
void lfs_flashbd_default_config(
        struct lfs_config *cfg,
        lfs_flashbd_t *bd,
        struct lfs_flashbd_config *bdcfg,
        uint32_t base_addr,
        uint32_t block_count,
        void *read_buffer,
        void *prog_buffer,
        void *lookahead_buffer);


#ifdef __cplusplus
} /* extern "C" */
#endif

#endif /* LFS_FLASHBD_H */