/**
 * @file esc_lan9252.h
 * @brief LAN9252 EtherCAT 从站控制器(ESC)驱动接口。
 * @note 通过 EscExmcBus 16-bit 并行总线,以 HBI Indexed Address Mode 访问
 *       LAN9252 寄存器与 PDI 内存:先写 HBI_IDX_0,再读写 HBI_DATA_0。
 *
 *       接口调用约束(避免 EXMC 总线争用):
 *       - 运行期 ESC 寄存器/PDI 访问统一走 SSC 移植层 hw_gd32exmc.cpp 的 HW 系列函数
 *         (主循环路径带 HBI 互斥守卫,ISR 路径由 ethercat_sync.cpp 包装器保证互斥)。
 *       - initOnly 系列:INIT-ONLY,仅允许在 EthercatSync::init() 使能 EXTI NVIC 之前调用
 *         (如 EthercatSlave::init 的芯片 ID/AL 状态探针)。
 */
#ifndef COMM_ESC_LAN9252_H
#define COMM_ESC_LAN9252_H

#include <cstdint>
#include <cstddef>

/**
 * @brief LAN9252 ESC 驱动。
 * @note 封装 ESC 寄存器读写与 PDI(Process Data Interface)内存块访问。
 */
class EscLan9252 {
public:
    /** @brief 初始化 EXMC 总线与 ESC 基本寄存器。
     *  @note 1.5.25 起内部先执行一次 hardwareReset() 受控复位(s_resetDone 门控,
     *        重复调用不会二次复位 SSC 已配置好的芯片),再探活 EXMC/HBI。
     *  @return bool true 表示 EXMC 总线探活通过(可继续读取芯片 ID)。 */
    static bool init();

    /** @brief INIT-ONLY:ECAT_NRST(PB10)受控复位序列(拉低 CONFIG_ESC_NRST_ASSERT_MS 后释放)。
     *  @note 满足 LAN9252 手册 18.6.3 tpurstd≥25ms/trstia≥200µs;RST# 释放瞬间
     *        重锁 CHIP_MODE strap。运行期调用会打断 EtherCAT 通信,仅供 init/诊断用。 */
    static void hardwareReset();

    /** @brief 诊断:手动控制/回读 ECAT_NRST(PB10)实际电平(SPI 0xA2 action 20+ 转发到此)。
     *  @param action 0=恢复自动态(推挽输出高) 1=持续拉低 2=持续拉高 3=浮空输入(交给 R44) 4=只读回
     *  @return 实际引脚电平 0/1(GD32 输入通路常连引脚,输出态亦读真实电压);0xEE=无效 action。
     *  判读:action 1→2 切换后引脚电平不变 => 网络被外部短路或驱动器损伤;
     *  驱动高读回低 => ECAT_NRST 被按死在复位,LAS9252 永在复位态。 */
    static uint8_t nrstDrive(uint8_t action);

    /**
     * @brief 读取 ESC 芯片 ID(INIT-ONLY,供 init 打印诊断用)。
     * @return uint32_t 32-bit 芯片 ID(期望值 0x87654321)。
     */
    static uint32_t readChipId();

    /** @brief INIT-ONLY:仅允许在 EthercatSync::init() 使能 EXTI NVIC 之前调用;运行期禁止调用,需 ESC 寄存器访问须通过 SSC 移植层(HW_*)。 */
    static uint16_t initOnlyReadReg(uint16_t addr);

    /** @brief INIT-ONLY:仅允许在 EthercatSync::init() 使能 EXTI NVIC 之前调用;运行期禁止调用。 */
    static void initOnlyWriteReg(uint16_t addr, uint16_t v);

    /** @brief EXMC 总线 + HBI_IDX_0 探针 + BYTE_TEST 全部通过(init 成功)后为 true。
     *  @note  与 init() 返回值一致,可作运行期查询。 */
    static bool isBusReady() { return s_busReady; }

private:
    static bool s_busReady;  /**< init 完整成功(EXMC+IDX 探针+BYTE_TEST)后置位。 */
    static bool s_resetDone; /**< hardwareReset 已执行门控(防二次复位清掉 SSC 配置)。 */
};

#endif /* COMM_ESC_LAN9252_H */