STM32进阶笔记——FATFS文件系统（下）

太陈抱不动2024-03-21 22:07

本专栏争取每周三更新直到更新完成，期待大家的订阅关注，欢迎互相学习交流。
  本文需要一些SD卡和内存管理等前置知识，后续文章会介绍，这里先介绍一下FATFS文件系统。关于FATFS的文章分为上下两篇，上篇主要介绍什么是FAT文件系统以及FATFS的移植，下篇主要介绍FATFS的一些API函数并给出一些简单的应用示例。

目录

  • 一、结构体介绍
    • [1.1 文件对象结构体](#1.1 文件对象结构体)
    • [1.2 目录对象结构体](#1.2 目录对象结构体)
    • [1.3 文件信息结构体](#1.3 文件信息结构体)
  • 二、文件操作函数
    • [2.1 f_open函数](#2.1 f_open函数)
    • [2.2 f_close函数](#2.2 f_close函数)
    • [2.3 f_read函数](#2.3 f_read函数)
    • [2.4 f_write函数](#2.4 f_write函数)
    • [2.5 f_size获取文件大小](#2.5 f_size获取文件大小)
  • 三、目录操作函数
    • [3.1 f_opendir函数](#3.1 f_opendir函数)
    • [3.2 f_closedir函数](#3.2 f_closedir函数)
    • [3.3 f_readdir函数](#3.3 f_readdir函数)
  • 四、文件/目录管理函数
    • [4.1 f_unlink函数](#4.1 f_unlink函数)
    • [4.2 f_rename函数](#4.2 f_rename函数)
    • [4.3 f_mkdir函数](#4.3 f_mkdir函数)
  • 五、示例程序
    • [5.1 文件操作函数使用示例](#5.1 文件操作函数使用示例)
    • [5.2 目录操作函数使用示例](#5.2 目录操作函数使用示例)

一、结构体介绍

在开始正式介绍FATFS的API函数之前，我们先来看几个关键的结构体，主要是简单了解一下其中的内容。

1.1 文件对象结构体

c 复制代码 
/* File object structure (FIL) */

typedef struct {
	FATFS*	fs;				/* Pointer to the related file system object (**do not change order**) */
	WORD	id;				/* Owner file system mount ID (**do not change order**) */
	BYTE	flag;			/* Status flags */
	BYTE	err;			/* Abort flag (error code) */
	DWORD	fptr;			/* File read/write pointer (Zeroed on file open) */
	DWORD	fsize;			/* File size */
	DWORD	sclust;			/* File start cluster (0:no cluster chain, always 0 when fsize is 0) */
	DWORD	clust;			/* Current cluster of fpter (not valid when fprt is 0) */
	DWORD	dsect;			/* Sector number appearing in buf[] (0:invalid) */
#if !_FS_READONLY
	DWORD	dir_sect;		/* Sector number containing the directory entry */
	BYTE*	dir_ptr;		/* Pointer to the directory entry in the win[] */
#endif
#if _USE_FASTSEEK
	DWORD*	cltbl;			/* Pointer to the cluster link map table (Nulled on file open) */
#endif
#if _FS_LOCK
	UINT	lockid;			/* File lock ID origin from 1 (index of file semaphore table Files[]) */
#endif
#if !_FS_TINY
	BYTE	buf[_MAX_SS];	/* File private data read/write window */
#endif
} FIL;

1.2 目录对象结构体

c 复制代码 
/* Directory object structure (DIR) */

typedef struct {
	FATFS*	fs;				/* Pointer to the owner file system object (**do not change order**) */
	WORD	id;				/* Owner file system mount ID (**do not change order**) */
	WORD	index;			/* Current read/write index number */
	DWORD	sclust;			/* Table start cluster (0:Root dir) */
	DWORD	clust;			/* Current cluster */
	DWORD	sect;			/* Current sector */
	BYTE*	dir;			/* Pointer to the current SFN entry in the win[] */
	BYTE*	fn;				/* Pointer to the SFN (in/out) {file[8],ext[3],status[1]} */
#if _FS_LOCK
	UINT	lockid;			/* File lock ID (index of file semaphore table Files[]) */
#endif
#if _USE_LFN
	WCHAR*	lfn;			/* Pointer to the LFN working buffer */
	WORD	lfn_idx;		/* Last matched LFN index number (0xFFFF:No LFN) */
#endif
#if _USE_FIND
	const TCHAR*	pat;	/* Pointer to the name matching pattern */
#endif
} DIR;

1.3 文件信息结构体

c 复制代码 
/* File information structure (FILINFO) */

typedef struct {
	DWORD	fsize;			/* File size */
	WORD	fdate;			/* Last modified date */
	WORD	ftime;			/* Last modified time */
	BYTE	fattrib;		/* Attribute */
	TCHAR	fname[13];		/* Short file name (8.3 format) */
#if _USE_LFN
	TCHAR*	lfname;			/* Pointer to the LFN buffer */
	UINT 	lfsize;			/* Size of LFN buffer in TCHAR */
#endif
} FILINFO;

二、文件操作函数

2.1 f_open函数

  • 函数功能：打开或者创建一个文件。
  • 函数原型：FRESULT f_open (FIL* fp, const TCHAR* path, BYTE mode);
  • 输入参数 ：*fp：指向一个空白文件对象的结构体指针；
    *path：文件名指针；
    mode：模式标志，共有以下几种模式：
模式 含义
FA_READ 指定对对象的读访问权限。可以从文件中读取数据。
FA_WRITE 指定对对象的写访问。数据可以写入文件。结合 FA _ READ 进行读写访问。
FA_OPEN_EXISTING 打开文件。如果文件不存在，函数将失败 (默认值)。
FA_OPEN_ALWAYS 如果文件存在，则打开该文件；如果没有，将创建一个新文件。
FA_CREATE_NEW 创建一个新文件。如果文件存在，函数将失败。
FA_CREATE_ALWAYS 创建一个新文件。如果该文件存在，它将被截断并覆盖。

当 _ FS _ READONLY = = 1时（只读模式），模式标志 FA _ WRITE、 FA _ CREATE _ ALWAYS、 FA _ CREATE _ NEW 和 FA _ OPEN _ ALWAYS 不可用。

  • 返回值：返回值是一个结构体，这里在每一个返回值后面给出了中文描述，仅供参考。
c 复制代码 
typedef enum {
	FR_OK = 0,				/* (0) 成功*/
	FR_DISK_ERR,			/* (1) 低级磁盘 I/O 层发生了一个硬错误 */
	FR_INT_ERR,				/* (2) 断言失败 */
	FR_NOT_READY,			/* (3) 物理驱动无法工作 */
	FR_NO_FILE,				/* (4) 无法找到文件 */
	FR_NO_PATH,				/* (5) 无法找到路径 */
	FR_INVALID_NAME,		/* (6) 路径名格式无效 */
	FR_DENIED,				/* (7) 由于禁止访问或目录已满而拒绝访问 */
	FR_EXIST,				/* (8) 由于禁止访问而拒绝访问 */
	FR_INVALID_OBJECT,		/* (9) 文件/目录对象无效 */
	FR_WRITE_PROTECTED,		/* (10) 物理驱动器受写保护 */
	FR_INVALID_DRIVE,		/* (11) 逻辑驱动器号无效 */
	FR_NOT_ENABLED,			/* (12) 卷没有工作区 */
	FR_NO_FILESYSTEM,		/* (13) 没有有效的FAT卷 */
	FR_MKFS_ABORTED,		/* (14) 由于任何参数错误，f _ mkfs ()中止 */
	FR_TIMEOUT,				/* (15) 无法获得在规定期限内访问卷的授权 */
	FR_LOCKED,				/* (16) 根据文件共享策略拒绝该操作 */
	FR_NOT_ENOUGH_CORE,		/* (17) 无法分配 LFN工作缓冲区 */
	FR_TOO_MANY_OPEN_FILES,	/* (18) 打开的文件数 > _ FS _ SHARE */
	FR_INVALID_PARAMETER	/* (19) 给定的参数无效 */
} FRESULT;
  • 注意事项：在使用任何文件函数之前，必须使用 f _ mount 函数将工作区(文件系统对象)注册到逻辑驱动器（f_mount 函数后续会介绍）。除 f _ fdisk 函数之外的所有 API 函数都可以在此过程之后工作。打开的文件必须在断电、删除媒体或重新挂载之前关闭，否则文件可能会被折叠。若要关闭打开的文件，请使用 f _ close 函数。禁止复制打开任何写模式标志的文件。。

2.2 f_close函数

  • 函数功能：关闭一个打开的文件。
  • 函数原型：FRESULT f_close (FIL* fp);
  • 输入参数：*fp：指向要关闭的打开文件对象结构的指针。
  • 返回值：包含在FRESULT结构体，不再详细介绍。
  • 注意事项：如果任何数据已经写入文件，文件的缓存信息将被写回卷。函数成功执行后，file 对象不再有效，可以将其丢弃。

2.3 f_read函数

  • 函数功能：从一个文件中读取数据。
  • 函数原型：FRESULT f_read (FIL* fp, void* buff, UINT btr, UINT* br);
  • 输入参数 ：*fp：指向打开文件对象的指针；
    *buff：指向存储读取数据的数组指针；
    btr：在 UINT 类型范围内要读取的字节数；
    *br：指向 UINT 变量的指针，以返回读取的字节数。无论结果如何，该值在函数调用后始终有效；
  • 返回值：包含在FRESULT结构体，不再详细介绍。
  • 注意事项：文件对象的文件读/写指针提高了读取的字节数。函数完成后，应该检查 * br 以检测文件的结尾。如果 * br 小于 btr，则表示在读操作期间读/写指针到达文件末尾。

2.4 f_write函数

  • 函数功能：往文件里写入数据。
  • 函数原型：FRESULT f_write (FIL* fp, const void* buff, UINT btw, UINT* bw);
  • 输入参数 ：*fp：指向打开文件对象的指针；
    *buff：指向要写入的数据的指针；
    btw：指定要在 UINT 类型范围内写入的字节数；
    *bw：指向 UINT 变量的指针，以返回写入的字节数；
  • 返回值：包含在FRESULT结构体，不再详细介绍。
  • 注意事项：函数完成后，应该检查 * bw 以检测磁盘是否已满。如果 * bw 小于 btw，则表示在写操作期间卷已满。该函数可以在卷满或接近满时执行。

经测试发现，写完成后必须关闭文件才能保存写的数据，如果写完成后不关闭文件直接读取，新写入的内容不会被读取出来。

2.5 f_size获取文件大小

f_size 函数获取文件的大小，返回文件的大小（以字节为单位）。它是作为宏实现的，只需要输入一个指向打开的文件对象结构的指针即可，使用比较简单，这里之所以单独介绍这个函数，是因为我们后续在使用SD卡读取文件时，很多时候需要先知道文件大小，然后开辟合适的空间来存储读取出来的文件内容。f_size函数的定义如下

c 复制代码 
#define f_size(fp) ((fp)->fsize)

三、目录操作函数

3.1 f_opendir函数

  • 函数功能：打开一个目录（文件夹）。
  • 函数原型：FRESULT f_opendir (DIR* dp, const TCHAR* path);
  • 输入参数 ：*dp：指向空白目录对象的指针，以创建新的目录对象；
    *path：指向指定要打开的目录名称的空终止字符串的指针；
  • 返回值：包含在FRESULT结构体，不再详细介绍。
  • 注意事项：当_FS_MINIMIZE <= 1时可用。

f_opendir函数是打开一个已存在的目录，并为后续的调用创建一个目录对象。该目录对象结构可以在任何时候不经任何步骤而被丢弃。

3.2 f_closedir函数

  • 函数功能：关闭一个打开的目录。
  • 函数原型：FRESULT f_closedir (DIR* dp);
  • 输入参数：指向要关闭的已打开目录对象结构的指针。
  • 返回值：包含在FRESULT结构体，不再详细介绍。

3.3 f_readdir函数

  • 函数功能：读取目录条目。
  • 函数原型：FRESULT f_readdir (DIR* dp, FILINFO* fno);
  • 输入参数 ：*dp：指向由 f _ opendir 函数创建的目录对象的指针；
    *fno：指向文件信息结构的指针，以存储有关已读项的信息；
  • 返回值：包含在FRESULT结构体，不再详细介绍。
  • 注意事项：f_readdir函数按顺序读取目录项、关于文件和目录的信息。通过重复调用 f _ readdir 函数，可以读取目录中的所有项。

当启用相对路径特性(_ FS _ RPATH >= 1)时，点条目不会被过滤掉，它们将出现在读取条目中。当所有目录项都已读取且没有要读取的项时，空字符串存储在 fno-> fname []中，不会出现任何错误。当指向 fno 的空指针被赋值时，目录对象的读索引将被重绕。
  启用 LFN 特性（长文件名）后，文件信息结构中的 fno-> lfname 和 fno-> lfsize 在使用之前必须使用有效值进行初始化。lfname 指向 LFN 读取缓冲区。lfsize 是以 TCHAR 为单位的 LFN 读缓冲区的大小。如果不需要 LFN，则将 lfname设置为一个空指针，则不返回 LFN。
  这里简单介绍几句相对路径 和绝对路径，至于更加详细的内容还需要大家自行搜索。其实很好理解，绝对路径是指文件在硬盘上真正存在的路径，绝对路径是唯一的，只有一个，而相对路径是相对于当前目录或者当前工作目录的路径，表示文件相对于当前位置的路径。我们常见的带盘符的路径都是绝对路径，比如C:\Users\de'l'l\Desktop\doc这种，而相对路径是相对一个目标对象而言的，它有自己的表示方式，"."表示当前所在目录，"..."代表上一层目录，"...\"代表上一层目录的上一层目录。

对于f_readdir函数，给出了示例程序，这里贴一下，后续会使用该函数来打印一下某个特定文件夹下的文件

c 复制代码 
FRESULT scan_files (
    char* path        /* Start node to be scanned (also used as work area) */
)
{
    FRESULT res;
    FILINFO fno;
    DIR dir;
    int i;
    char *fn;   /* This function assumes non-Unicode configuration */
#if _USE_LFN
    static char lfn[_MAX_LFN + 1];   /* Buffer to store the LFN */
    fno.lfname = lfn;
    fno.lfsize = sizeof lfn;
#endif


    res = f_opendir(&dir, path);                       /* Open the directory */
    if (res == FR_OK) {
        i = strlen(path);
        for (;;) {
            res = f_readdir(&dir, &fno);                   /* Read a directory item */
            if (res != FR_OK || fno.fname[0] == 0) break;  /* Break on error or end of dir */
            if (fno.fname[0] == '.') continue;             /* Ignore dot entry */
#if _USE_LFN
            fn = *fno.lfname ? fno.lfname : fno.fname;
#else
            fn = fno.fname;
#endif
            if (fno.fattrib & AM_DIR) {                    /* It is a directory */
                sprintf(&path[i], "/%s", fn);
                res = scan_files(path);
                path[i] = 0;
                if (res != FR_OK) break;
            } else {                                       /* It is a file. */
                printf("%s/%s\n", path, fn);
            }
        }
        f_closedir(&dir);
    }

    return res;
}

四、文件/目录管理函数

下面介绍的这几个文件/目录管理函数的使用都比较简单，下面就不再单独给出应用示例了。

4.1 f_unlink函数

  • 函数功能：删除一个文件或子目录。
  • 函数原型：FRESULT f_unlink (const TCHAR* path);
  • 输入参数：*path：文件/文件夹路径。
  • 返回值：包含在FRESULT结构体，不再详细介绍。
  • 注意事项 ：如果要删除的对象的条件适用于以下条件，则无法使用本函数删除
        文件/子目录不能有只读属性(AM _ RDO) ，否则函数将被 FR _ DENIED 拒绝。
        子目录必须为空并且不能被工作目录，否则函数将被拒绝。
        当启用文件锁定功能时，它将被安全地拒绝。

4.2 f_rename函数

  • 函数功能：重命名文件或子目录。
  • 函数原型：FRESULT f_rename (const TCHAR* path_old, const TCHAR* path_new);
  • 输入参数 ：*path_old：旧对象名称；
    *path_new：新对象名称；
  • 返回值：包含在FRESULT结构体，不再详细介绍。
  • 注意事项：要重命名的对象不能是打开的对象。当启用文件锁定功能时，可以安全地拒绝这种错误操作。

4.3 f_mkdir函数

  • 函数功能：创建一个新目录。
  • 函数原型：FRESULT f_mkdir (const TCHAR* path);
  • 输入参数：*path：目录名。
  • 返回值：包含在FRESULT结构体，不再详细介绍。

五、示例程序

5.1 文件操作函数使用示例

为了方便大家更好地理解FATFS的API函数的使用方法，我们这里通过一个小例子来演示一下，本例需要用到以下内容

  • 一张格式化过的空的SD卡；
  • 一个可以插SD卡的开发板或模块（这里使用的是STM32F103ZET6核心板）；
  • 一块LCD显示屏（屏幕主要是为了显示提示信息，可有可无，可以用串口来代替）

本例主要目的是在一张空的SD卡中创建并打开一个新的.txt文件，向文件中写入"ABCDEFGH"，然后读取文件内容并显示，最后读取一下文件大小。

这里贴一下核心代码，代码中有个别打开文件和关闭文件的操作没有进行返回值检测，不影响实际测试，这里特地说明一下。

c 复制代码 
  f_mount(fs[0],"0:",1); 					//挂载SD卡
	
	// 打开一个文件，如果文件不存在，则创建一个
	res = f_open(&fil, "ERTUElec.txt",FA_OPEN_ALWAYS	| FA_WRITE);
	// 判断是否创建成功
	if (!res)
	{
		LCD_ShowString(30,80,200,16,16,"File Creat Success!");
	}
	else
	{
		LCD_ShowString(30,80,200,16,16,"File Creat faild!  ");
	}
	
	// 写入数据
	res = f_write(&fil,&writeData[0],8,(UINT*)&bw);
	// 判断是否写入成功
	if (!res)
	{
		LCD_ShowString(30,100,200,16,16,"File Write Success!");
		f_close(&fil);
	}
	else
	{
		LCD_ShowString(30,100,200,16,16,"File Write faild!  ");
	}
	
	f_open(&fil, "ERTUElec.txt",FA_READ);
	// 读取文件
	res = f_read(&fil,&readData[0],8,(UINT*)&br);
	// 判断是否读取成功
	if (!res)
	{
		LCD_ShowString(30,120,200,16,16,"File Read Success!");
	}
	else
	{
		LCD_ShowString(30,120,200,16,16,"File Read faild!  ");
	}
	
	// 关闭打开的文件
	res = f_close(&fil);
	// 判断是否关闭成功
	if (!res)
	{
		LCD_ShowString(30,140,200,16,16,"File Close Success!");
	}
	else
	{
		LCD_ShowString(30,140,200,16,16,"File Close faild!  ");
	}
	
	// 显示读取内容
	sprintf ((char*)string,"Content is %s",readData);
	LCD_ShowString(30,160,200,16,16,string);
	
	// 获取文件大小（字节数）
	size = f_size(&fil);
	
	// 显示文件大小
	sprintf ((char*)string,"Size is %d",size);
	LCD_ShowString(30,180,200,16,16,string);

下面看一下LCD上显示的信息

5.2 目录操作函数使用示例

本示例比较简单，就是使用f_readdir函数来读取一个特定文件加下的全部文件名并通过串口打印。首先我们在SD卡中新建一个文件夹，文件夹内添加一些文件用来测试

然后我们利用介绍f_readdir函数时给出的示例函数将NEW文件夹内的全部文件名通过串口打印出来，示例函数在上面已经给出了，这里就不再重复介绍了，在使用时只需要输入文件夹路径即可

c 复制代码 
	scan_files("0:/NEW");

上电后观察串口输出内容

相关推荐
王俊山IT17 分钟前
C++学习笔记----10、模块、头文件及各种主题（二）---- 预处理指令
开发语言·c++·笔记·学习
慕卿扬26 分钟前
基于python的机器学习（二）—— 使用Scikit-learn库
笔记·python·学习·机器学习·scikit-learn
齐 飞2 小时前
MongoDB笔记02-MongoDB基本常用命令
前端·数据库·笔记·后端·mongodb
flying robot2 小时前
Go结构体(struct)
笔记
王俊山IT3 小时前
C++学习笔记----10、模块、头文件及各种主题（一）---- 模块（1）
开发语言·c++·笔记·学习
RationalDysaniaer3 小时前
Gin入门笔记
笔记·gin
xing25163 小时前
张氏宗谱序言白话文翻译
笔记
北京迅为4 小时前
【北京迅为】《STM32MP157开发板嵌入式开发指南》-第七十八章 Qt控制硬件
linux·stm32·单片机·嵌入式硬件
gma9994 小时前
【Effective C++】阅读笔记3
c++·笔记
安冬的码畜日常5 小时前
【The Art of Unit Testing 3_自学笔记06】3.4 + 3.5 单元测试核心技能之：函数式注入与模块化注入的解决方案简介
笔记·学习·单元测试·jest
热门推荐
01【HarmonyOS】HUAWEI DevEco Studio 下载地址汇总02(欧拉)openEuler系统添加网卡文件配置流程、(欧拉)openEuler系统手动配置ipv6地址流程、(欧拉)openEuler系统网络管理说明03组基轨迹建模 GBTM的介绍与实现（Stata 或 R）04全面解析：构建基于深度学习的安全帽检测系统（UI界面+YOLO代码+数据集）05红米手机使用google play06【经验分享】Ubuntu22.04安装微信(linux官方版)07【AIGC】重塑未来的科技巨轮08【Java】Ruoyi-Vue-Plus 整合 文件分片上传至 minio、阿里云、七牛云等OSS-【后端篇】09RAG 实践- Ollama+RagFlow 部署本地知识库10Ubuntu 20.04使用Livox mid 360 测试 FAST_LIO