From 38e56b4ec44139b5781d6ff13f1b422e4b38f0d4 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 17 Feb 2020 17:12:28 +0100 Subject: docs: filesystems: convert ubifs.txt to ReST - Add a SPDX header; - Add a document title; - Adjust section titles; - Some whitespace fixes and new line breaks; - Mark literal blocks as such; - Add table markups; - Add lists markups; - Add it to filesystems/index.rst. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/9043dc2965cafc64e6a521e2317c00ecc8303bf6.1581955849.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- Documentation/filesystems/index.rst | 1 + Documentation/filesystems/ubifs.rst | 137 ++++++++++++++++++++++++++++++++++++ Documentation/filesystems/ubifs.txt | 126 --------------------------------- 3 files changed, 138 insertions(+), 126 deletions(-) create mode 100644 Documentation/filesystems/ubifs.rst delete mode 100644 Documentation/filesystems/ubifs.txt (limited to 'Documentation') diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst index bb14738df358..58d57c9bf922 100644 --- a/Documentation/filesystems/index.rst +++ b/Documentation/filesystems/index.rst @@ -90,6 +90,7 @@ Documentation for filesystem implementations. sysfs sysv-fs tmpfs + ubifs ubifs-authentication.rst virtiofs vfat diff --git a/Documentation/filesystems/ubifs.rst b/Documentation/filesystems/ubifs.rst new file mode 100644 index 000000000000..e6ee99762534 --- /dev/null +++ b/Documentation/filesystems/ubifs.rst @@ -0,0 +1,137 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=============== +UBI File System +=============== + +Introduction +============ + +UBIFS file-system stands for UBI File System. UBI stands for "Unsorted +Block Images". UBIFS is a flash file system, which means it is designed +to work with flash devices. It is important to understand, that UBIFS +is completely different to any traditional file-system in Linux, like +Ext2, XFS, JFS, etc. UBIFS represents a separate class of file-systems +which work with MTD devices, not block devices. The other Linux +file-system of this class is JFFS2. + +To make it more clear, here is a small comparison of MTD devices and +block devices. + +1 MTD devices represent flash devices and they consist of eraseblocks of + rather large size, typically about 128KiB. Block devices consist of + small blocks, typically 512 bytes. +2 MTD devices support 3 main operations - read from some offset within an + eraseblock, write to some offset within an eraseblock, and erase a whole + eraseblock. Block devices support 2 main operations - read a whole + block and write a whole block. +3 The whole eraseblock has to be erased before it becomes possible to + re-write its contents. Blocks may be just re-written. +4 Eraseblocks become worn out after some number of erase cycles - + typically 100K-1G for SLC NAND and NOR flashes, and 1K-10K for MLC + NAND flashes. Blocks do not have the wear-out property. +5 Eraseblocks may become bad (only on NAND flashes) and software should + deal with this. Blocks on hard drives typically do not become bad, + because hardware has mechanisms to substitute bad blocks, at least in + modern LBA disks. + +It should be quite obvious why UBIFS is very different to traditional +file-systems. + +UBIFS works on top of UBI. UBI is a separate software layer which may be +found in drivers/mtd/ubi. UBI is basically a volume management and +wear-leveling layer. It provides so called UBI volumes which is a higher +level abstraction than a MTD device. The programming model of UBI devices +is very similar to MTD devices - they still consist of large eraseblocks, +they have read/write/erase operations, but UBI devices are devoid of +limitations like wear and bad blocks (items 4 and 5 in the above list). + +In a sense, UBIFS is a next generation of JFFS2 file-system, but it is +very different and incompatible to JFFS2. The following are the main +differences. + +* JFFS2 works on top of MTD devices, UBIFS depends on UBI and works on + top of UBI volumes. +* JFFS2 does not have on-media index and has to build it while mounting, + which requires full media scan. UBIFS maintains the FS indexing + information on the flash media and does not require full media scan, + so it mounts many times faster than JFFS2. +* JFFS2 is a write-through file-system, while UBIFS supports write-back, + which makes UBIFS much faster on writes. + +Similarly to JFFS2, UBIFS supports on-the-flight compression which makes +it possible to fit quite a lot of data to the flash. + +Similarly to JFFS2, UBIFS is tolerant of unclean reboots and power-cuts. +It does not need stuff like fsck.ext2. UBIFS automatically replays its +journal and recovers from crashes, ensuring that the on-flash data +structures are consistent. + +UBIFS scales logarithmically (most of the data structures it uses are +trees), so the mount time and memory consumption do not linearly depend +on the flash size, like in case of JFFS2. This is because UBIFS +maintains the FS index on the flash media. However, UBIFS depends on +UBI, which scales linearly. So overall UBI/UBIFS stack scales linearly. +Nevertheless, UBI/UBIFS scales considerably better than JFFS2. + +The authors of UBIFS believe, that it is possible to develop UBI2 which +would scale logarithmically as well. UBI2 would support the same API as UBI, +but it would be binary incompatible to UBI. So UBIFS would not need to be +changed to use UBI2 + + +Mount options +============= + +(*) == default. + +==================== ======================================================= +bulk_read read more in one go to take advantage of flash + media that read faster sequentially +no_bulk_read (*) do not bulk-read +no_chk_data_crc (*) skip checking of CRCs on data nodes in order to + improve read performance. Use this option only + if the flash media is highly reliable. The effect + of this option is that corruption of the contents + of a file can go unnoticed. +chk_data_crc do not skip checking CRCs on data nodes +compr=none override default compressor and set it to "none" +compr=lzo override default compressor and set it to "lzo" +compr=zlib override default compressor and set it to "zlib" +auth_key= specify the key used for authenticating the filesystem. + Passing this option makes authentication mandatory. + The passed key must be present in the kernel keyring + and must be of type 'logon' +auth_hash_name= The hash algorithm used for authentication. Used for + both hashing and for creating HMACs. Typical values + include "sha256" or "sha512" +==================== ======================================================= + + +Quick usage instructions +======================== + +The UBI volume to mount is specified using "ubiX_Y" or "ubiX:NAME" syntax, +where "X" is UBI device number, "Y" is UBI volume number, and "NAME" is +UBI volume name. + +Mount volume 0 on UBI device 0 to /mnt/ubifs:: + + $ mount -t ubifs ubi0_0 /mnt/ubifs + +Mount "rootfs" volume of UBI device 0 to /mnt/ubifs ("rootfs" is volume +name):: + + $ mount -t ubifs ubi0:rootfs /mnt/ubifs + +The following is an example of the kernel boot arguments to attach mtd0 +to UBI and mount volume "rootfs": +ubi.mtd=0 root=ubi0:rootfs rootfstype=ubifs + +References +========== + +UBIFS documentation and FAQ/HOWTO at the MTD web site: + +- http://www.linux-mtd.infradead.org/doc/ubifs.html +- http://www.linux-mtd.infradead.org/faq/ubifs.html diff --git a/Documentation/filesystems/ubifs.txt b/Documentation/filesystems/ubifs.txt deleted file mode 100644 index acc80442a3bb..000000000000 --- a/Documentation/filesystems/ubifs.txt +++ /dev/null @@ -1,126 +0,0 @@ -Introduction -============= - -UBIFS file-system stands for UBI File System. UBI stands for "Unsorted -Block Images". UBIFS is a flash file system, which means it is designed -to work with flash devices. It is important to understand, that UBIFS -is completely different to any traditional file-system in Linux, like -Ext2, XFS, JFS, etc. UBIFS represents a separate class of file-systems -which work with MTD devices, not block devices. The other Linux -file-system of this class is JFFS2. - -To make it more clear, here is a small comparison of MTD devices and -block devices. - -1 MTD devices represent flash devices and they consist of eraseblocks of - rather large size, typically about 128KiB. Block devices consist of - small blocks, typically 512 bytes. -2 MTD devices support 3 main operations - read from some offset within an - eraseblock, write to some offset within an eraseblock, and erase a whole - eraseblock. Block devices support 2 main operations - read a whole - block and write a whole block. -3 The whole eraseblock has to be erased before it becomes possible to - re-write its contents. Blocks may be just re-written. -4 Eraseblocks become worn out after some number of erase cycles - - typically 100K-1G for SLC NAND and NOR flashes, and 1K-10K for MLC - NAND flashes. Blocks do not have the wear-out property. -5 Eraseblocks may become bad (only on NAND flashes) and software should - deal with this. Blocks on hard drives typically do not become bad, - because hardware has mechanisms to substitute bad blocks, at least in - modern LBA disks. - -It should be quite obvious why UBIFS is very different to traditional -file-systems. - -UBIFS works on top of UBI. UBI is a separate software layer which may be -found in drivers/mtd/ubi. UBI is basically a volume management and -wear-leveling layer. It provides so called UBI volumes which is a higher -level abstraction than a MTD device. The programming model of UBI devices -is very similar to MTD devices - they still consist of large eraseblocks, -they have read/write/erase operations, but UBI devices are devoid of -limitations like wear and bad blocks (items 4 and 5 in the above list). - -In a sense, UBIFS is a next generation of JFFS2 file-system, but it is -very different and incompatible to JFFS2. The following are the main -differences. - -* JFFS2 works on top of MTD devices, UBIFS depends on UBI and works on - top of UBI volumes. -* JFFS2 does not have on-media index and has to build it while mounting, - which requires full media scan. UBIFS maintains the FS indexing - information on the flash media and does not require full media scan, - so it mounts many times faster than JFFS2. -* JFFS2 is a write-through file-system, while UBIFS supports write-back, - which makes UBIFS much faster on writes. - -Similarly to JFFS2, UBIFS supports on-the-flight compression which makes -it possible to fit quite a lot of data to the flash. - -Similarly to JFFS2, UBIFS is tolerant of unclean reboots and power-cuts. -It does not need stuff like fsck.ext2. UBIFS automatically replays its -journal and recovers from crashes, ensuring that the on-flash data -structures are consistent. - -UBIFS scales logarithmically (most of the data structures it uses are -trees), so the mount time and memory consumption do not linearly depend -on the flash size, like in case of JFFS2. This is because UBIFS -maintains the FS index on the flash media. However, UBIFS depends on -UBI, which scales linearly. So overall UBI/UBIFS stack scales linearly. -Nevertheless, UBI/UBIFS scales considerably better than JFFS2. - -The authors of UBIFS believe, that it is possible to develop UBI2 which -would scale logarithmically as well. UBI2 would support the same API as UBI, -but it would be binary incompatible to UBI. So UBIFS would not need to be -changed to use UBI2 - - -Mount options -============= - -(*) == default. - -bulk_read read more in one go to take advantage of flash - media that read faster sequentially -no_bulk_read (*) do not bulk-read -no_chk_data_crc (*) skip checking of CRCs on data nodes in order to - improve read performance. Use this option only - if the flash media is highly reliable. The effect - of this option is that corruption of the contents - of a file can go unnoticed. -chk_data_crc do not skip checking CRCs on data nodes -compr=none override default compressor and set it to "none" -compr=lzo override default compressor and set it to "lzo" -compr=zlib override default compressor and set it to "zlib" -auth_key= specify the key used for authenticating the filesystem. - Passing this option makes authentication mandatory. - The passed key must be present in the kernel keyring - and must be of type 'logon' -auth_hash_name= The hash algorithm used for authentication. Used for - both hashing and for creating HMACs. Typical values - include "sha256" or "sha512" - - -Quick usage instructions -======================== - -The UBI volume to mount is specified using "ubiX_Y" or "ubiX:NAME" syntax, -where "X" is UBI device number, "Y" is UBI volume number, and "NAME" is -UBI volume name. - -Mount volume 0 on UBI device 0 to /mnt/ubifs: -$ mount -t ubifs ubi0_0 /mnt/ubifs - -Mount "rootfs" volume of UBI device 0 to /mnt/ubifs ("rootfs" is volume -name): -$ mount -t ubifs ubi0:rootfs /mnt/ubifs - -The following is an example of the kernel boot arguments to attach mtd0 -to UBI and mount volume "rootfs": -ubi.mtd=0 root=ubi0:rootfs rootfstype=ubifs - -References -========== - -UBIFS documentation and FAQ/HOWTO at the MTD web site: -http://www.linux-mtd.infradead.org/doc/ubifs.html -http://www.linux-mtd.infradead.org/faq/ubifs.html -- cgit v1.2.3