A comprehensive VFS FAT example

[kirillandy]

Hi all!
I'm currently studying the FAT FS support in IDF that I would like to use for my project and I really, really am lacking a solid example for what the docs describe. This is the page in question:

https://docs.espressif.com/projects/esp ... fatfs.html

In all of the examples I have been able to find, the all-encompassing esp_vfs_fat_spiflash_mount_rw_wl function is used, which does 4-5 things "for convenience".

Essentially, I would like to do everything that esp_vfs_fat_spiflash_mount_rw_wl does but step-by-step, in order to gain access to lower-level functions and control blocks. So that would mean manually mount WL, register+mount FAT, etc, but it's a little difficult to piece together how all these API layers come together, in what order they should be used, and which read/write/etc functions I will end up using for file operations.

I would like to get to a point where I use the native FAT functions if possible.

Also, some things are just not explained.

To illustrate:
The docs page describes a more detailed process for getting FAT started, using esp_vfs_fat_register, ff_diskio_register, and other stuff, but there are certain function arguments that aren't properly explained. For example, what is the expected "drive number" to pass to esp_vfs_fat_register, where can I find the function pointers to put into the ff_diskio_impl_t struct to pass to the ff_diskio_register function, etc....

I have read everything I could find on WL API, SPI Flash API, and other relevant pieces, but I would be very grateful if someone can provide a neat example where all the levels/features of esp_vfs_fat_spiflash_mount_rw_wl are explicitly set up/initialized/registered/launched/etc in order to get a FAT FS going.

Thank you in advance for any help and clarification!

[RathiSonika]

To address your question, here’s a step-by-step breakdown of how to manually set up and use the FAT filesystem on SPI Flash in ESP-IDF without relying on the convenience function esp_vfs_fat_spiflash_mount_rw_wl.
1. Initialize the SPI Flash Partition: You need to locate and initialize the partition where the FAT filesystem will reside. e.g use function

Code: Select all

esp_partition_find_first(ESP_PARTITION_TYPE_DATA, ESP_PARTITION_SUBTYPE_DATA_FAT, NULL)

2. Set Up Wear Leveling (Optional): If you want to use wear leveling, initialize the WL library for the selected partition
3. Register FATFS with VFS: Use esp_vfs_fat_register to register FAT with the ESP-IDF VFS layer. This connects the FATFS filesystem with standard POSIX file I/O functions like fopen, fwrite, etc.

Code: Select all

esp_vfs_fat_register(base_path, drive, wl_handle, &fs)

where, drive Number (drive):
• The drive string ("0:", "1:", etc.) is used by FATFS to differentiate storage devices.
• Start with "0:" unless you're dealing with multiple drives.
4. Register Disk I/O Implementation: You need to register the disk I/O callbacks that FATFS will use to interact with the storage. This is done using ff_diskio_register.

Code: Select all

ff_diskio_impl_t diskio_impl = { .init = your_disk_init_function, 
                                 .read = your_disk_read_function, 
                                 .write = your_disk_write_function, 
                                 .ioctl = your_disk_ioctl_function, }; 
ff_diskio_register(drive, &diskio_impl);

Replace your_disk_*_function with the appropriate implementations for your SPI Flash storage.
Function Pointers in ff_diskio_impl_t must be implemented to interact with your storage device.
For SPI Flash, you can use ESP-IDF's wear leveling layer to simplify this using ff_diskio_register_wl_partition(). ( Refer to the file components/fatfs/diskio/diskio_wl.c)

5. Mount the FAT Filesystem: After setting up the VFS and Disk I/O, mount the FAT filesystem using f_mount(fs, drive, 1);
6. Perform File Operations: You can now use standard POSIX or FATFS file operations. You can use native FAT functions like f_open(), f_close(), f_read(), f_write() as well.
7. Unmount the Filesystem: When you're done, clean up resources:

So mainly there are 4 layers to understand
VFS: Provides a POSIX-like interface for file operations.
FATFS: The actual FAT implementation.
Wear Leveling: A layer to manage flash-specific constraints.
SPI Flash API: Low-level SPI Flash read/write operations.

You can refer to the documentation:
https://docs.espressif.com/projects/esp ... fatfs.html
https://docs.espressif.com/projects/esp ... e/vfs.html
https://docs.espressif.com/projects/esp ... lling.html

[kirillandy]

Thanks @RathiSonica!
This will help out nicely!

Am I right in understanding that ff_diskio_register_wl_partition will register the read/write/etc SPI flash functions that are used by the WL level, i.e. it will populate a ff_diskio_impl_t structure with relevant functions and register them for me?

I do not think I have the .c files for these APIs so I can't take a closer look at what actually goes on. It would be very helpful though. I've only got the .h files, unless the source code files of these APIs are buried elsewhere in the ESP32 Arduino folder...

To summarize, essentially, the hierarchy here looks something like this: POSIX calls -> VFS -> FATFS -> WL API -> Flash API -> (maybe smth intermediary) -> Physical flash module, correct?

[RathiSonika]

Yes, that's correct. You can refer to the source code here https://github.com/espressif/esp-idf/bl ... o_wl.c#L84

[kirillandy]

Got it, the source will be invaluable to understanding what it is I will actually be doing. Thank you again for the guidance @RathiSonika!