From 489d7cfd2b892ad45afd8e57884e13bd8477e974 Mon Sep 17 00:00:00 2001
From: Artem Bityutskiy <Artem.Bityutskiy@nokia.com>
Date: Sat, 15 Dec 2007 18:43:15 +0200
Subject: ubi-utils: clean-up text files
Signed-off-by: Artem Bityutskiy <Artem.Bityutskiy@nokia.com>
---
ubi-utils/README | 312 +++++++++++++++++++-----------------------------------
ubi-utils/UBI.TXT | 108 -------------------
2 files changed, 111 insertions(+), 309 deletions(-)
delete mode 100644 ubi-utils/UBI.TXT
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.
diff --git a/ubi-utils/UBI.TXT b/ubi-utils/UBI.TXT
deleted file mode 100644
index 9a1c3c7..0000000
--- a/ubi-utils/UBI.TXT
+++ /dev/null
@@ -1,108 +0,0 @@
-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.
-
-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.
-
-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
-
-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.
--
cgit v1.2.3