广州周立功单片机发展有限公司 Tel,(020) 38730916 38730917 38730976 38730977 Fax,38730925
ZLG/FS文件系统简要说明
1 概述
1.1 ZLG/FS简介
ZLG/FS 是 广州周立 功 单片机发 展 有限公司 开 发的面向 嵌 入式系统 开 发的小型 文 件 系统，是 ZLG 系列中间件的重要成员之一。它是与 FAT12,FAT16,FAT32 高度兼容的文件系统,可以直接与个人电脑交换文件。 它是可移植的,可固化的文件系统,可以用于前后 台系统，也可用于多任务环境。目前,ZLG/FS 的最新版本为 1.0。
1.2 ZLG/FS的特点
null 高度兼容 FAT12、FAT16、FAT32
ZLG/FS 可以正确访问由 windows98 建立的 FAT12,FAT16,FAT32 逻辑盘,ZLG/FS
建立的逻辑盘也可以被 windows98 正确的访问。
null 可移植
全部代码由 ANSI C 编写,并且与目标处理器的存储器结构无关（即与无论存储器是大端结构 还是小端结 构均不影响 程序的执行）,方便用户 移植到自己 的目标系统中。
null 可固化
ZLG/FS 为嵌入系统设计,如果您有固化手段,它可以嵌入到您的产品中成为产品的一部分
null 支持多任务操作系统
提供 ZLG/FS 在μ C/OS-II 使用的接口代码,用户参考这些代码就可以很方便的在别的多任务环境下使用 ZLG/FS。
null 兼容多种介质
ZLG/FS 提供一个底层驱动程序的接口,用户只需要提供相应的介质的扇区访问代码就可以在相应的介质上使用 ZLG/FS。
null 提供源代码
需要购买源码的用户可以与广州周立功单片机发展有限公司联系。
null 可配置
得到源码的用户可以对一些参数进行配置。
1.3 已实现的特性
null 支持多个逻辑盘
null 不同的逻辑盘可以在不同的介质上
null 支持树型目录结构，子目录层数不受限制
null 支持以 FAT12、FAT16、FAT32 格式化的逻辑盘
null 支持 8.3 文件名格式
null 支持文件读写和目录操作
null 提供格式化(format)范例代码
1.4 暂时未实现的特性
null 对文件、目录名的限制不够严格
这一版本的 ZLG/FS 有一些 FAT 规范限制使用的字符没有过滤掉。
- 1 -
广州周立功单片机发展有限公司 Tel,(020) 38730916 38730917 38730976 38730977 Fax,38730925
null 忽略文件（目录）属性中的时间相关属性
因为嵌入 式 系统常常 没 有系统时 钟,而且即 使 有，也没 有 统一的标 准,所以这一个版本的 ZLG/FS 没有处理文件、目录关于时间相关的特性。
null 忽略文件（目录）属性中的只读、存档、隐含、系统属性
这一版本的 ZLG/FS 没有对带有着几个属性的文件、目录进行特殊处理。
null 忽略除第一个 FAT 表以外的所有 FAT 表
如果逻辑盘有几个 FAT 表,则这一版 本的 ZLG/FS 只操作第一个 FAT 表,其它的 FAT
表保持不变。这几个 FAT 表就不同步。
null 忽略长文件名
这一版本的 ZLG/FS 不支持创建和访问长文件名的文件。不过，具有长文件名的文件还是可以通过短文件名访问。
ZLG/FS 的升级版将逐步解决上述问题。
2 ZLG/FS的结构视图
2.1 概述
ZLG/FS 采用模块化层次结构设计,并使用底层驱动程序来兼容不同的硬件结构和不同的介质，其结构如图 1 所示。
2.2 应用程序
应用程序是用户自己编写的程序,是 ZLG/FS 的使用者,位于整个程序的最高层。 应用程序可以调用 ZLG/FS 提供的函数 (API)对文件和目录进行相应的操作。
2.3 文件管理与目录管理
文件管理模块和目录管理模块是直接与应用程序接口的模块，位于 ZLG/FS 的最高层。
大部分用户接口函数 （ API） 都在这两个模块中定义。 文件管理模块提供所有与相关文件相关的函数（ API） ；目录管理模块提供与操作录相关的函数（ API） 。
2.4 文件分配表管理与文件目录表管理
文件分配表管理模块和文件目录表管理模块管理着 FAT 文 件系统的两个重要的数据结构，用户程序不能调用它们。
2.5 逻辑盘管理模块
逻辑盘管理模块保存着每个逻辑盘的一些基本信息。 例如,逻辑盘使用的驱动程序由这个模块保 存 。这些信 息 会被很多 其 它模块使 用,大部分 模 块都需要 调 用这个模 块 的 函 数
（ API）来获取自己需要的逻辑盘的信息。 ZLG/FS 通过这个模块管理多个逻辑盘。
2.6 高速缓存(cache)管理模块
高速缓存 （ cache） 是为了 加快逻辑盘的访问速度而加入的。 它利用一些 ram 作为 cache
保存一些访问过的逻辑盘扇区的内容。如果某次读逻辑盘扇区的数据时 cache 中有 其备份，
则不再 读取 磁盘。 同时,写数 据到 逻辑盘 扇区 实际并 不直 接操作 逻辑 盘扇区,而 是先写 到
cache 中,当 某种原因这一片 cache 要 存储其它扇区数据时,或是调用相应的函数 （ API）时才真正的写入逻辑盘。 这样就极大的减少了访问逻辑盘的次数,相应的提高了速度 （通常逻辑盘速度比较慢） 。这个模块就是用来管理 cache 的。
- 2 -
广州周立功单片机发展有限公司 Tel,(020) 38730916 38730917 38730976 38730977 Fax,38730925
2.7 底层驱动程序
ZLG/FS 可以兼容多种介质和硬件,这是通过底层驱动程序实现的。 底层驱动为上层程序提供与设备无关的接口,ZLG/FS 就通过这个接口访问实际的硬件。 由于嵌入式系统的硬件没有标准,千差万别,所以底层驱动程序一般由用户编写。 不过,ZLG/FS 已经把与硬件相关的代码压缩到最小,用户只要编写很少的代码就可以使用 ZLG/FS 了。 同时 ZLG/FS 给出相应的文档及实例帮助用户编写底层驱动程序。
2.8 实用程序
实用程序不是 ZLG/FS 的组成部分,用户的最终代码也可能不包括它们。 但它们又是非常必要的。 例如,初次使用文件系统时往往要用到 format（格式化逻辑盘） 实用程序初始化逻辑盘。 当前版本的 ZLG/FS 包含一个与硬件无关 format 的代码 （一些实用程序如分区是与硬件相关的） 。
文件分配表
（ FAT） 管理文件管理
目录管理
文件目录表
（ FDT） 管理逻辑盘管理 高速缓存（ CACSE）管理实用程序
应用程序
底层驱动程序
注释,(1) 实线箭头表示正常调用关系，虚线表示正常情况不会出现的调用。
(2) 模块所在位置代表其所在的层次
(3) 实用程序可能调用任何层次的函数
图1 ZLG/FS逻辑结构图
3 源代码文件说明
ZLG/FS 由多个文件组成，其简要说明见表 1。
表1 ZLG/FS源代码说明
文件名 所属模块 备注
Fat.h 无 ZLG/FS 的头文件
file.C 文件管理 无
dir.C 目录管理 无
- 3 -
广州周立功单片机发展有限公司 Tel,(020) 38730916 38730917 38730976 38730977 Fax,38730925
FAT.C 文件分配表管理 用户不能直接调用
FDT.C 文件目录表管理 用户不能直接调用
disk.C 逻辑盘管理 无
RWSec.C 高速缓存管理 用户不能直接调用
OSFile.c μ C/OS-II 接口代码 无
用户编写文件 低层驱动程序 参考例子 floppy.c
format.C 实用程序 格式化例子
4 API函数集
4.1 系统配置配置手册
ZLG/FS 是一个可以配置的软件包。目前，其可配置的选项不多，具体信息参考表 2。
其配置的方法是在 config.h 的 #include,fat.h”之前定义这些常量，其例子见程序清单 1。
表2 ZLG/FS系统配置一览表
功能 常量名 取值范围 描述、注意点
可以同时打开的文件数目
MAX_OPEN_FILES 1~0x8000 尽量贴近实际需要。使用较小的值可以优化代码和
RAM 的使用。其默认值为 10。
cache 可缓冲的数据大小
DISK_CACHE_SIZE 根据实际 情况取值
应当是所有逻辑盘中扇区所占字节数最大的那个逻辑盘的扇区的尺寸。其默认值为 512。
cache 可缓冲的扇区数目
MAX_DISK_CACHES 1~65535 调整此值可以在速度和 RAM 占用之间取得平衡,应该通过实验决定此值。其默认值为 100。
可同时支持的逻辑盘数目
MAX_DRIVES 1~26 尽量贴近实际需要。使用较小的值可以优化代码和
RAM 的使用。其默认值为 1。
程序清单1 修改ZLG/FS的配置
#define MAX_OPEN_FILES 10
#define DISK_CACHE_SIZE 512
#define MAX_DISK_CACHES 100
#define MAX_DRIVES 1
#include "fat.h"
4.2 返回值说明
ZLG/FS 的很多函数都用返回值返回操作的结果信息,它们的返回值是统一的,见表 3。
- 4 -
广州周立功单片机发展有限公司 Tel,(020) 38730916 38730917 38730976 38730977 Fax,38730925
表3 ZLG/FS 返回参数一览表
名称 值 含义
RETURN_OK 0x00 操作成功
NOT_FIND_DISK 0x01 逻辑盘不存在
DISK_FULL 0x02 逻辑盘满
SECTOR_NOT_IN_CACHE 0x03 扇区没有被 cache
NOT_EMPTY_CACHE 0x04 没有空闲 cache
SECTOR_READ_ERR 0x05 读扇区错误
CLUSTER_NOT_IN_DISK 0x06 逻辑盘中没有此簇
NOT_FIND_FDT 0x07 没有发现文件 (目录 )
NOT_FAT_DISK 0x08 非 FAT 文件系统
FDT_OVER 0x09 FDT 索引超出范围
FDT_EXISTS 0x0a 文件 (目录 )已经存在
ROOT_FDT_FULL 0x0b 根目录满
DIR_EMPTY 0x0c 目录空
DIR_NOT_EMPTY 0x0d 目录不空
PATH_NOT_FIND 0x0e 路径未找到
FAT_ERR 0x0f FAT 表错误
FILE_NAME_ERR 0x10 文件 (目录 )名错误
FILE_EOF 0x11 文件结束
FILE_LOCK 0x12 文件被锁定
NOT_FIND_FILE 0x13 没有发现指定文件
NOT_FIND_DIR 0x14 没有发现指定目录
NOT_RUN 0xfd 命令未执行
BAD_COMMAND 0xfe 错误命令
PARAMETER_ERR 0xff 非法参数
4.3 用户接口函数
ZLG/FS 有很多用户可以调用的接口函数，下面按照字母顺序对它们一一说明，包括：
函数名称、函数原型、函数功能描述、函数参数、函数返回值、特殊说明和注意点等。
注意：以下为单任务下的 API 函数,多任务情况下的 API 函数为对应的函数前加字符
Os，其它不变。
表4 AddFileDriver ()函数
函数名称 AddFileDriver
函数原型 void AddFileDriver(uint16 (* DiakCommand)(uint8 Cammand,void *Parameter))
功能描述 为 ZLG/FS 加载一个底层驱动程序
函数参数 DiakCommand：驱动程序接口函数
函数返回值 无
- 5 -
广州周立功单片机发展有限公司 Tel,(020) 38730916 38730917 38730976 38730977 Fax,38730925
特殊说明
和注意点
一般在系统初始化时调用
表5 AllCacheWriteBack()函数
函数名称 AllCacheWriteBack
函数原型 void AllCacheWriteBack(void)
功能描述 将所有已改变的逻辑扇区写回逻辑盘
函数参数 无
函数返回值 无
特殊说明
和注意点
一般在主程序结束前或每隔一定时间调用一次。
表6 CacheWriteBack2()函数
函数名称 CacheWriteBack2
函数原型 void CacheWriteBack2(uint16 Index)
功能描述 将指定 cache 保存的内容写回逻辑盘
函数参数 无 Index,cache 索引
函数返回值 无
特殊说明
和注意点
一般情况下用户无需调用此函数
表7 ChangeDir()函数
函数名称 ChangeDir
函数原型 uint8 ChangeDir(char *Path)
功能描述 改变当前目录
函数参数 Path：路径名
函数返回值 参考表 3
特殊说明
和注意点
每一个逻辑盘都有自己的当前目录
表8 ChangeDrive()函数
函数名称 ChangeDrive
函数原型 uint8 ChangeDrive(char *Drive)
- 6 -
广州周立功单片机发展有限公司 Tel,(020) 38730916 38730917 38730976 38730977 Fax,38730925
功能描述 改变当前逻辑盘
函数参数 Drive：包含逻辑盘符的字符串（路径格式）
函数返回值 无
特殊说明
和注意点
无
表9 DirIsEmpty()函数
函数名称 DirIsEmpty
函数原型 uint8 DirIsEmpty(uint8 Drive,uint32 ClusIndex)
功能描述 判断指定目录是否为空
函数参数
Drive：驱动器号
ClusIndex：目录首簇号
函数返回值
DIR_EMPTY：空
DIR_NOT_EMPTY：不空
其它参考表 3
特殊说明
和注意点
表10 DiskInit()函数
函数名称 DiskInit
函数原型 void DiskInit(void)
功能描述 逻辑盘信息管理模块初始化
函数参数 无
函数返回值 无
特殊说明
和注意点
仅在系统初始化时调用
表11 FDTIsLie()函数
函数名称 FDTIsLie
函数原型 uint8 FDTIsLie(uint8 Drive,uint32 ClusIndex,char FileName[])
功能描述 察看在指定目录的指定指定文件（目录）是否存在
函数参数
Drive：驱动器号
ClusIndex：目录首簇号
FileName：文件（目录）名（内部表示法）
函数返回值 参考表 3
- 7 -
广州周立功单片机发展有限公司 Tel,(020) 38730916 38730917 38730976 38730977 Fax,38730925
特殊说明
和注意点
FileName 为 FDT 表的格式，即 11 个字节,主文件名 8 个 字节，不足部分用 0x20 填充,
扩展文件名 3 个字节，不足部分用 0x20 填充
表12 FileClose()函数
函数名称 FileClose
函数原型
uint8 FileClose(H
ANDLE Handle)
功能描述 关闭指定文件
函数参数 Handle：需要关闭的文件的句柄
函数返回值 参考表 3
特殊说明
和注意点
与 c 语言标准库函数 fclose 的用法相同，只是文件指针替换为文件句柄
表13 FileCloseAll()函数
函数名称 FileCloseAll
函数原型 void FileCloseAll(void)
功能描述 关闭所有打开的文件
函数参数 无
函数返回值 无
特殊说明
和注意点
一般在系统关闭前调用,与 c 语言标准库函数 fcloseall 的用法相同
表14 FileEof()函数
函数名称 FileEof
函数原型 uint8 FileEof(HANDLE Handle)
功能描述 判断是否到读 \写到指定文件的文件尾
函数参数 Handle：文件句柄
函数返回值
0：否
1：是
特殊说明
和注意点
与 c 语言标准库函数 feof 的用法相同，只是文件指针替换为文件句柄
表15 FileGetCh()函数
函数名称 FileGetCh
- 8 -
广州周立功单片机发展有限公司 Tel,(020) 38730916 38730917 38730976 38730977 Fax,38730925
函数原型 uint8 FileGetCh(uint8 *Ch,HANDLE Handle)
功能描述 从指定文件读一个字节
函数参数
Ch：保存读到的数据的在地址
Handle：文件句柄
函数返回值 参考表 3
特殊说明
和注意点
无
表16 FileInit()函数
函数名称 FileInit
函数原型 void FileInit(void)
功能描述 初始化文件系统
函数参数 无
函数返回值 无
特殊说明
和注意点
无
表17 FileOpen()函数
函数名称 FileOpen
函数原型 HANDLE FileOpen(char *DirFileName,char *Type)
功能描述 以指定方式打开文件
函数参数
DirFileName：用户使用的文件名
Type:：开方式
函数返回值 文件句柄,Not_Open_FILE 为不能打开
特殊说明
和注意点
与 c 语言标准库函数 fopen 的参数和用法相同，只是文件指针替换为文件句柄
注意：不能同时以读写和 /或只写方式打开同一个文件两次或两次以上。
表18 FilePutCh()函数
函数名称 FilePutCh
函数原型 uint8 FilePutCh(uint8 Ch,HANDLE Handle)
功能描述 写一个字节到指定文件
函数参数
Ch：要写的数据
Handle：文件句柄
函数返回值 参考表 3
- 9 -
广州周立功单片机发展有限公司 Tel,(020) 38730916 38730917 38730976 38730977 Fax,38730925
特殊说明
和注意点
无
表19 FileRead()函数
函数名称 FileRead
函数原型 uint32 FileRead(void *Buf,uint32 Size,HANDLE Handle)
功能描述 从指定文件读取指定大小数据
函数参数
Buf：保存读回的数据地址
Size：要读的字节数
Handle：文件句柄
函数返回值 实际读到的字节数
特殊说明
和注意点
与 c 语言标准库函数 fread 类似
表20 FileSeek()函数
函数名称 FileSeek
函数原型 uint8 FileSeek(HANDLE Handle,int32 offset,uint8 Whence)
功能描述 移动文件读 \写位置
函数参数
Handle：文件句柄
Offset：移动偏移量
Whence：移动 模式 SEEK_SET:从文件头计 算 SEEK_CUR:从当前位置计算 SEEK_END:
从文件尾计算
函数返回值 无
特殊说明
和注意点
与 c 语言标准库函数 fseek 的参数和用法相同，只是文件指针替换为文件句柄
表21 FileWrite()函数
函数名称 FileWrite
函数原型 uint32 FileWrite(void *Buf,uint32 Size,HANDLE Handle)
功能描述 写多个数据到指定文件
函数参数
Buf：要写的数据的地址
Size：要写的字节数
Handle：文件句柄
函数返回值 实际写的字节数
特殊说明
和注意点
与 c 语言标准库函数 fwrite 类似
- 10 -
广州周立功单片机发展有限公司 Tel,(020) 38730916 38730917 38730976 38730977 Fax,38730925
表22 GetDrive()函数
函数名称 GetDrive
函数原型 uint8 GetDrive(char *Path)
功能描述 获取指定目录的逻辑驱动器的内部表示法名称
函数参数 Path：路径名
函数返回值 逻辑驱动器的内部表示法名称
特殊说明
和注意点
无
表23 GetFDTInfo()函数
函数名称 GetFDTInfo
函数原型 uint8 GetFDTInfo(FDT *Rt,uint8 Drive,uint32 ClusIndex,uint32 Index)
功能描述 获取指定目录指定文件（目录）信息
函数参数
Rt：存储返回信息的指针
Drive：驱动器号（内部表示法）
ClusIndex：目录首簇号
Index：文件（目录）在 FDT 中的位置
函数返回值 参考表 3
特殊说明
和注意点
一般情况下用户无需使用此函数。此函数是为搜索指定文件 \目录实用程序准备的。
表24 MakeDir()函数
函数名称 MakeDir
函数原型 uint8 MakeDir(char *Path)
功能描述 建立目录
函数参数 Path：路径名
函数返回值 参考表 3
特殊说明
和注意点
输入参数与 dos 命令 md 的参数相同
表25 RemoveDir()函数
函数名称 RemoveDir
函数原型 uint8 RemoveDir(char *Path)
功能描述 删除目录
- 11 -
广州周立功单片机发展有限公司 Tel,(020) 38730916 38730917 38730976 38730977 Fax,38730925
函数参数 Path：路径名
函数返回值 参考表 3
特殊说明
和注意点
输入参数与 dos 命令 rd 的参数相同
表26 RemoveFile()函数
函数名称 RemoveFile
函数原型 uint8 RemoveFile(char *DirFileName)
功能描述 删除指定文件
函数参数 DirFileName:用户使用的文件名（可包含路径）
函数返回值 参考表 3
特殊说明
和注意点
这个函数与 dos 的 del 命令不 同，它一次只能删除一个文件，而且在当前版本中理会文件的只读等属性。同时，如果文件已经被打开，则这个文件不能被删除。
表27 RemoveFileDriver()函数
函数名称 RemoveFileDriver
函数原型 void RemoveFileDriver(uint8 Drive)
功能描述 删除一个底层驱动程序
函数参数 Drive：逻辑驱动器号（内部表示法）
函数返回值 无
特殊说明
和注意点
无
表28 GetEmptyDiskInfoAddr()函数
函数名称 GetEmptyDiskInfoAddr
函数原型 Disk_Info * GetEmptyDiskInfoAddr(void)
功能描述 获取空闲逻辑盘登记项
函数参数 无
函数返回值 指向空闲逻辑盘信息登记项的结构体指针
特殊说明
和注意点
给底层驱动程序使用，一般用户程序无需调用。
- 12 -
ZLG/FS文件系统简要说明
1 概述
1.1 ZLG/FS简介
ZLG/FS 是 广州周立 功 单片机发 展 有限公司 开 发的面向 嵌 入式系统 开 发的小型 文 件 系统，是 ZLG 系列中间件的重要成员之一。它是与 FAT12,FAT16,FAT32 高度兼容的文件系统,可以直接与个人电脑交换文件。 它是可移植的,可固化的文件系统,可以用于前后 台系统，也可用于多任务环境。目前,ZLG/FS 的最新版本为 1.0。
1.2 ZLG/FS的特点
null 高度兼容 FAT12、FAT16、FAT32
ZLG/FS 可以正确访问由 windows98 建立的 FAT12,FAT16,FAT32 逻辑盘,ZLG/FS
建立的逻辑盘也可以被 windows98 正确的访问。
null 可移植
全部代码由 ANSI C 编写,并且与目标处理器的存储器结构无关（即与无论存储器是大端结构 还是小端结 构均不影响 程序的执行）,方便用户 移植到自己 的目标系统中。
null 可固化
ZLG/FS 为嵌入系统设计,如果您有固化手段,它可以嵌入到您的产品中成为产品的一部分
null 支持多任务操作系统
提供 ZLG/FS 在μ C/OS-II 使用的接口代码,用户参考这些代码就可以很方便的在别的多任务环境下使用 ZLG/FS。
null 兼容多种介质
ZLG/FS 提供一个底层驱动程序的接口,用户只需要提供相应的介质的扇区访问代码就可以在相应的介质上使用 ZLG/FS。
null 提供源代码
需要购买源码的用户可以与广州周立功单片机发展有限公司联系。
null 可配置
得到源码的用户可以对一些参数进行配置。
1.3 已实现的特性
null 支持多个逻辑盘
null 不同的逻辑盘可以在不同的介质上
null 支持树型目录结构，子目录层数不受限制
null 支持以 FAT12、FAT16、FAT32 格式化的逻辑盘
null 支持 8.3 文件名格式
null 支持文件读写和目录操作
null 提供格式化(format)范例代码
1.4 暂时未实现的特性
null 对文件、目录名的限制不够严格
这一版本的 ZLG/FS 有一些 FAT 规范限制使用的字符没有过滤掉。
- 1 -
广州周立功单片机发展有限公司 Tel,(020) 38730916 38730917 38730976 38730977 Fax,38730925
null 忽略文件（目录）属性中的时间相关属性
因为嵌入 式 系统常常 没 有系统时 钟,而且即 使 有，也没 有 统一的标 准,所以这一个版本的 ZLG/FS 没有处理文件、目录关于时间相关的特性。
null 忽略文件（目录）属性中的只读、存档、隐含、系统属性
这一版本的 ZLG/FS 没有对带有着几个属性的文件、目录进行特殊处理。
null 忽略除第一个 FAT 表以外的所有 FAT 表
如果逻辑盘有几个 FAT 表,则这一版 本的 ZLG/FS 只操作第一个 FAT 表,其它的 FAT
表保持不变。这几个 FAT 表就不同步。
null 忽略长文件名
这一版本的 ZLG/FS 不支持创建和访问长文件名的文件。不过，具有长文件名的文件还是可以通过短文件名访问。
ZLG/FS 的升级版将逐步解决上述问题。
2 ZLG/FS的结构视图
2.1 概述
ZLG/FS 采用模块化层次结构设计,并使用底层驱动程序来兼容不同的硬件结构和不同的介质，其结构如图 1 所示。
2.2 应用程序
应用程序是用户自己编写的程序,是 ZLG/FS 的使用者,位于整个程序的最高层。 应用程序可以调用 ZLG/FS 提供的函数 (API)对文件和目录进行相应的操作。
2.3 文件管理与目录管理
文件管理模块和目录管理模块是直接与应用程序接口的模块，位于 ZLG/FS 的最高层。
大部分用户接口函数 （ API） 都在这两个模块中定义。 文件管理模块提供所有与相关文件相关的函数（ API） ；目录管理模块提供与操作录相关的函数（ API） 。
2.4 文件分配表管理与文件目录表管理
文件分配表管理模块和文件目录表管理模块管理着 FAT 文 件系统的两个重要的数据结构，用户程序不能调用它们。
2.5 逻辑盘管理模块
逻辑盘管理模块保存着每个逻辑盘的一些基本信息。 例如,逻辑盘使用的驱动程序由这个模块保 存 。这些信 息 会被很多 其 它模块使 用,大部分 模 块都需要 调 用这个模 块 的 函 数
（ API）来获取自己需要的逻辑盘的信息。 ZLG/FS 通过这个模块管理多个逻辑盘。
2.6 高速缓存(cache)管理模块
高速缓存 （ cache） 是为了 加快逻辑盘的访问速度而加入的。 它利用一些 ram 作为 cache
保存一些访问过的逻辑盘扇区的内容。如果某次读逻辑盘扇区的数据时 cache 中有 其备份，
则不再 读取 磁盘。 同时,写数 据到 逻辑盘 扇区 实际并 不直 接操作 逻辑 盘扇区,而 是先写 到
cache 中,当 某种原因这一片 cache 要 存储其它扇区数据时,或是调用相应的函数 （ API）时才真正的写入逻辑盘。 这样就极大的减少了访问逻辑盘的次数,相应的提高了速度 （通常逻辑盘速度比较慢） 。这个模块就是用来管理 cache 的。
- 2 -
广州周立功单片机发展有限公司 Tel,(020) 38730916 38730917 38730976 38730977 Fax,38730925
2.7 底层驱动程序
ZLG/FS 可以兼容多种介质和硬件,这是通过底层驱动程序实现的。 底层驱动为上层程序提供与设备无关的接口,ZLG/FS 就通过这个接口访问实际的硬件。 由于嵌入式系统的硬件没有标准,千差万别,所以底层驱动程序一般由用户编写。 不过,ZLG/FS 已经把与硬件相关的代码压缩到最小,用户只要编写很少的代码就可以使用 ZLG/FS 了。 同时 ZLG/FS 给出相应的文档及实例帮助用户编写底层驱动程序。
2.8 实用程序
实用程序不是 ZLG/FS 的组成部分,用户的最终代码也可能不包括它们。 但它们又是非常必要的。 例如,初次使用文件系统时往往要用到 format（格式化逻辑盘） 实用程序初始化逻辑盘。 当前版本的 ZLG/FS 包含一个与硬件无关 format 的代码 （一些实用程序如分区是与硬件相关的） 。
文件分配表
（ FAT） 管理文件管理
目录管理
文件目录表
（ FDT） 管理逻辑盘管理 高速缓存（ CACSE）管理实用程序
应用程序
底层驱动程序
注释,(1) 实线箭头表示正常调用关系，虚线表示正常情况不会出现的调用。
(2) 模块所在位置代表其所在的层次
(3) 实用程序可能调用任何层次的函数
图1 ZLG/FS逻辑结构图
3 源代码文件说明
ZLG/FS 由多个文件组成，其简要说明见表 1。
表1 ZLG/FS源代码说明
文件名 所属模块 备注
Fat.h 无 ZLG/FS 的头文件
file.C 文件管理 无
dir.C 目录管理 无
- 3 -
广州周立功单片机发展有限公司 Tel,(020) 38730916 38730917 38730976 38730977 Fax,38730925
FAT.C 文件分配表管理 用户不能直接调用
FDT.C 文件目录表管理 用户不能直接调用
disk.C 逻辑盘管理 无
RWSec.C 高速缓存管理 用户不能直接调用
OSFile.c μ C/OS-II 接口代码 无
用户编写文件 低层驱动程序 参考例子 floppy.c
format.C 实用程序 格式化例子
4 API函数集
4.1 系统配置配置手册
ZLG/FS 是一个可以配置的软件包。目前，其可配置的选项不多，具体信息参考表 2。
其配置的方法是在 config.h 的 #include,fat.h”之前定义这些常量，其例子见程序清单 1。
表2 ZLG/FS系统配置一览表
功能 常量名 取值范围 描述、注意点
可以同时打开的文件数目
MAX_OPEN_FILES 1~0x8000 尽量贴近实际需要。使用较小的值可以优化代码和
RAM 的使用。其默认值为 10。
cache 可缓冲的数据大小
DISK_CACHE_SIZE 根据实际 情况取值
应当是所有逻辑盘中扇区所占字节数最大的那个逻辑盘的扇区的尺寸。其默认值为 512。
cache 可缓冲的扇区数目
MAX_DISK_CACHES 1~65535 调整此值可以在速度和 RAM 占用之间取得平衡,应该通过实验决定此值。其默认值为 100。
可同时支持的逻辑盘数目
MAX_DRIVES 1~26 尽量贴近实际需要。使用较小的值可以优化代码和
RAM 的使用。其默认值为 1。
程序清单1 修改ZLG/FS的配置
#define MAX_OPEN_FILES 10
#define DISK_CACHE_SIZE 512
#define MAX_DISK_CACHES 100
#define MAX_DRIVES 1
#include "fat.h"
4.2 返回值说明
ZLG/FS 的很多函数都用返回值返回操作的结果信息,它们的返回值是统一的,见表 3。
- 4 -
广州周立功单片机发展有限公司 Tel,(020) 38730916 38730917 38730976 38730977 Fax,38730925
表3 ZLG/FS 返回参数一览表
名称 值 含义
RETURN_OK 0x00 操作成功
NOT_FIND_DISK 0x01 逻辑盘不存在
DISK_FULL 0x02 逻辑盘满
SECTOR_NOT_IN_CACHE 0x03 扇区没有被 cache
NOT_EMPTY_CACHE 0x04 没有空闲 cache
SECTOR_READ_ERR 0x05 读扇区错误
CLUSTER_NOT_IN_DISK 0x06 逻辑盘中没有此簇
NOT_FIND_FDT 0x07 没有发现文件 (目录 )
NOT_FAT_DISK 0x08 非 FAT 文件系统
FDT_OVER 0x09 FDT 索引超出范围
FDT_EXISTS 0x0a 文件 (目录 )已经存在
ROOT_FDT_FULL 0x0b 根目录满
DIR_EMPTY 0x0c 目录空
DIR_NOT_EMPTY 0x0d 目录不空
PATH_NOT_FIND 0x0e 路径未找到
FAT_ERR 0x0f FAT 表错误
FILE_NAME_ERR 0x10 文件 (目录 )名错误
FILE_EOF 0x11 文件结束
FILE_LOCK 0x12 文件被锁定
NOT_FIND_FILE 0x13 没有发现指定文件
NOT_FIND_DIR 0x14 没有发现指定目录
NOT_RUN 0xfd 命令未执行
BAD_COMMAND 0xfe 错误命令
PARAMETER_ERR 0xff 非法参数
4.3 用户接口函数
ZLG/FS 有很多用户可以调用的接口函数，下面按照字母顺序对它们一一说明，包括：
函数名称、函数原型、函数功能描述、函数参数、函数返回值、特殊说明和注意点等。
注意：以下为单任务下的 API 函数,多任务情况下的 API 函数为对应的函数前加字符
Os，其它不变。
表4 AddFileDriver ()函数
函数名称 AddFileDriver
函数原型 void AddFileDriver(uint16 (* DiakCommand)(uint8 Cammand,void *Parameter))
功能描述 为 ZLG/FS 加载一个底层驱动程序
函数参数 DiakCommand：驱动程序接口函数
函数返回值 无
- 5 -
广州周立功单片机发展有限公司 Tel,(020) 38730916 38730917 38730976 38730977 Fax,38730925
特殊说明
和注意点
一般在系统初始化时调用
表5 AllCacheWriteBack()函数
函数名称 AllCacheWriteBack
函数原型 void AllCacheWriteBack(void)
功能描述 将所有已改变的逻辑扇区写回逻辑盘
函数参数 无
函数返回值 无
特殊说明
和注意点
一般在主程序结束前或每隔一定时间调用一次。
表6 CacheWriteBack2()函数
函数名称 CacheWriteBack2
函数原型 void CacheWriteBack2(uint16 Index)
功能描述 将指定 cache 保存的内容写回逻辑盘
函数参数 无 Index,cache 索引
函数返回值 无
特殊说明
和注意点
一般情况下用户无需调用此函数
表7 ChangeDir()函数
函数名称 ChangeDir
函数原型 uint8 ChangeDir(char *Path)
功能描述 改变当前目录
函数参数 Path：路径名
函数返回值 参考表 3
特殊说明
和注意点
每一个逻辑盘都有自己的当前目录
表8 ChangeDrive()函数
函数名称 ChangeDrive
函数原型 uint8 ChangeDrive(char *Drive)
- 6 -
广州周立功单片机发展有限公司 Tel,(020) 38730916 38730917 38730976 38730977 Fax,38730925
功能描述 改变当前逻辑盘
函数参数 Drive：包含逻辑盘符的字符串（路径格式）
函数返回值 无
特殊说明
和注意点
无
表9 DirIsEmpty()函数
函数名称 DirIsEmpty
函数原型 uint8 DirIsEmpty(uint8 Drive,uint32 ClusIndex)
功能描述 判断指定目录是否为空
函数参数
Drive：驱动器号
ClusIndex：目录首簇号
函数返回值
DIR_EMPTY：空
DIR_NOT_EMPTY：不空
其它参考表 3
特殊说明
和注意点
表10 DiskInit()函数
函数名称 DiskInit
函数原型 void DiskInit(void)
功能描述 逻辑盘信息管理模块初始化
函数参数 无
函数返回值 无
特殊说明
和注意点
仅在系统初始化时调用
表11 FDTIsLie()函数
函数名称 FDTIsLie
函数原型 uint8 FDTIsLie(uint8 Drive,uint32 ClusIndex,char FileName[])
功能描述 察看在指定目录的指定指定文件（目录）是否存在
函数参数
Drive：驱动器号
ClusIndex：目录首簇号
FileName：文件（目录）名（内部表示法）
函数返回值 参考表 3
- 7 -
广州周立功单片机发展有限公司 Tel,(020) 38730916 38730917 38730976 38730977 Fax,38730925
特殊说明
和注意点
FileName 为 FDT 表的格式，即 11 个字节,主文件名 8 个 字节，不足部分用 0x20 填充,
扩展文件名 3 个字节，不足部分用 0x20 填充
表12 FileClose()函数
函数名称 FileClose
函数原型
uint8 FileClose(H
ANDLE Handle)
功能描述 关闭指定文件
函数参数 Handle：需要关闭的文件的句柄
函数返回值 参考表 3
特殊说明
和注意点
与 c 语言标准库函数 fclose 的用法相同，只是文件指针替换为文件句柄
表13 FileCloseAll()函数
函数名称 FileCloseAll
函数原型 void FileCloseAll(void)
功能描述 关闭所有打开的文件
函数参数 无
函数返回值 无
特殊说明
和注意点
一般在系统关闭前调用,与 c 语言标准库函数 fcloseall 的用法相同
表14 FileEof()函数
函数名称 FileEof
函数原型 uint8 FileEof(HANDLE Handle)
功能描述 判断是否到读 \写到指定文件的文件尾
函数参数 Handle：文件句柄
函数返回值
0：否
1：是
特殊说明
和注意点
与 c 语言标准库函数 feof 的用法相同，只是文件指针替换为文件句柄
表15 FileGetCh()函数
函数名称 FileGetCh
- 8 -
广州周立功单片机发展有限公司 Tel,(020) 38730916 38730917 38730976 38730977 Fax,38730925
函数原型 uint8 FileGetCh(uint8 *Ch,HANDLE Handle)
功能描述 从指定文件读一个字节
函数参数
Ch：保存读到的数据的在地址
Handle：文件句柄
函数返回值 参考表 3
特殊说明
和注意点
无
表16 FileInit()函数
函数名称 FileInit
函数原型 void FileInit(void)
功能描述 初始化文件系统
函数参数 无
函数返回值 无
特殊说明
和注意点
无
表17 FileOpen()函数
函数名称 FileOpen
函数原型 HANDLE FileOpen(char *DirFileName,char *Type)
功能描述 以指定方式打开文件
函数参数
DirFileName：用户使用的文件名
Type:：开方式
函数返回值 文件句柄,Not_Open_FILE 为不能打开
特殊说明
和注意点
与 c 语言标准库函数 fopen 的参数和用法相同，只是文件指针替换为文件句柄
注意：不能同时以读写和 /或只写方式打开同一个文件两次或两次以上。
表18 FilePutCh()函数
函数名称 FilePutCh
函数原型 uint8 FilePutCh(uint8 Ch,HANDLE Handle)
功能描述 写一个字节到指定文件
函数参数
Ch：要写的数据
Handle：文件句柄
函数返回值 参考表 3
- 9 -
广州周立功单片机发展有限公司 Tel,(020) 38730916 38730917 38730976 38730977 Fax,38730925
特殊说明
和注意点
无
表19 FileRead()函数
函数名称 FileRead
函数原型 uint32 FileRead(void *Buf,uint32 Size,HANDLE Handle)
功能描述 从指定文件读取指定大小数据
函数参数
Buf：保存读回的数据地址
Size：要读的字节数
Handle：文件句柄
函数返回值 实际读到的字节数
特殊说明
和注意点
与 c 语言标准库函数 fread 类似
表20 FileSeek()函数
函数名称 FileSeek
函数原型 uint8 FileSeek(HANDLE Handle,int32 offset,uint8 Whence)
功能描述 移动文件读 \写位置
函数参数
Handle：文件句柄
Offset：移动偏移量
Whence：移动 模式 SEEK_SET:从文件头计 算 SEEK_CUR:从当前位置计算 SEEK_END:
从文件尾计算
函数返回值 无
特殊说明
和注意点
与 c 语言标准库函数 fseek 的参数和用法相同，只是文件指针替换为文件句柄
表21 FileWrite()函数
函数名称 FileWrite
函数原型 uint32 FileWrite(void *Buf,uint32 Size,HANDLE Handle)
功能描述 写多个数据到指定文件
函数参数
Buf：要写的数据的地址
Size：要写的字节数
Handle：文件句柄
函数返回值 实际写的字节数
特殊说明
和注意点
与 c 语言标准库函数 fwrite 类似
- 10 -
广州周立功单片机发展有限公司 Tel,(020) 38730916 38730917 38730976 38730977 Fax,38730925
表22 GetDrive()函数
函数名称 GetDrive
函数原型 uint8 GetDrive(char *Path)
功能描述 获取指定目录的逻辑驱动器的内部表示法名称
函数参数 Path：路径名
函数返回值 逻辑驱动器的内部表示法名称
特殊说明
和注意点
无
表23 GetFDTInfo()函数
函数名称 GetFDTInfo
函数原型 uint8 GetFDTInfo(FDT *Rt,uint8 Drive,uint32 ClusIndex,uint32 Index)
功能描述 获取指定目录指定文件（目录）信息
函数参数
Rt：存储返回信息的指针
Drive：驱动器号（内部表示法）
ClusIndex：目录首簇号
Index：文件（目录）在 FDT 中的位置
函数返回值 参考表 3
特殊说明
和注意点
一般情况下用户无需使用此函数。此函数是为搜索指定文件 \目录实用程序准备的。
表24 MakeDir()函数
函数名称 MakeDir
函数原型 uint8 MakeDir(char *Path)
功能描述 建立目录
函数参数 Path：路径名
函数返回值 参考表 3
特殊说明
和注意点
输入参数与 dos 命令 md 的参数相同
表25 RemoveDir()函数
函数名称 RemoveDir
函数原型 uint8 RemoveDir(char *Path)
功能描述 删除目录
- 11 -
广州周立功单片机发展有限公司 Tel,(020) 38730916 38730917 38730976 38730977 Fax,38730925
函数参数 Path：路径名
函数返回值 参考表 3
特殊说明
和注意点
输入参数与 dos 命令 rd 的参数相同
表26 RemoveFile()函数
函数名称 RemoveFile
函数原型 uint8 RemoveFile(char *DirFileName)
功能描述 删除指定文件
函数参数 DirFileName:用户使用的文件名（可包含路径）
函数返回值 参考表 3
特殊说明
和注意点
这个函数与 dos 的 del 命令不 同，它一次只能删除一个文件，而且在当前版本中理会文件的只读等属性。同时，如果文件已经被打开，则这个文件不能被删除。
表27 RemoveFileDriver()函数
函数名称 RemoveFileDriver
函数原型 void RemoveFileDriver(uint8 Drive)
功能描述 删除一个底层驱动程序
函数参数 Drive：逻辑驱动器号（内部表示法）
函数返回值 无
特殊说明
和注意点
无
表28 GetEmptyDiskInfoAddr()函数
函数名称 GetEmptyDiskInfoAddr
函数原型 Disk_Info * GetEmptyDiskInfoAddr(void)
功能描述 获取空闲逻辑盘登记项
函数参数 无
函数返回值 指向空闲逻辑盘信息登记项的结构体指针
特殊说明
和注意点
给底层驱动程序使用，一般用户程序无需调用。
- 12 -
