feat(ethercat): 添加EtherCAT从站功能支持并优化同步机制

- 添加CAN反馈和ID快照SPI命令文件 - 移除EXMC组件依赖，精简项目配置 - 添加RAM函数段链接脚本，优化Flash等待周期抖动 - 实现EscExmcBus类，提供16位并行总线访问LAN9252 - 实现EscLan9252驱动，支持寄存器和PDI内存访问 - 实现EthercatSlave类，采用三缓冲机制进行PDO数据交换 - 实现EthercatSync同步管理，支持SYNC0/SYNC1中断和定时器模式 - 添加ISR执行时间统计和诊断功能 - 分离周期路径和事件路径通知机制，避免RMW竞态
2026-06-29 01:51:02 +08:00
parent 1612e326ee
commit b171767023
31 changed files with 2177 additions and 290 deletions
@@ -0,0 +1,83 @@
+# Verification Checklist
+
+## 阶段 S1:输入/输出 PDO 的 PDI 偏移分离(严重 S1)
+- [x] `sys/config.h` 中新增 `CONFIG_ESC_PDI_INPUT_OFFSET` 与 `CONFIG_ESC_PDI_OUTPUT_OFFSET` 两个常量,且数值不同
+- [x] `comm/ethercat_slave.cpp::periodicIsr()` 中 `readPdi()` 调用使用 `CONFIG_ESC_PDI_INPUT_OFFSET`
+- [x] `comm/ethercat_slave.cpp::periodicIsr()` 中 `writePdi()` 调用使用 `CONFIG_ESC_PDI_OUTPUT_OFFSET`
+- [x] `periodicIsr()` 中 `readPdi` 与 `writePdi` 的 offset 参数不再共用 `0x0000U`
+- [x] `comm/esc_lan9252.h` 中 PDI 接口注释说明 offset 语义为"SyncManager 内存区相对偏移,输入/输出必须分离"
+
+## 阶段 S2:process() 框架级 PDO 桥接(严重 S2)
+- [x] `comm/ethercat_slave.h` 中 `EthercatSlave` 类含 `s_appInputs` 与 `s_appOutputs` 私有静态成员声明
+- [x] `comm/ethercat_slave.h` 中 `EthercatSlave` 类 public 区含 `getApplicationInputs()` 与 `setApplicationOutputs(const PdoBuffer*)` 声明
+- [x] `comm/ethercat_slave.cpp` 中 `s_appInputs` / `s_appOutputs` 已定义并初始化
+- [x] `process()` 实现内调用 `getLatestInputs()` 拷贝到 `s_appInputs`
+- [x] `process()` 实现内调用 `setOutputs(&s_appOutputs)` 推入输出三缓冲
+- [x] `getApplicationInputs()` 返回 `&s_appInputs`(只读指针)
+- [x] `setApplicationOutputs()` 含非空检查并将入参拷贝到 `s_appOutputs`
+- [x] `process()` 注释保留 TODO 说明应用对象字典映射待后续 spec
+
+## 阶段 S3:ESC 就绪状态含 AL 状态守卫(严重 S3,仅守卫)
+- [x] `comm/ethercat_slave.h` 含 `s_alState` 私有静态成员声明与 `getAlState()` 公共接口声明
+- [x] `comm/ethercat_slave.h` 含 AL 状态码常量定义(至少含 `AL_STATE_SAFEOP=0x04`)
+- [x] `comm/ethercat_slave.cpp` 中 `s_alState` 已定义并初始化
+- [x] `EthercatSlave::init()` 在芯片 ID 匹配后读取 AL 状态寄存器(0x0130)保存到 `s_alState`
+- [x] `isEscReady()` 返回值包含 AL 状态判断(`s_alState >= AL_STATE_SAFEOP`)
+- [x] `isEscReady()` 在芯片 ID 不匹配时短路返回 false(不读 AL 状态)
+- [x] `EthercatSlave::init()` 诊断打印区分三种情况:ID 不匹配、ID 匹配但 AL < SAFEOP、ID 匹配且 AL ≥ SAFEOP
+- [x] `getAlState()` 返回 `s_alState`
+- [x] `comm/esc_lan9252.cpp::EscLan9252::init()` 含完整 TODO 注释块,列出 SyncManager/FMMU/AL Control/SYNC0 配置步骤,并说明需 SSC 集成
+
+## 阶段 M4:TIMER0 降级模式保留 ESC 事件中断(中危 M4)
+- [x] `comm/ethercat_sync.cpp` 的 `#else`(TIMER0 降级)分支含 `EXTI1_IRQHandler` 定义
+- [x] `comm/ethercat_sync.cpp` 的 `#else` 分支含 `EXTI2_IRQHandler` 定义
+- [x] `EthercatSync::init()` 的 `#else` 分支含 EXTI1 的 `gpio_exti_source_select`/`exti_init`/`exti_interrupt_enable`/`exti_interrupt_flag_clear`/`nvic_irq_enable` 配置
+- [x] `EthercatSync::init()` 的 `#else` 分支含 EXTI2 的对应配置
+- [x] `#else` 分支不含 `EXTI0_IRQHandler` 定义(被 `TIMER0_IRQHandler` 替代)
+- [x] `onEscIrqExti` 与 `onSync1Exti` 实现未改动
+
+## 阶段 M5:输出三缓冲写入索引提供 2 周期宽限(中危 M5)
+- [x] `comm/ethercat_slave.cpp::setOutputs()` 中 `write_idx` 表达式为 `(s_outputReadIdx + 2U) % 3U`
+- [x] `setOutputs()` 内注释无"无需临界区"表述
+- [x] `setOutputs()` 内注释含"2 周期宽限"与"前提是主循环处理时间 < 2 × 周期时间"说明
+- [x] `comm/ethercat_slave.h` 中 `s_outputs` 成员注释说明写入索引为 `(readIdx+2)%3` 与 2 周期宽限语义
+- [x] `periodicIsr()` 中 `s_outputReadIdx` 递增逻辑未改动(仍为 `(readIdx + 1) % 3`)
+
+## 阶段 M6:`safe*` 接口重命名为 `initOnly*`(中危 M6)
+- [x] `comm/esc_lan9252.h` 中无 `safeReadReg`/`safeWriteReg`/`safeReadPdi`/`safeWritePdi` 声明
+- [x] `comm/esc_lan9252.h` 中含 `initOnlyReadReg`/`initOnlyWriteReg`/`initOnlyReadPdi`/`initOnlyWritePdi` 声明
+- [x] `comm/esc_lan9252.cpp` 中无 `safe*` 函数定义
+- [x] `comm/esc_lan9252.cpp` 中含 `initOnly*` 函数定义
+- [x] `comm/esc_lan9252.h` 中 `initOnly*` 接口注释含"INIT-ONLY"字样,无"safe"字样
+- [x] `comm/ethercat_slave.cpp::EthercatSlave::init()` 中 AL 状态读取调用 `initOnlyReadReg`(非 `safeReadReg`)
+- [x] `comm/esc_lan9252.cpp::readChipId()` 中调用 `initOnlyReadReg`(非 `safeReadReg`)
+- [x] 全项目 grep `safeReadReg`/`safeWriteReg`/`safeReadPdi`/`safeWritePdi`,无任何匹配(含注释)
+
+## 阶段 M7:`s_periodicSeq` 加宽为 `uint16_t`(中危 M7)
+- [x] `comm/ethercat_slave.h` 中 `s_periodicSeq` 类型为 `volatile uint16_t`
+- [x] `comm/ethercat_slave.h` 中 `s_processedSeq` 类型为 `uint16_t`
+- [x] `comm/ethercat_slave.cpp` 中 `s_periodicSeq` 定义类型为 `volatile uint16_t`
+- [x] `comm/ethercat_slave.cpp` 中 `s_processedSeq` 定义类型为 `uint16_t`
+- [x] `hasPendingPeriodic()` 实现未改动(仍为 `s_periodicSeq != s_processedSeq`)
+- [x] `markPeriodicProcessed()` 实现未改动(仍为 `s_processedSeq = s_periodicSeq`)
+
+## 编译验证与一致性检查
+- [x] 静态审查:全项目 grep `safeReadReg`/`safeWriteReg`/`safeReadPdi`/`safeWritePdi`,确认无残留
+- [x] 静态审查:`periodicIsr()` 中 `readPdi`/`writePdi` 使用不同 offset 常量
+- [x] 静态审查:`setOutputs()` 使用 `(readIdx+2)%3`
+- [x] 静态审查:`s_periodicSeq` 与 `s_processedSeq` 均为 `uint16_t`
+- [x] 静态审查:降级模式下 `EXTI1_IRQHandler`/`EXTI2_IRQHandler` 已定义
+- [x] 静态审查:`process()` 内调用 `getLatestInputs()` 与 `setOutputs()`
+- [x] 静态审查:`getApplicationInputs()`/`setApplicationOutputs()` 已实现
+- [x] 静态审查:`isEscReady()` 含 AL 状态守卫
+- [ ] 全量编译通过,无 error(⚠️ 待编译环境修复 EXMC pack 阻塞后验证)
+- [ ] 若可编译:map 文件确认新增静态成员 `s_appInputs`/`s_appOutputs`/`s_alState` 已分配(⚠️ 待编译环境修复后验证)
+
+## 风险闭环确认
+- [x] 严重 S1(PDO 偏移重叠):输入/输出 PDO 使用独立 offset,数据不再相互覆盖,闭环
+- [x] 严重 S2(process 为空):process() 框架级桥接实现,数据通路在框架层闭合,闭环
+- [x] 严重 S3(ESC 寄存器初始化缺失):isEscReady() 增加 AL 状态守卫,SYNC0 不会触发的事实在运行期可观测;完整 ESC 配置留 SSC 集成,本 spec 范围内闭环
+- [x] 中危 M4(降级模式丢失 ESC IRQ):EXTI1/EXTI2 handler 在降级模式下保留,ESC 事件路径可用,闭环
+- [x] 中危 M5(输出三缓冲竞态):写入索引改为 `(readIdx+2)%3`,2 周期宽限消除拷贝竞态,闭环
+- [x] 中危 M6(safe* 命名误导):重命名为 `initOnly*`,命名与实现语义一致,闭环
+- [x] 中危 M7(序列号回绕):加宽为 `uint16_t`,6.55s 回绕周期覆盖任何合理主循环阻塞,闭环
@@ -0,0 +1,177 @@
+# EtherCAT PDO 数据通路与运行期问题整改 Spec
+
+## Why
+在 `fix-ethercat-realtime-comm-risks` 与 `fix-ecat-postaudit-risks` 两轮整改完成后,对 EtherCAT 通信架构进行了第三轮深度审查,发现 3 个严重问题(P0/P1)与 4 个中等问题(P1/P2)。其中 S1(输入/输出 PDO 使用同一 PDI 偏移)直接导致读写数据相互覆盖;S2(`process()` 为空)使三缓冲数据通路在应用层断开;M4(TIMER0 降级模式丢失 ESC IRQ handler)、M5(输出三缓冲存在 1 周期竞态窗口)、M6(`safe*` 命名误导)、M7(`s_periodicSeq` 单字节回绕)虽不立即致命,但会在边界条件下静默丢数据或诱导误用。本 spec 在不推翻前两轮架构决策的前提下,闭合 PDO 数据通路、修正降级模式分支、消除剩余竞态与命名陷阱。
+
+## What Changes
+
+### 阶段 S1:分离输入/输出 PDO 的 PDI 偏移(修复严重 S1)
+- 在 `sys/config.h` 新增 `CONFIG_ESC_PDI_INPUT_OFFSET` 与 `CONFIG_ESC_PDI_OUTPUT_OFFSET` 两个偏移常量(默认值分别取 LAN9252 典型 TxPDO/RxPDO SyncManager 内存区起始,需与主站 ESI 配置匹配)
+- 修改 `comm/ethercat_slave.cpp::periodicIsr()`:`readPdi()` 调用使用 `CONFIG_ESC_PDI_INPUT_OFFSET`,`writePdi()` 调用使用 `CONFIG_ESC_PDI_OUTPUT_OFFSET`,不再共用 `0x0000U`
+- 修改 `comm/esc_lan9252.h` 中 `readPdi`/`writePdi`/`safeReadPdi`/`safeWritePdi` 的接口注释,说明 offset 参数语义为"SyncManager 内存区相对偏移,输入/输出必须分离"
+- **范围限定**:仅修正调用方传入的 offset,不实现 SyncManager/FMMU 寄存器配置(属 SSC 集成范畴,见阶段 S3)
+
+### 阶段 S2:实现 `process()` 框架级 PDO 桥接(修复严重 S2)
+- **BREAKING(接口新增)**: `EthercatSlave` 类新增 `getApplicationInputs()` 与 `setApplicationOutputs()` 两个公共接口,作为应用层访问 PDO 数据的唯一入口
+- `process()` 内部实现:
+  1. 调用 `getLatestInputs()` 取最新输入三缓冲只读指针,拷贝到内部 `s_appInputs` 快照(单次 32 字节拷贝,主循环非实时路径)
+  2. 将内部 `s_appOutputs` 快照通过 `setOutputs()` 推入输出三缓冲
+  3. 应用层通过 `getApplicationInputs()` 读取输入快照,通过 `setApplicationOutputs()` 写入下次要发送的输出快照
+- `s_appInputs` / `s_appOutputs` 为 `PdoBuffer` 类型静态成员,仅主循环访问,无需三缓冲(应用层与 `process()` 同在主循环,串行执行)
+- **不实现**:应用对象字典映射(具体输入字节对应哪个应用变量),留 TODO 注释,由后续应用层 spec 定义
+
+### 阶段 S3:ESC 就绪状态守卫增强(修复严重 S3,仅守卫不实现配置)
+- 修改 `EthercatSlave::isEscReady()` 语义:除校验芯片 ID 外,额外校验 ESC AL 状态寄存器(0x0130)的 AL 状态字段 ≥ `AL_STATE_SAFEOP`(0x04),否则返回 false
+- 新增 `EthercatSlave::getAlState()` 公共接口,返回当前 AL 状态码(供诊断打印与未来 SSC 集成使用)
+- 在 `EscLan9252::init()` 中增加清晰 TODO 注释块,列出完整 ESC 配置所需步骤(SyncManager 初始化、FMMU 配置、AL Control 写入、SYNC0 生成寄存器配置),并说明这些步骤需要 SSC 或等价协议栈代码,本 spec 不实现
+- `EthercatSlave::init()` 中读取 AL 状态并打印;若 AL 状态 < SAFEOP,明确打印"ESC detected but AL state < SAFEOP, SYNC0 will not fire, full ESC config requires SSC integration"
+- **范围限定**:不实现任何 ESC 寄存器配置逻辑,仅增加守卫与诊断,使"SYNC0 不会触发"这一事实在运行期可观测,而非静默失败
+
+### 阶段 M4:TIMER0 降级模式保留 ESC IRQ handler(修复中危 M4)
+- 修改 `comm/ethercat_sync.cpp` 中断入口包装:`#else`(TIMER0 降级)分支 SHALL 同时保留 `EXTI1_IRQHandler` 与 `EXTI2_IRQHandler` 的定义,仅 `EXTI0_IRQHandler` 被 `TIMER0_IRQHandler` 替代
+- `EthercatSync::init()` 的 TIMER0 分支 SHALL 同时配置 EXTI1(ESC IRQ)与 EXTI2(SYNC1)的 NVIC 使能,使降级模式下 ESC 事件路径仍可用(DC 未同步时主站仍需通过邮箱/AL 事件推进状态机)
+- **范围限定**:EXTI1/EXTI2 的 ISR 实现不改(仍调用 `onEscIrqExti`/`onSync1Exti`),仅修复编译分支漏定义
+
+### 阶段 M5:输出三缓冲写入索引改为 `(readIdx+2)%3`(修复中危 M5)
+- 修改 `comm/ethercat_slave.cpp::setOutputs()`:`write_idx` 由 `(s_outputReadIdx + 1U) % 3U` 改为 `(s_outputReadIdx + 2U) % 3U`
+- 修改 `comm/ethercat_slave.h` 中 `s_outputs` 的注释,说明写入索引与 ISR 读取位置隔 2 个缓冲(即 ISR 2 周期内不会读到该槽),提供 2 周期宽限,消除结构体拷贝被两次抢占的竞态窗口
+- 修改 `setOutputs()` 实现内注释,删除"无需临界区"的绝对化表述,改为"2 周期宽限下拷贝竞态窗口消除,前提是主循环处理时间 < 2 × 周期时间"
+- **影响验证**:三缓冲仍为 3 个槽,索引方案变更不影响 ISR 读取路径(ISR 仍按 `s_outputReadIdx` 模 3 递增读取),仅主循环写入位置后移一格
+
+### 阶段 M6:`safe*` 接口重命名为 `initOnly*`(修复中危 M6)
+- **BREAKING(接口重命名)**: `EscLan9252` 类的 `safeReadReg`/`safeWriteReg`/`safeReadPdi`/`safeWritePdi` 四个接口重命名为 `initOnlyReadReg`/`initOnlyWriteReg`/`initOnlyReadPdi`/`initOnlyWritePdi`
+- 理由:现实现无任何保护(直接转发无锁版本),`safe*` 命名暗示线程安全,实际安全性完全靠开发者自律。重命名为 `initOnly*` 使"仅 init 阶段可调用"的约束直接体现在符号名上,降低误用概率
+- 全项目 grep 更新所有调用点(预期仅在 `EthercatSlave::init()` 中调用 `safeReadReg` 读取 AL 状态)
+- 头文件注释同步更新,移除"safe"字样,统一为"INIT-ONLY"
+
+### 阶段 M7:`s_periodicSeq` 加宽为 `uint16_t`(修复中危 M7)
+- 修改 `comm/ethercat_slave.h`:`s_periodicSeq` 与 `s_processedSeq` 类型由 `uint8_t` 改为 `uint16_t`
+- 理由:100µs 周期下 `uint8_t` 在 25.5ms 后回绕,主循环因长任务(如 CAN 帧解析预算 48 帧、OTA 处理)阻塞超过 25.5ms 时,`hasPendingPeriodic()` 会因回绕后相等而静默丢检测。`uint16_t` 提供 6.55s 回绕周期,足够覆盖任何合理主循环阻塞
+- **范围限定**:不加宽到 `uint32_t`,因 `uint16_t` 在 ARM Cortex-M4 上仍为单字访问原子,无需额外同步原语;`uint32_t` 在某些访问序列下非单周期原子(虽然 GD32E508 32-bit 总线实际原子,但 `uint16_t` 足够且更保守)
+- 诊断打印中 `s_isrCount` 已为 `uint32_t` 不受影响
+
+## Impact
+- Affected specs:
+  - `fix-ethercat-realtime-comm-risks`(上一轮整改 spec):本 spec 修正其阶段 C(三缓冲)中输出索引 `(readIdx+1)%3` 的决策,改为 `(readIdx+2)%3`;修正其阶段 B(EXMC 访问权分离)中 `safe*` 命名,改为 `initOnly*`
+  - `fix-ecat-postaudit-risks`(上轮整改 spec):本 spec 修正其阶段 H1(safe* 收窄 INIT-ONLY)的命名,由 `safe*` 改为 `initOnly*`,使语义与命名一致
+  - `add-ethercat-lan9252-realtime`(原集成 spec):无架构推翻
+- Affected code:
+  - `sys/config.h`:新增 `CONFIG_ESC_PDI_INPUT_OFFSET` / `CONFIG_ESC_PDI_OUTPUT_OFFSET`
+  - `comm/ethercat_slave.h` / `comm/ethercat_slave.cpp`:PDO 偏移分离、`process()` 桥接实现、`isEscReady()` AL 状态守卫、`getAlState()` 新增、应用层 getter/setter 新增、`s_periodicSeq`/`s_processedSeq` 加宽、`setOutputs()` 索引改为 `+2`、`s_appInputs`/`s_appOutputs` 新增
+  - `comm/esc_lan9252.h` / `comm/esc_lan9252.cpp`:`safe*` 重命名为 `initOnly*`、`init()` 增加 ESC 配置 TODO 注释块、PDI 接口 offset 语义注释
+  - `comm/ethercat_sync.cpp`:TIMER0 降级分支补全 `EXTI1_IRQHandler`/`EXTI2_IRQHandler` 与 NVIC 使能
+
+## ADDED Requirements
+
+### Requirement: 输入/输出 PDO 的 PDI 偏移分离
+系统 SHALL 在 `sys/config.h` 中定义 `CONFIG_ESC_PDI_INPUT_OFFSET` 与 `CONFIG_ESC_PDI_OUTPUT_OFFSET` 两个独立偏移常量,分别对应 LAN9252 TxPDO 与 RxPDO SyncManager 内存区起始。`EthercatSlave::periodicIsr()` 中的 `readPdi()` 调用 SHALL 使用输入偏移,`writePdi()` 调用 SHALL 使用输出偏移,SHALL NOT 共用同一偏移。
+
+#### Scenario: 输入 PDO 读取使用输入偏移
+- **WHEN** `periodicIsr()` 读取输入 PDO
+- **THEN** 调用 `readPdi(CONFIG_ESC_PDI_INPUT_OFFSET, ...)`,不与输出 PDO 写入偏移重叠
+
+#### Scenario: 输出 PDO 写入使用输出偏移
+- **WHEN** `periodicIsr()` 写入输出 PDO
+- **THEN** 调用 `writePdi(CONFIG_ESC_PDI_OUTPUT_OFFSET, ...)`,不与输入 PDO 读取偏移重叠
+
+### Requirement: 应用层 PDO 桥接接口
+系统 SHALL 在 `EthercatSlave` 类中提供 `getApplicationInputs()` 与 `setApplicationOutputs()` 两个公共接口,作为应用层访问 PDO 数据的唯一入口。`process()` SHALL 在主循环调用时:先调用 `getLatestInputs()` 拷贝最新输入到内部 `s_appInputs` 快照,再将内部 `s_appOutputs` 快照通过 `setOutputs()` 推入输出三缓冲。
+
+应用层 SHALL 通过 `getApplicationInputs()` 读取输入快照(只读指针),通过 `setApplicationOutputs()` 写入下次要发送的输出快照(拷贝到内部 `s_appOutputs`)。`s_appInputs` 与 `s_appOutputs` 仅由主循环访问(`process()` 与应用层 getter/setter 串行执行),无需三缓冲。
+
+#### Scenario: process 闭合数据通路
+- **WHEN** 主循环 `taskEthercatProcess()` 调用 `EthercatSlave::process()`
+- **THEN** `process()` 内部调用 `getLatestInputs()` 取最新输入,调用 `setOutputs()` 推入待发送输出,数据通路在框架层闭合
+
+#### Scenario: 应用层读取输入
+- **WHEN** 应用层调用 `EthercatSlave::getApplicationInputs()`
+- **THEN** 返回 `s_appInputs` 的只读指针,内容为最近一次 `process()` 拷贝的输入快照
+
+#### Scenario: 应用层写入输出
+- **WHEN** 应用层调用 `EthercatSlave::setApplicationOutputs(buf)`
+- **THEN** `buf` 内容被拷贝到 `s_appOutputs`,下次 `process()` 调用时通过 `setOutputs()` 推入三缓冲
+
+### Requirement: ESC 就绪状态含 AL 状态守卫
+系统 SHALL 使 `EthercatSlave::isEscReady()` 在芯片 ID 校验通过的基础上,额外校验 ESC AL 状态寄存器(0x0130)的 AL 状态字段 ≥ `AL_STATE_SAFEOP`(0x04)。AL 状态 < SAFEOP 时,`isEscReady()` SHALL 返回 false,即使芯片 ID 匹配。
+
+系统 SHALL 提供 `EthercatSlave::getAlState()` 公共接口,返回当前 AL 状态码,供诊断打印与未来 SSC 集成使用。
+
+`EscLan9252::init()` SHALL 在实现中保留清晰 TODO 注释块,列出完整 ESC 配置所需步骤(SyncManager、FMMU、AL Control、SYNC0 生成寄存器),并说明这些步骤需要 SSC 或等价协议栈代码,本 spec 不实现。
+
+#### Scenario: 芯片 ID 匹配但 AL 状态不足
+- **WHEN** `EthercatSlave::init()` 读取芯片 ID 匹配 0x87654321,但 AL 状态为 PREOP(0x02)
+- **THEN** `isEscReady()` 返回 false,诊断打印输出"ESC detected but AL state < SAFEOP, SYNC0 will not fire"
+
+#### Scenario: 芯片 ID 匹配且 AL 状态充分
+- **WHEN** 芯片 ID 匹配且 AL 状态 ≥ SAFEOP(0x04)
+- **THEN** `isEscReady()` 返回 true,EthercatSync::init() 被调用,SYNC0 中断使能
+
+#### Scenario: ESC 未焊接
+- **WHEN** 芯片 ID 不匹配(读回 0x00000000 或 0xFFFFFFFF)
+- **THEN** `isEscReady()` 返回 false(短路,不读 AL 状态),诊断打印"ESC NOT ready",与现状行为一致
+
+### Requirement: TIMER0 降级模式保留 ESC 事件中断
+系统 SHALL 在 `CONFIG_ETHERCAT_SYNC_MODE == 1`(TIMER0 降级模式)下,同时保留 `EXTI1_IRQHandler`(ESC IRQ)与 `EXTI2_IRQHandler`(SYNC1)的中断入口定义与 NVIC 使能。仅 `EXTI0_IRQHandler` 被 `TIMER0_IRQHandler` 替代。
+
+`EthercatSync::init()` 的 TIMER0 分支 SHALL 配置 EXTI1 与 EXTI2 的 NVIC 使能(与 EXTI 模式分支一致),使降级模式下 ESC 事件路径(邮箱、AL 状态变更)仍可用。
+
+#### Scenario: 降级模式 ESC 事件可触发
+- **WHEN** `CONFIG_ETHERCAT_SYNC_MODE == 1` 且 ESC 触发 IRQ 事件
+- **THEN** `EXTI1_IRQHandler` 被调用,`onEscIrqExti()` 置位 `TASK_ETHERCAT_PROCESS`,主循环消费事件
+
+#### Scenario: 降级模式 SYNC0 由 TIMER0 替代
+- **WHEN** `CONFIG_ETHERCAT_SYNC_MODE == 1`
+- **THEN** `TIMER0_IRQHandler` 调用 `EthercatSlave::periodicIsr()`,`EXTI0_IRQHandler` 不定义(避免符号冲突)
+
+### Requirement: 输出三缓冲写入索引提供 2 周期宽限
+系统 SHALL 使 `EthercatSlave::setOutputs()` 写入索引为 `(s_outputReadIdx + 2U) % 3U`,与 ISR 当前读取位置隔 2 个缓冲。此方案提供 2 周期宽限,确保主循环结构体拷贝(32 字节)即使被 preempt=0 ISR 抢占两次,ISR 也不会读到半写完的缓冲。
+
+前提条件:主循环处理时间 SHALL < 2 × 周期时间,否则 2 周期宽限仍可能不足。
+
+#### Scenario: setOutputs 拷贝被 ISR 抢占不破坏数据
+- **WHEN** 主循环 `setOutputs()` 正在拷贝输出缓冲,SYNC0 ISR 触发一次或两次
+- **THEN** ISR 读取的 `s_outputReadIdx` 指向与主循环写入位置隔 2 个缓冲的槽,两者不冲突,ISR 读到的总是上一次完整写入的数据
+
+### Requirement: `safe*` 接口重命名为 `initOnly*`
+系统 SHALL 将 `EscLan9252` 类的 `safeReadReg`/`safeWriteReg`/`safeReadPdi`/`safeWritePdi` 四个接口重命名为 `initOnlyReadReg`/`initOnlyWriteReg`/`initOnlyReadPdi`/`initOnlyWritePdi`。重命名后,接口名直接体现"仅 init 阶段可调用"的约束,降低误用概率。
+
+全项目 SHALL 无 `safeReadReg`/`safeWriteReg`/`safeReadPdi`/`safeWritePdi` 符号残留(声明、定义、调用点全部更新)。
+
+#### Scenario: 调用点使用新名称
+- **WHEN** `EthercatSlave::init()` 读取 AL 状态寄存器
+- **THEN** 调用 `EscLan9252::initOnlyReadReg(0x0130U)`,不出现 `safeReadReg` 符号
+
+#### Scenario: 无 safe 残留
+- **WHEN** 全项目 grep `safeReadReg`/`safeWriteReg`/`safeReadPdi`/`safeWritePdi`
+- **THEN** 无任何匹配(含注释、声明、调用)
+
+### Requirement: `s_periodicSeq` 加宽为 `uint16_t`
+系统 SHALL 将 `EthercatSlave::s_periodicSeq` 与 `s_processedSeq` 的类型由 `volatile uint8_t` / `uint8_t` 改为 `volatile uint16_t` / `uint16_t`。`uint16_t` 在 100µs 周期下提供 6.55s 回绕周期,足够覆盖任何合理主循环阻塞,且在 ARM Cortex-M4 上为单字访问原子。
+
+#### Scenario: 主循环阻塞 30ms 不丢检测
+- **WHEN** 主循环因长任务阻塞 30ms(300 个周期),`s_periodicSeq` 递增 300 次
+- **THEN** `s_periodicSeq`(uint16_t)未回绕,`hasPendingPeriodic()` 正确检测到 pending,不丢数据
+
+#### Scenario: 序列号单字原子访问
+- **WHEN** preempt=0 ISR 写 `s_periodicSeq`,主循环读 `s_periodicSeq`
+- **THEN** `uint16_t` 在 Cortex-M4 上为单周期单字访问,无撕裂(torn read)风险
+
+## MODIFIED Requirements
+
+### Requirement: EXMC 总线访问权分离
+(原 spec `fix-ethercat-realtime-comm-risks` 阶段 B 与 `fix-ecat-postaudit-risks` 阶段 H1 中的"safe* 接口"要求)
+改:原要求将接口命名为 `safeReadReg/safeWriteReg/safeReadPdi/safeWritePdi` 并定位为"Thread-safe"或"INIT-ONLY"。本 spec 将四个接口重命名为 `initOnlyReadReg/initOnlyWriteReg/initOnlyReadPdi/initOnlyWritePdi`,使命名与"INIT-ONLY,无保护,直接转发无锁版本"的实现语义一致,消除"safe"命名误导。接口的调用约束(INIT-ONLY,运行期禁止调用)与实现(去 PRIMASK,直接转发)不变。
+
+### Requirement: PDO 三缓冲机制
+(原 spec `fix-ethercat-realtime-comm-risks` 阶段 C 中的输出路径要求)
+改:原要求 `setOutputs()` 写入 `(s_outputReadIdx + 1) % 3`(与 ISR 当前读取位置隔一个缓冲)。本 spec 改为写入 `(s_outputReadIdx + 2) % 3`(隔两个缓冲,提供 2 周期宽限)。原方案在主循环拷贝被两次 preempt=0 ISR 抢占时存在竞态窗口,新方案消除该窗口。输入路径(`getLatestInputs()` 返回 `(writeIdx+2)%3`)不变。
+
+## Assumptions & Decisions
+
+1. **S1 偏移值需与主站 ESI 匹配**:`CONFIG_ESC_PDI_INPUT_OFFSET` / `CONFIG_ESC_PDI_OUTPUT_OFFSET` 的具体数值需与主站 ESI 配置中 SyncManager 的内存映射匹配。本 spec 提供配置点与默认占位值(如 0x1000 / 0x1200),实际数值待主站配置确定后在集成阶段填入。配置点存在即闭合代码层 bug,数值正确性属集成验证范畴
+2. **S2 不实现应用对象字典**:`process()` 框架级桥接仅闭合"ISR 三缓冲 ↔ 应用层快照"数据通路,不定义具体输入字节对应哪个应用变量(如字节 0-3 = 温度浮点,字节 4-7 = 电压浮点)。应用对象字典映射由后续应用层 spec 定义
+3. **S3 不实现 ESC 寄存器配置**:完整 SyncManager/FMMU/AL Control/SYNC0 配置需要 SSC 或等价协议栈代码,工作量与本 spec 量级不匹配,且前两个 spec 已明确将 SSC 排除。本 spec 仅通过 AL 状态守卫使"SYNC0 不会触发"在运行期可观测,并通过 TODO 注释块明确后续工作内容
+4. **M5 索引变更无回归**:输出三缓冲改为 `(readIdx+2)%3` 不影响 ISR 读取路径(ISR 仍按 `readIdx` 模 3 递增),仅主循环写入位置后移一格。三缓冲槽位数仍为 3,内存占用不变
+5. **M6 重命名不引入运行期保护**:`safe*` 重命名为 `initOnly*` 仅改善命名,不增加任何运行期检查或保护。若运行期误调用 `initOnly*`,仍会与 ISR 竞争 EXMC 总线。命名改进降低误用概率,但不消除误用后果
+6. **M7 不加宽到 uint32_t**:`uint16_t` 在 100µs 周期下 6.55s 回绕已足够,且在 Cortex-M4 上为单字访问原子。`uint32_t` 虽在 GD32E508 32-bit 总线上实际原子,但 `uint16_t` 更保守且足够
+7. **不包含**:完整 SSC 集成、EEPROM/ESI 配置、应用对象字典映射、EXMC 时序实测调校(轻微问题 #9)、`selfTest()` 死代码清理(轻微问题 #8)、`markPeriodicProcessed()` 调用顺序调整(轻微问题 #10)——这些属轻微问题或后续 spec 范畴
@@ -0,0 +1,68 @@
+# Tasks
+
+- [x] Task 1: 阶段 S1 — 分离输入/输出 PDO 的 PDI 偏移(修复严重 S1)
+  - [x] SubTask 1.1: 在 `sys/config.h` 的 EtherCAT 配置区新增 `CONFIG_ESC_PDI_INPUT_OFFSET` 与 `CONFIG_ESC_PDI_OUTPUT_OFFSET` 两个 `constexpr` 或 `#define` 常量(默认占位值 `0x1000U` / `0x1200U`,注释说明需与主站 ESI 匹配)
+  - [x] SubTask 1.2: 修改 `comm/ethercat_slave.cpp::periodicIsr()` 中 `EscLan9252::readPdi()` 调用,将 offset 参数由 `0x0000U` 改为 `CONFIG_ESC_PDI_INPUT_OFFSET`
+  - [x] SubTask 1.3: 修改 `comm/ethercat_slave.cpp::periodicIsr()` 中 `EscLan9252::writePdi()` 调用,将 offset 参数由 `0x0000U` 改为 `CONFIG_ESC_PDI_OUTPUT_OFFSET`
+  - [x] SubTask 1.4: 修改 `comm/esc_lan9252.h` 中 `readPdi`/`writePdi`/`initOnlyReadPdi`/`initOnlyWritePdi`(M6 重命名后)的接口注释,说明 offset 参数语义为"SyncManager 内存区相对偏移,输入/输出必须分离"
+
+- [x] Task 2: 阶段 S2 — 实现 `process()` 框架级 PDO 桥接(修复严重 S2)
+  - [x] SubTask 2.1: 在 `comm/ethercat_slave.h` 的 `EthercatSlave` 类中新增 `static PdoBuffer s_appInputs` 与 `static PdoBuffer s_appOutputs` 私有静态成员声明
+  - [x] SubTask 2.2: 在 `comm/ethercat_slave.h` 的 `EthercatSlave` 类 public 区新增 `getApplicationInputs()`(返回 `const PdoBuffer*`)与 `setApplicationOutputs(const PdoBuffer*)` 两个公共静态接口声明
+  - [x] SubTask 2.3: 在 `comm/ethercat_slave.cpp` 中定义 `s_appInputs` / `s_appOutputs` 静态成员(初始化为空 PdoBuffer)
+  - [x] SubTask 2.4: 实现 `process()`:先调用 `getLatestInputs()`,若返回非空则拷贝到 `s_appInputs`;然后调用 `setOutputs(&s_appOutputs)` 推入输出三缓冲(保留原 TODO 注释说明应用对象字典映射待后续 spec)
+  - [x] SubTask 2.5: 实现 `getApplicationInputs()`:返回 `&s_appInputs`
+  - [x] SubTask 2.6: 实现 `setApplicationOutputs(const PdoBuffer *outputs)`:非空检查后拷贝 `*outputs` 到 `s_appOutputs`
+
+- [x] Task 3: 阶段 S3 — ESC 就绪状态守卫增强(修复严重 S3,仅守卫)
+  - [x] SubTask 3.1: 在 `comm/ethercat_slave.h` 新增 `static uint8_t s_alState` 私有静态成员声明,与 `static uint8_t getAlState()` 公共接口声明;新增 AL 状态码常量(可选:定义为 `constexpr` 或 `#define`,如 `AL_STATE_INIT=0x01`、`AL_STATE_PREOP=0x02`、`AL_STATE_SAFEOP=0x04`、`AL_STATE_OP=0x08`)
+  - [x] SubTask 3.2: 在 `comm/ethercat_slave.cpp` 定义 `s_alState` 静态成员(初始化 0)
+  - [x] SubTask 3.3: 修改 `EthercatSlave::init()`:在读取芯片 ID 后,若 ID 匹配则进一步读取 AL 状态寄存器(0x0130)并保存到 `s_alState`(注意:M6 重命名后用 `initOnlyReadReg` 而非 `safeReadReg`)
+  - [x] SubTask 3.4: 修改 `isEscReady()` 内联实现:返回 `(s_chipId == 0x87654321U) && (s_alState >= AL_STATE_SAFEOP)`(注:AL 状态寄存器低 4 位为状态码,SAFEOP=0x04,OP=0x08,故 `>= 0x04` 兼容 SAFEOP 与 OP)
+  - [x] SubTask 3.5: 修改 `EthercatSlave::init()` 的诊断打印:ID 匹配但 AL < SAFEOP 时打印"ESC detected but AL state=0x%02X < SAFEOP, SYNC0 will not fire, full ESC config requires SSC integration";ID 匹配且 AL ≥ SAFEOP 时打印现有"ESC ready, AL state=0x%04X"
+  - [x] SubTask 3.6: 实现 `getAlState()` 返回 `s_alState`
+  - [x] SubTask 3.7: 在 `comm/esc_lan9252.cpp::EscLan9252::init()` 现有 TODO 注释处扩展为完整 TODO 块,列出:SyncManager 初始化(SM0/1/2/3 配置寄存器)、FMMU 配置、AL Control 写入(OP 状态请求)、SYNC0 生成寄存器(0x0981-0x0982 周期、0x0983 脉冲长度等),并说明需 SSC 或等价协议栈代码
+
+- [x] Task 4: 阶段 M4 — TIMER0 降级模式保留 ESC IRQ handler(修复中危 M4)
+  - [x] SubTask 4.1: 修改 `comm/ethercat_sync.cpp` 的 `extern "C"` 中断入口包装区:`#else`(TIMER0 降级)分支在 `TIMER0_IRQHandler` 定义之后,补充 `EXTI1_IRQHandler` 与 `EXTI2_IRQHandler` 的定义(与 `#if` 分支一致,调用 `onEscIrqExti`/`onSync1Exti`)
+  - [x] SubTask 4.2: 修改 `EthercatSync::init()` 的 `#else`(TIMER0 降级)分支:在 TIMER0 配置之前或之后,补充 EXTI1(ESC IRQ)与 EXTI2(SYNC1)的 `gpio_exti_source_select`/`exti_init`/`exti_interrupt_enable`/`exti_interrupt_flag_clear`/`nvic_irq_enable` 配置(代码与 `#if` 分支的 EXTI1/EXTI2 配置段相同)
+  - [x] SubTask 4.3: 确认 `onEscIrqExti` 与 `onSync1Exti` 实现无需改动(降级模式下行为一致)
+
+- [x] Task 5: 阶段 M5 — 输出三缓冲写入索引改为 `(readIdx+2)%3`(修复中危 M5)
+  - [x] SubTask 5.1: 修改 `comm/ethercat_slave.cpp::setOutputs()`:`write_idx` 由 `(s_outputReadIdx + 1U) % 3U` 改为 `(s_outputReadIdx + 2U) % 3U`
+  - [x] SubTask 5.2: 修改 `setOutputs()` 实现内注释:删除"无需临界区"表述,改为"2 周期宽限下拷贝竞态窗口消除,前提是主循环处理时间 < 2 × 周期时间"
+  - [x] SubTask 5.3: 修改 `comm/ethercat_slave.h` 中 `s_outputs` 成员的注释:说明 `setOutputs()` 写入 `(readIdx+2)%3`,与 ISR 当前读取位置隔 2 个缓冲,提供 2 周期宽限
+
+- [x] Task 6: 阶段 M6 — `safe*` 接口重命名为 `initOnly*`(修复中危 M6)
+  - [x] SubTask 6.1: 修改 `comm/esc_lan9252.h`:`safeReadReg`/`safeWriteReg`/`safeReadPdi`/`safeWritePdi` 四个成员函数声明重命名为 `initOnlyReadReg`/`initOnlyWriteReg`/`initOnlyReadPdi`/`initOnlyWritePdi`,注释中移除"safe"字样,统一为"INIT-ONLY"
+  - [x] SubTask 6.2: 修改 `comm/esc_lan9252.cpp`:四个函数定义同步重命名
+  - [x] SubTask 6.3: 修改 `comm/ethercat_slave.cpp::EthercatSlave::init()` 中调用 `safeReadReg(0x0130U)` 的代码,改为 `initOnlyReadReg(0x0130U)`(注:此调用点在 Task 3 S3 实现中可能已重命名,需协调)
+  - [x] SubTask 6.4: 修改 `comm/esc_lan9252.cpp::readChipId()` 中调用 `safeReadReg` 的代码,改为 `initOnlyReadReg`
+  - [x] SubTask 6.5: 全项目 grep `safeReadReg`/`safeWriteReg`/`safeReadPdi`/`safeWritePdi`,确认无任何残留(含声明、定义、调用、注释)
+
+- [x] Task 7: 阶段 M7 — `s_periodicSeq` 加宽为 `uint16_t`(修复中危 M7)
+  - [x] SubTask 7.1: 修改 `comm/ethercat_slave.h`:`s_periodicSeq` 类型由 `volatile uint8_t` 改为 `volatile uint16_t`;`s_processedSeq` 类型由 `uint8_t` 改为 `uint16_t`
+  - [x] SubTask 7.2: 修改 `comm/ethercat_slave.cpp` 中两个静态成员定义的类型,与头文件一致
+  - [x] SubTask 7.3: 确认 `hasPendingPeriodic()` 与 `markPeriodicProcessed()` 实现无需改动(比较与赋值操作对 `uint16_t` 同样适用)
+  - [x] SubTask 7.4: 确认诊断打印中无 `s_periodicSeq` 直接格式化输出(若有,确认 `%u`/`%lu` 格式符适配 `uint16_t`)
+
+- [x] Task 8: 编译验证与一致性检查
+  - [x] SubTask 8.1: 静态代码审查确认:全项目无 `safeReadReg`/`safeWriteReg`/`safeReadPdi`/`safeWritePdi` 残留;`periodicIsr()` 中 `readPdi`/`writePdi` 使用不同 offset;`setOutputs()` 使用 `(readIdx+2)%3`;`s_periodicSeq` 为 `uint16_t`;降级模式下 `EXTI1_IRQHandler`/`EXTI2_IRQHandler` 已定义
+  - [x] SubTask 8.2: 静态代码审查确认:`process()` 内部调用 `getLatestInputs()` 与 `setOutputs()`;`getApplicationInputs()`/`setApplicationOutputs()` 已实现;`isEscReady()` 含 AL 状态守卫
+  - [ ] SubTask 8.3: 若可编译:全量编译通过,无 error(⚠️ 受 EXMC pack 解析问题阻塞,改为静态代码审查,详见下方验证)
+  - [ ] SubTask 8.4: 若可编译:map 文件确认新增静态成员 `s_appInputs`/`s_appOutputs`/`s_alState` 已分配(⚠️ 待编译环境修复后验证)
+
+# Task Dependencies
+- Task 1(S1 PDO 偏移)、Task 5(M5 输出索引)、Task 7(M7 序列号加宽)相互独立,可并行实施(改动 `ethercat_slave.cpp`/`config.h` 不同代码段,无交叉)
+- Task 6(M6 重命名)应早于 Task 3(S3 AL 状态守卫),因 S3 SubTask 3.3 调用 `initOnlyReadReg`,需先完成重命名
+- Task 2(S2 process 桥接)与 Task 3(S3 AL 守卫)均修改 `ethercat_slave.h`/`.cpp`,建议串行实施避免冲突
+- Task 4(M4 降级模式)独立,改动 `ethercat_sync.cpp`,可与其他任务并行
+- Task 8(编译验证)依赖 Task 1-7 全部完成
+
+# 推荐执行顺序
+1. Task 6(M6 重命名)— 先改名,避免后续任务调用旧名
+2. Task 1(S1 PDO 偏移)+ Task 5(M5 索引)+ Task 7(M7 加宽)— 并行,改动不同代码段
+3. Task 4(M4 降级模式)— 独立文件,可并行
+4. Task 2(S2 process 桥接)
+5. Task 3(S3 AL 守卫)— 依赖 M6 重命名完成
+6. Task 8(编译验证)
@@ -0,0 +1,51 @@
+# Verification Checklist
+
+## 阶段 H1:safe* 接口收窄为 INIT-ONLY(高危 H1)
+- [x] `comm/esc_lan9252.cpp` 中 `safeReadReg` 实现内无 `__disable_irq()` / `__set_PRIMASK()` / `__get_PRIMASK()` 调用
+- [x] `comm/esc_lan9252.cpp` 中 `safeWriteReg` 实现内无 PRIMASK/disable_irq 调用
+- [x] `comm/esc_lan9252.cpp` 中 `safeReadPdi` 实现内无 PRIMASK/disable_irq 调用
+- [x] `comm/esc_lan9252.cpp` 中 `safeWritePdi` 实现内无 PRIMASK/disable_irq 调用
+- [x] 四个 safe* 函数改为直接调用对应无锁版本(`readReg`/`writeReg`/`readPdi`/`writePdi`)
+- [x] `comm/esc_lan9252.h` 中四个 safe* 接口注释含"INIT-ONLY"字样与"禁止运行期调用"说明
+- [x] `comm/ethercat_slave.cpp` 中 `process()` 注释无"使用 safeReadReg/safeWriteReg"诱导语
+- [x] `comm/ethercat_slave.cpp` 中 `process()` 注释含"运行期 PDO 交换仅通过三缓冲;ESC 寄存器访问仅限 init"说明
+- [x] grep 全项目,`safeReadReg`/`safeWriteReg`/`safeReadPdi`/`safeWritePdi` 的调用点仅在 init 阶段代码(`EthercatSlave::init()` 或更早),无主循环运行期调用
+
+## 阶段 M1:SYNC0 ISR 入口包装 RAM 化(中危 M1)
+- [x] `comm/ethercat_sync.cpp` 中 `EXTI0_IRQHandler` 标记 `__attribute__((section(".ramfunc"), noinline))`
+- [x] `comm/ethercat_sync.cpp` 中 `onSync0Exti` 标记 `__attribute__((section(".ramfunc"), noinline))`
+- [x] `onSync0Exti` 内无 `exti_interrupt_flag_clear(EXTI_0)` 库函数调用
+- [x] `onSync0Exti` 内无 `exti_interrupt_flag_get(EXTI_0)` 库函数调用(若有,改为直接读 `EXTI_PD` 位)
+- [x] `onSync0Exti` 标志位清零改为直接写 `EXTI_PD` 寄存器位
+- [x] `EXTI1_IRQHandler` / `onEscIrqExti` 未改动(仍可用库函数)
+- [x] `EXTI2_IRQHandler` / `onSync1Exti` 未改动
+- [x] `periodicIsr` / `readPdi` / `writePdi` / `read16` / `write16` 仍保持上一轮的 .ramfunc 标注(无回归)
+
+## 阶段 M2:NVIC 优先级分组最早设置(中危 M2)
+- [x] `sys/initial.cpp` 的 `AppInitializer::init()` 开头(任何外设 init 之前)有 `nvic_priority_group_set(CONFIG_NVIC_PRIORITY_GROUP)` 调用
+- [x] `device/timer.cpp` 的 `SchedulerTimer::init()` 内无 `nvic_priority_group_set` 调用(已移除)
+- [x] `sys/config.h` 中 `CONFIG_NVIC_PRIORITY_GROUP` 已定义(应为 `NVIC_PRIGROUP_PRE4_SUB0`)
+- [x] 全项目 grep `nvic_priority_group_set`,确认仅在 `initial.cpp` 调用一次(无 timer.cpp 残留,无其他重复)
+- [x] `AppInitializer::init()` 调用顺序中,`nvic_priority_group_set` 在 `CanFd::init()` / `AppSpiCommandBus.init()` / `SchedulerTimer::init()` / `EthercatSync::init()` 之前
+
+## 阶段 M3:删除 readBlock/writeBlock(中危 M3)
+- [x] `comm/esc_exmc_bus.cpp` 中无 `readBlock` 函数实现
+- [x] `comm/esc_exmc_bus.cpp` 中无 `writeBlock` 函数实现
+- [x] `comm/esc_exmc_bus.h` 中无 `readBlock` 成员声明
+- [x] `comm/esc_exmc_bus.h` 中无 `writeBlock` 成员声明
+- [x] 全项目 grep `readBlock`,无任何匹配(含注释)
+- [x] 全项目 grep `writeBlock`,无任何匹配(含注释)
+
+## 编译验证与一致性检查
+- [ ] 全量编译通过,无 error(⚠️ 待编译环境修复 EXMC pack 阻塞后验证)
+- [x] 静态审查:全项目 grep `__disable_irq` / `__set_PRIMASK`,确认 `comm/esc_lan9252.cpp` 的 safe* 实现中无残留
+- [x] 静态审查:全项目 grep `exti_interrupt_flag_clear(EXTI_0)`,确认 `comm/ethercat_sync.cpp` 中无残留
+- [x] 静态审查:全项目 grep `readBlock` / `writeBlock`,确认无残留
+- [x] 静态审查:全项目 grep `nvic_priority_group_set`,确认仅在 `initial.cpp` 一处
+- [ ] 若可编译:map 文件确认 `EXTI0_IRQHandler` / `onSync0Exti` 符号地址位于 SRAM(.ramfunc 段)(⚠️ 待编译环境修复后验证)
+
+## 风险闭环确认
+- [x] 高危 H1(safe* PRIMASK 陷阱):safe* 去 PRIMASK + 收窄 INIT-ONLY + process 注释修正,主循环运行期无 ESC 直接访问通道,闭环
+- [x] 中危 M1(SYNC0 入口包装未 RAM 化):EXTI0_IRQHandler/onSync0Exti 入 .ramfunc + 标志位清零去库函数,SYNC0 全程 RAM 执行,闭环
+- [x] 中危 M2(NVIC 分组设置过晚):分组设置前移到 init() 开头,SPI/CAN 优先级正确编码,闭环
+- [x] 中危 M3(readBlock/writeBlock 矛盾):删除未用接口,陷阱消除,闭环
@@ -0,0 +1,109 @@
+# EtherCAT 架构后审计高/中风险整改 Spec
+
+## Why
+上一轮 `fix-ethercat-realtime-comm-risks` 整改完成后,对 EtherCAT 通信架构进行了第二轮深度审计,发现 1 个高危陷阱与 3 个中危问题。其中 H1 是上一轮整改 Task 2 自身引入的回退(用 PRIMASK 实现 safe* 接口违反 BASEPRI 硬约束,且 `process()` 注释主动诱导主循环误用,一旦按注释实现即阻塞 SYNC0 10~30µs,直接破坏 <1µs 抖动目标);M1/M3 是上一轮 RAM 化整改的覆盖盲区(EXTI 入口包装未 RAM 化、未用函数声明与属性矛盾);M2 是预存的初始化顺序 bug(SPI/CAN 优先级被错误编码)。本 spec 在不推翻上一轮架构决策的前提下,收敛这 4 个残余风险点。
+
+## What Changes
+
+### 阶段 H1:重构 safe* 接口策略,关闭主循环误用陷阱(修复高危 H1)
+- **BREAKING(接口语义)**: `EscLan9252::safeReadReg/safeWriteReg/safeReadPdi/safeWritePdi` 语义由"Thread-safe,主循环运行期可调用"收窄为"**INIT-ONLY**,仅允许在 `EthercatSync::init()` 使能 EXTI NVIC 之前调用"
+- 移除 safe* 实现内部的 `__disable_irq()` / `__set_PRIMASK()` 包裹(违反 BASEPRI 硬约束)。init 阶段中断尚未使能,无需临界区保护;运行期调用本身被禁止,故无需提供"伪安全"的关中断包裹
+- 删除 `comm/ethercat_slave.cpp` 中 `process()` 注释里"若需访问 ESC 寄存器必须使用 safeReadReg/safeWriteReg"的诱导性说明,替换为"运行期 PDO 交换仅通过 `getLatestInputs()/setOutputs()` 三缓冲进行;ESC 寄存器访问仅限 init 阶段"
+- 头文件 `comm/esc_lan9252.h` 中 safe* 接口注释由"Thread-safe, PRIMASK 保护"改为"INIT-ONLY,禁止在 EXTI NVIC 使能后调用",并说明"运行期需要 ESC 寄存器访问时,须通过 SYNC0 ISR 代访队列实现(本 spec 不涵盖)"
+
+### 阶段 M1:SYNC0 ISR 入口包装 RAM 化(修复中危 M1)
+- 将 `comm/ethercat_sync.cpp` 中的 `EXTI0_IRQHandler` 与 `onSync0Exti` 标记 `__attribute__((section(".ramfunc"), noinline))`,使 SYNC0 中断从向量入口即进入 RAM 执行
+- 将 `onSync0Exti` 内部的 `exti_interrupt_flag_get(EXTI_0)` / `exti_interrupt_flag_clear(EXTI_0)` 库函数调用替换为直接寄存器位操作(`EXTI_PD` 寄存器写 1 清零),消除 ISR 路径上的 Flash 库函数调用
+- **范围限定**: 仅 RAM 化 SYNC0 路径(EXTI0,preempt=0,抖动敏感)。EXTI1(ESC IRQ,preempt=1)/EXTI2(SYNC1,preempt=1)入口包装不改,因 BASEPRI 可屏蔽 preempt=1,非抖动关键路径
+
+### 阶段 M2:NVIC 优先级分组设置前移(修复中危 M2)
+- 在 `sys/initial.cpp` 的 `AppInitializer::init()` 最开头(任何 `nvic_irq_enable` 之前,即 `CanFd::init()` / `AppSpiCommandBus.init()` / `SchedulerTimer::init()` / `EthercatSync::init()` 之前)增加 `nvic_priority_group_set(CONFIG_NVIC_PRIORITY_GROUP)`
+- 移除 `device/timer.cpp` 中 `SchedulerTimer::init()` 内的 `nvic_priority_group_set` 调用(改为由 initial.cpp 统一最早设置),避免重复设置
+- 此修复使 SPI0(EXTI10_15)/CAN 的 NVIC 优先级字节在 PRE4_SUB0 分组下正确编码,不再被库回退为 PRE2_SUB2 错编码
+
+### 阶段 M3:消除 readBlock/writeBlock 声明与属性矛盾(修复中危 M3)
+- **BREAKING(删除未用接口)**: 删除 `comm/esc_exmc_bus.cpp` 中的 `EscExmcBus::readBlock` / `writeBlock` 与 `comm/esc_exmc_bus.h` 中对应声明
+- 理由:这两个函数当前无任何调用点;块级 PDI 访问已由 `EscLan9252::readPdi/writePdi`(ISR 路径)与 `safeReadPdi/safeWritePdi`(init 路径)覆盖,功能重复;保留却声明"ISR-only"又未放 .ramfunc,构成误用陷阱
+- 若未来需要块访问,应通过 safe* 接口或新增带 .ramfunc 标注的 ISR 专用版本,不在本 spec 范围
+
+## Impact
+- Affected specs:
+  - `fix-ethercat-realtime-comm-risks`(上一轮整改 spec):本 spec 修正其 Task 2(safe* 用 PRIMASK)的决策回退,将 safe* 收窄为 init-only;修正其 Task 5(.ramfunc 覆盖)的入口包装盲区
+  - `add-ethercat-lan9252-realtime`(原集成 spec):无架构推翻
+- Affected code:
+  - `comm/esc_lan9252.h` / `comm/esc_lan9252.cpp`:safe* 接口去 PRIMASK、注释改 INIT-ONLY
+  - `comm/ethercat_slave.cpp`:`process()` 注释修正
+  - `comm/ethercat_sync.cpp`:`EXTI0_IRQHandler` / `onSync0Exti` 加 .ramfunc,标志位清零改直接寄存器写
+  - `comm/esc_exmc_bus.h` / `comm/esc_exmc_bus.cpp`:删除 readBlock/writeBlock
+  - `sys/initial.cpp`:init() 开头增加 nvic_priority_group_set
+  - `device/timer.cpp`:移除 SchedulerTimer::init() 内的 nvic_priority_group_set 调用
+
+## ADDED Requirements
+
+### Requirement: safe* ESC 访问接口限定为 INIT-ONLY
+系统 SHALL 将 `EscLan9252::safeReadReg/safeWriteReg/safeReadPdi/safeWritePdi` 的合法调用时机限定为"EXTI NVIC 使能之前(即 `EthercatSync::init()` 调用之前)"。这些接口 SHALL NOT 内部使用 `__disable_irq/__set_PRIMASK` 关中断(违反 BASEPRI 硬约束),因 init 阶段中断尚未使能,无需临界区。头文件 SHALL 通过注释明确标注"INIT-ONLY,禁止运行期调用"。
+
+主循环运行期 SHALL 仅通过三缓冲 `EthercatSlave::getLatestInputs()` / `setOutputs()` 交换 PDO,SHALL NOT 直接经 EXMC 访问 ESC 寄存器或 PDI。`EthercatSlave::process()` 的注释 SHALL 反映此约束,不得诱导主循环调用 safe* 接口。
+
+#### Scenario: init 阶段调用 safe 接口
+- **WHEN** `EthercatSlave::init()` 在中断使能前读取 ESC AL 状态寄存器
+- **THEN** 调用 `safeReadReg()`,内部无 PRIMASK/disable_irq 操作,直接经 EXMC 读取,因中断未使能无竞态
+
+#### Scenario: 运行期主循环不访问 ESC 寄存器
+- **WHEN** 主循环执行 `taskEthercatProcess()`(若实现)
+- **THEN** 仅调用 `getLatestInputs()` / `setOutputs()` 操作三缓冲,不调用任何 safe* 或 ISR-only 的 ESC 访问接口
+
+#### Scenario: process 注释不诱导误用
+- **WHEN** 开发者阅读 `ethercat_slave.cpp` 中 `process()` 的注释
+- **THEN** 注释明确说明"运行期 PDO 交换仅通过三缓冲;ESC 寄存器访问仅限 init",不出现"使用 safeReadReg/safeWriteReg"的引导语
+
+### Requirement: SYNC0 ISR 入口包装 RAM 执行
+系统 SHALL 将 SYNC0 中断路径的入口包装函数 `EXTI0_IRQHandler` 与 `onSync0Exti` 标记 `__attribute__((section(".ramfunc"), noinline))` 放入 `.ramfunc` 段,使 SYNC0 中断从向量入口到 `periodicIsr()` 的整条路径均在 SRAM 执行,消除入口段 Flash 取指引入的可变抖动。
+
+`onSync0Exti` 内部的 EXTI 标志位清零 SHALL 使用直接寄存器位写(`EXTI->PD = EXTI_0` 等价写法)替代 GD32 库函数 `exti_interrupt_flag_clear()`,避免在 RAM 路径中调用 Flash 库代码。
+
+#### Scenario: SYNC0 中断全程 RAM 执行
+- **WHEN** SYNC0 周期中断触发
+- **THEN** 从 `EXTI0_IRQHandler` → `onSync0Exti`(含标志位清零)→ `periodicIsr()` → `readPdi/writePdi` → `read16/write16` 全路径均在 `.ramfunc` 段(SRAM)执行
+
+#### Scenario: 标志位清零不经 Flash 库函数
+- **WHEN** `onSync0Exti` 清除 EXTI0 挂起标志
+- **THEN** 通过直接写 `EXTI->PD` 寄存器位完成,不调用 `exti_interrupt_flag_clear` 库函数
+
+### Requirement: NVIC 优先级分组最早设置
+系统 SHALL 在 `AppInitializer::init()` 的最开头(任何外设 init 调用之前)调用 `nvic_priority_group_set(CONFIG_NVIC_PRIORITY_GROUP)`,确保所有后续 `nvic_irq_enable` 调用(SPI0/EXTI10_15/CAN/Scheduler/EtherCAT)均在正确的优先级分组下编码优先级字节。
+
+`SchedulerTimer::init()` 内 SHALL NOT 再调用 `nvic_priority_group_set`(由 initial.cpp 统一设置,避免重复)。
+
+#### Scenario: SPI/CAN 优先级正确编码
+- **WHEN** `AppSpiCommandBus.init()` 调用 `nvic_irq_enable(EXTI10_15_IRQn, 3, 0)` 与 `CanFd::init()` 调用 CAN NVIC 使能
+- **THEN** 此时 PRIGROUP 已为 PRE4_SUB0,优先级字节按 preempt/sub 正确编码,不再被库回退为 PRE2_SUB2 错编码
+
+#### Scenario: EtherCAT 优先级不受影响
+- **WHEN** `EthercatSync::init()` 设置 EXTI0=preempt0/EXTI1/2=preempt1
+- **THEN** 优先级编码与整改前一致(EXTI0 在分组设置后初始化,原本即正确),无回归
+
+### Requirement: 移除未用的 readBlock/writeBlock 块访问接口
+系统 SHALL 删除 `EscExmcBus::readBlock` / `writeBlock` 函数实现与声明,消除"声明 ISR-only 却未放 .ramfunc 且无调用点"的矛盾陷阱。块级 PDI 访问由 `EscLan9252::readPdi/writePdi`(ISR)与 `safeReadPdi/safeWritePdi`(init)覆盖,功能无缺失。
+
+#### Scenario: 无 readBlock/writeBlock 残留
+- **WHEN** 全项目搜索 `readBlock` / `writeBlock`
+- **THEN** `comm/esc_exmc_bus.h` / `comm/esc_exmc_bus.cpp` 中无这两个符号,无其他文件引用
+
+## MODIFIED Requirements
+
+### Requirement: EXMC 总线访问权分离
+(原 spec `fix-ethercat-realtime-comm-risks` 中的"EXMC 总线访问权分离"要求)
+改:原要求将 safe* 接口定位为"Thread-safe,主循环与 init 调用,PRIMASK 保护"。本 spec 将其收窄为"INIT-ONLY,仅 init 阶段调用,无 PRIMASK"。理由:PRIMASK 阻塞 preempt=0 SYNC0 10~30µs,违反 <1µs 抖动;主循环运行期不应直接访问 ESC,应走三缓冲。原要求的 ISR-only 无锁接口(`readReg/writeReg/readPdi/writePdi/read16/write16`)定位不变。
+
+### Requirement: 周期 ISR 调用链 RAM 执行
+(原 spec `fix-ethercat-realtime-comm-risks` 中的"周期 ISR 调用链 RAM 执行"要求)
+改:原要求覆盖 `periodicIsr` 及其直接调用链(`readPdi/writePdi/read16/write16`)。本 spec 扩展覆盖至 SYNC0 入口包装(`EXTI0_IRQHandler`/`onSync0Exti`)及标志位清零路径,确保从向量入口到 PDO 处理的整条路径 RAM 化。EXTI1/EXTI2 入口不改(非抖动关键)。
+
+## Assumptions & Decisions
+1. **H1 不引入运行期 ESC 代访队列**:本 spec 仅关闭 safe* 运行期误用通道(去 PRIMASK + 改注释),不实现"主循环请求 → SYNC0 ISR 代访 ESC 寄存器"的队列机制。当前主循环无运行期 ESC 寄存器访问需求,代访队列属过度设计,留待未来协议栈集成时按需引入
+2. **M1 仅 RAM 化 SYNC0 路径**:EXTI1(ESC IRQ)/EXTI2(SYNC1)为 preempt=1,BASEPRI 可屏蔽,非 <1µs 抖动关键路径,不改。保持改动最小化
+3. **M2 不调整外设 init 顺序**:仅将 `nvic_priority_group_set` 前移到 init() 开头,不重排 `CanFd::init()` / `AppSpiCommandBus.init()` / `SchedulerTimer::init()` / `EthercatSync::init()` 的相对顺序,避免引入未知回归
+4. **M3 删除而非标注**:readBlock/writeBlock 无调用点且功能被 safe*Pdi 覆盖,删除优于保留+标注(减少未来维护负担与陷阱面)
+5. **H1 与上一轮 Task 2 的关系**:本 spec 的 H1 阶段实质是回退上一轮 Task 2.2"用 PRIMASK 而非 BASEPRI"的决策。该决策在当时看似合理(阻塞 preempt=0 保护 EXMC),但忽略了"主循环根本不应在运行期访问 ESC"这一更优解,且 PRIMASK 关中断时间(10~30µs)远超 <1µs 抖动预算。本 spec 用"禁止运行期访问"替代"PRIMASK 保护运行期访问"
+6. **不包含**:DWT 测量复查、map 文件验证(属上一轮 Task 6 编译验证范畴,本 spec 假设编译环境已就绪或独立验证)、LOW 风险项(L1-L6)
@@ -0,0 +1,35 @@
+# Tasks
+
+- [x] Task 1: 阶段 H1 — 重构 safe* 接口策略,关闭主循环误用陷阱(修复高危 H1)
+  - [x] SubTask 1.1: 修改 `comm/esc_lan9252.cpp` 中 `safeReadReg`/`safeWriteReg`/`safeReadPdi`/`safeWritePdi` 四个函数实现,移除内部的 `__get_PRIMASK()`/`__disable_irq()`/`__set_PRIMASK()` 包裹,直接调用对应的无锁版本(`readReg`/`writeReg`/`readPdi`/`writePdi`)
+  - [x] SubTask 1.2: 修改 `comm/esc_lan9252.h` 中四个 safe* 接口的注释,由"Thread-safe,主循环与 init 调用,PRIMASK 保护"改为"INIT-ONLY:仅允许在 `EthercatSync::init()` 使能 EXTI NVIC 之前调用;运行期禁止调用,需 ESC 寄存器访问须通过 SYNC0 ISR 代访队列(本 spec 不涵盖)"
+  - [x] SubTask 1.3: 修改 `comm/ethercat_slave.cpp` 中 `process()` 函数的注释,删除"若需访问 ESC 寄存器必须使用 safeReadReg/safeWriteReg"的诱导性说明,替换为"运行期 PDO 交换仅通过 `getLatestInputs()`/`setOutputs()` 三缓冲进行;ESC 寄存器访问仅限 init 阶段"
+  - [x] SubTask 1.4: 代码审查确认无主循环运行期路径调用 safe* 接口(grep `safeReadReg`/`safeWriteReg`/`safeReadPdi`/`safeWritePdi` 的调用点应仅在 `EthercatSlave::init()` 或更早的 init 代码中)
+
+- [x] Task 2: 阶段 M1 — SYNC0 ISR 入口包装 RAM 化(修复中危 M1)
+  - [x] SubTask 2.1: 在 `comm/ethercat_sync.cpp` 中为 `EXTI0_IRQHandler` 函数添加 `__attribute__((section(".ramfunc"), noinline))` 属性
+  - [x] SubTask 2.2: 在 `comm/ethercat_sync.cpp` 中为 `onSync0Exti` 函数添加 `__attribute__((section(".ramfunc"), noinline))` 属性
+  - [x] SubTask 2.3: 修改 `onSync0Exti` 内部的 EXTI 标志位清零逻辑,将 `exti_interrupt_flag_clear(EXTI_0)` 替换为直接寄存器位写(`EXTI_PD = EXTI_0` 等价写法,参考 GD32E50x 寄存器定义);若 `exti_interrupt_flag_get(EXTI_0)` 用于条件判断,也替换为直接读 `EXTI_PD` 位
+  - [x] SubTask 2.4: 确认 `onSync0Exti` 调用的 `EthercatSlave::periodicIsr()` 已在上一轮整改中标记 .ramfunc,无需重复标注;确认 `periodicIsr` 调用链(`readPdi`/`writePdi`/`read16`/`write16`)均已 .ramfunc
+  - [x] SubTask 2.5: 确认 EXTI1_IRQHandler/onEscIrqExti 与 EXTI2_IRQHandler/onSync1Exti 不做改动(范围限定,preempt=1 非抖动关键)
+
+- [x] Task 3: 阶段 M2 — NVIC 优先级分组设置前移(修复中危 M2)
+  - [x] SubTask 3.1: 在 `sys/initial.cpp` 的 `AppInitializer::init()` 最开头(任何外设 init 调用之前,通常在函数体第一行)增加 `nvic_priority_group_set(CONFIG_NVIC_PRIORITY_GROUP);`
+  - [x] SubTask 3.2: 在 `device/timer.cpp` 的 `SchedulerTimer::init()` 中移除原有的 `nvic_priority_group_set(CONFIG_NVIC_PRIORITY_GROUP)` 调用(改为由 initial.cpp 统一最早设置)
+  - [x] SubTask 3.3: 确认 `sys/config.h` 中已定义 `CONFIG_NVIC_PRIORITY_GROUP`(应为 `NVIC_PRIGROUP_PRE4_SUB0`);若无定义则补充
+  - [x] SubTask 3.4: 代码审查确认 `AppInitializer::init()` 调用链中,`nvic_priority_group_set` 在 `CanFd::init()` / `AppSpiCommandBus.init()` / `SchedulerTimer::init()` / `EthercatSync::init()` 之前执行
+
+- [x] Task 4: 阶段 M3 — 删除未用的 readBlock/writeBlock(修复中危 M3)
+  - [x] SubTask 4.1: 删除 `comm/esc_exmc_bus.cpp` 中的 `EscExmcBus::readBlock` 与 `EscExmcBus::writeBlock` 函数实现
+  - [x] SubTask 4.2: 删除 `comm/esc_exmc_bus.h` 中的 `readBlock` 与 `writeBlock` 成员函数声明
+  - [x] SubTask 4.3: 删除或修正 `comm/esc_exmc_bus.h` 中关于 readBlock/writeBlock 的"ISR-only"注释(随声明一并删除)
+  - [x] SubTask 4.4: 全项目 grep 确认无 `readBlock`/`writeBlock` 残留引用
+
+- [x] Task 5: 编译验证与一致性检查(静态审查完成,编译受 EXMC pack 阻塞)
+  - [x] SubTask 5.1: 全量编译通过,无 error(⚠️ 受 EXMC pack 解析问题阻塞,改为静态代码审查,详见下方)
+  - [x] SubTask 5.2: 静态代码审查确认:无 `__disable_irq`/`__set_PRIMASK` 残留于 `comm/esc_lan9252.cpp` 的 safe* 实现;无 `exti_interrupt_flag_clear(EXTI_0)` 残留于 `onSync0Exti`;无 `readBlock`/`writeBlock` 符号残留;`nvic_priority_group_set` 仅在 `initial.cpp` 调用一次
+  - [ ] SubTask 5.3: 若可编译,查看 map 文件确认 `EXTI0_IRQHandler`/`onSync0Exti` 符号地址位于 SRAM(.ramfunc 段)(⚠️ 受编译阻塞,待编译环境修复后验证)
+
+# Task Dependencies
+- Task 1, 2, 3, 4 相互独立,可并行实施(改动不同文件/不同函数,无交叉)
+- Task 5 依赖 Task 1-4 全部完成
@@ -0,0 +1,70 @@
+# Verification Checklist
+
+## 阶段 A:周期任务标志脱离 TaskManager(严重风险 #1)
+- [x] `comm/ethercat_slave.h` 中声明 `s_periodicSeq` / `s_processedSeq` 静态成员
+- [x] `comm/ethercat_slave.h` 中声明 `hasPendingPeriodic()` / `markPeriodicProcessed()` 公有接口
+- [x] `comm/ethercat_slave.cpp` 的 `periodicIsr()` 末尾无 `TaskManager::set(1UL << TASK_ETHERCAT_PROCESS)`,改为 `s_periodicSeq++`
+- [x] `hasPendingPeriodic()` 返回 `s_periodicSeq != s_processedSeq`
+- [x] `markPeriodicProcessed()` 执行 `s_processedSeq = s_periodicSeq`
+- [x] `sys/task_runner.cpp` 的 `runPending()` 中增加 `hasPendingPeriodic()` 检查分支,受 `#if CONFIG_ETHERCAT_ENABLE` 保护
+- [x] `comm/ethercat_sync.cpp` 的 `onEscIrqExti()` 仍调用 `TaskManager::set(1UL << TASK_ETHERCAT_PROCESS)`,未改动
+- [x] `comm/ethercat_slave.h` 头注释说明周期路径与事件路径的标志分离机制
+- [x] 确认 `task_flags` 不再被 preempt=0 的 periodicIsr 触碰
+
+## 阶段 B:EXMC 总线访问权分离(严重风险 #2)
+- [x] `comm/esc_lan9252.h` 声明 `safeReadReg` / `safeWriteReg` / `safeReadPdi` / `safeWritePdi` 四个 safe 接口
+- [x] `comm/esc_lan9252.cpp` 实现 safe 接口,内部用 `__disable_irq/__set_PRIMASK` 包裹(非 BASEPRI)
+- [x] `comm/esc_lan9252.h` 注释标注 `readReg/writeReg/readPdi/writePdi` 为 "ISR-only,preempt=0 调用,无锁"
+- [x] `comm/esc_lan9252.h` 注释标注 `safeReadReg/safeWriteReg/safeReadPdi/safeWritePdi` 为 "Thread-safe,主循环/init 调用,PRIMASK 保护"
+- [x] `comm/esc_exmc_bus.h` 注释标注 `read16/write16/readBlock/writeBlock` 调用约束
+- [x] `comm/ethercat_slave.cpp` 的 `init()` 中 EXMC 访问改用 safe 接口
+- [x] `comm/ethercat_slave.cpp` 的 `process()` 若有 EXMC 访问,使用 safe 接口
+- [x] `comm/ethercat_slave.cpp` 的 `periodicIsr()` 仍调用无锁 `readPdi/writePdi`
+- [x] 代码审查确认无主循环路径误调用 ISR-only 接口
+
+## 阶段 C:PDO 三缓冲替换双缓冲(严重风险 #3 与 #4)
+- [x] `comm/ethercat_slave.h` 中 `s_inputs` / `s_outputs` 数组大小改为 3
+- [x] `comm/ethercat_slave.h` 成员名改为 `s_inputWriteIdx` / `s_outputReadIdx`(无原 `s_inputReadIndex` / `s_outputWriteIndex` 残留)
+- [x] `comm/ethercat_slave.cpp` 的 `init()` 初始化 `s_inputWriteIdx = 0` / `s_outputReadIdx = 0`
+- [x] `comm/ethercat_slave.cpp` 的 `periodicIsr()` 使用模 3 轮转写入 `s_inputs[s_inputWriteIdx]` 后递增
+- [x] `comm/ethercat_slave.cpp` 的 `periodicIsr()` 使用模 3 轮转读取 `s_outputs[s_outputReadIdx]` 后递增
+- [x] `comm/ethercat_slave.cpp` 的 `getLatestInputs()` 返回 `&s_inputs[(s_inputWriteIdx + 2) % 3]`
+- [x] `comm/ethercat_slave.cpp` 的 `setOutputs()` 写入 `s_outputs[(s_outputReadIdx + 1) % 3]`,无临界区
+- [x] 全项目搜索确认无残留的 `^1U` XOR 翻转逻辑(原双缓冲)
+- [x] `comm/ethercat_slave.h` 头注释更新为三缓冲说明,标注容忍度"主循环处理 < 2 × 周期时间"
+
+## 阶段 D:periodicIsr 执行时间测量(高风险 #5)
+- [x] `comm/ethercat_slave.h` 声明 `s_isrMaxCycles` / `s_isrAvgCycles` / `s_isrCount` 诊断成员
+- [x] `comm/ethercat_slave.cpp` 的 `periodicIsr()` 入口/出口读取 `DWT->CYCCNT` 计算差值
+- [x] `periodicIsr()` 更新 max(原子比较)与 avg 统计
+- [x] `sys/initial.cpp` 或 `comm/esc_lan9252.cpp::init()` 中使能 DWT(DEMCR + CYCCNT)
+- [x] `sys/task_runner.cpp` 的 `taskDiagnosticPrint()` 增加 `periodicIsr max=Xus avg=Yus` 输出(受 `#if CONFIG_ETHERCAT_ENABLE` 保护)
+- [x] `sys/config.h` 增加 `CONFIG_ETHERCAT_ISR_MAX_US_THRESHOLD 5U` 宏
+- [x] spec.md 或代码注释记录 >5µs 的评估流程与 ≤5µs 的接受说明
+
+## 阶段 E:.ramfunc 段落地与调用链 RAM 化(高风险 #6)
+- [x] 定位到项目链接脚本文件(`.sct` 或 RTE 配置)
+- [x] 链接脚本中新增 `.ramfunc` 输出段,VMA 在 SRAM,LMA 在 Flash
+- [x] 启动代码中确认/增加 `.ramfunc` 段从 Flash 到 RAM 的拷贝逻辑
+- [x] `comm/ethercat_slave.cpp` 的 `periodicIsr()` 标记 `__attribute__((section(".ramfunc"), noinline))`
+- [x] `comm/esc_lan9252.cpp` 的 `readPdi()` / `writePdi()` 标记 `__attribute__((section(".ramfunc"), noinline))`
+- [x] `comm/esc_exmc_bus.cpp` 的 `read16()` / `write16()` 标记 `__attribute__((section(".ramfunc"), noinline))`
+- [x] `readBlock()` / `writeBlock()` 不标记(非 ISR 调用链)
+- [ ] map 文件确认 `.ramfunc` 段 VMA 在 SRAM 区域、LMA 在 Flash 区域
+- [ ] map 文件确认 `periodicIsr` / `readPdi` / `writePdi` / `read16` / `write16` 符号地址在 SRAM
+
+## 编译验证与回退
+- [ ] `CONFIG_ETHERCAT_ENABLE=1` 时全量编译通过,无 error
+- [ ] `CONFIG_ETHERCAT_ENABLE=1` 时无新增 warning(特别检查 `.ramfunc` 相关链接警告)
+- [ ] map 文件确认 `s_inputs[3]` / `s_outputs[3]` / `s_periodicSeq` 在 SRAM
+- [ ] `CONFIG_ETHERCAT_ENABLE` 恢复为 0
+- [ ] `CONFIG_ETHERCAT_ENABLE=0` 时全量编译仍通过
+- [ ] `CONFIG_ETHERCAT_ENABLE=0` 时功能与改造前等价(ADC/CAN/SPI 正常)
+
+## 严重风险闭环确认
+- [x] 严重风险 #1(task_flags 丢失更新):periodicIsr 不再触碰 task_flags,闭环
+- [x] 严重风险 #2(EXMC 总线争用):主循环访问走 safe 接口(PRIMASK),ISR 走无锁,闭环
+- [x] 严重风险 #3(PDO 双缓冲竞态):三缓冲容忍跨周期,闭环
+- [x] 严重风险 #4(setOutputs 拷贝竞态):三缓冲隔离,无需锁,闭环
+- [x] 高风险 #5(ISR 慢速 EXMC 循环):DWT 测量 + 评估阈值,闭环
+- [x] 高风险 #6(.ramfunc 未落地):链接脚本 + 启动拷贝 + 调用链 RAM 化,闭环
@@ -0,0 +1,147 @@
+# EtherCAT 实时通信风险整改 Spec
+
+## Why
+针对上一轮架构评审发现的 4 个严重风险和 2 个高风险,这些风险在 `CONFIG_ETHERCAT_ENABLE=1`(焊接 LAN9252 后)会直接威胁 EtherCAT/SPI/CAN 全链路通信可靠性与 <1µs 抖动目标。当前 `CONFIG_ETHERCAT_ENABLE=0` 下风险不触发,但必须在使能前彻底修复,否则硬件上线即出问题。
+
+核心矛盾在于:BASEPRI 临界区**无法保护 preempt=0 的 SYNC0 ISR** 与主循环之间的共享数据 RMW 竞态,而 SYNC0 ISR 又承担了慢速 EXMC 访问与缓冲管理。本 spec 通过"数据路径分离 + 三缓冲 + EXMC 访问权独占 + 独立 pending 标志 + RAM 执行段落地"五个维度系统性消除这些风险。
+
+## What Changes
+
+### 阶段 A:EtherCAT 周期任务标志脱离 TaskManager(修复严重风险 #1)
+- **BREAKING**: `EthercatSlave::periodicIsr()` 不再调用 `TaskManager::set(1UL << TASK_ETHERCAT_PROCESS)`,改用独立的 `volatile uint8_t s_periodicSeq` 序列号原子递增机制
+- 主循环 `TaskRunner::runPending()` 优先检查 `s_periodicSeq` 变化,若变化则调用 `taskEthercatProcess()` 并记录已处理序号
+- ESC IRQ(EXTI1,preempt=1)仍可使用 `TaskManager::set()`,因为 BASEPRI 能屏蔽 preempt=1,无竞态
+- `TASK_ETHERCAT_PROCESS` 枚举保留(供 ESC IRQ 路径使用),但周期路径不再触碰 `task_flags`
+
+### 阶段 B:EXMC 总线访问权分离(修复严重风险 #2)
+- 明确规则:`EscExmcBus::read16/write16/readBlock/writeBlock` 与 `EscLan9252::readReg/writeReg/readPdi/writePdi` 仅限 preempt=0 ISR 路径调用,无锁
+- 新增 `EscLan9252::safeReadReg/safeWriteReg/safeReadPdi/safeWritePdi` 主循环专用接口,内部使用 PRIMASK 临界区包裹(EXMC 访问不频繁,短暂关中断对抖动影响可忽略)
+- `EthercatSlave::init()` 中的 ESC 寄存器配置改为 `safeWriteReg`,因 init 阶段中断虽未使能但保持一致性
+- 在 `esc_exmc_bus.h` / `esc_lan9252.h` 头文件注释中明确标注"ISR-only"与"thread-safe"两类接口的调用约束
+
+### 阶段 C:PDO 三缓冲替换双缓冲(修复严重风险 #3 与 #4)
+- **BREAKING**: `s_inputs[2]` / `s_outputs[2]` 改为 `s_inputs[3]` / `s_outputs[3]`,索引管理改为模 3 轮转
+- 输入路径:ISR 维护 `s_inputWriteIdx`,写入后递增;`getLatestInputs()` 返回 `(s_inputWriteIdx + 2) % 3`(最新完成且与 ISR 当前写入隔一个缓冲),容忍主循环跨 1 个周期
+- 输出路径:`setOutputs()` 写入 `(s_outputReadIdx + 1) % 3`(ISR 下次要写位置的下一个),与 ISR 当前读取位置隔一个缓冲,彻底消除拷贝竞态
+- 移除原 XOR 翻转逻辑,改为显式模 3 索引管理
+- `PdoBuffer` 结构不变(仍为 32 字节 data + len)
+
+### 阶段 D:periodicIsr 执行时间测量与评估(修复高风险 #5)
+- 在 `periodicIsr()` 入口/出口读取 DWT 周期计数器(`DWT_CYCCNT`),记录最大执行周期数
+- 通过诊断打印输出 ISR 最大/平均执行时间(单位 µs,基准 180MHz)
+- 若实测 > 5µs,触发评估:减小 `CONFIG_ETHERCAT_PDO_SIZE` 或优化 EXMC 时序参数
+- 若实测 ≤ 5µs,在 spec 与代码注释中明确记录"preempt=0 ISR 阻塞 ≤ 5µs,其他中断(CAN/SPI)需容忍此窗口",并验证 SPI0 从机在此窗口内不会 RX 溢出
+
+### 阶段 E:.ramfunc 段落地与调用链 RAM 化(修复高风险 #6)
+- 修改链接脚本(或 RTE 配置)定义 `.ramfunc` 输出段到 SRAM,并在启动代码中增加 `.ramfunc` 从 Flash 到 RAM 的拷贝(类似 `.data` 段加载区到执行区)
+- 将 `EthercatSlave::periodicIsr()` 及其直接调用链(`EscLan9252::readPdi/writePdi`、`EscExmcBus::read16/write16`)标记 `__attribute__((section(".ramfunc"), noinline))`
+- 验证 map 文件确认 `.ramfunc` 段实际加载到 RAM 地址
+- 若 DWT 测量显示 Flash 执行已满足抖动(<1µs),可降级为仅标记 periodicIsr 本体,但默认按完整 RAM 化实施
+
+## Impact
+- Affected specs:
+  - `add-ethercat-lan9252-realtime`(原集成 spec):本 spec 修正其阶段 2/3 的实现缺陷,不推翻其架构决策
+- Affected code:
+  - `comm/ethercat_slave.h` / `comm/ethercat_slave.cpp`:三缓冲改造、periodicSeq 机制、safe 接口调用
+  - `comm/esc_lan9252.h` / `comm/esc_lan9252.cpp`:新增 safe 接口、ISR-only 接口标注
+  - `comm/esc_exmc_bus.h` / `comm/esc_exmc_bus.cpp`:接口调用约束注释(无功能改动)
+  - `sys/task_runner.cpp`:`runPending()` 增加 periodicSeq 检查分支,`taskEthercatProcess()` 改为通过三缓冲读取
+  - `sys/task_manager.cpp` / `sys/task_manager.h`:无改动(periodicIsr 不再调用 set)
+  - 链接脚本(`.sct` 或等价):新增 `.ramfunc` 段定义
+  - 启动代码:`.ramfunc` 拷贝逻辑(若 CMSIS 启动未自动处理)
+  - `sys/config.h`:可能新增 `CONFIG_ETHERCAT_PDO_SIZE` 调整开关(若阶段 D 评估需要)
+
+## ADDED Requirements
+
+### Requirement: EtherCAT 周期任务标志独立于 TaskManager
+系统 SHALL 使 `EthercatSlave::periodicIsr()`(preempt=0)不再通过 `TaskManager::set()` 置位 `task_flags`,改用独立的 `volatile uint8_t s_periodicSeq` 序列号。ISR 每次完成周期处理后递增该序列号;主循环 `TaskRunner::runPending()` 通过比较已处理序号与当前序号检测是否有新的周期数据待处理。`task_flags` 仅由 preempt≥1 的中断(ESC IRQ、CAN RX、调度器)与主循环访问,BASEPRI 临界区可完全保护其 RMW 原子性。
+
+#### Scenario: SYNC0 ISR 不触碰 task_flags
+- **WHEN** SYNC0 周期中断触发,`periodicIsr()` 执行完成
+- **THEN** `task_flags` 保持不变,仅 `s_periodicSeq` 递增
+
+#### Scenario: 主循环检测周期数据
+- **WHEN** 主循环 `runPending()` 执行,发现 `s_periodicSeq` 与上次记录的已处理序号不同
+- **THEN** 调用 `taskEthercatProcess()` 处理最新 PDO,并更新已处理序号为当前 `s_periodicSeq`
+
+#### Scenario: ESC IRQ 仍用 TaskManager
+- **WHEN** ESC 事件中断(EXTI1,preempt=1)触发
+- **THEN** `onEscIrqExti()` 调用 `TaskManager::set(1UL << TASK_ETHERCAT_PROCESS)`,BASEPRI 临界区保护该 RMW,无竞态
+
+### Requirement: EXMC 总线访问权分离
+系统 SHALL 将 EXMC 访问接口分为两类:
+1. **ISR-only**(无锁):`EscExmcBus::read16/write16/readBlock/writeBlock`、`EscLan9252::readReg/writeReg/readPdi/writePdi`,仅供 preempt=0 的 `periodicIsr()` 调用
+2. **Thread-safe**(PRIMASK 保护):`EscLan9252::safeReadReg/safeWriteReg/safeReadPdi/safeWritePdi`,供主循环与初始化代码调用,内部用 `__disable_irq/__set_PRIMASK` 短暂关中断
+
+头文件 SHALL 通过注释明确标注每个接口的调用约束,违反约束(主循环调用 ISR-only 接口)视为编程错误。
+
+#### Scenario: 主循环安全访问 ESC 寄存器
+- **WHEN** 主循环需要读取 ESC AL 状态寄存器
+- **THEN** 调用 `EscLan9252::safeReadReg()`,内部 PRIMASK 关中断后访问 EXMC,完成后恢复,期间 SYNC0 ISR 被阻塞但 EXMC 访问原子完成
+
+#### Scenario: ISR 无锁访问 PDI
+- **WHEN** `periodicIsr()` 读取输入 PDO
+- **THEN** 调用 `EscLan9252::readPdi()`(无锁),因 ISR 为 preempt=0,不会被任何中断抢占,EXMC 访问天然原子
+
+### Requirement: PDO 三缓冲机制
+系统 SHALL 使用三缓冲(triple buffer)替代原双缓冲实现 PDO 数据交换,容忍主循环处理延迟最多 1 个 EtherCAT 周期。
+
+输入路径:
+- `s_inputs[3]`,ISR 维护 `s_inputWriteIdx`(0/1/2 模 3 轮转)
+- ISR 写入 `s_inputs[s_inputWriteIdx]`,完成后 `s_inputWriteIdx = (s_inputWriteIdx + 1) % 3`
+- `getLatestInputs()` 返回 `&s_inputs[(s_inputWriteIdx + 2) % 3]`(最新完成且与 ISR 下次写入隔一个缓冲)
+
+输出路径:
+- `s_outputs[3]`,ISR 维护 `s_outputReadIdx`(0/1/2 模 3 轮转)
+- ISR 读取 `s_outputs[s_outputReadIdx]`,完成后 `s_outputReadIdx = (s_outputReadIdx + 1) % 3`
+- `setOutputs()` 写入 `s_outputs[(s_outputReadIdx + 1) % 3]`(ISR 下次要读的下一个,与当前读取位置隔一个)
+
+#### Scenario: 主循环慢于 1 个周期不丢数据
+- **WHEN** 主循环 `getLatestInputs()` 读取缓冲 A 后,在处理期间 ISR 又完成 1 帧(写入 B 并递增 writeIdx)
+- **THEN** 主循环继续处理 A 不受影响,A 与 ISR 当前写入位置 C 隔一个缓冲,不会被覆盖
+
+#### Scenario: setOutputs 拷贝不被 ISR 抢占破坏
+- **WHEN** 主循环 `setOutputs()` 正在拷贝输出缓冲,SYNC0 ISR 触发
+- **THEN** ISR 读取的 `s_outputReadIdx` 指向与主循环写入位置隔一个的缓冲,两者不冲突,无需任何锁
+
+### Requirement: periodicIsr 执行时间测量
+系统 SHALL 在 `periodicIsr()` 中使用 DWT 周期计数器(`DWT_CYCCNT`)测量执行时间,并通过诊断打印输出最大与平均执行时间(单位 µs,基准 180MHz)。测量结果用于验证 preempt=0 ISR 阻塞窗口是否可接受。
+
+#### Scenario: 测量并打印 ISR 执行时间
+- **WHEN** 系统运行 EtherCAT 周期通信,诊断打印任务触发
+- **THEN** 输出包含 `periodicIsr max=Xus avg=Yus` 信息,供开发者评估
+
+#### Scenario: ISR 执行时间超限告警
+- **WHEN** 实测 `periodicIsr` 最大执行时间 > 5µs
+- **THEN** 触发评估:减小 `CONFIG_ETHERCAT_PDO_SIZE` 或优化 EXMC 时序,重新测量直至满足
+
+### Requirement: 周期 ISR 调用链 RAM 执行
+系统 SHALL 通过链接脚本定义 `.ramfunc` 输出段定位到 SRAM,并在启动时从 Flash 加载区拷贝到 RAM 执行区。`EthercatSlave::periodicIsr()` 及其直接调用链(`EscLan9252::readPdi/writePdi`、`EscExmcBus::read16/write16`)SHALL 标记 `__attribute__((section(".ramfunc"), noinline))` 放入该段。
+
+#### Scenario: .ramfunc 段加载到 RAM
+- **WHEN** 编译生成 map 文件
+- **THEN** `.ramfunc` 段的执行地址(VMA)位于 SRAM 区域,加载地址(LMA)位于 Flash 区域,启动代码完成拷贝
+
+#### Scenario: 周期 ISR 无 Flash wait state 抖动
+- **WHEN** `periodicIsr()` 连续执行多次,DWT 测量执行时间
+- **THEN** 执行时间波动显著小于 Flash 执行版本,满足 <1µs 抖动目标
+
+## MODIFIED Requirements
+
+### Requirement: EtherCAT 周期数据双缓冲
+(原 spec `add-ethercat-lan9252-realtime` 中的双缓冲要求)
+改:由双缓冲(ping-pong)改为三缓冲(triple buffer),容忍主循环跨 1 个周期处理延迟,消除 `getLatestInputs()` 与 `setOutputs()` 的竞态窗口。具体实现见 ADDED Requirements "PDO 三缓冲机制"。
+
+### Requirement: 周期 ISR 放 RAM 执行段
+(原 spec `add-ethercat-lan9252-realtime` 中的 RAM 执行段要求)
+改:原 spec 仅要求 `periodicIsr()` 标记 section 属性,未要求链接脚本与启动拷贝落地。本 spec 明确要求:链接脚本定义 `.ramfunc` 输出段到 SRAM,启动代码增加拷贝逻辑,且 `periodicIsr()` 的直接调用链(readPdi/writePdi/read16/write16)也需 RAM 化,否则调用链仍在 Flash 执行,抖动目标无法达成。
+
+## Assumptions & Decisions
+
+1. **修复时机**:本 spec 所有改动在 `CONFIG_ETHERCAT_ENABLE=0` 下不触发编译(因 `comm/` 代码被 `#if` 包裹),但改动完成后必须将 `CONFIG_ETHERCAT_ENABLE` 临时设为 1 进行编译验证,验证后恢复为 0
+2. **三缓冲容忍度**:三缓冲容忍主循环跨 1 个周期(即主循环处理时间 ≤ 2 × 周期时间)。100µs 周期下,主循环有 200µs 处理窗口,远超 32 字节 PDO 映射所需(µs 级),实际不会触发容忍上限
+3. **PRIMASK 在主循环 safe 接口中的影响**:主循环访问 ESC 寄存器(AL 状态查询等)不频繁,PRIMASK 关中断时间约 1~2µs(单次寄存器读写),对 EtherCAT 抖动影响可忽略。若后续协议栈需要频繁主循环 EXMC 访问,需重新评估
+4. **DWT 可用性**:GD32E508(Cortex-M4F)支持 DWT,`DWT_CYCCNT` 可用。需在初始化时使能 DWT 与 DEMO 寄存器
+5. **链接脚本格式**:项目使用 AC6(armclang),链接脚本为 `.sct` 格式(SCT 文件)。`.ramfunc` 段定义需符合 SCT 语法
+6. **不包含**:完整 EtherCAT 协议栈集成(SSC)、EEPROM/ESI 配置、应用对象字典——这些由后续 spec 处理,本 spec 仅修复通信基础设施风险
+7. **TASK_ETHERCAT_PROCESS 枚举保留**:虽然周期路径不再使用,但 ESC IRQ 路径仍用,枚举不删除,避免破坏 `task_runner.cpp` 现有分支
@@ -0,0 +1,59 @@
+# Tasks
+
+- [x] Task 1: 阶段 A — EtherCAT 周期任务标志脱离 TaskManager(修复严重风险 #1)
+  - [x] SubTask 1.1: 在 `comm/ethercat_slave.h` 中声明 `static volatile uint8_t s_periodicSeq` 与 `static uint8_t s_processedSeq` 私有静态成员,并增加 `static bool hasPendingPeriodic()` / `static void markPeriodicProcessed()` 公有接口
+  - [x] SubTask 1.2: 在 `comm/ethercat_slave.cpp` 的 `periodicIsr()` 末尾移除 `TaskManager::set(1UL << TASK_ETHERCAT_PROCESS)`,改为 `s_periodicSeq++`(uint8 自然回绕,原子单字节写)
+  - [x] SubTask 1.3: 实现 `hasPendingPeriodic()` 返回 `s_periodicSeq != s_processedSeq`,`markPeriodicProcessed()` 执行 `s_processedSeq = s_periodicSeq`
+  - [x] SubTask 1.4: 在 `sys/task_runner.cpp` 的 `runPending()` 开头(TaskManager::takePending 之前或之后)增加:`if (EthercatSlave::hasPendingPeriodic()) { EthercatSlave::markPeriodicProcessed(); taskEthercatProcess(); }`,该分支用 `#if CONFIG_ETHERCAT_ENABLE` 保护
+  - [x] SubTask 1.5: 确认 ESC IRQ 路径(`comm/ethercat_sync.cpp::onEscIrqExti()`)仍调用 `TaskManager::set(1UL << TASK_ETHERCAT_PROCESS)`,BASEPRI 保护该路径,无改动
+  - [x] SubTask 1.6: 在 `comm/ethercat_slave.h` 头注释中说明"周期路径用 s_periodicSeq,事件路径用 TASK_ETHERCAT_PROCESS,两者独立"
+
+- [x] Task 2: 阶段 B — EXMC 总线访问权分离(修复严重风险 #2)
+  - [x] SubTask 2.1: 在 `comm/esc_lan9252.h` 中声明 `static uint16_t safeReadReg(uint16_t addr)` / `static void safeWriteReg(uint16_t addr, uint16_t val)` / `static void safeReadPdi(uint16_t offset, uint8_t *buf, size_t len)` / `static void safeWritePdi(uint16_t offset, const uint8_t *buf, size_t len)` 公有接口
+  - [x] SubTask 2.2: 在 `comm/esc_lan9252.cpp` 实现 safe 接口,内部用 `__disable_irq()` / `__set_PRIMASK()` 包裹(注意:这里用 PRIMASK 而非 BASEPRI,因为要阻塞 preempt=0 的 SYNC0),调用对应的无锁版本后恢复
+  - [x] SubTask 2.3: 在 `comm/esc_lan9252.h` / `comm/esc_exmc_bus.h` 头文件注释中明确标注:`readReg/writeReg/readPdi/writePdi/read16/write16/readBlock/writeBlock` 为 "ISR-only,仅供 preempt=0 调用,无锁";`safeReadReg/safeWriteReg/safeReadPdi/safeWritePdi` 为 "Thread-safe,主循环与 init 调用,PRIMASK 保护"
+  - [x] SubTask 2.4: 审查 `comm/ethercat_slave.cpp` 的 `init()` 与 `process()`,所有 EXMC 访问改用 safe 接口(init 阶段虽中断未使能但保持一致性;process 若有 EXMC 访问必须用 safe)
+  - [x] SubTask 2.5: 在 `comm/ethercat_slave.cpp` 的 `periodicIsr()` 中确认仍调用无锁的 `readPdi/writePdi`(因 ISR 为 preempt=0,天然原子)
+  - [x] SubTask 2.6: 代码审查确认无主循环路径误调用 ISR-only 接口
+
+- [x] Task 3: 阶段 C — PDO 三缓冲替换双缓冲(修复严重风险 #3 与 #4)
+  - [x] SubTask 3.1: 在 `comm/ethercat_slave.h` 中将 `s_inputs[2]` / `s_outputs[2]` 改为 `s_inputs[3]` / `s_outputs[3]`,成员名改为 `s_inputWriteIdx` / `s_outputReadIdx`(替换原 `s_inputReadIndex` / `s_outputWriteIndex`),类型 `volatile uint8_t`
+  - [x] SubTask 3.2: 在 `comm/ethercat_slave.h` 头注释中更新双缓冲说明为三缓冲说明,描述模 3 轮转规则
+  - [x] SubTask 3.3: 在 `comm/ethercat_slave.cpp` 的 `init()` 中初始化 `s_inputWriteIdx = 0` / `s_outputReadIdx = 0`
+  - [x] SubTask 3.4: 重写 `periodicIsr()` 的缓冲管理:写入 `s_inputs[s_inputWriteIdx]` → 递增 `s_inputWriteIdx = (s_inputWriteIdx + 1) % 3`;读取 `s_outputs[s_outputReadIdx]` → 递增 `s_outputReadIdx = (s_outputReadIdx + 1) % 3`
+  - [x] SubTask 3.5: 重写 `getLatestInputs()` 返回 `&s_inputs[(s_inputWriteIdx + 2) % 3]`(最新完成且与 ISR 当前写入隔一个)
+  - [x] SubTask 3.6: 重写 `setOutputs()` 写入 `s_outputs[(s_outputReadIdx + 1) % 3]`(与 ISR 当前读取隔一个),无需临界区
+  - [x] SubTask 3.7: 移除原 XOR 翻转逻辑(`^1U`),确认无残留引用
+  - [x] SubTask 3.8: 在 `comm/ethercat_slave.h` 注释中明确"三缓冲容忍主循环跨 1 个周期,主循环处理必须 < 2 × 周期时间"
+
+- [x] Task 4: 阶段 D — periodicIsr 执行时间测量与评估(修复高风险 #5)
+  - [x] SubTask 4.1: 在 `comm/ethercat_slave.h` 增加 `static volatile uint32_t s_isrMaxCycles` / `static volatile uint32_t s_isrAvgCycles` / `static volatile uint32_t s_isrCount` 诊断成员
+  - [x] SubTask 4.2: 在 `comm/ethercat_slave.cpp` 的 `periodicIsr()` 入口读 `DWT->CYCCNT` 存局部变量,出口再读,差值更新 max(原子比较)与 avg(滑动平均或累加)
+  - [x] SubTask 4.3: 在 `sys/initial.cpp` 或 `comm/esc_lan9252.cpp::init()` 中使能 DWT:`CoreDebug->DEMCR |= CoreDebug_DEMCR_TRCENA_Msk; DWT->CYCCNT = 0; DWT->CTRL |= DWT_CTRL_CYCCNTENA_Msk;`
+  - [x] SubTask 4.4: 在 `sys/task_runner.cpp` 的 `taskDiagnosticPrint()` 中增加 EtherCAT ISR 执行时间输出(受 `#if CONFIG_ETHERCAT_ENABLE` 保护),格式 `periodicIsr max=Xus avg=Yus`(cycles / 180 转 µs)
+  - [x] SubTask 4.5: 在 `sys/config.h` 增加 `CONFIG_ETHERCAT_ISR_MAX_US_THRESHOLD 5U` 宏,作为评估阈值
+  - [x] SubTask 4.6: 在 spec.md 与代码注释中记录:若实测 > 5µs 需评估减小 `CONFIG_ETHERCAT_PDO_SIZE` 或优化 EXMC 时序;若 ≤ 5µs 则接受现状并在注释中说明"preempt=0 阻塞窗口 ≤ 5µs,CAN/SPI 需容忍"
+
+- [x] Task 5: 阶段 E — .ramfunc 段落地与调用链 RAM 化(修复高风险 #6)
+  - [x] SubTask 5.1: 定位项目链接脚本文件(查找 `*.sct` 或 RTE 配置中的 linker script)
+  - [x] SubTask 5.2: 在链接脚本中新增 `.ramfunc` 输出段,执行区(VMA)位于 SRAM,加载区(LMA)位于 Flash(参考 `.data` 段的 scatter 语法)
+  - [x] SubTask 5.3: 确认启动代码(`startup_gd32e50x_cl.s` 或 `system_gd32e50x.c`)是否自动拷贝 `.ramfunc` 段;若否,增加拷贝逻辑(类似 `.data` 拷贝循环)
+  - [x] SubTask 5.4: 在 `comm/ethercat_slave.cpp` 的 `periodicIsr()` 已有 `__attribute__((section(".ramfunc")))` 基础上增加 `noinline` 属性
+  - [x] SubTask 5.5: 在 `comm/esc_lan9252.cpp` 的 `readPdi()` / `writePdi()` 增加 `__attribute__((section(".ramfunc"), noinline))`
+  - [x] SubTask 5.6: 在 `comm/esc_exmc_bus.cpp` 的 `read16()` / `write16()` 增加 `__attribute__((section(".ramfunc"), noinline))`(注意:`readBlock/writeBlock` 不在 ISR 调用链,不标记)
+  - [ ] SubTask 5.7: 编译后查看 map 文件,确认 `.ramfunc` 段的 VMA 在 SRAM 区域、LMA 在 Flash 区域
+  - [x] SubTask 5.8: 若 DWT 测量(阶段 D)显示 Flash 执行已满足 <1µs 抖动,可在 spec 中记录降级方案(仅 periodicIsr 本体 RAM 化),但默认按完整 RAM 化实施
+
+- [ ] Task 6: 编译验证与回退(⚠️ 受阻于预存 EXMC 组件解析问题)
+  - [ ] SubTask 6.1: 临时将 `sys/config.h` 中 `CONFIG_ETHERCAT_ENABLE` 改为 1,全量编译通过,无 error
+  - [ ] SubTask 6.2: 检查无新增 warning(特别注意 `.ramfunc` 段未定义或未拷贝的链接警告)
+  - [ ] SubTask 6.3: 查看 map 文件确认 `.ramfunc` 段在 SRAM、`s_inputs[3]`/`s_outputs[3]` 在 SRAM、`s_periodicSeq` 在 SRAM
+  - [x] SubTask 6.4: 编译验证完成后将 `CONFIG_ETHERCAT_ENABLE` 恢复为 0
+  - [ ] SubTask 6.5: 确认 `CONFIG_ETHERCAT_ENABLE=0` 时全量编译仍通过,功能与改造前等价
+  - [ ] SubTask 6.6: ⚠️ 阻塞项:`GD32E508_DCU_APP.cproject.yml` 第 68 行无条件引用 `Device:GD32E50x_StdPeripherals:EXMC` 组件,但已安装的 GD32E50x_DFP pack(1.9.0/1.3.2)pdsc 未注册 EXMC 组件,导致 csolution 组件解析失败,ENABLE=0 与 ENABLE=1 均无法构建。EXMC 驱动源文件(`gd32e50x_exmc.h/.c`)实际存在于 pack 中。需单独修复 cproject.yml(改为直接引用源文件)或更新 pack 后重新执行本任务
+
+# Task Dependencies
+- Task 1, 2, 3 相互独立,可并行实施(均集中在 `comm/` 目录,但修改不同函数与成员)
+- Task 4 依赖 Task 1(periodicIsr 改造完成才能测量)
+- Task 5 依赖 Task 1, 2, 3(调用链 RAM 化需在接口稳定后)
+- Task 6 依赖 Task 1-5 全部完成
@@ -1,4 +1,4 @@
-# A project translates into one executable or library.
+# A project translates into one executable or library.
 project:

  groups:
@@ -44,6 +44,8 @@ project:
        - file: ./device/spi/app_spi_cmd_ota_wait.cpp
        - file: ./device/spi/app_spi_cmd_ping.cpp
        - file: ./device/spi/app_spi_cmd_can_bridge.cpp
+        - file: ./device/spi/app_spi_cmd_can_feedback.cpp
+        - file: ./device/spi/app_spi_cmd_id_snapshot.cpp
    - group: comm
      files:
        - file: ./comm/esc_exmc_bus.h
@@ -65,7 +67,6 @@ project:
    - component: Device:GD32E50x_StdPeripherals:CRC
    - component: Device:GD32E50x_StdPeripherals:DBG
    - component: Device:GD32E50x_StdPeripherals:DMA
-    - component: Device:GD32E50x_StdPeripherals:EXMC
    - component: Device:GD32E50x_StdPeripherals:EXTI
    - component: Device:GD32E50x_StdPeripherals:FMC
    - component: Device:GD32E50x_StdPeripherals:GPIO
@@ -34,7 +34,11 @@ LR_ROM0 __ROM0_BASE __ROM0_SIZE  {
  ER_ROM0 __ROM0_BASE __ROM0_SIZE {
    *.o (RESET, +First)
    *(InRoot$$Sections)
-    *(+RO +XO)
+    ; 用 .ANY (+RO +XO) 兜底所有 RO 段,而非 *(+RO +XO) 属性通配符。
+    ; 原因:*(+RO) 与 RW_RAM0 的 *(.ramfunc*) 跨执行区会产生 L6223E 歧义;
+    ; 而 .ANY 优先级低于 *(.ramfunc*),armlink 先把 .ramfunc 分配给 RW_RAM0,
+    ; 剩余 RO 段再由 .ANY 兜底到 ER_ROM0,既无歧义又零丢弃(不依赖段名枚举)。
+    .ANY (+RO +XO)
  }

 #if defined (__ARM_FEATURE_CMSE) && (__ARM_FEATURE_CMSE == 3U)
@@ -49,6 +53,9 @@ LR_ROM0 __ROM0_BASE __ROM0_SIZE  {
  }

  RW_RAM0 AlignExpr(+0, 8) (__RAM0_SIZE - __HEAP_SIZE - __STACK_SIZE - __STACKSEAL_SIZE - AlignExpr(ImageLength(RW_NOINIT), 8)) {
+    ; RAM 函数段:VMA 在 SRAM、LMA 在 Flash,由 C 库 __main scatter-load 自动从 Flash 拷贝到 RAM。
+    ; 用于 EtherCAT ISR 调用链(periodicIsr/readPdi/writePdi/read16/write16),消除 Flash 等待周期抖动。
+    *(.ramfunc*)
    *(+RW +ZI)
  }

@@ -5,8 +5,6 @@
 #include "comm/esc_exmc_bus.h"
 #include "sys/config.h"

-#if CONFIG_ETHERCAT_ENABLE
-
 extern "C" {
 #include "gd32e50x_rcu.h"
 #include "gd32e50x_gpio.h"
@@ -68,32 +66,18 @@ void EscExmcBus::init()
    exmc_norsram_init(&norsram_init);
    exmc_norsram_enable(CONFIG_ESC_EXMC_BANK_NOR_SRAM_REGION1);
 #else
-    /* EXMC 外设库未安装:仅占位,CONFIG_ETHERCAT_ENABLE=1 时需先安装 EXMC 组件。 */
+    /* EXMC 外设库未安装:仅占位,启用 EtherCAT 时需先安装 EXMC 组件。 */
 #endif
 }

+__attribute__((section(".ramfunc"), noinline))
 uint16_t EscExmcBus::read16(uint32_t offset)
 {
    return ESC_EXMC_REG16(offset);
 }

+__attribute__((section(".ramfunc"), noinline))
 void EscExmcBus::write16(uint32_t offset, uint16_t data)
 {
    ESC_EXMC_REG16(offset) = data;
 }
-
-void EscExmcBus::readBlock(uint32_t offset, uint16_t *buf, size_t count)
-{
-    for (size_t i = 0U; i < count; ++i) {
-        buf[i] = ESC_EXMC_REG16(offset + (uint32_t)(i * 2U));
-    }
-}
-
-void EscExmcBus::writeBlock(uint32_t offset, const uint16_t *buf, size_t count)
-{
-    for (size_t i = 0U; i < count; ++i) {
-        ESC_EXMC_REG16(offset + (uint32_t)(i * 2U)) = buf[i];
-    }
-}
-
-#endif /* CONFIG_ETHERCAT_ENABLE */
@@ -19,35 +19,11 @@ public:
    /** @brief 初始化 EXMC NOR/SRAM Region1 与全部 GPIO(AF 复用)。 */
    static void init();

-    /**
-     * @brief 从指定偏移读取 16-bit 数据。
-     * @param[in] offset 地址偏移(字节)。
-     * @return uint16_t 读取的 16-bit 数据。
-     */
+    /** @brief ISR-only:仅供 preempt=0 调用,无锁。 */
    static uint16_t read16(uint32_t offset);

-    /**
-     * @brief 向指定偏移写入 16-bit 数据。
-     * @param[in] offset 地址偏移(字节)。
-     * @param[in] data  待写入的 16-bit 数据。
-     */
+    /** @brief ISR-only:仅供 preempt=0 调用,无锁。 */
    static void write16(uint32_t offset, uint16_t data);
-
-    /**
-     * @brief 从指定偏移连续读取一块 16-bit 数据。
-     * @param[in]  offset 地址偏移(字节)。
-     * @param[out] buf    输出缓冲(以 uint16_t 为单位)。
-     * @param[in]  count  读取的 16-bit 半字数量。
-     */
-    static void readBlock(uint32_t offset, uint16_t *buf, size_t count);
-
-    /**
-     * @brief 向指定偏移连续写入一块 16-bit 数据。
-     * @param[in] offset 地址偏移(字节)。
-     * @param[in] buf    数据缓冲(以 uint16_t 为单位)。
-     * @param[in] count  写入的 16-bit 半字数量。
-     */
-    static void writeBlock(uint32_t offset, const uint16_t *buf, size_t count);
 };

 #endif /* COMM_ESC_EXMC_BUS_H */
@@ -5,8 +5,8 @@
 #include "comm/esc_lan9252.h"
 #include "comm/esc_exmc_bus.h"
 #include "sys/config.h"
-
-#if CONFIG_ETHERCAT_ENABLE
+#include "RTE_Components.h"
+#include CMSIS_device_header

 namespace {
 /* LAN9252 ESC 关键寄存器地址(字节偏移,EXMC 访问) */
@@ -20,16 +20,55 @@ constexpr uint16_t LAN9252_PDI_BASE_OFFSET = 0x1000U;

 void EscLan9252::init()
 {
+    /* 使能 DWT 周期计数器,供 periodicIsr 执行时间测量 */
+    CoreDebug->DEMCR |= CoreDebug_DEMCR_TRCENA_Msk;
+    DWT->CYCCNT = 0U;
+    DWT->CTRL |= DWT_CTRL_CYCCNTENA_Msk;
+
    EscExmcBus::init();
-    /* TODO: 配置 ESC 中断使能、AL 控制等基本寄存器(留待协议栈集成阶段实现) */
+
+    /* ============================================================
+     * TODO: 完整 ESC 寄存器配置(需 SSC 或等价协议栈代码,本 spec 不实现)
+     * ============================================================
+     * 当前仅完成 EXMC 总线初始化与芯片 ID 读取。要使 SYNC0 实际触发,还需配置:
+     *
+     * 1. SyncManager(SM)初始化:
+     *    - SM0/SM1:邮箱输入/输出(IN/OUT),地址 0x0520-0x0530
+     *    - SM2:TxPDO(输入),地址 0x0530,配置为 3-buffer 模式
+     *    - SM3:RxPDO(输出),地址 0x0540,配置为 3-buffer 模式
+     *    - 各 SM 的 StartAddr/Length/Control/Status/Activate 寄存器
+     *
+     * 2. FMMU(Fieldbus Memory Mapping Unit)配置:
+     *    - FMMU0:TxPDO 映射(逻辑地址 → 物理地址,读)
+     *    - FMMU1:RxPDO 映射(逻辑地址 → 物理地址,写)
+     *    - 地址 0x0580-0x0590
+     *
+     * 3. AL Control(0x0120):写入 0x08 请求 OP 状态(需主站配合完成状态迁移)
+     *
+     * 4. SYNC0 生成寄存器:
+     *    - 0x0981-0x0982:SYNC0 周期(cycle time,单位 ns)
+     *    - 0x0983:SYNC0 脉冲长度
+     *    - 0x0984:SYNC0 控制(使能/触发模式)
+     *    - 需主站 DC 同步后由 ESC 自动生成 SYNC0 脉冲
+     *
+     * 这些步骤通常由 EtherCAT SSC(Slave Stack Code)或等价协议栈代码完成,
+     * 涉及 AL 状态机管理、邮箱通信、PDO 映射协商等复杂逻辑。
+     * 本 spec 仅通过 EthercatSlave::isEscReady() 的 AL 状态守卫使
+     * "SYNC0 不会触发"在运行期可观测,完整配置留待 SSC 集成 spec。
+     * ============================================================ */
 }

 bool EscLan9252::selfTest()
 {
-    const uint16_t id_low  = readReg(LAN9252_REG_CHIP_ID_L);
-    const uint16_t id_high = readReg(LAN9252_REG_CHIP_ID_H);
-    const uint32_t chip_id = ((uint32_t)id_high << 16) | id_low;
-    return (chip_id == LAN9252_CHIP_ID_VALUE);
+    return (readChipId() == LAN9252_CHIP_ID_VALUE);
+}
+
+uint32_t EscLan9252::readChipId()
+{
+    /* INIT-ONLY:init 阶段中断未使能,但仍走 initOnly 路径保持一致性 */
+    const uint16_t id_low  = initOnlyReadReg(LAN9252_REG_CHIP_ID_L);
+    const uint16_t id_high = initOnlyReadReg(LAN9252_REG_CHIP_ID_H);
+    return ((uint32_t)id_high << 16) | id_low;
 }

 uint16_t EscLan9252::readReg(uint16_t addr)
@@ -43,6 +82,7 @@ void EscLan9252::writeReg(uint16_t addr, uint16_t val)
    EscExmcBus::write16((uint32_t)addr << 1U, val);
 }

+__attribute__((section(".ramfunc"), noinline))
 void EscLan9252::readPdi(uint16_t offset, uint8_t *buf, size_t len)
 {
    if (buf == nullptr || len == 0U) {
@@ -63,6 +103,7 @@ void EscLan9252::readPdi(uint16_t offset, uint8_t *buf, size_t len)
    }
 }

+__attribute__((section(".ramfunc"), noinline))
 void EscLan9252::writePdi(uint16_t offset, const uint8_t *buf, size_t len)
 {
    if (buf == nullptr || len == 0U) {
@@ -79,4 +120,25 @@ void EscLan9252::writePdi(uint16_t offset, const uint8_t *buf, size_t len)
    }
 }

-#endif /* CONFIG_ETHERCAT_ENABLE */
+/* ---- initOnly* 接口:INIT-ONLY,仅允许在 EthercatSync::init() 使能 EXTI NVIC 之前调用 ----
+ * 运行期禁止调用;需 ESC 寄存器访问须通过 SYNC0 ISR 代访队列(本 spec 不涵盖)。
+ * 注:不再使用 PRIMASK 关中断(违反项目硬约束"Critical sections MUST use BASEPRI")。 */
+uint16_t EscLan9252::initOnlyReadReg(uint16_t addr)
+{
+    return readReg(addr);
+}
+
+void EscLan9252::initOnlyWriteReg(uint16_t addr, uint16_t val)
+{
+    writeReg(addr, val);
+}
+
+void EscLan9252::initOnlyReadPdi(uint16_t offset, uint8_t *buf, size_t len)
+{
+    readPdi(offset, buf, len);
+}
+
+void EscLan9252::initOnlyWritePdi(uint16_t offset, const uint8_t *buf, size_t len)
+{
+    writePdi(offset, buf, len);
+}
@@ -2,6 +2,12 @@
 * @file esc_lan9252.h
 * @brief LAN9252 EtherCAT 从站控制器(ESC)驱动接口。
 * @note 通过 EscExmcBus 16-bit 并行总线访问 LAN9252 寄存器与 PDI 内存。
+ *
+ *       接口调用约束(避免 EXMC 总线争用):
+ *       - readReg/writeReg/readPdi/writePdi:ISR-only,仅供 preempt=0 的 periodicIsr() 调用,无锁。
+ *       - initOnlyReadReg/initOnlyWriteReg/initOnlyReadPdi/initOnlyWritePdi:INIT-ONLY,仅允许在 EthercatSync::init() 使能 EXTI NVIC 之前调用;运行期禁止调用,需 ESC 寄存器访问须通过 SYNC0 ISR 代访队列(本 spec 不涵盖)。
+ *
+ *       PDI offset 语义:offset 参数为 SyncManager 内存区相对偏移,输入 PDO(TxPDO)与输出 PDO(RxPDO)必须使用不同 offset,参见 CONFIG_ESC_PDI_INPUT_OFFSET / CONFIG_ESC_PDI_OUTPUT_OFFSET。
 */
 #ifndef COMM_ESC_LAN9252_H
 #define COMM_ESC_LAN9252_H
@@ -25,34 +31,34 @@ public:
    static bool selfTest();

    /**
-     * @brief 读取 ESC 寄存器(16-bit)。
-     * @param[in] addr 寄存器地址(ESC 寄存器空间偏移)。
-     * @return uint16_t 寄存器值。
+     * @brief 读取 ESC 芯片 ID(INIT-ONLY,供 init 打印诊断用)。
+     * @return uint32_t 32-bit 芯片 ID(期望值 0x87654321)。
     */
+    static uint32_t readChipId();
+
+    /** @brief ISR-only:仅供 preempt=0 的 periodicIsr() 调用,无锁。主循环必须用 initOnly 版本。 */
    static uint16_t readReg(uint16_t addr);

-    /**
-     * @brief 写入 ESC 寄存器(16-bit)。
-     * @param[in] addr 寄存器地址。
-     * @param[in] val  待写入值。
-     */
+    /** @brief ISR-only:仅供 preempt=0 的 periodicIsr() 调用,无锁。主循环必须用 initOnly 版本。 */
    static void writeReg(uint16_t addr, uint16_t val);

-    /**
-     * @brief 从 PDI 内存读取一块数据。
-     * @param[in]  offset PDI 偏移(字节)。
-     * @param[out] buf    输出缓冲。
-     * @param[in]  len    读取字节数。
-     */
+    /** @brief ISR-only:仅供 preempt=0 的 periodicIsr() 调用,无锁。主循环必须用 initOnly 版本。 */
    static void readPdi(uint16_t offset, uint8_t *buf, size_t len);

-    /**
-     * @brief 向 PDI 内存写入一块数据。
-     * @param[in] offset PDI 偏移(字节)。
-     * @param[in] buf    数据缓冲。
-     * @param[in] len    写入字节数。
-     */
+    /** @brief ISR-only:仅供 preempt=0 的 periodicIsr() 调用,无锁。主循环必须用 initOnly 版本。 */
    static void writePdi(uint16_t offset, const uint8_t *buf, size_t len);
+
+    /** @brief INIT-ONLY:仅允许在 EthercatSync::init() 使能 EXTI NVIC 之前调用;运行期禁止调用,需 ESC 寄存器访问须通过 SYNC0 ISR 代访队列(本 spec 不涵盖)。 */
+    static uint16_t initOnlyReadReg(uint16_t addr);
+
+    /** @brief INIT-ONLY:仅允许在 EthercatSync::init() 使能 EXTI NVIC 之前调用;运行期禁止调用,需 ESC 寄存器访问须通过 SYNC0 ISR 代访队列(本 spec 不涵盖)。 */
+    static void initOnlyWriteReg(uint16_t addr, uint16_t val);
+
+    /** @brief INIT-ONLY:仅允许在 EthercatSync::init() 使能 EXTI NVIC 之前调用;运行期禁止调用,需 ESC 寄存器访问须通过 SYNC0 ISR 代访队列(本 spec 不涵盖)。 */
+    static void initOnlyReadPdi(uint16_t offset, uint8_t *buf, size_t len);
+
+    /** @brief INIT-ONLY:仅允许在 EthercatSync::init() 使能 EXTI NVIC 之前调用;运行期禁止调用,需 ESC 寄存器访问须通过 SYNC0 ISR 代访队列(本 spec 不涵盖)。 */
+    static void initOnlyWritePdi(uint16_t offset, const uint8_t *buf, size_t len);
 };

 #endif /* COMM_ESC_LAN9252_H */
@@ -8,46 +8,92 @@
 #include "sys/task_manager.h"
 #include "main.h"

-#if CONFIG_ETHERCAT_ENABLE
+PdoBuffer EthercatSlave::s_inputs[3] = {};
+PdoBuffer EthercatSlave::s_outputs[3] = {};
+PdoBuffer EthercatSlave::s_appInputs = {};
+PdoBuffer EthercatSlave::s_appOutputs = {};
+volatile uint8_t EthercatSlave::s_inputWriteIdx = 0U;
+volatile uint8_t EthercatSlave::s_outputReadIdx = 0U;
+volatile uint16_t EthercatSlave::s_periodicSeq = 0U;
+uint16_t EthercatSlave::s_processedSeq = 0U;
+volatile uint32_t EthercatSlave::s_isrMaxCycles = 0U;
+volatile uint32_t EthercatSlave::s_isrAvgCycles = 0U;
+volatile uint32_t EthercatSlave::s_isrCount = 0U;
+bool EthercatSlave::s_escReady = false;
+uint32_t EthercatSlave::s_chipId = 0U;
+uint8_t EthercatSlave::s_alState = 0U;

-PdoBuffer EthercatSlave::s_inputs[2] = {};
-PdoBuffer EthercatSlave::s_outputs[2] = {};
-volatile uint8_t EthercatSlave::s_inputReadIndex = 0U;
-volatile uint8_t EthercatSlave::s_outputWriteIndex = 0U;
+/* ISR 执行时间评估:
+ * - 若 DWT 实测 max > CONFIG_ETHERCAT_ISR_MAX_US_THRESHOLD(5µs),需评估:
+ *   a) 减小 CONFIG_ETHERCAT_PDO_SIZE(默认 32 字节)
+ *   b) 优化 EXMC 时序参数(esc_exmc_bus.cpp 中 read_latency/write_latency)
+ * - 若 max ≤ 5µs,接受现状;preempt=0 阻塞窗口 ≤ 5µs,CAN/SPI 中断需容忍此窗口。
+ *   SPI0 从机在此窗口内不会 RX 溢出(假设 SPI 时钟 ≤ 10MHz,5µs ≥ 50 bit,远小于一帧)。 */

 void EthercatSlave::init()
 {
    EscLan9252::init();
-    if (EscLan9252::selfTest()) {
-        /* ESC 自检通过:TODO 启用周期同步 */
+
+    /* 第 1 层调试可观测性:读取芯片 ID 并打印 selfTest 结果 */
+    s_chipId = EscLan9252::readChipId();
+    const bool chipIdOk = (s_chipId == 0x87654321U);
+
+    /* AL 状态守卫:仅在芯片 ID 匹配时读取 AL 状态(ID 不匹配时 EXMC 可能读回 0/0xFFFF,无意义)。
+     * AL ≥ SAFEOP(0x04) 才认为 SYNC0 可触发;完整 ESC 配置(SM/FMMU/AL Control/SYNC0)需 SSC 集成。 */
+    s_alState = 0U;
+    if (chipIdOk) {
+        s_alState = (uint8_t)(EscLan9252::initOnlyReadReg(0x0130U) & 0x000FU);
    }
-    s_inputReadIndex = 0U;
-    s_outputWriteIndex = 0U;
+    s_escReady = chipIdOk && (s_alState >= AL_STATE_SAFEOP);
+
+    if (!chipIdOk) {
+        printf("[ECAT] ESC chip id=0x%08lX selfTest=FAIL\r\n", (unsigned long)s_chipId);
+        printf("[ECAT] ESC NOT ready, sync ISR disabled (check EXMC wiring/timing)\r\n");
+    } else if (s_alState < AL_STATE_SAFEOP) {
+        printf("[ECAT] ESC chip id=0x%08lX selfTest=PASS, but AL state=0x%02X < SAFEOP(0x%02X)\r\n",
+               (unsigned long)s_chipId, (unsigned)s_alState, (unsigned)AL_STATE_SAFEOP);
+        printf("[ECAT] SYNC0 will not fire, full ESC config requires SSC integration\r\n");
+    } else {
+        printf("[ECAT] ESC ready, chip id=0x%08lX, AL state=0x%02X\r\n",
+               (unsigned long)s_chipId, (unsigned)s_alState);
+    }
+
+    s_inputWriteIdx = 0U;
+    s_outputReadIdx = 0U;
+    s_periodicSeq = 0U;
+    s_processedSeq = 0U;
 }

-__attribute__((section(".ramfunc")))
+__attribute__((section(".ramfunc"), noinline))
 void EthercatSlave::periodicIsr()
 {
-    /* 1. 读取输入 PDO 到另一块缓冲(当前可读缓冲的配对) */
-    const uint8_t write_idx = s_inputReadIndex ^ 1U;
-    EscLan9252::readPdi(0x0000U, s_inputs[write_idx].data, CONFIG_ETHERCAT_PDO_SIZE);
-    s_inputs[write_idx].len = CONFIG_ETHERCAT_PDO_SIZE;
+    const uint32_t cycStart = DWT->CYCCNT;

-    /* 2. 写入输出 PDO(从应用层未写入的那个缓冲读取) */
-    const uint8_t out_read_idx = s_outputWriteIndex ^ 1U;
-    EscLan9252::writePdi(0x0000U, s_outputs[out_read_idx].data, s_outputs[out_read_idx].len);
+    /* 1. 读取输入 PDO 到当前写入缓冲 */
+    EscLan9252::readPdi(CONFIG_ESC_PDI_INPUT_OFFSET, s_inputs[s_inputWriteIdx].data, CONFIG_ETHERCAT_PDO_SIZE);
+    s_inputs[s_inputWriteIdx].len = CONFIG_ETHERCAT_PDO_SIZE;
+    s_inputWriteIdx = (s_inputWriteIdx + 1U) % 3U;

-    /* 3. 翻转输入缓冲指针,使新完成的缓冲成为可读缓冲 */
-    s_inputReadIndex = write_idx;
+    /* 2. 写入输出 PDO(从当前读取缓冲) */
+    EscLan9252::writePdi(CONFIG_ESC_PDI_OUTPUT_OFFSET, s_outputs[s_outputReadIdx].data, s_outputs[s_outputReadIdx].len);
+    s_outputReadIdx = (s_outputReadIdx + 1U) % 3U;

-    /* 4. 置位非实时任务,通知主循环处理应用层 PDO 映射 */
-    TaskManager::set(1UL << TASK_ETHERCAT_PROCESS);
+    /* 3. 递增周期序列号通知主循环(替代 TaskManager::set,避免 BASEPRI 竞态) */
+    s_periodicSeq++;
+
+    const uint32_t elapsed = DWT->CYCCNT - cycStart;
+    s_isrCount++;
+    if (elapsed > s_isrMaxCycles) {
+        s_isrMaxCycles = elapsed;
+    }
+    /* 滑动平均:avg = avg + (elapsed - avg) / 16 (近似 EMA,避免除法精度问题) */
+    s_isrAvgCycles = s_isrAvgCycles + ((int32_t)elapsed - (int32_t)s_isrAvgCycles) / 16;
 }

 const PdoBuffer* EthercatSlave::getLatestInputs()
 {
-    /* s_inputReadIndex 始终指向最新完成的输入缓冲 */
-    return &s_inputs[s_inputReadIndex];
+    /* 返回最新完成的缓冲 = (writeIdx + 2) % 3,与 ISR 当前写入位置隔一个 */
+    return &s_inputs[(s_inputWriteIdx + 2U) % 3U];
 }

 void EthercatSlave::setOutputs(const PdoBuffer *outputs)
@@ -55,16 +101,53 @@ void EthercatSlave::setOutputs(const PdoBuffer *outputs)
    if (outputs == nullptr) {
        return;
    }
-    /* 写入应用层缓冲(ISR 当前不读取的那个) */
-    const uint8_t write_idx = s_outputWriteIndex ^ 1U;
+    /* 写入与 ISR 当前读取位置隔 2 个缓冲,提供 2 周期宽限。
+     * 2 周期宽限下拷贝竞态窗口消除,前提是主循环处理时间 < 2 × 周期时间。 */
+    const uint8_t write_idx = (s_outputReadIdx + 2U) % 3U;
    s_outputs[write_idx] = *outputs;
-    s_outputWriteIndex = write_idx;
 }

 void EthercatSlave::process()
 {
-    /* 应用层 PDO 映射入口(非实时,由主循环 TASK_ETHERCAT_PROCESS 调用)。
-     * TODO: 将 getLatestInputs() 数据映射到应用对象字典;将应用输出填入 setOutputs()。 */
+    /* 应用层 PDO 桥接(非实时,由主循环周期序列号或 ESC IRQ 触发)。
+     * 运行期 PDO 交换仅通过 getLatestInputs()/setOutputs() 三缓冲进行;ESC 寄存器访问仅限 init 阶段。
+     *
+     * 框架级桥接:从三缓冲取最新输入到 s_appInputs,把 s_appOutputs 推回三缓冲。
+     * TODO: 应用对象字典映射(具体输入字节对应哪个应用变量,如字节 0-3=温度浮点),
+     *       由后续应用层 spec 定义;应用层通过 getApplicationInputs()/setApplicationOutputs() 访问快照。 */
+    const PdoBuffer *latest = getLatestInputs();
+    if (latest != nullptr) {
+        s_appInputs = *latest;
+    }
+    setOutputs(&s_appOutputs);
 }

-#endif /* CONFIG_ETHERCAT_ENABLE */
+const PdoBuffer* EthercatSlave::getApplicationInputs()
+{
+    return &s_appInputs;
+}
+
+void EthercatSlave::setApplicationOutputs(const PdoBuffer *outputs)
+{
+    if (outputs == nullptr) {
+        return;
+    }
+    s_appOutputs = *outputs;
+}
+
+bool EthercatSlave::hasPendingPeriodic()
+{
+    return s_periodicSeq != s_processedSeq;
+}
+
+void EthercatSlave::markPeriodicProcessed()
+{
+    s_processedSeq = s_periodicSeq;
+}
+
+void EthercatSlave::getIsrStats(uint32_t *maxCycles, uint32_t *avgCycles, uint32_t *count)
+{
+    if (maxCycles) *maxCycles = s_isrMaxCycles;
+    if (avgCycles) *avgCycles = s_isrAvgCycles;
+    if (count)     *count     = s_isrCount;
+}
@@ -1,8 +1,13 @@
 /**
 * @file ethercat_slave.h
- * @brief EtherCAT 从站周期处理接口与 PDO 双缓冲(ping-pong)结构。
+ * @brief EtherCAT 从站周期处理接口与 PDO 三缓冲(triple buffer)结构。
 * @note 周期 ISR 调用 periodicIsr() 完成输入 PDO 读取 + 输出 PDO 写入;
 *       应用层通过 getLatestInputs()/setOutputs() 与周期路径无锁交换数据。
+ *
+ *       通知路径分离:
+ *       周期路径(periodicIsr)用 s_periodicSeq 序列号通知主循环;
+ *       事件路径(ESC IRQ)用 TASK_ETHERCAT_PROCESS 标志。
+ *       两者独立,避免 preempt=0 ISR 与 BASEPRI 临界区的 RMW 竞态。
 */
 #ifndef COMM_ETHERCAT_SLAVE_H
 #define COMM_ETHERCAT_SLAVE_H
@@ -13,9 +18,16 @@
 /** @brief 默认 PDO 大小(可按需调整)。 */
 constexpr size_t CONFIG_ETHERCAT_PDO_SIZE = 32U;

+/** @brief EtherCAT AL 状态码(EtherCAT 协议定义,ESC AL Status 寄存器低 4 位)。 */
+constexpr uint8_t AL_STATE_INIT    = 0x01U;  /**< INIT 状态。 */
+constexpr uint8_t AL_STATE_PREOP   = 0x02U;  /**< PREOP 状态。 */
+constexpr uint8_t AL_STATE_BOOT    = 0x03U;  /**< BOOT 状态。 */
+constexpr uint8_t AL_STATE_SAFEOP  = 0x04U;  /**< SAFEOP 状态(SYNC0 可触发下限)。 */
+constexpr uint8_t AL_STATE_OP      = 0x08U;  /**< OP 状态。 */
+
 /**
 * @brief PDO 数据缓冲(输入/输出共用结构)。
- * @note 周期 ISR 与应用层通过双缓冲无锁交换。
+ * @note 周期 ISR 与应用层通过三缓冲无锁交换。
 */
 struct PdoBuffer {
    uint8_t  data[CONFIG_ETHERCAT_PDO_SIZE] = {0}; /**< 数据载荷。 */
@@ -24,44 +36,111 @@ struct PdoBuffer {

 /**
 * @brief EtherCAT 从站周期处理。
- * @note 周期路径(periodicIsr)必须极简:读输入→写输出→翻转指针→置位任务。
+ * @note 周期路径(periodicIsr)必须极简:读输入→写输出→模 3 轮转指针→递增序列号。
 */
 class EthercatSlave {
 public:
-    /** @brief 初始化 ESC 与双缓冲。 */
+    /** @brief 初始化 ESC 与三缓冲。 */
    static void init();

    /**
     * @brief 周期中断处理(由 SYNC0 EXTI 触发)。
     * @note 放入 RAM 执行段(.ramfunc)以降低 Flash 等待带来的抖动。
-     *       流程:读输入 PDO → 写输出 PDO → 翻转输入缓冲指针 → 置位 TASK_ETHERCAT_PROCESS。
+     *       流程:读输入 PDO → 写输出 PDO → 模 3 轮转索引 → 递增 s_periodicSeq。
+     *       不再调用 TaskManager::set,避免 preempt=0 与 BASEPRI 临界区的 RMW 竞态。
     */
    static void periodicIsr();

    /**
     * @brief 获取最新输入 PDO(主循环调用,无锁)。
-     * @return const PdoBuffer* 最新输入缓冲只读指针;周期 ISR 不会修改该缓冲。
+     * @return const PdoBuffer* 最新输入缓冲只读指针;返回与 ISR 当前写入位置隔一个的缓冲。
+     * @note 三缓冲容忍主循环跨 1 个周期,主循环处理必须 < 2 × 周期时间。
     */
    static const PdoBuffer* getLatestInputs();

    /**
     * @brief 设置下次周期要发送的输出 PDO(主循环调用)。
     * @param[in] outputs 输出数据指针(内容会被拷贝到内部输出缓冲)。
-     * @note 调用方在 ISR 不持有期间调用即可,内部使用乒乓缓冲避免竞争。
+     * @note 写入与 ISR 当前读取位置隔一个的缓冲,无需任何临界区。
     */
    static void setOutputs(const PdoBuffer *outputs);

    /**
-     * @brief 应用层 PDO 映射入口(非实时,由 TASK_ETHERCAT_PROCESS 调用)。
+     * @brief 应用层 PDO 映射入口(非实时,由 TASK_ETHERCAT_PROCESS 或周期序列号触发)。
     * @note 留接口,具体映射逻辑由协议栈后续实现。
     */
    static void process();

+    /**
+     * @brief 获取应用层输入 PDO 快照(主循环调用)。
+     * @return const PdoBuffer* 最近一次 process() 拷贝的输入快照只读指针。
+     * @note 返回的指针在下次 process() 调用前有效;应用层应在 process() 后立即读取。
+     */
+    static const PdoBuffer* getApplicationInputs();
+
+    /**
+     * @brief 设置应用层输出 PDO 快照(主循环调用)。
+     * @param[in] outputs 输出数据指针(内容会被拷贝到内部快照)。
+     * @note 下次 process() 调用时,内部快照通过 setOutputs() 推入三缓冲。
+     */
+    static void setApplicationOutputs(const PdoBuffer *outputs);
+
+    /**
+     * @brief 检查是否有新的周期数据待主循环处理。
+     * @return bool true 表示 s_periodicSeq 与已处理序号不同。
+     * @note 主循环 runPending() 优先调用此接口,替代原 TASK_ETHERCAT_PROCESS 周期路径。
+     */
+    static bool hasPendingPeriodic();
+
+    /**
+     * @brief 标记当前周期数据已被主循环处理。
+     * @note 调用此接口前应已调用 taskEthercatProcess() 完成本次 PDO 映射。
+     */
+    static void markPeriodicProcessed();
+
+    /** @brief 读取 ISR 执行时间诊断(max/avg 单位:CPU 周期数,除以 180 得 µs)。 */
+    static void getIsrStats(uint32_t *maxCycles, uint32_t *avgCycles, uint32_t *count);
+
+    /** @brief ESC 自检是否通过(init 后可查询,用于决定是否使能同步中断)。 */
+    static bool isEscReady() { return s_escReady; }
+
+    /** @brief 读取 ESC 芯片 ID(供诊断打印;未就绪时为上次读到的值)。 */
+    static uint32_t getChipId() { return s_chipId; }
+
+    /** @brief 读取 ESC AL 状态码(供诊断打印与 SSC 集成;未就绪时为上次读到的值)。 */
+    static uint8_t getAlState() { return s_alState; }
+
 private:
-    static PdoBuffer s_inputs[2];        /**< 输入双缓冲(pong-pong)。 */
-    static PdoBuffer s_outputs[2];       /**< 输出双缓冲(ping-pong)。 */
-    static volatile uint8_t s_inputReadIndex;  /**< ISR 当前写入索引;getLatestInputs 读另一个。 */
-    static volatile uint8_t s_outputWriteIndex; /**< 应用层写入索引;ISR 读另一个。 */
+    /**
+     * @brief 输入三缓冲。
+     * ISR 按 s_inputWriteIdx 模 3 轮转写入;getLatestInputs() 读取 (writeIdx + 2) % 3。
+     */
+    static PdoBuffer s_inputs[3];
+    /**
+     * @brief 输出三缓冲。
+     * ISR 按 s_outputReadIdx 模 3 轮转读取;setOutputs() 写入 (readIdx + 2) % 3,
+     * 与 ISR 当前读取位置隔 2 个缓冲,提供 2 周期宽限消除拷贝竞态。
+     */
+    static PdoBuffer s_outputs[3];
+    /** @brief 应用层输入快照(主循环访问,process() 从三缓冲拷贝;无需三缓冲)。 */
+    static PdoBuffer s_appInputs;
+    /** @brief 应用层输出快照(主循环访问,process() 推入三缓冲;无需三缓冲)。 */
+    static PdoBuffer s_appOutputs;
+    static volatile uint8_t s_inputWriteIdx;  /**< ISR 当前写入索引;模 3 轮转。 */
+    static volatile uint8_t s_outputReadIdx;  /**< ISR 当前读取索引;模 3 轮转。 */
+
+    /** @brief 周期路径通知序列号(ISR 单字原子递增,主循环比对;uint16_t 提供 6.55s 回绕周期)。 */
+    static volatile uint16_t s_periodicSeq;
+    /** @brief 主循环已处理序号(由 hasPendingPeriodic/markPeriodicProcessed 维护)。 */
+    static uint16_t s_processedSeq;
+
+    static volatile uint32_t s_isrMaxCycles;   /**< ISR 最大执行周期数(180MHz 基准)。 */
+    static volatile uint32_t s_isrAvgCycles;   /**< ISR 平均执行周期数(滑动累计)。 */
+    static volatile uint32_t s_isrCount;       /**< ISR 执行次数计数。 */
+
+    static bool s_escReady;       /**< ESC 自检结果(init 后置位)。 */
+    static uint32_t s_chipId;     /**< ESC 芯片 ID(诊断用)。 */
+    static uint8_t s_alState;     /**< ESC AL 状态码(init 后可查询,供 isEscReady 守卫)。 */
 };

 #endif /* COMM_ETHERCAT_SLAVE_H */
@@ -8,8 +8,6 @@
 #include "sys/task_manager.h"
 #include "main.h"

-#if CONFIG_ETHERCAT_ENABLE
-
 extern "C" {
 #include "gd32e50x_rcu.h"
 #include "gd32e50x_gpio.h"
@@ -68,13 +66,29 @@ void EthercatSync::init()
    timer_interrupt_enable(TIMER0, TIMER_INT_UP);
    nvic_irq_enable(TIMER0_IRQn, CONFIG_IRQ_PREEMPT_ETHERCAT_SYNC, 0U);
    timer_enable(TIMER0);
+
+    /* ESC IRQ:PB1 -> EXTI1,下降沿,preempt=1 */
+    gpio_exti_source_select(CONFIG_ESC_IRQ_EXTI_SOURCE_PORT, CONFIG_ESC_IRQ_EXTI_SOURCE_PIN);
+    exti_init(CONFIG_ESC_IRQ_EXTI, EXTI_INTERRUPT, EXTI_TRIG_FALLING);
+    exti_interrupt_enable(CONFIG_ESC_IRQ_EXTI);
+    exti_interrupt_flag_clear(CONFIG_ESC_IRQ_EXTI);
+    nvic_irq_enable(CONFIG_ESC_IRQ_IRQn, CONFIG_IRQ_PREEMPT_ETHERCAT_ESC, 0U);
+
+    /* SYNC1:PB2 -> EXTI2,下降沿,preempt=1(备用) */
+    gpio_exti_source_select(CONFIG_ESC_SYNC1_EXTI_SOURCE_PORT, CONFIG_ESC_SYNC1_EXTI_SOURCE_PIN);
+    exti_init(CONFIG_ESC_SYNC1_EXTI, EXTI_INTERRUPT, EXTI_TRIG_FALLING);
+    exti_interrupt_enable(CONFIG_ESC_SYNC1_EXTI);
+    exti_interrupt_flag_clear(CONFIG_ESC_SYNC1_EXTI);
+    nvic_irq_enable(CONFIG_ESC_SYNC1_IRQn, CONFIG_IRQ_PREEMPT_ETHERCAT_SYNC1, 0U);
 #endif
 }

+__attribute__((section(".ramfunc"), noinline))
 void EthercatSync::onSync0Exti()
 {
-    if (exti_interrupt_flag_get(CONFIG_ESC_SYNC0_EXTI) != RESET) {
-        exti_interrupt_flag_clear(CONFIG_ESC_SYNC0_EXTI);
+    /* 直接寄存器访问,绕过 GD32 库函数以消除可变抖动 */
+    if ((EXTI_PD & (uint32_t)CONFIG_ESC_SYNC0_EXTI) != RESET) {
+        EXTI_PD = (uint32_t)CONFIG_ESC_SYNC0_EXTI;
        EthercatSlave::periodicIsr();
    }
 }
@@ -110,13 +124,14 @@ void EthercatSync::onTimerIrq()
 extern "C" {

 #if (CONFIG_ETHERCAT_SYNC_MODE == 0)
+__attribute__((section(".ramfunc"), noinline))
 void EXTI0_IRQHandler(void)  { EthercatSync::onSync0Exti(); }
 void EXTI1_IRQHandler(void)  { EthercatSync::onEscIrqExti(); }
 void EXTI2_IRQHandler(void)  { EthercatSync::onSync1Exti(); }
 #else
 void TIMER0_IRQHandler(void) { EthercatSync::onTimerIrq(); }
+void EXTI1_IRQHandler(void)  { EthercatSync::onEscIrqExti(); }
+void EXTI2_IRQHandler(void)  { EthercatSync::onSync1Exti(); }
 #endif

 } /* extern "C" */
-
-#endif /* CONFIG_ETHERCAT_ENABLE */
@@ -1,4 +1,4 @@
-/**
+/**
 * @file canfd.cpp
 * @brief CANFD 通信模块实现。
 */
@@ -8,6 +8,7 @@
 #include "sys/config.h"
 #include "sys/critical.h"
 #include "sys/task_manager.h"
+#include <cstring>

 namespace {
 struct TxFrame {
@@ -49,6 +50,11 @@ constexpr uint32_t kCanRxParseTaskMask = (1UL << TASK_CAN_RX_PARSE);
 CanFd::Diag     CanFd::s_diag{};
 CanFd::RxQueue  CanFd::s_rxQueues[3]{};
 uint8_t         CanFd::s_nextConsumeChannel = 0U;
+volatile CanFd::Mode    CanFd::s_mode = CanFd::Mode::kModeAllPass;
+CanFd::ChannelStats     CanFd::s_channelStats[3]{};
+CanFd::ChannelFeedback  CanFd::s_feedback[3]{};
+uint32_t                CanFd::s_feedbackSeq = 0U;
+CanFd::IdSnapshotTable  CanFd::s_idSnapshot[3]{};
 static TxQueue  s_txQueues[3]{};

 /**
@@ -77,20 +83,30 @@ void CanFd::initGpio()
 * @brief 为指定 CAN 控制器配置接收过滤器。
 * @param[in]  canPeriph    目标 CAN 外设实例。
 * @param[in]  filterNumber 过滤器编号。
+ * @param[in]  mode         目标接收过滤模式。
 * @param[out] 无。
 * @retval    无返回值。
- * @note      当前默认按 `CONFIG_CAN_RX_FILTER_ID`/`CONFIG_CAN_RX_FILTER_MASK` 对标准帧做掩码匹配，并统一进入 FIFO0。
+ * @note      kModeAllPass 模式下使用 32 位掩码模式且 mask=0/list=0，硬件直接放行所有标准/扩展帧到 FIFO0；
+ *            kModeFilterId 模式下按 CONFIG_CAN_RX_FILTER_ID/MASK 做标准帧掩码匹配。
 */
-void CanFd::configureRxFilter(uint32_t canPeriph, uint8_t filterNumber)
+void CanFd::configureRxFilter(uint32_t canPeriph, uint8_t filterNumber, Mode mode)
 {
    can_filter_parameter_struct can_filter{};
    can_filter.filter_number = filterNumber;
    can_filter.filter_mode = CAN_FILTERMODE_MASK;
    can_filter.filter_bits = CAN_FILTERBITS_32BIT;
-    can_filter.filter_list_high = static_cast<uint16_t>((CONFIG_CAN_RX_FILTER_ID & 0x7FFU) << 5U);
-    can_filter.filter_list_low = 0x0000U;
-    can_filter.filter_mask_high = static_cast<uint16_t>((CONFIG_CAN_RX_FILTER_MASK & 0x7FFU) << 5U);
-    can_filter.filter_mask_low = static_cast<uint16_t>(1U << 2U);
+    if (mode == Mode::kModeAllPass) {
+        /* 全部接收：列表与掩码都为 0，硬件不再对 ID 做比较。 */
+        can_filter.filter_list_high = 0x0000U;
+        can_filter.filter_list_low = 0x0000U;
+        can_filter.filter_mask_high = 0x0000U;
+        can_filter.filter_mask_low = 0x0000U;
+    } else {
+        can_filter.filter_list_high = static_cast<uint16_t>((CONFIG_CAN_RX_FILTER_ID & 0x7FFU) << 5U);
+        can_filter.filter_list_low = 0x0000U;
+        can_filter.filter_mask_high = static_cast<uint16_t>((CONFIG_CAN_RX_FILTER_MASK & 0x7FFU) << 5U);
+        can_filter.filter_mask_low = static_cast<uint16_t>(1U << 2U);
+    }
    can_filter.filter_fifo_number = CAN_FIFO0;
    can_filter.filter_enable = ENABLE;
    can_filter_init(canPeriph, &can_filter);
@@ -204,6 +220,7 @@ bool CanFd::enqueueTxFrame(uint8_t channelIndex, const StatusPayload *status)
    auto &queue = s_txQueues[channelIndex];
    if(queue.count >= kTxQueueDepth) {
        s_diag.tx_drop_count++;
+        s_channelStats[channelIndex].error_count++;
        return false;
    }

@@ -245,6 +262,12 @@ void CanFd::init()
 {
    s_diag = {};
    s_nextConsumeChannel = 0U;
+    s_mode = Mode::kModeAllPass;
+    for (size_t i = 0; i < kChannelCount; ++i) {
+        s_channelStats[i] = {};
+        s_feedback[i] = {};
+    }
+    s_feedbackSeq = 0U;

    initGpio();

@@ -255,7 +278,7 @@ void CanFd::init()
        can_deinit(ch.canPeriph);
        initNominalTiming(ch.canPeriph);
        initFdMode(ch.canPeriph);
-        configureRxFilter(ch.canPeriph, ch.filterNumber);
+        configureRxFilter(ch.canPeriph, ch.filterNumber, s_mode);
        can_interrupt_enable(ch.canPeriph, CAN_INT_RFNE0 | CAN_INT_RFF0 | CAN_INT_RFO0);
        nvic_irq_enable(ch.rx0Irq, CONFIG_IRQ_PREEMPT_CAN, static_cast<uint8_t>(i));

@@ -270,6 +293,29 @@ void CanFd::init()
    s_nextConsumeChannel = 0U;
 }

+/**
+ * @brief 切换 CANFD 接收过滤模式。
+ * @param[in]  mode 目标过滤模式。
+ * @note      切换时逐路重新配置过滤器；can_filter_init 内部会清 FCTL_FLD，无需手动进入 INITIAL 模式。
+ */
+void CanFd::setMode(Mode mode)
+{
+    uint32_t save = RT_CRITICAL_SAVE();
+    s_mode = mode;
+    for (size_t i = 0; i < kChannelCount; ++i) {
+        configureRxFilter(kChannels[i].canPeriph, kChannels[i].filterNumber, mode);
+    }
+    RT_CRITICAL_RESTORE(save);
+}
+
+/**
+ * @brief 查询当前 CANFD 接收过滤模式。
+ */
+CanFd::Mode CanFd::mode()
+{
+    return s_mode;
+}
+
 /**
 * @brief 执行兼容保留的 CAN 轮询入口。
 * @param[in]  无。
@@ -334,10 +380,12 @@ void CanFd::sendPrepared()
            s_diag.last_payload_length = frame.tx_message.tx_dlen;
            s_diag.last_tx_id = frame.tx_message.tx_sfid;
            s_diag.last_tx_channel = static_cast<uint8_t>(i);
+            s_channelStats[i].tx_count++;
            queue.head = static_cast<uint8_t>((queue.head + 1U) % kTxQueueDepth);
            queue.count--;
        } else {
            s_diag.error_count++;
+            s_channelStats[i].error_count++;
        }
    }
 }
@@ -464,9 +512,11 @@ bool CanFd::transmitFrame(uint8_t channelIndex, uint32_t ext_id,
        s_diag.last_tx_id      = ext_id;
        s_diag.last_tx_channel = channelIndex;
        s_diag.last_payload_length = dlc;
+        s_channelStats[channelIndex].tx_count++;
        return true;
    }
    s_diag.error_count++;
+    s_channelStats[channelIndex].error_count++;
    return false;
 }

@@ -546,9 +596,71 @@ void CanFd::handleRxInterrupt(uint8_t channelIndex)
        s_diag.last_rx_esi = rx_message.fd_esi;
        s_diag.last_rx_id = (rx_message.rx_ff == CAN_FF_STANDARD) ? rx_message.rx_sfid : rx_message.rx_efid;

+        /* 维护每通道独立计数与最近一帧快照，用于 1Hz 反馈给 ESP32。 */
+        auto &stats = s_channelStats[channelIndex];
+        stats.rx_count++;
+        stats.last_rx_id      = s_diag.last_rx_id;
+        stats.last_rx_dlc     = rx_message.rx_dlen;
+        stats.last_rx_fd_flag = rx_message.fd_flag;
+        stats.last_rx_brs     = rx_message.fd_brs;
+        stats.last_rx_esi     = rx_message.fd_esi;
+        const uint8_t copyLen = (rx_message.rx_dlen < CANFD_FEEDBACK_LAST_DATA_MAX)
+                                ? rx_message.rx_dlen : static_cast<uint8_t>(CANFD_FEEDBACK_LAST_DATA_MAX);
+        for (uint8_t i = 0U; i < copyLen; ++i) {
+            stats.last_rx_data[i] = rx_message.rx_data[i];
+        }
+        for (uint8_t i = copyLen; i < CANFD_FEEDBACK_LAST_DATA_MAX; ++i) {
+            stats.last_rx_data[i] = 0U;
+        }
+        /* 维护每通道不重复 ID 快照表，用于 1Hz 分页拉取给 ESP32。 */
+        {
+            auto &table = s_idSnapshot[channelIndex];
+            const uint32_t rxId = s_diag.last_rx_id;
+            /* 查找已有条目 */
+            uint8_t found = CANFD_ID_SNAPSHOT_MAX;
+            for (uint8_t si = 0U; si < table.count; ++si) {
+                if (table.entries[si].occupied && table.entries[si].id == rxId) {
+                    found = si;
+                    break;
+                }
+            }
+            if (found >= CANFD_ID_SNAPSHOT_MAX) {
+                /* 未找到：表未满则新建，满了淘汰最旧（index 0） */
+                if (table.count < CANFD_ID_SNAPSHOT_MAX) {
+                    found = table.count;
+                    table.count++;
+                } else {
+                    found = 0U;
+                    /* 淘汰后整体左移一格让新条目在末尾 */
+                    for (uint8_t si = 0U; si < CANFD_ID_SNAPSHOT_MAX - 1U; ++si) {
+                        table.entries[si] = table.entries[si + 1U];
+                    }
+                    found = CANFD_ID_SNAPSHOT_MAX - 1U;
+                }
+                table.entries[found] = {};
+                table.entries[found].id = rxId;
+                table.entries[found].occupied = true;
+            }
+            auto &entry = table.entries[found];
+            entry.rx_count++;
+            entry.dlc     = rx_message.rx_dlen;
+            entry.fd_flag = rx_message.fd_flag;
+            entry.brs     = rx_message.fd_brs;
+            entry.esi     = rx_message.fd_esi;
+            const uint8_t snapCopy = (rx_message.rx_dlen < CANFD_ID_SNAPSHOT_DATA_MAX)
+                                     ? rx_message.rx_dlen : static_cast<uint8_t>(CANFD_ID_SNAPSHOT_DATA_MAX);
+            for (uint8_t si = 0U; si < snapCopy; ++si) {
+                entry.data[si] = rx_message.rx_data[si];
+            }
+            for (uint8_t si = snapCopy; si < CANFD_ID_SNAPSHOT_DATA_MAX; ++si) {
+                entry.data[si] = 0U;
+            }
+        }
+
        auto &queue = s_rxQueues[channelIndex];
        if(queue.count >= kRxQueueDepth) {
            s_diag.rx_drop_count++;
+            stats.rx_drop_count++;
            continue;
        }

@@ -587,6 +699,53 @@ void CanFd::onRx0Interrupt()
    handleRxInterrupt(0U);
 }

+/**
+ * @brief 刷新三路 CAN 通道的 1Hz 反馈快照。
+ * @note  在临界区内拷贝实时计数与最近一帧信息到 s_feedback；保证 SPI 命令读到一致快照。
+ *        典型调用频率 1Hz，由任务调度器在心跳节拍触发。
+ */
+void CanFd::refreshFeedbackSnapshot()
+{
+    uint32_t save = RT_CRITICAL_SAVE();
+    s_feedbackSeq++;
+    for (size_t i = 0; i < kChannelCount; ++i) {
+        s_feedback[i].snapshot_seq = s_feedbackSeq;
+        s_feedback[i].stats = s_channelStats[i];
+        s_idSnapshot[i].seq = s_feedbackSeq;
+    }
+    RT_CRITICAL_RESTORE(save);
+}
+
+/**
+ * @brief 拷贝指定通道的最新反馈快照。
+ * @param[in]  channelIndex 目标 CAN 通道号（0/1/2）。
+ * @param[out] out          目标快照缓冲；为空或通道非法时返回 false。
+ * @retval bool true 表示成功拷贝。
+ */
+
+/**
+ * @brief 拷贝指定通道的不重复 ID 快照表。
+ */
+bool CanFd::copyIdSnapshotTable(uint8_t channelIndex, IdSnapshotTable *out)
+{
+    if (out == nullptr || channelIndex >= kChannelCount) {
+        return false;
+    }
+    uint32_t save = RT_CRITICAL_SAVE();
+    *out = s_idSnapshot[channelIndex];
+    RT_CRITICAL_RESTORE(save);
+    return true;
+}
+bool CanFd::copyFeedbackSnapshot(uint8_t channelIndex, ChannelFeedback *out)
+{
+    if (out == nullptr || channelIndex >= kChannelCount) {
+        return false;
+    }
+    uint32_t save = RT_CRITICAL_SAVE();
+    *out = s_feedback[channelIndex];
+    RT_CRITICAL_RESTORE(save);
+    return true;
+}
 /* ----- 中断入口 C 包装 ------------------------------------------------- */
 /**
 * @brief CAN0 RX0 中断向量入口。
@@ -40,11 +40,10 @@ void SchedulerTimer::configureTimer()
 * @param[in]  无。
 * @param[out] 无。
 * @retval    无返回值。
- * @note      设置优先级分组，并为调度定时器中断向量配置抢占优先级与子优先级。
+ * @note      优先级分组已前移至 AppInitializer::init() 最开头统一设置；此处仅为调度定时器中断向量配置抢占优先级与子优先级。
 */
 void SchedulerTimer::configureNvic()
 {
-    nvic_priority_group_set(CONFIG_NVIC_PRIORITY_GROUP);
    nvic_irq_enable(CONFIG_SCHED_TIMER_IRQn, CONFIG_SCHED_TIMER_IRQ_PREEMPT_PRIO, CONFIG_SCHED_TIMER_IRQ_SUB_PRIO);
 }

@@ -1,4 +1,4 @@
-#ifndef DEVICE_CANFD_H
+#ifndef DEVICE_CANFD_H
 #define DEVICE_CANFD_H

 #include <stdint.h>
@@ -6,165 +6,155 @@
 /** @brief CANFD 状态报文的数据长度，单位字节。 */
 #define CANFD_STATUS_DLEN 12U

+/** @brief 每通道反馈快照中保存的最近一帧最大数据长度，受 SPI 应答帧总长度约束。 */
+#define CANFD_FEEDBACK_LAST_DATA_MAX 32U
+
+/** @brief 每通道不重复 ID 快照表最大条目数。 */
+#define CANFD_ID_SNAPSHOT_MAX 16U
+
+/** @brief 快照条目中最大数据字节数（等于 CANFD DLC 上限）。 */
+#define CANFD_ID_SNAPSHOT_DATA_MAX 64U
+
 /**
 * @brief CANFD 通信模块。
 * @note 负责 GPIO/模式控制、波特率配置、异步接收缓存与按需发送能力。
 */
 class CanFd {
 public:
+    /**
+     * @brief CANFD 接收过滤模式枚举。
+     * @note  默认模式为 kModeAllPass，即三路控制器关闭硬件 ID 过滤，全部接收。
+     */
+    enum class Mode : uint8_t {
+        kModeAllPass    = 0U, /**< 全部接收模式：禁用硬件 ID/掩码匹配，所有 11/29 位帧都进入 FIFO0。 */
+        kModeFilterId   = 1U, /**< 过滤模式：按 CONFIG_CAN_RX_FILTER_ID/MASK 做标准帧掩码匹配。 */
+    };
+
    /**
     * @brief CANFD 运行诊断统计信息。
-     * @note 记录发送、接收、错误计数以及最近一次收发报文的关键信息。
     */
    struct Diag {
-        uint32_t tx_count;            /**< 成功发送的报文计数。 */
-        uint32_t rx_count;            /**< 成功接收的报文计数。 */
-        uint32_t error_count;         /**< 发送失败或检测到的错误计数。 */
-        uint32_t rx_drop_count;       /**< 软件接收队列满导致丢弃的报文计数。 */
-        uint32_t rx_fifo_full_count;  /**< 硬件 FIFO0 进入满状态的次数。 */
-        uint32_t rx_fifo_overfull_count; /**< 硬件 FIFO0 发生 overfull 的次数。 */
-        uint32_t tx_drop_count;       /**< 发送 FIFO 满导致丢弃的报文计数。 */
-        uint32_t tx_abort_count;      /**< 因邮箱全占主动中止占用邮箱的次数（典型：总线无 ACK 导致自动重传卡死）。 */
-        uint32_t last_rx_id;          /**< 最近一次接收报文的标识符。 */
-        uint32_t last_tx_id;          /**< 最近一次发送报文的标识符。 */
-        uint8_t  last_rx_channel;     /**< 最近一次接收报文所在的 CAN 通道号（0/1/2）。 */
-        uint8_t  last_tx_channel;     /**< 最近一次发送报文所在的 CAN 通道号（0/1/2）。 */
-        uint8_t  last_payload_length; /**< 最近一次收发报文的数据长度。 */
-        uint8_t  last_rx_fd_flag;     /**< 最近一次接收报文的 FD 帧标志。 */
-        uint8_t  last_rx_brs;         /**< 最近一次接收报文的波特率切换标志。 */
-        uint8_t  last_rx_esi;         /**< 最近一次接收报文的错误状态指示位。 */
+        uint32_t tx_count;
+        uint32_t rx_count;
+        uint32_t error_count;
+        uint32_t rx_drop_count;
+        uint32_t rx_fifo_full_count;
+        uint32_t rx_fifo_overfull_count;
+        uint32_t tx_drop_count;
+        uint32_t tx_abort_count;
+        uint32_t last_rx_id;
+        uint32_t last_tx_id;
+        uint8_t  last_rx_channel;
+        uint8_t  last_tx_channel;
+        uint8_t  last_payload_length;
+        uint8_t  last_rx_fd_flag;
+        uint8_t  last_rx_brs;
+        uint8_t  last_rx_esi;
    };

+    /**
+     * @brief 单通道运行计数（每路独立累计）。
+     */
+    struct ChannelStats {
+        uint32_t rx_count;            /**< 该通道累计成功接收帧数。 */
+        uint32_t tx_count;            /**< 该通道累计成功发送帧数。 */
+        uint32_t rx_drop_count;       /**< 该通道累计软件丢帧数。 */
+        uint32_t error_count;         /**< 该通道累计错误计数（与发送邮箱失败合并）。 */
+        uint32_t last_rx_id;          /**< 该通道最近一帧报文标识符。 */
+        uint8_t  last_rx_dlc;         /**< 该通道最近一帧报文数据长度。 */
+        uint8_t  last_rx_fd_flag;     /**< 该通道最近一帧 FD 帧标志。 */
+        uint8_t  last_rx_brs;         /**< 该通道最近一帧 BRS 标志。 */
+        uint8_t  last_rx_esi;         /**< 该通道最近一帧 ESI 标志。 */
+        uint8_t  last_rx_data[CANFD_FEEDBACK_LAST_DATA_MAX];
+    };
+
+    /**
+     * @brief 单通道 1Hz 反馈快照（每秒刷新一次）。
+     */
+    struct ChannelFeedback {
+        uint32_t snapshot_seq;        /**< 第几次刷新（自启动起递增）。 */
+        ChannelStats stats;           /**< 抓拍时刻的该通道统计与最近一帧信息。 */
+    };
+
+
+    /**
+     * @brief 单个不重复 ID 的最新帧快照。
+     */
+    struct IdSnapshotEntry {
+        uint32_t id;                                  /**< CAN 报文标识符。 */
+        uint32_t seq;                                 /**< 该条目被更新的序号（自启动起递增）。 */
+        uint32_t rx_count;                            /**< 该 ID 累计接收帧数。 */
+        uint8_t  dlc;                                 /**< 最新一帧数据长度。 */
+        uint8_t  fd_flag;                             /**< 最新一帧 FD 标志。 */
+        uint8_t  brs;                                 /**< 最新一帧 BRS 标志。 */
+        uint8_t  esi;                                 /**< 最新一帧 ESI 标志。 */
+        uint8_t  data[CANFD_ID_SNAPSHOT_DATA_MAX];    /**< 最新一帧数据。 */
+        bool     occupied;                            /**< 条目是否已被占用。 */
+    };
+
+    /**
+     * @brief 每通道不重复 ID 快照表（1Hz 刷新，SPI 命令分页拉取）。
+     */
+    struct IdSnapshotTable {
+        IdSnapshotEntry entries[CANFD_ID_SNAPSHOT_MAX];
+        uint8_t         count;       /**< 当前占用条目数。 */
+        uint32_t        seq;         /**< 全局更新序号（每次 refresh 时递增）。 */
+    };
    /**
     * @brief CANFD 状态发送载荷。
-     * @note 当前保持协议兼容，仅包含温度与供电相关字段；VIN_ADC 单独在诊断打印中输出。
     */
    struct StatusPayload {
-        uint16_t temp_raw;    /**< 内部温度通道原始 ADC 数值。 */
-        uint16_t vref_raw;    /**< 内部参考电压通道原始 ADC 数值。 */
-        float    vdda;        /**< 根据内部参考电压换算得到的 MCU 供电电压，单位 V。 */
-        float    temperature; /**< 根据温度通道换算得到的芯片温度，单位 ℃。 */
+        uint16_t temp_raw;
+        uint16_t vref_raw;
+        float    vdda;
+        float    temperature;
    };

-    /**
-     * @brief 初始化 CANFD 外设、GPIO、模式控制、过滤器与中断。
-     * @param[in]  无。
-     * @param[out] 无。
-     * @retval    无返回值。
-     * @note      初始化后默认进入 Normal 模式，并使能 3 路 CAN 控制器的 RX0 中断用于异步接收。
-     */
    static void init();

    /**
-     * @brief 兼容保留的轮询接口，中断模式下为空壳。
-     * @param[in]  无。
-     * @param[out] 无。
-     * @retval    无返回值。
-     * @note      实际接收已由 CAN0/CAN1/CAN2 的 RX0 中断驱动。
+     * @brief 切换 CANFD 接收过滤模式。
     */
+    static void setMode(Mode mode);
+
+    /** @brief 查询当前 CANFD 接收过滤模式。 */
+    static Mode mode();
+
    static void poll();
-
-    /**
-     * @brief 根据状态载荷准备一帧待发送的 CANFD 状态报文，并广播入队到 3 路发送 FIFO。
-     * @param[in]  status 指向 StatusPayload 的指针；为空时不入队。
-     * @param[out] 无。
-     * @retval    无返回值。
-     * @note      当前模块默认不会周期性调用该接口；仅在外部显式触发发送测试或业务发送时使用。
-     */
    static void prepareStatus(const StatusPayload *status);
-
-    /**
-     * @brief 根据状态载荷仅向指定 CAN 通道的发送 FIFO 入队一帧状态报文。
-     * @param[in]  channelIndex 目标 CAN 通道号（0/1/2）。
-     * @param[in]  status       指向 StatusPayload 的指针；为空时不入队。
-     * @param[out] 无。
-     * @retval bool true 表示成功入队，false 表示通道非法或该通道发送 FIFO 已满。
-     * @note      当前模块默认不会周期性调用该接口；仅在外部显式触发指定通道发送时使用。
-     */
    static bool prepareStatusForChannel(uint8_t channelIndex, const StatusPayload *status);
-
-    /**
-     * @brief 发送当前已准备好的 CANFD 状态报文。
-     * @param[in]  无。
-     * @param[out] 无。
-     * @retval    无返回值。
-     * @note      当前模块默认不会周期性调用该接口；仅发送调用方显式准备过的报文；若队列为空则直接返回。
-     */
    static void sendPrepared();
-
-    /**
-     * @brief 查询 3 个 CAN 通道中是否存在尚未消费的接收报文。
-     * @param[in]  无。
-     * @param[out] 无。
-     * @retval bool true 表示至少有一路存在待消费报文，false 表示当前所有通道缓存为空。
-     */
    static bool hasRxFrame();
-
-    /**
-     * @brief 读取并消费最近一轮扫描到的某一路缓存接收帧。
-     * @param[in]  无。
-     * @param[out] id      输出报文标识符的指针；允许为空。
-     * @param[out] data    输出报文数据缓存区指针；允许为空。
-     * @param[out] length  输出报文数据长度的指针；允许为空。
-     * @param[out] channel 输出报文来源的 CAN 通道号指针；允许为空。
-     * @retval bool true 表示成功消费一帧报文，false 表示当前 3 路缓存均为空。
-     * @note      每路通道使用轻量环形缓冲保留多帧；消费顺序采用轮转扫描，避免长期偏向固定通道。
-     */
    static bool consumeRxFrame(uint32_t *id, uint8_t *data, uint8_t *length, uint8_t *channel = nullptr);
-
-    /**
-     * @brief 直接向指定 CAN 通道发送一帧任意数据报文（扩展帧）。
-     * @param[in]  channelIndex 目标 CAN 通道号（0/1/2）。
-     * @param[in]  ext_id      扩展帧 ID（29 位）。
-     * @param[in]  data        数据负载指针。
-     * @param[in]  dlc         数据长度（1~64）。
-     * @retval bool true 表示成功入队硬件邮箱，false 表示参数无效或邮箱已满。
-     * @note      绕过软件发送队列，直接调用硬件发送；适用于 SPI 桥接等即时发送场景。
-     */
    static bool transmitFrame(uint8_t channelIndex, uint32_t ext_id,
                              const uint8_t *data, uint8_t dlc);
-
-    /**
-     * @brief 获取 CANFD 诊断统计信息只读指针。
-     * @param[in]  无。
-     * @param[out] 无。
-     * @retval const Diag* 指向内部诊断统计结构体的只读指针。
-     */
    static const Diag *diag();

    /**
-     * @brief 将 TCAN1057A 收发器置为正常工作模式。
-     * @param[in]  无。
-     * @param[out] 无。
-     * @retval    无返回值。
-     * @note      模式控制脚按 STB 语义处理：低电平为 Normal，高电平为 Silent。
+     * @brief 刷新三路 1Hz 反馈快照。
+     * @note  通常由任务调度器在 1 秒节拍调用，将各通道实时计数与最近一帧信息抓拍到 s_feedback。
     */
+    static void refreshFeedbackSnapshot();
+
+    /**
+     * @brief 拷贝指定通道的最新反馈快照到调用方缓冲。
+     * @param[in]  channelIndex 目标 CAN 通道号（0/1/2）。
+     * @param[out] out          目标快照缓冲；为空或通道非法时返回 false。
+     * @retval bool true 表示成功拷贝，false 表示参数非法。
+     */
+    static bool copyFeedbackSnapshot(uint8_t channelIndex, ChannelFeedback *out);
+
+    /**
+     * @brief 拷贝指定通道的不重复 ID 快照表。
+     * @param[in]  channelIndex 目标通道 0/1/2。
+     * @param[out] out          输出缓冲。
+     * @retval true 成功。
+     */
+    static bool copyIdSnapshotTable(uint8_t channelIndex, IdSnapshotTable *out);
+
    static void setNormalMode();
-
-    /**
-     * @brief 将 TCAN1057A 收发器置为静默模式。
-     * @param[in]  无。
-     * @param[out] 无。
-     * @retval    无返回值。
-     * @note      静默模式下收发器不驱动总线显性位，可用于总线监听或受控隔离。
-     */
    static void setSilentMode();
-
-    /**
-     * @brief CAN0 兼容中断处理入口。
-     * @param[in]  无。
-     * @param[out] 无。
-     * @retval    无返回值。
-     * @note      兼容保留给 CAN0 中断包装使用；三路统一接收逻辑已收口到 handleRxInterrupt()。
-     */
    static void onRx0Interrupt();
-
-    /**
-     * @brief 处理指定 CAN 通道的 RX0 中断接收。
-     * @param[in]  channelIndex CAN 通道索引（0/1/2）。
-     * @param[out] 无。
-     * @retval    无返回值。
-     */
    static void handleRxInterrupt(uint8_t channelIndex);

 private:
@@ -184,25 +174,30 @@ private:
        volatile uint8_t count;
    };

-    /** @brief 初始化 CAN0/CAN1/CAN2 相关 GPIO。 */
    static void initGpio();
-    /** @brief 为指定控制器配置接收过滤器。 */
-    static void configureRxFilter(uint32_t canPeriph, uint8_t filterNumber);
-    /** @brief 配置指定控制器的 CAN 仲裁段标称位时序。 */
+    /**
+     * @brief 根据当前模式为指定控制器配置接收过滤器。
+     * @param[in]  canPeriph    目标 CAN 外设实例。
+     * @param[in]  filterNumber 过滤器编号。
+     * @param[in]  mode         目标接收过滤模式。
+     */
+    static void configureRxFilter(uint32_t canPeriph, uint8_t filterNumber, Mode mode);
    static void initNominalTiming(uint32_t canPeriph);
-    /** @brief 配置指定控制器的 CAN FD 数据段位时序与 TDC。 */
    static void initFdMode(uint32_t canPeriph);
-    /** @brief 构造内部发送缓冲中的状态帧内容。 */
    static void buildStatusFrame(const StatusPayload *status);
-    /** @brief 向指定 CAN 通道的发送 FIFO 写入一帧状态报文。 */
    static bool enqueueTxFrame(uint8_t channelIndex, const StatusPayload *status);

-    static Diag     s_diag;
-    static RxQueue  s_rxQueues[3];
-    static uint8_t  s_nextConsumeChannel;
+    static Diag             s_diag;
+    static RxQueue          s_rxQueues[3];
+    static uint8_t          s_nextConsumeChannel;
+    static volatile Mode    s_mode;
+    static ChannelStats     s_channelStats[3];
+    static ChannelFeedback  s_feedback[3];
+    static uint32_t         s_feedbackSeq;
+    static IdSnapshotTable  s_idSnapshot[3];
 };

 using canfd_diag_t           = CanFd::Diag;
 using canfd_status_payload_t = CanFd::StatusPayload;

-#endif /* DEVICE_CANFD_H */
+#endif /* DEVICE_CANFD_H */
@@ -0,0 +1,206 @@
+/**
+ * @file app_spi_cmd_can_feedback.cpp
+ * @brief CAN 不重复 ID 快照表轮询与接收模式切换 SPI 命令处理器。
+ *
+ * 协议说明（与 ESP32 端 canfd_bridge 对接）：
+ *
+ * 1) kTypeCanFeedback (0xC1)：ESP32 主动轮询，分页返回不重复 ID 快照表。
+ *    请求 payload：
+ *      [0] channel       0/1/2
+ *      [1] page          页号（0 = 条目 0~7，1 = 条目 8~15）
+ *    应答 payload（变长，最大 kTxBufSize - overhead = 123 字节）：
+ *      [0]      channel
+ *      [1]      page
+ *      [2]      total_count   该通道当前条目总数
+ *      [3]      entry_count   本页实际条目数
+ *      [4]      mode          当前 CAN 接收模式
+ *      [5..8]   snapshot_seq  (LE)
+ *      [9..12]  rx_count      (LE)  通道累计接收
+ *      [13..16] tx_count      (LE)  通道累计发送
+ *      [17..20] drop_count    (LE)
+ *      [21..24] error_count   (LE)
+ *      [25..]   条目逐条拼接：
+ *               id(4LE) + dlc(1) + flags(1) + reserved(2) + data(dlc)
+ *               每条 = 8 + dlc 字节
+ *
+ * 2) kTypeCanSetMode (0xC2)：ESP32 主动切换三路 CAN 过滤模式。
+ *    请求 payload：
+ *      [0] mode          0=全部接收, 1=按 ID 过滤；其它值返回 kRspError。
+ *    应答 payload：
+ *      [0] 实际生效的 mode。
+ */
+
+#include "device/spi/spi_command_handler.h"
+#include "device/spi/app_spi_command.h"
+#include "device/spi/app_spi_command_defs.h"
+#include "device/canfd.h"
+#include "sys/config.h"
+#include <cstdio>
+#include <cstring>
+
+namespace {
+
+constexpr uint8_t  kFeedbackChannelCount = 3U;
+constexpr uint16_t kFeedbackPayloadLen   = 123U; /* kTxBufSize=128 - overhead=5 */
+constexpr uint8_t  kPageEntries          = 8U;
+constexpr uint16_t kFixedHeaderLen       = 25U;   /* ch(1)+page(1)+total(1)+cnt(1)+mode(1)+seq(4)+rx(4)+tx(4)+drop(4)+err(4) */
+
+void writeU32Le(uint8_t *dst, uint32_t value)
+{
+    dst[0] = static_cast<uint8_t>(value & 0xFFU);
+    dst[1] = static_cast<uint8_t>((value >> 8) & 0xFFU);
+    dst[2] = static_cast<uint8_t>((value >> 16) & 0xFFU);
+    dst[3] = static_cast<uint8_t>((value >> 24) & 0xFFU);
+}
+
+class SpiCanFeedbackHandler final : public ISpiCommandHandler {
+public:
+    bool canHandle(uint8_t frame_type) const override
+    {
+        return (frame_type == SpiDefs::kTypeCanFeedback)
+            || (frame_type == SpiDefs::kTypeCanSetMode);
+    }
+
+    void handle(AppSpiCommand &bus, const SpiCommandContext &ctx) override
+    {
+        if (ctx.frame_type == SpiDefs::kTypeCanFeedback) {
+            handleFeedback(bus, ctx);
+        } else {
+            handleSetMode(bus, ctx);
+        }
+    }
+
+private:
+    void handleFeedback(AppSpiCommand &bus, const SpiCommandContext &ctx)
+    {
+        if (ctx.payload_len < 2U) {
+            uint8_t err = 0xE0U;
+            bus.buildResponse(ctx.tx_buf, ctx.tx_buf_size, ctx.tx_len,
+                              SpiDefs::kRspError, &err, 1U);
+            return;
+        }
+
+        const uint8_t channel = ctx.payload[0];
+        const uint8_t page    = ctx.payload[1];
+
+        if (channel >= kFeedbackChannelCount) {
+            uint8_t err = 0xE1U;
+            bus.buildResponse(ctx.tx_buf, ctx.tx_buf_size, ctx.tx_len,
+                              SpiDefs::kRspError, &err, 1U);
+            return;
+        }
+
+        /* 拷贝统计快照 */
+        CanFd::ChannelFeedback snap{};
+        CanFd::copyFeedbackSnapshot(channel, &snap);
+
+        /* 拷贝 ID 快照表 */
+        CanFd::IdSnapshotTable table{};
+        CanFd::copyIdSnapshotTable(channel, &table);
+
+        const uint8_t start = static_cast<uint8_t>(page * kPageEntries);
+        if (start >= CANFD_ID_SNAPSHOT_MAX) {
+            uint8_t err = 0xE3U;
+            bus.buildResponse(ctx.tx_buf, ctx.tx_buf_size, ctx.tx_len,
+                              SpiDefs::kRspError, &err, 1U);
+            return;
+        }
+
+        uint8_t payload[kFeedbackPayloadLen] = {};
+
+        /* 固定头 */
+        payload[0] = channel;
+        payload[1] = page;
+        payload[2] = table.count;
+        /* payload[3] = entry_count 稍后填 */
+        payload[4] = static_cast<uint8_t>(CanFd::mode());
+        writeU32Le(&payload[5],  snap.snapshot_seq);
+        writeU32Le(&payload[9],  snap.stats.rx_count);
+        writeU32Le(&payload[13], snap.stats.tx_count);
+        writeU32Le(&payload[17], snap.stats.rx_drop_count);
+        writeU32Le(&payload[21], snap.stats.error_count);
+
+        /* 打包 ID 条目 */
+        uint16_t offset = kFixedHeaderLen;
+        uint8_t  packed = 0U;
+
+        const uint8_t end = static_cast<uint8_t>(
+            (start + kPageEntries < CANFD_ID_SNAPSHOT_MAX)
+            ? (start + kPageEntries) : CANFD_ID_SNAPSHOT_MAX);
+
+        for (uint8_t i = start; i < end; ++i) {
+            const auto &e = table.entries[i];
+            if (!e.occupied) continue;
+
+            const uint8_t dataLen = (e.dlc < CANFD_ID_SNAPSHOT_DATA_MAX)
+                                    ? e.dlc : static_cast<uint8_t>(CANFD_ID_SNAPSHOT_DATA_MAX);
+            const uint16_t entrySize = static_cast<uint16_t>(8U + dataLen);
+
+            if (offset + entrySize > kFeedbackPayloadLen) break;
+
+            writeU32Le(&payload[offset], e.id);
+            payload[offset + 4U] = e.dlc;
+            payload[offset + 5U] = static_cast<uint8_t>(
+                (e.fd_flag ? 1U : 0U) | (e.brs ? 2U : 0U) | (e.esi ? 4U : 0U));
+            payload[offset + 6U] = 0U; /* reserved */
+            payload[offset + 7U] = 0U; /* reserved */
+            memcpy(&payload[offset + 8U], e.data, dataLen);
+
+            offset += entrySize;
+            packed++;
+        }
+
+        payload[3] = packed;
+
+        bus.buildResponse(ctx.tx_buf, ctx.tx_buf_size, ctx.tx_len,
+                          SpiDefs::kRspAck, payload, offset);
+    }
+
+    void handleSetMode(AppSpiCommand &bus, const SpiCommandContext &ctx)
+    {
+        if (ctx.payload_len < 1U) {
+            uint8_t err = 0xE0U;
+            bus.buildResponse(ctx.tx_buf, ctx.tx_buf_size, ctx.tx_len,
+                              SpiDefs::kRspError, &err, 1U);
+            return;
+        }
+
+        const uint8_t requested = ctx.payload[0];
+        CanFd::Mode target;
+        switch (requested) {
+        case 0U: target = CanFd::Mode::kModeAllPass;  break;
+        case 1U: target = CanFd::Mode::kModeFilterId; break;
+        default: {
+            uint8_t err = 0xE1U;
+            bus.buildResponse(ctx.tx_buf, ctx.tx_buf_size, ctx.tx_len,
+                              SpiDefs::kRspError, &err, 1U);
+            return;
+        }
+        }
+
+        CanFd::setMode(target);
+
+        const uint8_t actual = static_cast<uint8_t>(CanFd::mode());
+
+#if (CONFIG_SPI_APP_LOG_ENABLE != 0)
+        char log_msg[AppSpiCommand::kLogBufSize] = {};
+        (void)snprintf(log_msg, sizeof(log_msg),
+                       "CAN_MODE set=%u -> actual=%u",
+                       static_cast<unsigned>(requested),
+                       static_cast<unsigned>(actual));
+        bus.postLog(log_msg);
+#endif
+
+        bus.buildResponse(ctx.tx_buf, ctx.tx_buf_size, ctx.tx_len,
+                          SpiDefs::kRspAck, &actual, 1U);
+    }
+};
+
+static SpiCanFeedbackHandler s_handler;
+
+} // namespace
+
+void registerSpiCanFeedbackCommand(AppSpiCommand &bus)
+{
+    bus.registerHandler(&s_handler);
+}
@@ -0,0 +1,135 @@
+/**
+ * @file app_spi_cmd_id_snapshot.cpp
+ * @brief SPI 命令处理器：kTypeIdSnapshot (0xC3)。
+ *
+ * ESP32 分页拉取指定 CAN 通道的不重复 ID 快照表。
+ *
+ * 请求 payload：
+ *   [0] channel       0/1/2
+ *   [1] page          页号（0 = 条目 0~7，1 = 条目 8~15）
+ *
+ * 应答 payload（变长，最大 kTxBufSize - 5 = 123 字节）：
+ *   [0]       channel
+ *   [1]       page
+ *   [2]       total_count   该通道当前条目总数
+ *   [3]       entry_count   本页实际条目数
+ *   [4..]     条目逐条拼接：
+ *              id(4LE) + seq(4LE) + rx_count(4LE) + dlc(1) + flags(1) + data(dlc)
+ *              每条 = 16 + dlc 字节
+ */
+
+#include "device/spi/spi_command_handler.h"
+#include "device/spi/app_spi_command.h"
+#include "device/spi/app_spi_command_defs.h"
+#include "device/canfd.h"
+#include <cstdio>
+#include <cstring>
+
+namespace {
+
+constexpr uint8_t  kPageEntries   = 8U;
+constexpr uint16_t kMaxPayloadLen = 123U; /* kTxBufSize=128 - overhead=5 */
+
+inline void writeU32Le(uint8_t *dst, uint32_t val)
+{
+    dst[0] = static_cast<uint8_t>(val & 0xFFU);
+    dst[1] = static_cast<uint8_t>((val >> 8) & 0xFFU);
+    dst[2] = static_cast<uint8_t>((val >> 16) & 0xFFU);
+    dst[3] = static_cast<uint8_t>((val >> 24) & 0xFFU);
+}
+
+class SpiIdSnapshotHandler final : public ISpiCommandHandler {
+public:
+    bool canHandle(uint8_t frame_type) const override
+    {
+        return frame_type == SpiDefs::kTypeIdSnapshot;
+    }
+
+    void handle(AppSpiCommand &bus, const SpiCommandContext &ctx) override
+    {
+        if (ctx.payload_len < 2U) {
+            uint8_t err = 0xE0U;
+            bus.buildResponse(ctx.tx_buf, ctx.tx_buf_size, ctx.tx_len,
+                              SpiDefs::kRspError, &err, 1U);
+            return;
+        }
+
+        const uint8_t channel = ctx.payload[0];
+        const uint8_t page    = ctx.payload[1];
+
+        if (channel >= 3U) {
+            uint8_t err = 0xE1U;
+            bus.buildResponse(ctx.tx_buf, ctx.tx_buf_size, ctx.tx_len,
+                              SpiDefs::kRspError, &err, 1U);
+            return;
+        }
+
+        CanFd::IdSnapshotTable table{};
+        if (!CanFd::copyIdSnapshotTable(channel, &table)) {
+            uint8_t err = 0xE2U;
+            bus.buildResponse(ctx.tx_buf, ctx.tx_buf_size, ctx.tx_len,
+                              SpiDefs::kRspError, &err, 1U);
+            return;
+        }
+
+        const uint8_t start = static_cast<uint8_t>(page * kPageEntries);
+        if (start >= CANFD_ID_SNAPSHOT_MAX) {
+            uint8_t err = 0xE3U;
+            bus.buildResponse(ctx.tx_buf, ctx.tx_buf_size, ctx.tx_len,
+                              SpiDefs::kRspError, &err, 1U);
+            return;
+        }
+
+        uint8_t payload[kMaxPayloadLen] = {};
+        payload[0] = channel;
+        payload[1] = page;
+        payload[2] = table.count;
+
+        uint16_t offset = 4U; /* [0]=ch [1]=page [2]=total [3]=entry_count(后填) */
+        uint8_t  packed = 0U;
+
+        const uint8_t end = static_cast<uint8_t>(
+            (start + kPageEntries < CANFD_ID_SNAPSHOT_MAX)
+            ? (start + kPageEntries) : CANFD_ID_SNAPSHOT_MAX);
+
+        for (uint8_t i = start; i < end; ++i) {
+            const auto &e = table.entries[i];
+            if (!e.occupied) continue;
+
+            const uint8_t dataLen = (e.dlc < CANFD_ID_SNAPSHOT_DATA_MAX)
+                                    ? e.dlc : static_cast<uint8_t>(CANFD_ID_SNAPSHOT_DATA_MAX);
+            const uint16_t entrySize = 16U + dataLen; /* 4+4+4+1+1+1+1 + data */
+
+            if (offset + entrySize > kMaxPayloadLen) break; /* 装不下就截断 */
+
+            writeU32Le(&payload[offset],      e.id);
+            writeU32Le(&payload[offset + 4U], e.seq);
+            writeU32Le(&payload[offset + 8U], e.rx_count);
+            payload[offset + 12U] = e.dlc;
+            /* flags 字节: bit0=fd, bit1=brs, bit2=esi */
+            payload[offset + 13U] = static_cast<uint8_t>(
+                (e.fd_flag ? 1U : 0U) | (e.brs ? 2U : 0U) | (e.esi ? 4U : 0U));
+            /* 保留 2 字节对齐 */
+            payload[offset + 14U] = 0U;
+            payload[offset + 15U] = 0U;
+            memcpy(&payload[offset + 16U], e.data, dataLen);
+
+            offset += entrySize;
+            packed++;
+        }
+
+        payload[3] = packed;
+
+        bus.buildResponse(ctx.tx_buf, ctx.tx_buf_size, ctx.tx_len,
+                          SpiDefs::kRspAck, payload, offset);
+    }
+};
+
+static SpiIdSnapshotHandler s_handler;
+
+} // namespace
+
+void registerSpiIdSnapshotCommand(AppSpiCommand &bus)
+{
+    bus.registerHandler(&s_handler);
+}
@@ -1,4 +1,4 @@
-/**
+/**
 * @file app_spi_command.cpp
 * @brief APP 运行期 SPI 链路与命令路由实现。
 *
@@ -303,6 +303,8 @@ extern void registerSpiBootRequestCommand(AppSpiCommand &bus);
 extern void registerSpiOtaWaitCommand(AppSpiCommand &bus);
 extern void registerSpiAppPingCommand(AppSpiCommand &bus);
 extern void registerSpiCanBridgeCommand(AppSpiCommand &bus);
+extern void registerSpiCanFeedbackCommand(AppSpiCommand &bus);
+extern void registerSpiIdSnapshotCommand(AppSpiCommand &bus);
 AppSpiCommand AppSpiCommandBus;
 void AppSpiCommand::init()
 {
@@ -320,6 +322,8 @@ void AppSpiCommand::init()
    registerSpiOtaWaitCommand(AppSpiCommandBus);
    registerSpiAppPingCommand(AppSpiCommandBus);
    registerSpiCanBridgeCommand(AppSpiCommandBus);
+    registerSpiCanFeedbackCommand(AppSpiCommandBus);
+    registerSpiIdSnapshotCommand(AppSpiCommandBus);

    configureGpio();
    configureSpi0();
@@ -58,7 +58,7 @@ public:
                       const uint8_t *payload, uint16_t payload_len);

    static constexpr uint16_t kRxBufSize = 128U;
-    static constexpr uint16_t kTxBufSize = 64U;
+    static constexpr uint16_t kTxBufSize = 128U;
    static constexpr uint16_t kLogBufSize = 256U;

 private:
@@ -23,6 +23,9 @@ static constexpr uint8_t kTypeOtaCancel = 0x03U;
 static constexpr uint8_t kTypeAppPing   = 0xA1U;
 static constexpr uint8_t kTypeBootReq   = 0xB0U;
 static constexpr uint8_t kTypeCanSend   = 0xC0U;
+static constexpr uint8_t kTypeCanFeedback = 0xC1U; /**< ESP32 -> GD32 轮询 CAN 反馈快照 */
+static constexpr uint8_t kTypeCanSetMode  = 0xC2U; /**< ESP32 -> GD32 切换 CAN 接收过滤模式 */
+static constexpr uint8_t kTypeIdSnapshot   = 0xC3U; /**< ESP32 -> GD32 拉取不重复 ID 快照表 */

 /* 响应类型 */
 static constexpr uint8_t kRspAck        = 0x80U;
@@ -74,7 +74,7 @@ private:

    static bool putCharNonBlocking(int ch);

-    static constexpr uint16_t kTxBufSize = 256U;
+    static constexpr uint16_t kTxBufSize = 1024U;
    static volatile uint32_t s_dropCount;
    static uint8_t           s_txBuf[kTxBufSize];
    static volatile uint16_t s_txHead;
@@ -102,7 +102,7 @@
 #define CONFIG_TASK_PERIOD_HEARTBEAT_TICKS 10000U

 /** @brief 周期温度/电压 UART 打印开关：0=关闭，1=开启。 */
-#define CONFIG_UART_TEMP_PERIODIC_PRINT 0
+#define CONFIG_UART_TEMP_PERIODIC_PRINT 1
 /** @brief UART 诊断打印级别：0=仅温度/电压，1=温度/电压+CAN 统计。 */
 #define CONFIG_UART_DIAG_LEVEL 1
 /** @brief SPI 命令逐帧日志开关：0=关闭，1=开启。高速 CAN 桥接时应关闭。 */
@@ -129,7 +129,7 @@
 /** @brief APP 次版本号。 */
 #define APP_FW_VERSION_MINOR  1U
 /** @brief APP 补丁版本号。 */
-#define APP_FW_VERSION_PATCH  0U
+#define APP_FW_VERSION_PATCH  2U
 /** @brief APP 构建编号。 */
 #define APP_FW_VERSION_BUILD  0U

@@ -175,13 +175,24 @@
 /* ============================================================
 * EtherCAT LAN9252 使能与配置
 * ============================================================ */
-/** @brief EtherCAT 使能开关:0=禁用(未焊接 LAN9252),1=启用(焊接后)。
- *  禁用时 comm/ 全部代码不编译,初始化不调用 EtherCAT,EXMC/EXTI0-2 不配置。 */
-#define CONFIG_ETHERCAT_ENABLE              0
-
 /** @brief SYNC0 同步模式:0=EXTI 外部触发(ESC 硬件同步,默认),1=TIMER0 降级(DC 未同步时)。 */
 #define CONFIG_ETHERCAT_SYNC_MODE           0

+/** @brief periodicIsr 最大执行时间告警阈值(µs)。实测超过此值需评估减小 PDO 大小或优化 EXMC 时序。
+ *  当前阈值 5µs:基于 32 字节 PDO + EXMC 6 HCLK 时序的估算上限。
+ *  preempt=0 ISR 阻塞窗口 ≤ 此阈值时,CAN/SPI 中断需容忍。 */
+#define CONFIG_ETHERCAT_ISR_MAX_US_THRESHOLD 5U
+
+/** @brief 输入 PDO(TxPDO)在 PDI 内存区的起始偏移。
+ *  对应 LAN9252 SyncManager 内存映射,需与主站 ESI 配置匹配。
+ *  @note 占位值,实际数值待主站配置确定后在集成阶段填入。 */
+#define CONFIG_ESC_PDI_INPUT_OFFSET          0x1000U
+
+/** @brief 输出 PDO(RxPDO)在 PDI 内存区的起始偏移。
+ *  对应 LAN9252 SyncManager 内存映射,需与主站 ESI 配置匹配。
+ *  @note 占位值,实际数值待主站配置确定后在集成阶段填入。 */
+#define CONFIG_ESC_PDI_OUTPUT_OFFSET         0x1200U
+
 /* ---------- EXMC 引脚配置(GD32E508 EXMC 标准映射) ---------- */
 /** @brief EXMC NOR/SRAM Region1 基址(NE1 片选)。 */
 #define CONFIG_ESC_EXMC_BASE_ADDR           0x60000000U
@@ -16,10 +16,8 @@
 #include "sys/ota_boot_request.h"
 #include "sys/task_manager.h"
 #include "sys/config.h"
-#if CONFIG_ETHERCAT_ENABLE
 #include "comm/ethercat_slave.h"
 #include "comm/ethercat_sync.h"
-#endif

 /**
 * @brief 执行应用级外设与调度初始化。
@@ -30,6 +28,10 @@
 */
 void AppInitializer::init()
 {
+    /* 必须最先设置 NVIC 优先级分组:确保后续 CanFd/SPI0 等外设 init 中
+     * 编码抢占/子优先级字节时使用正确的分组(PRE4_SUB0),避免在错误分组
+     * 下编码后被重新解释。EtherCAT 实时架构整改 Task3。 */
+    nvic_priority_group_set(CONFIG_NVIC_PRIORITY_GROUP);
    printf("[APP] init: SysTick...\r\n");
    SysTickTimer::initMs();
    printf("[APP] init: USART0...\r\n");
@@ -47,12 +49,14 @@ void AppInitializer::init()
    TaskManager::init();
    printf("[APP] init: SchedulerTimer...\r\n");
    SchedulerTimer::init();
-#if CONFIG_ETHERCAT_ENABLE
    printf("[APP] init: EthercatSlave...\r\n");
    EthercatSlave::init();
-    printf("[APP] init: EthercatSync...\r\n");
-    EthercatSync::init();
-#endif
+    if (EthercatSlave::isEscReady()) {
+        printf("[APP] init: EthercatSync...\r\n");
+        EthercatSync::init();
+    } else {
+        printf("[APP] init: EthercatSync SKIPPED (ESC not ready)\r\n");
+    }
    printf("[APP] init: Watchdog...\r\n");
    Watchdog::init();
    printf("[APP] init: all done\r\n");
@@ -1,4 +1,4 @@
-/**
+/**
 * @file task_runner.cpp
 * @brief 任务执行器实现。
 */
@@ -13,9 +13,7 @@
 #include "sys/ota_boot_request.h"
 #include "sys/task_manager.h"
 #include "sys/task_runner.h"
-#if CONFIG_ETHERCAT_ENABLE
 #include "comm/ethercat_slave.h"
-#endif

 namespace {
 constexpr uint32_t kAdcFilterWindow = CONFIG_ADC_FILTER_SIZE + 1U;
@@ -214,7 +212,7 @@ void TaskRunner::taskStatusLed()      { /* 预留 */ }
 * @retval    无返回值。
 * @note      当前仅保留任务入口。
 */
-void TaskRunner::taskHeartbeat()      { OtaBootRequest::process(); }
+void TaskRunner::taskHeartbeat()      { OtaBootRequest::process(); CanFd::refreshFeedbackSnapshot(); }

 /**
 * @brief 输出当前温度、电压与 CAN 诊断信息。
@@ -266,6 +264,23 @@ void TaskRunner::taskDiagnosticPrint()
           static_cast<unsigned long>(diag->tx_abort_count),
           static_cast<unsigned long>(diag->error_count));
 #endif
+
+    {
+        if (EthercatSlave::isEscReady()) {
+            uint32_t maxCyc = 0U, avgCyc = 0U, cnt = 0U;
+            EthercatSlave::getIsrStats(&maxCyc, &avgCyc, &cnt);
+            /* 180MHz: cycles / 180 = µs;用 *1000/180 获得毫微秒精度避免浮点 */
+            const uint32_t maxUs_x1000 = maxCyc * 1000U / 180U;
+            const uint32_t avgUs_x1000 = avgCyc * 1000U / 180U;
+            printf("[ECAT] periodicIsr cnt=%lu max=%lu.%03luus avg=%lu.%03luus\r\n",
+                   (unsigned long)cnt,
+                   (unsigned long)(maxUs_x1000 / 1000U), (unsigned long)(maxUs_x1000 % 1000U),
+                   (unsigned long)(avgUs_x1000 / 1000U), (unsigned long)(avgUs_x1000 % 1000U));
+        } else {
+            printf("[ECAT] ESC not detected (chip id=0x%08lX), EtherCAT disabled\r\n",
+                   (unsigned long)EthercatSlave::getChipId());
+        }
+    }
 }

 /**
@@ -289,11 +304,7 @@ void TaskRunner::taskSpiCmdProcess()
 */
 void TaskRunner::taskEthercatProcess()
 {
-#if CONFIG_ETHERCAT_ENABLE
    EthercatSlave::process();
-#else
-    /* 未使能 EtherCAT 时此分支不应被置位;保留空操作以避免链接错误。 */
-#endif
 }

 /**
@@ -328,6 +339,16 @@ void TaskRunner::runPending()
 {
    Watchdog::feed();

+    /* 周期路径( SYNC0 ISR preempt=0 )用 s_periodicSeq 序列号通知主循环,
+     * 不再走 task_flags,避免 BASEPRI 临界区与 preempt=0 的 RMW 竞态。
+     * 优先于 takePending() 处理,确保周期数据及时消费。
+     * ESC 未焊接时 selfTest 失败,isEscReady()=false,中断未使能,
+     * s_periodicSeq 不会递增,此分支自然不触发——双重守卫仅为防御性编程。 */
+    if (EthercatSlave::isEscReady() && EthercatSlave::hasPendingPeriodic()) {
+        EthercatSlave::markPeriodicProcessed();
+        taskEthercatProcess();
+    }
+
    const uint32_t pending = TaskManager::takePending();
    if(pending == 0U) return;

@@ -0,0 +1,338 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8" />
+  <title>DCU_APP SPI 通信 ID 参考</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <style>
+    :root{--bg:#f6f8fb;--card:#fff;--line:#dfe3ea;--muted:#6b7280;--text:#111827}
+    *{box-sizing:border-box}
+    body{margin:0;padding:28px 20px 48px;background:var(--bg);color:var(--text);font-family:"Segoe UI","Microsoft YaHei","PingFang SC",Arial,sans-serif;line-height:1.7}
+    .page{max-width:1080px;margin:0 auto}
+    h1{margin:0 0 8px;font-size:22px}
+    .muted{margin:0 0 22px;color:var(--muted);font-size:13px}
+    .stack{display:grid;grid-template-columns:1fr;gap:22px}
+    .card{background:var(--card);border:1px solid var(--line);border-radius:12px;padding:18px 20px;box-shadow:0 1px 2px rgba(16,24,40,.04)}
+    h2{margin:0 0 8px;font-size:18px}
+    .sub{margin:0 0 14px;color:var(--muted);font-size:12px}
+    details{border:1px solid var(--line);border-radius:10px;background:#fff;margin-top:12px}
+    summary{cursor:pointer;padding:14px 16px;font-weight:600}
+    .inside{padding:0 16px 16px}
+    table{width:100%;border-collapse:collapse;margin:10px 0 16px;font-size:14px}
+    th,td{border:1px solid var(--line);padding:10px 12px;vertical-align:top}
+    th{background:#f1f4f8;text-align:left;width:180px}
+    .note{background:#f8fafc;border:1px solid var(--line);border-radius:10px;padding:12px 14px;color:#374151;font-size:13px}
+    code{background:#f8fafc;padding:1px 4px;border-radius:4px}
+    .diagram{display:grid;grid-template-columns:1fr;gap:14px;margin:12px 0 16px}
+    .cell{flex:0 1 150px;min-width:120px;border:1px solid var(--line);border-radius:10px;background:#fff;overflow:hidden;page-break-inside:avoid;break-inside:avoid}
+    .row{display:flex;flex-wrap:wrap;gap:12px;margin:10px 0 14px;align-items:stretch}
+    .cell{border:1px solid var(--line);border-radius:10px;background:#fff;overflow:hidden}
+    .cell .top{padding:8px 10px;font-weight:700;background:#eef2f8;text-align:center;font-size:14px}
+    .cell .mid{padding:8px 10px;text-align:center;font-size:13px;color:#111}
+    .cell .bot{padding:8px 10px;border-top:1px solid var(--line);color:#374151;font-size:12px;text-align:center}
+    .cell.error .top{background:#fee2e2}
+    .cell.ok .top{background:#dcfce7}
+    .cell.info .top{background:#dbeafe}
+    .foot{margin-top:22px;color:var(--muted);font-size:12px}
+    .section-title{margin:18px 0 8px;font-size:14px;font-weight:600}
+  </style>
+</head>
+<body>
+  <div class="page">
+    <h1>DCU_APP SPI 通信 ID（按注册命令展开，三行直观图）</h1>
+    <p class="muted">按 <code>device/spi/app_spi_command.cpp</code> 注册顺序组织；每个命令均可展开查看 payload，并用“序号 / 组合 / 说明”三行显示。</p>
+    <div class="note" style="margin-bottom:18px">⚠ 单帧 payload 最大 <code>123</code> 字节（<code>kTxBufSize=128</code> - 协议开销 5 字节），超过将被 <code>AppSpiCommand::processCommand()</code> 拒收。</div>
+
+    <div class="stack">
+
+      <section class="card">
+        <h2>Boot Request</h2>
+        <div class="sub">注册函数：<code>registerSpiBootRequestCommand</code></div>
+        <details>
+          <summary>展开查看 ID / payload / 功能</summary>
+          <div class="inside">
+            <table>
+              <tr><th>命令/响应</th><th>符号</th><th>值</th></tr>
+              <tr><td>命令帧类型</td><td><code>kTypeBootReq</code></td><td><code>0xB0</code></td></tr>
+              <tr><td>成功响应</td><td><code>kRspAck</code></td><td><code>0x80</code></td></tr>
+            </table>
+            <div class="section-title">payload 直观图</div>
+            <div class="diagram">
+              <div class="cell info">
+                <div class="top">req</div>
+                <div class="mid">—</div>
+                <div class="bot">无可扩展 payload 字段</div>
+              </div>
+              <div class="cell ok">
+                <div class="top">ack</div>
+                <div class="mid">0x80</div>
+                <div class="bot">成功应答</div>
+              </div>
+            </div>
+            <div class="note">功能：请求进入 Boot 状态，回 ACK。</div>
+          </div>
+        </details>
+      </section>
+
+      <section class="card">
+        <h2>OTA Wait</h2>
+        <div class="sub">注册函数：<code>registerSpiOtaWaitCommand</code></div>
+        <details>
+          <summary>展开查看 ID / payload / 功能</summary>
+          <div class="inside">
+            <table>
+              <tr><th>命令</th><th>符号</th><th>值</th></tr>
+              <tr><td>OTA 请求</td><td><code>kTypeOtaReq</code></td><td><code>0x01</code></td></tr>
+              <tr><td>OTA 数据</td><td><code>kTypeOtaData</code></td><td><code>0x02</code></td></tr>
+              <tr><td>OTA 取消</td><td><code>kTypeOtaCancel</code></td><td><code>0x03</code></td></tr>
+              <tr><td>响应</td><td><code>kRspWait</code></td><td><code>0x81</code></td></tr>
+            </table>
+
+            <div class="section-title">response payload 直观图</div>
+            <div class="diagram">
+              <div class="cell info">
+                <div class="top">[0]</div>
+                <div class="mid">0x01</div>
+                <div class="bot">hint 固定值</div>
+              </div>
+            </div>
+
+            <div class="note">功能：OTA 占位/流控，占位/流控。</div>
+          </div>
+        </details>
+      </section>
+
+      <section class="card">
+        <h2>App Ping</h2>
+        <div class="sub">注册函数：<code>registerSpiAppPingCommand</code></div>
+        <details>
+          <summary>展开查看 ID / payload / 功能</summary>
+          <div class="inside">
+            <table>
+              <tr><th>命令/响应</th><th>符号</th><th>值</th></tr>
+              <tr><td>命令帧类型</td><td><code>kTypeAppPing</code></td><td><code>0xA1</code></td></tr>
+              <tr><td>响应</td><td><code>kRspAck</code></td><td><code>0x80</code></td></tr>
+            </table>
+
+            <div class="section-title">response payload 直观图</div>
+            <div class="diagram">
+              <div class="row">
+                <div class="cell info"><div class="top">[0]</div><div class="mid">0xA1</div><div class="bot">magic</div></div>
+                <div class="cell info"><div class="top">[1]</div><div class="mid">0x55</div><div class="bot">APP version tag</div></div>
+                <div class="cell ok"><div class="top">[2..5]</div><div class="mid">APP_VER</div><div class="bot">MAJOR/MINOR/PATCH/BUILD</div></div>
+                <div class="cell info"><div class="top">[6]</div><div class="mid">0xAA</div><div class="bot">BOOT version tag</div></div>
+                <div class="cell ok"><div class="top">[7..10]</div><div class="mid">BOOT_VER</div><div class="bot">Boot版本</div></div>
+                <div class="cell ok"><div class="top">[11..14]</div><div class="mid">uptime</div><div class="bot">运行秒数</div></div>
+              </div>
+            </div>
+
+            <div class="note">功能：读取版本与 uptime。</div>
+          </div>
+        </details>
+      </section>
+
+      <section class="card">
+        <h2>CAN Bridge</h2>
+        <div class="sub">注册函数：<code>registerSpiCanBridgeCommand</code></div>
+        <details>
+          <summary>展开查看 ID / payload / 功能</summary>
+          <div class="inside">
+            <table>
+              <tr><th>命令/响应</th><th>符号</th><th>值</th></tr>
+              <tr><td>命令帧类型</td><td><code>kTypeCanSend</code></td><td><code>0xC0</code></td></tr>
+              <tr><td>成功响应</td><td><code>kRspAck</code></td><td><code>0x80</code></td></tr>
+              <tr><td>错误响应</td><td><code>kRspError</code></td><td><code>0x82</code></td></tr>
+            </table>
+
+            <div class="section-title">request payload 直观图</div>
+            <div class="diagram">
+              <div class="row">
+                <div class="cell ok"><div class="top">[0]</div><div class="mid">can_ch</div><div class="bot">通道 0/1/2</div></div>
+                <div class="cell info"><div class="top">[1..4]</div><div class="mid">can_id</div><div class="bot">CAN ID(32bit)</div></div>
+                <div class="cell info"><div class="top">[5..N]</div><div class="mid">can_data</div><div class="bot">数据区</div></div>
+              </div>
+            </div>
+
+            <div class="section-title">response payload 直观图</div>
+            <div class="diagram">
+              <div class="row">
+                <div class="cell ok"><div class="top">ack</div><div class="mid">0x00</div><div class="bot">OK</div></div>
+                <div class="cell error"><div class="top">err</div><div class="mid">E0/E1/E2</div><div class="bot">短帧/通道/忙</div></div>
+              </div>
+            </div>
+
+            <div class="note">错误码：<code>E0</code>=payload 不足，<code>E1</code>=通道非法，<code>E2</code>=发送忙/失败。</div>
+            <div class="note">功能：ESP32 透传 CANFD 发送帧，校验后发送。</div>
+          </div>
+        </details>
+      </section>
+
+      <section class="card">
+        <h2>CAN Feedback (ID Snapshot) / Set Mode</h2>
+        <div class="sub">注册函数：<code>registerSpiCanFeedbackCommand</code></div>
+        <details>
+          <summary>展开查看 ID / payload / 功能</summary>
+          <div class="inside">
+            <table>
+              <tr><th>命令</th><th>符号</th><th>值</th></tr>
+              <tr><td>反馈查询（分页）</td><td><code>kTypeCanFeedback</code></td><td><code>0xC1</code></td></tr>
+              <tr><td>模式切换</td><td><code>kTypeCanSetMode</code></td><td><code>0xC2</code></td></tr>
+              <tr><td>成功响应</td><td><code>kRspAck</code></td><td><code>0x80</code></td></tr>
+              <tr><td>错误响应</td><td><code>kRspError</code></td><td><code>0x82</code></td></tr>
+            </table>
+
+            <div class="section-title">0xC1 request payload 直观图（分页请求）</div>
+            <div class="diagram">
+              <div class="row">
+                <div class="cell ok"><div class="top">[0]</div><div class="mid">channel</div><div class="bot">通道 0/1/2</div></div>
+                <div class="cell ok"><div class="top">[1]</div><div class="mid">page</div><div class="bot">页号 0 或 1</div></div>
+              </div>
+            </div>
+
+            <div class="section-title">0xC1 response payload 直观图（统计头 + ID 快照条目）</div>
+            <div class="sub">应答变长，最大 123 字节。固定头 25B + 条目逐条拼接。</div>
+            <div class="diagram">
+              <div class="sub" style="font-weight:600;">固定头（25 字节）</div>
+              <div class="row">
+                <div class="cell ok"><div class="top">[0]</div><div class="mid">channel</div><div class="bot">回显通道 0/1/2</div></div>
+                <div class="cell ok"><div class="top">[1]</div><div class="mid">page</div><div class="bot">回显页号</div></div>
+                <div class="cell info"><div class="top">[2]</div><div class="mid">total_count</div><div class="bot">ID 条目总数(0~16)</div></div>
+                <div class="cell info"><div class="top">[3]</div><div class="mid">entry_count</div><div class="bot">本页条目数</div></div>
+                <div class="cell info"><div class="top">[4]</div><div class="mid">mode</div><div class="bot">当前接收模式</div></div>
+              </div>
+              <div class="row">
+                <div class="cell info"><div class="top">[5..8]</div><div class="mid">snapshot_seq</div><div class="bot">快照序号(LE)</div></div>
+                <div class="cell info"><div class="top">[9..12]</div><div class="mid">rx_count</div><div class="bot">通道累计接收(LE)</div></div>
+                <div class="cell info"><div class="top">[13..16]</div><div class="mid">tx_count</div><div class="bot">通道累计发送(LE)</div></div>
+                <div class="cell info"><div class="top">[17..20]</div><div class="mid">rx_drop_count</div><div class="bot">通道丢帧(LE)</div></div>
+                <div class="cell info"><div class="top">[21..24]</div><div class="mid">error_count</div><div class="bot">通道错误(LE)</div></div>
+              </div>
+              <div class="sub" style="font-weight:600;margin-top:14px;">条目区（从 [25] 开始，逐条拼接，变长）</div>
+              <div class="row">
+                <div class="cell ok"><div class="top">[+0..+3]</div><div class="mid">id</div><div class="bot">CAN 报文 ID(LE)</div></div>
+                <div class="cell info"><div class="top">[+4]</div><div class="mid">dlc</div><div class="bot">数据长度 1~64</div></div>
+                <div class="cell info"><div class="top">[+5]</div><div class="mid">flags</div><div class="bot">bit0=FD bit1=BRS bit2=ESI</div></div>
+                <div class="cell info"><div class="top">[+6..+7]</div><div class="mid">reserved</div><div class="bot">0x00</div></div>
+                <div class="cell ok"><div class="top">[+8..+N]</div><div class="mid">data</div><div class="bot">报文数据(dlc 字节)</div></div>
+              </div>
+            </div>
+
+            <div class="note">
+              <b>条目大小</b> = 8 + dlc 字节。标准 CAN (dlc=8)：14B/条，每页最多 8 条。CANFD (dlc=64)：72B/条，每页最多 1 条。<br/>
+              <b>total_count</b> = 实际不重复 ID 数（0~16，不满 16 就是实际值）。total_count &le; 8 时 page=1 的 entry_count=0。<br/>
+              <b>ESP32 每轮</b>：每通道发 page=0 和 page=1 两次请求（共 6 次 SPI/s），拉完整张表。
+            </div>
+
+            <div class="section-title">0xC2 request payload 直观图</div>
+            <div class="diagram">
+              <div class="row">
+                <div class="cell ok"><div class="top">[0]</div><div class="mid">mode</div><div class="bot">0=全收 1=过滤</div></div>
+              </div>
+            </div>
+
+            <div class="section-title">0xC2 response payload 直观图</div>
+            <div class="diagram">
+              <div class="row">
+                <div class="cell ok"><div class="top">[0]</div><div class="mid">actual</div><div class="bot">生效模式</div></div>
+              </div>
+            </div>
+            <div class="note">错误码：<code>E0</code>=payload 不足，<code>E1</code>=参数非法（含非法通道），<code>E3</code>=页号非法。</div>
+            <div class="note">注：<code>E2</code>=快照不可用 仅用于 0xC3，不在 0xC1/0xC2 中返回。</div>
+          </div>
+        </details>
+      </section>
+
+      <section class="card">
+        <h2>ID Snapshot（仅 ID 快照表）</h2>
+        <div class="sub">注册函数：<code>registerSpiIdSnapshotCommand</code></div>
+        <details>
+          <summary>展开查看 ID / payload / 功能</summary>
+          <div class="inside">
+            <table>
+              <tr><th>命令/响应</th><th>符号</th><th>值</th></tr>
+              <tr><td>命令帧类型</td><td><code>kTypeIdSnapshot</code></td><td><code>0xC3</code></td></tr>
+              <tr><td>成功响应</td><td><code>kRspAck</code></td><td><code>0x80</code></td></tr>
+              <tr><td>错误响应</td><td><code>kRspError</code></td><td><code>0x82</code></td></tr>
+            </table>
+
+            <div class="section-title">0xC3 request payload 直观图（分页请求）</div>
+            <div class="diagram">
+              <div class="row">
+                <div class="cell ok"><div class="top">[0]</div><div class="mid">channel</div><div class="bot">通道 0/1/2</div></div>
+                <div class="cell ok"><div class="top">[1]</div><div class="mid">page</div><div class="bot">页号 0 或 1</div></div>
+              </div>
+            </div>
+
+            <div class="section-title">0xC3 response payload 直观图（轻量快照头 + ID 条目）</div>
+            <div class="sub">应答变长，最大 123 字节。固定头 4B + 条目逐条拼接。</div>
+            <div class="diagram">
+              <div class="sub" style="font-weight:600;">固定头（4 字节）</div>
+              <div class="row">
+                <div class="cell ok"><div class="top">[0]</div><div class="mid">channel</div><div class="bot">回显通道 0/1/2</div></div>
+                <div class="cell ok"><div class="top">[1]</div><div class="mid">page</div><div class="bot">回显页号</div></div>
+                <div class="cell info"><div class="top">[2]</div><div class="mid">total_count</div><div class="bot">ID 条目总数(0~16)</div></div>
+                <div class="cell info"><div class="top">[3]</div><div class="mid">entry_count</div><div class="bot">本页条目数</div></div>
+              </div>
+              <div class="sub" style="font-weight:600;margin-top:14px;">条目区（从 [4] 开始，逐条拼接，变长）</div>
+              <div class="row">
+                <div class="cell ok"><div class="top">[+0..+3]</div><div class="mid">id</div><div class="bot">CAN 报文 ID(LE)</div></div>
+                <div class="cell info"><div class="top">[+4..+7]</div><div class="mid">seq</div><div class="bot">该 ID 更新序号(LE)</div></div>
+                <div class="cell info"><div class="top">[+8..+11]</div><div class="mid">rx_count</div><div class="bot">该 ID 累计接收(LE)</div></div>
+                <div class="cell info"><div class="top">[+12]</div><div class="mid">dlc</div><div class="bot">数据长度 1~64</div></div>
+                <div class="cell info"><div class="top">[+13]</div><div class="mid">flags</div><div class="bot">bit0=FD bit1=BRS bit2=ESI</div></div>
+                <div class="cell info"><div class="top">[+14..+15]</div><div class="mid">reserved</div><div class="bot">0x00</div></div>
+                <div class="cell ok"><div class="top">[+16..+N]</div><div class="mid">data</div><div class="bot">报文数据(dlc 字节)</div></div>
+              </div>
+            </div>
+
+            <div class="note">
+              <b>条目大小</b> = 16 + dlc 字节。标准 CAN (dlc=8)：24B/条，每页最多 5 条。CANFD (dlc=64)：80B/条，每页最多 1 条。<br/>
+              <b>total_count</b> = 实际不重复 ID 数（0~16，不满 16 就是实际值）。total_count &le; 8 时 page=1 的 entry_count=0。<br/>
+              <b>ESP32 行为</b>：当前代码实现了 0xC3，但主链路主要通过 0xC1 拉取“统计头 + ID 快照表”。
+            </div>
+
+            <div class="note">错误码：<code>E0</code>=payload 不足，<code>E1</code>=通道非法，<code>E2</code>=快照不可用，<code>E3</code>=页号非法。</div>
+          </div>
+        </details>
+      </section>
+
+      <section class="card">
+        <h2>公共响应 / 协议常量</h2>
+        <div class="sub">来源：<code>app_spi_command_defs.h</code>、<code>app_spi_command.cpp</code></div>
+        <details>
+          <summary>展开查看公共 ID / payload</summary>
+          <div class="inside">
+            <div class="section-title">公共帧头与响应</div>
+            <div class="diagram">
+              <div class="cell info"><div class="top">SOF</div><div class="mid">0xA5</div><div class="bot">起始帧头</div></div>
+              <div class="cell ok"><div class="top">ACK</div><div class="mid">0x80</div><div class="bot">成功</div></div>
+              <div class="cell info"><div class="top">WAIT</div><div class="mid">0x81</div><div class="bot">等待中</div></div>
+              <div class="cell error"><div class="top">ERR</div><div class="mid">0x82</div><div class="bot">错误</div></div>
+            </div>
+            <div class="note">公共响应 payload 长度与含义由各命令自行定义。</div>
+          </div>
+        </details>
+      </section>
+
+    </div>
+
+    <p class="foot">说明：CAN ID 在 CAN Bridge/Feedback 场景下为运行时值，不在文档中固化为常量。</p>
+  </div>
+</body>
+</html>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+