espressif/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2026-04-27 11:03:11 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(storage/fatfs): Update LFN default and dynamic buffers docs

Browse Source
This commit is contained in:
Tomáš Rohlínek
2026-03-04 10:42:23 +01:00
committed by Zhang Shuxian
parent 1ec13a92d2
commit a07d018409
1 changed files with 2 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/en/api-reference/storage/fatfs.rst
+2 -1
View File
@@ -31,7 +31,7 @@ Most applications use the following workflow when working with ``esp_vfs_fat_``
#. To mount the filesystem using the same drive number which was passed to :cpp:func:`esp_vfs_fat_register`, call the FatFs function :cpp:func:`f_mount`. If the filesystem is not present on the target logical drive, :cpp:func:`f_mount` will fail with the ``FR_NO_FILESYSTEM`` error. In such case, call :cpp:func:`f_mkfs` to create a fresh FatFS structure on the drive first, and then call :cpp:func:`f_mount` again. Note that SD cards need to be partitioned with :cpp:func:`f_fdisk` prior to previously described steps. For more information, see `FatFs documentation <http://elm-chan.org/fsw/ff/doc/mount.html>`_.
#. 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 :cpp:func:`esp_vfs_register` (for example, ``"/sdcard/hello.txt"``). The filesystem uses `8.3 filenames <https://en.wikipedia.org/wiki/8.3_filename>`_ format (SFN) by default. If you need to use long filenames (LFN), enable the :ref:`CONFIG_FATFS_LONG_FILENAMES` option. Please refer to `FatFs filenames <http://elm-chan.org/fsw/ff/doc/filename.html>`_ for more details.
#. 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 :cpp:func:`esp_vfs_register` (for example, ``"/sdcard/hello.txt"``). The filesystem supports long filenames (LFN) by default. If you want to reduce memory usage and avoid LFN working buffers, set :ref:`CONFIG_FATFS_LFN_NONE` (this limits names to the `8.3 format <https://en.wikipedia.org/wiki/8.3_filename>`_, SFN only). Please refer to `FatFs filenames <http://elm-chan.org/fsw/ff/doc/filename.html>`_ for more details.
#. Optionally, call the FatFs library functions directly. In this case, use paths without a VFS prefix, for example, ``"/hello.txt"``.
@@ -72,6 +72,7 @@ Configuration options
The following configuration options are available for the FatFs component:
* :ref:`CONFIG_FATFS_ALLOC_PREFER_ALIGNED_WORK_BUFFERS` - If enabled, FatFs tries to allocate its heap work buffers in DMA-capable, cache-aligned memory first so SDMMC transfers can avoid extra copies. This is useful on targets using PSRAM with SDMMC DMA (for example ESP32-P4). If enabled together with :ref:`CONFIG_FATFS_ALLOC_PREFER_EXTRAM`, FatFs will try DMA-capable RAM first, then external RAM, then internal RAM.
* :ref:`CONFIG_FATFS_USE_DYN_BUFFERS` - If enabled, FatFs allocates instance buffers separately, sized according to each mounted volume's sector size. This is useful when multiple FatFs instances use different sector sizes and can reduce memory usage. If disabled, all instances use buffers sized for the largest configured sector size.
* :ref:`CONFIG_FATFS_USE_FASTSEEK` - If enabled, the POSIX :cpp:func:`lseek` function will be performed faster. The fast seek does 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.
* :ref:`CONFIG_FATFS_IMMEDIATE_FSYNC` - If enabled, the FatFs will automatically call :cpp:func:`f_sync` to flush recent file changes after each call of :cpp:func:`write`, :cpp:func:`pwrite`, :cpp:func:`link`, :cpp:func:`truncate` and :cpp:func:`ftruncate` functions. This feature improves file-consistency and size reporting accuracy for the FatFs, at a price of decreased performance due to frequent disk operations.
* :ref:`CONFIG_FATFS_LINK_LOCK` - If enabled, this option guarantees the API thread safety, while disabling this option might be necessary for applications that require fast frequent small file operations (e.g., logging to a file). Note that if this option is disabled, the copying performed by :cpp:func:`link` will be non-atomic. In such case, using :cpp:func:`link` on a large file on the same volume in a different task is not guaranteed to be thread safe.