]>
Commit | Line | Data |
---|---|---|
e56a99d5 AB |
1 | Introduction |
2 | ============= | |
3 | ||
4 | UBIFS file-system stands for UBI File System. UBI stands for "Unsorted | |
5 | Block Images". UBIFS is a flash file system, which means it is designed | |
6 | to work with flash devices. It is important to understand, that UBIFS | |
7 | is completely different to any traditional file-system in Linux, like | |
8 | Ext2, XFS, JFS, etc. UBIFS represents a separate class of file-systems | |
9 | which work with MTD devices, not block devices. The other Linux | |
10 | file-system of this class is JFFS2. | |
11 | ||
12 | To make it more clear, here is a small comparison of MTD devices and | |
13 | block devices. | |
14 | ||
15 | 1 MTD devices represent flash devices and they consist of eraseblocks of | |
16 | rather large size, typically about 128KiB. Block devices consist of | |
17 | small blocks, typically 512 bytes. | |
18 | 2 MTD devices support 3 main operations - read from some offset within an | |
19 | eraseblock, write to some offset within an eraseblock, and erase a whole | |
20 | eraseblock. Block devices support 2 main operations - read a whole | |
21 | block and write a whole block. | |
22 | 3 The whole eraseblock has to be erased before it becomes possible to | |
23 | re-write its contents. Blocks may be just re-written. | |
24 | 4 Eraseblocks become worn out after some number of erase cycles - | |
25 | typically 100K-1G for SLC NAND and NOR flashes, and 1K-10K for MLC | |
26 | NAND flashes. Blocks do not have the wear-out property. | |
27 | 5 Eraseblocks may become bad (only on NAND flashes) and software should | |
28 | deal with this. Blocks on hard drives typically do not become bad, | |
29 | because hardware has mechanisms to substitute bad blocks, at least in | |
30 | modern LBA disks. | |
31 | ||
32 | It should be quite obvious why UBIFS is very different to traditional | |
33 | file-systems. | |
34 | ||
35 | UBIFS works on top of UBI. UBI is a separate software layer which may be | |
36 | found in drivers/mtd/ubi. UBI is basically a volume management and | |
37 | wear-leveling layer. It provides so called UBI volumes which is a higher | |
38 | level abstraction than a MTD device. The programming model of UBI devices | |
39 | is very similar to MTD devices - they still consist of large eraseblocks, | |
40 | they have read/write/erase operations, but UBI devices are devoid of | |
41 | limitations like wear and bad blocks (items 4 and 5 in the above list). | |
42 | ||
43 | In a sense, UBIFS is a next generation of JFFS2 file-system, but it is | |
44 | very different and incompatible to JFFS2. The following are the main | |
45 | differences. | |
46 | ||
47 | * JFFS2 works on top of MTD devices, UBIFS depends on UBI and works on | |
48 | top of UBI volumes. | |
49 | * JFFS2 does not have on-media index and has to build it while mounting, | |
50 | which requires full media scan. UBIFS maintains the FS indexing | |
51 | information on the flash media and does not require full media scan, | |
52 | so it mounts many times faster than JFFS2. | |
53 | * JFFS2 is a write-through file-system, while UBIFS supports write-back, | |
54 | which makes UBIFS much faster on writes. | |
55 | ||
56 | Similarly to JFFS2, UBIFS supports on-the-flight compression which makes | |
57 | it possible to fit quite a lot of data to the flash. | |
58 | ||
59 | Similarly to JFFS2, UBIFS is tolerant of unclean reboots and power-cuts. | |
2e244d08 | 60 | It does not need stuff like fsck.ext2. UBIFS automatically replays its |
e56a99d5 AB |
61 | journal and recovers from crashes, ensuring that the on-flash data |
62 | structures are consistent. | |
63 | ||
64 | UBIFS scales logarithmically (most of the data structures it uses are | |
65 | trees), so the mount time and memory consumption do not linearly depend | |
66 | on the flash size, like in case of JFFS2. This is because UBIFS | |
67 | maintains the FS index on the flash media. However, UBIFS depends on | |
68 | UBI, which scales linearly. So overall UBI/UBIFS stack scales linearly. | |
69 | Nevertheless, UBI/UBIFS scales considerably better than JFFS2. | |
70 | ||
71 | The authors of UBIFS believe, that it is possible to develop UBI2 which | |
72 | would scale logarithmically as well. UBI2 would support the same API as UBI, | |
73 | but it would be binary incompatible to UBI. So UBIFS would not need to be | |
74 | changed to use UBI2 | |
75 | ||
76 | ||
77 | Mount options | |
78 | ============= | |
79 | ||
80 | (*) == default. | |
81 | ||
82 | norm_unmount (*) commit on unmount; the journal is committed | |
83 | when the file-system is unmounted so that the | |
84 | next mount does not have to replay the journal | |
85 | and it becomes very fast; | |
86 | fast_unmount do not commit on unmount; this option makes | |
87 | unmount faster, but the next mount slower | |
88 | because of the need to replay the journal. | |
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 | |
2953e73f AH |
92 | no_chk_data_crc skip checking of CRCs on data nodes in order to |
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. | |
97 | chk_data_crc (*) do not skip checking CRCs on data nodes | |
e56a99d5 AB |
98 | |
99 | ||
100 | Quick usage instructions | |
101 | ======================== | |
102 | ||
103 | The UBI volume to mount is specified using "ubiX_Y" or "ubiX:NAME" syntax, | |
104 | where "X" is UBI device number, "Y" is UBI volume number, and "NAME" is | |
105 | UBI volume name. | |
106 | ||
107 | Mount volume 0 on UBI device 0 to /mnt/ubifs: | |
108 | $ mount -t ubifs ubi0_0 /mnt/ubifs | |
109 | ||
110 | Mount "rootfs" volume of UBI device 0 to /mnt/ubifs ("rootfs" is volume | |
111 | name): | |
112 | $ mount -t ubifs ubi0:rootfs /mnt/ubifs | |
113 | ||
114 | The following is an example of the kernel boot arguments to attach mtd0 | |
115 | to UBI and mount volume "rootfs": | |
116 | ubi.mtd=0 root=ubi0:rootfs rootfstype=ubifs | |
117 | ||
118 | ||
119 | Module Parameters for Debugging | |
120 | =============================== | |
121 | ||
122 | When UBIFS has been compiled with debugging enabled, there are 3 module | |
123 | parameters that are available to control aspects of testing and debugging. | |
124 | The parameters are unsigned integers where each bit controls an option. | |
125 | The parameters are: | |
126 | ||
127 | debug_msgs Selects which debug messages to display, as follows: | |
128 | ||
129 | Message Type Flag value | |
130 | ||
131 | General messages 1 | |
132 | Journal messages 2 | |
133 | Mount messages 4 | |
134 | Commit messages 8 | |
135 | LEB search messages 16 | |
136 | Budgeting messages 32 | |
137 | Garbage collection messages 64 | |
138 | Tree Node Cache (TNC) messages 128 | |
139 | LEB properties (lprops) messages 256 | |
140 | Input/output messages 512 | |
141 | Log messages 1024 | |
142 | Scan messages 2048 | |
143 | Recovery messages 4096 | |
144 | ||
145 | debug_chks Selects extra checks that UBIFS can do while running: | |
146 | ||
147 | Check Flag value | |
148 | ||
149 | General checks 1 | |
150 | Check Tree Node Cache (TNC) 2 | |
151 | Check indexing tree size 4 | |
152 | Check orphan area 8 | |
153 | Check old indexing tree 16 | |
154 | Check LEB properties (lprops) 32 | |
155 | Check leaf nodes and inodes 64 | |
156 | ||
157 | debug_tsts Selects a mode of testing, as follows: | |
158 | ||
159 | Test mode Flag value | |
160 | ||
161 | Force in-the-gaps method 2 | |
162 | Failure mode for recovery testing 4 | |
163 | ||
164 | For example, set debug_msgs to 5 to display General messages and Mount | |
165 | messages. | |
166 | ||
167 | ||
168 | References | |
169 | ========== | |
170 | ||
171 | UBIFS documentation and FAQ/HOWTO at the MTD web site: | |
172 | http://www.linux-mtd.infradead.org/doc/ubifs.html | |
173 | http://www.linux-mtd.infradead.org/faq/ubifs.html |