这份文档的核心主张：并口 NAND 在 Linux 下有现成的主线框架可走，先确认你的 SoC 有没有硬件 NFC 控制器。有就走厂商 host 驱动，没有就用主线的 gpio-control-nand，两条路都不通才需要自研——自研的代价（DMA、超时、并发、掉电保护）远大于多数人预期。本文把「什么时候必须自研」「自研要付多少代价」写清楚，而不是鼓励自研。

这份文档解决什么

并口 NAND（也写作 PPI NAND / Parallel NAND / Raw NAND）是容量与成本最优的一类非易失存储，在工控、路由器、IoT 网关、国产化替代的主控板上大量使用。但和 eMMC、SD NAND 不同，它在 Linux 里没有一个「插上就能用」的通用块设备路径：内核只提供 MTD 框架和几套 host 驱动，剩下的要靠设备树和几何表说清楚。

本文回答的问题：

• PPI NAND 和 SPI NAND 到底差在哪，为什么驱动不能互相套用；
• 你的项目应该走哪条控制器路线，各自的代价是什么；
• 设备树怎么写、哪些属性是必填、常见错法长什么样；
• ECC 引擎怎么选、OOB 怎么排、XTX XT27G02A/B 的坏块标记为什么不在 OOB 里；
• UBI 的 min_io_size 对齐陷阱，以及 UBIFS 参数怎么算；
• 出现「探测不到」「ECC 报错」「UBI attach 失败」时怎么定位。

读者路径

1 · 先把事实说清楚

在写第一行驱动代码之前，有四件事必须先确定： 它在物理上是什么、它在 Linux 里以什么形态存在、它和本系列其它器件差在哪、 以及它的可靠性责任归谁。这四件事里有任何一件搞错， 后面所有的工作都会建立在一个错误的前提上，而这种错误的代价往往要到量产才暴露。

1.1 并口 NAND 到底是什么：一颗没有封装外壳的 SPI Flash

先把这个比喻说清楚，因为它能省掉后面很多困惑。 并口 NAND 与 SPI NAND 的关系，好比「并口硬盘」与「USB 硬盘」： 里面都是 NAND 存储阵列 + 一颗片内控制器，差别只在外面怎么接线、 主机怎么跟它说话。

「并口」指的是数据总线直接挂在芯片引脚上，典型 x8（8 根数据线） 或 x16（16 根），加上 CLE、ALE、CE#、WE#、RE#、R/B#、WP# 共 7 根控制线， 一共 15~23 根信号。主机通过这套并行接口逐字节地把命令、地址、数据打进器件。 「SPI」则是把这套接口串行化成 4 根线（SCLK、MOSI、MISO、CS）， 代价是带宽低，换来的是布线简单、能跑高时钟。

1.2 Linux 主线的位置：MTD/rawnand，不是块设备

这是并口 NAND 在 Linux 里最容易被误解的一点，也是一系列后续困惑的根源。 在 Linux 里，并口 NAND 不是块设备。 内核不会给它创建 /dev/sda 这样的节点， 也不会把它挂成某种可以直接 mount 的普通文件系统。

它挂在 MTD（Memory Technology Device） 子系统下面， 对外表现为两种设备：

内核里的实现路径是：drivers/mtd/nand/（6.5 起为 drivers/mtd/nand/raw/）里的 rawnand 框架， 加上 SoC 厂商的 host 驱动（或主线的 gpio-control-nand）。 rawnand 之上可选地叠 UBI 与 UBIFS，得到一个真正的文件系统。 这五层的责任划分，是理解后面所有章节的基础。

1.3 三条技术路线与本系列其它器件的根本差异

Linux 生态里有四类主流的非易失 Flash：SPI NOR、SPI NAND、PPI NAND、SD NAND（eMMC 那一类）。 它们在主机侧的接口形态完全不同，驱动代码不能互相套用。 这也是本系列每类器件单独出一份指南的原因。

把这张表横着看，可以得到三条最容易被忽略的差异：

差异一：OOB 是并口与 SPI NAND 独有的

SPI NOR 与 SD NAND 都不暴露 OOB 概念——它们的数据是连续字节流，主机读写 「地址 + 长度」就完事。而 PPI NAND 与 SPI NAND 每一页尾部都带一段 OOB （也叫 Spare Area），用来存 ECC 字节、坏块标记、厂商元数据。 OOB 的存在让「读一页」变成了「读主区 + 读 OOB」两个动作， 而两者的读取方式在硬件上并不相同——这正是第 4 章 exec_op 模型要解决的问题。

差异二：SPI NOR 与 SD NAND 没有坏块概念

SPI NOR 是 NOR 结构，擦写单位是整个扇区，没有「块」这个中间层级， 因此不需要坏块管理。SD NAND 与 eMMC 有片内 FTL，把坏块与磨损均衡全包了， 主机看到的是一个干净的块设备。只有 PPI NAND 与 SPI NAND 需要主机操心坏块， 而这两者的坏块标记位置还互不相同（一个是 OOB 首位，一个可能别的地方）， 这也是第 8 章要专门讲一节的原因。

差异三：SD NAND 有一个「能用的块设备」，PPI NAND 没有

这是选型时最实际的差别。SD NAND 插上就是块设备，格式化即用； PPI NAND 插上是一堆 /dev/mtdN，要自己决定用不用 UBI、用什么文件系统。 前者是「集成成本低但单价高」，后者是「单价低但集成工作量大」。 本文档要讲清楚的，就是这部分集成工作的具体内容与代价。

2 · 器件与接口面

在讨论任何驱动代码之前，先把器件这一侧的「事实」摆清楚。驱动里所有的几何表、时参数、坏块偏移都来自本章，而这些值一旦错了，症状往往是「能识别但数据错」，比「识别不到」难查得多。

2.1 PPI NAND 的关键几何与能力参数

「几何」指器件的物理组织结构。内核靠一组几何参数把「行地址 / 列地址」翻译成「第几块第几页」，所有几何参数都直接来自器件 datasheet 或 Read ID 后的能力表，不能猜。

2.2 引脚与信号面：x8 与 x16 的差别在哪

「x8」「x16」指数据总线宽度：x8 是 I/O0~I/O7 共 8 根，x16 是 I/O0~I/O15 共 16 根。在设备树里体现为 nand-bus-width 取 8 或 16。这不只是「多几根线」：

2.3 ONFI 异步命令集与时序前提

ONFI（Open NAND Flash Interface）定义了并行 NAND 的标准命令集，绝大多数市面器件在基础命令上兼容 ONFI，扩展命令各家自定义。内核里没有一份「ONFI 命令表」可以直接填，几何与命令语义是通过 struct nand_chip 的能力表和 host 驱动的 exec_op 回调共同表达的。

上表数值为 ONFI 异步 Mode 0 的典型要求，具体到你的器件必须以 datasheet 为准。注意 tR / tPROG / tBERS 这三项由器件内部决定，主机无法加速，只能等。

2.4 芯天下 XTX XT27G02A / XT27G02B 型号对照

本系列器件在 Linux 侧使用时的关键差异点集中如下。这些值覆盖本章的通用表述，落地时以本表替换第 2.1 / 2.3 节的示例值。

3 · 硬件前提核查

这一章全是「动手前要确认的事」。 每一条都对应一类在软件层无法补救的问题——硬件层的问题在软件里怎么绕都绕不过去，只能返板。

3.1 SoC 侧必须先确认的三件事

3.2 引脚连接、电压域与上电时序

并口 NAND 的引脚分三类，各自的处理方式不同：

/* 设备树 pinctrl 示例：NAND 专用引脚组（SoC 相关，此处以通用写法示意） */
&pinctrl_nand {
    nand_ctrl_default: nand_ctrl {
        /* 数据线：复用为 NAND 数据总线，不是普通 GPIO */
        pinmux_ /* 以实际 SoC 的 PINMUX 宏为准 */;
    };
};

/* IO 电压域设置（示意，寄存器名因 SoC 而异） */
/* 将 NAND 所在 Bank 设为 3.3 V 或 3.3 V_HDR */

3.3 R/B# 上拉与就绪判定：最容易翻车的一根线

R/B# 是整条并口接口里信息量最大、也最容易出问题的一根线。 它把「器件内部忙不忙」这件事直接给出来，让主机可以被动等待而不是猜时间。

3.4 布线与信号完整性要点

• 数据线与控制线分开走：I/O0~7 与 CLE/ALE/RE#/WE# 分层或分开走线， 避免 RE# 串扰到数据线上（表现为随机位翻转，ECC 报可纠正错误）；
• 等长要求：x8 情况下数据线之间建议不超过 5 mm 长度差， 这是 x8 与 x16 唯一真正需要匹配的信号组；
• R/B# 单独走线：这根线上的任何毛刺都会让主机误判已完成；
• 去耦电容：器件 VCC 引脚正下方放 1 只 100 nF 加 1 只 1 uF； 并口 NAND 阵列操作电流跳变大，供电不足表现为随机 ECC 错误；
• CE# 与 WP# 上拉：虽然常态由 SoC 驱动为确定电平， 建议各加 10 kΩ 上拉，保证 SoC 复位与高阻期间器件仍处于安全态；
• 避免测试点与长支线：在 RE# 与 WE# 上加测试点要评估支线电感， 50 mm 支线在 40 MHz 以上的时序下可能接近四分之一波长；

4 · MTD / rawnand 子系统解剖

这一章是「看懂内核」的部分。 如果你只是照抄设备树就能跑通，可以跳过；但如果你要自研 host 驱动，或者要 debug 到底层， 这章决定了你能走多远。

4.1 三层结构与完整调用链

Linux 的裸 NAND 支持可以理解成三个互不重叠的抽象：

1. mtd_info：对上层（VFS、UBI、mtdblock）暴露的统一接口。 提供 read、write、erase、point、lock、unlock、block_isbad 七个语义。 上层只认这个结构，不关心底下是 NAND 还是 NOR。
2. nand_chip：描述「这是一颗什么样的 NAND」。 包含几何（pagesize、oobsize、erasesize、numblocks）、 特性位（options）、函数指针（ecc、badblock、dev_ready）、 以及最关键的 ops->exec_op 指令执行器。
3. nand_controller：描述「怎么驱动这颗 NAND」。 由 host 驱动提供 exec_op() 和 attach_chip() 两个回调。 内核 6.5 之后 rawnand 全面转向 exec_op 模型， 老式的 cmd_ctrl()、read_buf()、write_buf() 已被移除。

/* 核心构造的指令序列（简化示意，主机侧看到的形态） */
struct nand_operation op = {
    .type = NAND_OP_PAGE_READ,       /* 高层语义，核心负责展开 */
    .instrs = {
        { .type = NAND_OP_CMD_INSTR,  .ctx.cmd.opcode = NAND_CMD_READ0 },  /* 00h */
        { .type = NAND_OP_ADDR_INSTR, .ctx.addr.naddrs = 5,
          .ctx.addr.addrs  = { col_lo, col_hi, row0, row1, row2 } },
        { .type = NAND_OP_CMD_INSTR,  .ctx.cmd.opcode = NAND_CMD_READ30 }, /* 30h */
        { .type = NAND_OP_WAITRDY_INSTR, .ctx.waitrdy.timeout_ms = 100 },
        { .type = NAND_OP_DATA_INSTR,  .len = 2048, .buf = buf },
        { .type = NAND_OP_CMD_INSTR,  .ctx.cmd.opcode = NAND_CMD_READ30 }, /* 随机读换页 */
    },
    .ecc = &ecc_op,                   /* 让核心决定在哪一步插 ECC 引擎操作 */
};
this->ops->exec_op(this, &op, check_only);

4.2 nand_scan 探测时序逐拍

nand_scan() 是核心的探测入口，host 驱动在 probe 里调用它。 它做的事按顺序是：复位、读 ID、查 idt 表、装载能力表、 （可选）读 ONFI 参数页交叉校验、重新复位、填超时值、扫描坏块、建立 mtd_info、解析分区。

驱动在这个过程里唯一必须提供的是：

• 一个 struct nand_controller，含 exec_op 回调；
• 把几何的初始猜测写进 chip->parameters（可选， 有 idt 表命中时会被覆盖）；
• 如果器件不在 idt 表里，attach_chip() 回调里手工填能力表。

/* 在自研或修改后的 host 驱动里，为 XTX XT27G02A 装载能力表（示意） */
static int my_nand_attach_chip(struct nand_chip *chip)
{
    /* 先让核心走默认流程，若有匹配则直接返回 */
    int ret = nand_attach_chip(chip);
    if (ret == 0)
        return 0;

    /* 手工装载：XT27G02A —— 2048+128，64 页每块，128 KiB 每块，5 地址周期 */
    chip->mtd._point.phys_erase_size = 128 * 1024;   /* 块大小 128 KiB */
    chip->mtd._point.phys_block_size = 128 * 1024;
    chip->mtd._point.phys_page_size  = 2176;         /* 2048 Main + 128 Spare */
    chip->mtd.oobsize  = 128;                        /* Spare / OOB 大小 */
    chip->mtd.writesize = 2048;                       /* 页数据区大小 */
    chip->mtd.subpage_size = 2048;                   /* 2048 需整页写 */
    chip->mtd.eraseblock_size = 64;                  /* 每块页数 */
    chip->mtd.nr_banks = 1;
    chip->chip_delay = 20;                           /* tR，宿主要求的额外等待 */
    chip->ecc.algo    = NAND_ECC_ALGO_BCH;           /* 主机侧 ECC */
    chip->ecc.step_size = 544;                       /* 8 bit 每 544 B */
    chip->ecc.strength  = 8;
    chip->ecc.engine_type = NAND_ECC_ENGINE_TYPE_SOFT;
    chip->onfi_chip     = 0;                         /* 非 ONFI：不读 ECh */
    return 0;
}

4.3 关键结构体与移植接口

/* 一份最小可用的 nand_controller（示意） */
static const struct nand_controller_ops my_ops = {
    /* 把一条 nand_operation 落到总线上。这是唯一必须实现的回调。 */
    .exec_op = my_exec_op,

    /* 可选：核心探测后调用，让你修正几何与能力表 */
    .attach_chip = my_attach_chip,
};

static struct nand_controller controller = {
    .ops = &my_ops,
};
/* 之后：nand_to_mtd(&controller) 得到 mtd，再 nand_scan(mtd, 1) */

4.4 源码位置速查