blob: 6a0d70a22f05f238cb1da86208437818f192b495 [file] [log] [blame]
Artem Bityutskiye56a99d2008-07-14 19:08:34 +03001Introduction
2=============
3
4UBIFS file-system stands for UBI File System. UBI stands for "Unsorted
5Block Images". UBIFS is a flash file system, which means it is designed
6to work with flash devices. It is important to understand, that UBIFS
7is completely different to any traditional file-system in Linux, like
8Ext2, XFS, JFS, etc. UBIFS represents a separate class of file-systems
9which work with MTD devices, not block devices. The other Linux
10file-system of this class is JFFS2.
11
12To make it more clear, here is a small comparison of MTD devices and
13block devices.
14
151 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.
182 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.
223 The whole eraseblock has to be erased before it becomes possible to
23 re-write its contents. Blocks may be just re-written.
244 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.
275 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
32It should be quite obvious why UBIFS is very different to traditional
33file-systems.
34
35UBIFS works on top of UBI. UBI is a separate software layer which may be
36found in drivers/mtd/ubi. UBI is basically a volume management and
37wear-leveling layer. It provides so called UBI volumes which is a higher
38level abstraction than a MTD device. The programming model of UBI devices
39is very similar to MTD devices - they still consist of large eraseblocks,
40they have read/write/erase operations, but UBI devices are devoid of
41limitations like wear and bad blocks (items 4 and 5 in the above list).
42
43In a sense, UBIFS is a next generation of JFFS2 file-system, but it is
44very different and incompatible to JFFS2. The following are the main
45differences.
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
56Similarly to JFFS2, UBIFS supports on-the-flight compression which makes
57it possible to fit quite a lot of data to the flash.
58
59Similarly to JFFS2, UBIFS is tolerant of unclean reboots and power-cuts.
Sebastian Siewior2e244d02008-07-17 14:16:09 +020060It does not need stuff like fsck.ext2. UBIFS automatically replays its
Artem Bityutskiye56a99d2008-07-14 19:08:34 +030061journal and recovers from crashes, ensuring that the on-flash data
62structures are consistent.
63
64UBIFS scales logarithmically (most of the data structures it uses are
65trees), so the mount time and memory consumption do not linearly depend
66on the flash size, like in case of JFFS2. This is because UBIFS
67maintains the FS index on the flash media. However, UBIFS depends on
68UBI, which scales linearly. So overall UBI/UBIFS stack scales linearly.
69Nevertheless, UBI/UBIFS scales considerably better than JFFS2.
70
71The authors of UBIFS believe, that it is possible to develop UBI2 which
72would scale logarithmically as well. UBI2 would support the same API as UBI,
73but it would be binary incompatible to UBI. So UBIFS would not need to be
74changed to use UBI2
75
76
77Mount options
78=============
79
80(*) == default.
81
82norm_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;
86fast_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.
89
90
91Quick usage instructions
92========================
93
94The UBI volume to mount is specified using "ubiX_Y" or "ubiX:NAME" syntax,
95where "X" is UBI device number, "Y" is UBI volume number, and "NAME" is
96UBI volume name.
97
98Mount volume 0 on UBI device 0 to /mnt/ubifs:
99$ mount -t ubifs ubi0_0 /mnt/ubifs
100
101Mount "rootfs" volume of UBI device 0 to /mnt/ubifs ("rootfs" is volume
102name):
103$ mount -t ubifs ubi0:rootfs /mnt/ubifs
104
105The following is an example of the kernel boot arguments to attach mtd0
106to UBI and mount volume "rootfs":
107ubi.mtd=0 root=ubi0:rootfs rootfstype=ubifs
108
109
110Module Parameters for Debugging
111===============================
112
113When UBIFS has been compiled with debugging enabled, there are 3 module
114parameters that are available to control aspects of testing and debugging.
115The parameters are unsigned integers where each bit controls an option.
116The parameters are:
117
118debug_msgs Selects which debug messages to display, as follows:
119
120 Message Type Flag value
121
122 General messages 1
123 Journal messages 2
124 Mount messages 4
125 Commit messages 8
126 LEB search messages 16
127 Budgeting messages 32
128 Garbage collection messages 64
129 Tree Node Cache (TNC) messages 128
130 LEB properties (lprops) messages 256
131 Input/output messages 512
132 Log messages 1024
133 Scan messages 2048
134 Recovery messages 4096
135
136debug_chks Selects extra checks that UBIFS can do while running:
137
138 Check Flag value
139
140 General checks 1
141 Check Tree Node Cache (TNC) 2
142 Check indexing tree size 4
143 Check orphan area 8
144 Check old indexing tree 16
145 Check LEB properties (lprops) 32
146 Check leaf nodes and inodes 64
147
148debug_tsts Selects a mode of testing, as follows:
149
150 Test mode Flag value
151
152 Force in-the-gaps method 2
153 Failure mode for recovery testing 4
154
155For example, set debug_msgs to 5 to display General messages and Mount
156messages.
157
158
159References
160==========
161
162UBIFS documentation and FAQ/HOWTO at the MTD web site:
163http://www.linux-mtd.infradead.org/doc/ubifs.html
164http://www.linux-mtd.infradead.org/faq/ubifs.html