1. 抄一份 W25Q128 驱动之前:先把代码开发工具这一层对齐
在 STM32 上挂一颗 W25Q128 做参数存储或者字库,最常见的动作是去搜一份现成的 w25qxx.c 贴进工程,上电一跑,读 ID 出来是 0xFFFFFF 或者 0x000000,然后开始怀疑芯片是不是坏的、模块是不是虚焊。我前后翻过几次车,问题几乎都不在“驱动写得对不对”,而在代码开发工具这一层没对齐:SPI 句柄名改了没同步、片选宏指向了别的引脚、时钟极性和器件手册对不上、数据帧宽度配成了 16 位。上层再漂亮的命令封装,底层差一项就是一堆废纸。下面按一条能真正落地的路径走:工程配置、字节日收发、读 ID、擦扇区、写页、连续读,最后把真机上翻过车的几个点单独拎出来讲。适合手里已经有板子和 W25Q128 模块、想把驱动跑通而不是跑个编译通过的人。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 用代码开发工具搭骨架:SPI 句柄、片选宏与字节日收发
2.1 先把句柄、片选、超时这三样定死
在 CubeMX 里把 SPI 配成主机、全双工、8 位数据帧、软件片选(NSS 忽略),这是最常见也最省事的起点。之所以用软件片选,是因为 W25Q128 的 CS 需要在每条命令前后由固件精确控制,交给外设的硬件 NSS 之后,你很难在命令之间插入自己想要的延时和状态检查。生成工程后会得到一个类似 hspi1 的句柄,把它连同片选引脚一起写成宏,统一放在 w25qxx.h 里,而不是散落在各个 .c 文件里到处 HAL_GPIO_WritePin。
c复制/* w25qxx.h 部分定义 */
#define W25Q_SPI_HANDLE &hspi1 /* 你的 SPI 句柄,改名要同步这里 */
#define W25Q_CS_GPIO_PORT GPIOA /* 片选所在端口,按实际接线改 */
#define W25Q_CS_GPIO_PIN GPIO_PIN_4 /* 片选引脚号 */
/* 片选控制宏,提高效率 */
#define W25Q_CS_LOW() HAL_GPIO_WritePin(W25Q_CS_GPIO_PORT, W25Q_CS_GPIO_PIN, GPIO_PIN_RESET)
#define W25Q_CS_HIGH() HAL_GPIO_WritePin(W25Q_CS_GPIO_PORT, W25Q_CS_GPIO_PIN, GPIO_PIN_SET)
这三个宏看着朴素,但它决定了后面所有命令的时序起点。用宏而不是写 W25Q_CS_Control(0) 这样的函数,是因为 CS 拉低到第一个时钟沿之间的空隙越短越稳,宏在编译期直接展开成内联的寄存器写,省掉一次函数调用和压栈。W25Q_SPI_HANDLE 写成 &hspi1 而不是 hspi1,是因为 HAL 的接口一律收句柄指针,这一点在改句柄名的时候最容易漏,漏了编译不报错但行为全错——HAL_SPI_TransmitReceive 拿到一个空指针或者错误地址,返回值不是 HAL_OK,而你如果没检查返回值,就会一路“以为在通信”。
引脚这里还有一条实践上的硬要求:片选必须独占一个普通 GPIO,不能和 SPI 的 SCK/MOSI/MISO 复用在同一组里凑数,也不能挂在某个会被 CubeMX 重新分配的引脚上。我见过一次片选被配成了开漏输出,平时靠外部上拉拉高,结果模块上的上拉电阻是 10k,CS 上升沿慢得像爬坡,擦除命令偶尔被识别成半条,现象就是“有时候能擦有时候不能擦”。推挽输出、默认高电平,这是最省心的配置。
2.2 收发一个字节:为什么统一用 TransmitReceive
底层只留一个函数,所有命令、地址、数据都从它过。写法是固定的:
c复制/* 发送并接收一个字节(全双工) */
static uint8_t W25Q_SPI_ReadWriteByte(uint8_t data)
{
uint8_t rx_data;
/* Size=1 表示一个数据帧,Timeout=100 单位是毫秒 */
HAL_SPI_TransmitReceive(W25Q_SPI_HANDLE, &data, &rx_data, 1, 100);
return rx_data;
}
这里用 HAL_SPI_TransmitReceive 而不是 HAL_SPI_Transmit,原因只有一个:SPI 是被动时钟,主设备不产生时钟,从设备一个字节也吐不出来。W25Q128 读数据时的那些位,全靠主机发 dummy 字节把时钟打出来。所以读写必须是同一条路径,发 0xFF 收数据,收发共用一个入口,这样命令函数里就不需要区分“这是读还是写”。
参数逐个说清楚:第二个参数是发送缓冲区指针,第三个是接收缓冲区指针,第四个 Size=1 是数据帧个数而不是字节数,在 8 位数据宽度下两者等价,一旦有人把数据宽度改成 16 位,这里传 1 就变成一个 16 位帧,行为立刻偏离预期;第五个参数 100 是超时,单位毫秒,它的作用不是“通信要 100 毫秒”,而是防止总线被拉低或者从设备不响应时死等,有它兜底,函数至少能返回,返回值可以被上层检查。
还有一个细节:这个函数必须是 static,只在本文件可见。放出去成了全局符号,工程里别的地方随手调一次,很可能在某个中断里把 CS 时序打断。我吃过这个亏,一次在定时器中断里顺手读了一下状态寄存器,正好打断主循环里的页编程,CS 中途被拉高,那一页数据就废了。
时钟模式这一项要和器件手册对齐。W25Q128 支持模式 0(CPOL=0,CPHA=0)和模式 3(CPOL=1,CPHA=1),CubeMX 里配哪个都行,但定下来之后,读 ID、写使能、擦除、读数据必须全部走同一个模式,不能中途改。配错模式的典型现象是读 ID 拿到 0xFF 或 0x00,而总线上用示波器看波形其实非常干净——这就是玄学感的来源,波形好看但数据不对。
3. 命令层三件套:读 JEDEC ID 为什么是第一个验证点
3.1 三段 ID 是怎么拼出来的
驱动写完第一件事不是擦写,是读 ID。ID 读不对,后面所有操作都不用试。
c复制/* 读取器件 ID(JEDEC ID) */
uint32_t W25Q_ReadID(void)
{
uint32_t id = 0;
W25Q_CS_LOW();
W25Q_SPI_ReadWriteByte(0x9F); /* 读 JEDEC ID 命令 */
id |= (W25Q_SPI_ReadWriteByte(0xFF) << 16); /* 制造商字节 */
id |= (W25Q_SPI_ReadWriteByte(0xFF) << 8); /* 存储器类型 */
id |= W25Q_SPI_ReadWriteByte(0xFF); /* 容量字节 */
W25Q_CS_HIGH();
return id;
}
0x9F 是标准的读 JEDEC ID 命令,后面连续三个字节分别是制造商、存储器类型、容量。三个 W25Q_SPI_ReadWriteByte(0xFF) 里的 0xFF 没有实际意义,它只是 dummy,作用是把时钟打出来让器件把数据推上 MISO。填 0xFF 而不是 0x00 是习惯,对 SPI 从设备来说两者等价,但 0xFF 在某些器件上意味着“保持 MOSI 高”,总线空闲态更干净。
拼接顺序要留意:先收到的字节放高位。写成 id |= (byte << 16) 而不是先存到变量再左移,是为了不额外占一个中间变量,代价是可读性稍差一点。读完之后我一般把三个字节分别打印出来,而不是只看拼好的 32 位整体——三个字节分开看,能立刻判断是“完全没通”(三个都是 0x00 或 0xFF)还是“通了但型号不对”(容量字节不是预期值)。W25Q128JV 的容量字节是 0x18,加制造商 0xEF,拼出来是 0xEF4018。这个值记在纸上或者写在注释里,每次换板子对一遍,比事后怀疑人生强。
读 ID 之所以当第一个验证点,还因为它同时验证了三件事:CS 能拉低拉高、SPI 时钟能出来、MOSI/MISO 没有接反。任何一项有问题,读 ID 都会先炸,比写一页数据再读回要快得多,也不会留下擦写痕迹。
3.2 写使能不是可有可无的礼节
所有写和擦除之前,必须先发写使能。这不是流程客套,是器件内部的硬性状态位。
c复制/* 写使能:任何写/擦除操作前必须执行 */
void W25Q_WriteEnable(void)
{
W25Q_CS_LOW();
W25Q_SPI_ReadWriteByte(0x06); /* Write Enable 命令 */
W25Q_CS_HIGH();
/* 手册建议等待一小段时间,或检查状态寄存器 WEL 位 */
}
0x06 之后,器件内部把写使能锁存位(WEL)置 1,接下来那一条写或擦除命令才会被执行;执行完成之后 WEL 自动清零,也就是说写使能是一次性的,每一条写/擦除命令前都得重新发一遍。这一点在写循环里最容易漏:写一页发一次写使能没问题,但如果打算连续写十页,每一页前面都得补一次,不能只发一次然后循环十次。
读操作不需要写使能,也不需要擦除。这是 W25Q128 和所有 NOR Flash 一样的性质:读是只读的,不改变任何单元。所以读函数里看不到写使能,不是省了,是本来就不该有。
写使能之后不要立刻发下一条命令,最好读一次状态寄存器确认 WEL 真的起来了。有些板子上 CS 的上升沿拖得太慢,写使能命令可能被截断,表现出来就是“写使能发过了,但写页返回后数据没变”。加一次状态检查,成本是一次 8 位读,收益是把这类偶发问题变成确定性失败。
3.3 状态寄存器与 BUSY 轮询
状态寄存器 1 是这套驱动里最重要的一个寄存器,0x05 命令读它,两个位要盯:bit0 是 BUSY,bit1 是 WEL。
c复制/* 读取状态寄存器 1(主要检查 BUSY 位和 WEL 位) */
uint8_t W25Q_ReadStatusReg1(void)
{
uint8_t status;
W25Q_CS_LOW();
W25Q_SPI_ReadWriteByte(0x05); /* Read Status Register-1 */
status = W25Q_SPI_ReadWriteByte(0xFF);
W25Q_CS_HIGH();
return status;
}
c复制/* 等待 Flash 就绪 */
void W25Q_WaitForBusy(void)
{
uint32_t timeout = 1000000; /* 超时兜底,防止死等 */
while ((W25Q_ReadStatusReg1() & 0x01) == 0x01) /* bit0 为 BUSY */
{
if (--timeout == 0)
{
/* 超时处理:打印错误日志或复位,别在这里空转 */
break;
}
}
}
为什么必须有这个函数?因为擦除和写入是器件内部的高压操作,耗时以毫秒到秒计:页编程典型 0.7 毫秒,扇区擦除 45 毫秒,块擦除 200 毫秒,全片擦除几十秒。在这段时间里,除了读状态寄存器和挂起类命令,发给它的任何命令都会被忽略——注意,是“忽略”而不是“返回错误”,你根本收不到任何反馈,数据就这么静默地没写进去。没有轮询的驱动,编译、下载、跑起来都正常,只是偶尔丢数据,这类问题查起来最折磨人。
timeout = 1000000 这个数不是随便写的:它保证在最坏情况下循环也能退出,而不是把 CPU 卡在一个 while 里等看门狗复位。循环体里可以把 HAL_Delay(1) 打开,也可以不打开——不打开轮询更密,擦除完成的第一时间就能继续;打开则省一点总线占用。我一般在不带 RTOS 的裸机工程里不打开,在带 RTOS 的工程里必须打开并配合让出 CPU,否则一个低优先级任务会把整个系统卡住。
4. 擦除与页编程:4KB 扇区和 256 字节页这两条硬约束
4.1 扇区号到 24 位地址的换算
W25Q128 是 16MB 容量,地址需要 24 位,所以任何带地址的命令后面都要连发三个字节:高 8 位、中 8 位、低 8 位。这一点在写地址的时候最容易出错的是顺序和位移量。
c复制/* 擦除一个扇区(4KB) */
void W25Q_EraseSector(uint32_t sector_addr)
{
sector_addr *= 4096; /* 传入的是扇区号,这里换算成字节地址 */
W25Q_WriteEnable(); /* 第一步:写使能 */
W25Q_WaitForBusy();
W25Q_CS_LOW();
W25Q_SPI_ReadWriteByte(0x20); /* Sector Erase 命令 */
/* 24 位地址,从高到低依次发出 */
W25Q_SPI_ReadWriteByte((sector_addr >> 16) & 0xFF);
W25Q_SPI_ReadWriteByte((sector_addr >> 8) & 0xFF);
W25Q_SPI_ReadWriteByte(sector_addr & 0xFF);
W25Q_CS_HIGH();
W25Q_WaitForBusy(); /* 第二步:等待擦除完成 */
}
0x20 是 4KB 扇区擦除命令,对应的块擦除是 32KB 和 64KB 的命令。这里的坑集中在第一行:sector_addr *= 4096 说明函数参数收的是“第几个扇区”而不是“字节地址”。如果调用方按字节地址传进来,比如想擦 0x00100000,传了 0x00100000,函数内部再乘 4096,地址直接飞到器件容量之外,器件会默默忽略这条命令,读回来还是老数据。所以在函数命名上我后来改成了 W25Q_EraseSectorByIndex,把“这是扇区号”写进名字里,比在注释里解释一遍管用。
三个字节的发送顺序也不能反。(addr >> 16) & 0xFF 是最高的 8 位,最后发 addr & 0xFF,这是 SPI Flash 的通用约定。把顺序写反了,现象是“擦除命令发了,但擦掉的不是你想要的扇区”,如果恰好落在合法地址范围内,你甚至不会立刻发现,直到某天发现配置区被清空。
4.2 页编程的跨页判断
写入的单位是页,256 字节。这里有一条很多人第一次写驱动时不知道的规则:页编程命令发出的地址如果加上数据长度越过了 256 字节边界,器件不会报错,而是会在页内回卷——写到页尾的下一字节自动绕回该页的页首,把开头刚写进去的数据覆盖掉。
c复制/* 写入一页数据(最多 256 字节) */
void W25Q_WritePage(uint32_t addr, uint8_t *data, uint16_t len)
{
if (len > 256) len = 256; /* 单次页编程不能超过一页 */
if ((addr & 0xFF) + len > 256) /* 检查是否跨页 */
{
/* 处理跨页逻辑:拆成两次页编程,这里留空 */
return;
}
W25Q_WriteEnable();
W25Q_WaitForBusy();
W25Q_CS_LOW();
W25Q_SPI_ReadWriteByte(0x02); /* Page Program 命令 */
W25Q_SPI_ReadWriteByte((addr >> 16) & 0xFF);
W25Q_SPI_ReadWriteByte((addr >> 8) & 0xFF);
W25Q_SPI_ReadWriteByte(addr & 0xFF);
for (uint16_t i = 0; i < len; i++)
{
W25Q_SPI_ReadWriteByte(data[i]);
}
W25Q_CS_HIGH();
W25Q_WaitForBusy();
}
(addr & 0xFF) + len > 256 这一句是跨页判断的核心:addr & 0xFF 取出页内偏移,加上本次长度,超过一页就说明会回卷。判断成立时不能简单 return 了事,正确做法是拆成两段:先写满当前页剩余空间,再把剩下的从下一页页首开始写。拆的时候第二段的地址必须是 (addr + 第一段长度),而不是手算一个取整值,手算容易差一个字节。
再往上一层还有一条铁律:写之前必须先擦除。NOR Flash 的位只能从 1 变 0,不能从 0 变 1,擦除是把整个扇区恢复成全 0xFF。所以“覆盖写”这个动作在 Flash 上根本不存在,必须先擦掉整个 4KB 扇区再重新写。擦除单位(4KB 扇区、32KB/64KB 块)远大于写入单位(256 字节页),这个不对称是所有上层存储管理都要面对的现实:改一个 4 字节的配置项,代价是擦掉 4KB 再重写。想省掉这个代价,就得在应用层做日志式追加或者双扇区轮换,那是另一个话题,驱动层不解决。
4.3 连续读为什么不需要写使能
读是整条链路里最便宜的操作,0x03 标准读命令,发完 24 位地址之后连续打时钟,数据就一位一位出来。
c复制/* 读取数据 */
void W25Q_ReadData(uint32_t addr, uint8_t *buffer, uint32_t len)
{
W25Q_CS_LOW();
W25Q_SPI_ReadWriteByte(0x03); /* Read Data 命令 */
W25Q_SPI_ReadWriteByte((addr >> 16) & 0xFF);
W25Q_SPI_ReadWriteByte((addr >> 8) & 0xFF);
W25Q_SPI_ReadWriteByte(addr & 0xFF);
for (uint32_t i = 0; i < len; i++)
{
buffer[i] = W25Q_SPI_ReadWriteByte(0xFF); /* 发 dummy 打时钟,收数据 */
}
W25Q_CS_HIGH();
}
读函数没有写使能、没有擦除、也没有 BUSY 轮询,因为读不会触发内部高压操作,从命令发出到数据出来是即时的。唯一的限制是 len 不能跨越器件容量,越界会回卷到地址 0 继续读,读出来的内容看着像数据,实际毫无意义。做自检的时候我一般会把读回来的首尾各打印几个字节,确认没有回卷。
0x03 标准读的上限时钟频率有限制,想跑到更高频率要用 0x0B 快速读,代价是地址后面要多发一个 dummy 字节。这个放到最后一章细说。
5. 避坑与排查:五个真机上翻过车的现象
5.1 读 ID 恒为 0xFF 或恒为 0x00
现象:上电第一件事读 JEDEC ID,返回值要么全 0xFF,要么全 0x00,波形在示波器上看还很干净。
原因基本锁定在三处:CS 从来没有真正被拉低(宏指向的端口或引脚和实际接线不一致,或者 GPIO 时钟没开);SPI 时钟模式配错(模式 0 和模式 3 各试一次就能排除);MISO 和 MOSI 接反。全 0xFF 通常意味着 MISO 被上拉、器件根本没被选中;全 0x00 通常是 MISO 被拉低或者根本没接。
解决:先万用表量 CS 在调函数前后的电平,确认宏生效;再把时钟模式换一种试;最后对调 MISO/MOSI。这三步按顺序做,能覆盖九成以上情况,不要一上来就换模块。
5.2 写完立刻读回,读出来还是 0xFF
现象:写页函数返回了,也没报错,立刻读同一地址,值还是 0xFF。
原因:没有先擦除。NOR Flash 只能把 1 写成 0,写进 0 的位必须先靠擦除恢复成 1。如果目标扇区从来没有擦过,里面本来就是 0xFF,写进去的位本该变成 0 却没变,说明写使能没生效或者命令被忽略;如果里面是上一次的旧数据,写出来的结果会是新旧值的按位与,看起来就像“没写进去”。
解决:任何写入之前,先对目标地址所在的 4KB 扇区做一次擦除,擦完读一遍确认是全 0xFF,再写。养成“擦—验—写—验”四步走的习惯,比事后猜要快得多。
5.3 一次写 300 字节,只有前 256 字节生效
现象:调用页编程想写 300 字节,读回来发现前 256 字节是对的,后面 44 字节把开头的内容覆盖了。
原因:页编程跨过了 256 字节边界,器件页内回卷。len 参数被截断成 256 只是防了一半,真正的跨页判断是 (addr & 0xFF) + len > 256,两个条件缺一不可。很多人只做了前一个截断,忘了后一个判断。
解决:在页编程里加跨页检测,跨了就拆成两次,第一段长度是 256 - (addr & 0xFF),第二段地址是 addr + 第一段长度。拆完每一段都要补一次写使能,不能共用。
5.4 擦除完紧接着写,数据丢失或者写失败
现象:擦除函数返回了,马上写页,写不进去;或者过一会儿再读,数据是碎的。
原因:擦除函数里 W25Q_WaitForBusy() 被注释掉了,或者超时设得太短提前 break 了。扇区擦除典型要 45 毫秒,某些批次和老化器件能到上百毫秒,超时值如果按页编程的 0.7 毫秒去设,一定提前退出。退出之后你以为擦完了,其实器件还在忙,接下来的写命令全部被忽略。
解决:把超时值放大到明显大于最坏情况(块擦除按 200 毫秒往上留余量,全片擦除按几十秒留),并且把超时分支写成打日志或者置错误标志,而不是静默 break。静默 break 是这类问题的根源,它把“失败”伪装成了“成功”。
5.5 长时间 while 轮询把系统卡死
现象:设备偶尔整机无响应,看门狗复位,复位后一切正常。
原因:W25Q_WaitForBusy 里没有超时,或者超时值设成了 0xFFFFFFFF。一旦 CS 被意外拉高、器件进入异常状态,BUSY 位可能长时间为 1,CPU 就一直在 while 里转,喂不了狗。
解决:超时值必须是一个有限数,循环里如果跑在 RTOS 下要主动让出 CPU;超时分支里做最小限度的恢复动作,比如强制拉高 CS、重新发一次读状态寄存器确认,而不是直接死循环。这个坑我踩过一次之后,所有轮询函数一律带超时参数,没有例外。
6. 用代码开发工具收尾:从标准读到 Fast Read 的验证方法
0x03 标准读够用,但它的时钟上限偏低,读大块字库或者日志区会明显拖慢。想提速就换 0x0B 快速读,命令和标准读几乎一样,唯一的差别是发完 24 位地址之后要先补一个 dummy 字节,再开始收数据。这个 dummy 字节是器件内部流水线需要的时间,少发一个,收到的整个数据流就整体错位一个字节,读出来全是乱码,而且因为地址对、命令对,你会怀疑是不是数据本身写坏了。
c复制/* 快速读:地址后多一个 dummy 字节,之后时钟频率可以提上去 */
void W25Q_FastRead(uint32_t addr, uint8_t *buffer, uint32_t len)
{
W25Q_CS_LOW();
W25Q_SPI_ReadWriteByte(0x0B); /* Fast Read 命令 */
W25Q_SPI_ReadWriteByte((addr >> 16) & 0xFF);
W25Q_SPI_ReadWriteByte((addr >> 8) & 0xFF);
W25Q_SPI_ReadWriteByte(addr & 0xFF);
W25Q_SPI_ReadWriteByte(0xFF); /* dummy 字节,少发一个整段错位 */
for (uint32_t i = 0; i < len; i++)
{
buffer[i] = W25Q_SPI_ReadWriteByte(0xFF);
}
W25Q_CS_HIGH();
}
切到快速读之前,先把标准读跑通、数据比对通过,再换命令,否则两种读法的错误现象会混在一起,定位成本翻倍。
驱动写完不等于能用,我一般会留一套上电自检,四步走完才算这颗 Flash 可以交付:
| 步骤 | 操作 | 通过标准 |
|---|---|---|
| 1 | 读 JEDEC ID | 三个字节与器件型号一致 |
| 2 | 擦一个扇区后整段读 | 连续 4KB 全为 0xFF |
| 3 | 写满一页 256 字节后读回 | 逐字节比对一致,首尾字节正确 |
| 4 | 跨页写 300 字节后读回 | 前后两段都正确,无回卷覆盖 |
这套自检我放在 main 的初始化阶段,跑不通就停在错误码上不往下走。比起到业务层才发现存储坏了,停在自检阶段要有用得多。自检里还要加一条:写完之后断电再上电读一次,验证数据在掉电后真的保住了——有些虚焊的板子通电时靠总线电容撑着能读对,掉电就露馅。
从那以后我每次接一颗新的 SPI Flash,都强制走一遍“读 ID、擦扇区、写页、跨页写、掉电重读”这五步,代码可以复用,这五步不能省。希望帮到你。
