DCU_APP/docs/compose/spec/warm-jump-ecat-probe.md

feature, status, updated, branch, commits

feature	status	updated	branch	commits
warm-jump-ecat-probe	delivered	2026-09-16	master	7d9d9c7..uncommitted

Warm Jump 后 EtherCAT 起板探针修复

Report

What was built — APP 1.6.40：EscLan9252::init 起板探针放行门从 HBI_IDX_0==0x1234 改为 BYTE_TEST==0x87654321。warm jump 残留的 HBI_IDX_0=0x0054 只打 WARN 并放行；BYTE_TEST 不过才补一发 RST# 重探一轮。 cold 路径行为不变（仍等芯片出复位到 0x1234 再测 BYTE_TEST）。

Verification — 无 ARM 交叉编译环境；静态审查通过（spec 合规 / 正确性 / 代码风格），reviewer 无 critical。上板验收：ECAT 刷完 warm jump 后串口应见 [ECAT][ESC] init: OK（可带 WARN idx0=0x0054），[APP] init 不再报 skipped/failed: ethercat，主站可建连；reset 路径回归不破坏。

Journey log

• BOOT 1.1.0.18 短路 escResetForJump 是刻意实验；APP 侧旧探针把「复位默认值」 当成通路判据，在 warm 残值上必然假阴性。
• 主工作区曾有一份未完成的 1.6.40 草稿；本任务收口并跳过 warm 残值的 300ms 空等。
• 用户选了隔离 worktree，但本环境拦截 git worktree add，改动落在主工作区未提交 diff。

[S1] Problem

刷完固件后 BOOT（1.1.0.18，跳转前 escResetForJump() 已短路）warm jump 进 APP： APP banner 正常，但 EtherCAT 不可用（自检降级 / 主站无法建连）。按复位键走 cold jump 后 EtherCAT 恢复。同一镜像、同一 APP 启动链，差异只在进入 APP 前 ESC 的 HBI 索引寄存器状态。

[S2] Design

根因

1. BOOT bootEcatDeinit() 最后一条 writeReg32(IRQ_CFG) 把 LAN9252 的 HBI_IDX_0 留在 0x0054（索引模式残值，DS 9.5.4.2 复位默认才是 0x1234）。
2. 跳转前硬复位在 BOOT 1.1.0.18 被刻意短路（1.1.0.13/14 实测那发复位会打死 warm jump），warm 路径芯片 不会 回到 POR 默认态。
3. APP EscLan9252::init() 旧放行门是 HBI_IDX_0==0x1234。该值只证明 「芯片刚出过复位」，证明不了 HBI 通路。warm 路径上探针必然假阴性 → s_busReady=false → SSC 跳过 → 降级 ethercat。
4. cold 路径芯片自带 POR，IDX_0 天然 0x1234，与 PB10 那发复位无关 —— 这正是「reset 能好、刷完不行」的分界。

修复契约

• BYTE_TEST（0x064==0x87654321）是唯一物理通路门。readReg32 每次访问前 都 setHbiIndex(addr)，完整「索引写 + 数据低/高字读」往返，与复位态无关。
• HBI_IDX_0 降级为诊断读数：异常时打 WARN 并放行，不再导致 return false。
• 任一判据不过 → 补一发 hardwareReset() 再探一轮（此刻 SSC 未 MainInit， 二次复位零配置代价）。两轮仍不通 = 总线物理不通，维持降级。
• s_busReady 语义同步：EXMC + BYTE_TEST 通过即 true（与 initial.cpp 的 isBusReady()&&isCoreReady() 门控一致）。

不做的事

• 不改 BOOT（1.1.0.18 保持 RST# 短路）；APP 侧已能兜住 warm 残值。
• 不把 HBI_IDX_0==0x1234 恢复为硬门。
• 不动 PDO/SII/主站解码。

[S3] Out of Scope

• BOOT bootEcatDeinit 的 PD/PE 浮空注释错误、escResetForJump 时序重设计。
• PHY 链路重协商窗口与主站 probe 重试（另见 ecat_boot_handoff_link_issue.md）。
• 1.6.35~38 启动链实验回退项（已在 1.6.39 完成）。

Tasks

• T1: 改 EscLan9252::init 探针 — 放行门改为 BYTE_TEST，IDX 残值 WARN 放行，失败补一发 RST# 重探 — acceptance: 代码与 [S2] 契约一致 (covers: S2)
• T2: 同步 esc_lan9252.h 的 isBusReady 文档语义 — acceptance: 注释与实现一致 (covers: S2; depends: T1)
• T3: config.h 版本 bump 1.6.40 + 来由注释 — acceptance: PATCH=40 且注释写明 warm-jump 根因 (covers: S2)
• T4: 逻辑核对探针与调用方 — acceptance: 无 ARM 交叉编译环境，完成静态审查；initial.cpp 仍用 isBusReady()&&isCoreReady() 门控，语义兼容 (covers: S2; depends: T1)

工作区说明

用户选择隔离 worktree，但本环境拦截了 git worktree add（共享 ref store 保护）。改动落在主工作区未提交 diff，分支意图为 fix/warm-jump-ecat-probe。验收通过后需用户确认是否提交到 master。