1SPIFFS Filesystem
2=================
3
4:link_to_translation:`zh_CN:[中文]`
5
6Overview
7--------
8
9SPIFFS is a file system intended for SPI NOR flash devices on embedded targets. It supports wear levelling, file system consistency checks, and more.
10
11Notes
12-----
13
14 - Currently, SPIFFS does not support directories, it produces a flat structure. If SPIFFS is mounted under ``/spiffs``, then creating a file with the path ``/spiffs/tmp/myfile.txt`` will create a file called ``/tmp/myfile.txt`` in SPIFFS, instead of ``myfile.txt`` in the directory ``/spiffs/tmp``.
15 - It is not a real-time stack. One write operation might take much longer than another.
16 - For now, it does not detect or handle bad blocks.
17 - SPIFFS is able to reliably utilize only around 75% of assigned partition space.
18 - When the filesystem is running out of space, the garbage collector is trying to find free space by scanning the filesystem multiple times, which can take up to several seconds per write function call, depending on required space. This is caused by the SPIFFS design and the issue has been reported multiple times (e.g. `here <https://github.com/espressif/esp-idf/issues/1737>`_) and in the official `SPIFFS github repository <https://github.com/pellepl/spiffs/issues/>`_. The issue can be partially mitigated by the `SPIFFS configuration <https://github.com/pellepl/spiffs/wiki/Configure-spiffs>`_.
19 - Deleting a file does not always remove the whole file, which leaves unusable sections throughout the filesystem.
20
21Tools
22-----
23
24spiffsgen.py
25^^^^^^^^^^^^
26
27:component_file:`spiffsgen.py<spiffs/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``, open Terminal and run::
28
29    python spiffsgen.py <image_size> <base_dir> <output_file>
30
31The required arguments are as follows:
32
33- **image_size**: size of the partition onto which the created SPIFFS image will be flashed.
34- **base_dir**: directory for which the SPIFFS image needs to be created.
35- **output_file**: SPIFFS image output file.
36
37There are also other arguments that control image generation. Documentation on these arguments can be found in the tool's help::
38
39    python spiffsgen.py --help
40
41These optional arguments correspond to a possible SPIFFS build configuration. To generate the right image, please make sure that you use the same arguments/configuration as were used to build SPIFFS. As a guide, the help output indicates the SPIFFS build configuration to which the argument corresponds. In cases when these arguments are not specified, the default values shown in the help output will be used.
42
43When the image is created, it can be flashed using ``esptool.py`` or ``parttool.py``.
44
45Aside from invoking the ``spiffsgen.py`` standalone by manually running it from the command line or a script, it is also possible to invoke ``spiffsgen.py`` directly from the build system by calling ``spiffs_create_partition_image``.
46
47Make::
48
49    SPIFFS_IMAGE_FLASH_IN_PROJECT := ...
50    SPIFFS_IMAGE_DEPENDS := ...
51    $(eval $(call spiffs_create_partition_image,<partition>,<base_dir>))
52
53CMake::
54
55    spiffs_create_partition_image(<partition> <base_dir> [FLASH_IN_PROJECT] [DEPENDS dep dep dep...])
56
57This is more convenient as the build configuration is automatically passed to the tool, ensuring that the generated image 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.
58
59Due to the differences in structure between Make and CMake, it is important to note that:
60
61- for Make ``spiffs_create_partition_image`` must be called from the project Makefile
62- for CMake ``spiffs_create_partition_image`` must be called from one of the component CMakeLists.txt files
63
64Optionally, 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,
65
66in Make::
67
68    SPIFFS_IMAGE_FLASH_IN_PROJECT := 1
69    $(eval $(call spiffs_create_partition_image,<partition>,<base_dir>))
70
71in CMake::
72
73    spiffs_create_partition_image(my_spiffs_partition my_folder FLASH_IN_PROJECT)
74
75If FLASH_IN_PROJECT/SPIFFS_IMAGE_FLASH_IN_PROJECT is not specified, the image will still be generated, but you will have to flash it manually using ``esptool.py``, ``parttool.py``, or a custom build system target.
76
77There are cases where the contents of the base directory itself is generated at build time. Users can use DEPENDS/SPIFFS_IMAGE_DEPENDS to specify targets that should be executed before generating the image.
78
79in Make::
80
81    dep:
82        ...
83
84    SPIFFS_IMAGE_DEPENDS := dep
85    $(eval $(call spiffs_create_partition_image,<partition>,<base_dir>))
86
87in CMake::
88
89    add_custom_target(dep COMMAND ...)
90
91    spiffs_create_partition_image(my_spiffs_partition my_folder DEPENDS dep)
92
93For an example, see :example:`storage/spiffsgen`.
94
95mkspiffs
96^^^^^^^^
97
98Another tool for creating SPIFFS partition images is `mkspiffs <https://github.com/igrr/mkspiffs>`_. Similar to ``spiffsgen.py``, it can be used to create an image from a given folder and then flash that image using ``esptool.py``
99
100For that, you need to obtain the following parameters:
101
102- **Block Size**: 4096 (standard for SPI Flash)
103- **Page Size**: 256 (standard for SPI Flash)
104- **Image Size**: Size of the partition in bytes (can be obtained from a partition table)
105- **Partition Offset**: Starting address of the partition (can be obtained from a partition table)
106
107To pack a folder into a 1-Megabyte image, run::
108
109    mkspiffs -c [src_folder] -b 4096 -p 256 -s 0x100000 spiffs.bin
110
111To flash the image onto {IDF_TARGET_NAME} at offset 0x110000, run::
112
113    python esptool.py --chip {IDF_TARGET_PATH_NAME} --port [port] --baud [baud] write_flash -z 0x110000 spiffs.bin
114
115Notes on which SPIFFS tool to use
116~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
117
118The two tools presented above offer very similar functionality. However, there are reasons to prefer one over the other, depending on the use case.
119
120Use ``spiffsgen.py`` in the following cases:
121
1221. If you want to simply generate a SPIFFS image during the build. ``spiffsgen.py`` makes it very convenient by providing functions/commands from the build system itself.
1232. If the host has no C/C++ compiler available, because ``spiffsgen.py`` does not require compilation.
124
125Use ``mkspiffs`` in the following cases:
126
1271. If you need to unpack SPIFFS images in addition to image generation. For now, it is not possible with ``spiffsgen.py``.
1282. If you have an environment where a Python interpreter is not available, but a host compiler is available. Otherwise, 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.
129
130See also
131--------
132
133- :doc:`Partition Table documentation <../../api-guides/partition-tables>`
134
135
136Application Example
137-------------------
138
139An example of using SPIFFS is provided in the :example:`storage/spiffs` directory. This example initializes and mounts a SPIFFS partition, then writes and reads data from it using POSIX and C library APIs. See the README.md file in the example directory for more information.
140
141High-level API Reference
142------------------------
143
144.. include-build-file:: inc/esp_spiffs.inc
145