diff options
Diffstat (limited to 'gpxe/src/doc/build_sys.dox')
| -rw-r--r-- | gpxe/src/doc/build_sys.dox | 419 |
1 files changed, 0 insertions, 419 deletions
diff --git a/gpxe/src/doc/build_sys.dox b/gpxe/src/doc/build_sys.dox deleted file mode 100644 index 9466f662..00000000 --- a/gpxe/src/doc/build_sys.dox +++ /dev/null @@ -1,419 +0,0 @@ -/** @page build_sys Build system - -@section overview Overview - -Building an Etherboot image consists of three stages: - - -# @ref compilation : Compiling all the source files into object files - -# @ref linking : Linking a particular image from selected object files - -# @ref finalisation : Producing the final output binary - -Though this is a remarkably complex process, it is important to note -that it all happens automatically. Whatever state your build tree is -in, you can always type, for example - -@code - - make bin/rtl8139.dsk - -@endcode - -and know that you will get a floppy disk image with an RTL8139 driver -built from the current sources. - -@section compilation Compilation - -@subsection comp_overview Overview - -Each source file (a @c .c or a @c .S file) is compiled into a @c .o -file in the @c bin/ directory. Etherboot makes minimal use of -conditional compilation (see @ref ifdef_harmful), and so you will find -that all objects get built, even the objects that correspond to -features that you are not intending to include in your image. For -example, all network card drivers will be compiled even if you are -just building a ROM for a 3c509 card. This is a deliberate design -decision; please do @b not attempt to "fix" the build system to avoid -doing this. - -Source files are defined to be any @c .c or @c .S files found in a -directory listed in the Makefile variable #SRCDIRS. You therefore do -@b not need to edit the Makefile just because you have added a new -source file (although you will need to edit the Makefile if you have -added a new source directory). To see a list of all source -directories and source files that the build system currently knows -about, you can use the commands - -@code - - make srcdirs - make srcs - -@endcode - -Rules for compiling @c .c and @c .S files are defined in the Makefile -variables #RULE_c and #RULE_S. Makefile rules are automatically -generated for each source file using these rules. The generated rules -can be found in the @c .d file corresponding to each source file; -these are located in <tt>bin/deps/</tt>. For example, the rules -generated for <tt>drivers/net/rtl8139.c</tt> can be found in -<tt>bin/deps/drivers/net/rtl8139.c.d</tt>. These rules allow you to -type, for example - -@code - - make bin/rtl8139.o - -@endcode - -and have <tt>rtl8139.o</tt> be built from -<tt>drivers/net/rtl8139.c</tt> using the generic rule #RULE_c for -compiling @c .c files. - -You can see the full list of object files that will be built using - -@code - - make bobjs - -@endcode - -@subsection comp_ar After compilation - -Once all objects have been compiled, they will be collected into a -build library ("blib") in <tt>bin/blib.a</tt>. - -@subsection comp_custom Customising compilation - -The Makefile rules for a particular object can be customised to a -certain extent by defining the Makefile variable CFLAGS_@<object@>. -For example, if you were to set - -@code - - CFLAGS_rtl8139 = -DFOO - -@endcode - -then <tt>bin/rtl8139.o</tt> would be compiled with the additional -flags <tt>-DFOO</tt>. To see the flags that will be used when -compiling a particular object, you can use e.g. - -@code - - make bin/rtl8139.flags - -@endcode - -If you need more flexibility than the CFLAGS_@<object@> mechanism -provides, then you can exclude source files from the automatic rule -generation process by listing them in the Makefile variable -#NON_AUTO_SRCS. The command - -@code - - make autosrcs - -@endcode - -will show you which files are currently part of the automatic rule -generation process. - -@subsection comp_multiobj Multiple objects - -A single source file can be used to generate multiple object files. -This is used, for example, to generate the decompressing and the -non-decompressing prefixes from the same source files. - -By default, a single object will be built from each source file. To -override the list of objects for a source file, you can define the -Makefile variable OBJS_@<object@>. For example, the -<tt>arch/i386/prefix/dskprefix.S</tt> source file is built into two -objects, <tt>bin/dskprefix.o</tt> and <tt>zdskprefix.o</tt> by -defining the Makefile variable - -@code - - OBJS_dskprefix = dskprefix zdskprefix - -@endcode - -Since there would be little point in building two identical objects, -customised compilation flags (see @ref comp_custom) are defined as - -@code - - CFLAGS_zdskprefix = -DCOMPRESS - -@endcode - -Thus, <tt>arch/i386/prefix/dskprefix.S</tt> is built into @c -dskprefix.o using the normal set of flags, and into @c zdskprefix.o -using the normal set of flags plus <tt>-DCOMPRESS</tt>. - -@subsection comp_debug Special debugging targets - -In addition to the basic rules #RULE_c and #RULE_S for compiling -source files into object files, there are various other rules that can -be useful for debugging. - -@subsubsection comp_debug_c_to_c Preprocessed C - -You can see the results of preprocessing a @c .c file (including the -per-object flags defined via CFLAGS_@<object@> if applicable) using -e.g. - -@code - - make bin/rtl8139.c - -@endcode - -and examining the resulting file (<tt>bin/rtl8139.c</tt> in this -case). - -@subsubsection comp_debug_x_to_s Assembler - -You can see the results of assembling a @c .c file, or of -preprocessing a @c .S file, using e.g. - -@code - - make bin/rtl8139.s - make bin/zdskprefix.s - -@endcode - -@subsubsection comp_debug_dbg Debugging-enabled targets - -You can build targets with debug messages (DBG()) enabled using e.g. - -@code - - make bin/rtl8139.dbg.o - make bin/rtl8139.dbg2.o - -@endcode - -You will probably not need to use these targets directly, since a -mechanism exists to select debugging levels at build time; see @ref -debug. - -@section linking Linking - -@subsection link_overview Overview - -Etherboot is designed to be small and extremely customisable. This is -achieved by linking in only the features that are really wanted in any -particular build. - -There are two places from which the list of desired features is -obtained: - - -# @ref link_config_h - -# @ref link_cmdline - -@subsection link_config_h config.h - -The config.h file is used to define global build options that are -likely to apply to all images that you build, such as the console -types, supported download protocols etc. See the documentation for -config.h for more details. - -@subsection link_cmdline The make command line - -When you type a command such as - -@code - - make bin/dfe538.zrom - -@endcode - -it is used to derive the following information: - - - We are building a compressed ROM image - - The DFE538 is a PCI NIC, so we need the decompressing PCI ROM prefix - - The PCI IDs for the DFE538 are 1186:1300 - - The DFE538 is an rtl8139-based card, therefore we need the rtl8139 driver - -You can see this process in action using the command - -@code - - make bin/dfe538.zrom.info - -@endcode - -which will print - -@code - - Elements : dfe538 - Prefix : zrom - Drivers : rtl8139 - ROM name : dfe538 - Media : rom - - ROM type : pci - PCI vendor : 0x1186 - PCI device : 0x1300 - - LD driver symbols : obj_rtl8139 - LD prefix symbols : obj_zpciprefix - LD ID symbols : pci_vendor_id=0x1186 pci_device_id=0x1300 - - LD target flags : -u obj_zpciprefix --defsym check_obj_zpciprefix=obj_zpciprefix -u obj_rtl8139 --defsym check_obj_rtl8139=obj_rtl8139 -u obj_config --defsym check_obj_config=obj_config --defsym pci_vendor_id=0x1186 --defsym pci_device_id=0x1300 - -@endcode - -This should be interpreted as follows: - -@code - - Elements : dfe538 - Prefix : zrom - -@endcode - -"Elements" is the list of components preceding the first dot in the -target name. "Prefix" is the component following the first dot in the -target name. (It's called a "prefix" because the code that makes it a -@c .zrom (rather than a @c .dsk, @c .zpxe or any other type of target) -usually ends up at the start of the resulting binary image.) - -@code - - Drivers : rtl8139 - -@endcode - -"Drivers" is the list of drivers corresponding to the "Elements". -Most drivers support several network cards. The PCI_ROM() and -ISA_ROM() macros are used in the driver source files to list the cards -that a particular driver can support. - -@code - - ROM name : dfe538 - -@endcode - -"ROM name" is the first element in the "Elements" list. It is used to -select the PCI IDs for a PCI ROM. - -@code - - Media : rom - -@endcode - -"Media" is the "Prefix" minus the leading @c z, if any. - -@code - - ROM type : pci - PCI vendor : 0x1186 - PCI device : 0x1300 - -@endcode - -These are derived from the "ROM name" and the PCI_ROM() or ISA_ROM() -macros in the driver source files. - -@code - - LD driver symbols : obj_rtl8139 - LD prefix symbols : obj_zpciprefix - -@endcode - -This is the interesting part. At this point, we have established that -we need the rtl8139 driver (i.e. @c rtl8139.o) and the decompressing -PCI prefix (i.e. @c zpciprefix.o). Our build system (via the -compiler.h header file) arranges that every object exports a symbol -obj_@<object@>; this can be seen by e.g. - -@code - - objdump -t bin/rtl8139.o - -@endcode - -which will show the line - -@code - - 00000000 g *ABS* 00000000 obj_rtl8139 - -@endcode - -By instructing the linker that we need the symbols @c obj_rtl8139 and -@c obj_zpciprefix, we can therefore ensure that these two objects are -included in our build. (The linker will also include any objects that -these two objects require, since that's the whole purpose of the -linker.) - -In a similar way, we always instruct the linker that we need the -symbol @c obj_config, in order to include the object @c config.o. @c -config.o is used to drag in the objects that were specified via -config.h; see @ref link_config_h. - -@code - - LD target flags : -u obj_zpciprefix --defsym check_obj_zpciprefix=obj_zpciprefix -u obj_rtl8139 --defsym check_obj_rtl8139=obj_rtl8139 -u obj_config --defsym check_obj_config=obj_config --defsym pci_vendor_id=0x1186 --defsym pci_device_id=0x1300 - -@endcode - -These are the flags that we pass to the linker in order to include the -objects that we want in our build, and to check that they really get -included. (This latter check is needed to work around what seems to -be a bug in @c ld). - -The linker does its job of linking all the required objects together -into a coherent build. The best way to see what is happening is to -look at one of the resulting linker maps; try, for example - -@code - - make bin/dfe538.dsk.map - -@endcode - -The linker map includes, amongst others: - - - A list of which objects are included in the build, and why. - - The results of processing the linker script, line-by-line. - - A complete symbol table of the resulting build. - -It is worth spending time examining the linker map to see how an -Etherboot image is assembled. - -Whatever format is selected, the Etherboot image is built into an ELF -file, simply because this is the default format used by @c ld. - -@section finalisation Finalisation - -@subsection final_overview Overview - -The ELF file resulting from @ref linking "linking" needs to be -converted into the final binary image. Usually, this is just a case -of running - -@code - - objcopy -O binary <elf file> <output file> - -@endcode - -to convert the ELF file into a raw binary image. Certain image -formats require special additional treatment. - -@subsection final_rom ROM images - -ROM images must be rounded up to a suitable ROM size (e.g. 16kB or -32kB), and certain header information such as checksums needs to be -filled in. This is done by the @c makerom.pl program. - -@section debug Debugging-enabled builds - -*/ |