Doc: Update system power management doc

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

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
+Service VM 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
+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
+Service VM VHM. The Hypervisor needs to provide hypercall APIs to transit
-data from CPU state table to SOS VHM.
+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
+2) Before User VM launching, Device mode queries the Px/Cx data from Service
-   via ioctl interface.
+   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
+Each time, when lifecycle manager of User VM starts power state transition,
-finally write the ACPI register per ACPI spec requirement.
+it will finally write the ACPI register per ACPI spec requirement. With
-With help of ACRN I/O emulation framework, the UOS ACPI
+help of ACRN I/O emulation framework, the User VM ACPI register writing
-register writing will be dispatched to Device Model and Device Model
+will be dispatched to Device Model and Device Model will emulate the User VM
-will emulate the UOS power state (pause UOS VM for S3 and power off UOS
+power state (pause User VM for S3 and power off User VM for S5)
-VM for S5)
 
-The VM Manager monitors all UOS. If all active UOSes are in required power
+The VM Manager monitors all User VMs. If all active User VMs are in required
-state, VM Manager will notify OSPM of SOS to start SOS power state
+power state, VM Manager will notify lifecyle manager of Service VM to start
-transition. OSPM of SOS follows a very similar process as UOS for power
+Service VM power state transition. lifecycle manager of Service VM follows
-state transition. The difference is SOS ACPI register writing is trapped
+a very similar process as User VM for power state transition. The difference
-to ACRN HV. And ACRN HV will emulate SOS power state (pause SOS VM for
+is Service VM ACPI register writing is trapped to ACRN HV. And ACRN HV will
-S3 and no special action for S5)
+emulate Service VM power state (pause Service VM for S3 and no special
+action for S5)
 
-Once SOS low power state is done, ACRN HV will go through its own low
+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.
 
+:numref:`pmworkflow` shows the flow of low power S5 enter process
+with typical ISD configuration(S3 follows very similar process)
+
+.. figure:: images/hld-pm-image63.png
+   :align: center
+   :name: pmworkflow
+
+   ACRN system S5 enter workflow
+
+For system power state entry:
+
+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 SOS to let SOS go
+state exit path. Then ACRN hypervisor will resume the Service VM to let
-through SOS low power state exit path. After that, the DM is resumed and
+Service VM go through Service VM low power state exit path. After that,
-let UOS go through UOS low power state exit path. The system is resumed
+the DM is resumed and let User VM go through User VM low power state exit
-to running state after at least one UOS is resumed to running state.
+path. The system is resumed to running state after at least one User VM
+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
-   :align: center
-   :name: pmworkflow
-
-   ACRN system power management 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
 
 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
+- User VM enters S5 -> User VM powers off
-- System enters S3 -> System powers off
+- System enters S5 -> System powers off
-- System resumes From S3 -> System fresh start
+- System resumes From S5 -> System fresh start
-- UOS resumes from S3 -> UOS fresh startup
+- User VM resumes from S5 -> User VM fresh startup