diff options
Diffstat (limited to 'ubi-utils/README')
| -rw-r--r-- | ubi-utils/README | 312 |
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. |