[PATCH v7 3/3] Add UBI block interface documentation

Ezequiel Garcia
2014-02-24T12:40:19Z

Signed-off-by: Ezequiel Garcia <ezequiel.garcia@free-electrons.com>
---
doc/general.xml | 4 ++++
doc/ubi.xml | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
faq/ubi.xml | 16 +++++++--------
3 files changed, 73 insertions(+), 8 deletions(-)

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.
-
- <a
-href="http://lists.infradead.org/pipermail/linux-mtd/2008-January/020381.html">
-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?
--
1.8.1.5