Crash_Override/OVMS3-idf
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity
OVMS3-idf/docs/en/api-reference/storage/fatfs.rst

70 lines
4.3 KiB
ReStructuredText
Raw Normal View History

docs: add sdmmc and fatfs docs
2017-01-08 20:09:09 +00:00
FAT Filesystem Support
======================
ESP-IDF uses `FatFs <http://elm-chan.org/fsw/ff/00index_e.html>`_ library to work with FAT filesystems. FatFs library resides in ``fatfs`` component. Although it can be used directly, many of its features can be accessed via VFS using C standard library and POSIX APIs.
Additionally, FatFs has been modified to support run-time pluggable disk IO layer. This allows mapping of FatFs drives to physical disks at run-time.
Using FatFs with VFS
--------------------
FATFS support without wear levelling This change allows readonly FATFS to be mounted without wear levelling support. This will provide the customers a simple way to mount FATFS images generated on host and flashed onto the chip during factory provisioning. Since NVS encryption is not supported yet and NVS entry size is limited, the change will provide an easy alternative for securing the provisioning data by just marking FATFS parition as encrypted.
2018-06-08 12:09:00 +00:00
:component_file:`fatfs/src/esp_vfs_fat.h` header file defines functions to connect FatFs with VFS. :cpp:func:`esp_vfs_fat_register` function allocates a ``FATFS`` structure, and registers a given path prefix in VFS. Subsequent operations on files starting with this prefix are forwarded to FatFs APIs. :cpp:func:`esp_vfs_fat_unregister_path` function deletes the registration with VFS, and frees the ``FATFS`` structure.
docs: add sdmmc and fatfs docs
2017-01-08 20:09:09 +00:00
Most applications will use the following flow when working with ``esp_vfs_fat_`` functions:
FATFS support without wear levelling This change allows readonly FATFS to be mounted without wear levelling support. This will provide the customers a simple way to mount FATFS images generated on host and flashed onto the chip during factory provisioning. Since NVS encryption is not supported yet and NVS entry size is limited, the change will provide an easy alternative for securing the provisioning data by just marking FATFS parition as encrypted.
2018-06-08 12:09:00 +00:00
1. Call :cpp:func:`esp_vfs_fat_register`, specifying path prefix where the filesystem has to be mounted (e.g. ``"/sdcard"``, ``"/spiflash"``), FatFs drive number, and a variable which will receive a pointer to ``FATFS`` structure.
docs: add sdmmc and fatfs docs
2017-01-08 20:09:09 +00:00
FATFS support without wear levelling This change allows readonly FATFS to be mounted without wear levelling support. This will provide the customers a simple way to mount FATFS images generated on host and flashed onto the chip during factory provisioning. Since NVS encryption is not supported yet and NVS entry size is limited, the change will provide an easy alternative for securing the provisioning data by just marking FATFS parition as encrypted.
2018-06-08 12:09:00 +00:00
2. Call :cpp:func:`ff_diskio_register` function to register disk IO driver for the drive number used in step 1.
docs: add sdmmc and fatfs docs
2017-01-08 20:09:09 +00:00
FATFS support without wear levelling This change allows readonly FATFS to be mounted without wear levelling support. This will provide the customers a simple way to mount FATFS images generated on host and flashed onto the chip during factory provisioning. Since NVS encryption is not supported yet and NVS entry size is limited, the change will provide an easy alternative for securing the provisioning data by just marking FATFS parition as encrypted.
2018-06-08 12:09:00 +00:00
3. Call FatFs ``f_mount`` function (and optionally ``f_fdisk``, ``f_mkfs``) to mount the filesystem using the same drive number which was passed to :cpp:func:`esp_vfs_fat_register`. See `FatFs documentation for more details <http://www.elm-chan.org/fsw/ff/doc/mount.html>`.
docs: add sdmmc and fatfs docs
2017-01-08 20:09:09 +00:00
FATFS support without wear levelling This change allows readonly FATFS to be mounted without wear levelling support. This will provide the customers a simple way to mount FATFS images generated on host and flashed onto the chip during factory provisioning. Since NVS encryption is not supported yet and NVS entry size is limited, the change will provide an easy alternative for securing the provisioning data by just marking FATFS parition as encrypted.
2018-06-08 12:09:00 +00:00
4. Call POSIX and C standard library functions to open, read, write, erase, copy files, etc. Use paths starting with the prefix passed to :cpp:func:`esp_vfs_register` (such as ``"/sdcard/hello.txt"``).
docs: add sdmmc and fatfs docs
2017-01-08 20:09:09 +00:00
5. Optionally, call FatFs library functions directly. Use paths without a VFS prefix in this case (``"/hello.txt"``).
6. Close all open files.
FATFS support without wear levelling This change allows readonly FATFS to be mounted without wear levelling support. This will provide the customers a simple way to mount FATFS images generated on host and flashed onto the chip during factory provisioning. Since NVS encryption is not supported yet and NVS entry size is limited, the change will provide an easy alternative for securing the provisioning data by just marking FATFS parition as encrypted.
2018-06-08 12:09:00 +00:00
7. Call FatFs ``f_mount`` function for the same drive number, with NULL ``FATFS*`` argument, to unmount the filesystem.
docs: add sdmmc and fatfs docs
2017-01-08 20:09:09 +00:00
FATFS support without wear levelling This change allows readonly FATFS to be mounted without wear levelling support. This will provide the customers a simple way to mount FATFS images generated on host and flashed onto the chip during factory provisioning. Since NVS encryption is not supported yet and NVS entry size is limited, the change will provide an easy alternative for securing the provisioning data by just marking FATFS parition as encrypted.
2018-06-08 12:09:00 +00:00
8. Call FatFs :cpp:func:`ff_diskio_register` with NULL ``ff_diskio_impl_t*`` argument and the same drive number.
docs: add sdmmc and fatfs docs
2017-01-08 20:09:09 +00:00
FATFS support without wear levelling This change allows readonly FATFS to be mounted without wear levelling support. This will provide the customers a simple way to mount FATFS images generated on host and flashed onto the chip during factory provisioning. Since NVS encryption is not supported yet and NVS entry size is limited, the change will provide an easy alternative for securing the provisioning data by just marking FATFS parition as encrypted.
2018-06-08 12:09:00 +00:00
9. Call :cpp:func:`esp_vfs_fat_unregister_path` with the path where the file system is mounted to remove FatFs from VFS, and free the ``FATFS`` structure allocated on step 1.
docs: add sdmmc and fatfs docs
2017-01-08 20:09:09 +00:00
Convenience functions, ``esp_vfs_fat_sdmmc_mount`` and ``esp_vfs_fat_sdmmc_unmount``, which wrap these steps and also handle SD card initialization, are described in the next section.
.. doxygenfunction:: esp_vfs_fat_register
pick better name for unregister function and update docs
2017-02-02 10:24:38 +00:00
.. doxygenfunction:: esp_vfs_fat_unregister_path
docs: add sdmmc and fatfs docs
2017-01-08 20:09:09 +00:00
Using FatFs with VFS and SD cards
---------------------------------
FATFS support without wear levelling This change allows readonly FATFS to be mounted without wear levelling support. This will provide the customers a simple way to mount FATFS images generated on host and flashed onto the chip during factory provisioning. Since NVS encryption is not supported yet and NVS entry size is limited, the change will provide an easy alternative for securing the provisioning data by just marking FATFS parition as encrypted.
2018-06-08 12:09:00 +00:00
:component_file:`fatfs/src/esp_vfs_fat.h` header file also provides a convenience function to perform steps 1–3 and 7–9, and also handle SD card initialization: :cpp:func:`esp_vfs_fat_sdmmc_mount`. This function does only limited error handling. Developers are encouraged to look at its source code and incorporate more advanced versions into production applications. :cpp:func:`esp_vfs_fat_sdmmc_unmount` function unmounts the filesystem and releases resources acquired by :cpp:func:`esp_vfs_fat_sdmmc_mount`.
docs: add sdmmc and fatfs docs
2017-01-08 20:09:09 +00:00
.. doxygenfunction:: esp_vfs_fat_sdmmc_mount
add wear_levelling component and example
2017-04-10 14:06:35 +00:00
.. doxygenstruct:: esp_vfs_fat_mount_config_t
docs: add sdmmc and fatfs docs
2017-01-08 20:09:09 +00:00
:members:
.. doxygenfunction:: esp_vfs_fat_sdmmc_unmount
FATFS support without wear levelling This change allows readonly FATFS to be mounted without wear levelling support. This will provide the customers a simple way to mount FATFS images generated on host and flashed onto the chip during factory provisioning. Since NVS encryption is not supported yet and NVS entry size is limited, the change will provide an easy alternative for securing the provisioning data by just marking FATFS parition as encrypted.
2018-06-08 12:09:00 +00:00
Using FatFs with VFS in read-only mode
--------------------------------------
Convenience functions, :cpp:func:`esp_vfs_fat_rawflash_mount` and :cpp:func:`esp_vfs_fat_rawflash_unmount`, are provided by :component_file:`fatfs/src/esp_vfs_fat.h` header file in order to perform steps 1-3 and 7-9 for read-only FAT partitions. These are particularly helpful for data partitions written only once during factory provisioning and need not be changed by production application throughout the lifetime.
.. doxygenfunction:: esp_vfs_fat_rawflash_mount
.. doxygenfunction:: esp_vfs_fat_rawflash_unmount
docs: add sdmmc and fatfs docs
2017-01-08 20:09:09 +00:00
FatFS disk IO layer
-------------------
FatFs has been extended with an API to register disk IO driver at runtime.
FATFS support without wear levelling This change allows readonly FATFS to be mounted without wear levelling support. This will provide the customers a simple way to mount FATFS images generated on host and flashed onto the chip during factory provisioning. Since NVS encryption is not supported yet and NVS entry size is limited, the change will provide an easy alternative for securing the provisioning data by just marking FATFS parition as encrypted.
2018-06-08 12:09:00 +00:00
Implementation of disk IO functions for SD/MMC cards is provided. It can be registered for the given FatFs drive number using :cpp:func:`ff_diskio_register_sdmmc` function.
docs: add sdmmc and fatfs docs
2017-01-08 20:09:09 +00:00
.. doxygenfunction:: ff_diskio_register
.. doxygenstruct:: ff_diskio_impl_t
:members:
.. doxygenfunction:: ff_diskio_register_sdmmc
Reference in a new issue Copy permalink