Adding upstream version 6.0.4-dfsg.upstream/6.0.4-dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 160 insertions, 0 deletions

diff --git a/src/VBox/ValidationKit/bootsectors/bs3kit/bs3kit-docs.c b/src/VBox/ValidationKit/bootsectors/bs3kit/bs3kit-docs.c
new file mode 100644
index 00000000..8d1c86cc
--- /dev/null
+++ b/src/VBox/ValidationKit/bootsectors/bs3kit/bs3kit-docs.c
@@ -0,0 +1,160 @@
+/* $Id: bs3kit-docs.c $ */
+/** @file
+ * BS3Kit - Documentation.
+ */
+
+/*
+ * Copyright (C) 2007-2019 Oracle Corporation
+ *
+ * This file is part of VirtualBox Open Source Edition (OSE), as
+ * available from http://www.virtualbox.org. This file is free software;
+ * you can redistribute it and/or modify it under the terms of the GNU
+ * General Public License (GPL) as published by the Free Software
+ * Foundation, in version 2 as it comes in the "COPYING" file of the
+ * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
+ * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
+ *
+ * The contents of this file may alternatively be used under the terms
+ * of the Common Development and Distribution License Version 1.0
+ * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
+ * VirtualBox OSE distribution, in which case the provisions of the
+ * CDDL are applicable instead of those of the GPL.
+ *
+ * You may elect to license modified versions of this file under the
+ * terms and conditions of either the GPL or the CDDL or both.
+ */
+
+
+
+/** @page pg_bs3kit BS3Kit - Boot Sector Kit \#3
+ *
+ * The BS3Kit is a framework for bare metal floppy/usb image tests.
+ *
+ * The 3rd iteration of the framework includes support for 16-bit and 32-bit
+ * C/C++ code, with provisions for 64-bit C code to possibly be added later.
+ * The C code have to do without a runtime library, otherwhat what we can share
+ * possibly with IPRT.
+ *
+ * This iteration also adds a real linker into the picture, which is an
+ * improvment over early when all had to done in a single assembler run with
+ * lots of includes and macros controlling what we needed.  The functions are no
+ * in separate files and compiled/assembled into libraries, so the linker will
+ * only include exactly what is needed.  The current linker is the OpenWatcom
+ * one, wlink, that we're already using when building the BIOSes.  If it wasn't
+ * for the segment/selector fixups in 16-bit code (mostly), maybe we could
+ * convince the ELF linker from GNU binutils to do the job too (with help from
+ * the ).
+ *
+ *
+ * @sa grp_bs3kit, grp_bs3kit_tmpl, grp_bs3kit_cmn, grp_bs3kit_mode,
+ *     grp_bs3kit_system
+ *
+ * @section sec_calling_convention      Calling convention
+ *
+ * Because we're not mixing with C code, we will use __cdecl for 16-bit and
+ * 32-bit code, where as 64-bit code will use the microsoft calling AMD64
+ * convention.  To avoid unnecessary %ifdef'ing in assembly code, we will use a
+ * macro to load the RCX, RDX, R8 and R9 registers off the stack in 64-bit
+ * assembly code.
+ *
+ * Register treatment in 16-bit __cdecl, 32-bit __cdecl and 64-bit msabi:
+ *
+ * | Register     | 16-bit      | 32-bit     | 64-bit          | ASM template |
+ * | ------------ | ----------- | ---------- | --------------- | ------------ |
+ * | EAX, RAX     | volatile    | volatile   | volatile        | volatile     |
+ * | EBX, RBX     | volatile    | preserved  | preserved       | both         |
+ * | ECX, RCX     | volatile    | volatile   | volatile, arg 0 | volatile     |
+ * | EDX, RDX     | volatile    | volatile   | volatile, arg 1 | volatile     |
+ * | ESP, RSP     | preserved   | preserved  | preserved       | preserved    |
+ * | EBP, RBP     | preserved   | preserved  | preserved       | preserved    |
+ * | EDI, RDI     | preserved   | preserved  | preserved       | preserved    |
+ * | ESI, RSI     | preserved   | preserved  | preserved       | preserved    |
+ * | R8           | volatile    | volatile   | volatile, arg 2 | volatile     |
+ * | R9           | volatile    | volatile   | volatile, arg 3 | volatile     |
+ * | R10          | volatile    | volatile   | volatile        | volatile     |
+ * | R11          | volatile    | volatile   | volatile        | volatile     |
+ * | R12          | volatile    | volatile   | preserved       | preserved(*) |
+ * | R13          | volatile    | volatile   | preserved       | preserved(*) |
+ * | R14          | volatile    | volatile   | preserved       | preserved(*) |
+ * | R15          | volatile    | volatile   | preserved       | preserved(*) |
+ * | RFLAGS.DF    | =0          | =0         | =0              | =0           |
+ * | CS           | preserved   | preserved  | preserved       | preserved    |
+ * | DS           | preserved!  | preserved? | preserved       | both         |
+ * | ES           | volatile    | volatile   | preserved       | volatile     |
+ * | FS           | preserved   | preserved  | preserved       | preserved    |
+ * | GS           | preserved   | volatile   | preserved       | both         |
+ * | SS           | preserved   | preserved  | preserved       | preserved    |
+ *
+ * The 'both' here means that we preserve it wrt to our caller, while at the
+ * same time assuming anything we call will clobber it.
+ *
+ * The 'preserved(*)' marking of R12-R15 indicates that they'll be preserved in
+ * 64-bit mode, but may be changed in certain cases when running 32-bit or
+ * 16-bit code.  This is especially true if switching CPU mode, e.g. from 32-bit
+ * protected mode to 32-bit long mode.
+ *
+ * Return values are returned in the xAX register, but with the following
+ * caveats for values larger than ARCH_BITS:
+ *      - 16-bit code:
+ *          - 32-bit values are returned in AX:DX, where AX holds bits 15:0 and
+ *            DX bits 31:16.
+ *          - 64-bit values are returned in DX:CX:BX:AX, where DX holds bits
+ *            15:0, CX bits 31:16, BX bits 47:32, and AX bits 63:48.
+ *      - 32-bit code:
+ *          - 64-bit values are returned in EAX:EDX, where eax holds the least
+ *            significant bits.
+ *
+ * The DS segment register is pegged to BS3DATA16_GROUP in 16-bit code so that
+ * we don't need to reload it all the time.  This allows us to modify it in
+ * ring-0 and mode switching code without ending up in any serious RPL or DPL
+ * trouble.  In 32-bit and 64-bit mode the DS register is a flat, unlimited,
+ * writable selector.
+ *
+ * In 16-bit and 32-bit code we do not assume anything about ES, FS, and GS.
+ *
+ *
+ * For an in depth coverage of x86 and AMD64 calling convensions, see
+ * http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/function-calling-conventions.html
+ *
+ *
+ *
+ * @section sec_modes               Execution Modes
+ *
+ * BS3Kit defines a number of execution modes in order to be able to test the
+ * full CPU capabilities (that VirtualBox care about anyways).  It currently
+ * omits system management mode, hardware virtualization modes, and security
+ * modes as those aren't supported by VirtualBox or are difficult to handle.
+ *
+ * The modes are categorized into normal and weird ones.
+ *
+ * The normal ones are:
+ *    + RM     - Real mode.
+ *    + PE16   - Protected  mode running 16-bit code, 16-bit TSS and 16-bit handlers.
+ *    + PE32   - Protected  mode running 32-bit code, 32-bit TSS and 32-bit handlers.
+ *    + PEV86  - Protected  mode running  v8086 code, 32-bit TSS and 32-bit handlers.
+ *    + PP16   - 386  paged mode running 16-bit code, 16-bit TSS and 16-bit handlers.
+ *    + PP32   - 386  paged mode running 32-bit code, 32-bit TSS and 32-bit handlers.
+ *    + PPV86  - 386  paged mode running  v8086 code, 32-bit TSS and 32-bit handlers.
+ *    + PAE16  - PAE  paged mode running 16-bit code, 16-bit TSS and 16-bit handlers.
+ *    + PAE32  - PAE  paged mode running 32-bit code, 32-bit TSS and 32-bit handlers.
+ *    + PAEV86 - PAE  paged mode running  v8086 code, 32-bit TSS and 32-bit handlers.
+ *    + LM16   - AMD64 long mode running 16-bit code, 64-bit TSS and 64-bit handlers.
+ *    + LM32   - AMD64 long mode running 32-bit code, 64-bit TSS and 64-bit handlers.
+ *    + LM64   - AMD64 long mode running 64-bit code, 64-bit TSS and 64-bit handlers.
+ *
+ * The weird ones:
+ *    + PE16_32   - Protected  mode running 16-bit code, 16-bit TSS and 16-bit handlers.
+ *    + PE16_V86  - Protected  mode running 16-bit code, 16-bit TSS and 16-bit handlers.
+ *    + PE32_16   - Protected  mode running 32-bit code, 32-bit TSS and 32-bit handlers.
+ *    + PP16_32   - 386  paged mode running 16-bit code, 16-bit TSS and 16-bit handlers.
+ *    + PP16_V86  - 386  paged mode running 16-bit code, 16-bit TSS and 16-bit handlers.
+ *    + PP32_16   - 386  paged mode running 32-bit code, 32-bit TSS and 32-bit handlers.
+ *    + PAE16_32  - PAE  paged mode running 16-bit code, 16-bit TSS and 16-bit handlers.
+ *    + PAE16_V86 - PAE  paged mode running 16-bit code, 16-bit TSS and 16-bit handlers.
+ *    + PAE32_16  - PAE  paged mode running 32-bit code, 32-bit TSS and 32-bit handlers.
+ *
+ * Actually, the PE32_16, PP32_16 and PAE32_16 modes aren't all that weird and fits in
+ * right next to LM16 and LM32, but this is the way it ended up. :-)
+ *
+ */
+