Artem Bityutskiy | e56a99d | 2008-07-14 19:08:34 +0300 | [diff] [blame] | 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 ckfs.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 | |
| 90 | |
| 91 | Quick usage instructions |
| 92 | ======================== |
| 93 | |
| 94 | The UBI volume to mount is specified using "ubiX_Y" or "ubiX:NAME" syntax, |
| 95 | where "X" is UBI device number, "Y" is UBI volume number, and "NAME" is |
| 96 | UBI volume name. |
| 97 | |
| 98 | Mount volume 0 on UBI device 0 to /mnt/ubifs: |
| 99 | $ mount -t ubifs ubi0_0 /mnt/ubifs |
| 100 | |
| 101 | Mount "rootfs" volume of UBI device 0 to /mnt/ubifs ("rootfs" is volume |
| 102 | name): |
| 103 | $ mount -t ubifs ubi0:rootfs /mnt/ubifs |
| 104 | |
| 105 | The following is an example of the kernel boot arguments to attach mtd0 |
| 106 | to UBI and mount volume "rootfs": |
| 107 | ubi.mtd=0 root=ubi0:rootfs rootfstype=ubifs |
| 108 | |
| 109 | |
| 110 | Module Parameters for Debugging |
| 111 | =============================== |
| 112 | |
| 113 | When UBIFS has been compiled with debugging enabled, there are 3 module |
| 114 | parameters that are available to control aspects of testing and debugging. |
| 115 | The parameters are unsigned integers where each bit controls an option. |
| 116 | The parameters are: |
| 117 | |
| 118 | debug_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 | |
| 136 | debug_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 | |
| 148 | debug_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 | |
| 155 | For example, set debug_msgs to 5 to display General messages and Mount |
| 156 | messages. |
| 157 | |
| 158 | |
| 159 | References |
| 160 | ========== |
| 161 | |
| 162 | UBIFS documentation and FAQ/HOWTO at the MTD web site: |
| 163 | http://www.linux-mtd.infradead.org/doc/ubifs.html |
| 164 | http://www.linux-mtd.infradead.org/faq/ubifs.html |