VirtualBox

source: vbox/trunk/src/VBox/Main/Docs-Intro.cpp

Last change on this file was 98103, checked in by vboxsync, 18 months ago

Copyright year updates by scm.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 4.9 KB
Line 
1/* $Id: Docs-Intro.cpp 98103 2023-01-17 14:15:46Z vboxsync $ */
2/** @file
3 * This file contains the introduction to Main for developers.
4 */
5
6/*
7 * Copyright (C) 2011-2023 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/** @page pg_main Main API
29 *
30 * First of all, check out the "Technical background" chapter in the manual, pay
31 * attention to the "VirtualBox executables and components" chapter. It lists
32 * three processes, (1) VBoxSVC, (2) VirtualBox in manager mode and (3)
33 * VirtualBox in VM mode. This will be referred to as (1) server, (2) client
34 * and (3) VM process, respectively.
35 *
36 *
37 * @section sec_main_walk_thru_suspend IConsole::Pause Walkthru
38 *
39 * The instigator can be a client (VirtualBox in manager mode, VBoxManage
40 * controlvm, web services, ++) or the VM process it self (i.e. you select
41 * pause via the menu or the host key short cut).
42 *
43 * We will not cover the case where the guest triggers a suspend.
44 *
45 * Approximate sequence of events:
46 * - Client calls IConsole::Pause.
47 * - The COM/XPCOM routes this to the VM process, invoking Console::Pause() in
48 * ConsoleImpl.cpp. (The IConsole::Pause method in the client process is a
49 * COM/XPCOM stub method which does marshalling+IPC.)
50 * - Console::Pause validates the Console object state, the VM state and the VM
51 * handle.
52 * - Console::Pause calls VMR3Suspend to do the actual suspending.
53 * - VMR3Suspend() in VMM/VMMR3/VM.cpp calls VMMR3EmtRendezvous() to change the
54 * VM state synchronously on all EMTs (threads performing as virtual CPUs).
55 * - VMMR3EmtRendezvous() will first detect that the caller isn't an EMT and
56 * use VMR3ReqCallWait() to forward the call to an EMT.
57 * - When VMMR3EmtRendezvous() is called again on an EMT, it will signal the
58 * other EMTs by raising a force action flag (VM_FF_EMT_RENDEZVOUS) and then
59 * poke them via VMR3NotifyGlobalFFU(). Then wait for them all to arrive.
60 * - The other EMTs will call VMMR3EmtRendezvousFF as soon as they can.
61 * - When all EMTs are there, the calling back of vmR3Suspend() on each CPU in
62 * decending order will start.
63 * - When the CPU with the higest ID calls vmR3Suspend() the VM state is
64 * changed to VMSTATE_SUSPENDING or VMSTATE_SUSPENDING_EXT_LS.
65 * - When the CPU with ID 0 calls vmR3Suspend() the virtual device emulations
66 * and drivers get notified via PDMR3Suspend().
67 * - PDMR3Suspend() in VMM/VMMR3/PDM.cpp will iterate thru all device
68 * emulations and notify them that the VM is suspending by calling their
69 * PDMDEVREG::pfnSuspend / PDMUSBREG::pfnSuspend entry point (can be NULL).
70 * For each device it will iterate the chains of drivers and call their
71 * PDMDRVREG::pfnSuspend entry point as well.
72 * - Should a worker thread in a PDM device or PDM driver be busy and need some
73 * extra time to finish up / notice the pending suspend, the device or driver
74 * will ask for more time via PDMDevHlpSetAsyncNotification(),
75 * PDMDrvHlpSetAsyncNotification() or PDMUsbHlpSetAsyncNotification().
76 * PDMR3Suspend will then poll these devices and drivers frequently until all
77 * are done.
78 * - PDMR3Suspend() will return to vmR3Suspend() once all PDM devices and PDM
79 * drivers has responded to the pfnSuspend callback.
80 * - The virtual CPU with ID 0 returns from vmR3Suspend() to the rendezvous
81 * code and the EMTs are released.
82 * - The inner VMMR3EmtRendezvous() call returns and this in turn triggers the
83 * VMR3ReqCallWait() call to return (with the status code of the inner call).
84 * - The outer VMMR3EmtRendezvous() returns to VMR3Suspend().
85 * - VMR3Suspend() returns to Console::Pause().
86 * - Console::Pause() checks the result and flags provides error details on
87 * failure.
88 * - Console::Pause() returns to the COM/XPCOM marshalling/IPC stuff.
89 * - Switch back to client process.
90 * - The IConsole::Pause() call returns. The end.
91 *
92 * Summary of above: Client process calls into the VM process, VM process does a
93 * bunch of inter thread calls with all the EMT, EMT0 suspends the PDM devices
94 * and drivers.
95 *
96 * The EMTs will return to the outer execution loop, vmR3EmulationThreadWithId()
97 * in VMM/VMMR3/VMEmt.cpp, where they will mostly do sleep. They will not
98 * execute any guest code until VMR3Resume() is called.
99 *
100 */
101
Note: See TracBrowser for help on using the repository browser.

© 2023 Oracle
ContactPrivacy policyTerms of Use