1.. SPDX-License-Identifier: GPL-2.0 2 3=============== 4UBI File System 5=============== 6 7Introduction 8============ 9 10UBIFS file-system stands for UBI File System. UBI stands for "Unsorted 11Block Images". UBIFS is a flash file system, which means it is designed 12to work with flash devices. It is important to understand, that UBIFS 13is completely different to any traditional file-system in Linux, like 14Ext2, XFS, JFS, etc. UBIFS represents a separate class of file-systems 15which work with MTD devices, not block devices. The other Linux 16file-system of this class is JFFS2. 17 18To make it more clear, here is a small comparison of MTD devices and 19block devices. 20 211 MTD devices represent flash devices and they consist of eraseblocks of 22 rather large size, typically about 128KiB. Block devices consist of 23 small blocks, typically 512 bytes. 242 MTD devices support 3 main operations - read from some offset within an 25 eraseblock, write to some offset within an eraseblock, and erase a whole 26 eraseblock. Block devices support 2 main operations - read a whole 27 block and write a whole block. 283 The whole eraseblock has to be erased before it becomes possible to 29 re-write its contents. Blocks may be just re-written. 304 Eraseblocks become worn out after some number of erase cycles - 31 typically 100K-1G for SLC NAND and NOR flashes, and 1K-10K for MLC 32 NAND flashes. Blocks do not have the wear-out property. 335 Eraseblocks may become bad (only on NAND flashes) and software should 34 deal with this. Blocks on hard drives typically do not become bad, 35 because hardware has mechanisms to substitute bad blocks, at least in 36 modern LBA disks. 37 38It should be quite obvious why UBIFS is very different to traditional 39file-systems. 40 41UBIFS works on top of UBI. UBI is a separate software layer which may be 42found in drivers/mtd/ubi. UBI is basically a volume management and 43wear-leveling layer. It provides so called UBI volumes which is a higher 44level abstraction than a MTD device. The programming model of UBI devices 45is very similar to MTD devices - they still consist of large eraseblocks, 46they have read/write/erase operations, but UBI devices are devoid of 47limitations like wear and bad blocks (items 4 and 5 in the above list). 48 49In a sense, UBIFS is a next generation of JFFS2 file-system, but it is 50very different and incompatible to JFFS2. The following are the main 51differences. 52 53* JFFS2 works on top of MTD devices, UBIFS depends on UBI and works on 54 top of UBI volumes. 55* JFFS2 does not have on-media index and has to build it while mounting, 56 which requires full media scan. UBIFS maintains the FS indexing 57 information on the flash media and does not require full media scan, 58 so it mounts many times faster than JFFS2. 59* JFFS2 is a write-through file-system, while UBIFS supports write-back, 60 which makes UBIFS much faster on writes. 61 62Similarly to JFFS2, UBIFS supports on-the-flight compression which makes 63it possible to fit quite a lot of data to the flash. 64 65Similarly to JFFS2, UBIFS is tolerant of unclean reboots and power-cuts. 66It does not need stuff like fsck.ext2. UBIFS automatically replays its 67journal and recovers from crashes, ensuring that the on-flash data 68structures are consistent. 69 70UBIFS scales logarithmically (most of the data structures it uses are 71trees), so the mount time and memory consumption do not linearly depend 72on the flash size, like in case of JFFS2. This is because UBIFS 73maintains the FS index on the flash media. However, UBIFS depends on 74UBI, which scales linearly. So overall UBI/UBIFS stack scales linearly. 75Nevertheless, UBI/UBIFS scales considerably better than JFFS2. 76 77The authors of UBIFS believe, that it is possible to develop UBI2 which 78would scale logarithmically as well. UBI2 would support the same API as UBI, 79but it would be binary incompatible to UBI. So UBIFS would not need to be 80changed to use UBI2 81 82 83Mount options 84============= 85 86(*) == default. 87 88==================== ======================================================= 89bulk_read read more in one go to take advantage of flash 90 media that read faster sequentially 91no_bulk_read (*) do not bulk-read 92no_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. 97chk_data_crc do not skip checking CRCs on data nodes 98compr=none override default compressor and set it to "none" 99compr=lzo override default compressor and set it to "lzo" 100compr=zlib override default compressor and set it to "zlib" 101auth_key= specify the key used for authenticating the filesystem. 102 Passing this option makes authentication mandatory. 103 The passed key must be present in the kernel keyring 104 and must be of type 'logon' 105auth_hash_name= The hash algorithm used for authentication. Used for 106 both hashing and for creating HMACs. Typical values 107 include "sha256" or "sha512" 108==================== ======================================================= 109 110 111Quick usage instructions 112======================== 113 114The UBI volume to mount is specified using "ubiX_Y" or "ubiX:NAME" syntax, 115where "X" is UBI device number, "Y" is UBI volume number, and "NAME" is 116UBI volume name. 117 118Mount volume 0 on UBI device 0 to /mnt/ubifs:: 119 120 $ mount -t ubifs ubi0_0 /mnt/ubifs 121 122Mount "rootfs" volume of UBI device 0 to /mnt/ubifs ("rootfs" is volume 123name):: 124 125 $ mount -t ubifs ubi0:rootfs /mnt/ubifs 126 127The following is an example of the kernel boot arguments to attach mtd0 128to UBI and mount volume "rootfs": 129ubi.mtd=0 root=ubi0:rootfs rootfstype=ubifs 130 131References 132========== 133 134UBIFS documentation and FAQ/HOWTO at the MTD web site: 135 136- http://www.linux-mtd.infradead.org/doc/ubifs.html 137- http://www.linux-mtd.infradead.org/faq/ubifs.html 138