/**
 * @file esc_eeprom.h
 * @brief 通过 LAN9252 HBI Indexed 间接访问烧录外部 AT24C32 EEPROM (ESI)。
 *
 * 硬件前提（必须满足，否则模块不可用）：
 *   - LAN9252 A2 (Pin 29) 必须接到 GD32 EXMC A17 (PD12)，以访问 HBI_DATA_0 寄存器。
 *     注意：LAN9252 引脚顺序为 Pin25=A1, Pin26=A3, Pin27=A4, Pin28=CS, Pin29=A2。
 *     A2 是区分 IDX/DATA 寄存器的关键位（A2=0→IDX, A2=1→DATA），不接 A2 无法访问 DATA 寄存器。
 *   - A3/A4 可不接（仅访问 HBI_IDX_0/DATA_0 时不需要）。
 *   - LAN9252 处于 16-bit HBI Indexed Mode（CHIP_MODE 配置）。
 *
 * ESC EEPROM 寄存器映射（参见 LAN9252 DS00001909A 12.14.47~12.14.51）：
 *   0x0500  EEPROM Configuration       (8-bit)
 *   0x0501  EEPROM PDI Access State    (8-bit)
 *   0x0502  EEPROM Control/Status      (16-bit)
 *   0x0504  EEPROM Address             (32-bit)
 *   0x0508  EEPROM Data                (32-bit, 低 16 位为读写数据)
 *
 * 调用约束：INIT-ONLY，仅允许在 EthercatSync::init() 使能 EXTI NVIC 之前调用。
 */
#ifndef COMM_ESC_EEPROM_H
#define COMM_ESC_EEPROM_H

#include <cstdint>
#include <cstddef>

class EscEeprom {
public:
    /** @brief 初始化：获取 PDI 对 EEPROM 接口的控制权并验证总线。
     *  @return true 表示成功获取 EEPROM 控制权。 */
    static bool init();

    /** @brief 读取 EEPROM 一个 16-bit word。
     *  @param word_addr  word 地址（0 ~ 2047，对应 AT24C32 的 4KB 空间）。
     *  @param out        输出读取到的 16-bit 数据。
     *  @return true 表示读取成功。 */
    static bool readWord(uint16_t word_addr, uint16_t &out);

    /** @brief 写入 EEPROM 一个 16-bit word。
     *  @param word_addr  word 地址。
     *  @param data       要写入的 16-bit 数据。
     *  @return true 表示写入成功。 */
    static bool writeWord(uint16_t word_addr, uint16_t data);

    /** @brief 批量烧录 ESI 数据。
     *  @param data  数据缓冲区（按 byte 流给出，内部按 word 对齐处理）。
     *  @param len   数据长度（字节，应为 2 的倍数；奇数时末尾补 0xFF）。
     *  @return true 表示全部写入成功。 */
    static bool writeEsi(const uint8_t *data, size_t len);

    /** @brief 回读校验 ESI 数据。
     *  @param data  期望数据缓冲区。
     *  @param len   校验长度（字节）。
     *  @return true 表示回读数据与期望一致。 */
    static bool verifyEsi(const uint8_t *data, size_t len);

    /** @brief 触发 EEPROM 重新加载（写完 ESI 后调用，使 LAN9252 重新读取配置）。
     *  @return true 表示 Reload 命令已发出。 */
    static bool reload();

    /** @brief 查询 EEPROM 加载状态。
     *  @return true 表示 EEPROM 已加载且设备信息正常。 */
    static bool isLoaded();

    /** @brief AT24C32 容量（字节）。 */
    static constexpr size_t EEPROM_SIZE_BYTES = 4096U;
    /** @brief AT24C32 word 数。 */
    static constexpr uint16_t EEPROM_WORD_COUNT = 2048U;

private:
    static bool s_inited;
};

#endif /* COMM_ESC_EEPROM_H */