Documentation/filesystems/ubifs.txt

   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.
  60 It does not need stuff like fsck.ext2. UBIFS automatically replays its
  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.
  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
  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
  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"
 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