Doc: Update system power management doc

Signed-off-by: Yin Fengwei <fengwei.yin@intel.com>

Author: fyin1

doc/developer-guides/hld/hld-power-management.rst

@@ -13,8 +13,8 @@ CPU P-state/C-state are controlled by the guest OS. The ACPI
 P/C-state driver relies on some P/C-state-related ACPI data in the guest
 ACPI table.
 
-SOS could run ACPI driver with no problem because it can access native
-the ACPI table. For UOS though, we need to prepare the corresponding ACPI data
+Service VM could run ACPI driver with no problem because it can access native
+the ACPI table. For User VM though, we need to prepare the corresponding ACPI data
 for Device Model to build virtual ACPI table.
 
 The Px/Cx data includes four
@@ -59,7 +59,7 @@ Virtual ACPI table build flow
 =============================
 
 :numref:`vACPItable` shows how to build virtual ACPI table with
-Px/Cx data for UOS P/C-state management:
+Px/Cx data for User VM P/C-state management:
 
 .. figure:: images/hld-pm-image28.png
    :align: center
@@ -68,16 +68,16 @@ Px/Cx data for UOS P/C-state management:
    System block for building vACPI table with Px/Cx data
 
 Some ioctl APIs are defined for Device model to query Px/Cx data from
-SOS VHM. The Hypervisor needs to provide hypercall APIs to transit Px/Cx
-data from CPU state table to SOS VHM.
+Service VM VHM. The Hypervisor needs to provide hypercall APIs to transit
+Px/Cx data from CPU state table to Service VM VHM.
 
 The build flow is:
 
 1) Use offline tool (e.g. **iasl**) to parse the Px/Cx data and hard-code to
    CPU state table in Hypervisor. Hypervisor loads the data after
    system boot up.
-2) Before UOS launching, Device mode queries the Px/Cx data from SOS VHM
-   via ioctl interface.
+2) Before User VM launching, Device mode queries the Px/Cx data from Service
+   VM VHM via ioctl interface.
 3) VHM transmits the query request to Hypervisor by hypercall.
 4) Hypervisor returns the Px/Cx data.
 5) Device model builds the virtual ACPI table with these Px/Cx data
@@ -103,77 +103,91 @@ impact both power and performance.
 
 S3/S5
 *****
+ACRN is designed to support the system level S3/S5 with following
+assumptions:
+
+1) Guest has complete S3/S5 power state management.
+2) Guest follows the ACPI standard to implement S3/S5.
+3) Guest is responsible for saving its contents before entering S3/S5.
+4) Highest severity guest's power state is promoted to system power state.
+5) Guest has lifecycle manager running to handle power state transaction
+   requirement and initialize guest power state transaction.
+6) S3 is only available on configurations which has no DM launched RTVM.
+7) S3 is only supported at platform level - not VM level.
+
+ACRN has a common implementation for notification between lifecycle manager
+in different guest. Which is vUART based cross-vm notification. But user
+could customize it according to their hardware/software requirements.
+
+:numref:`systempmdiag` shows the basic system level S3/S5 diagram
+
+.. figure:: images/hld-pm-image62.png
+   :align: center
+   :name: systempmdiag
+
+   ACRN System S3/S5 diagram
 
-ACRN assumes guest has complete S3/S5 power state management and follows
-the ACPI standard exactly. System S3/S5 needs to follow well-defined
-enter/exit paths and cooperate among different components.
 
 System low power state enter process
 ====================================
 
-Each time, when OSPM of UOS starts power state transition, it will
-finally write the ACPI register per ACPI spec requirement.
-With help of ACRN I/O emulation framework, the UOS ACPI
-register writing will be dispatched to Device Model and Device Model
-will emulate the UOS power state (pause UOS VM for S3 and power off UOS
-VM for S5)
-
-The VM Manager monitors all UOS. If all active UOSes are in required power
-state, VM Manager will notify OSPM of SOS to start SOS power state
-transition. OSPM of SOS follows a very similar process as UOS for power
-state transition. The difference is SOS ACPI register writing is trapped
-to ACRN HV. And ACRN HV will emulate SOS power state (pause SOS VM for
-S3 and no special action for S5)
-
-Once SOS low power state is done, ACRN HV will go through its own low
+Each time, when lifecycle manager of User VM starts power state transition,
+it will finally write the ACPI register per ACPI spec requirement. With
+help of ACRN I/O emulation framework, the User VM ACPI register writing
+will be dispatched to Device Model and Device Model will emulate the User VM
+power state (pause User VM for S3 and power off User VM for S5)
+
+The VM Manager monitors all User VMs. If all active User VMs are in required
+power state, VM Manager will notify lifecyle manager of Service VM to start
+Service VM power state transition. lifecycle manager of Service VM follows
+a very similar process as User VM for power state transition. The difference
+is Service VM ACPI register writing is trapped to ACRN HV. And ACRN HV will
+emulate Service VM power state (pause Service VM for S3 and no special
+action for S5)
+
+Once Service VM low power state is done, ACRN HV will go through its own low
 power state enter path.
 
 The whole system is finally put into low power state.
 
-System low power state exit process
-===================================
+:numref:`pmworkflow` shows the flow of low power S5 enter process
+with typical ISD configuration(S3 follows very similar process)
 
-The low power state exit process is in reverse order. The ACRN
-hypervisor is woken up at first. It will go through its own low power
-state exit path. Then ACRN hypervisor will resume the SOS to let SOS go
-through SOS low power state exit path. After that, the DM is resumed and
-let UOS go through UOS low power state exit path. The system is resumed
-to running state after at least one UOS is resumed to running state.
-
-:numref:`pmworkflow` shows the flow of low power S3 enter/exit process (S5 follows
-very similar process)
-
-.. figure:: images/hld-pm-image62.png
+.. figure:: images/hld-pm-image63.png
    :align: center
    :name: pmworkflow
 
-   ACRN system power management workflow
+   ACRN system S5 enter workflow
 
 For system power state entry:
 
-1. UOS OSPM start UOS S3 entry
-2. The UOS S3 entering request is trapped ACPI PM Device of DM
-3. DM pauses UOS VM to emulate UOS S3 and notifies VM Manager that the UOS
-   dedicated to it is in S3
-4. If all UOSes are in S3, VM Manager will notify OSPM of SOS
-5. SOS OSPM starts SOS S3 enter
-6. SOS S3 entering request is trapped to Sx Agency in ACRN HV
-7. ACRN HV pauses SOS VM to emulate SOS S3 and starts ACRN HV S3 entry.
-
-For system power state exit:
-
-1. When system is resumed from S3, native bootloader will jump to wake
-   up vector of HV
-2. HV resumes S3 and jumps to wake up vector to emulate SOS resume from S3
-3. OSPM of SOS is running
-4. OSPM of SOS notifies VM Manager that it's ready to wake up UOS
-5. VM Manager will notify DM to resume the UOS
-6. DM resets the UOS VM to emulate UOS resume from S3
+1. Service VM received S5 request.
+2. Lifecycle manager in Service VM notify User VM1 and RTVM through
+   vUART for S5 request.
+3. Guest lifecycle manager initliaze S5 action. And guest enter S5.
+4. RTOS cleanup rt task, send response of S5 request back to Service
+   VM and RTVM enter S5.
+5. After get response from RTVM and all User VM are shutdown, Sevice VM
+   enter S5.
+6. OSPM in ACRN hypervisor check all guest in S5 state and shutdown
+   whole system.
+
+System low power state exit process
+===================================
+
+The low power state exit process is in reverse order. The ACRN
+hypervisor is woken up at first. It will go through its own low power
+state exit path. Then ACRN hypervisor will resume the Service VM to let
+Service VM go through Service VM low power state exit path. After that,
+the DM is resumed and let User VM go through User VM low power state exit
+path. The system is resumed to running state after at least one User VM
+is resumed to running state.
+
 
 According to ACPI standard, S3 is mapped to suspend to RAM and S5 is
 mapped to shutdown. So the S5 process is a little different:
 
-- UOS enters S3 -> UOS powers off
-- System enters S3 -> System powers off
-- System resumes From S3 -> System fresh start
-- UOS resumes from S3 -> UOS fresh startup
+- User VM enters S5 -> User VM powers off
+- System enters S5 -> System powers off
+- System resumes From S5 -> System fresh start
+- User VM resumes from S5 -> User VM fresh startup