简介：面向STM32F429嵌入式开发者与FatFs入门者，这份资料围绕SDIO接口驱动和FAT32文件系统移植，提供一套可直接编译的工程示例。压缩包共130个文件、仅2.51MB，以C源码为主：55个.c与64个.h，涵盖FatFs核心模块、STM32F4标准外设库驱动、BSP_SDIO_SD底层适配，以及Keil工程配置与说明文档，目录结构清晰，便于对照修改。目前已有1239人学习下载。借助该包可跳过繁琐的环境搭建，快速验证SD卡读写、挂载与文件操作；代码内含硬件初始化、disk_read/disk_write等接口映射及错误处理，适合需要移植文件系统或排查SDIO读写异常的学习者作为参考模板，能显著缩短开发周期。
1. 这个工程到底解决了什么问题
如果你玩过STM32F429，多半绕不开SD卡存储。很多人一开始拿SPI接口驱动TF卡，读个扇区还行，一旦涉及录音、数据采集、GUI图片资源这类高吞吐量场景，SPI那点带宽立刻就变瓶颈。我最初也是这么干的，SPI模式下读1MB文件硬生生等了几秒，后来换SDIO接口之后，同样是读大文件，等待时间直接砍掉一个数量级。这个stm32f429_sdio_fatfs_test.rar测试工程，干的事情就是把SDIO高速读写和FATFS文件系统组合起来，在F429上跑通一张TF卡的全套读写、创建、删除、追加操作。
这个工程适合谁？一类是做数据记录仪、音频播放器、图像采集设备的嵌入式工程师，另一类是刚入门FATFS移植、想把SD卡驱动跑起来的同学。工程麻雀虽小五脏俱全，从底层SDIO寄存器配置到上层f_open/f_read调用，整条链路全部打通，你解压之后烧进去改个引脚就能用，相当于直接把“SDIO+FATFS”的完整骨架给了你，剩下的业务逻辑你自己往上填。
如果你用的芯片恰好是国产GD32F407或者APM32F407这类兼容型号，这套代码同样有很强的参考价值。它们的内核和SDIO外设与STM32F4系列大概率同源，我以前在GD32F407上直接改了改中断号就把它跑起来了，后面我会专门说这块的坑。
2. SDIO方案的选型逻辑与FATFS的定位
2.1 为什么是SDIO而不是SPI
很多人习惯用SPI驱动SD卡，因为它引脚少、代码简单，ST的SPI主频最高跑到45MHz，听起来也不差，但实际传输效率远达不到理论值。SPI模式下SD卡每次命令都有握手应答，数据线只有一根，而且多数SD卡在SPI模式下只支持低速读写，真实吞吐量能跑到2MB/s就已经谢天谢地。SDIO则完全不同，STM32F429的SDIO接口最高支持48MHz时钟，4根数据线并行传输，实测读写速度可以稳定在15MB/s以上，如果开DMA还能把CPU占用率压到很低。
这里需要注意，SDIO接口的48MHz不是直接就那么用的。SD卡上电默认按1位模式、低速率跑，你要在初始化阶段先跟卡协商，把总线宽度从1位切到4位，把时钟频率从400kHz慢慢提上去。很多新手一上来就把分频配成0，结果卡初始化直接卡死，就是因为没搞清楚这个“先低速握手、后高速传输”的时序要求。
2.2 FATFS在整条链路里扮演什么角色
SDIO驱动本身只管“往某个扇区地址写数据”或者“从某个扇区读数据”，它不知道什么是文件、目录、文件夹，更不知道文件名规则。FATFS就是中间那层翻译官，它把用户对文件的操作转换成对扇区的读写请求，再交给SDIO驱动去执行。打个比方，SDIO像一条高速公路，FATFS像交通调度中心，你只需要告诉调度中心“我要去某个目的地”，它就能规划路线，但最终跑路的还是公路本身。
这个工程选的是FATFS R0.11以上的版本，开箱即用，支持的卡容量上限是2TB，对于绝大多数TF卡用户完全够了。你可以用f_mount挂载SD卡，用f_open创建文件，用f_write写数据，用f_read读数据，代码可读性比直接操作扇区好太多。而且FATFS是纯C写的，不依赖任何操作系统，裸机环境下跑得飞起，工程里也没有把RTOS硬塞进来增加复杂度，这点很良心。
2.3 工程文件结构一眼看穿
解压这个rar之后，目录结构大致是这样的：Core目录下放的是启动文件和中断处理函数，Drivers目录下是STM32F4xx标准外设库或者HAL库（取决于工程生成的版本），FATFS目录下分diskio.c和ff.c、ffconf.h这几个文件，还有一个顶层main.c和sdio_test.c。你重点要改的其实只有三个地方——sdio底层初始化函数、diskio.c里的读写钩子函数、ffconf.h里的配置宏。这三处改明白了，整套系统就跑通了。
3. SDIO初始化与底层机制的核心要点
3.1 时钟链路与分频计算
STM32F429的SDIO外设挂载在APB2总线上，APB2最高90MHz，但SDIO模块自带一个独立的时钟分频器，输入是48MHz的SDIOCLK。你要设置的寄存器叫CLKDIV，最终输出的SDIO_CK频率公式是：SDIO_CK = SDIOCLK / (2 + CLKDIV)。初始化阶段要保证时钟在400kHz以下，那么CLKDIV就要配成48MHz / 400kHz - 2 ≈ 118，取整就是118。等到卡识别完成、切到高速模式之后，再把CLKDIV调小，比如设成0，此时SDIO_CK就是24MHz。虽然理论上能跑到48MHz，但实测多数TF卡在24MHz下最稳，再高容易偶尔出错，稳定性优先的话保留24MHz比较合理。
这个计算过程建议你直接写成宏定义，比如：
#define SDIO_INIT_CLK_DIV 118 // 400kHz初始化时钟 #define SDIO_SPEED_CLK_DIV 0 // 24MHz高速模式初始化后如果发现卡握手失败，先别急着查电路，看看CLKDIV是不是设成0了。我见过好几个工程，初始化时直接用高速时钟去发CMD0，结果CMD0发出去卡根本没反应。
3.2 从1位模式切到4位模式的过程
SDIO的初始化流程大致是：上电延时、发CMD0进入空闲态、发CMD8确认电压范围、发ACMD41反复查询卡是否上电完成、发CMD2获取CID、发CMD3获取RCA，最后发CMD7选择卡。这些命令全部走CMD线，数据线此时处于空闲状态，所以先用1位模式完全没问题。等CMD7选中卡之后，再发ACMD6设置总线宽度为4位，然后修改SDIO控制寄存器里的WIDBUS位，这时4根数据线才能真正开始传输数据。
很多教程直接告诉你“要配4位模式”，却没说清楚什么时候切。正确的顺序一定是“先1位初始化，再4位传输”，顺序反了卡是铁定初始化不过去的。而且要注意，ACMD6之前必须先发CMD55作为前缀，因为ACMD开头的命令都属于“特定应用命令”，SD卡规定要先发送一个普通CMD55唤醒卡，才能识别后面的ACMD6。工程里封装的SD_Init函数已经在初始化流程里帮你把这个顺序处理好了，你只需要照抄结构，不需要自己从头捋时序。
3.3 DMA配置到底怎么选
F429若不开DMA，SDIO每接收一个4字节数据就要CPU去读一次FIFO，高速模式下基本跑满CPU，效率惨不忍睹。工程里用的是DMA2，SDIO接收是DMA2的Channel4，发送是Channel6，数据流可以选择Stream0到Stream3任一一个，只要跟SDIO的中断请求号匹配上就行。配置要点是数据方向必须跟SDIO模式严格对应——读卡时外设到内存，写卡时内存到外设，方向搞反了DMA永远进不了完成中断。
另一个容易踩坑的点是DMA地址对齐。FATFS传入的缓冲区地址一般是malloc出来的，只能保证4字节对齐，但SDIO的FIFO要求数据宽度是32位，如果缓冲区地址不是4的倍数，DMA传输就会直接进入错误状态。我建议你在disk_read和disk_write里加一个判断：当缓冲地址不对齐时，先把数据拷到一个对齐的临时数组里，再走DMA。虽然多一次memcpy，但省下来的排查时间绝对值得。
FATFS真正常规操作里，写入一个512字节扇区所需时间大概在零点几毫秒，CPU全程不参与搬运，只有DMA完成中断把CPU叫醒一次。这也是SDIO方案碾压SPI方案的底气来源。
4. FATFS移植的必要改造点
4.1 diskio.c里六个必须实现的函数
FATFS要跑起来，依赖diskio层提供的六个接口：disk_status、disk_initialize、disk_read、disk_write、disk_ioctl、get_fattime。其中disk_read和disk_write直接调用SDIO驱动的扇区读写函数，它们负责把用户的扇区号、缓冲区指针、扇区数量原封不动传给SDIO层。这个工程里用的是HAL库封装，操作非常简单：
DRESULT disk_read(BYTE pdrv, BYTE *buff, LBA_t sector, UINT count) { // 检查卡是否初始化完成 if (Stat_Check() != 0) return RES_NOTRDY; // 底层4位DMA读 if (SD_ReadMultiBlocks(buff, sector << 9, 512 * count) != 0) return RES_ERROR; // 等待DMA传输完成 while (SD_GetState() != SD_TRANSFER_OK); return RES_OK; }这里有个容易忽略的细节：sector << 9是因为SD卡以512字节为一扇区，sector编号要换算成字节地址，左移9位等价于乘以512。如果直接用sector当作地址传给底层，卡根本不知道你要操作哪个区域。
4.2 ffconf.h里的关键开关
FATFS的配置集中在ffconf.h里，不是所有宏都默认打开，有些你没开直接用就会报编译错或者运行错。以这个工程为基准，我建议你至少检查这几个配置项：
| 宏名称 | 推荐值 | 作用说明 |
|---|---|---|
| FF_USE_LFN | 1或2 | 支持长文件名，不开则只能操作“8.3”短文件名 |
| FF_VOLUMES | 1 | 卷数量，只挂一张卡就设1 |
| FF_MIN_SS / FF_MAX_SS | 512 / 512 | 扇区大小，SD卡固定512即可 |
| FF_USE_MKFS | 1 | 允许格式化函数，调试时特别有用 |
| FF_USE_STRFUNC | 1 | 允许f_printf格式化写入，方便日志输出 |
| FF_FS_RPATH | 1 | 开启相对路径支持，方便逐级进入目录 |
特别强调一下FF_USE_LFN，如果不打开，你创建一个test_data_20250101.txt都会报错文件名过长。但如果打开，你又得考虑缓冲区放在栈上还是静态区——工程默认放在静态区，占掉几百字节RAM，对F429这种RAM大户无所谓，对小内存芯片就要掂量一下了。
4.3 长文件名和磁盘格式化的小经验
长文件名功能打开后，f_mount挂载一个未格式化的空卡，返回的错误通常是FR_NO_FILESYSTEM。别慌，这不是驱动问题，是卡里没有FAT文件系统，工程里专门留了一段用f_mkfs格式化SD卡的测试代码。在调试阶段，我强烈建议你把FF_USE_MKFS打开，之后调用一次f_mkfs，再f_mount一次，就万事大吉。千万别自己拿电脑把TF卡格式化成exFAT格式，FATFS默认不带exFAT支持，识别不了。用Windows格式化时一定要选FAT32。
5. 实操过程与调试记录
5.1 硬件连接与CubeMX配置速记
F429的SDIO引脚是固定的，PA8是CLK，PC12是CMD，PC8/PC9/PC10/PC11是DATA0到DATA3，PB15是CD（卡检测），PD2是WP（写保护）。如果你的板子没把CD和WP拉出来，直接把它们设成上拉输入就行，这两个引脚不接也能跑。很多人问我能不能换几个引脚，答案是SDIO引脚在F429上是高度固定的，不能像普通GPIO那样任意映射，换引脚意味着换芯片选型。
CubeMX里配置SDIO时记得做三件事：打开4位总线模式、把时钟频率初始化成400kHz、使能SDIO的全局中断。DMA在CubeMX里也能直接配置，但要注意把DMA2的IRQHandler和SDIO的中断服务函数正确关联起来。工程用的是HAL库，中断回调是HAL_SD_TxCpltCallback和HAL_SD_RxCpltCallback，在里面置一个标志位，主循环等这个标志位置位再继续，简单高效。
我实测的引脚接法是：TF卡座和数据线距离F429芯片尽量短，数据线最好等长，差分走线的说法有点夸张，但也要尽量让四根数据线长度接近，地线要铺实。之前一块板子数据线走了十几厘米飞线，结果读写经常超时，改成短走线后问题消失。
5.2 初始化、写文件、读文件一条龙
工程里的测试流程很简单：上电初始化SDIO、挂载FATFS、打开或创建一个test.txt文件、写入一段字符串、关闭文件、再以读模式打开、把内容读回来打印到串口。如果串口助手能完整打印出写入的字符串，说明SDIO和FATFS已经彻底跑通。这个流程不是花架子，它覆盖了文件系统最核心的创建、写入、关闭、打开、读取五个操作，线上生产环境的代码骨架基本就是这一套再包裹业务逻辑。
我在实际测试中写入1MB数据的耗时大约在100ms左右，读回1MB大约70ms，这个数据是主频180MHz、DMA开启、24MHz SDIO时钟下的表现。如果你的速度差很远，先检查是不是没有开DMA，其次检查是不是总线宽度还是1位，最后检查卡是不是低速卡。
5.3 一个完整的写日志缓冲方案
在数据采集类的项目里，频繁f_write很拖慢主循环，因为FATFS每次写入都可能触发一次扇区擦写。我有一个惯用思路：把要写的日志先拼到一个内存缓冲里，凑够512字节或者1KB，再一次性写入文件。这样叫“攒批写入”，对SD卡寿命和写入速度都有好处。你也可以用f_sync定期把缓存刷到卡里，防止突然断电丢数据。这个工程里没有专门演示缓存机制，但你可以基于它的f_write结构自行扩展。
6. 常见问题与排查技巧实录
6.1 卡初始化失败，卡返回CID错误
这是最常见的问题。先用排除法：换一张卡试试，排除卡本身故障；再用示波器量SDIO_CLK引脚，确认初始化时钟在400kHz左右；再用万用表量CMD和DATA线上的上拉电阻，SDIO协议要求这些线必须上拉10k到50k电阻到3.3V。三件事排查完，八成问题就找到了。
如果是自制板，还要检查TF卡座的焊接和供电。TF卡座的VDD引脚必须接一个较大容量的滤波电容，比如10uF或以上，很多卡初始化失败正是因为供电瞬间跌落。这个问题在裸片卡座上尤其常见，插上卡的一瞬间电流尖峰直接拉低电源，卡直接进入欠压保护。
6.2 DMA超时，读卡卡死在发送状态
DMA超时通常有四个根源：一是DMA方向配错了；二是缓冲区地址没对齐；三是SDIO没有使能全局中断；四是中断服务函数里没有及时清标志位。我建议在HAL_SD_IRQHandler之后，检查htex结构中的错误码，把错误码打印出来，再对照HAL库的源码去定位。别凭感觉猜，直接看寄存器更可靠。
6.3 挂载成功但f_open返回FR_DENIED
FR_DENIED一般是权限问题，常见的场景是卡上只读属性生效了，或者是文件被其他程序占用（比如你电脑上还插着这张卡在调试，Windows没正常弹出）。最简单的方法是先格式化，或者换一张卡试试。如果连续两张卡都FR_DENIED，那就要检查ffconf.h里的FF_FS_READONLY是不是被误开成1了，这个宏一旦打开，所有写操作都会被拒绝，但编译却不报错，非常阴间。
6.4 热插拔造成文件丢失
FATFS不是为热插拔设计的，SD卡也不例外。万一切断写数据的瞬间拔卡，非常容易造成FAT表错乱，轻则刚写的文件丢失，重则整张卡需要重新格式化。工程里没有写防止热插拔的机制，但你在自己项目里至少要加一个写保护逻辑：当检测到SDIO的CD引脚电平变化时，延迟几秒后自动执行f_mount(NULL, ...)卸载文件系统，再进行关机流程。
6.5 GD32、APM32等国产芯片克隆注意点
国产F4系列芯片的SDIO外设基本都是对标STM32设计的，代码层面改动不大。我在GD32F407上踩过两个坑：一是GD32的SDIO时钟分频公式略有不同，最好读一下参考手册确认DIV值怎么填；二是GD32的DMA请求号可能跟ST不是完全一致，需要优先查看用户手册的DMA映射表，否则DMA永远触发不了。FATFS层代码完全通用，真正要看清的是你的芯片SDIO外设寄存器的兼容细节，不要想当然盲抄。
7. 工程外延：能不能再往上走一层
跑通F429+SDIO+FATFS之后，你可以在这个基础上去做几件很有价值的事。一是把文件写入改成双缓冲乒乓模式，一边采集数据一边写卡，这对数据记录仪类产品至关重要；二是引入RTOS，把SDIO驱动放进独立线程，用消息队列传递读写请求，整个系统响应会从容很多；三是对接SPIFlash，你会发现F429的QSPI也能跑FATFS，用同样的调用方式操作W25Q256这类外部Flash芯片，完全可以做一个小型文件系统。这也是为什么很多产品里同时出现SD卡和SPI Flash两个存储器件，它们跑FATFS的路数一模一样，底层钩子函数不同而已。
我手头这个工程之后扩展的方向就是加一个“循环记录”功能，用f_lseek配合文件大小判断来实现环形写入，听起来很高级，其实底层还是f_write那点事。拿到这个工程别急着删，它就是你后续所有存储类项目的出发点。
本文还有配套的精品资源，点击获取
