ubi-utils: clean-up text files

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

1 files changed, 111 insertions, 201 deletions

diff --git a/ubi-utils/README b/ubi-utils/README
index d976a76..5c7f9db 100644
--- a/ubi-utils/README
+++ b/ubi-utils/README
@@ -4,7 +4,7 @@ README
 The programs and libraries in this directory provide a tool-chain to
 generate binary data for embedded systems which can be flashed either
 by a hardware flash programmer, e.g. JTAG debugger, or on the target
-system directly using pfiflash, or ubimkvol, ubirmvol, ubiwritevol.
+system directly using pfiflash, or ubimkvol, ubirmvol, ubiupdatevol.
 
 The latter is the case when there is already Linux running which has
 build in UBI support.
@@ -12,6 +12,7 @@ build in UBI support.
 Authors: Oliver Lohmann
          Frank Haverkamp
 	 Andreas Arnez
+	 Artem Bityutskiy
 
 mkpfi           - tool for flash content generation in PFI
                   format
@@ -27,210 +28,119 @@ ubigen          - tool to create binary UBI images e.g. for a
 nandimg         - tool to add OOB data to binary images intended
                   for NAND flash systems
 ubilib          - UBI library
+ubimkvol        - UBI volume creation utility
+ubirmvol        - UBI volume removal utility
+ubiupdatevol    - UBI volume update utility
 
-!!! NOTICE !!!
-If you execute ./configure in the top_level directory the helper Makefile
-gets overwritten. Thats actually no problem, but be aware of that.
-
-1. Build Process
-
-1.1 Build, install and forget
-    o Build all and everything
-      $make all (takes a while, builds ppc and x86 binaries/libs)
-    o Installation:
-      $make install
-    o Uninstallation:
-      $make uninstall
-
-    o x86 only would be:
-      $make x86 && make install_x86
-    
-1.2 Usage for a developer
-
-    1.2.1 The build process in detail
-
-    o If you've checked out the sources from the CVS repository you'll find a
-      directory setup like this:
-
-	flashutils/
-	-rw-r--r--  1 olli olli 1.3K Mar 14 11:53 Makefile
-	-rw-r--r--  1 olli olli 1.9K Mar 14 10:50 Makefile.am
-	-rwxr-xr-x  1 olli olli  265 Mar  9 00:47 bootstrap
-	-rw-r--r--  1 olli olli 1.1K Mar  9 16:55 configure.ac
-	drwxr-xr-x  2 olli olli 4.0K Mar  9 00:28 doc
-	drwxr-xr-x  2 olli olli 4.0K Mar 14 11:56 inc
-	drwxr-xr-x  2 olli olli 4.0K Mar 14 11:56 lib
-	drwxr-xr-x 17 olli olli 4.0K Mar 13 16:50 src
-
-    o To generate the initial build templates you have to  call the bootstrap
-      script:
-      $ ./bootstrap
-    o Create a directory for the target platform 
-      $ mkdir build_x86
-    o Descend into the directory and call the top-level configure script
-      with the desired options.
-      $ cd build_x86
-      $ ../configure --prefix=/usr/local [...]
-    o Now you'll find a directory structure like this:
-      
-	flashutils/build_x86/
-	-rw-r--r-- 1 olli olli  47K Mar 14 13:33 Makefile
-	-rw-r--r-- 1 olli olli  33K Mar 14 13:33 config.log
-	-rwxr-xr-x 1 olli olli  38K Mar 14 13:33 config.status
-	drwxr-xr-x 2 olli olli 4.0K Mar 14 13:33 inc
-	drwxr-xr-x 3 olli olli 4.0K Mar 14 13:33 lib
-	-rwxr-xr-x 1 olli olli 202K Mar 14 13:33 libtool
-
-    o The config.guess script can be used to update the Makefiles in the
-      target directory after a change of the top-level template files 
-      (i.e. the Makefile.in files).
-      $ ./config.guess
-    o To compile everything for this platform just invoke make in
-      flashutils/build_x86:
-      $ make
-      or from toplevel:
-      $ make -C ./build_x86
-    o The build process creates a new directory "bin":
-	flashutils/build_x86/
-	[...]
-	drwxr-xr-x 3 olli olli 4.0K Mar 14 13:41 bin
-	[...]
-
-      This directory contains all binary files which will be installed
-      by make install, e.g.:
-
-	flashutils/build_x86/bin/
-	-rwxr-xr-x 1 olli olli 7.2K Mar 14 13:41 bin2nand
-	-rwxr-xr-x 1 olli olli  15K Mar 14 13:41 mkbootenv
-	-rwxr-xr-x 1 olli olli  16K Mar 14 13:41 pddcustomize
-	-rwxr-xr-x 1 olli olli  36K Mar 14 13:41 pfi2bin
-	-rwxr-xr-x 1 olli olli 6.8K Mar 14 13:41 pfiflash
-	-rwxr-xr-x 1 olli olli 5.0K Mar 14 13:41 ubicrc32
-	-rwxr-xr-x 1 olli olli  13K Mar 14 13:41 ubigen
-	-rwxr-xr-x 1 olli olli 6.3K Mar 14 13:41 ubimirror
-
-
-    1.2.2 Modifying and Adding Sources
-
-    o There is a dedicated directory which contains all source code
-      of the flashutils package, e.g.:
-
-	flashutils/src/
-	drwxr-xr-x 2 olli olli 4.0K Mar 13 11:42 libbootenv
-	drwxr-xr-x 2 olli olli 4.0K Mar 13 11:42 liberror
-	drwxr-xr-x 2 olli olli 4.0K Mar 13 16:48 mkpfi
-	drwxr-xr-x 2 olli olli 4.0K Mar 13 16:12 pddcustomize
-
-      
-      
-      The prefix "lib" is used to mark directories as part of a convenience
-      library. Binaries have no special prefix.
-
-    o How to add sources?
-      
-      Just create a new directory at flashutils/src/, e.g.:
-
-      For a binary:
-      $ mkdir rider
-      $ cd rider
-      $ vi rider.c
-      /* do sth with that file... */
-
-      For a convenience library (as well as for "normal libs")
-      $ mkdir libworld
-      $ cd libworld
-      $ vi world.c
-      /* do sth with that file... */
-
-    o How to register sources in the build process (for binaries)?
-
-      You have to register your sources at the top-level automake Makefile:
-
-      In directory flashutils/
-      $ vi Makefile.am
-
-      Binaries have to be registered at "bin_PROGRAMS", e.g.:
-	bin_PROGRAMS	= bin/pddcustomize \
-			  bin/rider
-
-      Add the rule how the binary is assembled, e.g.:
-	bin_pddcustomize_SOURCES = \
-		$(top_srcdir)/src/pddcustomize/pddcustomize.c 
-	bin_pddcustomize_LDADD   = \
-		$(top_builddir)/lib/libbootenv.la \
-		$(top_builddir)/lib/liberror.la 
-
-	bin_rider_SOURCES = \
-		$(top_srcdir)/src/rider/rider.c
-
-      This example reflects a simple build process for "rider". "rider"
-      is built without any other dependencies or convenience libraries.
-      The example for pddcustomize is a bit more complicated.
-      "_LDADD" adds some convenience libraris into the link process of 
-      "pddcustomize". Imagine, that your "rider" has common code 
-      with "dragon_bin" which is held in a library called "libworld".
-      The build rules would like like the following:
-
-	bin_rider_SOURCES = \
-		$(top_srcdir)/src/rider/rider.c
-	bin_rider_LDADD   = \
-		$(top_builddir)/lib/libworld.la 
-
-	bin_dragon_SOURCES = \
-		$(top_srcdir)/src/dragon_bin/dragon_bin.c
-	bin_dragon_LDADD   = \
-		$(top_builddir)/lib/libworld.la 
-
-      Don't forget to add "dragon" to "bin_PROGRAMS"!
-      Don't forget to set the build rule for the "libworld" itself!
-      This is documented in the next section.
-      	
-
-    o How to register sources in the build process (for libraries)?
-
-      Until now we didn't care about the build process of "libworld".
-      Libraries are handled special in this build process because
-      they are handled as "modules", i.e. they are able to be built
-      without building the binaries in the same step. Additionally,
-      it is possible to assemble complex libraries out of simple ones.
-      That especially makes sense if you want to export (install) a 
-      library on a system which uses some common code and makes
-      some adoptions for usability and presents a comfortable interface to
-      the user (see libpfiflash in the sources for an example).
-
-    o Registering "libworld" as convenience library.
-
-      Instead of editing the "Makefile.am" in "flashtools/", we have to 
-      edit now the "Makefile.am" in "flashtools/lib/":
-
-	noinst_LTLIBRARIES	= libworld.la 
 
-	libworld_la_SOURCES	= $(top_srcdir)/src/libworld/world.c
+The following text is from original UBI announcement
+====================================================
 
-    o Registering "libworld" as library which gets installed.
-      
-	lib_LTLIBRARIES		= libworld.la 
-	libworld_la_SOURCES	= $(top_srcdir)/src/libworld/world.c
-	libworld_la_LDFLAGS	= -no-undefined -version-info 0:0:0
-
-    o Header files
-      
-      All header files are stored at "flashutils/inc", regardless
-      if convenience library or not. 
-
-      If you want to export headers you have to specify this in the Makefile.am
-      located at "flashutils/inc", e.g. (this should not be done 
-      for convenience libraries):
-
-         nobase_include_HEADERS = world.h
- 
+UBI - Unsorted Block Images
 
+UBI (Latin: "where?") manages multiple logical volumes on a single
+flash device, specifically supporting NAND flash devices. UBI provides
+a flexible partitioning concept which still allows for wear-levelling
+across the whole flash device.
 
-Appendix
+In a sense, UBI may be compared to the Logical Volume Manager
+(LVM). Whereas LVM maps logical sector numbers to physical HDD sector
+numbers, UBI maps logical eraseblocks to physical eraseblocks.
 
-A.1. FAQ
+More information may be found in the UBI design documentation:
+ubidesign.pdf. Which can be found here:
+http://www.linux-mtd.infradead.org/doc/ubi.html
 
-   Q How to call configure to setup a cross-platform build?
-   A $ ./configure --build=i686-pc-linux-gnu --host=ppc-linux \
-	--prefix=/opt/.../ppcnf/crossroot/ \
-	--exec-prefix=/opt/..../ppcnf/crossroot/usr
+Partitioning/Re-partitioning
+
+  An UBI volume occupies a certain number of erase blocks. This is
+  limited by a configured maximum volume size, which could also be
+  viewed as the partition size. Each individual UBI volume's size can
+  be changed independently of the other UBI volumes, provided that the
+  sum of all volume sizes doesn't exceed a certain limit.
+
+  UBI supports dynamic volumes and static volumes. Static volumes are
+  read-only and their contents are protected by CRC check sums.
+
+Bad eraseblocks handling
+
+  UBI transparently handles bad eraseblocks. When a physical
+  eraseblock becomes bad, it is substituted by a good physical
+  eraseblock, and the user does not even notice this.
+
+Scrubbing
+
+  On a NAND flash bit flips can occur on any write operation,
+  sometimes also on read. If bit flips persist on the device, at first
+  they can still be corrected by ECC, but once they accumulate,
+  correction will become impossible. Thus it is best to actively scrub
+  the affected eraseblock, by first copying it to a free eraseblock
+  and then erasing the original. The UBI layer performs this type of
+  scrubbing under the covers, transparently to the UBI volume users.
+
+Erase Counts
+
+  UBI maintains an erase count header per eraseblock. This frees
+  higher-level layers (like file systems) from doing this and allows
+  for centralized erase count management instead. The erase counts are
+  used by the wear-levelling algorithm in the UBI layer. The algorithm
+  itself is exchangeable.
+
+Booting from NAND
+
+  For booting directly from NAND flash the hardware must at least be
+  capable of fetching and executing a small portion of the NAND
+  flash. Some NAND flash controllers have this kind of support. They
+  usually limit the window to a few kilobytes in erase block 0. This
+  "initial program loader" (IPL) must then contain sufficient logic to
+  load and execute the next boot phase.
+
+  Due to bad eraseblocks, which may be randomly scattered over the
+  flash device, it is problematic to store the "secondary program
+  loader" (SPL) statically. Also, due to bit-flips it may become
+  corrupted over time. UBI allows to solve this problem gracefully by
+  storing the SPL in a small static UBI volume.
+
+UBI volumes vs. static partitions
+
+  UBI volumes are still very similar to static MTD partitions:
+
+    * both consist of eraseblocks (logical eraseblocks in case of UBI
+      volumes, and physical eraseblocks in case of static partitions;
+    * both support three basic operations - read, write, erase.
+
+  But UBI volumes have the following advantages over traditional
+  static MTD partitions:
+
+    * there are no eraseblock wear-leveling constraints in case of UBI
+      volumes, so the user should not care about this;
+    * there are no bit-flips and bad eraseblocks in case of UBI volumes.
+
+  So, UBI volumes may be considered as flash devices with relaxed
+  restrictions.
+
+Where can it be found?
+
+  Documentation, kernel code and applications can be found in the MTD
+  gits.
+
+What are the applications for?
+
+  The applications help to create binary flash images for two
+  purposes: pfi files (partial flash images) for in-system update of
+  UBI volumes, and plain binary images, with or without OOB data in
+  case of NAND, for a manufacturing step. Furthermore some tools
+  are/and will be created that allow flash content analysis after a
+  system has crashed.
+
+Who did UBI?
+
+  The original ideas, where UBI is based on, were developed by Andreas
+  Arnez, Frank Haverkamp and Thomas Gleixner. Josh W. Boyer and
+  some others were involved too. The implementation of the kernel
+  layer was done by Artem B. Bityutskiy. The user-space applications
+  and tools were written by Oliver Lohmann with contributions from
+  Frank Haverkamp, Andreas Arnez, and Artem. Joern Engel contributed a
+  patch which modifies JFFS2 so that it can be run on a UBI
+  volume. Thomas Gleixner did modifications to the NAND layer and also
+  some to JFFS2 to make it work.