U-Boot flash子系统与持久化：MTD、SPI-NOR架构及环境变量保存实战

1. 从一次启动失败说起为什么flash子系统值得单独梳理前阵子帮朋友看一块工控板现象很典型串口能打印U-Boot的启动日志DRAM初始化也过了但每次跑到加载内核那一步就卡死报错信息里反复出现SF: Failed to read和Bad Magic Number。板子上的固件是烧在SPI-NOR里的之前一直跑得好好的只是最近换了一批同型号但不同批次的flash芯片。这种问题最折磨人因为它不是代码逻辑错了而是U-Boot的flash子系统在跟新芯片对不上暗号。这件事让我意识到很多人用U-Boot都是拿来就用编译、烧录、启动一旦涉及flash读写、环境变量保存、固件升级这些持久化操作就开始抓瞎。U-Boot的flash子系统其实是一套分层清晰、但细节极多的框架它上承命令行工具sf、mtd、nand等下接具体控制器驱动SPI控制器、NAND控制器中间还夹着MTD抽象层和SPI-NOR/NAND的通用操作层。任何一层配置不对持久化就会出问题。这篇梳理就是想把U-Boot里跟flash持久化相关的这套东西讲透。核心关键词是u-boot、flash子系统、持久化、MTD、SPI-NOR。我会从整体架构讲到具体驱动从设备树配置讲到命令行实操重点解释为什么这么设计以及实际用的时候哪里最容易翻车。适合正在做嵌入式Linux开发、需要自己适配flash、或者被环境变量保存和固件升级折磨过的朋友。不管你是刚接触U-Boot的新手还是已经能改驱动但没系统梳理过的老手应该都能从里面找到点有用的东西。2. U-Boot flash子系统的分层架构与数据流向2.1 四层结构从命令行到物理芯片U-Boot的flash子系统不是一坨代码而是分层的。理解这个分层是排查所有flash问题的前提。从上到下大致是这么四层命令层sf、mtd、nand、ubi这些命令是用户直接敲的。它们负责解析参数然后调用下层接口。抽象层MTDdrivers/mtd/mtdcore.c这一套提供统一的mtd_info结构体和mtd_read/mtd_write/mtd_erase接口。不管底层是NOR还是NAND上层看到的都是MTD设备。通用操作层针对SPI-NOR有spi-nor.c针对NAND有nand_base.c。这一层处理芯片的通用命令比如读ID、擦除、页编程。控制器驱动层具体SoC的SPI控制器驱动如spi-quad.c或NAND控制器驱动。这一层直接操作寄存器跟硬件打交道。数据流向是这样的你在命令行敲sf read 0x80000000 0x100000 0x10000命令层解析出从flash偏移0x100000读0x10000字节到内存0x80000000然后调用MTD的mtd_read。MTD根据设备类型找到对应的_read函数SPI-NOR的话最终走到spi_nor_read它再通过SPI控制器驱动发命令给芯片。芯片返回数据原路返回。这个分层的好处是换一个SPI控制器只要写新的控制器驱动上层MTD和命令层完全不用动。坏处是一旦出问题你得知道是哪一层挂了。比如读出来全是0xFF可能是控制器驱动没配对也可能是SPI模式设错了还可能是芯片根本没响应。2.2 MTD抽象层到底抽象了什么MTDMemory Technology Device这层是理解flash子系统的关键。它把闪存这种特殊的存储介质抽象成可以按块擦除、按页读写的设备。为什么不能像内存一样随便写因为flash的物理特性决定了写之前必须先擦除而且擦除的最小单位扇区/块远大于写入的最小单位页。MTD用mtd_info这个结构体描述一个flash设备里面有几个字段你必须认识字段含义典型值SPI-NORtype设备类型MTD_NORFLASHsize总容量16MBerasesize擦除块大小64KB4KB扇区×16writesize写入页大小1字节NOR可以按字节写flags能力标志MTD_CAP_NORFLASH注意writesize对NOR来说是1因为NOR支持按字节编程但对NAND来说通常是2048或4096。这个差异直接影响了上层怎么组织写入。另外erasesize特别重要环境变量保存、固件升级时如果没按擦除块对齐就会出问题。MTD还维护分区表。U-Boot里分区可以通过设备树的partition子节点定义也可以在板级文件里硬编码。分区的作用是把一整块flash切成几段比如u-boot、u-boot-env、kernel、rootfs。每个分区在MTD里是一个独立的mtd_info有自己的偏移和大小。这样你操作环境变量分区时就不会误伤内核分区。2.3 SPI-NOR与NAND在U-Boot里的处理差异虽然MTD把两者统一了但SPI-NOR和NAND在U-Boot里的处理路径差别很大持久化操作时踩的坑也不一样。SPI-NOR的特点是接口简单SPI总线、支持随机读、按字节写、可靠性高、容量小。U-Boot里SPI-NOR的驱动在drivers/mtd/spi/下面核心是spi-nor.c。它通过spi_flash结构体跟SPI控制器通信。SPI-NOR的读写命令是标准化的比如0x03读、0x02页编程、0x20扇区擦除。但不同厂商的芯片在状态寄存器、擦除命令上可能有细微差别这就是为什么换芯片批次会出问题。NAND的特点是容量大、成本低、有坏块、需要ECC。U-Boot里NAND驱动在drivers/mtd/nand/下面核心是nand_base.c。NAND的读写必须经过ECC校验坏块管理也是必须的。持久化时如果没处理坏块写到坏块上数据就丢了。对持久化来说SPI-NOR通常用来存U-Boot本身、环境变量、设备树NAND通常用来存内核和根文件系统。环境变量这种小数据、高可靠性要求的放SPI-NOR更合适。这也是为什么热词里光猫jffs2挂载哪个mtd分区这种问题本质是在问NAND上的文件系统分区怎么对应。3. 环境变量持久化从内存到flash的完整链路3.1 环境变量存在哪CONFIG_ENV_IS_IN_SPI_FLASH的配置逻辑U-Boot的环境变量默认存在内存里掉电就丢。要持久化必须配置存储后端。跟flash相关的配置项有好几个CONFIG_ENV_IS_IN_SPI_FLASH环境变量存在SPI-NOR里CONFIG_ENV_IS_IN_NAND存在NAND里CONFIG_ENV_IS_IN_MMC存在eMMC/SD卡里CONFIG_ENV_IS_NOWHERE不持久化默认以SPI-NOR为例配置里还要指定几个关键参数CONFIG_ENV_IS_IN_SPI_FLASHy CONFIG_ENV_OFFSET0x100000 CONFIG_ENV_SIZE0x10000 CONFIG_ENV_SECT_SIZE0x10000CONFIG_ENV_OFFSET是环境变量在flash里的偏移CONFIG_ENV_SIZE是环境变量区大小CONFIG_ENV_SECT_SIZE是擦除扇区大小。这里有个坑CONFIG_ENV_SECT_SIZE必须跟flash实际的擦除扇区大小一致。如果flash的扇区是64KB你配成4KB保存环境变量时擦除就会出错。为什么要有CONFIG_ENV_SECT_SIZE因为环境变量保存时U-Boot需要先擦除再写入。擦除的最小单位是扇区如果环境变量区跨了多个扇区就得逐个擦除。这个参数告诉U-Boot每次擦多大。3.2 saveenv背后发生了什么你在U-Boot命令行敲saveenv看起来就一条命令背后其实走了一长串流程命令层调用env_save()。env_save()根据配置找到对应的存储驱动比如env_save_spi_flash()。驱动先检查环境变量区是否有效如果无效就先擦除。把内存里的环境变量数据env_ptr指向的缓冲区按扇区对齐逐扇区擦除再写入。写入完成后可能还要回读校验。这里最容易出问题的是第4步。环境变量数据在内存里是紧凑的但写入flash时必须按扇区对齐。如果CONFIG_ENV_SIZE不是CONFIG_ENV_SECT_SIZE的整数倍U-Boot会报错或者写入不完整。我见过有人把CONFIG_ENV_SIZE设成0x8000CONFIG_ENV_SECT_SIZE设成0x10000结果保存时只写了一半重启后环境变量丢失。还有一个隐蔽的坑环境变量的CRC校验。U-Boot在环境变量数据末尾会存一个CRC32值。如果写入过程中断电CRC对不上U-Boot会认为环境变量损坏回退到默认值。这其实是保护机制但如果你在调试时频繁断电可能会误以为环境变量没保存成功。3.3 冗余环境变量CONFIG_ENV_OFFSET_REDUND的取舍U-Boot支持冗余环境变量配置CONFIG_ENV_OFFSET_REDUND后会存两份环境变量一份在CONFIG_ENV_OFFSET一份在CONFIG_ENV_OFFSET_REDUND。每次保存时交替写入并记录一个标志位表示哪份是最新的。这个机制的好处是防断电。如果保存第一份时断电第二份还是完整的U-Boot启动时能自动恢复。坏处是占用双倍空间而且配置更复杂。实际用的时候如果你的产品对可靠性要求高比如工业设备建议开冗余。如果只是开发板调试单份就够了。开冗余时要注意两个偏移不能重叠而且都要按扇区对齐。我见过有人把两个偏移设得太近结果第二份覆盖了第一份反而更糟。4. SPI-NOR驱动适配换芯片批次就翻车的根因4.1 spi-nor.c如何识别芯片JEDEC ID与SFDPSPI-NOR驱动识别芯片靠的是JEDEC ID。每颗SPI-NOR芯片上电后你发0x9F命令它会返回3个字节的ID厂商ID、设备ID高字节、设备ID低字节。驱动拿这个ID去spi_nor_ids表里查找到对应的struct flash_info里面记录了芯片的容量、扇区大小、页大小、读写命令等参数。但JEDEC ID有个问题同厂商同容量的芯片ID可能一样但内部参数比如擦除命令、状态寄存器位定义不同。这时候就要靠SFDPSerial Flash Discoverable Parameters。SFDP是JEDEC标准芯片里有一块参数表驱动读出来就知道芯片支持哪些命令、扇区怎么分布。U-Boot的spi-nor.c里如果spi_nor_ids表里没找到匹配的ID会尝试读SFDP。如果SFDP也读不到就会报unrecognized JEDEC id bytes。这就是换芯片批次翻车的常见原因新批次芯片的ID跟旧的不一样或者SFDP表格式变了驱动没适配。4.2 手动添加flash_info的完整步骤遇到不认识的芯片最直接的办法是手动添加flash_info。步骤如下用示波器或逻辑分析仪抓SPI总线确认0x9F命令返回的ID。或者用U-Boot的sf probe命令看打印的ID。在drivers/mtd/spi/spi-nor-ids.c不同版本路径可能不同里找到spi_nor_ids数组。添加一条记录格式类似{ .name mx25l25635f, .id SNOR_ID(0xc2, 0x20, 0x19), .size SZ_32M, .sector_size SZ_64K, .page_size 256, .flags SPI_NOR_HAS_LOCK | SPI_NOR_4BIT_BP, },如果芯片支持4字节地址容量大于16MB还要加SPI_NOR_4B_OPCODES标志。重新编译U-Boot烧录测试。这里的关键是sector_size和page_size必须跟芯片手册一致。sector_size错了擦除会失败page_size错了写入会出错。另外flags里的SPI_NOR_HAS_LOCK表示支持写保护SPI_NOR_4BIT_BP表示状态寄存器用4位表示块保护这些都要看手册。4.3 设备树里SPI-NOR节点的正确写法现代U-Boot用设备树描述硬件。SPI-NOR节点挂在SPI控制器下面典型写法spi0 { status okay; flash0 { compatible jedec,spi-nor; reg 0; spi-max-frequency 50000000; spi-tx-bus-width 1; spi-rx-bus-width 4; #address-cells 1; #size-cells 1; partitions { compatible fixed-partitions; #address-cells 1; #size-cells 1; partition0 { label u-boot; reg 0x0 0x100000; }; partition100000 { label u-boot-env; reg 0x100000 0x10000; }; }; }; };几个容易错的地方spi-rx-bus-width设成4表示用Quad模式读但有些芯片Quad读需要先发使能命令如果驱动没处理读出来就是乱码。spi-max-frequency不能超过芯片和控制器支持的最高频率设高了会读写不稳定。分区节点的reg是偏移 大小偏移和大小都要跟实际布局一致否则环境变量保存会写到错误位置。5. 命令行实操sf与mtd命令的持久化用法5.1 sf probe与sf read/write/erase的完整流程sf命令是操作SPI-NOR最常用的。基本流程sf probe 0:0 50000000 0 sf read 0x80000000 0x100000 0x10000 sf erase 0x100000 0x10000 sf write 0x80000000 0x100000 0x10000sf probe的参数是总线:片选 频率 模式。频率不写就用设备树里的。sf read是内存地址 flash偏移 长度。sf erase是flash偏移 长度长度必须是擦除扇区的整数倍。sf write是内存地址 flash偏移 长度。这里有个大坑sf write之前必须先sf erase。因为flash只能把1写成0不能把0写成1。如果目标区域不是全0xFF直接写会得到错误的数据。我见过有人直接sf write覆盖旧数据结果读出来是旧数据和新数据的按位与完全不对。另一个坑是长度对齐。sf erase的长度如果不是扇区大小的整数倍U-Boot会报错或者只擦部分。sf write的长度如果跨了扇区边界写入过程中可能触发隐式擦除取决于驱动实现导致数据丢失。稳妥的做法是擦除和写入都按扇区对齐长度取扇区整数倍。5.2 mtd命令与分区操作mtd命令更偏向分区操作mtd list mtd read 分区名 内存地址 偏移 长度 mtd write 分区名 内存地址 偏移 长度 mtd erase 分区名mtd list会列出所有MTD分区包括SPI-NOR和NAND的。用分区名操作比用裸偏移安全因为分区名对应的是逻辑分区不会误伤其他区域。mtd write内部会自动处理擦除吗不一定。有些版本的U-Boot里mtd write会先擦除再写有些不会。稳妥起见还是先mtd erase再mtd write。另外mtd erase如果不带偏移和长度会擦除整个分区用的时候要小心。5.3 环境变量相关命令env print/set/save/export环境变量操作命令env print env set bootargs consolettyS0,115200 root/dev/mtdblock3 env save env export -t 0x80000000 env import -t 0x80000000 0x1000env save就是saveenv。env export把环境变量导出到内存env import从内存导入。这两个命令在批量烧录时有用可以先在一台设备上配好环境变量导出成二进制然后批量导入到其他设备。注意env set只是改内存里的值必须env save才持久化。如果改了没保存重启就丢。另外环境变量有大小限制CONFIG_ENV_SIZE决定了能存多少。如果变量太多超了env save会报错。6. 持久化踩坑实录几个真实案例的排查链路6.1 案例一saveenv报Failed to erase的排查现象敲saveenv报Failed to erase环境变量保存失败。排查链路先确认CONFIG_ENV_SECT_SIZE跟flash实际扇区大小是否一致。查芯片手册扇区是64KB配置里是0x10000一致。用sf probe确认芯片识别正常ID对得上。用sf read读环境变量区看是否能读出数据。能读说明读路径没问题。手动sf erase环境变量区报同样的错。说明擦除命令有问题。查spi_nor_ids表发现芯片的擦除命令是0x204KB扇区擦除但驱动里配的是0xD864KB块擦除。新批次芯片不支持0xD8。修改flash_info里的擦除命令或者让驱动用0x20逐扇区擦除。重新编译问题解决。这个案例的教训是擦除命令不是所有芯片都一样的。老芯片支持块擦除新芯片可能只支持扇区擦除。驱动适配时一定要看手册。6.2 案例二环境变量保存后重启丢失现象saveenv显示成功但重启后环境变量恢复默认值。排查链路确认CONFIG_ENV_OFFSET跟分区表里环境变量分区的偏移一致。查设备树分区偏移是0x100000配置里也是0x100000一致。用sf read读环境变量区看是否有数据。读出来全是0xFF说明根本没写进去。检查saveenv的返回值发现虽然打印成功但实际写入长度为0。查代码发现CONFIG_ENV_SIZE设成了0x20000但CONFIG_ENV_SECT_SIZE是0x10000环境变量区跨了两个扇区。驱动在擦除第二个扇区时失败但错误没上报。把CONFIG_ENV_SIZE改成0x10000重新编译问题解决。这个案例的教训是环境变量区大小必须是扇区大小的整数倍而且最好就是一个扇区避免跨扇区操作。6.3 案例三NAND上JFFS2挂载失败与MTD分区对应热词里光猫jffs2挂载哪个mtd分区这个问题本质是NAND分区和文件系统分区的对应关系。现象内核启动时挂载JFFS2失败报No filesystem could mount root。排查链路看内核启动日志确认NAND驱动是否识别了所有分区。mtd list能看到分区但名字可能跟预期不符。确认JFFS2分区在设备树里的reg是否正确。JFFS2需要知道分区的起始偏移和大小。检查内核命令行root参数。如果是root/dev/mtdblock3要确认mtdblock3对应的是哪个分区。mtdblock的编号是按分区注册顺序来的顺序变了编号就变了。用mtd read读JFFS2分区头部看是否有JFFS2的魔数0x1985。如果没有说明分区里没烧文件系统。重新烧录JFFS2镜像到正确分区问题解决。这个案例的教训是MTD分区编号不是固定的依赖注册顺序。用分区名比用编号可靠。另外JFFS2挂载需要分区里有有效的文件系统镜像空分区挂不上。7. 把flash子系统用稳的几个经验7.1 配置检查清单每次适配新板子或新flash按这个清单过一遍CONFIG_ENV_IS_IN_SPI_FLASH或CONFIG_ENV_IS_IN_NAND是否使能CONFIG_ENV_OFFSET是否跟分区表一致CONFIG_ENV_SIZE是否是CONFIG_ENV_SECT_SIZE的整数倍CONFIG_ENV_SECT_SIZE是否跟芯片手册一致设备树里SPI-NOR节点的spi-max-frequency是否在安全范围内spi-rx-bus-width是否跟硬件连线一致单线还是四线分区表的偏移和大小是否跟实际布局一致7.2 调试技巧用sf probe确认芯片识别看打印的ID和容量用sf read读关键区域确认数据可读用md命令看内存里的数据对比flash读出的数据保存环境变量后立即sf read回读确认写入成功如果读写不稳定降低SPI频率试试用逻辑分析仪抓SPI波形看命令和数据是否符合预期7.3 关于持久化的个人体会我在实际项目里踩过最多的坑不是代码写错而是想当然。比如以为同型号芯片参数一定一样以为环境变量区大小随便设以为擦除命令所有芯片都支持。这些想当然在实验室可能不出问题一到量产就爆发。现在我的习惯是每换一款flash先花半小时看手册把JEDEC ID、扇区大小、页大小、擦除命令、状态寄存器位定义都记下来然后跟驱动里的flash_info逐项对比。这个习惯帮我省了很多返工时间。另外环境变量这种关键数据我建议开冗余。多占一个扇区的空间换来的是断电不丢配置很值。固件升级时也尽量用分区名而不是裸偏移减少误操作。flash子系统的代码在U-Boot里不算最复杂的但细节最多。把这些细节理清楚持久化就稳了。