100ASK T113S3 Pro 主线适配真实调试记录

本章目标

本章不把最终成功结果倒推成一条“从未失败”的直线流程，而是保留主线适配中真实出现过的 USB、SPL 返回、启动介质、U-Boot 环境、SPI NAND 读取、UBI 参数、串口监控和源码重建问题。每条结论必须能追溯到任务 ID、UART 标志、Git 提交或 SHA-256 清单。

Ubuntu、FEL 与 UART 联合调试场景

AI 生成的调试场景示意图，参考了 100ASK T113S3 Pro V1.3 实物图。下文任务 ID、错误信息和串口片段来自真实脱敏记录；本图本身不是硬件证据。

什么叫“真实记录”

本章使用以下证据：

证据	内容	真实性边界
Lynx 导出的任务 JSONL	任务 ID、阶段、进度、错误、退出码	已删除绝对路径和无关设备信息
Lynx Power 记录	设备、继电器通道、断电/上电和间隔	只保留本次板卡相关事件
UART 日志	U-Boot、Linux、UBI、UBIFS、登录提示	来自独立串口采集
Git 提交记录	问题修复和永久补丁演进	以公开功能分支为准
产物 manifest	确切 SHA-256 和状态分级	哈希只对应特定构建

公开仓库不包含 Lynx 原始 SQLite 数据库，因为其中可能混有其他板卡和主机元数据。本文引用的是已经导出并脱敏的 JSONL。文档构建过程也不依赖现场 MCP 查询，避免未来无法连接 Lynx 时页面失去证据。

调试时间线

任务或证据	结果	观察到的问题	后续处理
`mainline-1787540528424261798`	失败	写 Bootloader 到 `0x47000000` 时 USB transfer failed	继续收敛 FEL 地址计划和 USB 会话
`mainline-1787544643184636049`	失败	plan 使用未知角色 `spl`，OpenixCLI 只接受既定角色枚举	修正计划角色和解析约束
`mainline-1787560530410263404`	失败	`MAINLINE_SPL_RETURN_READ_FAILED`	修正 R528 SRAM 返回路径、PLL 保留和重连逻辑
`mainline-1787624335570337470`	失败	`mainline_spl_return_reconnect_wait` 超时	增加有界重连并继续验证物理 USB 端点
`mainline-1787624706059583488`	成功	同阶段传输完成	证明修改后的 RAM 交接路径可继续运行
`mainline-1787655837814079629`	成功	installer 100%，随后冷启动进入登录终端	建立第一套硬件验证基线
`mainline-1787708569776828829`	工具错误	`/dev/ttyACM0` 被诊断客户端关闭	禁止旁路程序打开/关闭 UI 管理的串口 handle
`mainline-1787708850567538011`	失败	clean build 到 50%，180 秒内没有 installer marker	该组哈希标记为 `failed-do-not-use`
`mainline-1787709324680503509`	成功	旧硬件验证 bundle 再次达到 100%	证明板卡和工作流本身仍然可用
`mainline-1787715829104265529`	成功	源码重建完成安装、温重启和两次冷启动	新源码重建产物晋升为 `hardware-verified`

时间线中“成功”只表示相应任务自身的状态。只有同时拥有 installer 完成、读回校验、温重启和断电冷启动证据的哈希，才能写成硬件验证产物。

记录一：计划角色不匹配

早期任务中的真实错误为：

task_id=mainline-1787544643184636049
status=failed
phase=opening_device
error=MAINLINE_PLAN_PARSE:
unknown variant `spl`, expected one of
`bootloader`, `kernel`, `device_tree`, `initramfs`, `trusted_firmware`

这不是板卡故障，而是主机侧计划 schema 与 OpenixCLI 枚举不一致。后续计划生成器把 U-Boot proper 标为 bootloader，installer FIT 标为 kernel，payload 分片标为 initramfs；SPL 的专用语义则由当前功能分支显式支持和校验。

记录二：SPL 返回和 USB 重连

多个任务曾停在 SPL 执行或返回后：

mainline-1787560530410263404
MAINLINE_SPL_RETURN_READ_FAILED
Caused by: USB transfer failed

mainline-1787624335570337470
MAINLINE_USB_PROGRESS_TIMEOUT:30000ms:
phase=mainline_spl_return_reconnect_wait

问题收敛过程中依次处理了：

R528 SRAM 区域重叠；
BootROM 返回所需的交换和返回 thunk；
SPL 不应破坏 FEL 返回依赖的 PLL 状态；
USB 设备重新枚举后应按固定物理端点有界重开；
终止失败任务后必须手动重新进入 FEL，不自动重试 NAND 写入。

任务 mainline-1787624706059583488 随后以相同工作流完成传输，说明修改后的 RAM 交接路径可以继续推进，但它本身仍不能代替 NAND 安装证据。

记录三：串口监控被旁路程序破坏

脱敏 Lynx 记录：

{
  "taskId": "mainline-1787708569776828829",
  "status": "failed",
  "phase": "waiting_for_installer",
  "progressPct": 50.0,
  "error": "Port /dev/ttyACM0 is not open",
  "classification": "operator-tooling-error"
}

调查确认是诊断客户端关闭了 Lynx UI 正在管理的共享串口 handle。该任务不能用于判定产物好坏。正确做法是通过任务状态接口观察，不另行打开或关闭同一个串口设备。

记录四：本地门禁通过，但硬件 installer 没启动

干净仓库重建后，语法、格式、哈希、FIT、UBI 和地址门禁全部通过，但真实硬件任务得到：

{
  "taskId": "mainline-1787708850567538011",
  "status": "failed",
  "phase": "waiting_for_installer",
  "progressPct": 50.0,
  "error": "MAINLINE_INSTALLER_TIMEOUT:no completion marker within 180 seconds",
  "classification": "failed-do-not-use",
  "artifactManifest": "manifests/clean-build-20260825.sha256"
}

根因最终定位到 U-Boot 永久补丁 hunk 计数错误：补丁声明新增 15 行，实际包含 16 行，末尾 CONFIG_CONS_INDEX=4 没有进入干净构建。板卡实际使用 UART3，而构建结果回到了 UART0，因此 installer 是否运行无法被预期串口观测和验收。

提交 d1eedf7 修正 patch hunk，并新增两个门禁：

检查永久补丁中保留 CONFIG_CONS_INDEX=4；
检查最终构建配置确实使用 UART3。

这次失败说明：make all 成功和本地 fail=0 都不是上板成功。

记录五：硬件基线复验

选择已知硬件验证 bundle 的确切 SHA-256 后，Lynx 任务得到：

{
  "taskId": "mainline-1787709324680503509",
  "status": "success",
  "phase": "complete",
  "progressPct": 100.0,
  "exitCode": 0,
  "classification": "verified",
  "artifactManifest": "manifests/verified-hardware-artifacts.sha256"
}

随后 Lynx Power 对设备 5、继电器通道 6 执行两秒断电：

{"deviceId":5,"action":"power_off","status":"success","relayChannel":6}
{"deviceId":5,"action":"power_on","status":"success","relayChannel":6}

复验排除了板卡损坏、FEL 工作流整体失效等可能性，把问题重新收敛到 clean build 的源码/补丁差异。

记录六：源码重建产物最终通过

修复永久补丁并重新构建后，脱敏证据记录了完整闭环：

{"event":"installer_task","taskId":"mainline-1787715829104265529","status":"success","phase":"complete","progressPct":100.0,"exitCode":0}
{"event":"installer_evidence","markers":["LYNX_PROGRESS phase=installer_complete progress=100","MAINLINE INSTALL COMPLETE","Trying to boot from sunxi SPI","VFS: Mounted root (ubifs filesystem)","t113s3pro-mainline login:"],"result":"warm-reboot-pass"}
{"event":"power","controller":"lynx_power","deviceId":5,"channel":6,"action":"power_off","status":"success"}
{"event":"power","controller":"lynx_power","deviceId":5,"channel":6,"action":"power_on","status":"success","offIntervalSeconds":3}
{"event":"cold_boot_evidence","markers":["UBIFS: mounted UBI device 0, volume 0, name rootfs","VFS: Mounted root (ubifs filesystem) on device 0:15","t113s3pro-mainline login:"],"result":"cold-boot-pass"}

第二轮断电间隔为两秒，也再次到达登录提示。由此，manifests/hardware-verified-source-rebuild-20260825.sha256 对应的产物才被晋升为 hardware-verified。

真实冷启动 UART 片段

以下内容摘自 logs/final-cold-boot.log：

Trying to boot from sunxi SPI
U-Boot 2026.07 (Aug 25 2026 - 07:00:31 -0400) DshanPi T113S3 Pro
Verifying Hash Integrity ... sha256+ OK
spi-nand spi0.0: Winbond SPI NAND was found.
UBIFS (ubi0:0): UBIFS: mounted UBI device 0, volume 0, name "rootfs"
VFS: Mounted root (ubifs filesystem) on device 0:15.
DshanPi T113S3 Pro - mainline Buildroot
t113s3pro-mainline login:

DshanPi 是当前源码和运行时字符串中的项目名称，目标硬件仍是本手册定义的 100ASK T113S3 Pro。

其他真实问题与对应修复

现象	真实原因	永久处理
VM 中 USB initialization failed	FEL 设备仍属于宿主机	将 `1f3a:efe8` 显式连接到 Ubuntu guest
`Unknown boot source 4`	R528 把 SPI NAND 报告为介质值 4	U-Boot 增加该值的 SPI NAND 映射
`Loading Environment` 时复位	尝试读取不存在或不兼容的持久环境	使用 `CONFIG_ENV_IS_NOWHERE`
U-Boot NAND 读取全 `ff`	U-Boot proper 强制 quad read 不适配该路径	U-Boot 专用 DTS 使用单线读取
`ubi.mtd=rootfs` 挂载失败	`rootfs` 是 UBI volume，不是 MTD 分区	改为 `ubi.mtd=sys root=ubi0:rootfs`
手动 `setenv` 能启动	只证明临时参数有效	永久修改、重建、重刷并重新冷启动

如何复查这些记录

克隆主线功能分支后可直接检查：

cd DshanPI-T113xMainlineLinux

rg 'mainline-1787708850567538011|mainline-1787715829104265529' \
  logs docs manifests

rg 'Trying to boot from sunxi SPI|Mounted root|login:' \
  logs/final-cold-boot.log

sha256sum -c manifests/hardware-verified-source-rebuild-20260825.sha256

主要证据文件：

logs/t113-task-history-20260824-25.jsonl；
logs/hardware-revalidation-20260825.jsonl；
logs/source-rebuild-hardware-validation-20260825.jsonl；
logs/final-cold-boot.log；
docs/development-journal.md；
docs/verification-status.md；
manifests/artifact-status.md。

记录更新规程

后续调试不得只在文档中追加一句“测试通过”。每次新构建至少记录：

两个仓库的 Git commit；
Buildroot、Linux 和 U-Boot 固定版本；
完整 FEL_SHA256SUMS；
Lynx/OpenixCLI 任务 ID 和退出状态；
独立 UART installer marker；
温重启结果；
至少一次受控断电冷启动；
失败产物的明确状态，禁止覆盖原记录。

汇总后的版本、哈希和结论边界见开发与验证记录。

本章目标​

什么叫“真实记录”​

调试时间线​

记录一：计划角色不匹配​

记录二：SPL 返回和 USB 重连​

记录三：串口监控被旁路程序破坏​

记录四：本地门禁通过，但硬件 installer 没启动​

记录五：硬件基线复验​

记录六：源码重建产物最终通过​

真实冷启动 UART 片段​

其他真实问题与对应修复​

如何复查这些记录​

记录更新规程​