2. 文件系统管理

AD16N FLASH方案支持只读sydfs、录音读写norfs以及fatfs文件系统；OTP方案只支持只读fatfs文件系统，且不使用vfs文件系统管理，直接调用fat文件系统接口，可节约代码空间；文件系统涉及的文件包括appsappbspcommonfs目录下的所有c文件、include_libfs目录下的所有头文件以及errno-base.h文件。

支持的文件系统列表：

文件系统

OTP方案

flash方案

详情

sydfs

不支持

支持

只读文件系统，用于存放资源文件到norflash；

norfs

不支持

支持

循环覆盖文件系统，可读写;针对norflash设计；

simple_fat

无

无

简单fat文件系统驱动,占用资源少，不支持搜索；支持FAT12/16/32, EXFAT;

fatfs

支持

支持

完整的fat文件系统驱动,占用资源多，支持搜索；支持FAT12/16/32, EXFAT;

fs有以下主要函数:
void fs_init(void);
u32 fs_mount(void **ppvfs, void *device, void *type);
u32 fs_openbypath(void *pvfs, void **ppvfile, const char *path);
int fs_select(void *pvfs, void **ppvfile, struct vfscan *fs, int sel_mode, int arg);
u32 fs_read(void *pvfile, void *buf, u32 len);
u32 fs_seek(void *pvfile, u32 offset, u32 mode);
u32 fs_file_close(void **ppvfile);
u32 fs_fs_close(void **ppvfs);
u32 fs_file_name(void *pvfile, void *name, u32 len);
int fs_get_attrs(void *pvfile, void *pvfs_attr);
int fs_ioctl(void *pvfile, int cmd, int arg);
int fs_ftell(void *pvfile, void *parm);
int fs_get_fsize(void *pvfile, void *parm);
struct vfscan *fs_fscan_new(void *pvfs, const char *path, const char *arg, u8 max_deepth, int (*callback)(void), struct vfscan *fsn, struct vfscan_reset_info *info);
int fs_fscan_release(void *pvfs, struct vfscan *fs);
int vs_get_folderinfo(void **pvfile, struct vfscan *fs, int *start_num, int *end_num);
int fs_get_encfolder_info(void *pvfs, char *folder, char *ext, u32 *last_num, u32 *total_num);

2.1. 文件系统介绍

SDK中支持的文件系统有：只读sydfs、录音读写norfs以及fatfs；可以在appbspfs目录下查看各文件系统的文件以及支持的接口；本小节将介绍各个文件系统以及支持的ioctl对应的cmd命令，ioctl具体接口请查看《3.13函数说明》；

2.1.1. sydfs文件系统

Sydfs是系统数据运行的 只读文件系统 ，可以通过sdk的download工具来下载存放资源文件，并于系统运行时读取；该文件系统能使用的接口图1.1所示：

图1.1 syd 文件系统接口
其中ioctl支持的cmd命令有：
①FS_IOCTL_FILE_TOTAL:
示例：
    int file_total;
    vfs_ioctl(pfile, FS_IOCTL_FILE_TOTAL, (int)&file_total);
    file_total即为pfile文件所在文件系统的总文件数；
②FS_IOCTL_FS_TOTAL:
示例：
    int file_total;
    vfs_ioctl(pfs, FS_IOCTL_FILE_TOTAL, (int)&file_total);
    file_total即为pfs文件系统的总文件数；
③FS_IOCTL_FILE_ATTR:
示例：
    struct vfs_attr attr;
    vfs_ioctl(pfile, FS_IOCTL_FILE_ATTR, (int)&attr);
    attr即可获取pfile文件的位置和大小；
注意：通过ioctl获取的文件位置仅为该pfile文件在其上层目录下的相对偏移；若要获取该文件相对于flash的偏移地址，需要调用vfs_get_fsize()；

2.1.2. norfs文件系统

Norfs是一个循环管理的可读写文件系统，内部空间环形管理，空间不足时新写入的文件会覆盖之前的文件；norfs文件系统只通过文件号进行管理，创建新文件后文件号会累加；一般在录音时使用；该文件系统能使用的接口如图所示：

图1.2 norfs文件系统支持的接口
其中ioctl支持的cmd命令有：
①FS_IOCTL_FILE_TOTAL，同上

②FS_IOCTL_FS_TOTAL，同上

③FS_IOCTL_FILE_ATTR，同上

④FS_IOCTL_FILE_SYNC:
示例：
    u32 flen = 0;
    vfs_ioctl(pfile, FS_IOCTL_FILE_SYNC, (int)&flen);
    该命令一般在录音结束时调用，用于更新norfs录音文件头，flen传入时为需要舍弃的录音末尾字节数，调用结束后会flen会被赋值为录音文件的字节数；
④FS_IOCTL_FILE_INDEX:
示例：
    int file_index;
    vfs_ioctl(pfile, FS_IOCTL_FILE_INDEX, (int)&file_index);
    file_index即为pfile文件所在norfs文件系统的最新文件序号；
⑤FS_IOCTL_FS_INDEX:
示例：
    int file_index;
    vfs_ioctl(pfs, FS_IOCTL_FS_INDEX, (int)&file_index);
    file_index即为pfs所指的norfs文件系统的最新文件序号；

2.1.3. fat文件系统

FatFs是一个通用的文件系统，在本机中，支持对FAT12/16/32、exFAT文件系统进行读写操作，FAT文件系统能使用的接口如图1.3所示：

图1.3 fat文件系统支持的接口

2.2. 文件系统使用一般流程

如图，fs运行大致流程如下；

图2.1 fs 运行大致流程

文件系统的流程

调用函数void fs_init(void)，完成对所有文件系统驱动的初始化；
调用u32 fs_mount(void **ppvfs, void *device, void *type)，传递指定设备句柄，并完成对具体文件系统的挂载，并获取文件系统的句柄；
调用u32 fs_openbypath(void *pvfs, void **ppvfile, const char *path)或u32 fs_select(void *fsn, void *pfs, int sel_mode, void **ppfile, int arg)打开文件，并获取文件句柄；
调用u32 fs_read(void *pvfile, void *buf, u32 len)对文件进行读操作；
调用int fs_ioctl(void *pvfile, int cmd, int arg)使用不同的命令进行不同的操作，如获取文件号、获取文件总数、获取文件地址、获取文件名字等；
调用u32 fs_file_close(void **ppvfile)关闭文件，并释放文件句柄。
调用u32 fs_fs_close(void **ppvfs)关闭文件系统，并释放文件系统句柄。
可以通过调用接口得到的返回值查看是否调用成功，以及失败的原因；失败原因可在include_lib/common/errno-base.h中查看。

可以通过调用接口得到的返回值查看是否调用成功，以及失败的原因；失败原因可在include_lib/common/errno-base.h中查看。

2.3. 通用文件系统管理函数

通用文件系统管理函数将介绍sydfs、norfs、fatfs通用的接口，各文件系统具体能使用哪些接口请查看是上面几张图片，下一小节将介绍fatfs独有的相关文件系统接口；

2.3.1. 函数void fs_init(void)

此函数实现对所有文件系统驱动的初始化；在开机第一次调用即可。

2.3.2. 函数u32 fs_mount(void **ppvfs, void device, void type)

此函数实现对指定设备挂在指定类型的文件系统，所挂载的系统必须设备自身支持；其中参数：

1、ppvfs：文件系统句柄指针，若句柄指向为NULL，函数会自行申请空间；
2、device：设备句柄；
3、type：文件系统类型的字符串；
    ①　“fat”：挂载fat文件系统；
4、返回值：
    成功 0；
    失败 错误请查看errno-base.h。
示例1：
    void *device = device_open(SD0_INDEX);//获取SD卡设备句柄
    void *pfs = NULL;
    u32 err = fs_mount(&pfs, device, “fat”); //SD卡挂载fatfs系统
    if (pfs != NULL && err == 0) {
    //SD卡挂载fatfs成功
    }
    示例2：        void *device = device_open(UDISK_INDEX);//获取U盘卡设备句柄
    void *pfs = NULL;
    u32 err = vfs_mount(&pfs, device, “fat”); //U盘挂载fatfs系统
    if (pfs != NULL && err == 0) {
    //U盘挂载fatfs成功
    }

2.3.3. 函数u32 fs_openbypath(void *pvfs, void **ppvfile, const char *path)

此函数实现打开指定路径的文件，其中参数：

1、pvfs：已挂载的文件系统句柄；
2、ppvfile：文件句柄指针，若句柄指向为NULL，函数会自行申请空间；
3、path：路径字符串；
    ①　如果字符串只是包含文件夹名，那么会打开文件夹；
    ②　如果字符串里面包含了完成的文件名，那么会同时包含文件名！
    ③　如果字符串为空，则返回错误；
4、返回值：成功 0；
失败 错误请查看errno-base.h。
示例：
    void *pfile = NULL;
    u32 err = vfs_openbypath(pfs, &pfile, “dir_song/so001.f1a”);
    if (pfile != NULL && err == 0) {
    //成功打开dir_song文件夹里的so001.f1a文件
    }

2.3.4. 函数u32 fs_read(void pvfile, void buf, u32 len)

此函数实现对指定文件的读操作。其中参数：

1、pvfile：已打开的文件句柄；
2、buf：数据buff；
3、len：需要读取的字节长度；
4、返回值：
    成功 读取的字节数；
    失败 0。
示例：
    u8 read_buf[32];
    u32 read_len = fs_read(pfile, (void *)read_buf, 32);
    if (read_len != 0) {
    //成功读取pfile中read_len长度的数据到read_buf里
    }

2.3.5. 函数u32 fs_seek(void *pvfile, u32 offset, u32 mode)

此函数实现改变指定文件中读写指针的偏移。其中参数：

1、pvfile：已打开的文件句柄；
2、offset：偏移量；
3、mode：seek模式选择。如图3.1，seek模式有3种，分别为：
    ①　SEEK_SET：从文件起始位置开始向后偏移，首先会判断偏移量是否大于文件长度，若小于则使文件读写指针rw_p = offset；
    ②　SEEK_CIR：从文件读写指针位置开始向后偏移，使rw_p = rw_p + offset；
    ③　SEEK_END：从文件末尾位置向前偏移，首先会判断偏移量是否大于文件长度，若小于则使rw_p = 文件长度 - offset；
4、返回值：0。

图3.1 seek模式选择

2.3.6. 函数u32 fs_file_close(void **ppvfile)

此函数实现关闭文件并释放句柄。其中参数：

1、ppvfile：已打开的文件句柄指针；
2、返回值：0。
示例：
    vfs_file_close(&pfile);
    if (pfile == NULL) {
    //成功关闭pfile文件
    }

2.3.7. 函数u32 fs_fs_close(void **ppvfs)

此函数实现关闭文件系统并释放相关句柄。其中参数：

1、ppvfs：已挂载的文件系统句柄指针；
2、返回值：NULL。
示例：
    fs_fs_close(&pfs);
    if (pfs == NULL) {
    //成功关闭pfs文件系统
    }

2.3.8. 函数u32 fs_file_name(void pvfile， void name, u32 len)

此函数实现获取指定文件句柄的文件名。其中参数：

1、pvfile：已打开的文件句柄；
2、name：存放文件名的buf；
3、len：获取文件名的长度；
4、返回值：成功 返回获取文件名的长度；

2.3.9. 函数int fs_get_attrs(void pvfile, void pvfs_attr)

此函数实现记录文件的属性，包括文件大小和地址，nor_fs无法使用此功能。其中参数：

1、pvfile：已打开的文件句柄；
2、pvfs_attr：文件系统属性，需要传入vfs_attr结构体类型的指针；
3、返回值：0。
示例：
    struct vfs_attr file_attr;
    fs_get_attrs(pfile, &file_attr);
    //文件地址和大小分别保存在file_attr.sclust和file_attr.fsize中

2.3.10. 函数int fs_ioctl(void *pvfile, int cmd, int arg)

此函数实现对指定文件的相关操作，各文件系统具体的cmd命令请查看《1文件系统介绍》小节。其中参数：
1、pvfile：已打开的文件句柄；
2、cmd：命令；
3、arg：参数；
4、返回值：
    成功 0；
    失败 错误请查看errno-base.h。

2.4. FAT文件系统管理函数

下面的函数为仅FAT使用的接口，在appbspcommonfsfatfat_resource.c中的fat_demo()接口，可以找到下列函数的使用示例；

2.4.1. 函数int fs_ftell(void pvfile, void parm)

此函数实现获取文件读写指针，仅FAT可使用该功能。其中参数：
1、pvfile：已打开的文件句柄；
2、param：用于保存文件系统读写指针；
3、返回值：
    成功 0；
    失败 错误请查看errno-base.h。

2.4.2. 函数int vfs_get_fsize(void pvfile, void parm)

此函数实现获取文件大小，仅FAT可使用该功能。其中参数：
1、      pvfile：已打开的文件句柄；
2、param：用于保存文件大小的指针；
3、返回值：
    成功 0；
    失败 错误请查看errno-base.h。

2.4.3. 函数struct vfscan vfs_fscan_new(void pvfs, const char path, const char arg, u8 max_deepth, int (callback)(void), strcut vfscan fsn, struct vfscan_reset_info *info)

此函数实现FAT文件系统的文件扫描配置，会返回文件扫描句柄供其他扫描接口使用，与vfs_fscan_release()搭配调用，可在ac104n sdk中的play_file.c中查看该函数具体使用示例。其中参数：

1、pvfs：已挂载的文件系统句柄；
2、path：文件扫描的起始路径；
3、arg：文件扫描配置参数；
    例：static const char scan_parm_test[] = “-t”
                                            “MP1MP2MP3WAVTXT”
                                            “ -sn -r”
                                            ;
    ①　首行”-t”表示需要扫描的文件类型，后面”MP1MP2MP3WAVTXT”即为扫描的后缀名，三个字符为一种类型，最多不可超过20种文件类型；
    ②　第三行” -sn”表示扫描文件的顺序是按照文件号排序，另一种组合” -st”表示按照时间排序；
    ③　第三行” -r”表示搜索会包含文件夹子目录；
    ④　各种扫描参数配置间，需要以空格隔开，其他配置有：
        a)扫描是否将文件夹算入总数，可配置” -d”；
        b)扫描只读文件配置” -ar”，扫描非读文件配置” -a/r”，不配置默认扫描所有文件；
4、max_deep：扫描深度，最大为8；
5、callback：扫描回调；
6、fsn：文件扫描句柄；
7、info：扫描结果信息，包含文件总数和文件夹总数等信息；
8、返回值：
    成功 返回文件扫描句柄；
    失败 错误请查看errno-base.h。

2.4.4. 函数void fs_fscan_release(void pvfs, struct vfscan fs)

此函数实现释放文件扫描句柄，仅FAT可使用该功能，与vfs_fscan()搭配调用。其中参数：
1、pvfs：已挂载的文件系统句柄；
2、fs：文件扫描句柄；
3、返回值：无。

2.4.5. 函数int fs_get_folderinfo(void **pvfile, struct vfscan fs, int start_num, int *end_num)

此函数实现文件夹扫描，需使用vfs_fscan()返回的文件扫描句柄，仅FAT可使用该功能。其中参数：

1、pvfile：需要扫描的设备里的文件；
2、fs：文件扫描句柄；
3、Start_num：用于保存第一个文件夹的第一个文件号；
4、End_num：用于保存最后一个文件夹的最后一个文件号；
5、返回值：
    成功 0；
    失败 错误请查看errno-base.h。

2.4.6. 函数int fs_get_encfolder_info(void pvfs, char folder, char ext, u32 last_num, u32 *total_num)

此函数实现获取录音文件夹信息，包括录音文件总数，仅FAT可使用该功能。其中参数：

1、      pvfs：已挂载的文件系统句柄；
2、folder：文件夹路径，如”/JL_REC”；
3、ext：录音文件的后缀名，如”MP3”；
4、last_num：第一个可以使用的录音文件的文件序号；
5、total_num：总录音文件数；
6、返回值：
    成功 0；
    失败 错误请查看errno-base.h。

2.4.7. 函数u32 fs_file_delete(void *pvfile)

此函数实现文件的删除，仅FAT可使用该功能。其中参数：
1、      pvfile：已打开的文件句柄；
2、返回值：成功 0；
失败 错误请查看errno-base.h。

2.4.8. 函数int fs_select(void *pvfs, void **ppvfile, struct vfscan *fs, int sel_mode, int arg)

此函数实现FAT文件系统的文件查找，支持多种查找方式，具体示例可查看fat_demo(void)接口。其中参数：

1、      pvfs：已挂载的文件系统句柄；
2、ppvfile：文件句柄指针，若句柄指向为NULL，函数会自行申请空间；
3、fs：文件扫描句柄；
4、sel_mode：文件查找方式：
    ①　FSEL_BY_NUMBER：按文件号查找；
    ②　FSEL_BY_SCLUST：按簇号查找；
    ③　FSEL_BY_PATH：按路径查找；
5、arg：文件查找参数；
    ①　按文件号查找时传入文件号；
    ②　按簇号查找时传入簇号；
    ③　按路径查找时传入相应路径，支持通配符查找；
6、返回值：
    成功 0；
    失败 错误请查看errno-base.h。

2.4.9. 函数int vfs_mk_dir(void pvfs, char folder, u8 mode)

此函数实现获取创建文件夹，仅FAT可使用该功能。其中参数：

1、pvfs：已挂载的文件系统句柄；
2、folder：文件夹路径，如”/JL_REC”；
3、mode：目录属性；
    ①　1：设置为隐藏属性；
    ②　0：不设置；
4、返回值：
    成功 0；
    失败 错误请查看errno-base.h。

2.4.10. 函数int vfs_get_encfolder_info(void pvfs, char folder, char ext, u32 last_num, u32 *total_num)

此函数实现获取录音文件夹信息，包括录音文件总数，仅FAT可使用该功能。其中参数：

1、pvfs：已挂载的文件系统句柄；
2、folder：文件夹路径，如”/JL_REC”；
3、ext：录音文件的后缀名，如”MP3”；
4、last_num：第一个可以使用的录音文件的文件序号；
5、total_num：总录音文件数；
6、返回值：
    成功 0；
    失败 错误请查看errno-base.h。

2.4.11. 函数u32 vfs_file_delete(void *pvfile)

此函数实现文件的删除，仅FAT可使用该功能。其中参数：
1、pvfile：已打开的文件句柄；
2、返回值：
    成功 0；
    失败 错误请查看errno-base.h。

2.4.12. 函数int vfs_select(void *pvfs, void **ppvfile, struct vfscan *fs, int sel_mode, int arg)