1.. _cpu_sharing:
2
3Enable CPU Sharing
4##################
5
6About CPU Sharing
7*****************
8
9CPU sharing allows the virtual CPUs (vCPUs) of different VMs to run on the same
10physical CPU, just like how multiple processes run concurrently on a single CPU.
11Internally the hypervisor adopts time slicing scheduling and periodically
12switches among those vCPUs.
13
14This feature can help improve overall CPU utilization when the VMs are not fully
15loaded. However, sharing a physical CPU among multiple vCPUs increases the
16worst-case response latency of them, and thus is not suitable for vCPUs running
17latency-sensitive workloads.
18
19Dependencies and Constraints
20****************************
21
22Consider the following dependencies and constraints:
23
24* CPU sharing is a hypervisor feature that is hardware and OS neutral.
25
26* CPU sharing is not available for real-time VMs or for VMs with local APIC
27  passthrough (via the LAPIC passthrough option in the ACRN Configurator or via
28  the Device Model ``--lapic_pt`` option).
29
30* You can choose the scheduler the hypervisor uses. A scheduler is an algorithm
31  for determining the priority of VMs running on a shared virtual CPU. ACRN
32  supports the following schedulers:
33
34  - Borrowed Virtual Time (BVT), which fairly allocates time slices to multiple
35    vCPUs pinned to the same physical CPU. The BVT scheduler is the default and
36    is sufficient for most use cases.
37
38  - No-Operation (NOOP), which runs at most one vCPU on each physical CPU.
39
40  - Priority based, which supports vCPU scheduling based on their static
41    priorities defined in the scenario configuration. A vCPU can be running only
42    if there is no higher-priority vCPU running on the same physical CPU.
43
44Configuration Overview
45**********************
46
47You use the :ref:`acrn_configurator_tool` to enable CPU sharing by assigning the
48same set of physical CPUs to multiple VMs and selecting a scheduler. The
49following documentation is a general overview of the configuration process.
50
51To assign the same set of physical CPUs to multiple VMs, set the following
52parameters in each VM's **Basic Parameters**:
53
54* VM type: Standard (Real-time VMs don't support CPU sharing)
55* Physical CPU affinity > pCPU ID: Select a physical CPU by its core ID.
56* To add another physical CPU, click **+** on the right side of an existing CPU.
57  Or click **-** to delete a CPU.
58* Repeat the process to assign the same physical CPUs to another VM.
59
60.. image:: images/configurator-cpusharing-affinity.png
61   :align: center
62   :class: drop-shadow
63
64To select a scheduler, go to **Hypervisor Global Settings > Advanced Parameters
65> Virtual CPU scheduler** and select a scheduler from the list.
66
67.. image:: images/configurator-cpusharing-scheduler.png
68   :align: center
69   :class: drop-shadow
70
71Example Configuration
72*********************
73
74The following steps show how to enable and verify CPU sharing between two User
75VMs. The example extends the information provided in the :ref:`gsg`.
76
77#. In the ACRN Configurator, create a shared scenario with a Service VM and two
78   post-launched User VMs.
79
80#. For the first User VM, set the following parameters in the VM's **Basic
81   Parameters**:
82
83   * VM name: This example uses ``POST_STD_VM1``.
84   * VM type: ``Standard``
85   * Physical CPU affinity: Select pCPU ID ``1``, then click **+** and select
86     pCPU ID ``2`` to assign the VM to CPU cores 1 and 2.
87
88   .. image:: images/configurator-cpusharing-vm1.png
89      :align: center
90      :class: drop-shadow
91
92   .. image:: images/configurator-cpusharing-affinity.png
93      :align: center
94      :class: drop-shadow
95
96#. For the second User VM, set the following parameters in the VM's **Basic
97   Parameters**:
98
99   * VM name: This example uses ``POST_STD_VM2``.
100   * VM type: ``Standard``
101   * Physical CPU affinity: Select pCPU ID ``1`` and ``2``. The pCPU IDs must be
102     the same as those of ``POST_STD_VM1`` to use the CPU sharing function.
103
104#. In **Hypervisor Global Settings > Advanced Parameters > Virtual CPU
105   scheduler**, confirm that the default scheduler, Borrowed Virtual Time, is
106   selected.
107
108#. Save the scenario and launch script.
109
110#. Build ACRN, copy all the necessary files from the development computer to
111   the target system, and launch the Service VM and post-launched User VMs.
112
113#. In the :ref:`ACRN hypervisor shell<acrnshell>`, check the CPU sharing via
114   the ``vcpu_list`` command. For example:
115
116   .. code-block:: none
117
118      ACRN:\>vcpu_list
119
120      VM ID    PCPU ID    VCPU ID    VCPU ROLE    VCPU STATE    THREAD STATE
121      =====    =======    =======    =========    ==========    ==========
122        0         0          0        PRIMARY      Running       RUNNABLE
123        0         1          1        SECONDARY    Running       BLOCKED
124        0         2          2        SECONDARY    Running       BLOCKED
125        0         3          3        SECONDARY    Running       BLOCKED
126        1         1          0        PRIMARY      Running       RUNNING
127        1         2          1        SECONDARY    Running       BLOCKED
128        2         1          0        PRIMARY      Running       BLOCKED
129        2         2          1        SECONDARY    Running       RUNNING
130
131   The VM ID, PCPU ID, VCPU ID, and THREAD STATE columns provide information to
132   help you check CPU sharing. In the VM ID column, VM 0 is the Service VM, VM 1
133   is POST_STD_VM1, and VM 2 is POST_STD_VM2. The output shows that ACRN
134   assigned all physical CPUs (pCPUs) to VM 0 as expected. It also confirms that
135   you assigned pCPUs 1 and 2 to VMs 1 and 2 (via the ACRN Configurator). vCPU 1
136   of VM 0 and vCPU 0 of VM 1 and VM 2 are running on the same physical CPU;
137   they are sharing the physical CPU execution time. The thread state column
138   shows the current states of the vCPUs. The BLOCKED state can occur for
139   different reasons, most likely the vCPU is waiting for an I/O operation to be
140   completed. Once it is done, the state will change to RUNNABLE. When this vCPU
141   gets its pCPU execution time, its state will change to RUNNING, then the vCPU
142   is actually running on the pCPU.
143
144Learn More
145**********
146
147For details on the ACRN CPU virtualization high-level design, For the
148:ref:`hv-cpu-virt`.