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

- 添加CAN反馈和ID快照SPI命令文件
- 移除EXMC组件依赖，精简项目配置
- 添加RAM函数段链接脚本，优化Flash等待周期抖动
- 实现EscExmcBus类，提供16位并行总线访问LAN9252
- 实现EscLan9252驱动，支持寄存器和PDI内存访问
- 实现EthercatSlave类，采用三缓冲机制进行PDO数据交换
- 实现EthercatSync同步管理，支持SYNC0/SYNC1中断和定时器模式
- 添加ISR执行时间统计和诊断功能
- 分离周期路径和事件路径通知机制，避免RMW竞态

.trae/specs/fix-ecat-pdo-and-runtime-issues/checklist.md

@@ -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 回绕周期覆盖任何合理主循环阻塞,闭环

.trae/specs/fix-ecat-pdo-and-runtime-issues/spec.md

@@ -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 范畴

.trae/specs/fix-ecat-pdo-and-runtime-issues/tasks.md

@@ -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(编译验证)

.trae/specs/fix-ecat-postaudit-risks/checklist.md

@@ -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 矛盾):删除未用接口,陷阱消除,闭环

.trae/specs/fix-ecat-postaudit-risks/spec.md

@@ -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)

.trae/specs/fix-ecat-postaudit-risks/tasks.md

@@ -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 全部完成

.trae/specs/fix-ethercat-realtime-comm-risks/checklist.md

@@ -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 化,闭环

.trae/specs/fix-ethercat-realtime-comm-risks/spec.md

@@ -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` 现有分支

.trae/specs/fix-ethercat-realtime-comm-risks/tasks.md

@@ -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 全部完成