From e44e3482bdb4d0ebde2d8b41830ac2cdb07948fb Mon Sep 17 00:00:00 2001 From: Yang Zhang Date: Fri, 28 Aug 2015 09:58:54 +0800 Subject: Add qemu 2.4.0 Change-Id: Ic99cbad4b61f8b127b7dc74d04576c0bcbaaf4f5 Signed-off-by: Yang Zhang --- qemu/roms/ipxe/src/doc/build_sys.dox | 419 +++++++++++++++++++++++++++++++++++ 1 file changed, 419 insertions(+) create mode 100644 qemu/roms/ipxe/src/doc/build_sys.dox (limited to 'qemu/roms/ipxe/src/doc/build_sys.dox') diff --git a/qemu/roms/ipxe/src/doc/build_sys.dox b/qemu/roms/ipxe/src/doc/build_sys.dox new file mode 100644 index 000000000..9466f6621 --- /dev/null +++ b/qemu/roms/ipxe/src/doc/build_sys.dox @@ -0,0 +1,419 @@ +/** @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 bin/deps/. For example, the rules +generated for drivers/net/rtl8139.c can be found in +bin/deps/drivers/net/rtl8139.c.d. These rules allow you to +type, for example + +@code + + make bin/rtl8139.o + +@endcode + +and have rtl8139.o be built from +drivers/net/rtl8139.c 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 bin/blib.a. + +@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_@. +For example, if you were to set + +@code + + CFLAGS_rtl8139 = -DFOO + +@endcode + +then bin/rtl8139.o would be compiled with the additional +flags -DFOO. 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_@ 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_@. For example, the +arch/i386/prefix/dskprefix.S source file is built into two +objects, bin/dskprefix.o and zdskprefix.o 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, arch/i386/prefix/dskprefix.S is built into @c +dskprefix.o using the normal set of flags, and into @c zdskprefix.o +using the normal set of flags plus -DCOMPRESS. + +@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_@ if applicable) using +e.g. + +@code + + make bin/rtl8139.c + +@endcode + +and examining the resulting file (bin/rtl8139.c 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_@; 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 + +@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 + +*/ -- cgit 1.2.3-korg