]>
Commit | Line | Data |
---|---|---|
38e56b4e MCC |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
3 | =============== | |
4 | UBI File System | |
5 | =============== | |
6 | ||
e56a99d5 | 7 | Introduction |
38e56b4e | 8 | ============ |
e56a99d5 AB |
9 | |
10 | UBIFS file-system stands for UBI File System. UBI stands for "Unsorted | |
11 | Block Images". UBIFS is a flash file system, which means it is designed | |
12 | to work with flash devices. It is important to understand, that UBIFS | |
13 | is completely different to any traditional file-system in Linux, like | |
14 | Ext2, XFS, JFS, etc. UBIFS represents a separate class of file-systems | |
15 | which work with MTD devices, not block devices. The other Linux | |
16 | file-system of this class is JFFS2. | |
17 | ||
18 | To make it more clear, here is a small comparison of MTD devices and | |
19 | block devices. | |
20 | ||
21 | 1 MTD devices represent flash devices and they consist of eraseblocks of | |
22 | rather large size, typically about 128KiB. Block devices consist of | |
23 | small blocks, typically 512 bytes. | |
24 | 2 MTD devices support 3 main operations - read from some offset within an | |
25 | eraseblock, write to some offset within an eraseblock, and erase a whole | |
26 | eraseblock. Block devices support 2 main operations - read a whole | |
27 | block and write a whole block. | |
28 | 3 The whole eraseblock has to be erased before it becomes possible to | |
29 | re-write its contents. Blocks may be just re-written. | |
30 | 4 Eraseblocks become worn out after some number of erase cycles - | |
31 | typically 100K-1G for SLC NAND and NOR flashes, and 1K-10K for MLC | |
32 | NAND flashes. Blocks do not have the wear-out property. | |
33 | 5 Eraseblocks may become bad (only on NAND flashes) and software should | |
34 | deal with this. Blocks on hard drives typically do not become bad, | |
35 | because hardware has mechanisms to substitute bad blocks, at least in | |
36 | modern LBA disks. | |
37 | ||
38 | It should be quite obvious why UBIFS is very different to traditional | |
39 | file-systems. | |
40 | ||
41 | UBIFS works on top of UBI. UBI is a separate software layer which may be | |
42 | found in drivers/mtd/ubi. UBI is basically a volume management and | |
43 | wear-leveling layer. It provides so called UBI volumes which is a higher | |
44 | level abstraction than a MTD device. The programming model of UBI devices | |
45 | is very similar to MTD devices - they still consist of large eraseblocks, | |
46 | they have read/write/erase operations, but UBI devices are devoid of | |
47 | limitations like wear and bad blocks (items 4 and 5 in the above list). | |
48 | ||
49 | In a sense, UBIFS is a next generation of JFFS2 file-system, but it is | |
50 | very different and incompatible to JFFS2. The following are the main | |
51 | differences. | |
52 | ||
53 | * JFFS2 works on top of MTD devices, UBIFS depends on UBI and works on | |
54 | top of UBI volumes. | |
55 | * JFFS2 does not have on-media index and has to build it while mounting, | |
56 | which requires full media scan. UBIFS maintains the FS indexing | |
57 | information on the flash media and does not require full media scan, | |
58 | so it mounts many times faster than JFFS2. | |
59 | * JFFS2 is a write-through file-system, while UBIFS supports write-back, | |
60 | which makes UBIFS much faster on writes. | |
61 | ||
62 | Similarly to JFFS2, UBIFS supports on-the-flight compression which makes | |
63 | it possible to fit quite a lot of data to the flash. | |
64 | ||
65 | Similarly to JFFS2, UBIFS is tolerant of unclean reboots and power-cuts. | |
2e244d08 | 66 | It does not need stuff like fsck.ext2. UBIFS automatically replays its |
e56a99d5 AB |
67 | journal and recovers from crashes, ensuring that the on-flash data |
68 | structures are consistent. | |
69 | ||
70 | UBIFS scales logarithmically (most of the data structures it uses are | |
71 | trees), so the mount time and memory consumption do not linearly depend | |
72 | on the flash size, like in case of JFFS2. This is because UBIFS | |
73 | maintains the FS index on the flash media. However, UBIFS depends on | |
74 | UBI, which scales linearly. So overall UBI/UBIFS stack scales linearly. | |
75 | Nevertheless, UBI/UBIFS scales considerably better than JFFS2. | |
76 | ||
77 | The authors of UBIFS believe, that it is possible to develop UBI2 which | |
78 | would scale logarithmically as well. UBI2 would support the same API as UBI, | |
79 | but it would be binary incompatible to UBI. So UBIFS would not need to be | |
80 | changed to use UBI2 | |
81 | ||
82 | ||
83 | Mount options | |
84 | ============= | |
85 | ||
86 | (*) == default. | |
87 | ||
38e56b4e | 88 | ==================== ======================================================= |
4793e7c5 AH |
89 | bulk_read read more in one go to take advantage of flash |
90 | media that read faster sequentially | |
91 | no_bulk_read (*) do not bulk-read | |
2bcf0021 | 92 | no_chk_data_crc (*) skip checking of CRCs on data nodes in order to |
2953e73f AH |
93 | improve read performance. Use this option only |
94 | if the flash media is highly reliable. The effect | |
95 | of this option is that corruption of the contents | |
96 | of a file can go unnoticed. | |
2bcf0021 | 97 | chk_data_crc do not skip checking CRCs on data nodes |
80736d41 AB |
98 | compr=none override default compressor and set it to "none" |
99 | compr=lzo override default compressor and set it to "lzo" | |
100 | compr=zlib override default compressor and set it to "zlib" | |
d8a22773 SH |
101 | auth_key= specify the key used for authenticating the filesystem. |
102 | Passing this option makes authentication mandatory. | |
103 | The passed key must be present in the kernel keyring | |
104 | and must be of type 'logon' | |
105 | auth_hash_name= The hash algorithm used for authentication. Used for | |
106 | both hashing and for creating HMACs. Typical values | |
107 | include "sha256" or "sha512" | |
38e56b4e | 108 | ==================== ======================================================= |
e56a99d5 AB |
109 | |
110 | ||
111 | Quick usage instructions | |
112 | ======================== | |
113 | ||
114 | The UBI volume to mount is specified using "ubiX_Y" or "ubiX:NAME" syntax, | |
115 | where "X" is UBI device number, "Y" is UBI volume number, and "NAME" is | |
116 | UBI volume name. | |
117 | ||
38e56b4e MCC |
118 | Mount volume 0 on UBI device 0 to /mnt/ubifs:: |
119 | ||
120 | $ mount -t ubifs ubi0_0 /mnt/ubifs | |
e56a99d5 AB |
121 | |
122 | Mount "rootfs" volume of UBI device 0 to /mnt/ubifs ("rootfs" is volume | |
38e56b4e MCC |
123 | name):: |
124 | ||
125 | $ mount -t ubifs ubi0:rootfs /mnt/ubifs | |
e56a99d5 AB |
126 | |
127 | The following is an example of the kernel boot arguments to attach mtd0 | |
128 | to UBI and mount volume "rootfs": | |
129 | ubi.mtd=0 root=ubi0:rootfs rootfstype=ubifs | |
130 | ||
e56a99d5 AB |
131 | References |
132 | ========== | |
133 | ||
134 | UBIFS documentation and FAQ/HOWTO at the MTD web site: | |
38e56b4e MCC |
135 | |
136 | - http://www.linux-mtd.infradead.org/doc/ubifs.html | |
137 | - http://www.linux-mtd.infradead.org/faq/ubifs.html |