.. _vfs-based_applications:

基于虚拟文件系统(VFS)的应用开发
================================

为了更好地支持SPV1x对于外置存储介质（如外置数据SPI Nor Flash和SPI SD/TF卡）的访问，
并将获得的数据用于SPV1x配套音频解码库输入，SPV1x SDK提供了相应的软件配套。

.. note::

    - 单纯使用SPV1x内置flash(定义为通过Nor控制器直连的flash)的场景搭建，请使用非VFS流程，获得最佳性能。
    - 目前只有音频解码播放库支持VFS方式使用，录音库/离线语音识别/MIDI库暂不支持VFS。

VFS应用框架
----------------------

.. image:: ../_static/kiwi-vfs-sys-flow.png
  :align: center

说明
-------------------------

  - 物理存储介质的驱动，需要实现实体文件系统的文件操作方式，后挂载到虚拟文件系统上，库通过调用虚拟文件系统接口，实现对介质的访问。
  - 同一时刻只能访问单个文件夹中单个文件

API
-------------------------

.. c:enum:: vfs_err_t

 文件系统错误码

    - *VFS_EOK*: 正确
    - *VFS_ERROR*: 存在错误

.. c:enum:: vfs_type_t

  已支持文件系统类型

   - *VFS_Type_None*: 表示无文件系统
   - *VFS_Type_Flash*: 表示内置cpu可直接地址方式访问flash文件系统
   - *VFS_Type_SDC*: 表示sd卡文件系统
   - *VFS_Type_Spiflash*: 表示spi驱动小于16Mbyteflash文件系统
   - *VFS_Type_Ospiflash*: 表示spi驱动大于16Mbyteflash文件系统
   - *VFS_Type_SDC_Direct*: 表示sd卡访问，以类似flash方式访问的文件系统


.. c:struct:: vfs_dir_t

  文件夹信息

    .. c:member:: uint16_t index

      文件序号
    
    .. c:member:: uint8_t* fn

      文件名地址

    .. c:member:: uint32_t sclust 

      开始簇地址，fat32使用

    .. c:member:: uint32_t clust 

      当前簇地址，fat32使用

    .. c:member:: uint32_t sect 

      当前簇中块序号，fat32使用


.. c:struct:: vfs_filinfo_t

  打开文件信息

    .. c:member:: uint32_t fsize 

      文件大小

    .. c:member:: uint16_t fdate 

      文件日期

    .. c:member:: uint16_t ftime 

      文件时间

    .. c:member:: uint8_t fattrib

      文件属性 

    .. c:member:: char fname[25]

      文件名 


.. c:struct:: vfs_t

  虚拟文件系统实体
 
    .. c:member:: vfs_err_t (*init)()

      挂载物理介质的初始化函数实体

    .. c:member:: vfs_err_t (*open)(char* filename)

      挂载文件打开

    .. c:member:: int32_t (*read)(void* buffer,int32_t size)

      挂载文件读取

    .. c:member:: vfs_err_t (*write)(void* buffer,int32_t size)

      挂载文件写

    .. c:member:: vfs_err_t (*lseek)(int32_t offset,int32_t fromwhere)

      挂载文件光标位置修改

    .. c:member:: int32_t (*size)()

      挂载获取文件大小

    .. c:member:: int32_t (*tell)()

      挂载获取文件光标位置

    .. c:member:: vfs_err_t (*opendir)(vfs_dir_t* dj,const char* path)

      挂载打开文件夹

    .. c:member:: vfs_err_t (*readdir)(vfs_dir_t* dj,vfs_filinfo_t* fno)

      挂载打开已打开文件夹下文件

    .. c:member:: player_file_attribute_t (*get_file_attribute)()

      挂载已打开获取文件属性


.. c:function:: vfs_err_t vfs_register(vfs_t *dev_vfs,vfs_type_t use_file_type)

  注册文件系统的接口

    :param dev_vfs: 接口信息指针
    :param use_file_type: 所使用文件系统类型
    :retval VFS_EOK: 成功
    :retval other: 失败

.. c:function:: vfs_type_t vfs_get_current_file_type()

  获取当前打开文件系统类型

    :retval : 参看 vfs_type_t

.. c:function:: vfs_err_t vfs_init()

  接口初始化

    :retval VFS_EOK: 成功
    :retval other: 失败

.. c:function:: vfs_err_t vfs_open(char* filename)

  打开文件

    :param filename: 当前文件夹下，需打开文件的文件名，支持播放文件后缀参看 player_file_attribute_t
    :retval VFS_EOK: 成功
    :retval other: 失败

.. c:function:: int32_t vfs_read(void* buffer,int32_t size)

  从打开文件中读取数据

    :param buffer: 读取数据缓存空间的首地址
    :param size: 读取数据长度，单位byte
    :retval int32_t: 实际读取到的数据长度
    :note: 读数之前需要确保文件打开，否则数据读取错误，函数不检测文件是否打开

.. c:function:: vfs_err_t vfs_write(void* buffer,int32_t size)

  将数据写入已打开文件

    :param buffer: 写入数据缓存空间的首地址
    :param size: 写入数据长度，单位byte
    :retval VFS_EOK: 成功
    :retval other: 失败

.. c:function:: vfs_err_t vfs_lseek(int32_t offset,int32_t fromwhere)

  设置文件当前访问的位置偏移

    :param offset: 相对位置偏移
    :param fromwhere: 相对偏移的起始位置，SEEK_SET 相对文件开始位置，SEEK_CUR 相对当前位置，SEEK_END 相对文件结束位置
    :retval VFS_EOK: 成功
    :retval other: 失败

.. c:function:: int32_t vfs_size()

  读取文件大小

    :retval : 文件大小，单位byte

.. c:function:: int32_t vfs_tell()

  访问文件当前偏移

    :retval : 文件当前偏移

.. c:function:: vfs_err_t vfs_opendir(vfs_dir_t* dj,const char* path)

  打开指定文件夹

    :param dj: 存放文件夹信息的指针 vfs_dir_t 类型 
    :param path: 文件夹名
    :retval VFS_EOK: 成功
    :retval other: 失败

.. c:function:: vfs_err_t vfs_readdir(vfs_dir_t* dj,vfs_filinfo_t* fno)

  读取已打开文件夹中的文件

    :param dj: 已打开文件夹信息的指针 vfs_dir_t类型
    :param fno: 文件信息指针 vfs_filinfo_t类型
    :retval VFS_EOK: 成功
    :retval other: 失败

.. c:function:: player_file_attribute_t vfs_get_file_attribute()

  读已打开文件属性

    :retval: 文件属性

使用方法
-------------------------

  1. 调用vfs_register()注册文件系统；
  2. 调用vfs_init()初始化文件系统；
  3. 正常使用vfs_xxx()函数访问文件。

示例应用
-------------------------
参看sdk下templates文件夹中带有vfs名称的工程