aboutsummaryrefslogtreecommitdiff
path: root/ubi-utils/README
diff options
context:
space:
mode:
Diffstat (limited to 'ubi-utils/README')
-rw-r--r--ubi-utils/README236
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