0.1 编写目的与读者对象

SPI NAND 在 Linux 下几乎不需要从零写驱动——内核主线已有完整的 spinand 框架与厂商器件表。真正的工作量集中在：选对内核配置、写对设备树、适配新器件、 把 UBI/UBIFS 跑通、以及量产阶段的可靠性与运维。本文把这些工作按可执行的顺序固化下来。

• 驱动工程师：按第 3~7 章完成配置、DTS、器件适配与驱动改造；按第 10 章定位问题。
• 硬件工程师：重点读第 2 章（原理图 / 电源 / 测试点 / BOM 约束）与第 5 章（reset-gpio、pinctrl、供电绑定）。
• 测试工程师：按第 9 章执行功能 / 压力 / 性能 / 回归四项测试，按第 17 章核查清单验收。
• 量产与运维：按第 6 章做产线烧录，按第 15 章做日志采集、坏块监控与 A/B 分区 OTA。

一句话结论：SPI NAND 在 Linux 里的「驱动开发」，本质是 把器件能力（ID / 页大小 / OOB 布局 / ECC 强度 / 命令变体）正确喂给 spinand 框架， 再把 MTD → UBI → UBIFS 这条链路打通；剩下的 80% 工作量在设备树、分区表、bootargs、 量产烧录与可靠性验证上，而不是在 drivers/mtd/nand/spi/ 里写新代码。

0.2 术语与缩略语

下表是本文（以及内核 MTD 邮件列表、datasheet）里高频出现的词。驱动调试时大量日志来自这些子系统， 先建立词与层级的对应关系，能省掉一半读日志的时间。

0.3 内核版本与 MTD 接口差异

MTD 子系统在 4.x → 5.x → 6.x 之间做过多次重构，照抄旧教程会直接编译不过或行为异常。 下表按版本给出关键差异，适配前先确认自己的内核基线。

0.4 硬件平台与参考器件

本文以「ARM SoC + 板载 SPI NAND」为基准平台。驱动视角下，硬件只需要落实三件事： SPI 控制器接在哪个片选、器件供电域是多少、RESET#/WP# 是否可控。

1 · 前置知识依赖

动手改驱动之前，先确认四类前置知识齐备：内核驱动模型、Flash 物理原理、交叉编译环境、调试环境。 这四项任何一项缺失，后面每调试一个问题都会多花一倍时间。

1.1 Linux 内核驱动基础

SPI NAND 驱动落在「SPI 总线 + MTD 子系统」的交叉点上，需要理解的概念可以收敛到下面几条：

1.2 Flash 基础原理

SPI NAND 保留了 NAND 的全部物理约束，只是把并行总线换成了 SPI。下面这些概念在后面每一章都会反复出现：

1.3 交叉编译与内核构建环境

下图给出一条标准的「源码 → 镜像 → 部署」流水线。关键是四条产物各自独立： 内核镜像、设备树 blob、内核模块、rootfs 镜像，任何一条没更新都会表现为「改了没生效」。

最小可用构建命令

# 1) 内核（以 arm64 为例；ARCH/CROSS_COMPILE 按平台替换）
export ARCH=arm64
export CROSS_COMPILE=aarch64-linux-gnu-
make <soc>_defconfig
make menuconfig          # 按第 3 章勾选 MTD / SPI_NAND / UBI / UBIFS
make -j$(nproc) Image dtbs modules
make modules_install INSTALL_MOD_PATH=./_install

# 2) 设备树单独编译（改 DTS 后只需重编 dtb，秒级）
make dtbs
# 或单文件反编译排查：dtc -I dtb -O dts board.dtb -o board.dts

# 3) 检查设备树语法
dtc -I dts -O dtb -o /dev/null arch/arm64/boot/dts/<vendor>/board.dts

1.4 开发环境：SDK 构建与 TFTP / NFS 调试环境

SPI NAND 项目通常是整机构建（Bootloader + Kernel + Rootfs），推荐先用 SDK（Buildroot / Yocto） 统一产出，再用 TFTP/NFS 做快速迭代。

2 · 硬件设计规范（驱动视角）

驱动工程师不需要画原理图，但必须能读懂原理图并指出哪些地方会让驱动跑不起来。 本章只讲与驱动行为直接相关的硬件约定；器件级电气参数与封装以《SPI NAND Flash 电路设计指南》与 datasheet 为准。

2.1 原理图设计要点

2.2 电源设计

2.3 硬件信号测试标准

2.4 必留测试点

板子回来看不到信号就没法联调。下面这张图是硬件必须提供的最小测试点集合， 新板评审时按图核对。

2.5 BOM 选型约束

不同品牌、不同系列的 SPI NAND 在页大小、OOB 大小、ECC 强度、命令集、QE 位位置上并不一致。 驱动侧的器件表就是为这些差异准备的——选型阶段就要把能力表定下来。

3 · 内核配置与编译构建

SPI NAND 在内核里是一个「开开关」的问题：把 MTD、spinand、UBI、UBIFS 四项开对， 器件就能被识别。本章给出完整可勾选的 config 清单、内置/模块两种编译方式，以及 U-Boot 侧配套配置。

3.1 内核 config 配置项清单

必选项（缺一不可）

# —— SPI 侧 ——
CONFIG_SPI=y                       # SPI 总线核心
CONFIG_SPI_MASTER=y                # （部分内核版本中与 SPI 合并）
CONFIG_SPI_MEM=y                   # spi-mem 抽象层（通常被自动 select）
CONFIG_SPI_<YOUR_SOC>=y            # 具体 SoC 的 SPI 控制器驱动（如 CONFIG_SPI_PL022 / CONFIG_SPI_SUNXI 等）

# —— MTD / SPI NAND ——
CONFIG_MTD=y
CONFIG_MTD_SPI_NAND=y              # 或 =m，产出 spinand.ko
CONFIG_MTD_NAND_CORE=y             # 被 MTD_SPI_NAND 自动 select
CONFIG_MTD_OOPS=y                  # 可选：panic 时把日志写进 Flash，对量产排查很有用

# —— UBI / UBIFS ——
CONFIG_MTD_UBI=y
CONFIG_MTD_UBI_FASTMAP=y           # 强烈建议：attach 时间从数十秒降到秒级
CONFIG_MTD_UBI_GLUEBI=m            # 可选：把 UBI 卷再暴露成 MTD（很少用，按需）
CONFIG_UBIFS_FS=y
CONFIG_UBIFS_FS_ZSTD=y             # 可选：压缩算法（另有 LZO / ZLIB）

# —— 分区表 ——
CONFIG_MTD_OF_PARTS=y              # 设备树 fixed-partitions（推荐）
# CONFIG_MTD_CMDLINE_PARTS=y       # 二选一：命令行 mtdparts（老方案）

调试用选项（问题定位时打开，量产后关闭）

CONFIG_MTD_TESTS=m                 # mtd_nandecctest / mtd_pagetest 等内核自测模块
CONFIG_MTD_UBI_DEBUG=y             # UBI 内部详细日志（部分版本提供）
CONFIG_MTD_UBI_DEBUG_MSG=y
CONFIG_MTD_UBI_DEBUG_PARANOID=y
CONFIG_UBIFS_FS_DEBUG=y            # UBIFS 断言与调试统计
CONFIG_UBIFS_FS_DEBUG_CHKS=y
CONFIG_DYNAMIC_DEBUG=y             # 【关键】dynamic_debug 的前提，见 10.1
CONFIG_DEBUG_FS=y                  # debugfs，ubi/ubifs 的统计都在下面
CONFIG_MAGIC_SYSRQ=y               # 掉电测试时手动触发 sync / 重启

3.2 内置进内核 vs 编译成 ko 模块

# 模块方式常用命令
make M=drivers/mtd/nand/spi modules          # 只编 spinand 模块（秒级）
adb push spinand.ko /tmp/                    # 或用 scp / NFS
insmod /lib/modules/$(uname -r)/kernel/drivers/mtd/nand/spi/spinand.ko
rmmod  spinand
modinfo spinand                              # 看依赖与参数
depmod -a                                    # 重建依赖表后可用 modprobe spinand

3.3 DTS 编译与设备树 overlay

# 全量编译设备树
make dtbs
# 单文件编译（快）
cpp -nostdinc -I include -I arch -undef -x assembler-with-cpp board.dts board.dts.pre
dtc -I dts -O dtb board.dts.pre -o board.dtb

# 反编译已生效的 dtb（排查「到底生效了哪棵树」）
dtc -I dtb -O dts /sys/firmware/fdt -o running.dts

# 运行时确认（比反编译更直接）
ls /sys/firmware/devicetree/base/
find /sys/firmware/devicetree/base -name compatible | xargs grep -l spi-nand

3.4 Rootfs 构建：mtd-utils 工具包

没有 mtd-utils 就没有调试手段。无论 Buildroot 还是 Yocto，这个包必须进 rootfs。

# Buildroot
make menuconfig
  Target packages  --->  Hardware handling  --->
      [*] mtd-utils           # 含 flash_erase / nanddump / nandwrite / mtd_debug
      [*]   ubi health        # ubiattach / ubimkvol / ubiformat / ubinize ...
# 或直接写 defconfig
echo 'BR2_PACKAGE_MTD_UTILS=y' >> configs/board_defconfig

# Yocto
IMAGE_INSTALL:append = " mtd-utils mtd-utils-ubifs"

# 主机侧（做镜像用，通常 apt 安装）
sudo apt install mtd-utils

3.5 U-Boot 配套配置

U-Boot 需要能读 SPI NAND，才能把内核 / dtb / UBI 镜像加载起来。U-Boot 与内核用的是同一套 spinand 代码（U-Boot 会周期性从 Linux 同步），但配置开关名字不同。

# U-Boot defconfig 必开项
CONFIG_MTD=y
CONFIG_MTD_SPI_NAND=y          # U-Boot 侧 spinand 框架
CONFIG_SPI=y
CONFIG_DM_SPI=y
CONFIG_SPI_MEM=y
CONFIG_CMD_MTD=y               # mtd list / mtd read / mtd write / mtd erase
CONFIG_CMD_UBI=y               # ubi part / ubi attach
CONFIG_CMD_UBIFS=y             # ubifsmount / ubifsload / ubifsls
CONFIG_CMD_SF=y                # （SPI NOR 用，NAND 场景可选）
CONFIG_ENV_IS_IN_UBI=y         # 环境变量存 UBI 卷（可选）
CONFIG_SPL_SPI_NAND_SUPPORT=y  # 若由 SPL 从 SPI NAND 加载 U-Boot

4 · 驱动架构与代码框架

本章回答「内核里到底有哪些代码在跑」。读完应当能定位任意一个问题落在哪一层， 以及新器件适配时要改哪个文件、填哪张表。

4.1 软件分层总览

SPI NAND 的完整链路是 UBIFS → UBI → MTD → NAND core → spinand → spi-mem → SPI 控制器 → 器件。 其中「自己写的代码」通常只占最下面两层中的厂商 ops 部分。

4.2 源码目录与文件职责

4.3 关键数据结构

下面三个（组）结构是所有适配工作的落点。字段名随内核版本有变化， 动手前请以手上源码的 include/linux/mtd/spinand.h 为准。

/* 典型厂商器件表条目（示意，字段名以实际内核为准） */
static const struct spinand_info xtx_spinand_table[] = {
    SPINAND_INFO("XT26G01D",
                 SPINAND_ID(SPINAND_READID_METHOD_OPCODE_DUMMY, 0xE1),
                 NAND_MEMORG(1, 2048, 128, 64, 1024, 1, 1, 1),  /* luns, pagesize, oobsize, pages_per_eraseblock(64), blocks_per_lun, planes, ... */
                 NAND_ECCREQ(8, 512),          /* On-Die ECC: 8bit / 512B */
                 SPINAND_INFO_OP_VARIANTS(&read_cache_variants,
                                          &write_cache_variants,
                                          &update_cache_variants),
                 0,
                 SPINAND_ECCINFO(&xt26xxxd_ooblayout,
                                 xt26xxxd_ecc_get_status)),
};

const struct spinand_manufacturer xtx_spinand_manufacturer = {
    .id    = SPINAND_MFR_XTX,       /* 0x0B */
    .name  = "XTX",
    .chips = xtx_spinand_table,
    .nchips = ARRAY_SIZE(xtx_spinand_table),
    .ops   = &xtx_spinand_manuf_ops,
};

4.4 probe 执行流程

下图是 spinand_probe() 的主干。理解它之后，「设备树写了但没出 mtd 设备」这类问题可以逐步对位。

各阶段失败时的典型日志与判据

4.5 页 / OOB / ECC 布局与 UBI 开销

理解这张图，就能解释「为什么 128MB 的器件格式化成 UBI 后只剩 100 多 MB 可用」。

4.6 中断与 DMA

SPI NAND 走的是 SPI 控制器，没有 NAND 控制器那种专用中断。性能优化与稳定性问题基本都落在 SPI 控制器的 DMA 与 FIFO 行为上。

4.7 编码规范与 remove 函数

1. checkpatch 必过：./scripts/checkpatch.pl --strict --no-tree 0001-*.patch；upstream 提交对 --strict 也要求零 error。
2. 错误处理走 goto 链：内核惯例，出错时按资源申请的反序释放，不要用「一路 return + 每层重复释放」。
3. 优先 devm_* 系列：devm_kzalloc / devm_gpiod_get 等，remove 时自动释放，减少漏释放。
4. remove 与 probe 严格对称：probe 里申请的每一份资源都要有对应释放；rmmod 后再 insmod 必须能正常工作（这是最有效的自测）。
5. 日志等级克制：正常路径用 dev_dbg（由 dynamic_debug 控制），异常才用 dev_err；量产日志里刷屏的 dev_info 要清掉。
6. 提交粒度：一个 patch 做一件事；新增器件、修 bug、改格式分成三个 patch。
7. Signed-off-by 必带：git commit -s，否则 upstream 不接受。

/* remove 与 probe 对称的典型写法（示意） */
static int spinand_remove(struct spi_mem *mem)
{
    struct spinand_device *spinand = spi_mem_get_drvdata(mem);
    int ret;

    ret = mtd_device_unregister(&spinand->base.mtd);
    if (ret)
        return ret;

    nanddev_cleanup(&spinand->base);
    kfree(spinand->scratchbuf);
    /* devm_* 申请的资源无需在此释放 */
    return 0;
}

/* 自测：反复加载卸载 20 次不应有内存泄漏或 oops */
# for i in $(seq 1 20); do modprobe spinand; rmmod spinand; done; dmesg | tail