| 1 | /* $Id: bs3kit-docs.c 98103 2023-01-17 14:15:46Z vboxsync $ */
|
|---|
| 2 | /** @file
|
|---|
| 3 | * BS3Kit - Documentation.
|
|---|
| 4 | */
|
|---|
| 5 |
|
|---|
| 6 | /*
|
|---|
| 7 | * Copyright (C) 2007-2023 Oracle and/or its affiliates.
|
|---|
| 8 | *
|
|---|
| 9 | * This file is part of VirtualBox base platform packages, as
|
|---|
| 10 | * available from https://www.virtualbox.org.
|
|---|
| 11 | *
|
|---|
| 12 | * This program is free software; you can redistribute it and/or
|
|---|
| 13 | * modify it under the terms of the GNU General Public License
|
|---|
| 14 | * as published by the Free Software Foundation, in version 3 of the
|
|---|
| 15 | * License.
|
|---|
| 16 | *
|
|---|
| 17 | * This program is distributed in the hope that it will be useful, but
|
|---|
| 18 | * WITHOUT ANY WARRANTY; without even the implied warranty of
|
|---|
| 19 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|---|
| 20 | * General Public License for more details.
|
|---|
| 21 | *
|
|---|
| 22 | * You should have received a copy of the GNU General Public License
|
|---|
| 23 | * along with this program; if not, see <https://www.gnu.org/licenses>.
|
|---|
| 24 | *
|
|---|
| 25 | * The contents of this file may alternatively be used under the terms
|
|---|
| 26 | * of the Common Development and Distribution License Version 1.0
|
|---|
| 27 | * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
|
|---|
| 28 | * in the VirtualBox distribution, in which case the provisions of the
|
|---|
| 29 | * CDDL are applicable instead of those of the GPL.
|
|---|
| 30 | *
|
|---|
| 31 | * You may elect to license modified versions of this file under the
|
|---|
| 32 | * terms and conditions of either the GPL or the CDDL or both.
|
|---|
| 33 | *
|
|---|
| 34 | * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
|
|---|
| 35 | */
|
|---|
| 36 |
|
|---|
| 37 |
|
|---|
| 38 |
|
|---|
| 39 | /** @page pg_bs3kit BS3Kit - Boot Sector Kit \#3
|
|---|
| 40 | *
|
|---|
| 41 | * The BS3Kit is a framework for bare metal floppy/usb image tests.
|
|---|
| 42 | *
|
|---|
| 43 | * The 3rd iteration of the framework includes support for 16-bit and 32-bit
|
|---|
| 44 | * C/C++ code, with provisions for 64-bit C code to possibly be added later.
|
|---|
| 45 | * The C code have to do without a runtime library, otherwhat what we can share
|
|---|
| 46 | * possibly with IPRT.
|
|---|
| 47 | *
|
|---|
| 48 | * This iteration also adds a real linker into the picture, which is an
|
|---|
| 49 | * improvment over early when all had to done in a single assembler run with
|
|---|
| 50 | * lots of includes and macros controlling what we needed. The functions are no
|
|---|
| 51 | * in separate files and compiled/assembled into libraries, so the linker will
|
|---|
| 52 | * only include exactly what is needed. The current linker is the OpenWatcom
|
|---|
| 53 | * one, wlink, that we're already using when building the BIOSes. If it wasn't
|
|---|
| 54 | * for the segment/selector fixups in 16-bit code (mostly), maybe we could
|
|---|
| 55 | * convince the ELF linker from GNU binutils to do the job too (with help from
|
|---|
| 56 | * the ).
|
|---|
| 57 | *
|
|---|
| 58 | *
|
|---|
| 59 | * @sa grp_bs3kit, grp_bs3kit_tmpl, grp_bs3kit_cmn, grp_bs3kit_mode,
|
|---|
| 60 | * grp_bs3kit_system
|
|---|
| 61 | *
|
|---|
| 62 | * @section sec_calling_convention Calling convention
|
|---|
| 63 | *
|
|---|
| 64 | * Because we're not mixing with C code, we will use __cdecl for 16-bit and
|
|---|
| 65 | * 32-bit code, where as 64-bit code will use the microsoft calling AMD64
|
|---|
| 66 | * convention. To avoid unnecessary %ifdef'ing in assembly code, we will use a
|
|---|
| 67 | * macro to load the RCX, RDX, R8 and R9 registers off the stack in 64-bit
|
|---|
| 68 | * assembly code.
|
|---|
| 69 | *
|
|---|
| 70 | * Register treatment in 16-bit __cdecl, 32-bit __cdecl and 64-bit msabi:
|
|---|
| 71 | *
|
|---|
| 72 | * | Register | 16-bit | 32-bit | 64-bit | ASM template |
|
|---|
| 73 | * | ------------ | ----------- | ---------- | --------------- | ------------ |
|
|---|
| 74 | * | EAX, RAX | volatile | volatile | volatile | volatile |
|
|---|
| 75 | * | EBX, RBX | volatile | preserved | preserved | both |
|
|---|
| 76 | * | ECX, RCX | volatile | volatile | volatile, arg 0 | volatile |
|
|---|
| 77 | * | EDX, RDX | volatile | volatile | volatile, arg 1 | volatile |
|
|---|
| 78 | * | ESP, RSP | preserved | preserved | preserved | preserved |
|
|---|
| 79 | * | EBP, RBP | preserved | preserved | preserved | preserved |
|
|---|
| 80 | * | EDI, RDI | preserved | preserved | preserved | preserved |
|
|---|
| 81 | * | ESI, RSI | preserved | preserved | preserved | preserved |
|
|---|
| 82 | * | R8 | volatile | volatile | volatile, arg 2 | volatile |
|
|---|
| 83 | * | R9 | volatile | volatile | volatile, arg 3 | volatile |
|
|---|
| 84 | * | R10 | volatile | volatile | volatile | volatile |
|
|---|
| 85 | * | R11 | volatile | volatile | volatile | volatile |
|
|---|
| 86 | * | R12 | volatile | volatile | preserved | preserved(*) |
|
|---|
| 87 | * | R13 | volatile | volatile | preserved | preserved(*) |
|
|---|
| 88 | * | R14 | volatile | volatile | preserved | preserved(*) |
|
|---|
| 89 | * | R15 | volatile | volatile | preserved | preserved(*) |
|
|---|
| 90 | * | RFLAGS.DF | =0 | =0 | =0 | =0 |
|
|---|
| 91 | * | CS | preserved | preserved | preserved | preserved |
|
|---|
| 92 | * | DS | preserved! | preserved? | preserved | both |
|
|---|
| 93 | * | ES | volatile | volatile | preserved | volatile |
|
|---|
| 94 | * | FS | preserved | preserved | preserved | preserved |
|
|---|
| 95 | * | GS | preserved | volatile | preserved | both |
|
|---|
| 96 | * | SS | preserved | preserved | preserved | preserved |
|
|---|
| 97 | *
|
|---|
| 98 | * The 'both' here means that we preserve it wrt to our caller, while at the
|
|---|
| 99 | * same time assuming anything we call will clobber it.
|
|---|
| 100 | *
|
|---|
| 101 | * The 'preserved(*)' marking of R12-R15 indicates that they'll be preserved in
|
|---|
| 102 | * 64-bit mode, but may be changed in certain cases when running 32-bit or
|
|---|
| 103 | * 16-bit code. This is especially true if switching CPU mode, e.g. from 32-bit
|
|---|
| 104 | * protected mode to 32-bit long mode.
|
|---|
| 105 | *
|
|---|
| 106 | * Return values are returned in the xAX register, but with the following
|
|---|
| 107 | * caveats for values larger than ARCH_BITS:
|
|---|
| 108 | * - 16-bit code:
|
|---|
| 109 | * - 32-bit values are returned in AX:DX, where AX holds bits 15:0 and
|
|---|
| 110 | * DX bits 31:16.
|
|---|
| 111 | * - 64-bit values are returned in DX:CX:BX:AX, where DX holds bits
|
|---|
| 112 | * 15:0, CX bits 31:16, BX bits 47:32, and AX bits 63:48.
|
|---|
| 113 | * - 32-bit code:
|
|---|
| 114 | * - 64-bit values are returned in EAX:EDX, where eax holds the least
|
|---|
| 115 | * significant bits.
|
|---|
| 116 | *
|
|---|
| 117 | * The DS segment register is pegged to BS3DATA16_GROUP in 16-bit code so that
|
|---|
| 118 | * we don't need to reload it all the time. This allows us to modify it in
|
|---|
| 119 | * ring-0 and mode switching code without ending up in any serious RPL or DPL
|
|---|
| 120 | * trouble. In 32-bit and 64-bit mode the DS register is a flat, unlimited,
|
|---|
| 121 | * writable selector.
|
|---|
| 122 | *
|
|---|
| 123 | * In 16-bit and 32-bit code we do not assume anything about ES, FS, and GS.
|
|---|
| 124 | *
|
|---|
| 125 | *
|
|---|
| 126 | * For an in depth coverage of x86 and AMD64 calling convensions, see
|
|---|
| 127 | * http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/function-calling-conventions.html
|
|---|
| 128 | *
|
|---|
| 129 | *
|
|---|
| 130 | *
|
|---|
| 131 | * @section sec_modes Execution Modes
|
|---|
| 132 | *
|
|---|
| 133 | * BS3Kit defines a number of execution modes in order to be able to test the
|
|---|
| 134 | * full CPU capabilities (that VirtualBox care about anyways). It currently
|
|---|
| 135 | * omits system management mode, hardware virtualization modes, and security
|
|---|
| 136 | * modes as those aren't supported by VirtualBox or are difficult to handle.
|
|---|
| 137 | *
|
|---|
| 138 | * The modes are categorized into normal and weird ones.
|
|---|
| 139 | *
|
|---|
| 140 | * The normal ones are:
|
|---|
| 141 | * + RM - Real mode.
|
|---|
| 142 | * + PE16 - Protected mode running 16-bit code, 16-bit TSS and 16-bit handlers.
|
|---|
| 143 | * + PE32 - Protected mode running 32-bit code, 32-bit TSS and 32-bit handlers.
|
|---|
| 144 | * + PEV86 - Protected mode running v8086 code, 32-bit TSS and 32-bit handlers.
|
|---|
| 145 | * + PP16 - 386 paged mode running 16-bit code, 16-bit TSS and 16-bit handlers.
|
|---|
| 146 | * + PP32 - 386 paged mode running 32-bit code, 32-bit TSS and 32-bit handlers.
|
|---|
| 147 | * + PPV86 - 386 paged mode running v8086 code, 32-bit TSS and 32-bit handlers.
|
|---|
| 148 | * + PAE16 - PAE paged mode running 16-bit code, 16-bit TSS and 16-bit handlers.
|
|---|
| 149 | * + PAE32 - PAE paged mode running 32-bit code, 32-bit TSS and 32-bit handlers.
|
|---|
| 150 | * + PAEV86 - PAE paged mode running v8086 code, 32-bit TSS and 32-bit handlers.
|
|---|
| 151 | * + LM16 - AMD64 long mode running 16-bit code, 64-bit TSS and 64-bit handlers.
|
|---|
| 152 | * + LM32 - AMD64 long mode running 32-bit code, 64-bit TSS and 64-bit handlers.
|
|---|
| 153 | * + LM64 - AMD64 long mode running 64-bit code, 64-bit TSS and 64-bit handlers.
|
|---|
| 154 | *
|
|---|
| 155 | * The weird ones:
|
|---|
| 156 | * + PE16_32 - Protected mode running 16-bit code, 16-bit TSS and 16-bit handlers.
|
|---|
| 157 | * + PE16_V86 - Protected mode running 16-bit code, 16-bit TSS and 16-bit handlers.
|
|---|
| 158 | * + PE32_16 - Protected mode running 32-bit code, 32-bit TSS and 32-bit handlers.
|
|---|
| 159 | * + PP16_32 - 386 paged mode running 16-bit code, 16-bit TSS and 16-bit handlers.
|
|---|
| 160 | * + PP16_V86 - 386 paged mode running 16-bit code, 16-bit TSS and 16-bit handlers.
|
|---|
| 161 | * + PP32_16 - 386 paged mode running 32-bit code, 32-bit TSS and 32-bit handlers.
|
|---|
| 162 | * + PAE16_32 - PAE paged mode running 16-bit code, 16-bit TSS and 16-bit handlers.
|
|---|
| 163 | * + PAE16_V86 - PAE paged mode running 16-bit code, 16-bit TSS and 16-bit handlers.
|
|---|
| 164 | * + PAE32_16 - PAE paged mode running 32-bit code, 32-bit TSS and 32-bit handlers.
|
|---|
| 165 | *
|
|---|
| 166 | * Actually, the PE32_16, PP32_16 and PAE32_16 modes aren't all that weird and fits in
|
|---|
| 167 | * right next to LM16 and LM32, but this is the way it ended up. :-)
|
|---|
| 168 | *
|
|---|
| 169 | */
|
|---|
| 170 |
|
|---|
