znFAT移植与使用手册.doc

znFAT移植与使用手册（1）znFAT简介znFAT是一种高效、完备、精简且具有高可移植性的嵌入式FAT32文件系统解决方案。其主要特性如下：1）可通用于多种嵌入式CPU，如51、AVR、PIC、ARM、Cortex、DSP、MSP430、 freescale S12等等。2）所占用的RAM与ROM资源极少，并可由使用者视目标平台资源情况进行灵活 配置，最简配置情况下，RAM的使用量约在800900字节左右。3）内建独特的数据写入加速算法以及扇区级的基于“预建文件”的数据写入机制。 4）底层提供简单的单扇区读写驱动接口以及可选的硬件级多扇区连续读写驱动接 口。（在提供多扇区连续读写驱动的情况下，数据读写速度将有近24倍的提升， 甚至更高。）5）提供清晰而强大的对函数模块裁剪的功能，极大限度的减小最终生成的可执行文 件的体积。6）提供数据读取的重定向功能，使读到的数据无需缓冲暂存，直接流向应用目的。7）支持长文件名，长文件名最大长度可配置。默认配备并使用GB2312中文字符， 并可选择是否使用OEM字符集，以减少程序体积。8）支持与Windows、Linux等操作系统兼容的路径表示，路径分隔可使用/或。支持 无限深目录，支持长名目录。9）提供数据写入的实时模式，写入的任何数据，只怕只有一个字节，立即落实到物 理存储器，防止因恶劣工作环境、干扰或其它原因引起的目标平台不可预见的死 机或故障，造成数据丢失（实时模式数据写入速度不高，内存中不缓冲任何数据）。10）支持对存储设备的格式化，文件系统为FAT32。11）支持*与?通配，长名亦支持通配。12）支持文件与目录的删除，目录支持内含子目录与无限深级子目录结构的删除。13）支持无限级目录创建。14）支持多文件同时操作。15）支持多设备，即同时挂载多种存储设备，可在多种存储设备间任意切换。（2）znFAT的移植1）znFAT的代码结构 主体：znFAT的具体实现。znFAT.h是对相关数据结构、宏的定义，以及对使用者可调用的功能函数的声明。znFAT.c是对功能函数的具体实现。移植相关：znFAT的移植相关文件。mytype.h中对类型进行重定义。deviceio.c对存储设备物理扇区读写驱动进行具体实现。config.h 对znFAT进行一些配置。其它头文件：cc_macro.h 是znFAT中的功能函数依赖关系的定义。gb2uni.h 是znFAT中GB2312向UNICODE转换的映射表。deviceio.h 此文件向znFAT提供扇区读写驱动接口函数的声明。template.h znFAT中用于实现格式化功能的模板数据。2）znFAT的移植方法znFAT的移植其实非常简单，前提是已经有了现成的，较为成熟稳定的存储设备扇区读写等驱动函数。a. 重新定义数据类型，如下图。根据硬件平台实际的数据类型对mytype.h中的类型进行重新定义，包括 无符号整型、有符号整形与固化数据的ROM类型。b. 通过deviceio.c将存储设备驱动函数与znFAT标准物理接口进行接驳，包括 存储设备初始化、单扇区读取、单扇区写入、多扇区连续读取与写入，多扇区连续清0 I. 加入存储设备驱动头文件，如下图。（device0.h只是举个例子）。 II. 将存储设备初始化函数与znFAT_Device_Init函数接驳，如下图。除了将实际存储设备的初始化函数加入接口函数znFAT_Device_Init中，此函数中其它代码请不要改动（以下同理）。并且最好按函数中的格式来写，在有多个存储设备的情况下，可以方便地知道每一个存储设备的初始化成功与否。III. 将扇区读取驱动函数与znFAT_Device_Read_Sector函数进行接驳，如下图。IV. 将扇区写入驱动函数与znFAT_Device_Write_Sector函数进行接驳，如下图。V. 将多扇区连续读取驱动函数与znFAT_Device_Read_nSector函数进行接驳，如下 图。znFAT中的多扇区连续读取驱动接口函数采用了两种实现方式，使用者可以通过修改config.h中的相应宏选择使用哪种实现方式。config.h中的宏如下图：如果这个宏被注释，则采用单扇区读取驱动+循环的实现方式；否则，将采用硬件级的多扇区连续读取驱动，此地，使用者必须提供存储设备的多扇区连续读取驱动函数。VI. 将多扇区连续写入驱动函数与znFAT_Device_Write_nSector函数进行接驳（与V同理，config.h中对应的宏为 #define USE_MULTISEC_W）VII.将多扇区连续清零驱动函数与znFAT_Device_Clear_nSector函数进行接驳（与V与VI同理，config.h中对应的宏为 #define USE_MULTISEC_CLEAR） 以上就是znFAT的移植方法。（3）znFAT的使用方法znFAT为使用者提供了强大而完备的应用层函数。下面对znFAT的使用方法进行详细介绍。1） 存储设备初始化函数 UINT8 znFAT_Device_Init(void)对znFAT中挂接的所有存储设备进行初始化，如果有任何一个存储设备初始化失败，则返回值不为0。返回值为8位整型，某一位为1，表示对应的存储设备初始化失败。比如0X02，表示设备1初始化失败。（前提是移植的时候，遵循函数的格式。）2） 选择某一存储设备 UINT8 znFAT_Select_Device(UINT8 devno, struct znFAT_Init_Args *pinitargs)znFAT是支持多设备的，即允许多种存储设备同时挂接在znFAT上，但某一时刻只能有一个存储设备被操作。因此，要对存储设备进行选择。与存储设备相关的有两个重要的全局变量Dev_No与pInit_Args，即设备号与指向记录存储设备文件系统相关参数信息的结构体的指针。设备号用于控制扇区读写接口函数中的分支，从而决定了使用哪个驱动函数；后者所指向的结构体中的参数将参与此存储设备上的文件操作过程中的相关计算。因此，在对某一存储设备进行操作之前，务必正确设置这两个变量。3）格式化 UINT8 znFAT_Make_FS(UINT32 tt_sec,UINT16 clu_sz)此函数将存储设备格式化为FAT32文件系统。此函数可能会运行较长时间，而且视存储设备容量不同时间长短亦会不同。参数tt_sec为存储设备的总扇区数，clu_sz为簇大小。其中，如果clu_sz为0，则说明由znFAT自动按照存储设备的容量选择比较合适的簇大小。要实现格式化功能，使用者必须给出ROM固化数据的读取函数的实现。包括三个函数：从ROM中读取一个字节：UINT8 PGM_BYTE_FUN(ROM_TYPE_UINT8 *ptr)从ROM中读取一个字： UINT16 PGM_WORD_FUN(ROM_TYPE_UINT16 *ptr)从ROM中读取一个双字：UINT32 PGM_DWORD_FUN(ROM_TYPE_UINT32 *ptr)不同的CPU上，这些函数的实现可能不一样，比如在51和ARM上实现如下：UINT8 PGM_BYTE_FUN(ROM_TYPE_UINT8 *ptr) return *(ptr); UINT16 PGM_WORD_FUN(ROM_TYPE_UINT16 *ptr) return *(ptr);UINT32 PGM_DWORD_FUN(ROM_TYPE_UINT32 *ptr) return *(ptr);在AVR上为（WINAVR GCC平台）：UINT8 PGM_BYTE_FUN(ROM_TYPE_UINT8 *ptr) return pgm_read_byte(ptr); UINT16 PGM_WORD_FUN(ROM_TYPE_UINT16 *ptr) return pgm_read_word(ptr);UINT32 PGM_DWORD_FUN(ROM_TYPE_UINT32 *ptr) return pgm_read_dword(ptr);至于其它CPU平台的具体实现，要依实际平台而定。注：在格式化前，必须设定要格式化的存储设备的设备号，实际应用代码如下：extern UINT32 Dev_No;int main(void) Dev_No=0; /设定当前存储设备为设备0 znFAT_Select_Device(0,&Init_Args); /选择设备 znFAT_Init(); /文件系统初始化 znFAT_Make_FS(10000000,0); /格式化，总扇区数为10000000，由znFAT /自动选择簇大小 return 0;4）对存储设备的文件系统的初始化UINT8 znFAT_Init(void) 此函数将对选定的存储设备上的文件系统进行初始化。其实质是将文件系统的一些重要参数装入到当前所选定的文件系统参数集合结构体中去，以备后面使用。此函数如果返回0，说明 成功；否则失败，返回错误码：1：失败 2：非FAT32文件系统。如下程序说明znFAT中文件系统初始化的一般过程：struct znFAT_Init_Args Init_Args; /初始化参数集合int main(void) znFAT_Select_Device(0,&Init_Args); /选择设备 znFAT_Init(); /文件系统初始化 printf(znFAT init OKn); /输出文件系统相关参数 printf(BPB_Sector_No:%dn,Init_Args.BPB_Sector_No); printf(Total_SizeKB:%dn,Init_Args.Total_SizeKB); printf(BytesPerSector:%dn,Init_Args.BytesPerSector); printf(FATsectors:%dn,Init_Args.FATsectors); printf(SectorsPerClust:%dn,Init_Args.SectorsPerClust); printf(FirstFATSector:%dn,Init_Args.FirstFATSector); printf(FirstDirSector:%dn,Init_Args.FirstDirSector); printf(FSsec:%dn,Init_Args.FSINFO_Sec); printf(Next_Free_Cluster:%dn,Init_Args.Next_Free_Cluster); printf(FreenCluster:%dn,Init_Args.Free_nCluster); znFAT_Flush(); return 0; 4）文件或目录的打开 UINT8 znFAT_Open_File(struct FileInfo *pFI, INT8 *filepath,UINT32 n,UINT8 is_file)此函数用于打开文件或目录。pFI是指向文件信息体的指针；filepath是文件或目录的路径；n是目标文件或目录的索引值；is_file用于指示要打开的是目录还是文件，1表示要打开文件，0为目录。文件或目录被成功打开之后，其相关信息即被存入pFI所指向的文件信息体，以备后面使用。文件或目录的名字支持通配名，比如/abc/xyz/a*b.txt 表示/abc/xyz/目录下的所有主文件名以a开头，以b结束，扩展名为txt的文件 ； /a/b/t?st.txt 表示 /a/b/目录下所有以t开头，第二个字符为任意字符，后面为st.txt的文件。在通配情况下，与通配名匹配的文件或目录可能会有多个，参数n用于选择这些文件或目录中的第n个。此函数的应用实例如下：1） 打开一个文件struct znFAT_Init_Args Init_Args; /初始化参数集合struct FileInfo fileinfo; /文件信息集合int main(void) znFAT_Device_Init(); /存储设备初始化 znFAT_Select_Device(0,&Init_Args); /选择设备 znFAT_Init(); /文件系统初始化 if(!znFAT_Open_File(&fileinfo,/abc/xyz/test.txt,0,1) printf(suc. to open file.n); printf(=n); printf(File_Name:%sn,fileinfo.File_Name); /文件名 printf(File_Size:%d(bytes)n,fileinfo.File_Size); /文件大小 printf(File_StartClust:%dn,fileinfo.File_StartClust); /文件开始簇 printf(File_CurClust:%dn,fileinfo.File_CurClust); /文件当前簇 printf(File_CurSec:%dn,fileinfo.File_CurSec); /文件当前扇区 printf(File_CurPos:%dn,fileinfo.File_CurPos); /文件当前扇区内偏移 printf(File_CurOffset:%dn,fileinfo.File_CurOffset); /文件当前偏移量 printf(=n); znFAT_Close_File(&fileinfo); else printf(fail to open file.n); znFAT_Flush(); return 0;2） 通过文件通配功能列举出目录下所有匹配的文件 struct znFAT_Init_Args Init_Args; /初始化参数集合struct FileInfo fileinfo; /文件信息集合int main(void) unisigned char n=0; znFAT_Device_Init(); /存储设备初始化 znFAT_Select_Device(0,&Init_Args); /选择设备 znFAT_Init(); /文件系统初始化 while(!znFAT_Open_File(&fileinfo,/abc/xyz/*.txt,n,1) printf(%d:File_Name:%sn,n,fileinfo.File_Name); /文件名 n+; znFAT_Close_File(&fileinfo); znFAT_Flush(); return 0; 5）读取文件数据 UINT32 znFAT_ReadData(struct FileInfo *pFI, UINT32 offset,UINT32 len,UINT8 *app_Buffer)此函数用于对文件数据进行读取。pFI用于指向文件信息体，以从中获取文件的相关参数；offset为读取数据的起始位置；len为要读的数据长度；app_Buffer为指向应用数据缓冲区的指针。返回值为实际读到的数据长度。如果要读取的数据长度len大于文件当前剩余的有效数据长度。比如，从偏移量为40的位置开始读取100字节的数据，但是此文件大小只有60字节，则len的值自动修正为20，实际读到的数据长度也为20。应用实例如下：struct znFAT_Init_Args Init_Args; /初始化参数集合struct FileInfo fileinfo; /文件信息集合UINT8 buffer20;int main(void) znFAT_Device_Init(); /存储设备初始化 znFAT_Select_Device(0,&Init_Args); /选择设备 znFAT_Init(); /文件系统初始化 if(!znFAT_Open_File(&fileinfo,/test.txt,0,1) printf(suc. to open file.n); printf(=n); printf(File_Name:%sn,fileinfo.File_Name); printf(File_Size:%d(bytes)n,fileinfo.File_Size); printf(File_StartClust:%dn,fileinfo.File_StartClust); printf(File_CurClust:%dn,fileinfo.File_CurClust); printf(File_CurSec:%dn,fileinfo.File_CurSec); printf(File_CurPos:%dn,fileinfo.File_CurPos); printf(File_CurOffset:%dn,fileinfo.File_CurOffset); printf(=n); len=znFAT_ReadData(&fileinfo,2,10,app_buffer); /从2位置读10个字节 if(len) /如果实际读到的数据不为0，则认为成功 printf(suc. to read %d bytes.n,len); app_bufferlen=0; printf(data read is %s. n,app_buffer); else printf(no data is read.n); znFAT_Close_File(&fileinfo); else printf(fail to open file.n); znFAT_Flush(); return 0; 5）文件数据读取 （加数据重定向） UINT32 znFAT_ReadDataX(struct FileInfo *pfi, UINT32 offset,UINT32 len);此函数功能与4）基本相同，只不过它带有数据重定向功能，即数据不再放入缓冲中，而是可以直接通过函数进行处理。处理函数由使用者自行定义与实现，通过config.h中的宏引入到函数之中。#define Data_Redirect UART_Send_Byte /数据重定向函数名定义 这个宏定义将处理函数定义为UART_Send_Byte，即通过串口发送一个字节的函数。这样，函数在读到每一个字节时，都会通过串口将它直接发出。这样可以无需使用数据缓冲区，从而减少内存的使用量。 6）文件数据写入 UINT32 znFAT_WriteData(struct FileInfo *pfi,UINT32 len, UINT8 *pbuf)此函数用于将数据写入到文件之中。pfi是指向文件信息体的指针；len要写入的数据长度；pbuf是指向应用数据缓冲区的指针。返回值为实际写入的数据量。应用实例如下：struct znFAT_Init_Args Init_Args; /初始化参数集合struct FileInfo fileinfo; /文件信息集合UINT8 buf20=0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19;int main(void) znFAT_Device_Init(); /存储设备初始化 znFAT_Select_Device(0,&Init_Args); /选择设备 znFAT_Init(); /文件系统初始化 if(!znFAT_Open_File(&fileinfo,/znmcu.txt,0,1) /打开文件 printf(suc. to open file.n); printf(=n); printf(File_Name:%sn,fileinfo.File_Name); printf(File_Size:%d(bytes)n,fileinfo.File_Size); printf(File_StartClust:%dn,fileinfo.File_StartClust); printf(File_CurClust:%dn,fileinfo.File_CurClust); printf(File_CurSec:%dn,fileinfo.File_CurSec); printf(File_CurPos:%dn,fileinfo.File_CurPos); printf(File_CurOffset:%dn,fileinfo.File_CurOffset); printf(=n); len=znFAT_WriteData(&fileinfo,20,buf); /写入数据 if(len) /如果写入成功 printf(suc. to write %d(bytes).n,len); printf(=n); printf(File_StartClust:%dn,fileinfo.File_StartClust); printf(File_CurClust:%dn,fileinfo.File_CurClust); printf(File_CurSec:%dn,fileinfo.File_CurSec); printf(File_CurPos:%dn,fileinfo.File_CurPos); printf(File_CurOffset:%dn,fileinfo.File_CurOffset); printf(=n); else printf(fail to write data.n); znFAT_Close_File(&fileinfo); else printf(fail to open file.n); znFAT_Flush(); return 0; 7）文件创建 UINT8 znFAT_Create_File(struct FileInfo *pfi,INT8 *pfn, struct DateTime *pdt)此函数用于实现文件的创建。pfi是指向文件信息体的指针，文件创建成功之后，文件的相关信息将被装入到文件信息体中；pfn是文件的路径；pdt是指向时间日期结构体的指针，这个时间信息用于设定文件的创建时间。应用实例如下：struct znFAT_Init_Args Init_Args; /初始化参数集合struct FileInfo fileinfo; /文件信息集合struct DateTime dt; /日期时间结构体变量UINT8 buf20;int main(void) znFAT_Device_Init(); /存储设备初始化 znFAT_Select_Device(0,&Init_Args); /选择设备 znFAT_Init(); /文件系统初始化 dt.date.year=2012; dt.date.month=12; dt.date.day=21; dt.time.hour=15; dt.time.min=14; dt.time.sec=35; if(!znFAT_Create_File(&fileinfo,/znmcu.txt,&dt) printf(suc. to create file.n); printf(=n); printf(File_Name:%sn,fileinfo.File_Name); printf(File_Size:%d(bytes)n,fileinfo.File_Size); printf(File_StartClust:%dn,fileinfo.File_StartClust); printf(File_CurClust:%dn,fileinfo.File_CurClust); printf(File_CurSec:%dn,fileinfo.File_CurSec); printf(File_CurPos:%dn,fileinfo.File_CurPos); printf(File_CurOffset:%dn,fileinfo.File_CurOffset); printf(=n); znFAT_Close_File(&fileinfo); else printf(fail to create file.n); znFAT_Flush(); return 0; 8）目录创建 UINT8 znFAT_Create_Dir(INT8 *pdp,struct DateTime *pdt)此函数用于目录的创建。pdp为目录的路径，如/abc/xyz/ ，注意此路径必须以/或结束；pdt是指向时间日期结构体的指针，作为目录的创建时间。应用实例如下：struct znFAT_Init_Args Init_Args; /初始化参数集合struct DateTime dt; /日期时间结构体变量UINT8 buf20;int main(void) znFAT_Device_Init(); /存储设备初始化 znFAT_Select_Device(0,&Init_Args); /选择设备 znFAT_Init(); /文件系统初始化 dt.date.year=2012; dt.date.month=12; dt.date.day=21; dt.time.hour=15; dt.time.min=14; dt.time.sec=35; if(!znFAT_Create_Dir(/dir1/dir2/dir3/,&dt) printf(suc. to create dir.n); else printf(fail to create dir.n); znFAT_Flush(); return 0; 8）文件数据截断 UINT8 znFAT_Dump_Data(struct FileInfo *pfi,UINT32 offset)此函数用于实现文件数据的截断。pfi是指向文件信息体的指针；offset是数据偏移量，此函数将对此偏移量后面的数据进行删除。注意：进行对数据进行截断，实质上就是数据的删除时，最好确保没有文件处于打开状态（处于非实时簇链更新工作模式下时，关于znFAT的工作模式，在后面会详细介绍）。应用实例：struct znFAT_Init_Args Init_Args; /初始化参数集合struct FileInfo fileinfo; /文件信息集合int main(void) znFAT_Device_Init(); /存储设备初始化 znFAT_Select_Device(0,&Init_Args); /选择设备 znFAT_Init(); /文件系统初始化 if(!znFAT_Open_File(&fileinfo,/abc/xyz/test.txt,0,1) printf(suc. to open file.n); printf(=n); printf(File_Name:%sn,fileinfo.File_Name); /文件名 printf(File_Size:%d(bytes)n,fileinfo.File_Size); /文件大小 printf(File_StartClust:%dn,fileinfo.File_StartClust); /文件开始簇 printf(File_CurClust:%dn,fileinfo.File_CurClust); /文件当前簇 printf(File_CurSec:%dn,fileinfo.File_CurSec); /文件当前扇区 printf(File_CurPos:%dn,fileinfo.File_CurPos); /文件当前扇区内偏移 printf(File_CurOffset:%dn,fileinfo.File_CurOffset); /文件当前偏移量 printf(=n); if(!znFAT_Dump_Data(&fileinfo,10) /文件数据截断 printf(suc. to dump data.n); else printf(fail to dump data.n); znFAT_Close_File(&fileinfo); else printf(fail to open file.n); znFAT_Flush(); return 0; 9）文件删除 UINT8 znFAT_Delete_File(INT8 *filepath)此函数用于文件的删除。filepath 是文件的路径。文件删除时，最好保证此时没有文件处于打开状态（znFAT处于非实时簇链更新的情况下）。应用实例如下：struct znFAT_Init_Args Init_Args; /初始化参数集合int main(void) znFAT_Device_Init(); /存储设备初始化 znFAT_Select_Device(0,&Init_Args); /选择设备 znFAT_Init(); /文件系统初始化 if(!znFAT_Delete_File(/znmcu.txt) printf(suc. to del file.n); else printf(fail to del file.n); znFAT_Flush(); return 0; 9）目录删除 UINT8 znFAT_Delete_Dir(INT8 *dirpath)此函数用于实现对目录的删除。dirpath为目录的路径，如/abc/xyz ，注意此路径不以/或结束。要删除的目录下如果有文件中子目录，并且有更深子目录，也会一并删除。应用实例如下：struct znFAT_Init_Args Init_Args; /初始化参数集合int main(void) znFAT_Device_Init(); /存储设备初始化 znFAT_Select_Device(0,&Init_Args); /选择设备 znFAT_Init(); /文件系统初始化 if(!znFAT_Delete_Dir(/dir1) printf(suc. to del dir.n); else printf(fail to del dir.n); znFAT_Flush(); return 0; 10）大模式为文件预先准备存储空间 UINT8 znFAT_Prepare_Space_For_File(struct FileInfo *pfi,UINT32 datalen)大模式是