/**
 * @file esc_exmc_bus.h
 * @brief LAN9252 ESC 的 EXMC 16-bit 并行总线抽象接口。
 * @note 通过 EXMC NOR/SRAM Region0(NE0,基址 0x60000000)以内存映射方式访问 LAN9252。
 *       16-bit 数据总线 + A16/A17 地址线 + NOE/NWE/NE0 控制线。
 *       (LQFP100 只有 NE0=PD7 一个片选引脚，故用 Region0/SNCTL0)
 */
#ifndef COMM_ESC_EXMC_BUS_H
#define COMM_ESC_EXMC_BUS_H

#include <cstdint>
#include <cstddef>

/**
 * @brief LAN9252 ESC 的 EXMC 并行总线驱动。
 * @note 提供 16-bit 读写与块读写接口,内部通过内存映射地址直接访问 ESC 寄存器空间。
 */
class EscExmcBus {
public:
    /** @brief 初始化 EXMC NOR/SRAM Region0 与全部 GPIO(AF 复用)。
     *  @return bool true 表示 EXMC Region0 已成功使能且首次回读探活通过。 */
    static bool init();

    /** @brief ISR-only:仅供 preempt=0 调用,无锁。 */
    static uint16_t read16(uint32_t offset);

    /** @brief ISR-only:仅供 preempt=0 调用,无锁。 */
    static void write16(uint32_t offset, uint16_t data);

    /** @brief init 后查询:EXMC Region0 是否使能且探活通过(供上层诊断汇总)。 */
    static bool isOk() { return s_ok; }

    /** @brief HBI 事务互斥入口:屏蔽 EXTI0(SYNC0,preempt=0)+ EXTI1(ESC IRQ,preempt=1)。
     *  @note  HBI Indexed 是两步事务(先写 IDX 再读写 DATA),不可被其他 HBI 用户打断,
     *         而 SYNC0 优先级 0 无法用 BASEPRI 屏蔽,只能关 NVIC。返回先前使能状态,
     *         配合 maskExit() 使用;保存/恢复语义不会破坏外层(如 SSC DISABLE_ESC_INT)的屏蔽。
     *         仅供主循环上下文的 HBI 访问使用(HW_* 非 Isr 版本)。 */
    static uint32_t maskEnter();

    /** @brief HBI 事务互斥出口:按 maskEnter() 返回的状态恢复 NVIC 使能。 */
    static void maskExit(uint32_t prev);

    /** @brief 硬件诊断:bit-bang 探活 + 位级回显分析(精简版)。
     *  @note  EtherCAT 同步 ISR 激活期间自动跳过(诊断会把 EXMC 引脚切成 GPIO)。 */
    static void diagDump();

    /** @brief 通断测试:逐个 pattern 驱动(不延时,保持到下次调用)。
     *  @param action 0=stop(恢复AF_PP), 1=0xFFFF, 2=0x0000, 3=0xAAAA, 4=0x5555,
     *                5=CS低, 6=RD低, 7=WR低, 8=A1高, 9=A2高,
     *                10=读保持(CS#+RD#持续低+数据线Hi-Z,万用表在芯片侧量读周期电平)
     *  @return 0=OK, 0xEE=无效 action */
    static uint8_t continuityDrive(uint8_t action);

private:
    static bool s_ok;  /**< EXMC Region0 使能 + 探活结果(init 后置位)。 */
};

#endif /* COMM_ESC_EXMC_BUS_H */