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