1.. _hld-power-management:
2
3Power Management High-Level Design
4##################################
5
6P-State/C-State Management
7**************************
8
9ACPI Px/Cx Data
10===============
11
12CPU P-state/C-state are controlled by the guest OS. The ACPI
13P/C-state driver relies on some P/C-state-related ACPI data in the guest
14ACPI table.
15
16The Service VM can run the ACPI driver with no problems because it can access the native ACPI table. For the User VM though, we need to prepare the corresponding ACPI data
17for the Device Model to build a virtual ACPI table.
18
19The Px/Cx data includes four
20ACPI objects: _PCT, _PPC, and _PSS for P-state management, and _CST for
21C-state management. All these ACPI data must be consistent with the
22native data because the control method is a kind of passthrough.
23
24These ACPI objects data are parsed by an offline tool and hard-coded in a
25Hypervisor module named CPU state table:
26
27.. code-block:: c
28
29   struct cpu_pstate_data {
30       uint64_t core_frequency;        /* megahertz */
31       uint64_t power;                 /* milliWatts */
32       uint64_t transition_latency;    /* microseconds */
33       uint64_t bus_master_latency;    /* microseconds */
34       uint64_t control;               /* control value */
35       uint64_t status;                /* success indicator */
36   } __attribute__((aligned(8)));
37
38   struct acrn_acpi_generic_address {
39       uint8_t     space_id;
40       uint8_t     bit_width;
41       uint8_t     bit_offset;
42       uint8_t     access_size;
43       uint64_t    address;
44   } __attribute__((aligned(8)));
45
46   struct cpu_cstate_data {
47       struct acrn_acpi_generic_address cx_reg;
48       uint8_t     type;
49       uint32_t    latency;
50       uint64_t    power;
51   } __attribute__((aligned(8)));
52
53
54With these Px/Cx data, the Hypervisor is able to intercept the guest's
55P/C-state requests with desired restrictions.
56
57Virtual ACPI Table Build Flow
58=============================
59
60:numref:`vACPItable` shows how to build the virtual ACPI table with the
61Px/Cx data for User VM P/C-state management:
62
63.. figure:: images/hld-pm-image28.png
64   :align: center
65   :name: vACPItable
66
67   System Block for Building vACPI Table with Px/Cx Data
68
69Some ioctl APIs are defined for the Device Model to query Px/Cx data from
70the Service VM HSM. The Hypervisor needs to provide hypercall APIs to transit
71Px/Cx data from the CPU state table to the Service VM HSM.
72
73The build flow is:
74
751) Use an offline tool (e.g. **iasl**) to parse the Px/Cx data and hard-code to
76   a CPU state table in the Hypervisor. The Hypervisor loads the data after
77   the system boots.
782) Before User VM launching, the Device Model queries the Px/Cx data from the Service
79   VM HSM via ioctl interface.
803) HSM transmits the query request to the Hypervisor by hypercall.
814) The Hypervisor returns the Px/Cx data.
825) The Device Model builds the virtual ACPI table with these Px/Cx data
83
84Intercept Policy
85================
86
87The Hypervisor should be able to restrict guest's
88P/C-state request with a user-customized policy.
89
90Hypervisor should intercept guest P-state request and validate whether
91it is a valid P-state. Any invalid P-state (e.g. doesn't exist in CPU state
92table) should be rejected.
93
94It is better not to intercept C-state request because the trap would
95impact both power and performance.
96
97.. note:: For P-state control, you should pay attention to SoC core
98   voltage domain design when doing P-state measurement. The highest
99   P-state would win if different P-state requests on the cores shared
100   same voltage domain. In this case, APERF/MPERF must be used to see
101   what P-state was granted on that core.
102
103S3/S5
104*****
105ACRN is designed to support the system level S3/S5 with following
106assumptions:
107
1081) Guest has complete S3/S5 power state management.
1092) Guest follows the ACPI standard to implement S3/S5.
1103) Guest is responsible for saving its contents before entering S3/S5.
1114) Highest severity guest's power state is promoted to system power state.
1125) Guest has lifecycle manager running to handle power state transaction
113   requirement and initialize guest power state transaction.
1146) S3 is only available on configurations that have no DM launched RTVM.
1157) S3 is only supported at platform level - not VM level.
116
117ACRN has a common implementation for notification between lifecycle manager
118in different guest. Which is vUART based cross-VM notification. But user
119could customize it according to their hardware/software requirements.
120
121:numref:`systempmdiag` shows the basic system level S3/S5 diagram.
122
123.. figure:: images/hld-pm-image62.png
124   :align: center
125   :name: systempmdiag
126
127   ACRN System S3/S5 Diagram
128
129
130System Low Power State Entry Process
131====================================
132
133Each time, when lifecycle manager of User VM starts power state transition,
134it will finally write the ACPI register per ACPI spec requirement. With
135help of ACRN I/O emulation framework, the User VM ACPI register writing
136will be dispatched to Device Model and Device Model will emulate the User VM
137power state (pause User VM for S3 and power off User VM for S5)
138
139The VM Manager monitors all User VMs. If all active User VMs are in required
140power state, VM Manager will notify lifecycle manager of Service VM to start
141Service VM power state transition. lifecycle manager of Service VM follows
142a very similar process as User VM for power state transition. The difference
143is Service VM ACPI register writing is trapped to ACRN HV. And ACRN HV will
144emulate Service VM power state (pause Service VM for S3 and no special
145action for S5)
146
147Once Service VM low power state is done, ACRN HV will go through its own low
148power state enter path.
149
150The whole system is finally put into low power state.
151
152:numref:`pmworkflow` shows the flow of low power S5 enter process
153with typical ISD configuration(S3 follows very similar process)
154
155.. figure:: images/hld-pm-image63.png
156   :align: center
157   :name: pmworkflow
158
159   ACRN System S5 Entry Workflow
160
161For system power state entry:
162
1631. Service VM received S5 request.
1642. Lifecycle manager in Service VM notifies User VM1 and RTVM through
165   vUART for S5 request.
1663. Guest lifecycle manager initializes S5 action and guest enters S5.
1674. RTOS cleanup RT task, send response of S5 request back to Service
168   VM and RTVM enters S5.
1695. After get response from RTVM and all User VM are shutdown, Service VM
170   enter S5.
1716. OSPM in ACRN hypervisor checks all guests are in S5 state and shuts down
172   whole system.
173
174System Low Power State Exit Process
175===================================
176
177The low power state exit process is in reverse order. The ACRN
178hypervisor is awakened first. It will go through its own low power
179state exit path. Then, ACRN hypervisor will resume the Service VM to let
180Service VM go through Service VM low power state exit path. After that,
181the DM is resumed and let User VM go through User VM low power state exit
182path. The system is resumed to running state after at least one User VM
183is resumed to running state.
184
185
186According to ACPI standard, S3 is mapped to suspend to RAM and S5 is
187mapped to shutdown. So the S5 process is a little different:
188
189- User VM enters S5 -> User VM powers off
190- System enters S5 -> System powers off
191- System resumes From S5 -> System fresh start
192- User VM resumes from S5 -> User VM fresh startup
193