Du kannst nicht mehr als 25 Themen auswählen Themen müssen mit entweder einem Buchstaben oder einer Ziffer beginnen. Sie können Bindestriche („-“) enthalten und bis zu 35 Zeichen lang sein.

build_sys.dox 11KB

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