SFIx变体：外部Flash Loader实现量产多段镜像烧录与校验

作为一个常年跟嵌入式固件和量产烧录打交道的工程师，我对“external loader”这个词再熟悉不过了。调试器（JLink、OpenOCD、Keil、IAR）默认只认识芯片内部的Flash，一旦你需要在外部SPI NOR Flash、SD卡甚至并口NOR上跑程序，就必须自己写一个外部加载器（External Flash Loader），把擦除、编程、校验这些操作封装成调试器能调用的标准接口。

而我这次要聊的，是我们在某个项目里实际用到的一种特殊变体：SFIx。它不是什么官方标准，而是基于通用外部Loader框架扩展出来的镜像格式变体。核心思路是：把原本直接往Flash里塞裸数据的流程改造成“先打包成SFIx镜像，再通过外部Loader解析写入”，这样就能在量产烧录时一次性写入带校验、带块索引、甚至带压缩标记的数据。这篇文章我会把SFIx变体的设计思路、接口实现、配套的Python生成脚本和调试技巧全部拆开讲一遍，代码都给可直接抄的版本，适合正在做MCU外部存储烧录、量产工具、BootLoader配套开发的工程师参考。

1. 项目背景与需求拆解

1.1 SFIx到底是什么，和普通外部Loader有什么不同

先说明一下SFIx这个名字。在我们项目里，它的全称是Serial Flash Image eXchange，本质上是把标准的外部Loader从“裸数据搬运工”升级成一个“能识别带格式镜像的解析器”。

普通的外部Loader只管三件事：初始化Flash、擦除扇区、写页数据。调试器从hex/bin里读到的数据是什么，Loader就原样往Flash里写什么，不做二次处理。这在大多数场景下没什么问题，但一旦你遇到下面两种情况就很头疼：

• 镜像里有多个子镜像（Boot、App、校准数据、文件系统），需要各自烧到不同偏移；
• 量产时希望用同一份固件文件，通过Loader自动决定写到哪里、要不要加CRC、要不要跳过空白区域。

SFIx变体解决的就是这类问题。它在Loader内部增加了一个镜像解析层，主机侧生成的固件文件不再是裸bin，而是带SFIx头（Magic、版本、块数量、CRC、每个子块的偏移/长度/属性）的镜像包。Loader在Program阶段识别这个头，然后根据块表依次写入对应地址。这样主机工具（比如JLink Commander、OpenOCD flash write）不需要做任何额外逻辑，只要把整个SFIx文件扔给Loader，就能自动完成多段、多属性的烧录。

1.2 这个项目要解决的三个实际问题

做这个变体的直接驱动来自量产线的三个痛点：

1. 烧录分段太多。产品上电后需要同时存在Bootloader和App，Bootloader在0x000000，App在0x080000，中间还夹着一段校准参数区，用普通Loader得写三次命令，容易出错。
2. 烧错地址风险高。流水线上操作员手动输入地址，偶尔会把App烧到Boot区域，板子直接变砖，返修成本高。
3. 校验逻辑不统一。之前用JLink脚本在主机侧做CRC校验，但烧录工具一换就得重写一遍，很烦。

SFIx方案把这些问题全部压到Loader内部：地址写在镜像头里，操作员只需要选择文件；块表里带CRC字段，Loader写完后自动回读校验；属性的含义（必须写、可跳过、可覆盖）由Loader统一解释，跨工具保持一致。

1.3 适合谁参考，需要具备什么基础

这篇内容的适用对象很明确：正在做STM32/AT32/GD32之类MCU外部Flash烧录的工程师，或者在做量产工装、BootLoader配套工具链的人。你需要对CMSIS-Pack里的Flash算法结构有基本认识，至少知道Init、UnInit、EraseSector、ProgramPage这几个函数是干嘛的。如果你还没写过完整的外部Loader，建议先把官方模板（比如Keil下的FlashOS驱动）跑通，再来看SFIx的改造就顺了。

配套的Python镜像生成脚本也附在后面，这一部分门槛很低，会Python就行，主要用来给现有烧录流程补上一个“打包SFIx”的环节。

2. 整体设计思路与格式规划

2.1 架构选择：为什么在Loader层解析，而不是在主机侧解析

一开始我们讨论过两个方案：

• 方案A：在主机侧（比如JLink脚本、Python脚本）解析SFIx，解析完再逐段调用普通Loader写入；
• 方案B：在Loader内部解析SFIx，主机侧每次直接把整个镜像文件丢给Loader。

方案A看起来改动更小，但它有个致命问题：主机侧的烧录工具五花八门，JLink脚本是一种写法，OpenOCD是另一种，将来可能还会接到自研的量产上位机上，每换一个工具就得重新写一遍解析。而方案B把解析逻辑固化在Loader这个动态库里，所有工具只要会调用ProgramPage就能享受同样的行为。

代价是Loader本身要做一些“越权”的事情。标准ProgramPage接口相当于是“你给我一段数据，我写进Flash”，而SFIx需要Loader在第一次ProgramPage调用时缓存数据、识别镜像头、解析块表，后续写入时根据块表决定落点。这里必须在Init函数里先把整个SFIx块表解析到位，ProgramPage才能快速定位。所以我们把SFIx头设计得足够紧凑，一个扇区的读取就能拿到全部块目录。

2.2 SFIx镜像格式定义

SFIx v1.0的格式分两个部分：文件头（File Header）和块表（Block Table）。

文件头固定12字节，包含：

块表每条16字节，长度为BlockCount条，紧跟在文件头后面：

镜像体就是各块数据连续拼接。生成脚本会把Boot放在第一块、App放在第二块、校准参数区放在第三块，三个块的DestAddr写死，产线不用再手动传地址。

2.3 为什么用CRC16而不是CRC32

可能有人会问，都2025年了，做个镜像校验还用CRC16，是不是太抠了？

这里其实是用脚投票的结果。外部Loader跑在MCU里，CPU频率和高核Flash时钟都不算高，CRC32在软件实现上要查两次表，耗时会翻倍。而CRC16（查表法）算4KB数据大约在几十微秒级别，量产烧录时这个开销可以忽略。另外，SFIx镜像主要用于烧录正确性校验，不是用于传输安全，碰撞概率在产线场景可以接受。

如果你非要换成CRC32，只需要把生成脚本和Loader里的查表逻辑同步改掉，注意头格式里Crc16字段长度要扩到4字节，整个块表会变成18字节一条，别搞乱偏移。

3. 核心代码实现：C侧Loader解析与Python镜像生成

3.1 C侧Loader的SFIx初始化解析

Loader侧最核心的改动集中在Init函数里。正常流程是先初始化Flash控制器，然后对外部Flash做一次复位和ID读取。SFIx变体则会在这一步额外读取外部Flash的起始扇区，从中解析SFIx文件头。

这里有个前提需要说明：我们的量产流程规定Flash上空白的起始扇区（通常是第一个64KB扇区）写入的就是SFIx镜像。所以Init时，Loader直接把Flash地址0x000000开始的第一个扇区读到RAM缓存，然后检查Magic。

#include <stdint.h> #include <string.h> #define SFIX_MAGIC 0x53464958UL #define SFIX_HEADER_LEN 12 #define SFIX_BLOCK_LEN 16 #define SFIX_MAX_BLOCKS 64 #define SFIX_FLAG_GLOBAL_CRC 0x00000001UL #define SFIX_FLAG_SKIP_FF 0x00000002UL typedef struct { uint32_t magic; uint16_t version; uint16_t block_count; uint32_t flags; } sfix_file_header_t; typedef struct { uint32_t dest_addr; uint32_t data_len; uint16_t flags; uint16_t crc16; } sfix_block_entry_t; static sfix_file_header_t s_sfix_header; static sfix_block_entry_t s_sfix_blocks[SFIX_MAX_BLOCKS]; static uint8_t s_sfix_block_ram[64 * 1024]; static uint32_t s_sfix_initialized = 0; static uint16_t sfix_crc16(const uint8_t *data, uint32_t len) { uint16_t crc = 0xFFFF; while (len--) { crc ^= *data++; for (int i = 0; i < 8; i++) { crc = (crc & 1) ? (crc >> 1) ^ 0xA001 : (crc >> 1); } } return crc; } int32_t Init(uint32_t adr, uint32_t clk, uint32_t fnc) { (void)adr; (void)clk; (void)fnc; // 1. Flash控制器的初始化 flash_ctrl_init(); flash_reset(); uint32_t jedec_id = flash_read_jedec_id(); if (jedec_id == 0xFFFFFFFF) { return 1; } // 2. 读取起始扇区里的SFIx头 flash_read(0x00000000, s_sfix_block_ram, sizeof(s_sfix_block_ram)); memcpy(&s_sfix_header, s_sfix_block_ram, SFIX_HEADER_LEN); if (s_sfix_header.magic != SFIX_MAGIC) { return 1; } // 3. 解析块表 if (s_sfix_header.block_count > SFIX_MAX_BLOCKS) { return 1; } memcpy(s_sfix_blocks, &s_sfix_block_ram[SFIX_HEADER_LEN], s_sfix_header.block_count * SFIX_BLOCK_LEN); s_sfix_initialized = 1; return 0; }

这段代码里有一个很容易忽略的细节：flash_read一次性读64KB。在外部SPI NOR Flash上，连续读64KB可能要好几十毫秒，而JLink等调试器对Init的等待时间是有上限的。如果超时会直接报“Cannot communicate with target”，这类问题我在后面的调试章节会专门讲。

如果你不想在Init里读整个扇区，也可以只读文件头和块表部分，也就是12 + block_count * 16字节，通常不到1KB，速度快很多。我们当时全量读是为了给后续镜像校验做缓存，给ProgramPage省一次Flash回读。

3.2 ProgramPage如何按块表落址

标准外部Loader的ProgramPage长这样：接收一个目标地址、一段数据、一个长度，然后把数据写进去。但SFIx变体下，主机侧烧录时往往不知道内部子镜像的实际地址，它会从0x000000开始把整个SFIx文件依次当作ProgramPage的输入。

所以ProgramPage内部需要做一次“地址重定向”——根据当前写入的偏移量，查找它在块表里属于哪一块，再把数据写到那一块的DestAddr + 偏移位置。

int32_t ProgramPage(uint32_t adr, uint32_t sz, uint8_t *buf) { if (!s_sfix_initialized) { return 1; } uint32_t base = 0; uint32_t written = 0; // 把镜像文件内的线性地址映射到块表的DestAddr if (adr < SFIX_HEADER_LEN) { // 头区域，直接忽略写入 return 0; } uint32_t file_off = adr - SFIX_HEADER_LEN; for (uint32_t i = 0; i < s_sfix_header.block_count; i++) { sfix_block_entry_t *blk = &s_sfix_blocks[i]; if (file_off >= base && file_off < base + blk->data_len) { uint32_t blk_off = file_off - base; uint32_t len = blk->data_len - blk_off; if (len > sz) { len = sz; } uint32_t target = blk->dest_addr + blk_off; // 如果块标记为“允许跳过”，且当前数据全为0xFF，则跳过写入 if ((blk->flags & 0x0001) == 0 && is_all_ff(buf, len)) { return 0; } if (flash_write(target, buf, len) != 0) { return 1; } written = len; // 写完每个块后，如果启用了CRC校验，则回读对比 if (s_sfix_header.flags & SFIX_FLAG_GLOBAL_CRC) { uint8_t rd[64]; flash_read(target, rd, len); uint16_t crc_calc = sfix_crc16(rd, len); uint16_t crc_expect = blk->crc16; if (crc_calc != crc_expect) { return 2; } } return written; } base += blk->data_len; } return 0; }

注意代码里对文件偏移的换算逻辑：SFIx文件的前12字节是文件头，之后紧跟块表，然后才是各块数据，所以主机侧烧录时镜像内的线性偏移和Flash物理地址是两套体系。ProgramPage收到的是“镜像文件内偏移”，必须减去文件头和块表的长度，才能映射到第一个数据块。

当初我们第一版把文件头长度当成0来计算，结果App烧进去后整个启动向量错乱，调试器一跑就进HardFault。后来加了一条log才看清楚，前面12字节偏移没处理。

3.3 Python侧生成SFIx镜像：用while循环做容量换算

镜像怎么生成？我们在产线用的是Python脚本，输入三个bin文件（boot.bin、app.bin、calib.bin），输出一个sfix_image.bin。

脚本里有个小细节，就是如何计算每个块的容量对齐。外部Flash的扇区擦除粒度是4KB，如果块的长度不是4KB整数倍，擦除时会把相邻块的数据也抹掉。所以我们用while循环把每个块的长度向上对齐到4KB，同时顺便算出整个镜像需要预留多少填充空间。

这里需要计算一些边界值，比如当块偏移位很大时，直接用位运算容易看不懂，我就用while循环来确认2^n的数值，这也是调试时很好的辅助手段。比如在生成脚本里，我们会打印2^59到底是多少，用来估算一个“理论上限值”会不会越界：

def pow2_by_loop(n): result = 1 count = 0 while count < n: result *= 2 count += 1 return result # 验证64位地址空间中非对齐边界的换算 big_boundary = pow2_by_loop(59) print(f"2^59 = {big_boundary}")

这个例子在实际脚本里的作用是：当我们设计SFIx块表时，需要确认某些极端情况下地址偏移会不会超出32位范围。虽然目前所有子镜像都放在32位地址空间内，但调试脚本加一个2^59的边界验证，可以防止把data_len声明成32位时出现高位截断的隐患。当然，如果你用的MCU支持64位寻址，这块另说。

3.4 Python侧生成SFIx镜像：核心实现

下面这段是生成SFIx镜像的核心代码，其中用到了logging模块，把日志输出到文件app_85.log，方便产线追溯。

import os import struct import logging logging.basicConfig( filename='app_85.log', level=logging.INFO, format='%(asctime)s [%(levelname)s] %(message)s' ) SFIX_MAGIC = 0x53464958 SFIX_VERSION = 0x0100 SFIX_HEADER_LEN = 12 SFIX_BLOCK_LEN = 16 FLASH_SECTOR_ALIGN = 4 * 1024 # 4KB对齐 def align_up(value, align): return (value + align - 1) // align * align def crc16_modbus(data): crc = 0xFFFF for byte in data: crc ^= byte for _ in range(8): crc = (crc >> 1) ^ 0xA001 if (crc & 1) else crc >> 1 return crc def build_sfix(blocks, out_path): """ blocks: list of (dest_addr, data_bytes, flags) """ header = struct.pack('<IHHI', SFIX_MAGIC, SFIX_VERSION, len(blocks), 0x00000003) block_table = b'' payload = b'' for dest_addr, data, flags in blocks: data_len = len(data) # 数据长度对齐，工厂里方便按扇区擦写 aligned_len = align_up(data_len, FLASH_SECTOR_ALIGN) extended = data + b'\xFF' * (aligned_len - data_len) blk_crc = crc16_modbus(extended) block_table += struct.pack('<IIHH', dest_addr, aligned_len, flags, blk_crc) payload += extended image = header + block_table + payload with open(out_path, 'wb') as f: f.write(image) logging.info('generate %s, %d blocks, total %d bytes', out_path, len(blocks), len(image)) return len(image) if __name__ == '__main__': boot_data = open('boot.bin', 'rb').read() app_data = open('app.bin', 'rb').read() calib_data = bytearray(2048) # 模拟校准区默认数据 for i in range(len(calib_data)): calib_data[i] = i & 0xFF total = build_sfix([ (0x000000, boot_data, 1), # 必须写 (0x080000, app_data, 1), # 必须写 (0x100000, calib_data, 0), # 允许跳过 ], 'sfix_image.bin') print('total bytes:', total)

几个关键点说明：

• flags字段传1表示必须写块，传0表示可跳过。Loader会在ProgramPage里判断，如果目标区域全是0xFF就直接跳过，加速烧录；
• 数据长度按4KB对齐后再做CRC，这样Loader回读校验时能够按扇区边界校验，避免跨扇区校验时多读一次；
• logging输出到app_85.log，这台机器上每次生成镜像都会留痕，产线出问题了可以翻日志看是哪批数据生成的不对。

4. 编译配置和调试环境的那些坑

4.1 外部Loader的工程配置注意点

SFIx变体的代码最终是要编译成外部Loader动态库（Windows下是DLL，OpenOCD环境下可能是so，或者直接编译成特定格式的FLM）。编译配置里有几个坑，值得单独拎出来说。

一个是PrgFunc、EraseFunc这些导出函数名必须和调试器预期一致。Keil下Flash算法使用固定函数导出名，比如Init、UnInit、EraseSector、ProgramPage，大小写都不能错。函数名错了，调试器加载DLL时直接提示找不到接口，烧录根本跑不起来。

另一个是代码应该运行在RAM里，而不是Flash里。外部Loader本身是调试器临时加载到MCU RAM里执行的“小固件”，所以在分散加载文件（sct文件）里要把执行区放在RAM。如果你把代码放到了内部的Flash区域，烧录时可能覆盖到正在运行的固件，直接崩溃。我在第一版就吃过这个亏，忘了改ROM地址，结果每次Init都跳飞。

链接脚本里还要预留足够的堆栈空间。SFIx解析需要在RAM里缓存整个块表和一个扇区数据，我们当时把ProgramPage里最大单次写入长度设为64字节，但Init里的扇区缓存就占了64KB。对STM32F103这种20KB RAM的型号肯定不够，后来换成了F407才跑得动。如果你的MCU RAM偏小，就得把Init里的读扇区改成只读文件头+块表（最大约1KB），牺牲一点缓存，换RAM空间。

4.2 烧录时序：为什么Init会超时

外部Loader挂在调试器上，调试器对每个接口的调用时间是有隐式限制的。

JLink环境下，Init如果超过一定时间（通常不会太长）会报“Cannot connect to target”。我上一节提到Init里读64KB外部Flash，如果在低速SPI（比如1MHz）下要几百毫秒，就有风险。我们实测把SPI时钟拉到10MHz，读64KB大约6毫秒，没问题；但如果硬件上SPI走线长、负载大，10MHz跑不稳，只能降到5MHz，这时读64KB也会到十几毫秒，仍然安全。

更麻烦的是EraseSector。SPI NOR Flash擦除一个4KB扇区典型耗时30~80毫秒，JLink能容忍。但如果你用SFIx块表一次性擦除大片区域，在EraseSector里写了循环擦除几十个扇区，总时长可能超过1秒，部分调试器会误判为假死。

解决方法是：EraseSector被调用时，只擦除传入的那个扇区；涉及多个扇区的擦除，由主机侧（比如JLink脚本或OpenOCD命令）多次调用EraseSector，每次擦一个扇区。这样单次耗时可控，不会触发超时。

4.3 JLink和OpenOCD下烧录SFIx镜像的参考命令

调试环境搭建好后，烧录命令并不复杂。

JLink旁一般用JLink.exe命令行或者JFlash。JFlash里选择对应的外部Loader文件，然后加载生成的sfix_image.bin，起始地址填0x000000。因为Loader内部会做地址重定向，这里起始地址填多少其实影响不大。关键是文件类型要选Raw Binary，不要选Intel Hex，否则JLink会按Hex里的地址去写，那就绕过了SFIx的重定向逻辑。

OpenOCD下可以这样写：

openocd -f interface/stlink.cfg -f target/stm32f4x.cfg \ -c "init" \ -c "halt" \ -c "flash bank external stm32f4x.flash 0x000000 0 0 0 $TARGET" \ -c "flash write_image erase sfx_image.bin 0x000000 bin" \ -c "reset"

注意flash write_image后面如果带bin参数，也会把镜像按线性地址直接写入，不会经过块表重定向。所以更稳妥的用法是让OpenOCD只把它当成一个普通二进制，把整包丢给Loader，靠Loader内部解析。

如果要在OpenOCD里完全走外部Loader的路径，可以查一下目标板对应的flash驱动配置，一般需要指定driver是eflash_loader或者自定义的CFI驱动变体。这块各家的OpenOCD版本差异很大，建议确认版本再折腾。

5. 常见问题与排查技巧实录

5.1 现象：烧录完成但App起动不了，卡在HardFault

这是最典型的SFIx首版问题，基本可以锁定为地址映射错位。

当时我们烧完后用调试器读外部Flash内容，发现Boot区的确写对了，但App区开头多了12个FF字节。分析下来就是因为ProgramPage里没有减去文件头的12字节，导致第一个块的数据从DestAddr + 12开始写，App的向量表整体偏移了。

改动方法就是我在代码里写的file_off = adr - SFIX_HEADER_LEN。如果你自己改过文件头长度或者块表结构，这块偏移要同步更新，否则所有子镜像都会整体飘移。

排查时建议先在ProgramPage里加临时log，输出adr、file_off、target这三个值，跟Python脚本里预设的DestAddr对比，一眼就能看出问题。

5.2 现象：Init可以过，但ProgramPage每次都返回错误码2

错误码2是我在代码里写的“CRC校验失败”。没改代码的情况下，先不要在Loader里查CRC，直接用逻辑分析仪或者调试器读Flash，看数据是否真的写入成功。

如果写入的数据和预期一致但CRC还不匹配，大概率是CRC的计算范围有问题。我在Python脚本里是对“对齐后带填充FF”的数据做CRC，而Loader里的flash_read回读长度是len，如果len没有包含填充部分，算出来的CRC必然不一致。

简化处理方式是让Loader回读校验时也按对齐后的长度读。就是把ProgramPage里的len = blk->data_len - blk_off改成读取aligned_len - blk_off，这样CRC计算范围才能对得上。

5.3 现象：烧录速度极慢，一个2MB镜像要4分钟

排除SPI时钟频率太低的情况后，最可能的原因是“跳过空白块”功能没有生效。

我们量产时校准区大部分数据是0xFF，如果Loader没有跳过，就会老老实实擦除、写入这些空白区域，白白浪费时间。检查ProgramPage里的跳过条件：

• 块标志位flags & 0x0001为0，表示允许跳过；
• 当前写入的数据全部为0xFF。

两个条件同时满足才跳过。如果块表里flags传的是1，那么即使数据全是0xFF也会强制写入，速度自然快不了。

另一个提速点是EraseSector。如果主机侧每写一个页就触发一次扇区擦除，会产生大量重复擦除。可以在Init里记录当前擦除状态，EraseSector若传入的是同一个已擦扇区就直接返回成功，减少无效擦除。

5.4 常见问题速查表

5.5 一点独家经验：把SFIx头和块表放在烧录日志里

这个不算技术，但挺实用。我们在生成SFIx镜像时，会顺带把文件头、块表信息打印成一行摘要，存到和app_85.log同级的sfix_index.txt里。

产线后来有次出了“烧了一半的板子换工位继续烧”的情况，到第二条产线重新烧录时，工程师不知道上一工位已经把Boot写好了，又往外面写了一整包2MB镜像，结果把原来Boot区覆盖成新版本。有了块表日志，我们一查就发现两边的镜像版本不一致，最终定位是产线脚本同步问题。

所以只要是在做量产相关的东西，日志和现场信息越详细越好，这比在代码里多写几个功能点重要得多。

6. 写在最后：这个变体后续还能怎么扩展

SFIx变体跑通之后，整个烧录流程从“多个文件多次操作”变成了“一个文件一次搞定”，产线效率提升非常明显。目前这个方案我们还在迭代，后续有几个方向是我想继续做的：

• 在块表里加一个encrypt_flag字段，对接AES-128硬件解密，这样SFIx文件放到产线电脑上也不怕泄密；
• 在Loader的UnInit里加一个整体镜像指纹计算，调用方可以在烧录完成后拿到一个固定字符串，用于MES系统做追溯；
• 把Python生成脚本扩展成命令行工具，接受JSON配置，这样换项目时不用改代码，改个JSON就能生成对应布局。

如果你正在被外部Flash多段烧录、产线地址填错、校验逻辑分散这几个问题困扰，照着这个SFIx思路做一套，底层的原理是完全通用的。遇到具体实现上的问题，也可以按我文里给的排查方向去定位，基本都能搞定。