UBIFS: add brief documentation

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 ckfs.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.

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