海思平台 · SPI NAND 量产常见失败排查

编制日期 2026-10-14 ｜ 版本号 Rev 1.0

XTX 芯天下 · FAE 现场技术文档 ｜ 海思 Hi35xx / Hi38xx / Hi3516 / Hi3559 等 SoC 外挂 SPI NAND 量产失败（启动 / 烧录 / 分区 / 挂载）｜ 2026-09 版

结论：海思平台 SPI NAND 「烧录绿勾却起不来 / 启动报错」绝大多数是 烧录侧与主控侧对器件的「认知不一致」——ID 表没收录、ECC/OOB 解释不同、坏块策略错位、分区版本不对、UBI 几何不一致。 烧录器能烧、能校验通过，只证明器件是好的、数据写进去了；不证明海思控制器能按同一套规则把它读出来。 先抓完整启动 LOG 按关键字分流，再逐类对齐参数卡。

报告总结

解决的是海思 SoC 外挂 SPI NAND 在量产阶段「绿勾后启动失败 / 启动中途报错」这一类问题的定位与根治， 覆盖 Hi35xx、Hi38xx、Hi3516、Hi3559 等系列从 BootROM → u-boot → kernel（LiteOS / OpenHarmony / Linux）整条链路。 全文按「现象 → 机制 → 类目 → 立即动作 → 根治动作」组织，第 9 章是可翻查的速查表，第 10 章是防复发的参数卡与首件检验。

怎么用这份文档

1. 先抓一份完整启动 LOG：从按下上电到卡住的全部串口输出贴出来，按第 2 章关键字把失败归到某一类，不要一上来就换芯片。
2. 存一份「已知好板」基线：把能正常启动那块板的启动日志、回读 ID、烧录工程参数、分区表各存一份，后面所有对比都拿它当基准。
3. 用第 1 章的三段断点法收敛：先确认 BootROM 是否读到 ID，再看 u-boot 是否校验过镜像，最后看 kernel 是否挂上 UBIFS——不要跳段。
4. 一次只改一个变量：SDK 器件表、ECC 强度、坏块策略、分区偏移每次只动一处，改完重新烧录 + 上电抓日志。
5. 金样对照闭环：同板换认可料一次、问题料上金板一次，确认是板级还是存储侧，再决定改烧录还是改 SDK。
6. 终判以装板实跑为准：任何改动的最终判定，是「完整启动 + 关键功能 + 一次断电重启」都通过，烧录器绿勾不能替代。

1. 问题本质：海思侧启动链路与识别机制

海思平台「烧录绿勾却起不来」这句话在现场被用得太泛。它可能是 BootROM 根本没读到 ID， 可能是 u-boot 读到了但 ECC 校验不过，也可能是 kernel 进去了却挂不上 UBIFS。 本章先把现象还原成机制：讲清海思是怎么把一颗 SPI NAND 从 BootROM 一路认到 kernel 的、 每一段失败会暴露成什么长相，然后把本文的排查对象与「烧录器找不到型号」严格切开。

1.1 三段启动链路

海思 SoC 外挂 SPI NAND 的启动是一条串行链路：BootROM 先把最前面的 SPL 搬进内部 SRAM， SPL / u-boot 再去扫整片 NAND、加载环境变量与内核镜像，kernel 最后挂载 UBIFS 跑应用。 每一段都要重新和 SPI NAND 打一次交道，任何一段对器件的「认知」和烧录时不一致，整条链就断。

1.2 海思怎么「认」一颗 SPI NAND

海思对 SPI NAND 的识别，本质是一次 「发命令 → 收结构化应答 → 查表 → 套参数」的过程：

• 读 ID：BootROM / 驱动发 9Fh（写使能 06h 后），器件回出 [厂商ID | 器件ID | 容量ID] 一串字节；
• 查表：把回读的 ID 拿去 SDK 的 spi-nand 器件表 （drivers/mtd/nand/spi/ 下）逐条匹配；
• 套参数：命中后把表里登记的页大小、OOB 大小、ECC 强度、坏块处理方式填进控制器结构体；
• 后续操作：之后所有读页（13h）、读数据（0Bh）、写、擦都按这套参数走。

关键认知在于：ID 对，不代表参数对。ID 只是查表的键，真正决定能不能读的是查表之后套上来的那一组参数 （页 / OOB 大小、ECC 强度、坏块策略）。这正是本文 7 类失败里 2~5 类全部来自「参数认知不一致」的根本原因。

1.3 与「烧录器找不到型号」的分工

产线上这两件事经常被当成同一件事处理，但发生位置、判定主体、根因集合、解决路径完全不同。 判别只有一句话：烧录器能不能正常把活干完。

1.4 先抓 LOG 再动参数

无论归到哪一类，现场第一步永远是接串口、上电、把从按下复位到卡住的完整 LOG 存下来。 海思平台在不同阶段会打出不同关键字（SPI NAND、unknown id、ECC、 ubi、bad block），这些关键字是第 2 章分流的直接依据。 没有完整 LOG 就改烧录参数，等于盲调——很可能把 5 分钟能定位的问题拖成两天的拉锯。

1.5 海思各系列外挂 SPI NAND 的差异

海思 Hi35xx / Hi38xx / Hi3516 / Hi3559 等系列都支持外挂 SPI NAND，但具体谁先启动、SPI NAND 扮演什么角色、BootROM 如何找它因系列与具体型号而异。 排查前先确认你手上是哪个系列、SPI NAND 是主启动介质还是辅助介质，否则 boot pins 与器件表的核对方向会搞反。

注意上表是常见定位的归纳，不是承诺：同一系列不同型号、同一型号不同项目，启动介质选择都可能不同。 最终以该板《硬件设计指南》的 boot 配置与 SDK 的 defconfig 为准。本文所有机制不依赖具体系列，但第 3 章「加器件表项」时必须按你这个系列的驱动路径去加。

1.6 海思 SPI NAND 控制器的 ECC 配置落在哪

海思 NAND 控制器把 ECC 强度、step size、纠错开关等放在一组控制器寄存器里， 具体寄存器名与位域因系列与 SDK 而异，以海思 TRM 与 SDK 源码为准。排查第 2 类时， 先在 SDK 里确认 nand-ecc-strength / nand-ecc-step-size 这两个关键参数—— 它们就是控制器与烧录器必须对齐的「ECC 契约」。

1.7 为什么 SPI NAND 比 NOR 更容易在量产翻车

SPI NOR 没有坏块、没有 OOB/ECC 之争，烧录器与主控看到的是同一片线性空间，参数不一致几乎无从发生。 SPI NAND 把坏块、OOB、ECC、BBT 全部暴露给主控和烧录器， 两边只要有一处默认假设不同，量产就会被放大成「绿勾不启」。这也是本文 7 类失败几乎都集中在 SPI NAND 的原因—— NOR / eMMC 没有这套暴露面，问题天然少一个数量级。

1.8 关键术语速查

第七章反复出现几个术语，先统一叫法，避免现场各说各话：

• OOB（Out-Of-Band）：每页数据之外的小块区，存 ECC 校验码、坏块标记、spare；布局必须两侧一致。
• BBT（Bad Block Table）：坏块映射表，记录哪些块不可用；烧录器与 BootROM 的策略必须一致。
• ECC：纠错码，强度（bit 数）与 step size 决定能纠多少位错；强度两侧必须相同。
• 逻辑地址 / 物理地址：逻辑是「跳过坏块后连续」的视图，物理是器件真实块号；坏块策略不同会让二者错位。
• PEB / LEB：UBI 的物理擦除块 / 逻辑擦除块，体积差一个 EC header，配置须与 SDK 一致。

2. 方案总览：分流与介质对比

海量失败现象背后，真正要做的动作其实很收敛：读 LOG、定类目、对齐参数卡。 本章给出一张分流图（按关键字直接落到第 3~8 章）和一张介质对比表（说明为什么本文聚焦 SPI NAND 而不套用 NOR / eMMC 的套路）。

2.1 分流总图

现场不要凭感觉改参数。先把完整启动 LOG 抓下来，按下面的关键字把失败归到对应章节，再去翻那一章的「立即动作」。

2.2 介质对比：为什么 SPI NAND 要单独立章

海思外挂存储常见四种介质，识别依据与失败长相差别很大，排查套路不能互相套。本文聚焦 SPI NAND， 因为它同时具备「JEDEC ID + 参数页 / 内建几何 + OOB/ECC + 坏块管理 + UBI」五重复杂度，失败类目最多。

2.3 核心动作：对齐三件套

无论归到哪一类，最终都收敛为同一件事——让烧录工程与海思 SDK对三件套达成一致：

• ID 表：SDK 的 spi-nand 器件表包含该 XTX 料号，且参数正确；
• 分区：mtdparts / bootargs 的分区偏移与烧录镜像落盘偏移是同一版本；
• ECC / 坏块：烧录器的 ECC 强度、OOB 布局、坏块跳过策略与海思 NAND 控制器一致。

三件套锁进参数卡（见第 10 章），量产才有可复现的基线。

2.4 海思烧录工具链（HiTool / hiburn）与参数一致性

海思量产常用 HiTool（Windows 图形工具）或 hiburn / 一线烧录方式把镜像写到外挂 SPI NAND。 这些工具本身不「认识」器件参数——ECC 强度、OOB 布局、坏块策略、分区偏移全部来自你导入的那份烧录工程 / XML 配置， 也就是第 3~6 章三件套的落点。工具报绿勾，只代表「按这份工程把活干完了」，绝不代表工程里的参数与海思 SDK 一致。

• 工程即参数：HiTool 工程里的「器件类型 / 页大小 / OOB / ECC / 坏块策略」选项，就是第 2 类与第 3 类失败的开关，改动前先对照参数卡。
• 一线烧录 vs 座烧：在板一线烧录受板级走线 / 电平影响，座烧不受；若座烧 OK、一线烧失败，先怀疑板级（纪律篇）而非参数。
• 版本一致性：HiTool 工程版本、SDK 版本、烧录器算法库版本要写在同一张参数卡上，避免「换电脑就换行为」。

2.5 样例启动 LOG 解读

下面是一段示意启动 LOG，标注了第 2 章分流会用到的关键字。真实 LOG 以你的平台与 SDK 为准，不要逐字对照。

# BootROM 阶段
SPI NAND: unknown id (0b 21 00)        # ← 第 1 类：器件表未收录
# u-boot 阶段
Loading Environment from SPI NAND ...
ubi: reading page 0x10 ... ECC error     # ← 第 2 类：ECC / OOB 不一致
# kernel 阶段
ubi_attach: bad EC header at PEB 12     # ← 第 5 类（上游多为第 2 类）
VFS: Cannot open root device "ubi0"     # ← 第 4 / 5 类：分区或 UBI 错位
Kernel panic - not syncing              # ← 最终表现（线索在上面）

2.6 烧录侧与主控侧视角对照小结

3. 第 1 类：SPI NAND ID 未收录

现象：烧录器一切正常（能建工程、能烧、能校验通过），但板子上电后 BootROM / u-boot 报 unknown ID、No SPI NAND、unrecognized JEDEC id。 根因几乎总是海思 SDK 的 spi-nand 器件表没有这个 XTX 料号——器件是好的，只是主控的「花名册」里没它。

3.1 原理

海思读 ID 后，会用回读的 [MID|DID|容量] 去 drivers/mtd/nand/spi/ 下的器件表逐条匹配。 命中了才把页大小、OOB、ECC、坏块策略套进来；没命中就退回默认参数或直接放弃，表现成 unknown ID。 换料号（如新导入 XT25Q08D）却没同步更新 SDK 器件表，是这一类最高发的触发动作。

3.2 立即动作（产线止血）

1. 回读 ID 字节：在 u-boot 命令行用 sf probe / 平台提供的 nand 工具读 ID，记下 MID|DID|容量。
2. 比对 SDK 器件表：在 drivers/mtd/nand/spi/ 与 u-boot-*/drivers/mtd/spi-nand/ 里搜该 ID，确认是否缺项。
3. 临时对照烧录：若有「官方推荐烧录方式 / 金样板工程」，先用它烧一片验证能否启动，隔离是 SDK 还是烧录问题。
4. 金样对照：同板换一颗已收录的 XTX 料号（如 XT25F08B 在表中），能启 → 锁定是「未收录」。

3.3 根治动作（长效）

• 加器件表项：按 datasheet 把该料号的页大小、OOB、ECC 能力、坏块策略填进 spi-nand 驱动表，必要时打 XTX 原厂提供的适配补丁。
• 核对三个位置：海思 SDK 里 BootROM 阶段、u-boot 阶段、kernel 阶段的器件表都要覆盖，缺一就会在对应阶段断链。
• 锁定参数卡：把料号 + SDK 版本 + 补丁号写进参数卡（第 10 章），下次换料号先查表。

3.4 边界与红线

3.5 读 ID 的命令时序细节

标准流程：先发 06h 写使能，再发 9Fh，随后在 SO 上连续回出若干字节 （厂商 / 器件 / 容量，部分料号支持更长的 ID 或参数页）。回读长度与顺序以 datasheet 为准。 读回值能直接区分「板级没应答」与「器件表没收录」：

• ff ff ff：器件没应答——CS# 没拉到、电平不对、或介质配错（板级，不在本文 7 类）。
• 00 00 00：总线被拉低 / 短路，或上拉缺失（板级）。
• 值对但 unknown ID：器件应答完全正常，纯器件表未收录（第 1 类本相）。

3.6 验证修复生效

• u-boot 命令行 sf probe 能列出正确型号，不再 unknown ID
• 整片上电 LOG 无 unknown id / No SPI NAND
• 同板换问题料能稳定启动（金样对照通过）
• 器件表 3 段（BootROM / u-boot / kernel）均含该料号
• 参数卡已登记料号 + SDK 补丁号，并双签

3.7 器件表项示意（以 SDK 源码为准）

/* drivers/mtd/nand/spi/xtx.c —— 示意，具体字段以 SDK 与 datasheet 为准 */
{ .id = {0x0b, 0x21}, .name = "XT25F08B",
  .pagesize = 2048, .oobsize = 64, .ecc_strength = 4, ... }

三处都要有：BootROM 阶段、u-boot 阶段、kernel 阶段的器件表，缺一就在对应阶段断链。 字段值（页 / OOB / ECC）必须与 XTX 该料号 datasheet 逐条一致，禁止照抄其它料号。

4. 第 2 类：ECC 与 OOB 布局不一致

现象：BootROM 能读到 ID（说明第 1 类已过），u-boot 加载镜像或 kernel 读页时大量报 ECC error、uncorrectable，甚至数据静默出错。根因是烧录器写 OOB 时按自己的 ECC 强度 / 布局落盘， 海思 NAND 控制器按另一套解释 OOB，两者对不上。

4.1 原理

SPI NAND 每页除数据区外还有 OOB 区，用于存放 ECC 校验码、坏块标记（BB）、 spare 等。 烧录器写 OOB 的字节划分（ECC 占多少、坏块标记放哪、其余留给谁）和 海思控制器读 OOB 的字节划分必须完全一致，否则控制器会把烧录器写的 ECC 字节当成数据、把数据当成 ECC， 读出即错位。

4.2 立即动作

1. 抓 ECC 报错 LOG：记下是「读 ECC error」还是「写 ECC error」、发生在 u-boot 还是 kernel。
2. 核对烧录器 ECC 配置：确认烧录工程里 ECC 强度 / OOB 布局选项，与海思 SDK 的 nand-ecc-* 一致。
3. 对齐 OOB 布局：按 XTX 料号 datasheet 的 OOB 建议，让烧录器与控制器用同一套 ECC 字节数 / 位置。
4. 重烧验证：改完重新烧录 + 上电，看 ECC error 是否消失。

4.3 根治动作

• 把 ECC / OOB 锁进参数卡：烧录器与 SDK 两侧的 ECC 强度、step size、OOB 布局写死，禁止产线自由改。
• 用官方推荐烧录方式对照：若有海思官方推荐的烧录工程，以其 ECC/OOB 为基准对齐。
• 交叉验证读回：烧录后用平台工具按逻辑地址读回关键区，确认 OOB 字节与预期一致。

4.4 边界

4.5 常见页 / OOB 组合（示例，以 datasheet 为准）

不同 XTX 料号的页大小、OOB 大小、ECC 能力不同，下面仅为常见取值示例，动手前必须逐料号核对 datasheet， 禁止跨料号套用。

4.6 验证修复生效

• u-boot / kernel 阶段 ECC error 消失
• 烧录工程 ECC 强度 / step = SDK 的 nand-ecc-*
• OOB 字节位置与 XTX datasheet 一致（ECC / BB / spare）
• 重烧后装板读回关键区无数据错位
• 参数卡 ECC 字段已锁定，产线不可自由改

4.7 OOB 解释错位的读回差异（示意）

# 烧录器视角 OOB（ECC 32B）：  [ECC·32][BB·2][spare·30]
# 控制器视角 OOB（ECC 28B）：  [ECC·28][BB·2][resv·34]
# 控制器读时把烧录器的 spare 前 4 B 当 ECC 校验码 → 校验失败 / 数据错位

差异往往只有几个字节，但足以让整页 ECC 不可纠。对齐的判据是：两侧 ECC 字节数、坏块标记位、spare 划分完全一致。