---
feature: warm-jump-ecat-probe
status: delivered
updated: 2026-09-16
branch: master
commits: 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

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

### 工作区说明

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