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

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

1 files changed, 219 insertions, 0 deletions

diff --git a/doc/VBox-doc.c b/doc/VBox-doc.c
new file mode 100644
index 00000000..79fd4b16
--- /dev/null
+++ b/doc/VBox-doc.c
@@ -0,0 +1,219 @@
+/* $Id: VBox-doc.c $ */
+/** @file
+ * VirtualBox Top Level Documentation File.
+ */
+
+/*
+ * Copyright (C) 2006-2022 Oracle and/or its affiliates.
+ *
+ * This file is part of VirtualBox base platform packages, as
+ * available from https://www.virtualbox.org.
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation, in version 3 of the
+ * License.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, see <https://www.gnu.org/licenses>.
+ *
+ * SPDX-License-Identifier: GPL-3.0-only
+ */
+
+
+/** @mainpage   VirtualBox
+ *
+ * (add introduction here)
+ *
+ * @section pg_main_comp    Components
+ *
+ *  - VM / @ref pg_vmm "VMM" / GVM / @ref pg_gvmm "GVMM" - Virtual Machine
+ *    Monitor.
+ *      - @ref pg_cfgm
+ *      - @ref pg_cpum
+ *      - @ref pg_dbgf
+ *          - @ref pg_dbgf_addr_space
+ *          - @ref pg_dbgf_vmcore
+ *          - @ref pg_dbgf_module
+ *          - @ref pg_dbgc
+ *          - VBoxDbg - Debugger GUI (Qt).
+ *      - @ref grp_dis
+ *      - @ref pg_em
+ *      - @ref pg_gim
+ *      - @ref pg_hm
+ *      - @ref pg_iem
+ *      - @ref pg_nem
+ *      - @ref pg_gmm
+ *          - @ref pg_mm
+ *          - @ref pg_pgm
+ *              - @ref pg_pgm_phys
+ *              - @ref pg_pgm_pool
+ *          - @ref pg_selm
+ *      - @ref pg_iom
+ *      - @ref pg_pdm
+ *          - Devices / USB Devices, Drivers and their public interfaces.
+ *          - Async I/O Completion API.
+ *          - Async Task API.
+ *          - Critical Section API.
+ *          - Queue API.
+ *          - Thread API.
+ *          - @ref pg_pdm_block_cache
+ *      - @ref pg_ssm
+ *      - @ref pg_stam
+ *      - @ref pg_tm
+ *      - @ref pg_trpm
+ *      - VMM docs:
+ *          - @ref pg_vmm_guideline
+ *          - @ref pg_raw
+ *  - Pluggable Components (via PDM).
+ *      - DevPCArch - PC Architecture Device (chipset, legacy ++).
+ *      - DevPCBios - Basic Input Output System.
+ *      - DevDMAC - DMA Controller.
+ *      - DevPIC - Programmable Interrupt Controller.
+ *      - DevPIT - Programmable Interval Timer (i8254).
+ *      - DevRTC - Real Time Clock.
+ *      - DevVGA - Video Graphic Array.
+ *      - DevPCI - Peripheral Component Interface (Bus).
+ *      - VBoxDev - Special PCI Device which serves as an interface between
+ *                  the VMM and the guest OS for the additions.
+ *      - @ref pg_pdm_audio "Audio":
+ *          - DevHda - Intel High Definition Audio Device Emulation.
+ *          - DevIchAc97 - ICH AC'97 Device Emulation.
+ *          - DevSB16 - SoundBlaster 16 Device Emulation.
+ *          - DrvAudio - Intermediate driver.
+ *          - DrvHostAudioAlsa - ALSA Host Audio Driver (Linux).
+ *          - DrvHostAudioCoreAudio - Core Audio Host Audio Driver (macOS).
+ *          - DrvHostAudioDebug - Debug Backend Driver.
+ *          - DrvHostAudioDSound - DirectSound Host Audio Driver (Windows).
+ *          - DrvHostAudioNull - NULL Backend Driver.
+ *          - DrvHostAudioOss - Open Sound System Host Audio Driver (Linux,
+ *            Solaris, ++).
+ *          - DrvHostAudioPulseAudio - PulseAudio Host Audio Driver (Linux).
+ *          - DrvHostAudioValidationKit - Validation Kit Test Driver.
+ *          - DrvHostAudioWasApi - Windows Audio Session API Host Audio Driver.
+ *      - Networking:
+ *          - DevPCNet - AMD PCNet Device Emulation.
+ *          - DevE1000 - Intel E1000 Device Emulation.
+ *          - DevEEPROM - Intel E1000 EPROM Device Emulation.
+ *          - SrvINetNetR0 - Internal Networking Ring-0 Service.
+ *          - DevINIP - IP Stack Service for the internal networking.
+ *          - DrvIntNet - Internal Networking Driver.
+ *          - DrvNetSniffer - Wireshark Compatible Sniffer Driver (pass thru).
+ *          - DrvNAT - Network Address Translation Driver.
+ *          - DrvTAP - Host Interface Networking Driver.
+ *      - Storage:
+ *          - DevATA - ATA ((E)IDE) Device Emulation.
+ *          - @ref pg_dev_ahci
+ *          - DevFDC - Floppy Controller Device Emulation.
+ *          - DrvBlock - Intermediate block driver.
+ *          - DrvHostBase - Common code for the host drivers.
+ *          - DrvHostDVD - Host DVD drive driver.
+ *          - DrvHostFloppy - Host floppy drive driver.
+ *          - DrvHostRawDisk - Host raw disk drive driver.
+ *          - DrvMediaISO - ISO media driver.
+ *          - DrvRawImage - Raw image driver (floppy images etc).
+ *          - DrvVD - Intermediate Virtual Drive (Media) driver.
+ *          - DrvVDI - VirtualBox Drive Image Container Driver.
+ *          - DrvVmdk - VMDK Drive Image Container Driver.
+ *      - USB:
+ *          - @ref pg_dev_ohci
+ *          - @ref pg_dev_ehci
+ *          - @ref pg_dev_vusb
+ *          - @ref pg_dev_vusb_old
+ *  - Host Drivers.
+ *      - SUPDRV - The Support driver (aka VBoxDrv).
+ *          - @ref pg_sup
+ *      - @ref pg_netflt
+ *      - @ref pg_netadp
+ *      - VBoxUSB - The USB support driver.
+ *      - @ref pg_netflt
+ *      - @ref pg_rawpci
+ *  - Host Services.
+ *      - @ref pg_hostclip
+ *      - Shared Folders.
+ *      - @ref pg_svc_guest_properties
+ *      - @ref pg_svc_guest_control
+ *  - Guest Additions.
+ *      - VBoxGuest.
+ *          - @ref pg_guest_lib
+ *      - @ref pg_vgsvc
+ *          - @ref pg_vgsvc_timesync
+ *          - @ref pg_vgsvc_vminfo
+ *          - @ref pg_vgsvc_vmstats
+ *          - @ref pg_vgsvc_gstctrl
+ *          - @ref pg_vgsvc_pagesharing
+ *          - @ref pg_vgsvc_memballoon
+ *          - @ref pg_vgsvc_cpuhotplug
+ *          - @ref pg_vgsvc_automount
+ *          - @ref pg_vgsvc_clipboard
+ *      - VBoxControl.
+ *      - Linux, Solaris and FreeBSD specific guest services and drivers.
+ *          - @ref pg_vboxdrmcliet (Linux only).
+ *          - VBoxClient.
+ *          - VBoxVideo.
+ *      - Windows Guests.
+ *          - VBoxTray.
+ *      - crOpenGL.
+ *      - pam.
+ *      - ...
+ *  - Network Services:
+ *      - @ref pg_net_dhcp
+ *      - NAT
+ *  - @ref pg_main
+ *      - @ref pg_main_events
+ *      - @ref pg_vrdb_usb
+ *  - Frontends:
+ *      - VirtualBox - The default Qt-based GUI.
+ *      - VBoxHeadless - The headless frontend.
+ *      - VBoxManage - The CLI.
+ *      - VBoxShell - An interactive shell written in python.
+ *      - VBoxSDL - A very simple GUI.
+ *      - VBoxBFE - A bare metal edition which does not use COM/XPCOM (barely
+ *        maintained atm).
+ *  - IPRT - Runtime Library for hiding host OS differences.
+ *  - Validation Kit:
+ *      - @ref pg_validationkit_guideline
+ *      - @ref pg_bs3kit
+ *  - @ref pg_vbox_guideline
+ *
+ * @todo Make links to the components.
+ *
+ *
+ *
+ * @section Execution Contexts
+ *
+ * VirtualBox defines a number of different execution context, this can be
+ * confusing at first.  So, to start with take a look at this diagram:
+ *
+ * @image html VMMContexts.png
+ *
+ * Context definitions:
+ *      - Host context (HC) - This is the context where the host OS runs and
+ *        runs VirtualBox within it.  The absense of IN_RC and IN_GUEST
+ *        indicates that we're in HC.  IN_RING0 indicates ring-0 (kernel) and
+ *        IN_RING3 indicates ring-3.
+ *      - Raw-mode Context (RC) - This is the special VMM context where we
+ *        execute the guest code directly on the CPU.  Kernel code is patched
+ *        and execute in ring-1 instead of ring-0 (ring compression).  Ring-3
+ *        code execute unmodified.  Only VMMs use ring-1, so we don't need to
+ *        worry about that (it's guarded against in the scheduler (EM)).  We can
+ *        in theory run ring-2 there, but since practially only only OS/2 uses
+ *        ring-2, it is of little importance.  The macro IN_RC indicates that
+ *        we're compiling something for RC.
+ *        Note! This used to be called GC (see below) earlier, so a bunch of RC
+ *        things are using GC markers.
+ *      - Guest Context (GC) - This is where the guest code is executed.  When
+ *        compiling, IN_GUEST indicates that it's for GC.  IN_RING0 and
+ *        IN_RING3 are also set when applicable, these are accompanied by
+ *        IN_GUEST_R0 and IN_GUEST_R3 respecitively.
+ *      - Intermediate context - This is a special memory context used within
+ *        the world switchers (HC -> RC and back), it features some identity
+ *        mapped code pages so we can switch to real mode if necessary.
+ *
+ */
+