1.. _hv-vm-management:
2
3VM Management
4#############
5
6The ACRN hypervisor maintained a dedicated VM structure instance for each
7running VM, and a series VM APIs like create_vm, start_vm, reset_vm, shutdown_vm
8etc are used to switch a VM to the right state, according to the requirements of
9applications or system power operations.
10
11VM Structure
12************
13
14The ``acrn_vm`` structure is defined to manage a VM instance, this structure
15maintained a VM's HW resources such as vCPU, vPIC, vIOAPIC, vUART, and vPCI.
16At
17the same time ``acrn_vm`` structure also records SW information
18related with corresponding VM, such as info for VM identifier, info for SW
19loader, info for memory e820 entries, info for IO/MMIO handlers, and info for
20platform level cpuid entries.
21
22The ``acrn_vm`` structure instance will be created by ``create_vm`` API, and then
23work as the first parameter for other VM APIs.
24
25VM State
26********
27
28Generally, a VM is not running at the beginning: it is in a 'powered off'
29state. After it is created successfully, the VM enters a 'created' state.
30Then the VM could be kicked to run, and enter a 'started' state. When the
31VM powers off, the VM returns to a 'powered off' state again.
32A VM can be paused to wait for some operation when it is running, so there is
33also a 'paused' state.
34
35:numref:`hvvm-state` illustrates the state-machine of a VM state transition.
36Refer to :ref:`hv-cpu-virt` for related vCPU state.
37
38.. figure:: images/hld-image108.png
39   :align: center
40   :name: hvvm-state
41
42   Hypervisor VM State Transition
43
44VM State Management
45*******************
46
47Pre-Launched and Service VM
48===========================
49
50The hypervisor is the owner to control pre-launched and Service VM's state
51by calling VM APIs directly, following the design of system power
52management. Refer to ACRN power management design for more details.
53
54
55Post-Launched User VMs
56======================
57
58DM takes control of post-launched User VMs' state transition after the Service VM
59boots, by calling VM APIs through hypercalls.
60
61Service VM user level service such as Life-Cycle-Service and tools such
62as ``acrnd`` may work together with DM to launch or stop a User VM.
63Refer to :ref:`acrnctl` documentation for more details.
64