一、概述
1、目的
在移植之前,先将源代码大概的阅读一遍,主要是了解文件系统的结构、各个函数的功能和接口、与移植相关的代码等等。
2、准备工作
在官方网站下载了0.07c版本的源代码,利用记事本进行阅读。
二、源代码的结构
1、源代码组成
源代码压缩包解压后,共两个文件夹,doc是说明,src里就是代码。src文件夹里共五个文件和一个文件夹。文件夹是option,还有00readme.txt、diskio.c、diskio.h、ff.c、ff.h、integer.h。对比网上的文章,版本已经不同了,已经没有所谓的tff.c和tff.h了,估计现在都采用条件编译解决这个问题了,当然文件更少,可能编译选项可能越复杂。
2、00readme.txt的说明
Low level disk I/O module is not included in this archive because the FatFs
module is only a generic file system layer and not depend on any specific
storage device. You have to provide a low level disk I/O module that written
to control your storage device.主要是说不包含底层IO代码,这是个通用文件系统可以在各种介质上使用。我们移植时针对具体存储设备提供底层代码。
接下来做了版权声明-可以自由使用和传播。
然后对版本的变迁做了说明。
3、源代码阅读次序
先读integer.h,了解所用的数据类型,然后是ff.h,了解文件系统所用的数据结构和各种函数声明,然后是diskio.h,了解与介质相关的数据结构和操作函数。再把ff.c和diskio.c两个文件所实现的函数大致扫描一遍。最后根据用户应用层程序调用函数的次序仔细阅读相关代码。
三、源代码阅读
1、integer.h头文件
这个文件主要是类型声明。以下是部分代码。
typedef intINT;
typedef unsigned int UINT;
typedef signed charCHAR;/* These types must be 8-bit integer */
都是用typedef做类型定义。移植时可以修改这部分代码,特别是某些定义与你所在工程的类型定义有冲突的时候。
2、ff.h头文件
以下是部分代码的分析
#include“integer.h”使用integer.h的类型定义
#ifndef _FATFS
#define _FATFS 0x007C版本号007c,0.07c
#define _WORD_ACCESS 0//如果定义为1,则可以使用word访问。
中间有一些看着说明很容易弄清楚意思。这里就不例举了。
#define _CODE_PAGE 936
/* The _CODE_PAGE specifies the OEM code page to be used on the target system.
/936–Simplified Chinese GBK (DBCS, OEM, Windows)跟据这个中国应该是936.
打开option文件夹看一下。打开cc936.c文件,里面有一个很大的数组static const WCHAR uni2oem[]。
根据英文说明,这个数组用于unicode码和OEM码之间的相互转换。
接下来又有两个函数ff_convert()和ff_wtoupper()具体执行码型转换和将字符转换为大写。
?
百度一下:看OEM码什么意思。
unicode是一种双字节字符编码,无论中文还是英文,或者其他语言统一到2个字节。与现有的任何编码(
ASCII,GB等)都不兼容。WindowsNT(2000)的内核即使用该编码,所有数据进入内核前转换成UNICODE,退
出内核后在转换成版本相关的编码(通常称为OEM,在简体中文版下即为GB).(百度所得)继续往下阅读。
#define _USE_LFN 1//这个估计是长文件名支持了,以前的0.06版本好像是不支持。
#define _MAX_LFN 255//最长支持255个双字节字符。
#define _FS_RPATH 0//是否文件相对路径选项。
/* When _FS_RPATH is set to 1, relative path feature is enabled and f_chdir,
/f_chdrive function are available.//有些函数会受影响。
/Note that output of the f_readdir fnction is affected by this option. */
#define _FS_REENTRANT 0//如果要支持文件系统可重入,必须加入几个函数。
#define _TIMEOUT1000/* Timeout period in unit of time ticks of the OS */
#define _SYNC_tHANDLE/* Type of sync object used on the OS. e.g. HANDLE, OS_EVENT*, ID and etc.. */
/* To make the FatFs module re-entrant, set _FS_REENTRANT to 1 and add user /provided synchronization handlers, ff_req_grant, ff_rel_grant, ff_del_syncobj /and ff_cre_syncobj function to the project. */
#elif _CODE_PAGE == 936 /* Simplified Chinese GBK */
#define _DF1S 0×81
#define _DF1E 0xFE
#define _DS1S 0×40
#define _DS1E 0x7E
#define _DS2S 0×80
#define _DS2E 0xFE
接下来很大一部分都是与语言相关的因素,略过。
/* Character code support macros */三个宏判断是否大写、小写、数字。
#define IsUpper(c) (((c)>=’A')&&((c)<=’Z'))
#define IsLower(c) (((c)>=’a')&&((c)<=’z'))
#define IsDigit(c) (((c)>=’0′)&&((c)<=’9′))
#if _DF1S/* DBCS configuration */双字节编码相关的设定,暂时不理会它。#if _MULTI_PARTITION/* Multiple partition configuration */
//该变量定义为1时,支持一个磁盘的多个分区。
typedef struct _PARTITION {
BYTE pd;/* Physical drive# */
BYTE pt;/* Partition # (0-3) */
} PARTITION;
ExternconstPARTITION Drives[];//如果支持分区,则声明变量Drivers #define LD2PD(drv) (Drives[drv].pd)/*获得磁盘对应的物理磁盘
#define LD2PT(drv) (Drives[drv].pt)/*获得磁盘对应的分区
#else/* Single partition configuration */
#define LD2PD(drv) (drv)/* Physical drive# is equal to the logical drive# */ #define LD2PT(drv) 0/* Always mounts the 1st partition */
#if _MAX_SS == 512//一般扇区长度取512字节。
#defineSS(fs)512U
#if _LFN_UNICODE && _USE_LFN
typedef WCHAR XCHAR;/* Unicode */ XCHAR是文件名的码型所用。
#else
typedef char XCHAR;/* SBCS, DBCS */
#endif
typedef struct _FATFS_ {
BYTEfs_type;/* FAT sub type */
BYTEdrive;/*对应实际驱动号01—*/
BYTEcsize;/*每个簇的扇区数目*/
先查一下簇的含义:应该是文件数据分配的基本单位。
BYTEn_fats;/*文件分配表的数目*/
FAT文件系统依次应该是:引导扇区、文件分配表两个、根目录区和数据区。
BYTEwflag;/* win[] dirty flag (1:must be written back) */
//文件是否改动的标志,为1时要回写。WORDid;/* File system mount ID文件系统加载ID*/
WORDn_rootdir;/*根目录区目录项的数目*/
#if _FS_REENTRANT
_SYNC_tsobj;/*允许重入,则定义同步对象*/
#endif
#if _MAX_SS != 512
WORDs_size;/* Sector size */
#endif
#if !_FS_READONLY//文件为可写
BYTEfsi_flag;/* fsinfo dirty flag (1:must be written back) */
//文件需要回写的标志
DWORDlast_clust;/* Last allocated cluster */
DWORDfree_clust;/* Number of free clusters */
DWORDfsi_sector;/* fsinfo sector */
#endif
#if _FS_RPATH
DWORDcdir;/*使用相对路径,则要存储文件系统当前目录
#endif
DWORDsects_fat;/*文件分配表占用的扇区
DWORDmax_clust;/*最大簇数
DWORDfatbase;/*文件分配表开始扇区
DWORDdirbase;/*如果是FAT32,根目录开始扇区需要首先得到。
DWORDdatabase;/*数据区开始扇区
DWORDwinsect;/* Current sector appearing in the win[] */
//目前的扇区在win[]里面,这个win[]数组暂时还不知道含义。
BYTEwin[_MAX_SS];/* Disk access window for Directory/FAT */
//这是一个win[512]数组,存储着一个扇区,好像作为扇区缓冲使用。
} FATFS;
typedef struct _DIR_ {
FATFS* fs;/* Pointer to the owner file system object */指向相应文件系统对象。
WORDid;/*文件系统加载ID*/
WORDindex;/* Current read/write index number */目前读写索引代码
DWORDsclust;/* Table start cluster (0:Static table) */文件数据区开始簇
DWORDclust;/* Current cluster */目前处理的簇
DWORDsect;/* 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 _USE_LFN
WCHAR*lfn;/* Pointer to the LFN working buffer */指向长文件名缓冲。
WORDlfn_idx;/* Last matched LFN index number (0xFFFF:No LFN) */
#endif
} DIR;
typedef struct _FIL_ {
FATFS* fs;/* Pointer to the owner file system object */
WORDid;/* Owner file system mount ID */
BYTEflag;/* File status flags */文件状态标志
BYTEcsect;/* Sector address in the cluster */扇区偏移
DWORDfptr;/* File R/W pointer */读写指针
DWORDfsize;/* File size */
DWORDorg_clust;/* File start cluster */文件开始簇
DWORDcurr_clust;/* Current cluster */当前簇
DWORDdsect;/* Current data sector */文件当前扇区
#if !_FS_READONLY
DWORDdir_sect; /* Sector containing the directory entry */该文件目录项对应所在的扇区BYTE*dir_ptr;/* Ponter to the directory entry in the window */
#endif
#if !_FS_TINY
BYTEbuf[_MAX_SS];/* File R/W buffer */文件读写缓冲
#endif
} FIL;
/* File status structure */
typedef struct _FILINFO_ {
DWORDfsize;/* File size */
WORDfdate;/* Last modified date */
WORDftime;/* Last modified time */
BYTEfattrib;/* Attribute */
char fname[13];/* Short file name (8.3 format) */
#if _USE_LFN
XCHAR*lfname;/* Pointer to the LFN buffer */
intlfsize;/* Size of LFN buffer [chrs] */
#endif
} FILINFO;这个结构主要描述文件的状态信息,包括文件名13个字符
(8+.+3+\0)、属性、修改时间等。
接下来是函数的定义,先大概浏览一遍。
FRESULT f_mount (BYTE, FATFS*);//加载文件系统,BYTE参数是ID,后一个是文件系统定义。
FRESULT f_open (FIL*, const XCHAR*, BYTE);//打开文件,第一个参数是文件信息结构,第二个参数是文件名,第三是文件打开模式
FRESULT f_read (FIL*, void*, UINT, UINT*);//文件读取函数,参数1为文件对象(文件打开函数中得到),参数2为文件读取缓冲区,参数3为读取的字节数,参数4意义不清晰,等读到源代码就清楚了。
FRESULT f_write (FIL*, const void*, UINT, UINT*);//写文件,参数跟读差不多
FRESULT f_lseek (FIL*, DWORD); //移动文件的读写指针,参数2应该是移动的数目。
FRESULT f_close (FIL*);/* Close an open file object */
FRESULT f_opendir (DIR*, const XCHAR*);打开目录,返回目录对象
FRESULT f_readdir (DIR*, FILINFO*);读取目录,获得文件信息
FRESULT f_stat (const XCHAR*, FILINFO*);/* Get file status */
FRESULT f_getfree (const XCHAR*, DWORD*, FATFS**);/* Get number of free clusters on thedrive */
FRESULT f_truncate (FIL*);/* Truncate file */
FRESULT f_sync (FIL*);/* Flush cached data of a writing file */将缓冲区数据写回文件
FRESULT f_unlink (const XCHAR*);删除目录中的一个文件
FRESULTf_mkdir (const XCHAR*);/* Create a new directory */
FRESULT f_chmod (const XCHAR*, BYTE, BYTE); /* Change attriburte of the
file/dir */
FRESULT f_utime (const XCHAR*, const FILINFO*);/* Change timestamp of the file/dir */FRESULT f_rename (const XCHAR*, const XCHAR*);/* Rename/Move a file or directory */FRESULT f_forward (FIL*, UINT(*)(const BYTE*,UINT), UINT, UINT*); /* Forward data to the stream*/这个函数还要提供一个回调函数。
FRESULT f_mkfs (BYTE, BYTE, WORD);/* Create a file system on the drive */
FRESULT f_chdir (const XCHAR*);/* Change current directory */改变当前目录
FRESULT f_chdrive (BYTE);/* Change current drive */
应该说基本能明白这些函数用于干什么。
#if _USE_STRFUNC
int f_putc (int, FIL*);/* Put a character to the file */
int f_puts (const char*, FIL*);/* Put a string to the file */
int f_printf (FIL*, const char*,…);/* Put a formatted string to the file */char* f_gets (char*, int, FIL*);/* Get a string from the file */
#define f_eof(fp) (((fp)->fptr == (fp)->fsize) ? 1 : 0)
#define f_error(fp) (((fp)->flag & FA__ERROR) ? 1 : 0)
#if _FS_REENTRANT//如果定义了重入,则需要实现以下四个函数
BOOL ff_cre_syncobj(BYTE, _SYNC_t*);创建同步对象
BOOL ff_del_syncobj(_SYNC_t);删除同步对象
BOOL ff_req_grant(_SYNC_t);申请同步对象
void ff_rel_grant(_SYNC_t);释放同步对象。
#endif
3、diskio.h文件
typedef BYTEDSTATUS;
typedefDRESULT;//首先定义了两个变量,各个函数都有用到。
BOOL assign_drives (int argc, char *argv[]); //这个函数不知道干吗
DSTATUS disk_initialize (BYTE); //磁盘初始化
DSTATUS disk_status (BYTE); //获取磁盘状态
DRESULT disk_read (BYTE, BYTE*, DWORD, BYTE);
#if_READONLY == 0
DRESULT disk_write (BYTE, const BYTE*, DWORD, BYTE);
#endif
DRESULT disk_ioctl (BYTE, BYTE, void*); //磁盘控制
接下来还有一些常数的定义,具体用到时在看。
4、diskio.c的结构
DSTATUS disk_initialize (BYTE drv/* Physical drive nmuber (0..) */) {
DSTATUS stat;
int result;
switch (drv) {
case ATA :
result = ATA_disk_initialize();
// translate the reslut code here
return stat;
case MMC :
result = MMC_disk_initialize();
// translate the reslut code here
return stat;
case USB :
result = USB_disk_initialize();
// translate the reslut code here
return stat;
}
return STA_NOINIT;
}
函数基本都像这样,drv表示磁盘的类型。没有实现,用户必须实现这部分代码。5、ff.c文件简单浏览
#include“ff.h”/* FatFs configurations and declara tions */
#include“diskio.h”/* Declarations of low level disk I/O functions */
#defineENTER_FF(fs){ if (!lock_fs(fs)) return FR_TIMEOUT; } //获取文件系统同步对象,不成功返回超时,成功,继续执行。
#defineLEAVE_FF(fs, res){ unlock_fs(fs, res); return res; } //释放文件系统同步对象。
StaticFATFS *FatFs[_DRIVES]; //定义一个文件系统对象指针数组,当然一般我们也就用到一个元素。
Static WORD LfnBuf[_MAX_LFN + 1];//这个是与长文件名支持相关的。
#defineNAMEBUF(sp,lp)BYTE sp[12]; WCHAR *lp = LfnBuf
#define INITBUF(dj,sp,lp) dj.fn = sp; dj.lfn = lp
下面都是函数的定义,很多只在内部使用。
Staticvoid mem_cpy (void* dst, const void* src, int cnt) {
char *d = (char*)dst;
const char *s = (const char *)src;
while (cnt–) *d++ = *s++;
} //接下来还定义了几个内存操作的函数,这个函数实现了从一块内存到另一块的复制,下面还有mem_set()对一块内存进行清0或设置操作;
mem_cmp()比较内存的多个字节是否相同,相同返回0;chk_chr()检测字符串中是否存在某个字符,存在则返回该字符。
FRESULT move_window (
FATFS *fs,/* File system object */
DWORD sector/* Sector number to make apperance in the fs->win[] */
)//简单阅读了一下源代码,应该是改变文件系统的当前工作扇区,如果想要操作的扇区就是当前扇区,什么事不做;如果不是,则将原扇区写回;如果是FAT表,还得写入备份区。
这个函数内部使用,外部无法引用。
FRESULT sync (/* FR_OK: successful, FR_DISK_ERR: failed */
FATFS *fs/* File system object */
)//这个函数用于更新FAT32文件系统的FSI_Sector。什么含义还不太清楚。
DWORD get_fat (/* 0xFFFFFFFF:Disk error, 1:Interal error, Else:Cluster status */ FATFS *fs,/* File system object */
DWORD clst/* Cluster# to get the link information */
)
if (move_window(fs, fsect + (clst / (SS(fs) / 4)))) break;获取簇号码对应的FAT 扇区return LD_DWORD(&fs->win[((WORD)clst * 4) & (SS(fs) - 1)]) & 0x0FFFFFFF; //这个函数应该是获取簇的下一个连接簇。
综合起来,这个函数应该是获取下一簇,感觉这个函数名起得不太好。get_nextcluster感觉更好一点。
FRESULT put_fat (
FATFS *fs,/* File system object */
DWORD clst,/* Cluster# to be changed in range of 2 to fs->max_clust–1
*/DWORD val /* New value to mark the cluster */
)//上个函数是获取连接簇,这个是写入新的连接信息。
FRESULT remove_chain (
FATFS *fs,/* File system object */
DWORD clst/* Cluster# to remove a chain from */
)//将下一簇号写为0,也就是该文件的簇到此为止,同时系统的自由簇增加1.
DWORD create_chain (/* 0:No free cluster, 1:Internal error, 0xFFFFFFFF:Disk error, >=2:Newcluster# */
FATFS *fs,/* File system object */
DWORD clst/* Cluster# to stretch. 0 means create a new chain. */
)//跟上一个相反,在该簇的位置写入新的下一簇簇号。
DWORD clust2sect (/* !=0: Sector number, 0: Failed–invalid cluster# */
FATFS *fs,/* File system object */
DWORD clst/* Cluster# to be converted */
) //这个函数是将簇号转变为对应的扇区号。
clst * fs->csize + fs->database; //这个是算法
FRESULT dir_seek (
DIR *dj,/* Pointer to directory object */
WORD idx/* Directory index number */
)//这个函数的最终目的是根据索引号找到目录项所在簇、所在扇区、并是目录对象的对象指针指向文件系统对象窗口扇区的对应位置。FRESULT dir_next (/* FR_OK:Succeeded, FR_NO_FILE:End of table, FR_DENIED:EOT and couldnot streach */
DIR *dj,/* Pointer to directory object */
BOOL streach/* FALSE: Do not streach table, TRUE: Streach table if needed /) //移动当前目录项,根据索引,源代码简单看了一下,作用还不是很清晰,先放过。
接下来有5个函数与长文件名有关,这里先跳过。
FRESULT dir_find (
DIR *dj/* Pointer to the directory object linked to the file name */
)//
FRESULT dir_read (
DIR *dj/* Pointer to the directory object that pointing the entry to be read */)
FRESULT dir_register (/* FR_OK:Successful, FR_DENIED:No free entry or too many SFNcollision, FR_DISK_ERR:Disk error */
DIR *dj/* Target directory with object name to be created */
)
FRESULT dir_remove (/* FR_OK: Successful, FR_DISK_ERR: A disk error */
DIR *dj/* Directory object pointing the entry to be removed */
)
//以上这些函数都是对目录项的操作函数。
FRESULT create_name (
DIR *dj,/* Pointer to the directory object */
const XCHAR **path/* Pointer to pointer to the segment in the path string */)//这个函数太长了,具体用到的时候再说吧。
void get_fileinfo (/* No return code */
DIR *dj,/* Pointer to the directory object */
FILINFO *fno/* Pointer to store the file information */)
该函数用于获取文件状态信息。主要是从文件的目录项中获取信息。
FRESULT follow_path (/* FR_OK(0): successful, !=0: error code */
DIR *dj,/* Directory object to return last directory and found object */
const XCHAR *path/* Full-path string to find a file or directory */
)
该函数给定一个全路径,得到相应的目录对象。
BYTE check_fs (/* 0:The FAT boot record, 1:Valid boot record but not an FAT, 2:Not a bootrecord, 3:Error */
FATFS *fs,/* File system object */
DWORD sect/* Sector# (lba) to check if it is an FAT boot record or not */)
该函数用于读取BOOT扇区,检查是否FAT文件系统。
FRESULT auto_mount (/* FR_OK(0): successful, !=0: any error occured */
const XCHAR **path,/* Pointer to pointer to the path name (drive number)
*/FATFS **rfs,/* Pointer to pointer to the found file system object */
BYTE chk_wp/* !=0: Check media write protection for write access */)这个函数的功能不太明白。
FRESULT validate (/* FR_OK(0): The object is valid, !=0: Invalid */
FATFS *fs,/* Pointer to the file system object */
WORD id/* Member id of the target object to be checked */
)//检查是否合法的文件系统。
FRESULT f_mount (
BYTE vol,/* Logical drive number to be mounted/unmounted */
FATFS *fs/* Pointer to new file system object (NULL for unmount)*/)
这是一个很重要的函数,装载文件系统。也是从这个函数开始,对外输出供用户调用。
if (vol >= _DRIVES)现在只支持卷号0.
FatFs[vol] = fs;将参数文件系统对象指针赋给全局文件对象指针。
后面的函数主要是对文件和目录进行操作,这里就不一一例举了。