doc/VBox-doc.c

   1 /* $Id$ */
   2 /** @file
   3  * VirtualBox Top Level Documentation File.
   4  */
   5
   6 /*
   7  * Copyright (C) 2006-2024 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  * SPDX-License-Identifier: GPL-3.0-only
  26  */
  27
  28
  29 /** @mainpage   VirtualBox
  30  *
  31  * (add introduction here)
  32  *
  33  * @section pg_main_comp    Components
  34  *
  35  *  - VM / @ref pg_vmm "VMM" / GVM / @ref pg_gvmm "GVMM" - Virtual Machine
  36  *    Monitor.
  37  *      - @ref pg_cfgm
  38  *      - @ref pg_cpum
  39  *      - @ref pg_dbgf
  40  *          - @ref pg_dbgf_addr_space
  41  *          - @ref pg_dbgf_vmcore
  42  *          - @ref pg_dbgf_module
  43  *          - @ref pg_dbgc
  44  *          - VBoxDbg - Debugger GUI (Qt).
  45  *      - @ref grp_dis
  46  *      - @ref pg_em
  47  *      - @ref pg_gim
  48  *      - @ref pg_hm
  49  *      - @ref pg_iem
  50  *      - @ref pg_nem
  51  *      - @ref pg_gmm
  52  *          - @ref pg_mm
  53  *          - @ref pg_pgm
  54  *              - @ref pg_pgm_phys
  55  *              - @ref pg_pgm_pool
  56  *          - @ref pg_selm
  57  *      - @ref pg_iom
  58  *      - @ref pg_pdm
  59  *          - Devices / USB Devices, Drivers and their public interfaces.
  60  *          - Async I/O Completion API.
  61  *          - Async Task API.
  62  *          - Critical Section API.
  63  *          - Queue API.
  64  *          - Thread API.
  65  *          - @ref pg_pdm_block_cache
  66  *      - @ref pg_ssm
  67  *      - @ref pg_stam
  68  *      - @ref pg_tm
  69  *      - @ref pg_trpm
  70  *      - VMM docs:
  71  *          - @ref pg_vmm_guideline
  72  *          - @ref pg_raw
  73  *  - Pluggable Components (via PDM).
  74  *      - DevPCArch - PC Architecture Device (chipset, legacy ++).
  75  *      - DevPCBios - Basic Input Output System.
  76  *      - DevDMAC - DMA Controller.
  77  *      - DevPIC - Programmable Interrupt Controller.
  78  *      - DevPIT - Programmable Interval Timer (i8254).
  79  *      - DevRTC - Real Time Clock.
  80  *      - DevVGA - Video Graphic Array.
  81  *      - DevPCI - Peripheral Component Interface (Bus).
  82  *      - VBoxDev - Special PCI Device which serves as an interface between
  83  *                  the VMM and the guest OS for the additions.
  84  *      - @ref pg_pdm_audio "Audio":
  85  *          - DevHda - Intel High Definition Audio Device Emulation.
  86  *          - DevIchAc97 - ICH AC'97 Device Emulation.
  87  *          - DevSB16 - SoundBlaster 16 Device Emulation.
  88  *          - DrvAudio - Intermediate driver.
  89  *          - DrvHostAudioAlsa - ALSA Host Audio Driver (Linux).
  90  *          - DrvHostAudioCoreAudio - Core Audio Host Audio Driver (macOS).
  91  *          - DrvHostAudioDebug - Debug Backend Driver.
  92  *          - DrvHostAudioDSound - DirectSound Host Audio Driver (Windows).
  93  *          - DrvHostAudioNull - NULL Backend Driver.
  94  *          - DrvHostAudioOss - Open Sound System Host Audio Driver (Linux,
  95  *            Solaris, ++).
  96  *          - DrvHostAudioPulseAudio - PulseAudio Host Audio Driver (Linux).
  97  *          - DrvHostAudioValidationKit - Validation Kit Test Driver.
  98  *          - DrvHostAudioWasApi - Windows Audio Session API Host Audio Driver.
  99  *      - Networking:
 100  *          - DevPCNet - AMD PCNet Device Emulation.
 101  *          - DevE1000 - Intel E1000 Device Emulation.
 102  *          - DevEEPROM - Intel E1000 EPROM Device Emulation.
 103  *          - SrvINetNetR0 - Internal Networking Ring-0 Service.
 104  *          - DevINIP - IP Stack Service for the internal networking.
 105  *          - DrvIntNet - Internal Networking Driver.
 106  *          - DrvNetSniffer - Wireshark Compatible Sniffer Driver (pass thru).
 107  *          - DrvNAT - Network Address Translation Driver.
 108  *          - DrvTAP - Host Interface Networking Driver.
 109  *      - Storage:
 110  *          - DevATA - ATA ((E)IDE) Device Emulation.
 111  *          - @ref pg_dev_ahci
 112  *          - DevFDC - Floppy Controller Device Emulation.
 113  *          - DrvBlock - Intermediate block driver.
 114  *          - DrvHostBase - Common code for the host drivers.
 115  *          - DrvHostDVD - Host DVD drive driver.
 116  *          - DrvHostFloppy - Host floppy drive driver.
 117  *          - DrvHostRawDisk - Host raw disk drive driver.
 118  *          - DrvMediaISO - ISO media driver.
 119  *          - DrvRawImage - Raw image driver (floppy images etc).
 120  *          - DrvVD - Intermediate Virtual Drive (Media) driver.
 121  *          - DrvVDI - VirtualBox Drive Image Container Driver.
 122  *          - DrvVmdk - VMDK Drive Image Container Driver.
 123  *      - USB:
 124  *          - @ref pg_dev_ohci
 125  *          - @ref pg_dev_ehci
 126  *          - @ref pg_dev_vusb
 127  *          - @ref pg_dev_vusb_old
 128  *  - Host Drivers.
 129  *      - SUPDRV - The Support driver (aka VBoxDrv).
 130  *          - @ref pg_sup
 131  *      - @ref pg_netflt
 132  *      - @ref pg_netadp
 133  *      - VBoxUSB - The USB support driver.
 134  *      - @ref pg_netflt
 135  *      - @ref pg_rawpci
 136  *  - Host Services.
 137  *      - @ref pg_hostclip
 138  *      - Shared Folders.
 139  *      - @ref pg_svc_guest_properties
 140  *      - @ref pg_svc_guest_control
 141  *  - Guest Additions.
 142  *      - VBoxGuest.
 143  *          - @ref pg_guest_lib
 144  *      - @ref pg_vgsvc
 145  *          - @ref pg_vgsvc_timesync
 146  *          - @ref pg_vgsvc_vminfo
 147  *          - @ref pg_vgsvc_vmstats
 148  *          - @ref pg_vgsvc_gstctrl
 149  *          - @ref pg_vgsvc_pagesharing
 150  *          - @ref pg_vgsvc_memballoon
 151  *          - @ref pg_vgsvc_cpuhotplug
 152  *          - @ref pg_vgsvc_automount
 153  *          - @ref pg_vgsvc_clipboard
 154  *      - VBoxControl.
 155  *      - Linux, Solaris and FreeBSD specific guest services and drivers.
 156  *          - @ref pg_vboxdrmcliet (Linux only).
 157  *          - VBoxClient.
 158  *          - VBoxVideo.
 159  *      - Windows Guests.
 160  *          - VBoxTray.
 161  *      - crOpenGL.
 162  *      - pam.
 163  *      - ...
 164  *  - Network Services:
 165  *      - @ref pg_net_dhcp
 166  *      - NAT
 167  *  - @ref pg_main
 168  *      - @ref pg_main_events
 169  *      - @ref pg_vrdb_usb
 170  *  - Frontends:
 171  *      - VirtualBox - The default Qt-based GUI.
 172  *      - VBoxHeadless - The headless frontend.
 173  *      - VBoxManage - The CLI.
 174  *      - VBoxShell - An interactive shell written in python.
 175  *      - VBoxSDL - A very simple GUI.
 176  *      - VBoxBFE - A bare metal edition which does not use COM/XPCOM (barely
 177  *        maintained atm).
 178  *  - IPRT - Runtime Library for hiding host OS differences.
 179  *  - Validation Kit:
 180  *      - @ref pg_validationkit_guideline
 181  *      - @ref pg_bs3kit
 182  *  - @ref pg_vbox_guideline
 183  *
 184  * @todo Make links to the components.
 185  *
 186  *
 187  *
 188  * @section Execution Contexts
 189  *
 190  * VirtualBox defines a number of different execution context, this can be
 191  * confusing at first.  So, to start with take a look at this diagram:
 192  *
 193  * @image html VMMContexts.png
 194  *
 195  * Context definitions:
 196  *      - Host context (HC) - This is the context where the host OS runs and
 197  *        runs VirtualBox within it.  The absense of IN_RC and IN_GUEST
 198  *        indicates that we're in HC.  IN_RING0 indicates ring-0 (kernel) and
 199  *        IN_RING3 indicates ring-3.
 200  *      - Raw-mode Context (RC) - This is the special VMM context where we
 201  *        execute the guest code directly on the CPU.  Kernel code is patched
 202  *        and execute in ring-1 instead of ring-0 (ring compression).  Ring-3
 203  *        code execute unmodified.  Only VMMs use ring-1, so we don't need to
 204  *        worry about that (it's guarded against in the scheduler (EM)).  We can
 205  *        in theory run ring-2 there, but since practially only only OS/2 uses
 206  *        ring-2, it is of little importance.  The macro IN_RC indicates that
 207  *        we're compiling something for RC.
 208  *        Note! This used to be called GC (see below) earlier, so a bunch of RC
 209  *        things are using GC markers.
 210  *      - Guest Context (GC) - This is where the guest code is executed.  When
 211  *        compiling, IN_GUEST indicates that it's for GC.  IN_RING0 and
 212  *        IN_RING3 are also set when applicable, these are accompanied by
 213  *        IN_GUEST_R0 and IN_GUEST_R3 respecitively.
 214  *      - Intermediate context - This is a special memory context used within
 215  *        the world switchers (HC -> RC and back), it features some identity
 216  *        mapped code pages so we can switch to real mode if necessary.
 217  *
 218  */
 219