| 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 |
