0.1 编写目的与读者对象

SPI NOR 在 Linux 下几乎不需要从零写驱动——主线内核已有完整的 spi-mem + spi-nor 框架、SFDP 自动探测与厂商器件表。真正的工作量集中在： 写对设备树、打开 4 字节地址模式把容量用满、适配新器件、把 JFFS2/UBI 跑通、 以及量产阶段的可靠性与运维。本文把这些工作按可执行的顺序固化下来，并把调试经验系统化。

• 驱动工程师：按第 3~7 章完成配置、DTS、大容量适配与新器件支持；按第 10 章定位问题。
• 硬件工程师：重点读第 2 章（WP#/HOLD#/RESET#、电压域、测试点）与第 6.10 节（容量只读到一半的硬件侧原因）。
• 测试工程师：按第 9 章执行功能 / 大容量专项 / 压力 / 性能测试，按第 14.2 节交付清单验收。
• 量产与运维：按第 12 章做可靠性设计，按第 15 章做日志采集、寿命监控与 A/B 分区 OTA。

一句话结论：SPI NOR 在 Linux 里的「驱动开发」，本质是 把器件能力（JEDEC ID / 容量 / 擦除粒度 / 地址宽度 / 读协议 / 保护机制）正确喂给 spi-nor 框架， 再把 MTD → 文件系统这条链路打通；80% 的工作量在设备树、4 字节地址、分区表、量产烧录与可靠性验证上， 而不是在 drivers/mtd/spi-nor/ 里写新代码。

0.2 术语与缩略语

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

0.3 内核版本与接口差异

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

# 1) 看内核版本号 Rev 1.4 -r
# 2) 看模块名与是否存在 core.o
ls /lib/modules/$(uname -r)/kernel/drivers/mtd/spi-nor/
# 6.6+ : core.ko winbond.ko gigadevice.ko ... controllers/
# 5.15 : spi-nor.ko
# 3) 看驱动打印的 banner（开 dynamic_debug 可见）
dmesg | grep -i "spi-nor\|spi_mem"

0.4 硬件平台与参考器件

本文以「ARM64 SoC + 单片 SPI NOR + 独立 SPI 控制器」为基准平台。为便于对照，列出 XTX 主力量产料号的 容量/电压/封装矩阵，调试时可在 /sys/.../spi-nor/ 下核对实际识别结果。

1 · 前置知识与开发环境

SPI NOR 的调试难度不在「写代码」，而在对器件行为与内核行为的双向理解。 本章把后续反复用到的三个前提讲清楚：器件本质、驱动基础要求、构建与调试环境。

1.1 SPI NOR 器件本质

SPI NOR Flash 是随机可读、页可编程、块可擦除的存储介质。这三句话决定了后面所有设计：

1.2 Linux 驱动基础要求

上手本文需要具备以下内核侧基础。缺失哪一块，第 10 章对应小节会额外展开：

1.3 交叉编译与构建环境

本文所有示例以 AArch64 为例，ARM32 / RISC-V 把工具链前缀换成对应即可。核心流程如下：

1. 拉 SDK / 内核源码：厂商 SDK 通常带 kernel/、u-boot/、buildroot/ 或 yocto/。本文以 Linux 6.6 为基准线。
2. 配置并交叉编译内核：

   export ARCH=arm64
   export CROSS_COMPILE=/path/to/toolchain/bin/aarch64-linux-gnu-
   make O=out mrproper
   make O=out defconfig
   # 合并板级配置片段（推荐用 scripts/kconfig/merge_config.sh）
   ./scripts/kconfig/merge_config.sh -O out out/.config board.fragment
   make O=out olddefconfig
   make O=out -j$(nproc) Image dtbs modules

3. 单独编译 MTD 工具（强烈建议静态编译，方便拷到板子上直接跑）：

   cd mtd-utils
   ./autogen.sh
   ./configure --enable-static --disable-werror \
       CROSS_COMPILE=aarch64-linux-gnu- \
       CFLAGS="-I${KERNEL_OUT/include -I${KERNEL_SRC/include}" \
       LDFLAGS="-L${KERNEL_OUT}"
   make -j$(nproc)
   # 产物：flash_erase flashcp flashdump nanddump mtdinfo ...

4. 部署到板子：scp mtd-utils/flash_* root@板子:/usr/sbin/，或打进 rootfs 镜像。
5. 设置交叉工具链环境（把日志重定向到主机，方便剪贴板）：

   # 主机侧
   picocom -b 115200 /dev/ttyUSB0 | tee boot.log
   # 或
   screen /dev/ttyUSB0 115200

1.4 调试环境搭建

调试 SPI NOR，「软件日志 + 硬件波形」双线并行效率最高。硬件侧只需三样便宜工具：

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

驱动工程师不需要画原理图，但必须能读懂原理图并指出哪些地方会让驱动跑不起来。 SPI NOR 硬件上最关键的三根线是 WP#、HOLD#、RESET#——它们决定了「写不进去」「读会停住」 这类诡异故障的物理原因。本章只讲与驱动行为直接相关的硬件约定；器件级电气参数以《SPI_NOR_Flash_电路设计指南》与 datasheet 为准。

2.1 原理图信号设计要点

2.2 WP# / HOLD# / RESET# 三根关键线

这三根线各自对应一类完全不同的软件故障。调试时按下表对号入座，可以省掉大量试错：

2.3 电压域与 IO 电平

SPI NOR 常见两个电压档：2.7~3.6V（XT25F 系列）与 1.65/1.7~2.0V（XT25Q / XT55Q 系列）。 混用是硬件评审的高频问题：

2.4 必留测试点与联调顺序

硬件联调按「先量电平、再抓波形、最后改驱动」的顺序做，不要一上来就改代码：

2.5 BOM 选型约束

3 · 内核配置与编译构建

SPI NOR 的内核配置项不多，但有两个必须打开且常被忽略的开关 （CONFIG_MTD_OF_PARTS 与 CONFIG_SPI_NOR_SFDP_RUNTIME）。本章给出可直接使用的 fragment 模板与逐项说明。

3.1 内核 config 清单

把下面内容保存为 board.fragment，用 merge_config.sh 合并：

# === SPI NOR 核心 ===
CONFIG_MTD=y
CONFIG_MTD_BLOCK=y
CONFIG_MTD_CFI=y
CONFIG_MTD_CFI_GEOMETRY=y
CONFIG_MTD_SPI_NOR=y
CONFIG_MTD_OF_PARTS=y                 # 关键：设备树 fixed-partitions 分区表
CONFIG_MTD_PARTITION=y
CONFIG_MTD_OF_IOMUX=y                 # 若用 pinctrl 绑定 flash 节点

# === SPI / spi-mem 框架 ===
CONFIG_SPI=y
CONFIG_SPI_MASTER=y
CONFIG_SPI_MEM=y                      # 关键：四段式内存操作抽象
CONFIG_SPI_LOOPBACK_TEST=y            # 建议开：spidev 自测

# === 文件系统（按实际需要裁剪） ===
CONFIG_JFFS2_FS=y
CONFIG_JFFS2_FS_WRITEBUFFER=y        # 强烈建议：写缓冲显著降低挂载时间与磨损
CONFIG_JFFS2_SUMMARY=y
CONFIG_UBIFS_FS=y
CONFIG_UBIFS_FS_ADVANCED_COMPR=y
CONFIG_UBIFS_FS_LZO=y
CONFIG_UBIFS_FS_ZLIB=y
CONFIG_SQUASHFS=y
CONFIG_SQUASHFS_ZLIB=y                # 只读 rootfs 推荐
CONFIG_SQUASHFS_FILE_DIRECT=y

# === 调试（量产前可关） ===
CONFIG_DEBUG_FS=y                     # 关键：/sys/kernel/debug/spi-nor/* 下有 params 视图
CONFIG_DYNAMIC_DEBUG=y
CONFIG_DEBUG_KERNEL=y
CONFIG_MTD_SPI_NOR_DEBUG=y            # 若存在该旧选项（旧内核用）
CONFIG_JFFS2_DEBUG=y                 # 排 JFFS2 问题时有日志（较吵）
CONFIG_MTD_CFI_GEOMETRY_DEBUG=y

# === MTD 工具需要的支持 ===
CONFIG_COMPAT=y                       # 32 位系统跑 64 位工具时需要（可选）

# 1) 内核命令行确认
cat /proc/config.gz | gunzip | grep -E "MTD_SPI_NOR|SPI_MEM|MTD_OF_PARTS|DEBUG_FS"
# 或（未开 IKCONFIG 时）在编译目录查
grep -E "CONFIG_(MTD_SPI_NOR|SPI_MEM|MTD_OF_PARTS|DEBUG_FS)" .config
# 2) 运行期确认模块与设备
lsmod | grep -i spi_nor
ls -l /dev/mtd* /dev/mtdblock* 2>/dev/null
# 3) 设备树分区是否被采纳（关键）
cat /proc/mtd

3.2 内置 vs ko 模块

# 模块方式的加载顺序
modprobe spi_mem        # 若单独编成模块
modprobe spi_nor
# 或直接 insmod 并检查依赖
modinfo spi_nor | head -5

3.3 DTS 编译与 overlay

板级 DTS 里 Flash 节点的改动频率最高（换料、加密位、4B 属性），因此建议用 overlay 而不是改主 DTS：

# 1) 把 Flash 节点抽成独立片段，便于复用
#    board/flash/xtx-spi-nor-512mbit.dtsi
&qspi0 {
    flash@0 {
        compatible = "jedec,spi-nor";
        reg = <0>;
        spi-max-frequency = <104000000>;
        spi-rx-bus-width = <4>;
        spi-tx-bus-width = <4>;
    };
};

# 2) 编译设备树
make O=out ARCH=arm64 dtbs
# 产物：out/arch/arm64/boot/dts/<厂商>/<板子>.dtb

# 3) 反查 DTB 里的实际内容（验证语法与继承是否正确）
dtc -I dtb -O dts out/arch/arm64/boot/dts/<厂商>/<板子>.dtb | grep -A 20 "flash@0"

# 4) 启动时确认内核收到的是同一个 dtb
cat /proc/device-tree/$(cat /proc/device-tree/aliases)/spi*/flash@0/compatible; echo

3.4 Rootfs 与 mtd-utils

SPI NOR 上放什么，取决于启动方案。三种典型形态：

Rootfs 里必须包含的工具：

• mtd-utils：mtdinfo / flash_erase / flashcp / flashdump / nanddump（NOR 上也能用做只读 dump）。
• e2fsprogs：mkfs.jffs2 / jffs2dump / jffs2loader（flashcp -j 写 JFFS2 镜像时需要）。
• mtd-utils-ubifs：mkfs.ubifs / ubinize（用 UBI 方案时）。
• mtdinfo 替代品：cat /proc/mtd 任何时候可用，做自动化脚本时优先用它。

3.5 U-Boot 配套配置

U-Boot 与内核必须在三处保持一致（详见 5.3）。与 SPI NOR 相关的 U-Boot 配置：

# ===== U-Boot Kconfig =====
CONFIG_MTD_NOR_FLASH=y
CONFIG_SPI_FLASH=y
CONFIG_SPI_FLASH_MTD=y          # 让 sf 命令走 MTD 框架，分区表与内核统一
CONFIG_CMD_SF=y
CONFIG_CMD_SF_TEST=y            # sf test 可做全盘擦写校验，产线自检很有用
CONFIG_ENV_IS_IN_SPI_FLASH=y
CONFIG_SPI_FLASH_SHOW_PROGRESS=y

# DT 中给 U-Boot 用的快读使能（非标准属性，注意厂商差异）
# 很多平台用 m25p,fast-read 打开 0x0B 快读；具体看该平台 U-Boot 代码

4 · 驱动架构与代码框架

理解 spi-nor 框架的内部结构，是能读懂 dmesg 报错、能写对 vendor patch、 能判断「内核认为器件是什么」的前提。本章按「分层 → 文件 → probe 流程 → 结构体 → SFDP → 三条路径」的顺序展开。

4.1 软件分层总览

4.2 源码目录与文件职责

以 6.6 / 6.12 为例（5.15 及以前只有 spi-nor.c 单文件，逻辑都在一起）：

4.3 probe 执行全流程

4.4 关键结构体与 flags

调试时最常查的是 struct spi_nor 的几个字段与 SNOR_F_* 标志位。 下表按「与 >128Mbit 相关」的程度排序，6.x 内核源码为准：

4.5 SFDP 解析与能力协商

SFDP（0x5A 命令）是 JESD216 定义的自描述参数表，内核优先依赖它， ID 表只是「SFDP 不可靠时的兜底」。理解 SFDP 是做大容量适配的前提：

4.6 读/写/擦三条路径

三条路径都由 spi_mem_exec_op() 执行，区别只在「opcode + 地址字节数 + dummy + 数据方向」：

4.7 编码规范与 remove

需要改内核代码时（加 ID 表条目、加 fixups），遵守以下规范，避免被 maintainer 打回：

• 注释用英文，且说明「为什么」不只「是什么」。引用 datasheet 章节号与页码，例如 /* See section 4.2.1 of DS-xxxx Rev.3 */。
• 一行不超过 80 列，用 tab 缩进（内核风格）。
• 不新增无必要的中文注释；与主线风格冲突的本地化注释不进上游。
• 新增 ID 条目优先加到厂商文件（winbond.c / gigadevice.c …），不要塞进 core.c。
• 提交信息带 Signed-off-by 与 Tested-by（含控制器名与实测频率），这是主线 review 的硬性要求。
• 提交前跑 scripts/checkpatch.pl --no-tree。
• 本地维护与上游提交分成两个 patch 序列：本地 hack 明确标注，方便后续 rebase。

remove / shutdown 路径上，框架会调用 spi_nor_restore() 把器件恢复到「复位后的默认状态」（退出 4 字节模式、关掉连续读模式）。这段代码是 厂商 fixups 里最需要小心的地方：如果你的器件有非易失的状态被错误地「恢复」了， 下次启动行为就会变。写 fixups 时若操作了厂商私有位，务必在 fixups->restore 里对称还原。