ubifs.rst 5.7 KB

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