fd7b794e81
This change allows readonly FATFS to be mounted without wear levelling support. This will provide the customers a simple way to mount FATFS images generated on host and flashed onto the chip during factory provisioning. Since NVS encryption is not supported yet and NVS entry size is limited, the change will provide an easy alternative for securing the provisioning data by just marking FATFS parition as encrypted.
70 lines
4.3 KiB
ReStructuredText
70 lines
4.3 KiB
ReStructuredText
FAT Filesystem Support
|
||
======================
|
||
|
||
ESP-IDF uses `FatFs <http://elm-chan.org/fsw/ff/00index_e.html>`_ library to work with FAT filesystems. FatFs library resides in ``fatfs`` component. Although it can be used directly, many of its features can be accessed via VFS using C standard library and POSIX APIs.
|
||
|
||
Additionally, FatFs has been modified to support run-time pluggable disk IO layer. This allows mapping of FatFs drives to physical disks at run-time.
|
||
|
||
Using FatFs with VFS
|
||
--------------------
|
||
|
||
:component_file:`fatfs/src/esp_vfs_fat.h` header file defines functions to connect FatFs with VFS. :cpp:func:`esp_vfs_fat_register` function allocates a ``FATFS`` structure, and registers a given path prefix in VFS. Subsequent operations on files starting with this prefix are forwarded to FatFs APIs. :cpp:func:`esp_vfs_fat_unregister_path` function deletes the registration with VFS, and frees the ``FATFS`` structure.
|
||
|
||
Most applications will use the following flow when working with ``esp_vfs_fat_`` functions:
|
||
|
||
1. Call :cpp:func:`esp_vfs_fat_register`, specifying path prefix where the filesystem has to be mounted (e.g. ``"/sdcard"``, ``"/spiflash"``), FatFs drive number, and a variable which will receive a pointer to ``FATFS`` structure.
|
||
|
||
2. Call :cpp:func:`ff_diskio_register` function to register disk IO driver for the drive number used in step 1.
|
||
|
||
3. Call FatFs ``f_mount`` function (and optionally ``f_fdisk``, ``f_mkfs``) to mount the filesystem using the same drive number which was passed to :cpp:func:`esp_vfs_fat_register`. See `FatFs documentation for more details <http://www.elm-chan.org/fsw/ff/doc/mount.html>`.
|
||
|
||
4. Call POSIX and C standard library functions to open, read, write, erase, copy files, etc. Use paths starting with the prefix passed to :cpp:func:`esp_vfs_register` (such as ``"/sdcard/hello.txt"``).
|
||
|
||
5. Optionally, call FatFs library functions directly. Use paths without a VFS prefix in this case (``"/hello.txt"``).
|
||
|
||
6. Close all open files.
|
||
|
||
7. Call FatFs ``f_mount`` function for the same drive number, with NULL ``FATFS*`` argument, to unmount the filesystem.
|
||
|
||
8. Call FatFs :cpp:func:`ff_diskio_register` with NULL ``ff_diskio_impl_t*`` argument and the same drive number.
|
||
|
||
9. Call :cpp:func:`esp_vfs_fat_unregister_path` with the path where the file system is mounted to remove FatFs from VFS, and free the ``FATFS`` structure allocated on step 1.
|
||
|
||
Convenience functions, ``esp_vfs_fat_sdmmc_mount`` and ``esp_vfs_fat_sdmmc_unmount``, which wrap these steps and also handle SD card initialization, are described in the next section.
|
||
|
||
.. doxygenfunction:: esp_vfs_fat_register
|
||
.. doxygenfunction:: esp_vfs_fat_unregister_path
|
||
|
||
|
||
Using FatFs with VFS and SD cards
|
||
---------------------------------
|
||
|
||
:component_file:`fatfs/src/esp_vfs_fat.h` header file also provides a convenience function to perform steps 1–3 and 7–9, and also handle SD card initialization: :cpp:func:`esp_vfs_fat_sdmmc_mount`. This function does only limited error handling. Developers are encouraged to look at its source code and incorporate more advanced versions into production applications. :cpp:func:`esp_vfs_fat_sdmmc_unmount` function unmounts the filesystem and releases resources acquired by :cpp:func:`esp_vfs_fat_sdmmc_mount`.
|
||
|
||
.. doxygenfunction:: esp_vfs_fat_sdmmc_mount
|
||
.. doxygenstruct:: esp_vfs_fat_mount_config_t
|
||
:members:
|
||
.. doxygenfunction:: esp_vfs_fat_sdmmc_unmount
|
||
|
||
|
||
Using FatFs with VFS in read-only mode
|
||
--------------------------------------
|
||
|
||
Convenience functions, :cpp:func:`esp_vfs_fat_rawflash_mount` and :cpp:func:`esp_vfs_fat_rawflash_unmount`, are provided by :component_file:`fatfs/src/esp_vfs_fat.h` header file in order to perform steps 1-3 and 7-9 for read-only FAT partitions. These are particularly helpful for data partitions written only once during factory provisioning and need not be changed by production application throughout the lifetime.
|
||
|
||
.. doxygenfunction:: esp_vfs_fat_rawflash_mount
|
||
.. doxygenfunction:: esp_vfs_fat_rawflash_unmount
|
||
|
||
FatFS disk IO layer
|
||
-------------------
|
||
|
||
FatFs has been extended with an API to register disk IO driver at runtime.
|
||
|
||
Implementation of disk IO functions for SD/MMC cards is provided. It can be registered for the given FatFs drive number using :cpp:func:`ff_diskio_register_sdmmc` function.
|
||
|
||
.. doxygenfunction:: ff_diskio_register
|
||
.. doxygenstruct:: ff_diskio_impl_t
|
||
:members:
|
||
.. doxygenfunction:: ff_diskio_register_sdmmc
|
||
|