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