Skip to content

Latest commit

 

History

History
86 lines (51 loc) · 5.5 KB

fatfs.rst

File metadata and controls

86 lines (51 loc) · 5.5 KB
Raw

FAT Filesystem Support

:link_to_translation:zh_CN:[中文]

ESP-IDF uses the FatFs library to work with FAT filesystems. FatFs resides in the fatfs component. Although the library can be used directly, many of its features can be accessed via VFS, using the C standard library and POSIX API functions.

Additionally, FatFs has been modified to support the runtime pluggable disk I/O layer. This allows mapping of FatFs drives to physical disks at runtime.

Using FatFs with VFS

The header file :component_file:`fatfs/vfs/esp_vfs_fat.h` defines the functions for connecting FatFs and VFS.

The function :cppesp_vfs_fat_register 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. The function :cppesp_vfs_fat_unregister_path deletes the registration with VFS, and frees the FATFS structure.

Most applications use the following workflow when working with esp_vfs_fat_ functions:

  1. Call :cppesp_vfs_fat_register to specify:
    • Path prefix where to mount the filesystem (e.g. "/sdcard", "/spiflash")
    • FatFs drive number
    • A variable which will receive the pointer to the FATFS structure
  2. Call :cppff_diskio_register to register the disk I/O driver for the drive number used in Step 1.
  3. Call the FatFs function f_mount, and optionally f_fdisk, f_mkfs, to mount the filesystem using the same drive number which was passed to :cppesp_vfs_fat_register. For more information, see FatFs documentation.
  4. Call the C standard library and POSIX API functions to perform such actions on files as open, read, write, erase, copy, etc. Use paths starting with the path prefix passed to :cppesp_vfs_register (for example, "/sdcard/hello.txt"). The filesystem uses 8.3 filenames format (SFN) by default. If you need to use long filenames (LFN), enable the CONFIG_FATFS_LONG_FILENAMES option. More details on the FatFs filenames are available here.
  5. Optionally, by enabling the option CONFIG_FATFS_USE_FASTSEEK, use the POSIX lseek function to perform it faster, the fast seek will not work for files in write mode, so to take advantage of fast seek, you should open (or close and then reopen) the file in read-only mode.
  6. Optionally, call the FatFs library functions directly. In this case, use paths without a VFS prefix (for example, "/hello.txt").
  7. Close all open files.
  8. Call the FatFs function f_mount for the same drive number, with NULL FATFS* argument, to unmount the filesystem.
  9. Call the FatFs function :cppff_diskio_register with NULL ff_diskio_impl_t* argument and the same drive number to unregister the disk I/O driver.
  10. Call :cppesp_vfs_fat_unregister_path with the path where the file system is mounted to remove FatFs from VFS, and free the FATFS structure allocated in Step 1.

The convenience functions esp_vfs_fat_sdmmc_mount, esp_vfs_fat_sdspi_mount and esp_vfs_fat_sdcard_unmount wrap the steps described above and also handle SD card initialization. These two functions are described in the next section.

esp_vfs_fat_register

esp_vfs_fat_unregister_path

Using FatFs with VFS and SD cards

The header file :component_file:`fatfs/vfs/esp_vfs_fat.h defines convenience functions :cpp:func:`esp_vfs_fat_sdmmc_mount, :cppesp_vfs_fat_sdspi_mount and :cppesp_vfs_fat_sdcard_unmount. These function perform Steps 1–3 and 7–9 respectively and handle SD card initialization, but provide only limited error handling. Developers are encouraged to check its source code and incorporate more advanced features into production applications.

The convenience function :cppesp_vfs_fat_sdmmc_unmount unmounts the filesystem and releases the resources acquired by :cppesp_vfs_fat_sdmmc_mount.

esp_vfs_fat_sdmmc_mount

esp_vfs_fat_sdspi_mount

esp_vfs_fat_mount_config_t

esp_vfs_fat_sdcard_unmount

Using FatFs with VFS in read-only mode

The header file :component_file:`fatfs/vfs/esp_vfs_fat.h also defines the convenience functions :cpp:func:`esp_vfs_fat_rawflash_mount and :cppesp_vfs_fat_rawflash_unmount. These functions perform Steps 1-3 and 7-9 respectively for read-only FAT partitions. These are particularly helpful for data partitions written only once during factory provisioning which will not be changed by production application throughout the lifetime of the hardware.

esp_vfs_fat_rawflash_mount

esp_vfs_fat_rawflash_unmount

FatFS disk IO layer

FatFs has been extended with API functions that register the disk I/O driver at runtime.

They provide implementation of disk I/O functions for SD/MMC cards and can be registered for the given FatFs drive number using the function :cppff_diskio_register_sdmmc.

ff_diskio_register

ff_diskio_impl_t

ff_diskio_register_sdmmc

ff_diskio_register_wl_partition

ff_diskio_register_raw_partition