/**********************************************************************
*   Copyright: (C)2024 LingYun IoT System Studio
*      Author: GuoWenxue<guowenxue@gmail.com>
* Description: I2C EEPROM device driver for ISKBoard
*
*   ChangeLog:
*        Version    Date       Author            Description
*        V1.0.0  2024.08.29    GuoWenxue      Release initial version
***********************************************************************/
#ifndef __EEPROM_H__
#define __EEPROM_H__

#include "i2c_bitbang.h"

#define EEPROM_INFO(_name, _cap, _page, _addr_bytes) \
        .name        = _name,       \
        .capacity    = _cap,        \
        .page_size   = _page,       \
        .addr_bytes  = _addr_bytes, \
        .n_pages     = (_cap)/(_page)

typedef struct eeprom_info
{
    const char     *name;         /* 芯片型号名称，如 "AT24C256" */
    uint32_t        capacity;     /* 总容量 (Bytes) */
    uint32_t        page_size;    /* 单页大小 (Bytes) */
    uint8_t         addr_bytes;   /* 片内寻址字节数：1 或 2 */
    uint32_t        n_pages;      /* 总页数 */
} eeprom_info_t;

/* 设备运行时上下文结构体 */
typedef struct eeprom_dev
{
    i2c_bus_t            *bus;       /* 绑定的 I2C 总线 */
    uint8_t               dev_addr;  /* 基础 I2C 从机地址 (通常为 0x50) */
    const eeprom_info_t  *info;      /* 指向匹配成功的规格信息，直接替代原 switch-case */
} eeprom_dev_t;

/* 导出 API */

/**
 * @brief  初始化 EEPROM 设备结构体对象
 * @note   该函数仅做内部参数映射与规格配置(如页大小、芯片容量)。
 * @param  eeprom:   指向 EEPROM 设备句柄的指针
 * @param  bus:      绑定的物理 I2C 总线对象指针
 * @param  dev_addr: EEPROM 的 7 位 I2C 从机基地址 (例如 AT24C256 常规为 0x50)
 * @param  chip_name: EEPROM 的芯片型号名称 (例如 "AT24C256")
 * @retval None
 */
int eeprom_init(eeprom_dev_t *eeprom, i2c_bus_t *bus, uint8_t dev_addr, const char *chip_name);

/**
 * @brief  从 EEPROM 的指定内部地址连续读取数据
 * @param  eeprom:   指向已初始化的 EEPROM 设备句柄的指针
 * @param  reg_addr: 芯片内部物理存储的 16 位起始地址 (0x0000 ~ 0x7FFF)
 * @param  buf:      存放接收数据的用户缓冲区指针
 * @param  len:      期望读取的数据字节数
 * @retval I2C_OK: 读取成功; I2C_ERROR: 总线或从机无应答; I2C_BUSY: 总线被占用
 */
i2c_status_t eeprom_read(eeprom_dev_t *eeprom, uint16_t reg_addr, uint8_t *buf, uint16_t len);

/**
 * @brief  向 EEPROM 的指定内部地址连续写入数据（含跨页切片处理）
 * @param  eeprom:   指向已初始化的 EEPROM 设备句柄的指针
 * @param  reg_addr: 芯片内部物理存储的 16 位起始地址 (0x0000 ~ 0x7FFF)
 * @param  buf:      存放待发送数据的源缓冲区指针
 * @param  len:      期望写入的数据字节数
 * @retval I2C_OK: 全部数据写入成功; I2C_ERROR: 期间发生物理通信故障
 */
i2c_status_t eeprom_write(eeprom_dev_t *eeprom, uint16_t reg_addr, uint8_t *buf, uint16_t len);

/**
 * @brief  EEPROM 测试函数
 * @param  bus: 绑定的物理 I2C 总线对象指针
 * @retval None
 */
int eeprom_test(i2c_bus_t *bus);

#endif /* __EEPROM_H__ */