summaryrefslogtreecommitdiffstats
path: root/src/VBox/Main/Docs-Intro.cpp
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-11 08:17:27 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-11 08:17:27 +0000
commitf215e02bf85f68d3a6106c2a1f4f7f063f819064 (patch)
tree6bb5b92c046312c4e95ac2620b10ddf482d3fa8b /src/VBox/Main/Docs-Intro.cpp
parentInitial commit. (diff)
downloadvirtualbox-f215e02bf85f68d3a6106c2a1f4f7f063f819064.tar.xz
virtualbox-f215e02bf85f68d3a6106c2a1f4f7f063f819064.zip
Adding upstream version 7.0.14-dfsg.upstream/7.0.14-dfsg
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'src/VBox/Main/Docs-Intro.cpp')
-rw-r--r--src/VBox/Main/Docs-Intro.cpp101
1 files changed, 101 insertions, 0 deletions
diff --git a/src/VBox/Main/Docs-Intro.cpp b/src/VBox/Main/Docs-Intro.cpp
new file mode 100644
index 00000000..43b08b80
--- /dev/null
+++ b/src/VBox/Main/Docs-Intro.cpp
@@ -0,0 +1,101 @@
+/* $Id: Docs-Intro.cpp $ */
+/** @file
+ * This file contains the introduction to Main for developers.
+ */
+
+/*
+ * Copyright (C) 2011-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
+ */
+
+/** @page pg_main Main API
+ *
+ * First of all, check out the "Technical background" chapter in the manual, pay
+ * attention to the "VirtualBox executables and components" chapter. It lists
+ * three processes, (1) VBoxSVC, (2) VirtualBox in manager mode and (3)
+ * VirtualBox in VM mode. This will be referred to as (1) server, (2) client
+ * and (3) VM process, respectively.
+ *
+ *
+ * @section sec_main_walk_thru_suspend IConsole::Pause Walkthru
+ *
+ * The instigator can be a client (VirtualBox in manager mode, VBoxManage
+ * controlvm, web services, ++) or the VM process it self (i.e. you select
+ * pause via the menu or the host key short cut).
+ *
+ * We will not cover the case where the guest triggers a suspend.
+ *
+ * Approximate sequence of events:
+ * - Client calls IConsole::Pause.
+ * - The COM/XPCOM routes this to the VM process, invoking Console::Pause() in
+ * ConsoleImpl.cpp. (The IConsole::Pause method in the client process is a
+ * COM/XPCOM stub method which does marshalling+IPC.)
+ * - Console::Pause validates the Console object state, the VM state and the VM
+ * handle.
+ * - Console::Pause calls VMR3Suspend to do the actual suspending.
+ * - VMR3Suspend() in VMM/VMMR3/VM.cpp calls VMMR3EmtRendezvous() to change the
+ * VM state synchronously on all EMTs (threads performing as virtual CPUs).
+ * - VMMR3EmtRendezvous() will first detect that the caller isn't an EMT and
+ * use VMR3ReqCallWait() to forward the call to an EMT.
+ * - When VMMR3EmtRendezvous() is called again on an EMT, it will signal the
+ * other EMTs by raising a force action flag (VM_FF_EMT_RENDEZVOUS) and then
+ * poke them via VMR3NotifyGlobalFFU(). Then wait for them all to arrive.
+ * - The other EMTs will call VMMR3EmtRendezvousFF as soon as they can.
+ * - When all EMTs are there, the calling back of vmR3Suspend() on each CPU in
+ * decending order will start.
+ * - When the CPU with the higest ID calls vmR3Suspend() the VM state is
+ * changed to VMSTATE_SUSPENDING or VMSTATE_SUSPENDING_EXT_LS.
+ * - When the CPU with ID 0 calls vmR3Suspend() the virtual device emulations
+ * and drivers get notified via PDMR3Suspend().
+ * - PDMR3Suspend() in VMM/VMMR3/PDM.cpp will iterate thru all device
+ * emulations and notify them that the VM is suspending by calling their
+ * PDMDEVREG::pfnSuspend / PDMUSBREG::pfnSuspend entry point (can be NULL).
+ * For each device it will iterate the chains of drivers and call their
+ * PDMDRVREG::pfnSuspend entry point as well.
+ * - Should a worker thread in a PDM device or PDM driver be busy and need some
+ * extra time to finish up / notice the pending suspend, the device or driver
+ * will ask for more time via PDMDevHlpSetAsyncNotification(),
+ * PDMDrvHlpSetAsyncNotification() or PDMUsbHlpSetAsyncNotification().
+ * PDMR3Suspend will then poll these devices and drivers frequently until all
+ * are done.
+ * - PDMR3Suspend() will return to vmR3Suspend() once all PDM devices and PDM
+ * drivers has responded to the pfnSuspend callback.
+ * - The virtual CPU with ID 0 returns from vmR3Suspend() to the rendezvous
+ * code and the EMTs are released.
+ * - The inner VMMR3EmtRendezvous() call returns and this in turn triggers the
+ * VMR3ReqCallWait() call to return (with the status code of the inner call).
+ * - The outer VMMR3EmtRendezvous() returns to VMR3Suspend().
+ * - VMR3Suspend() returns to Console::Pause().
+ * - Console::Pause() checks the result and flags provides error details on
+ * failure.
+ * - Console::Pause() returns to the COM/XPCOM marshalling/IPC stuff.
+ * - Switch back to client process.
+ * - The IConsole::Pause() call returns. The end.
+ *
+ * Summary of above: Client process calls into the VM process, VM process does a
+ * bunch of inter thread calls with all the EMT, EMT0 suspends the PDM devices
+ * and drivers.
+ *
+ * The EMTs will return to the outer execution loop, vmR3EmulationThreadWithId()
+ * in VMM/VMMR3/VMEmt.cpp, where they will mostly do sleep. They will not
+ * execute any guest code until VMR3Resume() is called.
+ *
+ */
+