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

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