qemu/roms/seabios/docs/Execution_and_code_flow.md

   1 This page provides a high-level description of some of the major code
   2 phases that SeaBIOS transitions through and general information on
   3 overall code flow.
   4
   5 SeaBIOS code phases
   6 ===================
   7
   8 The SeaBIOS code goes through a few distinct code phases during its
   9 execution lifecycle. Understanding these code phases can help when
  10 reading and enhancing the code.
  11
  12 POST phase
  13 ----------
  14
  15 The Power On Self Test (POST) phase is the initialization phase of the
  16 BIOS. This phase is entered when SeaBIOS first starts execution. The
  17 goal of the phase is to initialize internal state, initialize external
  18 interfaces, detect and setup hardware, and to then start the boot
  19 phase.
  20
  21 On emulators, this phase starts when the CPU starts execution in 16bit
  22 mode at 0xFFFF0000:FFF0. The emulators map the SeaBIOS binary to this
  23 address, and SeaBIOS arranges for romlayout.S:reset_vector() to be
  24 present there. This code calls romlayout.S:entry_post() which then
  25 calls post.c:handle_post() in 32bit mode.
  26
  27 On coreboot, the build arranges for romlayout.S:entry_elf() to be
  28 called in 32bit mode. This then calls post.c:handle_post().
  29
  30 On CSM, the build arranges for romlayout.S:entry_csm() to be called
  31 (in 16bit mode). This then calls csm.c:handle_csm() in 32bit mode.
  32 Unlike on the emulators and coreboot, the SeaBIOS CSM POST phase is
  33 orchastrated with UEFI and there are several calls back and forth
  34 between SeaBIOS and UEFI via handle_csm() throughout the POST
  35 process.
  36
  37 The POST phase itself has several sub-phases.
  38
  39 * The "preinit" sub-phase: code run prior to code relocation.
  40 * The "init" sub-phase: code to initialize internal variables and
  41   interfaces.
  42 * The "setup" sub-phase: code to setup hardware and drivers.
  43 * The "prepboot" sub-phase: code to finalize interfaces and prepare
  44   for the boot phase.
  45
  46 At completion of the POST phase, SeaBIOS invokes an "int 0x19"
  47 software interrupt in 16bit mode which begins the boot phase.
  48
  49 Boot phase
  50 ----------
  51
  52 The goal of the boot phase is to load the first portion of the
  53 operating system's boot loader into memory and start execution of that
  54 boot loader. This phase starts when a software interrupt ("int 0x19"
  55 or "int 0x18") is invoked. The code flow starts in 16bit mode in
  56 romlayout.S:entry_19() or romlayout.S:entry_18() which then
  57 transition to 32bit mode and call boot.c:handle_19() or
  58 boot.c:handle_18().
  59
  60 The boot phase is technically also part of the "runtime" phase of
  61 SeaBIOS. It is typically invoked immiediately after the POST phase,
  62 but it can also be invoked by an operating system or be invoked
  63 multiple times in an attempt to find a valid boot media. Although the
  64 boot phase C code runs in 32bit mode it does not have write access to
  65 the 0x0f0000-0x100000 memory region and can not call the various
  66 malloc_X() calls. See [Memory Model](Memory Model) for
  67 more information.
  68
  69 Main runtime phase
  70 ------------------
  71
  72 The main runtime phase occurs after the boot phase starts the
  73 operating system. Once in this phase, the SeaBIOS code may be invoked
  74 by the operating system using various 16bit and 32bit calls. The goal
  75 of this phase is to support these legacy calling interfaces and to
  76 provide compatibility with BIOS standards. There are multiple entry
  77 points for the BIOS - see the entry_XXX() assembler functions in
  78 romlayout.S.
  79
  80 Callers use most of these legacy entry points by setting up a
  81 particular CPU register state, invoking the BIOS, and then inspecting
  82 the returned CPU register state. To handle this, SeaBIOS will backup
  83 the current register state into a "struct bregs" (see romlayout.S,
  84 entryfuncs.S, and bregs.h) on call entry and then pass this struct to
  85 the C code. The C code can then inspect the register state and modify
  86 it. The assembler entry functions will then restore the (possibly
  87 modified) register state from the "struct bregs" on return to the
  88 caller.
  89
  90 Resume and reboot
  91 -----------------
  92
  93 As noted above, on emulators SeaBIOS handles the 0xFFFF0000:FFF0
  94 machine startup execution vector. This vector is also called on
  95 machine faults and on some machine "resume" events. It can also be
  96 called (as 0xF0000:FFF0) by software as a request to reboot the
  97 machine (on emulators, coreboot, and CSM).
  98
  99 The SeaBIOS "resume and reboot" code handles these calls and attempts
 100 to determine the desired action of the caller. Code flow starts in
 101 16bit mode in romlayout.S:reset_vector() which calls
 102 romlayout.S:entry_post() which calls romlayout.S:entry_resume() which
 103 calls resume.c:handle_resume(). Depending on the request the
 104 handle_resume() code may transition to 32bit mode.
 105
 106 Technically this code is part of the "runtime" phase, so even though
 107 parts of it run in 32bit mode it still has the same limitations of the
 108 runtime phase.
 109
 110 Threads
 111 =======
 112
 113 Internally SeaBIOS implements a simple cooperative multi-tasking
 114 system. The system works by giving each "thread" its own stack, and
 115 the system round-robins between these stacks whenever a thread issues
 116 a yield() call. This "threading" system may be more appropriately
 117 described as [coroutines](http://en.wikipedia.org/wiki/Coroutine).
 118 These "threads" do not run on multiple CPUs and are not preempted, so
 119 atomic memory accesses and complex locking is not required.
 120
 121 The goal of these threads is to reduce overall boot time by
 122 parallelizing hardware delays. (For example, by allowing the wait for
 123 an ATA harddrive to spinup and respond to commands to occur in
 124 parallel with the wait for a PS/2 keyboard to respond to a setup
 125 command.) These hardware setup threads are only available during the
 126 "setup" sub-phase of the [POST phase](#POST_phase).
 127
 128 The code that implements threads is in stacks.c.
 129
 130 Hardware interrupts
 131 ===================
 132
 133 The SeaBIOS C code always runs with hardware interrupts disabled. All
 134 of the C code entry points (see romlayout.S) are careful to explicitly
 135 disable hardware interrupts (via "cli"). Because running with
 136 interrupts disabled increases interrupt latency, any C code that could
 137 loop for a significant amount of time (more than about 1 ms) should
 138 periodically call yield(). The yield() call will briefly enable
 139 hardware interrupts to occur, then disable interrupts, and then resume
 140 execution of the C code.
 141
 142 There are two main reasons why SeaBIOS always runs C code with
 143 interrupts disabled. The first reason is that external software may
 144 override the default SeaBIOS handlers that are called on a hardware
 145 interrupt event. Indeed, it is common for DOS based applications to do
 146 this. These legacy third party interrupt handlers may have
 147 undocumented expections (such as stack location and stack size) and
 148 may attempt to call back into the various SeaBIOS software services.
 149 Greater compatibility and more reproducible results can be achieved by
 150 only permitting hardware interrupts at specific points (via yield()
 151 calls). The second reason is that much of SeaBIOS runs in 32bit mode.
 152 Attempting to handle interrupts in both 16bit mode and 32bit mode and
 153 switching between modes to delegate those interrupts is an unneeded
 154 complexity. Although disabling interrupts can increase interrupt
 155 latency, this only impacts legacy systems where the small increase in
 156 interrupt latency is unlikely to be noticeable.
 157
 158 Extra 16bit stack
 159 =================
 160
 161 SeaBIOS implements 16bit real mode handlers for both hardware
 162 interrupts and software request "interrupts". In a traditional BIOS,
 163 these requests would use the caller's stack space. However, the
 164 minimum amount of space the caller must provide has not been
 165 standardized and very old DOS programs have been observed to allocate
 166 very small amounts of stack space (100 bytes or less).
 167
 168 By default, SeaBIOS now switches to its own stack on most 16bit real
 169 mode entry points. This extra stack space is allocated in ["low
 170 memory"](Memory Model). It ensures SeaBIOS uses a minimal amount of a
 171 callers stack (typically no more than 16 bytes) for these legacy
 172 calls. (More recently defined BIOS interfaces such as those that
 173 support 16bit protected and 32bit protected mode calls standardize a
 174 minimum stack size with adequete space, and SeaBIOS generally will not
 175 use its extra stack in these cases.)
 176
 177 The code to implement this stack "hopping" is in romlayout.S and in
 178 stacks.c.