138e56b4eSMauro Carvalho Chehab.. SPDX-License-Identifier: GPL-2.0 238e56b4eSMauro Carvalho Chehab 338e56b4eSMauro Carvalho Chehab=============== 438e56b4eSMauro Carvalho ChehabUBI File System 538e56b4eSMauro Carvalho Chehab=============== 638e56b4eSMauro Carvalho Chehab 738e56b4eSMauro Carvalho ChehabIntroduction 838e56b4eSMauro Carvalho Chehab============ 938e56b4eSMauro Carvalho Chehab 1038e56b4eSMauro Carvalho ChehabUBIFS file-system stands for UBI File System. UBI stands for "Unsorted 1138e56b4eSMauro Carvalho ChehabBlock Images". UBIFS is a flash file system, which means it is designed 1238e56b4eSMauro Carvalho Chehabto work with flash devices. It is important to understand, that UBIFS 1338e56b4eSMauro Carvalho Chehabis completely different to any traditional file-system in Linux, like 1438e56b4eSMauro Carvalho ChehabExt2, XFS, JFS, etc. UBIFS represents a separate class of file-systems 1538e56b4eSMauro Carvalho Chehabwhich work with MTD devices, not block devices. The other Linux 1638e56b4eSMauro Carvalho Chehabfile-system of this class is JFFS2. 1738e56b4eSMauro Carvalho Chehab 1838e56b4eSMauro Carvalho ChehabTo make it more clear, here is a small comparison of MTD devices and 1938e56b4eSMauro Carvalho Chehabblock devices. 2038e56b4eSMauro Carvalho Chehab 2138e56b4eSMauro Carvalho Chehab1 MTD devices represent flash devices and they consist of eraseblocks of 2238e56b4eSMauro Carvalho Chehab rather large size, typically about 128KiB. Block devices consist of 2338e56b4eSMauro Carvalho Chehab small blocks, typically 512 bytes. 2438e56b4eSMauro Carvalho Chehab2 MTD devices support 3 main operations - read from some offset within an 2538e56b4eSMauro Carvalho Chehab eraseblock, write to some offset within an eraseblock, and erase a whole 2638e56b4eSMauro Carvalho Chehab eraseblock. Block devices support 2 main operations - read a whole 2738e56b4eSMauro Carvalho Chehab block and write a whole block. 2838e56b4eSMauro Carvalho Chehab3 The whole eraseblock has to be erased before it becomes possible to 2938e56b4eSMauro Carvalho Chehab re-write its contents. Blocks may be just re-written. 3038e56b4eSMauro Carvalho Chehab4 Eraseblocks become worn out after some number of erase cycles - 3138e56b4eSMauro Carvalho Chehab typically 100K-1G for SLC NAND and NOR flashes, and 1K-10K for MLC 3238e56b4eSMauro Carvalho Chehab NAND flashes. Blocks do not have the wear-out property. 3338e56b4eSMauro Carvalho Chehab5 Eraseblocks may become bad (only on NAND flashes) and software should 3438e56b4eSMauro Carvalho Chehab deal with this. Blocks on hard drives typically do not become bad, 3538e56b4eSMauro Carvalho Chehab because hardware has mechanisms to substitute bad blocks, at least in 3638e56b4eSMauro Carvalho Chehab modern LBA disks. 3738e56b4eSMauro Carvalho Chehab 3838e56b4eSMauro Carvalho ChehabIt should be quite obvious why UBIFS is very different to traditional 3938e56b4eSMauro Carvalho Chehabfile-systems. 4038e56b4eSMauro Carvalho Chehab 4138e56b4eSMauro Carvalho ChehabUBIFS works on top of UBI. UBI is a separate software layer which may be 4238e56b4eSMauro Carvalho Chehabfound in drivers/mtd/ubi. UBI is basically a volume management and 4338e56b4eSMauro Carvalho Chehabwear-leveling layer. It provides so called UBI volumes which is a higher 4438e56b4eSMauro Carvalho Chehablevel abstraction than a MTD device. The programming model of UBI devices 4538e56b4eSMauro Carvalho Chehabis very similar to MTD devices - they still consist of large eraseblocks, 4638e56b4eSMauro Carvalho Chehabthey have read/write/erase operations, but UBI devices are devoid of 4738e56b4eSMauro Carvalho Chehablimitations like wear and bad blocks (items 4 and 5 in the above list). 4838e56b4eSMauro Carvalho Chehab 4938e56b4eSMauro Carvalho ChehabIn a sense, UBIFS is a next generation of JFFS2 file-system, but it is 5038e56b4eSMauro Carvalho Chehabvery different and incompatible to JFFS2. The following are the main 5138e56b4eSMauro Carvalho Chehabdifferences. 5238e56b4eSMauro Carvalho Chehab 5338e56b4eSMauro Carvalho Chehab* JFFS2 works on top of MTD devices, UBIFS depends on UBI and works on 5438e56b4eSMauro Carvalho Chehab top of UBI volumes. 5538e56b4eSMauro Carvalho Chehab* JFFS2 does not have on-media index and has to build it while mounting, 5638e56b4eSMauro Carvalho Chehab which requires full media scan. UBIFS maintains the FS indexing 5738e56b4eSMauro Carvalho Chehab information on the flash media and does not require full media scan, 5838e56b4eSMauro Carvalho Chehab so it mounts many times faster than JFFS2. 5938e56b4eSMauro Carvalho Chehab* JFFS2 is a write-through file-system, while UBIFS supports write-back, 6038e56b4eSMauro Carvalho Chehab which makes UBIFS much faster on writes. 6138e56b4eSMauro Carvalho Chehab 62*5f5cae9bSJoel StanleySimilarly to JFFS2, UBIFS supports on-the-fly compression which makes 6338e56b4eSMauro Carvalho Chehabit possible to fit quite a lot of data to the flash. 6438e56b4eSMauro Carvalho Chehab 6538e56b4eSMauro Carvalho ChehabSimilarly to JFFS2, UBIFS is tolerant of unclean reboots and power-cuts. 6638e56b4eSMauro Carvalho ChehabIt does not need stuff like fsck.ext2. UBIFS automatically replays its 6738e56b4eSMauro Carvalho Chehabjournal and recovers from crashes, ensuring that the on-flash data 6838e56b4eSMauro Carvalho Chehabstructures are consistent. 6938e56b4eSMauro Carvalho Chehab 7038e56b4eSMauro Carvalho ChehabUBIFS scales logarithmically (most of the data structures it uses are 7138e56b4eSMauro Carvalho Chehabtrees), so the mount time and memory consumption do not linearly depend 7238e56b4eSMauro Carvalho Chehabon the flash size, like in case of JFFS2. This is because UBIFS 7338e56b4eSMauro Carvalho Chehabmaintains the FS index on the flash media. However, UBIFS depends on 7438e56b4eSMauro Carvalho ChehabUBI, which scales linearly. So overall UBI/UBIFS stack scales linearly. 7538e56b4eSMauro Carvalho ChehabNevertheless, UBI/UBIFS scales considerably better than JFFS2. 7638e56b4eSMauro Carvalho Chehab 7738e56b4eSMauro Carvalho ChehabThe authors of UBIFS believe, that it is possible to develop UBI2 which 7838e56b4eSMauro Carvalho Chehabwould scale logarithmically as well. UBI2 would support the same API as UBI, 7938e56b4eSMauro Carvalho Chehabbut it would be binary incompatible to UBI. So UBIFS would not need to be 8038e56b4eSMauro Carvalho Chehabchanged to use UBI2 8138e56b4eSMauro Carvalho Chehab 8238e56b4eSMauro Carvalho Chehab 8338e56b4eSMauro Carvalho ChehabMount options 8438e56b4eSMauro Carvalho Chehab============= 8538e56b4eSMauro Carvalho Chehab 8638e56b4eSMauro Carvalho Chehab(*) == default. 8738e56b4eSMauro Carvalho Chehab 8838e56b4eSMauro Carvalho Chehab==================== ======================================================= 8938e56b4eSMauro Carvalho Chehabbulk_read read more in one go to take advantage of flash 9038e56b4eSMauro Carvalho Chehab media that read faster sequentially 9138e56b4eSMauro Carvalho Chehabno_bulk_read (*) do not bulk-read 9238e56b4eSMauro Carvalho Chehabno_chk_data_crc (*) skip checking of CRCs on data nodes in order to 9338e56b4eSMauro Carvalho Chehab improve read performance. Use this option only 9438e56b4eSMauro Carvalho Chehab if the flash media is highly reliable. The effect 9538e56b4eSMauro Carvalho Chehab of this option is that corruption of the contents 9638e56b4eSMauro Carvalho Chehab of a file can go unnoticed. 9738e56b4eSMauro Carvalho Chehabchk_data_crc do not skip checking CRCs on data nodes 9838e56b4eSMauro Carvalho Chehabcompr=none override default compressor and set it to "none" 9938e56b4eSMauro Carvalho Chehabcompr=lzo override default compressor and set it to "lzo" 10038e56b4eSMauro Carvalho Chehabcompr=zlib override default compressor and set it to "zlib" 10138e56b4eSMauro Carvalho Chehabauth_key= specify the key used for authenticating the filesystem. 10238e56b4eSMauro Carvalho Chehab Passing this option makes authentication mandatory. 10338e56b4eSMauro Carvalho Chehab The passed key must be present in the kernel keyring 10438e56b4eSMauro Carvalho Chehab and must be of type 'logon' 10538e56b4eSMauro Carvalho Chehabauth_hash_name= The hash algorithm used for authentication. Used for 10638e56b4eSMauro Carvalho Chehab both hashing and for creating HMACs. Typical values 10738e56b4eSMauro Carvalho Chehab include "sha256" or "sha512" 10838e56b4eSMauro Carvalho Chehab==================== ======================================================= 10938e56b4eSMauro Carvalho Chehab 11038e56b4eSMauro Carvalho Chehab 11138e56b4eSMauro Carvalho ChehabQuick usage instructions 11238e56b4eSMauro Carvalho Chehab======================== 11338e56b4eSMauro Carvalho Chehab 11438e56b4eSMauro Carvalho ChehabThe UBI volume to mount is specified using "ubiX_Y" or "ubiX:NAME" syntax, 11538e56b4eSMauro Carvalho Chehabwhere "X" is UBI device number, "Y" is UBI volume number, and "NAME" is 11638e56b4eSMauro Carvalho ChehabUBI volume name. 11738e56b4eSMauro Carvalho Chehab 11838e56b4eSMauro Carvalho ChehabMount volume 0 on UBI device 0 to /mnt/ubifs:: 11938e56b4eSMauro Carvalho Chehab 12038e56b4eSMauro Carvalho Chehab $ mount -t ubifs ubi0_0 /mnt/ubifs 12138e56b4eSMauro Carvalho Chehab 12238e56b4eSMauro Carvalho ChehabMount "rootfs" volume of UBI device 0 to /mnt/ubifs ("rootfs" is volume 12338e56b4eSMauro Carvalho Chehabname):: 12438e56b4eSMauro Carvalho Chehab 12538e56b4eSMauro Carvalho Chehab $ mount -t ubifs ubi0:rootfs /mnt/ubifs 12638e56b4eSMauro Carvalho Chehab 12738e56b4eSMauro Carvalho ChehabThe following is an example of the kernel boot arguments to attach mtd0 12838e56b4eSMauro Carvalho Chehabto UBI and mount volume "rootfs": 12938e56b4eSMauro Carvalho Chehabubi.mtd=0 root=ubi0:rootfs rootfstype=ubifs 13038e56b4eSMauro Carvalho Chehab 13138e56b4eSMauro Carvalho ChehabReferences 13238e56b4eSMauro Carvalho Chehab========== 13338e56b4eSMauro Carvalho Chehab 13438e56b4eSMauro Carvalho ChehabUBIFS documentation and FAQ/HOWTO at the MTD web site: 13538e56b4eSMauro Carvalho Chehab 13638e56b4eSMauro Carvalho Chehab- http://www.linux-mtd.infradead.org/doc/ubifs.html 13738e56b4eSMauro Carvalho Chehab- http://www.linux-mtd.infradead.org/faq/ubifs.html 138