[6303] | 1 | /* $Id: VBox-doc.c 80010 2019-07-26 15:05:06Z vboxsync $ */
|
---|
| 2 | /** @file
|
---|
| 3 | * VirtualBox Top Level Documentation File.
|
---|
| 4 | */
|
---|
| 5 |
|
---|
| 6 | /*
|
---|
[76553] | 7 | * Copyright (C) 2006-2019 Oracle Corporation
|
---|
[6303] | 8 | *
|
---|
| 9 | * This file is part of VirtualBox Open Source Edition (OSE), as
|
---|
| 10 | * available from http://www.virtualbox.org. This file is free software;
|
---|
| 11 | * you can redistribute it and/or modify it under the terms of the GNU
|
---|
| 12 | * General Public License (GPL) as published by the Free Software
|
---|
| 13 | * Foundation, in version 2 as it comes in the "COPYING" file of the
|
---|
| 14 | * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
|
---|
| 15 | * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
|
---|
| 16 | */
|
---|
| 17 |
|
---|
| 18 |
|
---|
| 19 | /** @mainpage VirtualBox
|
---|
| 20 | *
|
---|
| 21 | * (add introduction here)
|
---|
| 22 | *
|
---|
| 23 | * @section pg_main_comp Components
|
---|
| 24 | *
|
---|
[13001] | 25 | * - VM / @ref pg_vmm "VMM" / GVM / @ref pg_gvmm "GVMM" - Virtual Machine
|
---|
| 26 | * Monitor.
|
---|
| 27 | * - @ref pg_cfgm
|
---|
| 28 | * - @ref pg_cpum
|
---|
| 29 | * - @ref pg_dbgf
|
---|
[39685] | 30 | * - @ref pg_dbgf_addr_space
|
---|
| 31 | * - @ref pg_dbgf_vmcore
|
---|
| 32 | * - @ref pg_dbgf_module
|
---|
| 33 | * - @ref pg_dbgc
|
---|
[6303] | 34 | * - VBoxDbg - Debugger GUI (Qt).
|
---|
[58396] | 35 | * - @ref grp_dis
|
---|
[13001] | 36 | * - @ref pg_em
|
---|
[58094] | 37 | * - @ref pg_gim
|
---|
[58396] | 38 | * - @ref pg_hm
|
---|
| 39 | * - @ref pg_rem
|
---|
[39685] | 40 | * - @ref pg_vboxrem_amd64
|
---|
| 41 | * - @ref pg_iem
|
---|
[13001] | 42 | * - @ref pg_gmm
|
---|
| 43 | * - @ref pg_mm
|
---|
| 44 | * - @ref pg_pgm
|
---|
[39685] | 45 | * - @ref pg_pgm_phys
|
---|
| 46 | * - @ref pg_pgm_pool
|
---|
[13001] | 47 | * - @ref pg_selm
|
---|
| 48 | * - @ref pg_iom
|
---|
| 49 | * - @ref pg_pdm
|
---|
[6303] | 50 | * - Devices / USB Devices, Drivers and their public interfaces.
|
---|
| 51 | * - Async I/O Completion API.
|
---|
| 52 | * - Async Task API.
|
---|
| 53 | * - Critical Section API.
|
---|
| 54 | * - Queue API.
|
---|
| 55 | * - Thread API.
|
---|
[39685] | 56 | * - @ref pg_pdm_block_cache
|
---|
[13001] | 57 | * - @ref pg_ssm
|
---|
| 58 | * - @ref pg_stam
|
---|
| 59 | * - @ref pg_tm
|
---|
| 60 | * - @ref pg_trpm
|
---|
[39685] | 61 | * - VMM docs:
|
---|
| 62 | * - @ref pg_vmm_guideline
|
---|
| 63 | * - @ref pg_raw
|
---|
[6303] | 64 | * - Pluggable Components (via PDM).
|
---|
| 65 | * - DevPCArch - PC Architecture Device (chipset, legacy ++).
|
---|
| 66 | * - DevPCBios - Basic Input Output System.
|
---|
| 67 | * - DevDMAC - DMA Controller.
|
---|
| 68 | * - DevPIC - Programmable Interrupt Controller.
|
---|
| 69 | * - DevPIT - Programmable Interval Timer (i8254).
|
---|
| 70 | * - DevRTC - Real Time Clock.
|
---|
| 71 | * - DevVGA - Video Graphic Array.
|
---|
| 72 | * - DevPCI - Peripheral Component Interface (Bus).
|
---|
| 73 | * - VBoxDev - Special PCI Device which serves as an interface between
|
---|
| 74 | * the VMM and the guest OS for the additions.
|
---|
| 75 | * - Networking:
|
---|
| 76 | * - DevPCNet - AMD PCNet Device Emulation.
|
---|
| 77 | * - DevE1000 - Intel E1000 Device Emulation.
|
---|
| 78 | * - DevEEPROM - Intel E1000 EPROM Device Emulation.
|
---|
| 79 | * - SrvINetNetR0 - Internal Networking Ring-0 Service.
|
---|
| 80 | * - DevINIP - IP Stack Service for the internal networking.
|
---|
| 81 | * - DrvIntNet - Internal Networking Driver.
|
---|
| 82 | * - DrvNetSniffer - Wireshark Compatible Sniffer Driver (pass thru).
|
---|
| 83 | * - DrvNAT - Network Address Translation Driver.
|
---|
| 84 | * - DrvTAP - Host Interface Networking Driver.
|
---|
| 85 | * - Storage:
|
---|
| 86 | * - DevATA - ATA ((E)IDE) Device Emulation.
|
---|
[39685] | 87 | * - @ref pg_dev_ahci
|
---|
[6303] | 88 | * - DevFDC - Floppy Controller Device Emulation.
|
---|
| 89 | * - DrvBlock - Intermediate block driver.
|
---|
| 90 | * - DrvHostBase - Common code for the host drivers.
|
---|
| 91 | * - DrvHostDVD - Host DVD drive driver.
|
---|
| 92 | * - DrvHostFloppy - Host floppy drive driver.
|
---|
| 93 | * - DrvHostRawDisk - Host raw disk drive driver.
|
---|
| 94 | * - DrvMediaISO - ISO media driver.
|
---|
| 95 | * - DrvRawImage - Raw image driver (floppy images etc).
|
---|
| 96 | * - DrvVD - Intermediate Virtual Drive (Media) driver.
|
---|
| 97 | * - DrvVDI - VirtualBox Drive Image Container Driver.
|
---|
| 98 | * - DrvVmdk - VMDK Drive Image Container Driver.
|
---|
[39685] | 99 | * - USB:
|
---|
| 100 | * - @ref pg_dev_ohci
|
---|
| 101 | * - @ref pg_dev_ehci
|
---|
| 102 | * - @ref pg_dev_vusb
|
---|
| 103 | * - @ref pg_dev_vusb_old
|
---|
[6303] | 104 | * - Host Drivers.
|
---|
| 105 | * - SUPDRV - The Support driver (aka VBoxDrv).
|
---|
[39685] | 106 | * - @ref pg_sup
|
---|
| 107 | * - @ref pg_netflt
|
---|
| 108 | * - @ref pg_netadp
|
---|
[6303] | 109 | * - VBoxUSB - The USB support driver.
|
---|
[13001] | 110 | * - @ref pg_netflt
|
---|
[39685] | 111 | * - @ref pg_rawpci
|
---|
[6303] | 112 | * - Host Services.
|
---|
[39685] | 113 | * - @ref pg_hostclip Shared Clipboard.
|
---|
| 114 | * - Shared Folders.
|
---|
| 115 | * - Shared OpenGL. See PDF. (TODO: translate PDF to doxygen)
|
---|
| 116 | * - @ref pg_opengl_cocoa
|
---|
| 117 | * - @ref pg_svc_guest_properties
|
---|
| 118 | * - @ref pg_svc_guest_control
|
---|
| 119 | * - Guest Additions.
|
---|
| 120 | * - VBoxGuest.
|
---|
| 121 | * - @ref pg_guest_lib
|
---|
[58166] | 122 | * - @ref pg_vgsvc
|
---|
| 123 | * - @ref pg_vgsvc_timesync
|
---|
| 124 | * - @ref pg_vgsvc_vminfo
|
---|
| 125 | * - @ref pg_vgsvc_vmstats
|
---|
| 126 | * - @ref pg_vgsvc_gstctrl
|
---|
| 127 | * - @ref pg_vgsvc_pagesharing
|
---|
| 128 | * - @ref pg_vgsvc_memballoon
|
---|
| 129 | * - @ref pg_vgsvc_cpuhotplug
|
---|
| 130 | * - @ref pg_vgsvc_automount
|
---|
| 131 | * - @ref pg_vgsvc_clipboard
|
---|
[39685] | 132 | * - VBoxControl.
|
---|
| 133 | * - VBoxVideo.
|
---|
| 134 | * - crOpenGL.
|
---|
| 135 | * - VBoxClient / VBoxTray.
|
---|
| 136 | * - pam.
|
---|
| 137 | * - ...
|
---|
| 138 | * - Network Services:
|
---|
| 139 | * - @ref pg_net_dhcp
|
---|
[58166] | 140 | * - NAT
|
---|
[39685] | 141 | * - @ref pg_main
|
---|
| 142 | * - @ref pg_main_events
|
---|
| 143 | * - @ref pg_vrdb_usb
|
---|
[41857] | 144 | * - Frontends:
|
---|
[65128] | 145 | * - VirtualBox - The default Qt-based GUI.
|
---|
[41857] | 146 | * - VBoxHeadless - The headless frontend.
|
---|
| 147 | * - VBoxManage - The CLI.
|
---|
| 148 | * - VBoxShell - An interactive shell written in python.
|
---|
| 149 | * - VBoxSDL - A very simple GUI.
|
---|
| 150 | * - VBoxBFE - A bare metal edition which does not use COM/XPCOM (barely
|
---|
| 151 | * maintained atm).
|
---|
[39685] | 152 | * - IPRT - Runtime Library for hiding host OS differences.
|
---|
[51346] | 153 | * - Validation Kit:
|
---|
[51368] | 154 | * - @ref pg_validationkit_guideline
|
---|
[60600] | 155 | * - @ref pg_bs3kit
|
---|
[68446] | 156 | * - @ref pg_vbox_guideline
|
---|
[6303] | 157 | *
|
---|
| 158 | * @todo Make links to the components.
|
---|
[41857] | 159 | *
|
---|
| 160 | *
|
---|
| 161 | *
|
---|
| 162 | * @section Execution Contexts
|
---|
| 163 | *
|
---|
| 164 | * VirtualBox defines a number of different execution context, this can be
|
---|
| 165 | * confusing at first. So, to start with take a look at this diagram:
|
---|
| 166 | *
|
---|
| 167 | * @image html VMMContexts.png
|
---|
| 168 | *
|
---|
| 169 | * Context definitions:
|
---|
| 170 | * - Host context (HC) - This is the context where the host OS runs and
|
---|
| 171 | * runs VirtualBox within it. The absense of IN_RC and IN_GUEST
|
---|
| 172 | * indicates that we're in HC. IN_RING0 indicates ring-0 (kernel) and
|
---|
| 173 | * IN_RING3 indicates ring-3.
|
---|
| 174 | * - Raw-mode Context (RC) - This is the special VMM context where we
|
---|
| 175 | * execute the guest code directly on the CPU. Kernel code is patched
|
---|
| 176 | * and execute in ring-1 instead of ring-0 (ring compression). Ring-3
|
---|
| 177 | * code execute unmodified. Only VMMs use ring-1, so we don't need to
|
---|
| 178 | * worry about that (it's guarded against in the scheduler (EM)). We can
|
---|
| 179 | * in theory run ring-2 there, but since practially only only OS/2 uses
|
---|
| 180 | * ring-2, it is of little importance. The macro IN_RC indicates that
|
---|
| 181 | * we're compiling something for RC.
|
---|
| 182 | * Note! This used to be called GC (see below) earlier, so a bunch of RC
|
---|
| 183 | * things are using GC markers.
|
---|
| 184 | * - Guest Context (GC) - This is where the guest code is executed. When
|
---|
| 185 | * compiling, IN_GUEST indicates that it's for GC. IN_RING0 and
|
---|
| 186 | * IN_RING3 are also set when applicable, these are accompanied by
|
---|
| 187 | * IN_GUEST_R0 and IN_GUEST_R3 respecitively.
|
---|
| 188 | * - Intermediate context - This is a special memory context used within
|
---|
| 189 | * the world switchers (HC -> RC and back), it features some identity
|
---|
| 190 | * mapped code pages so we can switch to real mode if necessary.
|
---|
| 191 | *
|
---|
[6303] | 192 | */
|
---|
[12653] | 193 |
|
---|