1.. zephyr:code-sample:: fs
2   :name: File system manipulation
3   :relevant-api: file_system_api disk_access_interface
4
5   Use file system API with various filesystems and storage devices.
6
7Overview
8********
9
10This sample app demonstrates use of the file system API and uses the FAT or Ext2 file
11system driver with SDHC card, SoC flash or external flash chip.
12
13To access device the sample uses :ref:`disk_access_api`.
14
15Requirements for SD card support
16********************************
17
18This project requires SD card support and microSD card formatted with proper file system
19(FAT or Ext2) See the :ref:`disk_access_api` documentation for Zephyr implementation details.
20Boards that by default use SD card for storage: ``arduino_mkrzero``, ``esp_wrover_kit``,
21``mimxrt1050_evk``, ``nrf52840_blip`` and  ``olimexino_stm32``. The sample should be able
22to run with any other board that has "zephyr,sdmmc-disk" DT node enabled.
23
24Requirements for setting up FAT FS on SoC flash
25***********************************************
26
27For the FAT FS to work with internal flash, the device needs to support erase
28pages of size <= 4096 bytes and have at least 64kiB of flash available for
29FAT FS partition alone.
30Currently the following boards are supported:
31``nrf52840dk/nrf52840``
32
33Requirements for setting up FAT FS on external flash
34****************************************************
35
36This type of configuration requires external flash device to be available
37on DK board. Currently following boards support the configuration:
38``nrf52840dk/nrf52840`` by ``nrf52840dk_nrf52840_qspi`` configuration.
39
40Building and Running FAT samples
41********************************
42
43Boards with default configurations, for example ``arduino_mkrzero`` or
44``nrf52840dk/nrf52840`` using internal flash can be built using command:
45
46.. zephyr-app-commands::
47   :zephyr-app: samples/subsys/fs/fs_sample
48   :board: nrf52840_blip
49   :goals: build
50   :compact:
51
52Where used example board ``nrf52840_blip`` should be replaced with desired board.
53
54In case when some more specific configuration is to be used for a given board,
55for example ``nrf52840dk/nrf52840`` with MX25 device over QSPI, configuration
56and DTS overlays need to be also selected. The command would look like this:
57
58.. zephyr-app-commands::
59   :zephyr-app: samples/subsys/fs/fs_sample
60   :board: nrf52840dk/nrf52840
61   :gen-args: -DEXTRA_CONF_FILE=nrf52840dk_nrf52840_qspi.conf -DDTC_OVERLAY_FILE=nrf52840dk_nrf52840_qspi.overlay
62   :goals: build
63   :compact:
64
65In case when board with SD card is used FAT microSD card should be present in the
66microSD slot. If there are any files or directories present in the card, the
67sample lists them out on the debug serial output.
68
69.. warning::
70   In case when mount fails the device may get re-formatted to FAT FS.
71   To disable this behaviour disable :kconfig:option:`CONFIG_FS_FATFS_MOUNT_MKFS` .
72
73Building and Running EXT2 samples
74*********************************
75
76Ext2 sample can be built for ``hifive_unmatched/fu740/s7`` or ``bl5340_dvk/nrf5340/cpuapp``. Because
77FAT is default file system for this sample, additional flags must be passed to build
78the sample.
79
80.. zephyr-app-commands::
81   :zephyr-app: samples/subsys/fs/fs_sample
82   :board: hifive_unmatched/fu740/s7 hifive_unmatched/fu740/u74
83   :gen-args: -DCONF_FILE=prj_ext.conf
84   :goals: build
85   :compact:
86
87A microSD card must be present in a microSD card slot of the board, for the sample to execute.
88After starting the sample a contents of a root directory should be printed on the console.
89