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. The call32() and stack_hop_back()
  96 macros automatically add the required prefix for C code, but the
  97 prefixes need to be explicitly added in assembler code.
  98
  99 Build garbage collection
 100 ------------------------
 101
 102 To reduce the overall size of the final SeaBIOS binary the build
 103 supports automatically weeding out of unused code and variables. This
 104 is done with two separate processes: when supported the gcc
 105 "-fwhole-program" compilation flag is used, and the layoutrom.py
 106 script checks for unreferenced ELF sections. The layoutrom.py script
 107 builds the final linker scripts with only referenced ELF sections, and
 108 thus unreferenced sections are weeded out from the final objects.
 109
 110 When writing C code, it is necessary to mark C functions with the
 111 VISIBLE16, VISIBLE32SEG, or VISIBLE32FLAT macros if the functions are
 112 ever referenced from assembler code. These macros ensure the
 113 corresponding C function is emitted by the C compiler when compiling
 114 for the given memory mode. These macros, however, do not affect the
 115 layoutrom.py reference check, so even a function decorated with one of
 116 the above macros can be weeded out from the final object if it is
 117 never referenced.
 118
 119 Code relocation
 120 ---------------
 121
 122 To further reduce the runtime memory size of the BIOS, the build
 123 supports runtime self-relocation. Normally SeaBIOS is loaded into
 124 memory in the memory region at 0xC0000-0x100000. This is convenient
 125 for initial binary deployment, but the space competes with memory
 126 requirements for Option ROMs, BIOS tables, and runtime storage. By
 127 default, SeaBIOS will self-relocate its one-time initialization code
 128 to free up space in this region.
 129
 130 To support this feature, the build attempts to automatically detect
 131 which C code is exclusively initialization phase code (see
 132 layoutrom.py:checkRuntime()). It does this by finding all functions
 133 decorated with the VISIBLE32INIT macro and all functions only
 134 reachable via functions with that macro. These "init only" functions
 135 are then grouped together and their location and size is stored in the
 136 binary for the runtime code to relocate (see post.c:reloc_preinit()).
 137
 138 The build also locates all cross section code references along with
 139 all absolute memory addresses in the "init only" code. These addresses
 140 need to be modified with the new run-time address in order for the
 141 code to successfully run at a new address. The build finds the
 142 location of the addresses (see layoutrom.py:getRelocs()) and stores
 143 the information in the final binary.
 144
 145 Final binary checks
 146 ===================
 147
 148 At the conclusion of the main linking stage, the code is contained in
 149 the file **rom.o**. This object file contains all of the assembler
 150 code, variables, and the C code from all three memory model modes.
 151
 152 At this point the **scripts/checkrom.py** script is run to perform
 153 final checks on the code. The script performs some sanity checks, it
 154 may update some tables in the binary, and it reports some size
 155 information.
 156
 157 After the checkrom.py script is run the final user visible binary is
 158 produced. The name of the final binary is either **bios.bin**,
 159 **Csm16.bin**, or **bios.bin.elf** depending on the SeaBIOS build
 160 requested.