| 1 | /* $Id: VBox-doc.c 106061 2024-09-16 14:03:52Z vboxsync $ */
|
|---|
| 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 |
|
|---|
