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