0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ===============
0004 UBI File System
0005 ===============
0006
0007 Introduction
0008 ============
0009
0010 UBIFS file-system stands for UBI File System. UBI stands for "Unsorted
0011 Block Images". UBIFS is a flash file system, which means it is designed
0012 to work with flash devices. It is important to understand, that UBIFS
0013 is completely different to any traditional file-system in Linux, like
0014 Ext2, XFS, JFS, etc. UBIFS represents a separate class of file-systems
0015 which work with MTD devices, not block devices. The other Linux
0016 file-system of this class is JFFS2.
0017
0018 To make it more clear, here is a small comparison of MTD devices and
0019 block devices.
0020
0021 1 MTD devices represent flash devices and they consist of eraseblocks of
0022 rather large size, typically about 128KiB. Block devices consist of
0023 small blocks, typically 512 bytes.
0024 2 MTD devices support 3 main operations - read from some offset within an
0025 eraseblock, write to some offset within an eraseblock, and erase a whole
0026 eraseblock. Block devices support 2 main operations - read a whole
0027 block and write a whole block.
0028 3 The whole eraseblock has to be erased before it becomes possible to
0029 re-write its contents. Blocks may be just re-written.
0030 4 Eraseblocks become worn out after some number of erase cycles -
0031 typically 100K-1G for SLC NAND and NOR flashes, and 1K-10K for MLC
0032 NAND flashes. Blocks do not have the wear-out property.
0033 5 Eraseblocks may become bad (only on NAND flashes) and software should
0034 deal with this. Blocks on hard drives typically do not become bad,
0035 because hardware has mechanisms to substitute bad blocks, at least in
0036 modern LBA disks.
0037
0038 It should be quite obvious why UBIFS is very different to traditional
0039 file-systems.
0040
0041 UBIFS works on top of UBI. UBI is a separate software layer which may be
0042 found in drivers/mtd/ubi. UBI is basically a volume management and
0043 wear-leveling layer. It provides so called UBI volumes which is a higher
0044 level abstraction than a MTD device. The programming model of UBI devices
0045 is very similar to MTD devices - they still consist of large eraseblocks,
0046 they have read/write/erase operations, but UBI devices are devoid of
0047 limitations like wear and bad blocks (items 4 and 5 in the above list).
0048
0049 In a sense, UBIFS is a next generation of JFFS2 file-system, but it is
0050 very different and incompatible to JFFS2. The following are the main
0051 differences.
0052
0053 * JFFS2 works on top of MTD devices, UBIFS depends on UBI and works on
0054 top of UBI volumes.
0055 * JFFS2 does not have on-media index and has to build it while mounting,
0056 which requires full media scan. UBIFS maintains the FS indexing
0057 information on the flash media and does not require full media scan,
0058 so it mounts many times faster than JFFS2.
0059 * JFFS2 is a write-through file-system, while UBIFS supports write-back,
0060 which makes UBIFS much faster on writes.
0061
0062 Similarly to JFFS2, UBIFS supports on-the-flight compression which makes
0063 it possible to fit quite a lot of data to the flash.
0064
0065 Similarly to JFFS2, UBIFS is tolerant of unclean reboots and power-cuts.
0066 It does not need stuff like fsck.ext2. UBIFS automatically replays its
0067 journal and recovers from crashes, ensuring that the on-flash data
0068 structures are consistent.
0069
0070 UBIFS scales logarithmically (most of the data structures it uses are
0071 trees), so the mount time and memory consumption do not linearly depend
0072 on the flash size, like in case of JFFS2. This is because UBIFS
0073 maintains the FS index on the flash media. However, UBIFS depends on
0074 UBI, which scales linearly. So overall UBI/UBIFS stack scales linearly.
0075 Nevertheless, UBI/UBIFS scales considerably better than JFFS2.
0076
0077 The authors of UBIFS believe, that it is possible to develop UBI2 which
0078 would scale logarithmically as well. UBI2 would support the same API as UBI,
0079 but it would be binary incompatible to UBI. So UBIFS would not need to be
0080 changed to use UBI2
0081
0082
0083 Mount options
0084 =============
0085
0086 (*) == default.
0087
0088 ==================== =======================================================
0089 bulk_read read more in one go to take advantage of flash
0090 media that read faster sequentially
0091 no_bulk_read (*) do not bulk-read
0092 no_chk_data_crc (*) skip checking of CRCs on data nodes in order to
0093 improve read performance. Use this option only
0094 if the flash media is highly reliable. The effect
0095 of this option is that corruption of the contents
0096 of a file can go unnoticed.
0097 chk_data_crc do not skip checking CRCs on data nodes
0098 compr=none override default compressor and set it to "none"
0099 compr=lzo override default compressor and set it to "lzo"
0100 compr=zlib override default compressor and set it to "zlib"
0101 auth_key= specify the key used for authenticating the filesystem.
0102 Passing this option makes authentication mandatory.
0103 The passed key must be present in the kernel keyring
0104 and must be of type 'logon'
0105 auth_hash_name= The hash algorithm used for authentication. Used for
0106 both hashing and for creating HMACs. Typical values
0107 include "sha256" or "sha512"
0108 ==================== =======================================================
0109
0110
0111 Quick usage instructions
0112 ========================
0113
0114 The UBI volume to mount is specified using "ubiX_Y" or "ubiX:NAME" syntax,
0115 where "X" is UBI device number, "Y" is UBI volume number, and "NAME" is
0116 UBI volume name.
0117
0118 Mount volume 0 on UBI device 0 to /mnt/ubifs::
0119
0120 $ mount -t ubifs ubi0_0 /mnt/ubifs
0121
0122 Mount "rootfs" volume of UBI device 0 to /mnt/ubifs ("rootfs" is volume
0123 name)::
0124
0125 $ mount -t ubifs ubi0:rootfs /mnt/ubifs
0126
0127 The following is an example of the kernel boot arguments to attach mtd0
0128 to UBI and mount volume "rootfs":
0129 ubi.mtd=0 root=ubi0:rootfs rootfstype=ubifs
0130
0131 References
0132 ==========
0133
0134 UBIFS documentation and FAQ/HOWTO at the MTD web site:
0135
0136 - http://www.linux-mtd.infradead.org/doc/ubifs.html
0137 - http://www.linux-mtd.infradead.org/faq/ubifs.html
