feat(fs): file writes update the file cache (#6186)

Co-authored-by: kevinkang-Globe <139213362+kevinkang-Globe@users.noreply.github.com>

docs/conf.py

@@ -42,7 +42,8 @@ extensions = [
     'sphinx_sitemap',
     'lv_example',
     'sphinx_rtd_dark_mode',
-    'link_roles'
+    'link_roles',
+    'sphinxcontrib.mermaid'
 ]
 
 default_dark_mode = False

docs/libs/fs.rst

@@ -34,7 +34,7 @@ The work directory can be set with ``LV_FS_..._PATH``. E.g.
 ``"/home/joe/projects/"`` The actual file/directory paths will be
 appended to it.
 
-Cached reading is also supported if ``LV_FS_..._CACHE_SIZE`` is set to
+:ref:`Cached reading <overview_file_system_cache>` is also supported if ``LV_FS_..._CACHE_SIZE`` is set to
 not ``0`` value. :cpp:func:`lv_fs_read` caches this size of data to lower the
 number of actual reads from the storage.
 

docs/overview/fs.rst

@@ -155,6 +155,95 @@ To use files in image widgets the following callbacks are required:
 - seek
 - tell
 
+.. _overview_file_system_cache:
+
+Optional file buffering/caching
+*******************************
+
+Files will buffer their reads if the corresponding ``LV_FS_*_CACHE_SIZE``
+config option is set to a value greater than zero. Each open file will
+buffer up to that many bytes to reduce the number of FS driver calls.
+
+Generally speaking, file buffering can be optimized for different kinds
+of access patterns. The one implemented here is optimal for reading large
+files in chunks, which is what the image decoder does.
+It has the potential to call the driver's ``read`` fewer
+times than ``lv_fs_read`` is called. In the best case where the cache size is
+\>= the size of the file, ``read`` will only be called once. This strategy is good
+for linear reading of large files but less helpful for short random reads across a file bigger than the buffer
+since data will be buffered that will be discarded after the next seek and read.
+The cache should be sufficiently large or disabled in that case. Another case where the cache should be disabled
+is if the file contents are expected to change by an external factor like with special OS files.
+
+The implementation is documented below. Note that the FS functions make calls
+to other driver FS functions when the cache is enabled. i.e., ``lv_fs_read`` may call the driver's ``seek``
+so the driver needs to implement more callbacks when the cache is enabled.
+
+``lv_fs_read`` :sub:`(behavior when the cache is enabled)`
+-------------------------------------------------
+
+.. mermaid::
+   :zoom:
+
+   %%{init: {'theme':'neutral'}}%%
+   flowchart LR
+       A["call lv_fs_read and
+          the cache is enabled"] --> B{{"is there cached data
+                                         at the file position?"}}
+       B -->|yes| C{{"does the cache have
+                      all required bytes available?"}}
+       C -->|yes| D["copy all required bytes from
+                     the cache to the destination
+                     buffer"]
+       C -->|no| F["copy the available
+                    required bytes
+                    until the end of the cache
+                    into the destination buffer"]
+             --> G["seek the real file to the end
+                    of what the cache had available"]
+             --> H{{"is the number of remaining bytes
+                     larger than the size of the whole cache?"}}
+       H -->|yes| I["read the remaining bytes
+                     from the real file to the
+                     destination buffer"]
+       H -->|no| J["eagerly read the real file
+                    to fill the whole cache
+                    or as many bytes as the
+                    read call can"]
+             --> O["copy the required bytes
+                    to the destination buffer"]
+       B -->|no| K["seek the real file to
+                    the file position"]
+             --> L{{"is the number of required
+                     bytes greater than the
+                     size of the entire cache?"}}
+       L -->|yes| M["read the real file to
+                     the destination buffer"]
+       L -->|no| N["eagerly read the real file
+                    to fill the whole cache
+                    or as many bytes as the
+                    read call can"]
+             --> P["copy the required bytes
+                    to the destination buffer"]
+
+``lv_fs_write`` :sub:`(behavior when the cache is enabled)`
+--------------------------------------------------
+
+The part of the cache that coincides with the written content
+will be updated to reflect the written content.
+
+``lv_fs_seek`` :sub:`(behavior when the cache is enabled)`
+-------------------------------------------------
+
+The driver's ``seek`` will not actually be called unless the ``whence``
+is ``LV_FS_SEEK_END``, in which case ``seek`` and ``tell`` will be called
+to determine where the end of the file is.
+
+``lv_fs_tell`` :sub:`(behavior when the cache is enabled)`
+-------------------------------------------------
+
+The driver's ``tell`` will not actually be called.
+
 .. _overview_file_system_api:
 
 API

docs/requirements.txt

@@ -10,5 +10,6 @@ sphinxcontrib-htmlhelp
 sphinxcontrib-jsmath
 sphinxcontrib-qthelp
 sphinxcontrib-serializinghtml
+sphinxcontrib-mermaid
 sphinx-rtd-dark-mode
 typing-extensions