diff --git a/docs/en/api-reference/storage/spiffs.rst b/docs/en/api-reference/storage/spiffs.rst index a6922d168..a11c3814e 100644 --- a/docs/en/api-reference/storage/spiffs.rst +++ b/docs/en/api-reference/storage/spiffs.rst @@ -10,15 +10,74 @@ It supports wear leveling, file system consistency checks and more. Notes ----- - - Presently, spiffs does not support directories. It produces a flat structure. If SPIFFS is mounted under ``/spiffs`` creating a file with path ``/spiffs/tmp/myfile.txt`` will create a file called ``/tmp/myfile.txt`` in SPIFFS, instead of ``myfile.txt`` under directory ``/spiffs/tmp``. + - Currently, SPIFFS does not support directories. It produces a flat structure. If SPIFFS is mounted under ``/spiffs``, then creating a file with path ``/spiffs/tmp/myfile.txt`` will create a file called ``/tmp/myfile.txt`` in SPIFFS, instead of ``myfile.txt`` under directory ``/spiffs/tmp``. - It is not a realtime stack. One write operation might last much longer than another. - - Presently, it does not detect or handle bad blocks. + - Currently, it does not detect or handle bad blocks. Tools ----- -Host-Side tools for creating SPIFS partition images exist and one such tool is `mkspiffs `_. -You can use it to create image from a given folder and then flash that image with ``esptool.py`` +spiffsgen.py +^^^^^^^^^^^^ + +:component_file:`spiffsgen.py` is a write-only Python SPIFFS implementation used to create filesystem +images from the contents of a host folder. To use ``spiffsgen.py``, simply invoke it from your favorite terminal:: + + python spiffsgen.py + +- image_size: size of the partition on which the created SPIFFS image will be flashed to +- base_dir: directory to create the SPIFFS image of +- output_file: SPIFFS image output file + +Besides the three required arguments: *image_size*, *base_dir* and *output_file*, there are other arguments +that control image generation. Documentation on these arguments exist in the tool's help:: + + python spiffsgen.py --help + +These optional arguments correspond to possible SPIFFS build configuration. +User should make sure that the image is generated with the same arguments/configuration as +SPIFFS was built with, else the user ends up with an invalid image. As a guide, the help output indicates the SPIFFS +build configuration the argument corresponds to. In cases when these arguments +are not specified, the default values shown in the help output are used. + +Once the image has been created, it can be flashed using ``esptool.py`` or ``parttool.py``. + +Aside from invoking ``spiffsgen.py`` standalone, it is also possible to use it directly from the build system by calling +``spiffs_create_partition_image``. + +Make:: + + $(eval $(call spiffs_create_partition_image,,,[FLASH_IN_PROJECT])) + +CMake:: + + spiffs_create_partition_image( [FLASH_IN_PROJECT]) + +This is more convenient as the build configuration is automatically passed to the tool, +ensuring that the image generated is valid for that build. An example of this is while the *image_size* is required +for the standalone invocation, only the *partition* name is required when using ``spiffs_create_partition_image`` -- +the image size is automatically obtained from the project's partition table. +It is important to note that due to the differences in structure between the two build systems, +when using Make, ``spiffs_create_partition_image`` must be called from the project Makefile; +for CMake, it should be called from one of the component CMakeLists.txt. For both build systems, the image will be created in the build directory +with filename *partition*.bin. + +Optionally, user can opt to have the image automatically flashed together with the app binaries, partition tables, etc. on +``idf.py flash`` or ``make flash`` by specifying ``FLASH_IN_PROJECT``. For example:: + + spiffs_create_partition_image(my_spiffs_partition my_folder FLASH_IN_PROJECT) + +If FLASH_IN_PROJECT is not specified, the image is still generated, +but user has to flash it manually using ``esptool.py``, ``parttool.py`` or a custom build system target. + +For an example, see :example:`examples/build_system/spiffsgen>`. + + +mkspiffs +^^^^^^^^ + +Another tool for creating SPIFS partition images is `mkspiffs `_. +Like ``spiffsgen.py``, it can be used to create image from a given folder and then flash that image with ``esptool.py`` To do that you need to obtain some parameters: @@ -35,6 +94,27 @@ To flash the image to ESP32 at offset 0x110000:: python esptool.py --chip esp32 --port [port] --baud [baud] write_flash -z 0x110000 spiffs.bin + +Notes on which SPIFFS tool to use +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The two tools presented above offer very similar functionality. There are, however, reasons to prefer one +over the other depending on the use case. + +If the intent is to simply generate a SPIFFS image during build, ``spiffsgen.py`` makes it very convenient +by providing functions/commands from the build system itself. This makes it easy to generate SPIFFS images +that match the build configuration and can be flashed together with the application. +Another case for choosing ``spiffsgen.py`` is when the host has no C/C++ compiler available, since ``mkspiffs`` +requires compilation. + +On the other hand, ``mkspiffs`` offers unpacking SPIFFS images in addition to image generation. This is not +possible with ``spiffsgen.py``, at least not yet. There might also be environments where a Python interpreter +is not available, but a host compiler is or a pre-compiled ``mkspiffs`` binary +can do the job. However, there is no build system integration for ``mkspiffs`` and the user has to +do the corresponding work: compiling ``mkspiffs`` during build (if a pre-compiled binary is not used), creating build rules/targets +for the output files, passing proper parameters to the tool, etc. + + See also --------