1/** @page build_sys Build system 2 3@section overview Overview 4 5Building an Etherboot image consists of three stages: 6 7 -# @ref compilation : Compiling all the source files into object files 8 -# @ref linking : Linking a particular image from selected object files 9 -# @ref finalisation : Producing the final output binary 10 11Though this is a remarkably complex process, it is important to note 12that it all happens automatically. Whatever state your build tree is 13in, you can always type, for example 14 15@code 16 17 make bin/rtl8139.dsk 18 19@endcode 20 21and know that you will get a floppy disk image with an RTL8139 driver 22built from the current sources. 23 24@section compilation Compilation 25 26@subsection comp_overview Overview 27 28Each source file (a @c .c or a @c .S file) is compiled into a @c .o 29file in the @c bin/ directory. Etherboot makes minimal use of 30conditional compilation (see @ref ifdef_harmful), and so you will find 31that all objects get built, even the objects that correspond to 32features that you are not intending to include in your image. For 33example, all network card drivers will be compiled even if you are 34just building a ROM for a 3c509 card. This is a deliberate design 35decision; please do @b not attempt to "fix" the build system to avoid 36doing this. 37 38Source files are defined to be any @c .c or @c .S files found in a 39directory listed in the Makefile variable #SRCDIRS. You therefore do 40@b not need to edit the Makefile just because you have added a new 41source file (although you will need to edit the Makefile if you have 42added a new source directory). To see a list of all source 43directories and source files that the build system currently knows 44about, you can use the commands 45 46@code 47 48 make srcdirs 49 make srcs 50 51@endcode 52 53Rules for compiling @c .c and @c .S files are defined in the Makefile 54variables #RULE_c and #RULE_S. Makefile rules are automatically 55generated for each source file using these rules. The generated rules 56can be found in the @c .d file corresponding to each source file; 57these are located in <tt>bin/deps/</tt>. For example, the rules 58generated for <tt>drivers/net/rtl8139.c</tt> can be found in 59<tt>bin/deps/drivers/net/rtl8139.c.d</tt>. These rules allow you to 60type, for example 61 62@code 63 64 make bin/rtl8139.o 65 66@endcode 67 68and have <tt>rtl8139.o</tt> be built from 69<tt>drivers/net/rtl8139.c</tt> using the generic rule #RULE_c for 70compiling @c .c files. 71 72You can see the full list of object files that will be built using 73 74@code 75 76 make bobjs 77 78@endcode 79 80@subsection comp_ar After compilation 81 82Once all objects have been compiled, they will be collected into a 83build library ("blib") in <tt>bin/blib.a</tt>. 84 85@subsection comp_custom Customising compilation 86 87The Makefile rules for a particular object can be customised to a 88certain extent by defining the Makefile variable CFLAGS_@<object@>. 89For example, if you were to set 90 91@code 92 93 CFLAGS_rtl8139 = -DFOO 94 95@endcode 96 97then <tt>bin/rtl8139.o</tt> would be compiled with the additional 98flags <tt>-DFOO</tt>. To see the flags that will be used when 99compiling a particular object, you can use e.g. 100 101@code 102 103 make bin/rtl8139.flags 104 105@endcode 106 107If you need more flexibility than the CFLAGS_@<object@> mechanism 108provides, then you can exclude source files from the automatic rule 109generation process by listing them in the Makefile variable 110#NON_AUTO_SRCS. The command 111 112@code 113 114 make autosrcs 115 116@endcode 117 118will show you which files are currently part of the automatic rule 119generation process. 120 121@subsection comp_multiobj Multiple objects 122 123A single source file can be used to generate multiple object files. 124This is used, for example, to generate the decompressing and the 125non-decompressing prefixes from the same source files. 126 127By default, a single object will be built from each source file. To 128override the list of objects for a source file, you can define the 129Makefile variable OBJS_@<object@>. For example, the 130<tt>arch/i386/prefix/dskprefix.S</tt> source file is built into two 131objects, <tt>bin/dskprefix.o</tt> and <tt>zdskprefix.o</tt> by 132defining the Makefile variable 133 134@code 135 136 OBJS_dskprefix = dskprefix zdskprefix 137 138@endcode 139 140Since there would be little point in building two identical objects, 141customised compilation flags (see @ref comp_custom) are defined as 142 143@code 144 145 CFLAGS_zdskprefix = -DCOMPRESS 146 147@endcode 148 149Thus, <tt>arch/i386/prefix/dskprefix.S</tt> is built into @c 150dskprefix.o using the normal set of flags, and into @c zdskprefix.o 151using the normal set of flags plus <tt>-DCOMPRESS</tt>. 152 153@subsection comp_debug Special debugging targets 154 155In addition to the basic rules #RULE_c and #RULE_S for compiling 156source files into object files, there are various other rules that can 157be useful for debugging. 158 159@subsubsection comp_debug_c_to_c Preprocessed C 160 161You can see the results of preprocessing a @c .c file (including the 162per-object flags defined via CFLAGS_@<object@> if applicable) using 163e.g. 164 165@code 166 167 make bin/rtl8139.c 168 169@endcode 170 171and examining the resulting file (<tt>bin/rtl8139.c</tt> in this 172case). 173 174@subsubsection comp_debug_x_to_s Assembler 175 176You can see the results of assembling a @c .c file, or of 177preprocessing a @c .S file, using e.g. 178 179@code 180 181 make bin/rtl8139.s 182 make bin/zdskprefix.s 183 184@endcode 185 186@subsubsection comp_debug_dbg Debugging-enabled targets 187 188You can build targets with debug messages (DBG()) enabled using e.g. 189 190@code 191 192 make bin/rtl8139.dbg.o 193 make bin/rtl8139.dbg2.o 194 195@endcode 196 197You will probably not need to use these targets directly, since a 198mechanism exists to select debugging levels at build time; see @ref 199debug. 200 201@section linking Linking 202 203@subsection link_overview Overview 204 205Etherboot is designed to be small and extremely customisable. This is 206achieved by linking in only the features that are really wanted in any 207particular build. 208 209There are two places from which the list of desired features is 210obtained: 211 212 -# @ref link_config_h 213 -# @ref link_cmdline 214 215@subsection link_config_h config.h 216 217The config.h file is used to define global build options that are 218likely to apply to all images that you build, such as the console 219types, supported download protocols etc. See the documentation for 220config.h for more details. 221 222@subsection link_cmdline The make command line 223 224When you type a command such as 225 226@code 227 228 make bin/dfe538.zrom 229 230@endcode 231 232it is used to derive the following information: 233 234 - We are building a compressed ROM image 235 - The DFE538 is a PCI NIC, so we need the decompressing PCI ROM prefix 236 - The PCI IDs for the DFE538 are 1186:1300 237 - The DFE538 is an rtl8139-based card, therefore we need the rtl8139 driver 238 239You can see this process in action using the command 240 241@code 242 243 make bin/dfe538.zrom.info 244 245@endcode 246 247which will print 248 249@code 250 251 Elements : dfe538 252 Prefix : zrom 253 Drivers : rtl8139 254 ROM name : dfe538 255 Media : rom 256 257 ROM type : pci 258 PCI vendor : 0x1186 259 PCI device : 0x1300 260 261 LD driver symbols : obj_rtl8139 262 LD prefix symbols : obj_zpciprefix 263 LD ID symbols : pci_vendor_id=0x1186 pci_device_id=0x1300 264 265 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 266 267@endcode 268 269This should be interpreted as follows: 270 271@code 272 273 Elements : dfe538 274 Prefix : zrom 275 276@endcode 277 278"Elements" is the list of components preceding the first dot in the 279target name. "Prefix" is the component following the first dot in the 280target name. (It's called a "prefix" because the code that makes it a 281@c .zrom (rather than a @c .dsk, @c .zpxe or any other type of target) 282usually ends up at the start of the resulting binary image.) 283 284@code 285 286 Drivers : rtl8139 287 288@endcode 289 290"Drivers" is the list of drivers corresponding to the "Elements". 291Most drivers support several network cards. The PCI_ROM() and 292ISA_ROM() macros are used in the driver source files to list the cards 293that a particular driver can support. 294 295@code 296 297 ROM name : dfe538 298 299@endcode 300 301"ROM name" is the first element in the "Elements" list. It is used to 302select the PCI IDs for a PCI ROM. 303 304@code 305 306 Media : rom 307 308@endcode 309 310"Media" is the "Prefix" minus the leading @c z, if any. 311 312@code 313 314 ROM type : pci 315 PCI vendor : 0x1186 316 PCI device : 0x1300 317 318@endcode 319 320These are derived from the "ROM name" and the PCI_ROM() or ISA_ROM() 321macros in the driver source files. 322 323@code 324 325 LD driver symbols : obj_rtl8139 326 LD prefix symbols : obj_zpciprefix 327 328@endcode 329 330This is the interesting part. At this point, we have established that 331we need the rtl8139 driver (i.e. @c rtl8139.o) and the decompressing 332PCI prefix (i.e. @c zpciprefix.o). Our build system (via the 333compiler.h header file) arranges that every object exports a symbol 334obj_@<object@>; this can be seen by e.g. 335 336@code 337 338 objdump -t bin/rtl8139.o 339 340@endcode 341 342which will show the line 343 344@code 345 346 00000000 g *ABS* 00000000 obj_rtl8139 347 348@endcode 349 350By instructing the linker that we need the symbols @c obj_rtl8139 and 351@c obj_zpciprefix, we can therefore ensure that these two objects are 352included in our build. (The linker will also include any objects that 353these two objects require, since that's the whole purpose of the 354linker.) 355 356In a similar way, we always instruct the linker that we need the 357symbol @c obj_config, in order to include the object @c config.o. @c 358config.o is used to drag in the objects that were specified via 359config.h; see @ref link_config_h. 360 361@code 362 363 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 364 365@endcode 366 367These are the flags that we pass to the linker in order to include the 368objects that we want in our build, and to check that they really get 369included. (This latter check is needed to work around what seems to 370be a bug in @c ld). 371 372The linker does its job of linking all the required objects together 373into a coherent build. The best way to see what is happening is to 374look at one of the resulting linker maps; try, for example 375 376@code 377 378 make bin/dfe538.dsk.map 379 380@endcode 381 382The linker map includes, amongst others: 383 384 - A list of which objects are included in the build, and why. 385 - The results of processing the linker script, line-by-line. 386 - A complete symbol table of the resulting build. 387 388It is worth spending time examining the linker map to see how an 389Etherboot image is assembled. 390 391Whatever format is selected, the Etherboot image is built into an ELF 392file, simply because this is the default format used by @c ld. 393 394@section finalisation Finalisation 395 396@subsection final_overview Overview 397 398The ELF file resulting from @ref linking "linking" needs to be 399converted into the final binary image. Usually, this is just a case 400of running 401 402@code 403 404 objcopy -O binary <elf file> <output file> 405 406@endcode 407 408to convert the ELF file into a raw binary image. Certain image 409formats require special additional treatment. 410 411@subsection final_rom ROM images 412 413ROM images must be rounded up to a suitable ROM size (e.g. 16kB or 41432kB), and certain header information such as checksums needs to be 415filled in. This is done by the @c makerom.pl program. 416 417@section debug Debugging-enabled builds 418 419*/ 420