From: Ezequiel Garcia Date: Mon, 24 Feb 2014 12:39:24 +0000 (-0300) Subject: Add UBI block interface documentation X-Git-Url: https://www.infradead.org/git/?a=commitdiff_plain;h=d1bcc005de239ba0c3daee262d9db09e4988082a;p=mtd-www.git Add UBI block interface documentation Signed-off-by: Ezequiel Garcia Signed-off-by: Artem Bityutskiy --- diff --git a/doc/general.xml b/doc/general.xml index 31ea243..06cb887 100644 --- a/doc/general.xml +++ b/doc/general.xml @@ -182,6 +182,10 @@ use block-based file systems on top of bare flashes using In other words, please, do not use mtdblock unless you know exactly what you are doing.

+

Instead, you may find the block device emulation provided by UBI +useful. Please refer to the UBI section for more +details.

+

There is also a read-only version of this driver which doesn't have the capacity to do the caching and erase/writeback, mainly for use with uCLinux where the extra RAM requirement was considered too large.

diff --git a/doc/ubi.xml b/doc/ubi.xml index f55c04a..a65f18e 100644 --- a/doc/ubi.xml +++ b/doc/ubi.xml @@ -47,6 +47,7 @@
  • Fastmap
    • +
  • Block device
  • More documentation
    • @@ -173,6 +174,10 @@ because:

    mechanisms). +

    UBI also provides a block device that allows regular, block-oriented +file systems to be mounted on top of an UBI volume. This is possible because UBI +handles bad-blocks transparently.

    +

    There is an additional driver called gluebi which emulates MTD devices on top of UBI volumes. This looks a little strange, because UBI works on top of an MTD device, then gluebi emulates other MTD devices @@ -236,6 +241,8 @@ sub-directory.

    devices (the opposite to what ubiattach does);
  • ubimkvol - creates UBI volumes on UBI devices;
  • ubirmvol - removes UBI volumes from UBI devices;
    • +
  • ubiblock - manages block interfaces for UBI volumes. + See here for more information;
  • ubiupdatevol - updates UBI volumes; this tool uses the UBI volume update feature which leaves the volume in "corrupted" state if the update was interrupted; @@ -1261,6 +1268,60 @@ second. Therefore, fastmap makes only sense on fast and large flash devices where a full scan takes too long. E.g. On 4GiB NAND chips a full scan takes several seconds whereas a fast attach needs less than one second.

    +

    Read-only block device access

    + +

    UBI allows to create a block device on top of each UBI volume. The block +device implementation currently has the following limitations: + +

      +
    • Read-only operation.
      • +
    • Serialized operation.
      • +
    • 1-to-1 mapping between block sectors and logical eraseblocks. + In other words, no wear-leveling is provided.
      • +

    + +

    Keep in mind the NAND driver core already serializes all I/O anyway, +so it's not expected this limitation will affect performance.

    + +

    Despite these limitations, a block device is still very useful to mount +read-only, regular file systems on top of UBI volumes. This is the case +of squashfs, which can be used as a lightweigth read-only rootfs on a NAND +device.

    + +

    Usage

    +

    Attaching and detaching a block device on a UBI volume is fairly easy. +You can do this either by using the block UBI module parameter +or with the ubiblock user-space tool.

    + +

    In order to attach a block device on bootup time (e.g. to mount the rootfs +on such a block device) you can specify the block parameter as +a kernel boot arguments:

    + +

    ubi.mtd=5 ubi.block=0,0 root=/dev/ubiblock0_0

    + +

    There are several ways if specifying a volume:

    +
      +

    • Using the UBI volume path:

      + ubi.block=/dev/ubi0_0
      • + +

    • Using the UBI device, and the volume name:

      + ubi.block=0,rootfs
      • + +

    • Using both UBI device number and UBI volume number:

      + ubi.block=0,0
      • +
    + +

    If you've built UBI as a module you can use this parameter at module insertion +time:

    + +$ modprobe ubi mtd=/dev/mtd5 block=/dev/ubi0_0 + +

    A block device can also be attached/detached dynamically at runtime, using +the ubiblock user-space tool:

    + +

    $ ubiblock --attach /dev/ubi0_0

    +

    $ ubiblock --detach /dev/ubi0_0

    +

    More documentation

    Unfortunately, there are no thorough and strict UBI documents. But there is diff --git a/faq/ubi.xml b/faq/ubi.xml index 2832928..e207862 100644 --- a/faq/ubi.xml +++ b/faq/ubi.xml @@ -18,6 +18,7 @@

  • How do I create/delete UBI volumes?
  • How do I run JFFS2 on top of an UBI volume?
  • Can I run ext2 on top of UBI?
    • +
  • Can I run squashfs on top of UBI?
  • Do I have to format my empty flash before running UBI on top of it?
  • How do I erase flash and preserve erase counters?
  • How do I create UBI images?
    • @@ -159,16 +160,15 @@ Please, read the big red note and overview documentation sections to realize why.

    -

    But it is much easier to implement FTL on top of UBI than on top of MTD, -because UBI takes care about many flash complexities and makes it -possible to concentrate on on upper-level issues rather then solving flash -media problems like wear-leveling, bit-flips, bad eraseblocks, etc.

    - -

    -This e-mail describes an idea of a simple FTL layer on top of UBI.

    +

    However, given UBI takes care of many flash complexities, it provides a +bad-block-free block device access on top of UBI volumes. This feature is useful to +mount read-only file systems.

    +

    Can I run squashfs on top of UBI?

    +

    Yes. UBI allows to create a read-only block device on top of a UBI volume +which is suitable for read-only, block-oriented file systems, such as squashfs. +See the UBI block device section for more details.

    Do I have to format my empty flash before running UBI on top of it?