[deliverable/linux.git] / Documentation / filesystems / ubifs.txt

Introduction
=============

UBIFS file-system stands for UBI File System. UBI stands for "Unsorted
Block Images". UBIFS is a flash file system, which means it is designed
to work with flash devices. It is important to understand, that UBIFS
is completely different to any traditional file-system in Linux, like
Ext2, XFS, JFS, etc. UBIFS represents a separate class of file-systems
which work with MTD devices, not block devices. The other Linux
file-system of this class is JFFS2.

To make it more clear, here is a small comparison of MTD devices and
block devices.

1 MTD devices represent flash devices and they consist of eraseblocks of
  rather large size, typically about 128KiB. Block devices consist of
  small blocks, typically 512 bytes.
2 MTD devices support 3 main operations - read from some offset within an
  eraseblock, write to some offset within an eraseblock, and erase a whole
  eraseblock. Block  devices support 2 main operations - read a whole
  block and write a whole block.
3 The whole eraseblock has to be erased before it becomes possible to
  re-write its contents. Blocks may be just re-written.
4 Eraseblocks become worn out after some number of erase cycles -
  typically 100K-1G for SLC NAND and NOR flashes, and 1K-10K for MLC
  NAND flashes. Blocks do not have the wear-out property.
5 Eraseblocks may become bad (only on NAND flashes) and software should
  deal with this. Blocks on hard drives typically do not become bad,
  because hardware has mechanisms to substitute bad blocks, at least in
  modern LBA disks.

It should be quite obvious why UBIFS is very different to traditional
file-systems.

UBIFS works on top of UBI. UBI is a separate software layer which may be
found in drivers/mtd/ubi. UBI is basically a volume management and
wear-leveling layer. It provides so called UBI volumes which is a higher
level abstraction than a MTD device. The programming model of UBI devices
is very similar to MTD devices - they still consist of large eraseblocks,
they have read/write/erase operations, but UBI devices are devoid of
limitations like wear and bad blocks (items 4 and 5 in the above list).

In a sense, UBIFS is a next generation of JFFS2 file-system, but it is
very different and incompatible to JFFS2. The following are the main
differences.

* JFFS2 works on top of MTD devices, UBIFS depends on UBI and works on
  top of UBI volumes.
* JFFS2 does not have on-media index and has to build it while mounting,
  which requires full media scan. UBIFS maintains the FS indexing
  information on the flash media and does not require full media scan,
  so it mounts many times faster than JFFS2.
* JFFS2 is a write-through file-system, while UBIFS supports write-back,
  which makes UBIFS much faster on writes.

Similarly to JFFS2, UBIFS supports on-the-flight compression which makes
it possible to fit quite a lot of data to the flash.

Similarly to JFFS2, UBIFS is tolerant of unclean reboots and power-cuts.
It does not need stuff like fsck.ext2. UBIFS automatically replays its
journal and recovers from crashes, ensuring that the on-flash data
structures are consistent.

UBIFS scales logarithmically (most of the data structures it uses are
trees), so the mount time and memory consumption do not linearly depend
on the flash size, like in case of JFFS2. This is because UBIFS
maintains the FS index on the flash media. However, UBIFS depends on
UBI, which scales linearly. So overall UBI/UBIFS stack scales linearly.
Nevertheless, UBI/UBIFS scales considerably better than JFFS2.

The authors of UBIFS believe, that it is possible to develop UBI2 which
would scale logarithmically as well. UBI2 would support the same API as UBI,
but it would be binary incompatible to UBI. So UBIFS would not need to be
changed to use UBI2


Mount options
=============

(*) == default.

norm_unmount (*)	commit on unmount; the journal is committed
			when the file-system is unmounted so that the
			next mount does not have to replay the journal
			and it becomes very fast;
fast_unmount		do not commit on unmount; this option makes
			unmount faster, but the next mount slower
			because of the need to replay the journal.
bulk_read		read more in one go to take advantage of flash
			media that read faster sequentially
no_bulk_read (*)	do not bulk-read
no_chk_data_crc		skip checking of CRCs on data nodes in order to
			improve read performance. Use this option only
			if the flash media is highly reliable. The effect
			of this option is that corruption of the contents
			of a file can go unnoticed.
chk_data_crc (*)	do not skip checking CRCs on data nodes
compr=none              override default compressor and set it to "none"
compr=lzo               override default compressor and set it to "lzo"
compr=zlib              override default compressor and set it to "zlib"


Quick usage instructions
========================

The UBI volume to mount is specified using "ubiX_Y" or "ubiX:NAME" syntax,
where "X" is UBI device number, "Y" is UBI volume number, and "NAME" is
UBI volume name.

Mount volume 0 on UBI device 0 to /mnt/ubifs:
$ mount -t ubifs ubi0_0 /mnt/ubifs

Mount "rootfs" volume of UBI device 0 to /mnt/ubifs ("rootfs" is volume
name):
$ mount -t ubifs ubi0:rootfs /mnt/ubifs

The following is an example of the kernel boot arguments to attach mtd0
to UBI and mount volume "rootfs":
ubi.mtd=0 root=ubi0:rootfs rootfstype=ubifs


Module Parameters for Debugging
===============================

When UBIFS has been compiled with debugging enabled, there are 3 module
parameters that are available to control aspects of testing and debugging.
The parameters are unsigned integers where each bit controls an option.
The parameters are:

debug_msgs	Selects which debug messages to display, as follows:

		Message Type				Flag value

		General messages			1
		Journal messages			2
		Mount messages				4
		Commit messages				8
		LEB search messages			16
		Budgeting messages			32
		Garbage collection messages		64
		Tree Node Cache (TNC) messages		128
		LEB properties (lprops) messages	256
		Input/output messages			512
		Log messages				1024
		Scan messages				2048
		Recovery messages			4096

debug_chks	Selects extra checks that UBIFS can do while running:

		Check					Flag value

		General checks				1
		Check Tree Node Cache (TNC)		2
		Check indexing tree size		4
		Check orphan area			8
		Check old indexing tree			16
		Check LEB properties (lprops)		32
		Check leaf nodes and inodes		64

debug_tsts	Selects a mode of testing, as follows:

		Test mode				Flag value

		Force in-the-gaps method		2
		Failure mode for recovery testing	4

For example, set debug_msgs to 5 to display General messages and Mount
messages.


References
==========

UBIFS documentation and FAQ/HOWTO at the MTD web site:
http://www.linux-mtd.infradead.org/doc/ubifs.html
http://www.linux-mtd.infradead.org/faq/ubifs.html
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
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"
e56a99d5 AB	101
	102
	103	Quick usage instructions
	104	========================
	105
	106	The UBI volume to mount is specified using "ubiX_Y" or "ubiX:NAME" syntax,
	107	where "X" is UBI device number, "Y" is UBI volume number, and "NAME" is
	108	UBI volume name.
	109
	110	Mount volume 0 on UBI device 0 to /mnt/ubifs:
	111	$ mount -t ubifs ubi0_0 /mnt/ubifs
	112
	113	Mount "rootfs" volume of UBI device 0 to /mnt/ubifs ("rootfs" is volume
	114	name):
	115	$ mount -t ubifs ubi0:rootfs /mnt/ubifs
	116
	117	The following is an example of the kernel boot arguments to attach mtd0
	118	to UBI and mount volume "rootfs":
	119	ubi.mtd=0 root=ubi0:rootfs rootfstype=ubifs
	120
	121
	122	Module Parameters for Debugging
	123	===============================
	124
	125	When UBIFS has been compiled with debugging enabled, there are 3 module
	126	parameters that are available to control aspects of testing and debugging.
	127	The parameters are unsigned integers where each bit controls an option.
	128	The parameters are:
	129
	130	debug_msgs Selects which debug messages to display, as follows:
	131
	132	Message Type Flag value
	133
	134	General messages 1
	135	Journal messages 2
	136	Mount messages 4
	137	Commit messages 8
	138	LEB search messages 16
	139	Budgeting messages 32
	140	Garbage collection messages 64
	141	Tree Node Cache (TNC) messages 128
	142	LEB properties (lprops) messages 256
	143	Input/output messages 512
	144	Log messages 1024
	145	Scan messages 2048
	146	Recovery messages 4096
	147
	148	debug_chks Selects extra checks that UBIFS can do while running:
	149
	150	Check Flag value
	151
	152	General checks 1
	153	Check Tree Node Cache (TNC) 2
	154	Check indexing tree size 4
	155	Check orphan area 8
	156	Check old indexing tree 16
	157	Check LEB properties (lprops) 32
	158	Check leaf nodes and inodes 64
	159
	160	debug_tsts Selects a mode of testing, as follows:
	161
	162	Test mode Flag value
	163
	164	Force in-the-gaps method 2
165	Failure mode for recovery testing 4
166
167	For example, set debug_msgs to 5 to display General messages and Mount
168	messages.
169
170
171	References
172	==========
173
174	UBIFS documentation and FAQ/HOWTO at the MTD web site:
175	http://www.linux-mtd.infradead.org/doc/ubifs.html
176	http://www.linux-mtd.infradead.org/faq/ubifs.html