FAT 文件系统的支持¶
ESP-IDF 使用 FatFs 库作为 FAT 文件系统。FatFs 库位于 fatfs
组件内。尽管它可以被直接访问,它的许多功能都可以通过 VFS 访问,即使用标准 C 库和 POSIX API。
此外,FatFs 已被修改,支持运行时可插拔磁盘 IO 层。这能让 FatFs 在运行时映射为物理磁盘。
FatFs with VFS¶
头文件 esp_vfs_fat.h
中定义的函数可以将 FatFs 与 VFS 连接起来。函数 esp_vfs_fat_register
分配了一个 FATFS
结构,并在 VSF 中注册了一个所给路径前缀。随后对以这个前缀作为开始的文件的操作将会被转发给 FatFs 的 API。函数 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:
- Call
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 toFATFS
structure. - Call
ff_diskio_register
function to register disk IO driver for the drive number used in step 1. - Call
f_mount
function (and optionallyf_fdisk
,f_mkfs
) to mount the filesystem using the same drive number which was passed toesp_vfs_fat_register
. See FatFs documentation for more details. - Call POSIX and C standard library functions to open, read, write, erase, copy files, etc. Use paths starting with the prefix passed to
esp_vfs_register
(such as"/sdcard/hello.txt"
). - Optionally, call FatFs library functions directly. Use paths without a VFS prefix in this case (
"/hello.txt"
). - Close all open files.
- Call
f_mount
function for the same drive number, with NULLFATFS*
argument, to unmount the filesystem. - Call
ff_diskio_register
with NULLff_diskio_impl_t*
argument and the same drive number. - Call
esp_vfs_fat_unregister_path
with the path where the file system is mounted to remove FatFs from VFS, and free theFATFS
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.
-
esp_err_t
esp_vfs_fat_register
(const char *base_path, const char *fat_drive, size_t max_files, FATFS **out_fs)¶ Register FATFS with VFS component.
This function registers given FAT drive in VFS, at the specified base path. If only one drive is used, fat_drive argument can be an empty string. Refer to FATFS library documentation on how to specify FAT drive. This function also allocates FATFS structure which should be used for f_mount call.
- Note
- This function doesn’t mount the drive into FATFS, it just connects POSIX and C standard library IO function with FATFS. You need to mount desired drive into FATFS separately.
- Return
- ESP_OK on success
- ESP_ERR_INVALID_STATE if esp_vfs_fat_register was already called
- ESP_ERR_NO_MEM if not enough memory or too many VFSes already registered
- Parameters
base_path
: path prefix where FATFS should be registeredfat_drive
: FATFS drive specification; if only one drive is used, can be an empty stringmax_files
: maximum number of files which can be open at the same timeout_fs
: pointer to FATFS structure which can be used for FATFS f_mount call is returned via this argument.
-
esp_err_t
esp_vfs_fat_unregister_path
(const char *base_path)¶ Un-register FATFS from VFS.
- Note
- FATFS structure returned by esp_vfs_fat_register is destroyed after this call. Make sure to call f_mount function to unmount it before calling esp_vfs_fat_unregister_ctx. Difference between this function and the one above is that this one will release the correct drive, while the one above will release the last registered one
- Return
- ESP_OK on success
- ESP_ERR_INVALID_STATE if FATFS is not registered in VFS
- Parameters
base_path
: path prefix where FATFS is registered. This is the same used when esp_vfs_fat_register was called
Using FatFs with VFS and SD cards¶
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: 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. esp_vfs_fat_sdmmc_unmount
function unmounts the filesystem and releases resources acquired by esp_vfs_fat_sdmmc_mount
.
-
esp_err_t
esp_vfs_fat_sdmmc_mount
(const char *base_path, const sdmmc_host_t *host_config, const sdmmc_slot_config_t *slot_config, const esp_vfs_fat_mount_config_t *mount_config, sdmmc_card_t **out_card)¶ Convenience function to get FAT filesystem on SD card registered in VFS.
This is an all-in-one function which does the following:
- initializes SD/MMC peripheral with configuration in host_config
- initializes SD/MMC card with configuration in slot_config
- mounts FAT partition on SD/MMC card using FATFS library, with configuration in mount_config
- registers FATFS library with VFS, with prefix given by base_prefix variable
This function is intended to make example code more compact. For real world applications, developers should implement the logic of probing SD card, locating and mounting partition, and registering FATFS in VFS, with proper error checking and handling of exceptional conditions.
- Return
- ESP_OK on success
- ESP_ERR_INVALID_STATE if esp_vfs_fat_sdmmc_mount was already called
- ESP_ERR_NO_MEM if memory can not be allocated
- ESP_FAIL if partition can not be mounted
- other error codes from SDMMC host, SDMMC protocol, or FATFS drivers
- Parameters
base_path
: path where partition should be registered (e.g. “/sdcard”)host_config
: pointer to structure describing SDMMC hostslot_config
: pointer to structure with extra SDMMC slot configurationmount_config
: pointer to structure with extra parameters for mounting FATFSout_card
: if not NULL, pointer to the card information structure will be returned via this argument
-
struct
esp_vfs_fat_mount_config_t
¶ Configuration arguments for esp_vfs_fat_sdmmc_mount and esp_vfs_fat_spiflash_mount functions.
-
esp_err_t
esp_vfs_fat_sdmmc_unmount
()¶ Unmount FAT filesystem and release resources acquired using esp_vfs_fat_sdmmc_mount.
- Return
- ESP_OK on success
- ESP_ERR_INVALID_STATE if esp_vfs_fat_sdmmc_mount hasn’t been called
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 ff_diskio_register_sdmmc
function.
-
void
ff_diskio_register
(BYTE pdrv, const ff_diskio_impl_t *discio_impl)¶ Register or unregister diskio driver for given drive number.
When FATFS library calls one of disk_xxx functions for driver number pdrv, corresponding function in discio_impl for given pdrv will be called.
- Parameters
pdrv
: drive numberdiscio_impl
: pointer to ff_diskio_impl_t structure with diskio functions or NULL to unregister and free previously registered drive
-
struct
ff_diskio_impl_t
¶ Structure of pointers to disk IO driver functions.
See FatFs documentation for details about these functions
Public Members
-
DSTATUS (*
init
)(BYTE pdrv)¶ disk initialization function
-
DSTATUS (*
status
)(BYTE pdrv)¶ disk status check function
-
DRESULT (*
read
)(BYTE pdrv, BYTE *buff, DWORD sector, UINT count)¶ sector read function
-
DRESULT (*
write
)(BYTE pdrv, const BYTE *buff, DWORD sector, UINT count)¶ sector write function
-
DRESULT (*
ioctl
)(BYTE pdrv, BYTE cmd, void *buff)¶ function to get info about disk and do some misc operations
-
DSTATUS (*
-
void
ff_diskio_register_sdmmc
(BYTE pdrv, sdmmc_card_t *card)¶ Register SD/MMC diskio driver
- Parameters
pdrv
: drive numbercard
: pointer to sdmmc_card_t structure describing a card; card should be initialized before calling f_mount.