UBI/UBIFS: document better why people should use ubiformat

Signed-off-by: Artem Bityutskiy <Artem.Bityutskiy@nokia.com>

diff --git a/doc/ubi.xml b/doc/ubi.xml
index 5b25fa3d1705d6199dbed7828d6190b7e5e7f287..49b3de8d1f0cd9a258c1ff1edcb7ed8e3c62ef91 100644 (file)
--- a/doc/ubi.xml
+++ b/doc/ubi.xml
@@ -26,9 +26,8 @@
        <li><a href="ubi.html#L_subpage">NAND flash sub-pages</a></li>
        <li><a href="ubi.html#L_hdr_pos">UBI headers position</a></li>
        <li><a href="ubi.html#L_overhead">Flash space overhead</a></li>
-       <li><a href="ubi.html#L_format">Saving erase counters</a>
-               <ul><li><a href="ubi.html#L_format_det">UBI flasher details</a></li></ul>
-       </li>
+       <li><a href="ubi.html#L_format">Saving erase counters</a></li>
+       <li><a href="ubi.html#L_flasher_algo">How UBI flasher should work</a></li>
        <li><a href="ubi.html#L_torturing">Marking eraseblocks as bad</a></li>
        <li><a href="ubi.html#L_scalability">Scalability issues</a>
                <ul><li><a href="ubi.html#L_scalability_det">Implementation details</a></li></ul>
@@ -580,7 +579,7 @@ you use to erase the flash and to write UBI images have to be UBI-aware. The
 <a href="ubi.html#L_usptools">mtd-utils</a> repository contains the
 <code>ubiformat</code> utility which takes things right.</p>
 
-<h4><a name="L_format_det">UBI flasher details</a></h4>
+<h2><a name="L_flasher_algo">How UBI flasher should work</a></h2>
 
 <p>The following is a list of what the UBI flasher program has to do when
 erasing the flash or when flashing UBI images.</p>

diff --git a/faq/ubi.xml b/faq/ubi.xml
index 9c0b291712336e30ba6a9d5ad3318ea3b6be7e79..3a9c255043c27eb056983bbe473f3a01cebb3f33 100644 (file)
--- a/faq/ubi.xml
+++ b/faq/ubi.xml
@@ -187,7 +187,7 @@ format the flash. The formatting process takes time, though.</p>
 counters, so you lose wearing information. Doing this over and over again may
 wear out some eraseblocks. This is especially dangerous on MLC NAND flashes
 which have very low eraseblock life-cycle. Try to use UBI-aware utilities and
-flashing programs (see <a href="../doc/ubi.html#L_format">here</a>).</p>
+flashing programs.</p>
 
 
 
@@ -212,7 +212,7 @@ ubiformat: formatting eraseblock 4095 -- 100 % complete
 MTD does not support sysfs, you have to pass "<code>-s</code>" argument to
 <code>ubiformat</code>.</p>
 
-<p><a href="../doc/ubi.html#L_format">This</a> section has some hints
+<p><a href="../doc/ubi.html#L_flasher_algo">This</a> section has some hints
 for those who implement a custom UBI flasher.</p>
 
 
@@ -312,7 +312,7 @@ padding.</p>
 <a href="../doc/ubi.html#L_usptools"><code>ubiformat</code></a> utility to
 flash the resulting UBI image. Also, you can find detailed description of how
 UBI-aware flashing programs should work in
-<a href="../doc/ubi.html#L_format_det">this</a> section.</p>
+<a href="../doc/ubi.html#L_flasher_algo">this</a> section.</p>
 
 
 
@@ -363,8 +363,17 @@ ubiformat: flashing eraseblock 50 -- 100 % complete
 ubiformat: formatting eraseblock 4095 -- 100 % complete
 </pre>
 
-<p>Note, <a href="../doc/ubi.html#L_format">this</a> has some hints for those
-who implement a custom UBI-aware flasher program.</p>
+<p>Note, <a href="../doc/ubi.html#L_flasher_algo">this</a> section has
+describes how UBI-aware flasher program has to work.</p>
+
+<p><b>Important!</b>: even if you do not care about erasecounters, do not use
+<code>dd</code> for flashing UBI images to NAND flashes, because
+<code>dd</code> does handle bad eraseblocks.</p>
+
+<p><b>Important!</b>: even if you do not care about erasecounters, do not use
+<code>nandwrite</code> for flashing UBI images containing UBIFS file-system to
+NAND flashes, read <a href="../faq/ubifs.html#L_why_ubiformat">here</a> for
+more information.</p>
 
 
 
@@ -587,7 +596,7 @@ avoid using the <code>-s</code> parameter.</p>
 
 <h2><a name="L_flasher">How to implement UBI flasher?</a></h2>
 
-<p>Please, read <a href="../doc/ubi.html#L_format">here</a></p>
+<p>Please, read <a href="../doc/ubi.html#L_flasher_algo">here</a></p>
 
 
 

diff --git a/faq/ubifs.xml b/faq/ubifs.xml
index 75bdfea0b62ad6b3dffd2eabb6db00ce6da76313..f29943e36beff2b8b7f042006d6e16cd2a7f8e06 100644 (file)
--- a/faq/ubifs.xml
+++ b/faq/ubifs.xml
@@ -19,6 +19,7 @@
        <li><a href="ubifs.html#L_mkfubifs">How to create an UBIFS image?</a></li>
        <li><a href="ubifs.html#L_emptyflash">May an empty UBI volume be mounted?</a></li>
        <li><a href="ubifs.html#L_max_leb_cnt">What is the purpose of -c (--max-leb-cnt) mkfs.ubifs option?</a></li>
+       <li><a href="ubifs.html#L_why_ubiformat">Why I have to use ubiformat?</a></li>
        <li><a href="ubifs.html#L_mkfs_ubifs_comp">How to compile mkfs.ubifs?</a></li>
        <li><a href="ubifs.html#L_favor_lzo">What is "favor LZO" compression?</a></li>
        <li><a href="ubifs.html#L_loop_mount">Can UBIFS mount loop-back devices?</a></li>
@@ -376,9 +377,12 @@ vol_flags=autoresize
 </pre>
 
 <p>To flash UBI images, please use the <code>ubiformat</code> utility
-(see <a href="ubi.html#L_flash_img">here</a>) or use/implement a custom
-flasher program (<a href="../doc/ubi.html#L_format">here</a> you may find some
-hints).</p>
+(see <a href="ubi.html#L_flash_img">here</a>) or use/implement a
+<b>proper</b> custom flasher program.
+(<a href="../doc/ubi.html#L_flasher_algo">here</a> you may find some
+hints). Please, read
+<a href="ubifs.html#L_why_ubiformat">this</a> section for more information
+why you should use <code>ubiformat</code>.</p>
 
 
 
@@ -535,6 +539,52 @@ in the kernel.</p>
 
 
 
+<h2><a name="L_why_ubiformat">Why I have to use ubiformat?</a></h2>
+
+<p>The first obvious reason is that <code>ubiformat</code> preserves erase
+counters, so you do not lose your wear-leveling information when flashing new
+images.</p>
+
+<p>The other reason is more subtle, and specific to NAND flashes which have
+ECC calculation algorithm which produces ECC code not equivalent to all
+<code>0xFF</code> bytes if the NAND page contains only <code>0xFF</code> bytes.
+Consider an example.</p>
+
+<ul>
+       <li>We erase whole flash, so everything is <code>0xFF</code>'ed
+       now.</li>
+
+       <li>We write an UBI/UBIFS image to flash using
+       <code>nandwrite</code>.</li>
+
+       <li>Some eraseblocks in the UBIFS image may contain several empty NAND
+       pages at the end, and UBIFS will write to them when it is run.</li>
+
+       <li>The <code>nandwrite</code> utility writes whole image, and it
+       explicitely writes <code>0xFF</code> bytes to those NAND pages.</li>
+
+       <li>The ECC checksums are calculated for these <code>0xFF</code>'ed
+       NAND pages and are stored in the OOB area. The ECC codes are not
+       <code>0xFF</code>'ed. This is often the case for HW ECC calculation
+       engines, and it is difficult to fix this. Normally, ECC codes should
+       be <code>0xFF</code>'ed for such pages.</li>
+
+       <li>When later UBIFS runs, it writes data to these NAND pages, which
+       means that a new ECC code is calculated, and written on top of the
+       existing one (unsuccessfully, of course). This may trigger an error
+       straight away, but usually at this point no error is triggered.</li>
+
+       <li>At some point UBIFS is trying to read from these pages, and gets
+       and an ECC error (<code>-EBADMSG</code> = <code>-74</code>).</li>
+</ul>
+
+<p>In fewer words, <code>ubiformat</code> makes sure that every NAND page is
+written once and only once after the erasure. If you use
+<code>nandwrite</code>, some pages are written twice - once by
+<code>nandwrite</code>, and once by UBIFS.</p>
+
+
+
 <h2><a name="L_mkfs_ubifs_comp">How to compile mkfs.ubifs?</a></h2>
 
 <p>The <code>mkfs.ubifs</code> utility requires <i>zlib</i>, <i>lzo</i> and