| 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 |
|
|---|
