diff options
Diffstat (limited to 'doc/VBox-doc.c')
| -rw-r--r-- | doc/VBox-doc.c | 219 |
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..c8114b1f --- /dev/null +++ b/doc/VBox-doc.c @@ -0,0 +1,219 @@ +/* $Id: VBox-doc.c $ */ +/** @file + * VirtualBox Top Level Documentation File. + */ + +/* + * Copyright (C) 2006-2023 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. + * + */ + |