STM32 SD卡FATFS文件系统移植与读写实战

简介围绕STM32平台读取SD卡并挂载FATFS文件系统这套实战工程包面向嵌入式初学者、课程设计学生及需要快速验证存储方案的开发者重点解决SPI/SDIO接口下SD卡初始化、扇区读写与文件系统移植问题。资料将HAL库、FATFS配置、KEIL工程组织与文件操作示例整合在一起可用于数据记录、配置存储等场景的原型搭建。压缩包共229个文件以83个C源文件和83个头文件为核心配合36个汇编启动文件及工程配置、说明文档等整体约1.48MB目录中保留完整工程结构便于对照编译与裁剪。已有3377人学习下载。读者可从中获得可编译的KEIL工程、SD卡底层驱动与FATFS接入思路并借鉴文件打开、读写、关闭及异常处理的组织方式适合作为课程实践和项目移植的参考底稿。1. 从一张读不出来的卡说起这套 SD 卡 FATFS 方案到底解决什么问题一块 STM32 板子插上 SD 卡跑一个读文件的例程很多人把它当成新手练手项目直到f_mount返回FR_NO_FILESYSTEM而同一张卡插到电脑上一切正常。这套基于 STM32 的 SD 卡读取 FATFS 文件系统方案真正的价值点在于把“卡能不能被认出来”这件事拆成可定位的几层SPI 或 SDIO 的物理时序、diskio.c里的扇区读写、ffconf.h的配置开关、最后才是f_open那层 API。适合手里有 STM32 板子、要给设备加一个本地存储或数据导出功能的开发者也适合想在裸机环境里跑通文件系统、后续接 USB 或网络传输的人熟手能在这套分层里直接改底层驱动新手照着顺序也能把第一行日志写进卡里。2. 硬件与工程骨架SPI 还是 SDIO文件从总线到扇区的完整通路拿到需求先别急着写f_open先确定卡怎么接到 MCU 上。这一步选错后面所有调试都会变成玄学。2.1 接口选型与最小系统连线STM32 接 SD 卡常见两条路SPI 和 SDIO。SPI 的好处是引脚少、任意 SPI 外设都能用、驱动写起来直观缺点是速度被压在十几兆以内且一张卡独占一个 SPISDIO 走 4 位数据线理论带宽高得多适合连续采样落盘但引脚固定、DMA 配置和时钟树要一起调。我一般这样分数据量小、只是偶尔导个配置或日志用 SPI 足够调试成本最低要做音频、图像或高频传感器记录直接上 SDIO别在中途换方案换一次等于底层重写。SPI 模式下连线是 SCK、MOSI、MISO、CS 四根加上 3.3V 和地CS 建议用软件控制初始化阶段要在发命令前手动拉低、发完拉高硬件 NSS 在一些型号上行为不好控。SDIO 模式则是 CLK、CMD、D0D3外加卡检测脚CD可选。电源部分容易被忽略SD 卡在写入瞬间电流会冲到 100mA 以上板子上的 3.3V LDO 如果余量不够表现就是“读正常、写随机失败”。这不是代码问题是供电问题先量电压再改程序。提示SPI 的 MOSI/MISO 上建议串 22100 欧电阻长线或飞线接卡座时能压住过冲省掉很多偶发 CRC 错误。2.2 工程目录与分层结构这套工程我习惯按“总线层 → 扇区层 → 文件系统层 → 业务层”四层摆目录大致长这样project/ ├── Drivers/ │ ├── sd_spi.c / sd_spi.h # 卡初始化、命令、扇区读写 │ └── diskio.c # FATFS 要求的 6 个移植函数 ├── Middlewares/ │ └── fatfs/ │ ├── ff.c / ff.h │ ├── ffconf.h # 配置开关全在这里 │ └── diskio.h ├── App/ │ ├── storage.c # 挂载、打开、写日志的封装 │ └── main.c └── BSP/ └── bsp_spi.c # SPI 外设与片选s d_spi.c只认命令和扇区号不认文件名diskio.c把 FATFS 的disk_read/disk_write翻译成sd_read_blocks/sd_write_blocksstorage.c才是业务侧真正调f_open的地方。这样分层的好处是换接口时只动前两层ff.c一行不改。2.3 时钟、DMA 与初始化顺序SD 卡上电后的第一段通信必须慢。规范要求识别阶段时钟不超过 400kHz很多卡在 1MHz 以上就开始不响应 CMD0。所以初始化分两步先低速发命令把卡识别出来再切高速跑数据。/* SPI2 低速初始化APB1 36MHz / 128 281kHz落在 400kHz 以内 */ static void sd_spi_low_speed(void) { SPI_InitTypeDef spi; SPI_StructInit(spi); spi.SPI_Direction SPI_Direction_2Lines_FullDuplex; spi.SPI_Mode SPI_Mode_Master; spi.SPI_DataSize SPI_DataSize_8b; spi.SPI_CPOL SPI_CPOL_High; /* 模式 3卡在时钟上升沿采样 */ spi.SPI_CPHA SPI_CPHA_2Edge; spi.SPI_NSS SPI_NSS_Soft; /* 片选手动控制 */ spi.SPI_BaudRatePrescaler SPI_BaudRatePrescaler_128; spi.SPI_FirstBit SPI_FirstBit_MSB; SPI_Init(SPI2, spi); SPI_Cmd(SPI2, ENABLE); } /* 识别完成后切高速36MHz / 4 9MHz先别一上来就 18MHz */ static void sd_spi_high_speed(void) { SPI2-CR1 ~SPI_CR1_SPE; SPI2-CR1 (SPI2-CR1 ~SPI_CR1_BR) | SPI_BaudRatePrescaler_4; SPI2-CR1 | SPI_CR1_SPE; }SPI_BaudRatePrescaler_128是分频系数不是频率值算的时候用外设挂载的总线时钟去除。SPI_CPOL/CPHA固定为模式 3这是 SD 卡 SPI 模式的标准时序改错的表现是命令能发出去但回的永远是 0xFF。初始化顺序我固定为GPIO → SPI 低速 → 上电延时至少 1ms让卡内部稳压器稳定→ 发 80 个时钟 → CMD0 进 idle → CMD8 查电压 → ACMD41 等卡就绪 → CMD58 读 OCR 判断是不是 SDHC → 切高速。少一步都可能让某些卡“时好时坏”。SDIO 模式下顺序类似但多一步 DMASDIO的 IDMA 要配成双缓冲或单缓冲接收/发送的缓冲区必须 4 字节对齐且不能放在栈上临时变量里否则 DMA 搬运时地址对不齐会直接进错误中断。3. FATFS 移植层diskio.c 六个函数怎么落到 SD 卡上FATFS 是纯软件层它不知道底下是 SD 卡还是 NAND全部通过diskio.c里那几个函数拿扇区。这一层写对了ff.c就是黑盒。3.1 ffconf.h 里必须先改的几个开关ffconf.h是这套代码里最容易被跳过、也最容易埋雷的文件。默认配置面向小内存直接拿来用会在几个地方翻车宏默认/建议作用与踩坑点_FS_READONLY0置 1 后所有写 API 被裁掉只读场景可省 flash_USE_MKFS1需要格式化的板子要开否则只能用电脑预格式化_USE_LFN1 或 20 时只支持 8.3 短名中文名直接丢失_MAX_SS512必须是 2 的幂改大改小都要跟卡的实际扇区一致_MIN_SS512与_MAX_SS一起决定扇区缓冲大小_VOLUMES1挂多个分区或卡才需要加_FS_REENTRANT0多任务同时读写必须开并实现ff_req_grant/ff_rel_grant_FS_TINY0置 1 省 RAM但一次只能有一个文件对象在读写_USE_LFN开到 1 时长文件名缓冲放在栈上深度不够会直接 HardFault开到 2 用堆要保证_MAX_LFN乘上字符宽度不超过堆余量常见做法是给 255 字节的静态缓冲。中文文件名还有一个隐含条件_CODE_PAGE要选 936GBK或 437/850 之外的值否则目录里读出来的是一串问号。3.2 disk_initialize / disk_status 的实现这两个函数决定 FATFS 认为“卡在不在”。返回值不是布尔是一组状态位组合。#include ff.h #include diskio.h #include sd_spi.h #define DRV_SD 0 DSTATUS disk_status(BYTE pdrv) { if (pdrv ! DRV_SD) return STA_NOINIT; /* 卡被拔掉或初始化失败时返回 STA_NOINITFATFS 会拒绝后续操作 */ return sd_card_ready() ? 0 : STA_NOINIT; } DSTATUS disk_initialize(BYTE pdrv) { if (pdrv ! DRV_SD) return STA_NOINIT; if (sd_init() ! SD_OK) { return STA_NOINIT | STA_NODISK; /* 没卡或初始化失败 */ } return 0; /* 0 表示就绪 */ }STA_NODISK表示物理上没有卡STA_NOINIT表示初始化没完成两个可以叠加。disk_status不要写成每次都重新初始化卡它会被 FATFS 频繁调用重初始化会把正在进行的写操作打断。3.3 disk_read / disk_write 与扇区对齐读写函数是把 FATFS 的扇区号转成 SD 卡命令。SPI 模式下读单块用 CMD17、写单块用 CMD24连续多块用 CMD18/CMD25能明显减少命令开销。DRESULT disk_read(BYTE pdrv, BYTE *buff, LBA_t sector, UINT count) { if (pdrv ! DRV_SD || count 0) return RES_PARERR; /* sector 是逻辑块地址SDHC 卡直接按块寻址标准卡要乘 512 */ if (sd_read_blocks((DWORD)sector, buff, count) ! SD_OK) return RES_ERROR; return RES_OK; } DRESULT disk_write(BYTE pdrv, const BYTE *buff, LBA_t sector, UINT count) { if (pdrv ! DRV_SD || count 0) return RES_PARERR; if (sd_write_blocks((DWORD)sector, buff, count) ! SD_OK) return RES_ERROR; return RES_OK; }LBA_t在 FATFS R0.13 之后才有早期版本是DWORD从旧工程迁移时这个类型对不上会报一堆编译错误先把ff.h版本确认清楚。buff的地址必须能按 4 字节对齐DMA 模式下更是硬要求否则搬出来的数据整体错位表现是文件能打开但内容是乱码。写函数里还有一个隐含动作写完一个扇区后卡内部要编程这段时间不响应新命令必须等忙信号释放再返回否则下一次读会拿到旧数据。3.4 disk_ioctl 的 CTRL_SYNC 和 GET_SECTOR_COUNTdisk_ioctl是 FATFS 用来问底层能力的接口最常被调用的是这三个命令DRESULT disk_ioctl(BYTE pdrv, BYTE cmd, void *buff) { if (pdrv ! DRV_SD) return RES_PARERR; switch (cmd) { case CTRL_SYNC: /* 刷缓存等卡内部写完 */ return sd_wait_ready() SD_OK ? RES_OK : RES_ERROR; case GET_SECTOR_COUNT: /* 总扇区数f_mkfs 要用 */ *(DWORD *)buff sd_card_capacity_blocks(); return RES_OK; case GET_SECTOR_SIZE: /* 单扇区字节数 */ *(WORD *)buff 512; return RES_OK; case GET_BLOCK_SIZE: /* 擦除块大小单位扇区 */ *(DWORD *)buff 1; return RES_OK; default: return RES_PARERR; } }CTRL_SYNC不能空实现直接返回RES_OK那样f_sync就失去意义掉电时最后几条记录必然丢。GET_BLOCK_SIZE返回 1 是最保守的写法格式化时按单扇区擦除速度慢但兼容性最好知道卡的实际擦除块大小可以填大能显著加快f_mkfs。4. 文件操作实战挂载、遍历、读写与日志落盘底层通了之后业务侧真正每天打交道的就那几个 API但顺序和参数错一个现象都长得差不多。4.1 f_mount 与路径前缀f_mount是文件系统的入口它把FATFS对象和某个逻辑盘符绑起来。第三个参数在 R0.13 之后才有表示是否立即挂载旧版本只有两个参数直接调用会编译不过。FATFS fs; FIL logf; FRESULT storage_init(void) { FRESULT fr f_mount(fs, 0:, 1); /* 1 立即挂载并检查 */ if (fr ! FR_OK) return fr; /* FA_OPEN_ALWAYS不存在就创建存在就打开适合日志文件 */ fr f_open(logf, 0:/log/data.csv, FA_OPEN_ALWAYS | FA_WRITE | FA_READ); if (fr ! FR_OK) { f_mount(NULL, 0:, 0); /* 失败要卸载避免状态残留 */ return fr; } f_lseek(logf, f_size(logf)); /* 定位到文件末尾做追加 */ return FR_OK; }路径里的0:是逻辑盘符必须和_VOLUMES对得上0:/log/data.csv这种写法要求log目录已经存在f_open不会自动建目录得先f_mkdir。挂载失败先看返回值FR_NO_FILESYSTEM是卡上没有识别到 FAT 结构FR_DISK_ERR是底层读写失败FR_NOT_READY是卡没初始化好三种原因完全不同不要一上来就怀疑卡坏了。4.2 目录遍历与文件筛选导出数据、查找最新日志都离不开遍历目录。f_readdir的结束条件是返回的文件名为空不是返回错误码。FRESULT list_dir(const char *path) { DIR dir; FILINFO fno; FRESULT fr f_opendir(dir, path); if (fr ! FR_OK) return fr; while (1) { fr f_readdir(dir, fno); if (fr ! FR_OK || fno.fname[0] 0) break; /* 空名 读完 */ if (fno.fattrib AM_DIR) { /* 目录项递归前先确认栈够深别在中断里递归 */ } else { /* fno.fsize 是 32 位大小fno.fdate/ftime 是修改时间 */ } } f_closedir(dir); return FR_OK; }FILINFO里的fname在_USE_LFN打开时是长文件名否则是 8.3 短名。遍历大目录时不要每读一项就打开文件f_open的开销远大于f_readdir先按名字或后缀筛再对命中项操作。4.3 按块读写与追加写日志写日志最忌讳一次f_write写一大块然后长时间不刷。正确做法是小块多次写每次写完调f_sync。FRESULT append_record(const char *line, UINT len) { UINT bw 0; FRESULT fr f_write(logf, line, len, bw); if (fr ! FR_OK || bw ! len) return FR_DISK_ERR; /* 每条都同步牺牲吞吐换掉电安全批量场景可改成每 N 条或定时刷 */ return f_sync(logf); }f_write的第三个参数是请求写入的字节数第四个是实际写入数两者不等就说明卡写满了或底层出错。大文件顺序读用f_read循环配 512 字节对齐的缓冲一次读 4KB8KB 比较平衡缓冲太小命令开销占比高太大占 RAM。4.4 掉电保护f_sync 的时机FATFS 默认有写缓存f_write返回成功不代表数据已经落到卡上。设备突然断电缓存里那部分就没了文件长度可能还是 0。策略看场景日志类数据要求“最多丢最后一条”就每条f_sync批量采集要求吞吐就按时间或条数攒批比如每 2 秒或每 64 条刷一次同时在掉电检测中断里补一次f_sync。前提是掉电检测的保持电容够大能撑到刷完。注意f_sync内部会调disk_ioctl(CTRL_SYNC)如果那个函数是空实现这里的保护就是假的。5. 常见问题排查五个把调试时间拉长的坑这一章按“现象 → 原因 → 解决”记都是实际调试里反复出现的。5.1 f_mount 返回 FR_NO_FILESYSTEM但卡在电脑上正常现象同一张卡电脑能读能写板子上f_mount就是失败换一张小容量卡反而好了。原因通常有两个。一是卡被格式化成 exFAT 或 NTFSFATFS 默认只认 FAT12/16/32大容量卡出厂经常是 exFAT。二是分区表类型是 GPTMBR 解析拿不到分区起始扇区。三是_MAX_SS和卡的实际扇区大小不一致读出来的 BPB 全是错位数据。解决先在电脑上确认文件系统类型格式化成 FAT32 再试容量超过 32GB 的卡用第三方工具格式成 FAT32。确认分区表是 MBR。然后核对ffconf.h里_MAX_SS/_MIN_SS都是 512disk_ioctl的GET_SECTOR_SIZE也返回 512。三步走完还不行就把读到的第一个扇区前 64 字节打印出来看0x55AA在不在、0xEB跳转指令在不在一眼就能判断是读错了还是解析错了。5.2 f_open 偶发 FR_DISK_ERR重启后又正常现象跑一段时间随机失败失败率不高但一直有示波器看 SPI 波形也正常。原因多半是写操作没等卡忙完。SPI 模式写扇区后卡内部编程需要几毫秒这期间发任何命令都返回 0xFF代码如果没检查忙信号直接发下一条就会拿到错误响应。另一个可能是 SPI 时钟切太高9MHz 能跑但 18MHz 就不稳卡与卡之间差异很大。解决在sd_write_blocks结尾加忙等待超时给 500ms超时返回错误而不是死等。SPI 高速分频先退回 8 或 16稳定后再往上试。DMA 模式下检查收发缓冲是否 4 字节对齐、是否放在会被编译器优化掉的位置。5.3 写入成功拔卡后文件长度是 0现象程序里f_write返回FR_OKf_size也在涨断电或复位后文件变空或者只剩最后一段。原因是没有f_sync或者f_sync调了但CTRL_SYNC是空实现。FATFS 的目录项和 FAT 表更新有延迟文件长度字段要等同步时才写回。解决关键数据每次写完调f_syncdisk_ioctl的CTRL_SYNC必须等卡忙释放关闭文件用f_close而不是只把FIL对象丢掉。调试阶段可以在每次f_sync后重新f_open读一遍长度做校验确认真的落盘了。5.4 中文文件名读出乱码或直接不显示现象电脑上命名的中文文件板子上遍历出来是问号或者干脆跳过。原因_USE_LFN为 0 时只保留 8.3 短名中文被截断_CODE_PAGE不是 936 时GBK 编码的字节按单字节码页解析出来就是乱码。栈空间不够时_USE_LFN1还会直接跑飞。解决_USE_LFN设 1 或 2_CODE_PAGE设 936_MAX_LFN给 255_USE_LFN1时把启动文件里的栈调大至少 1KB 余量遍历时用fno.fname直接按字节处理不要假设它是 UTF-8。5.5 多任务同时读写直接死机或返回 FR_TOO_MANY_OPEN_FILES现象单任务跑得好好的加了 RTOS 或中断里也写日志之后偶发死机、返回FR_LOCKED或打开文件数超限。原因FATFS 默认不可重入ff.c内部的静态变量会被并发踩坏同时打开的文件数超过_FS_LOCK设定值在中断里调用文件 API而中断优先级高于正在执行的文件操作。解决_FS_REENTRANT置 1 并实现ff_req_grant/ff_rel_grant两个同步函数用二值信号量即可_FS_LOCK按实际并发打开数配置文件操作统一放到一个任务里其他任务通过队列把数据交给它中断里只往环形缓冲写字节不碰 FATFS。这条改完之后之前那些“偶发”“随机”的问题会一起消失。6. 二次开发把裸机读写改成带队列的采集存储模块裸机例程里“采一个数写一行”的写法放到真实设备上撑不住采集频率一高f_write的耗时会把采样周期拖垮。我一般的改法是加一层环形缓冲采集任务只负责入队另一个低优先级任务负责批量刷盘。/* 采集侧只写内存不碰文件系统 */ bool storage_push(const void *data, uint16_t len) { return ringbuf_write(g_rb, data, len) len; } /* 存储任务攒够 4KB 或超时 1s 就落一次盘 */ void storage_task(void *arg) { uint8_t buf[4096]; for (;;) { size_t n ringbuf_read(g_rb, buf, sizeof(buf), 1000); if (n 0) { UINT bw 0; f_write(logf, buf, n, bw); f_sync(logf); /* 批量刷比逐条刷吞吐高一个量级 */ } } }改造时有两点要盯住。一是环形缓冲的读写指针要用原子操作或关中断保护否则生产者和消费者会互相覆盖二是f_write的返回值和实际写入数每次都要判卡写满或出错时把数据转到备用文件或置错误标志别静默丢弃。验证方法很直接连续跑 24 小时每 10 分钟记一次文件大小和队列水位队列持续上涨说明刷盘速度跟不上采集速度要么加大批大小要么换 SDIO 接口。从那以后我每次移植 FATFS都强制先把ffconf.h和disk_ioctl过一遍再写业务代码因为那两处出的问题最像玄学查起来最费时间。希望帮到你。本文还有配套的精品资源点击获取