Merge branch 'ubi'

1 files changed, 236 insertions, 0 deletions

diff --git a/ubi-utils/README b/ubi-utils/README
new file mode 100644
index 0000000..d976a76
--- /dev/null
+++ b/ubi-utils/README
@@ -0,0 +1,236 @@
+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.
+
+The latter is the case when there is already Linux running which has
+build in UBI support.
+
+Authors: Oliver Lohmann
+         Frank Haverkamp
+	 Andreas Arnez
+
+mkpfi           - tool for flash content generation in PFI
+                  format
+pfi2bin         - conversion tool to transfer a PFI file into a
+                  binary image
+pfiflash        - tool to update the embedded systems flash using
+                  pfi files created by mkpfi
+libbootenv      - library for boot-parameter processing
+libpfi          - library for partial flash image (PFI) creation
+                  and handling
+ubigen          - tool to create binary UBI images e.g. for a
+                  jtag flashing tool
+nandimg         - tool to add OOB data to binary images intended
+                  for NAND flash systems
+ubilib          - UBI library
+
+!!! 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
+
+    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
+ 
+
+
+Appendix
+
+A.1. FAQ
+
+   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