Merge branch 'feature/sd_perf_uplift' into 'master'

fatfs: fstat - enable setting a custom preferred block size

Closes IDF-6978

See merge request espressif/esp-idf!22522

components/fatfs/Kconfig

@@ -216,4 +216,18 @@ menu "FAT Filesystem support"
             This value should be chosen based on prior knowledge of
             maximum elements of each file entry would store.
 
+    config FATFS_VFS_FSTAT_BLKSIZE
+        int "Default block size"
+        default 0
+        help
+            If set to 0, the 'newlib' library's default size (BLKSIZ) is used (128 B).
+            If set to a non-zero value, the value is used as the block size.
+            Default file buffer size is set to this value
+            and the buffer is allocated when first attempt of reading/writing to a file is made.
+            Increasing this value improves fread() speed, however the heap usage is increased as well.
+
+            NOTE: The block size value is shared by all the filesystem functions
+            accessing target media for given file descriptor!
+            See 'Improving I/O performance' section of 'Maximizing Execution Speed' documentation page
+            for more details.
 endmenu

components/fatfs/vfs/vfs_fat.c

@@ -600,6 +600,7 @@ static int vfs_fat_fstat(void* ctx, int fd, struct stat * st)
     st->st_mtime = 0;
     st->st_atime = 0;
     st->st_ctime = 0;
+    st->st_blksize = CONFIG_FATFS_VFS_FSTAT_BLKSIZE;
     return 0;
 }
 

docs/en/api-guides/performance/speed.rst

@@ -240,3 +240,20 @@ Improving Network Speed
     :SOC_WIFI_SUPPORTED: * For Wi-Fi, see :ref:`How-to-improve-Wi-Fi-performance` and :ref:`wifi-buffer-usage`
     * For lwIP TCP/IP (Wi-Fi and Ethernet), see :ref:`lwip-performance`
     :SOC_WIFI_SUPPORTED: * The :example:`wifi/iperf` example contains a configuration that is heavily optimized for Wi-Fi TCP/IP throughput. Append the contents of the files :example_file:`wifi/iperf/sdkconfig.defaults`, :example_file:`wifi/iperf/sdkconfig.defaults.{IDF_TARGET_PATH_NAME}` and :example_file:`wifi/iperf/sdkconfig.ci.99` to your project ``sdkconfig`` file in order to add all of these options. Note that some of these options may have trade-offs in terms of reduced debuggability, increased firmware size, increased memory usage, or reduced performance of other features. To get the best result, read the documentation pages linked above and use this information to determine exactly which options are best suited for your app.
+
+Improving I/O performance
+-------------------------
+
+Using standard C library functions like ``fread`` and ``fwrite`` instead of platform specific unbuffered syscalls such as ``read`` and ``write`` can be slow.
+These functions are designed to be portable, so they are not necessarily optimized for speed, have a certain overhead and are buffered.
+
+:doc:`FatFS </api-reference/storage/fatfs>` specific information and tips:
+
+.. list::
+
+    - Maximum size of the R/W request == FatFS cluster size (allocation unit size)
+    - Use ``read`` and ``write`` instead of ``fread`` and ``fwrite``
+    - To increase speed of buffered reading functions like ``fread`` and ``fgets``, you can increase a size of the file buffer (Newlib's default is 128 bytes) to a higher number like 4096, 8192 or 16384. This can be done locally via ``setvbuf`` function used on a certain file pointer or globally applied to all files via modifying :ref:`CONFIG_FATFS_VFS_FSTAT_BLKSIZE`.
+
+        .. note::
+            Setting a bigger buffer size will also increase the heap memory usage.

examples/storage/sd_card/sdmmc/sdkconfig.ci

@@ -1 +1,2 @@
 CONFIG_EXAMPLE_FORMAT_IF_MOUNT_FAILED=y
+CONFIG_FATFS_VFS_FSTAT_BLKSIZE=4096

examples/storage/sd_card/sdmmc/sdkconfig.defaults

@@ -0,0 +1 @@
+CONFIG_FATFS_VFS_FSTAT_BLKSIZE=4096