From 47571b83a145afaa88ca524b7b8248cc7ebaa627 Mon Sep 17 00:00:00 2001 From: Artem Bityutskiy Date: Tue, 4 Mar 2014 11:55:39 +0200 Subject: [PATCH] Clean-up documentation for ubiblock and fastmap Signed-off-by: Artem Bityutskiy --- doc/general.xml | 15 +++--- doc/ubi.xml | 123 +++++++++++++++++++++++++----------------------- 2 files changed, 73 insertions(+), 65 deletions(-) diff --git a/doc/general.xml b/doc/general.xml index 06cb887..10ea02b 100644 --- a/doc/general.xml +++ b/doc/general.xml @@ -174,7 +174,7 @@ works by caching a whole flash erase block in RAM, modifying it as requested, then erasing the whole block and writing back the modified. This means that mtdblock does not try to do any optimizations, and that you will lose lots of data in case of power cuts. And last, but not least, -mtdblock does not do any wear-leveling.

+mtdblock does not do any wear-leveling or bit-flips handling.

Often people consider mtdblock as general FTL layer and try to use block-based file systems on top of bare flashes using @@ -182,13 +182,14 @@ 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, mainly for use with +uCLinux where the extra RAM requirement was considered too large. However, just +like the R/W version of the driver, there is no wear-levelling and bit-flips +handling.

-

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.

+

Instead of using this old driver, you may check the R/O block device +emulation provided by UBI useful. Please refer to the +UBI section for more details.

diff --git a/doc/ubi.xml b/doc/ubi.xml index a65f18e..19140a1 100644 --- a/doc/ubi.xml +++ b/doc/ubi.xml @@ -47,7 +47,7 @@
  • Fastmap
    • -
  • Block device
    • +
  • R/O block devices on top of UBI volumes
  • More documentation
    • @@ -242,7 +242,7 @@ sub-directory.

  • 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;
    • + 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; @@ -1159,21 +1159,22 @@ means that all data has been written to the flash media), otherwise it selects the PEB with lower sequence number(P1). Of course, UBI has to read the LEB contents in order to check the CRC-32 checksum.

    + +

    Fastmap

    -

    -Fastmap is an experimental and optional UBI feature, which can be enabled -by setting CONFIG_MTD_UBI_FASTMAP to 'y'. -Once enabled UBI evaluates the module parameter -"fm_autoconvert". If it is set to 1 (default is 0) UBI automatically enables -fastmap for any attached image. This means UBI creates a new internal +

    Fastmap is an experimental and optional UBI feature, which can be enabled +by setting CONFIG_MTD_UBI_FASTMAP to 'y'. Once enabled UBI evaluates the module +parameter "fm_autoconvert". If it is set to 1 (default is 0) UBI automatically +enables fastmap for any attached image. This means UBI creates a new internal volume with the fastmap data such that next time the fast attach mode can be -used. -In the default configuration UBI will use the information stored in this -fastmap volume to accelerate the attach procedure. -If you want to test fastmap, set fm_autoconvert to 1 and attach a volume. -

    +used.

    + +

    In the default configuration UBI will use the information stored in this +fastmap volume to accelerate the attach procedure. If you want to test +fastmap, set fm_autoconvert to 1 and attach a volume.

    + +

    The following settings are possible:

    -The following settings are possible: @@ -1205,12 +1206,12 @@ is automatically installed on all attached images
    CONFIG_MTD_UBI_FASTMAP

    Backwards compatibility

    +

    The fastmap on-disk data structure makes use of delete compatible volumes, therefore fastmap enabled images are fully backwards compatible with UBI -implementations which do not support fastmap. The kernel will remove the fastmap -volumes and continue with scanning. -This includes not only v3.6- but also v3.7+ with this option disabled. -

    +implementations which do not support fastmap. The kernel will remove the +fastmap volumes and continue with scanning. This includes not only v3.6- but +also v3.7+ with this option disabled.

    Technical design

    @@ -1231,9 +1232,10 @@ It contains pointers to the remaining PEBs which carry the actual fastmap data. On modern NAND chips the whole fastmap fits into a single PEB. Hence, the anchor PEB points to itself. After loading the fastmap data, UBI attach information structure is created -from it. +from it.

    + +

    The attach process works as follows:

    -The attach process works as follows:
    1. UBI tries to find the fastmap anchor PEB, if no anchor PEB was found UBI performs traditional full scan
      2. @@ -1242,62 +1244,61 @@ The attach process works as follows:
    2. Then it performs a traditional scan only on PEBs in the pool instead of all PEBs
    -If UBI detects that the used fastmap is invalid or corrupted it automatically -falls back to scanning mode and performs a full scan. -Using a CRC32 checksum and consistency checks of the internal UBI structures -UBI is able to detect whether a fastmap is invalid or not. -

    - -

    -A fastmap is written to the devices each time the fastmap pool becomes full + +

    If UBI detects that the used fastmap is invalid or corrupted it +automatically falls back to scanning mode and performs a full scan. Using a +CRC32 checksum and consistency checks of the internal UBI structures UBI is +able to detect whether a fastmap is invalid or not.

    + +

    A fastmap is written to the devices each time the fastmap pool becomes full (no free PEBs are available), the volume layout changes or the image is -detached. One may wonder why writing at detach time is needed. -If UBI would not write a new fastmap at detach time all erase counter -modifications since the last fastmap write are lost. -

    +detached. One may wonder why writing at detach time is needed. If UBI would +not write a new fastmap at detach time all erase counter modifications since +the last fastmap write are lost.

    Overhead

    +

    If fastmap enabled UBI will reserve enough PEBs to carry two complete -fastmaps. In practice on modern NAND chips two PEBs are reserved for fastmap. -

    -

    -There is also some runtime overhead, to guarantee that the new fastmap is valid +fastmaps. In practice on modern NAND chips two PEBs are reserved for fastmap.

    + +

    There is also some runtime overhead, to guarantee that the new fastmap is valid and conistent UBI has to take care that all IO which would cause EBA changes are blocked while attaching. Depending on flash chips this can take up to one 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: + +

    R/O block devices on top of UBI volumes

    + +

    UBI allows to create block devices on top of UBI volumes with +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.

    +
  • Serialized I/O operation, but keep in mind the NAND driver core + already serializes all I/O too.
    • +

    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.

    +device. The UBI layer will take care of things like bit-flips handling and +wear-levelling.

    -

    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 +

    Usage

    + +

    Creating and destroying block devices on a UBI volume is somewhat similar to +attaching MTD devices to UBI. You can either use the block UBI +module parameter or use the "ubiblock" user-space tool.

    + +

    In order to create 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

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

    There are several ways if specifying a volume:

    -

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

    +

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

    -$ modprobe ubi mtd=/dev/mtd5 block=/dev/ubi0_0 +
    +$ 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

    +
    +$ ubiblock --attach /dev/ubi0_0
+$ ubiblock --detach /dev/ubi0_0
+
    + +

    More documentation

    -- 2.49.0