qemu/roms/seabios/docs/Linking_overview.md

   1 This page describes the process that the SeaBIOS build uses to link
   2 the compiled code into the final binary objects.
   3
   4 Unfortunately, the SeaBIOS linking phase is complex. This complexity
   5 is due to several unusual requirements:
   6
   7 * Some BIOS entry points must reside at specific hardcoded memory
   8   locations. The build must support positioning code and variables at
   9   specific locations.
  10 * In order to support multiple [memory models](Memory Model) the same
  11   C code can be complied in three modes (16bit mode, 32bit segmented
  12   mode, and 32bit "flat" mode). Binary code from these three modes
  13   must be able to co-exist and on occasion reference each other.
  14 * There is a finite amount of memory available to the BIOS. The build
  15   will attempt to weed out unused code and variables from the final
  16   binary. It also supports self-relocation of one-time initialization
  17   code.
  18
  19 Code layout
  20 ===========
  21
  22 To support the unusual build requirements, several
  23 [gcc](http://en.wikipedia.org/wiki/GNU_Compiler_Collection) compiler
  24 options are used. The "-ffunction-sections" and "-fdata-sections"
  25 flags instruct the compiler to place each variable and function into
  26 its own
  27 [ELF](http://en.wikipedia.org/wiki/Executable_and_Linkable_Format)
  28 section.
  29
  30 The C code is compiled three times into three separate objects for
  31 each of the major supported [memory models](Memory Model):
  32 **code16.o**, **code32seg.o**, and **code32flat.o**. Information on
  33 the sections and symbols of these three objects are extracted (using
  34 **objdump**) and passed in to the **scripts/layoutrom.py** python
  35 script. This script analyzes this information and produces gnu
  36 [ld](http://en.wikipedia.org/wiki/GNU_linker) "linker scripts" which
  37 provide precise location information to the linker. These linker
  38 scripts are then used during the link phase which produces a **rom.o**
  39 object containing all the code.
  40
  41 Fixed location entry points
  42 ---------------------------
  43
  44 The build supports placing code entry points and variables at fixed
  45 memory locations. This support is required in order to support the
  46 legacy BIOS standards. For example, a program might execute an "int
  47 0x15" to request system information from the BIOS, but another old
  48 program might use "ljmpw $0xf000, $0xf859" instead. Both must provide
  49 the same results and so the build must position the 0x15 interrupt
  50 entry point in physical memory at 0xff859.
  51
  52 This support is accomplished by placing the given code/variables into
  53 ELF sections that have a name containing the substring
  54 ".fixedaddr.0x1234" (where 0x1234 is the desired address). For
  55 variables in C code this is accomplished by marking the variables with
  56 the VARFSEGFIXED(0x1234) macro. For assembler entry points the ORG
  57 macro is used (see **romlayout.S**).
  58
  59 During the build, the **layoutrom.py** script will detect sections
  60 that contain the ".fixedaddr." substring and will arrange for the
  61 final linker scripts to specify the desired address for the given
  62 section.
  63
  64 Due to the sparse nature of these fixed address sections, the
  65 layoutrom.py script will also arrange to pack in other unrelated 16bit
  66 code into the free space between fixed address sections (see
  67 layoutrom.py:fitSections()). This maximizes the space available and
  68 reduces the overall size of the final binary.
  69
  70 C code in three modes
  71 ---------------------
  72
  73 SeaBIOS must support multiple [memory models](Memory Model). This is
  74 accomplished by compiling the C code three separate times into three
  75 separate objects.
  76
  77 The C code within a mode must not accidentally call a C function in
  78 another mode, but multiple modes must all access the same single copy
  79 of global variables. Further, it is occasionally necessary for the C
  80 code in one mode to obtain the address of C code in another mode.
  81
  82 In order to use the same global variables between all modes, the
  83 layoutrom.py script will detect references to global variables and
  84 emit specific symbol definitions for those global variables in the
  85 linker scripts so that all references use the same physical memory
  86 address (see layoutrom.py:outXRefs()).
  87
  88 To ensure C code does not accidentally call C code compiled in a
  89 different mode, the build will ensure the symbols for C code in each
  90 mode are isolated from each other during the linking stage. To support
  91 those situations where an address of a C function in another mode is
  92 required the build supports symbols with a special "\_cfuncX_"
  93 prefix. The layoutrom.py script detects these references and will emit
  94 a corresponding symbol definitions in the linker script that points to
  95 the C code of the specified mode. This is typically seen with code
  96 like:
  97
  98 `extern void _cfunc32flat_process_op(void);`\
  99 `return call32(_cfunc32flat_process_op, 0, 0);`
 100
 101 In the above example, when the build finds the symbol
 102 "\_cfunc32flat_process_op" it will emit that symbol with the physical
 103 address of the 32bit "flat" version of the process_op() C function.
 104
 105 Build garbage collection
 106 ------------------------
 107
 108 To reduce the overall size of the final SeaBIOS binary the build
 109 supports automatically weeding out of unused code and variables. This
 110 is done with two separate processes: when supported the gcc
 111 "-fwhole-program" compilation flag is used, and the layoutrom.py
 112 script checks for unreferenced ELF sections. The layoutrom.py script
 113 builds the final linker scripts with only referenced ELF sections, and
 114 thus unreferenced sections are weeded out from the final objects.
 115
 116 When writing C code, it is necessary to mark C functions with the
 117 VISIBLE16, VISIBLE32SEG, or VISIBLE32FLAT macros if the functions are
 118 ever referenced from assembler code. These macros ensure the
 119 corresponding C function is emitted by the C compiler when compiling
 120 for the given memory mode. These macros, however, do not affect the
 121 layoutrom.py reference check, so even a function decorated with one of
 122 the above macros can be weeded out from the final object if it is
 123 never referenced.
 124
 125 Code relocation
 126 ---------------
 127
 128 To further reduce the runtime memory size of the BIOS, the build
 129 supports runtime self-relocation. Normally SeaBIOS is loaded into
 130 memory in the memory region at 0xC0000-0x100000. This is convenient
 131 for initial binary deployment, but the space competes with memory
 132 requirements for Option ROMs, BIOS tables, and runtime storage. By
 133 default, SeaBIOS will self-relocate its one-time initialization code
 134 to free up space in this region.
 135
 136 To support this feature, the build attempts to automatically detect
 137 which C code is exclusively initialization phase code (see
 138 layoutrom.py:checkRuntime()). It does this by finding all functions
 139 decorated with the VISIBLE32INIT macro and all functions only
 140 reachable via functions with that macro. These "init only" functions
 141 are then grouped together and their location and size is stored in the
 142 binary for the runtime code to relocate (see post.c:reloc_preinit()).
 143
 144 The build also locates all cross section code references along with
 145 all absolute memory addresses in the "init only" code. These addresses
 146 need to be modified with the new run-time address in order for the
 147 code to successfully run at a new address. The build finds the
 148 location of the addresses (see layoutrom.py:getRelocs()) and stores
 149 the information in the final binary.
 150
 151 Final binary checks
 152 ===================
 153
 154 At the conclusion of the main linking stage, the code is contained in
 155 the file **rom.o**. This object file contains all of the assembler
 156 code, variables, and the C code from all three memory model modes.
 157
 158 At this point the **scripts/checkrom.py** script is run to perform
 159 final checks on the code. The script performs some sanity checks, it
 160 may update some tables in the binary, and it reports some size
 161 information.
 162
 163 After the checkrom.py script is run the final user visible binary is
 164 produced. The name of the final binary is either **bios.bin**,
 165 **Csm16.bin**, or **bios.bin.elf** depending on the SeaBIOS build
 166 requested.