README.rst
1.. zephyr:code-sample:: littlefs
2 :name: LittleFS filesystem
3 :relevant-api: file_system_api flash_area_api
4
5 Use file system API over LittleFS.
6
7Overview
8********
9
10This sample app demonstrates use of Zephyr's :ref:`file system API
11<file_system_api>` over `littlefs`_, using file system with files that:
12* count the number of times the system has booted
13* holds binary pattern with properly incremented values in it
14
15Other information about the file system is also displayed.
16
17.. _littlefs:
18 https://github.com/ARMmbed/littlefs
19
20Requirements
21************
22
23Flash memory device
24-------------------
25
26The partition labeled "storage" will be used for the file system; see
27:ref:`flash_map_api`. If that area does not already have a
28compatible littlefs file system its contents will be replaced by an
29empty file system. You will see diagnostics like this::
30
31 [00:00:00.010,192] <inf> littlefs: LittleFS version 2.0, disk version 2.0
32 [00:00:00.010,559] <err> littlefs: Corrupted dir pair at 0 1
33 [00:00:00.010,559] <wrn> littlefs: can't mount (LFS -84); formatting
34
35The error and warning are normal for a new file system.
36
37After the file system is mounted you'll also see::
38
39 [00:00:00.182,434] <inf> littlefs: filesystem mounted!
40 [00:00:00.867,034] <err> fs: failed get file or dir stat (-2)
41
42This error is also normal for Zephyr not finding a file (the boot count,
43in this case).
44
45Block device (e.g. SD card)
46---------------------------
47
48One needs to prepare the SD/MMC card with littlefs file system on
49the host machine with the `lfs`_ program.
50
51.. _lfs:
52 https://www.thevtool.com/mounting-littlefs-on-linux-machine/
53
54.. code-block:: console
55
56 sudo chmod a+rw /dev/sda
57 lfs -d -s -f --read_size=512 --prog_size=512 --block_size=512 --cache_size=512 --lookahead_size=8192 --format /dev/sda
58 lfs -d -s -f --read_size=512 --prog_size=512 --block_size=512 --cache_size=512 --lookahead_size=8192 /dev/sda ./mnt_littlefs
59 cd ./mnt_littlefs
60 echo -en '\x01' > foo.txt
61 cd -
62 fusermount -u ./mnt_littlefs
63
64
65Building and Running
66********************
67
68Flash memory device
69-------------------
70
71This example should work on any board that provides a "storage"
72partition. Two tested board targets are described below.
73
74You can set ``CONFIG_APP_WIPE_STORAGE`` to force the file system to be
75recreated.
76
77Block device (e.g. SD card)
78---------------------------
79
80This example has been devised and initially tested on :ref:`Nucleo H743ZI <nucleo_h743zi_board>`
81board. It can be also run on any other board with SD/MMC card connected to it.
82
83To build the test:
84
85.. zephyr-app-commands::
86 :zephyr-app: samples/subsys/fs/littlefs
87 :board: nucleo_h743zi
88 :goals: build flash
89 :gen-args: -DCONF_FILE=prj_blk.conf
90 :compact:
91
92At the moment, only two types of block devices are acceptable in this sample: SDMMC and MMC.
93
94It is possible that both the `zephyr,sdmmc-disk` and `zephyr,mmc-disk` block devices will be
95present and enabled in the final board dts and configuration files simultaneously, the mount
96point name for the `littlefs` file system block device will be determined based on the
97following logic:
98
99* if the ``CONFIG_SDMMC_VOLUME_NAME`` configuration is defined, it will be used
100 as the mount point name;
101* if the ``CONFIG_SDMMC_VOLUME_NAME`` configuration is not defined, but the
102 ``CONFIG_MMC_VOLUME_NAME`` configuration is defined, ``CONFIG_MMC_VOLUME_NAME`` will
103 be used as the mount point name;
104* if neither ``CONFIG_SDMMC_VOLUME_NAME`` nor ``CONFIG_MMC_VOLUME_NAME`` configurations
105 are defined, the mount point name will not be determined, and an appropriate error will
106 apear during the sample build.
107
108NRF52840 Development Kit
109========================
110
111On this device the file system will be placed in the SOC flash.
112
113.. zephyr-app-commands::
114 :zephyr-app: samples/subsys/fs/littlefs
115 :board: nrf52840dk/nrf52840
116 :goals: build
117 :compact:
118
119Particle Xenon
120==============
121
122On this device the file system will be placed on the external SPI NOR
123flash memory.
124
125.. zephyr-app-commands::
126 :zephyr-app: samples/subsys/fs/littlefs
127 :board: particle_xenon
128 :goals: build
129 :compact:
130
