feat(fs): file writes update the file cache

[liamHowatt]

Description of the feature or fix

Continuing PR #5172

PR #5172 adds updating the file cache upon write. Data written out will now be reflected in the cache so file caching is no longer read-only.

This PR is a continuation of the other PR that also adds:

• a test case that writes to a file "randomly", intermixed with read and seek operations.
• Adds more docs for the FS to clarify exactly what kind of caching/buffering the file cache does and when it should and should not be used.
• Refactors the caching code in lv_fs.c. The formatting and sequence of operations is easier to visually parse now. It's easier to see the difference in the refactor if you open the old and new file and review them separately without the diff. I did not touch the implementations of the caching logic. The only thing I changed was remove the driver seek for SEEK_SET and SEEK_CUR when caching is active.

At the time of opening this PR, this is what the new docs look like:

Here is the mermaid flowchart embedded.

   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"]

Notes

• Update the Documentation if needed.
• Add Examples if relevant.
• Add Tests if applicable.
• If you added new options to lv_conf_template.h run lv_conf_internal_gen.py and update Kconfig.
• Run scripts/code-format.py (astyle version v3.4.12 needs to be installed) and follow the Code Conventions.
• Mark the Pull request as Draft while you are working on the first version, and mark is as Ready when it's ready for review.
• When changes were requested, re-request review to notify the maintainers.
• Help us to review this Pull Request! Anyone can approve or request changes.

[kisvegabor]

Very nice! The use of mermaid is especially cool. We haven't used it so far.

It's hard to spot any issues just by reading the code, so if the test passes it should be good 🙂