github/acrn-hypervisor
1
0
Fork 0
mirror of https://github.com/projectacrn/acrn-hypervisor.git synced 2025-06-20 12:42:54 +00:00
Code Issues Projects Releases Wiki Activity

Doc: Grammatical edits to the Enable S5 Guide.

Browse Source 
Signed-off-by: Deb Taylor <deb.taylor@intel.com>
This commit is contained in:
Deb Taylor 2019-11-11 10:27:13 -05:00 committed by wenlingz
parent b16e598763
commit 94394ae98d
1 changed files with 42 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

81
doc/tutorials/enable_s5.rst
View File

@ -6,8 +6,7 @@ Platform S5 Enable Guide
Introduction Introduction
************ ************
S5 is one of the `ACPI Sleep State <http://acpi.sourceforge.net/documentation/sleep.html>`_. S5 is one of the `ACPI sleep states <http://acpi.sourceforge.net/documentation/sleep.html>`_ that refers to the system being shut down (although some power may still be supplied to
It refers to the system being shut down (although some power may still be supplied to
certain devices). In this document, S5 means the function to shut down the certain devices). In this document, S5 means the function to shut down the
**User VMs**, **the Service VM**, the hypervisor, and the hardware. In most cases, **User VMs**, **the Service VM**, the hypervisor, and the hardware. In most cases,
directly shutting down the power of a computer system is not advisable because it can directly shutting down the power of a computer system is not advisable because it can
@ -21,7 +20,7 @@ S5 Architecture
*************** ***************
ACRN provides a mechanism to trigger the S5 state transition throughout the system. ACRN provides a mechanism to trigger the S5 state transition throughout the system.
It uses vUART channel to communicate between the Service VM and the User VMs. It uses a vUART channel to communicate between the Service and User VMs.
The diagram below shows the overall architecture: The diagram below shows the overall architecture:
.. figure:: images/s5_overall_architecture.png .. figure:: images/s5_overall_architecture.png
@ -31,47 +30,46 @@ The diagram below shows the overall architecture:
- **Scenario I**: - **Scenario I**:
The User VM's serial port device (``ttySn``) is emulated in Device Model, the channel from Service VM to User VM: The User VM's serial port device (``ttySn``) is emulated in the Device Model, the channel from the Service VM to the User VM:
.. graphviz:: images/s5-scenario-1.dot .. graphviz:: images/s5-scenario-1.dot
:name: s5-scenario-1 :name: s5-scenario-1
- **Scenario II**: - **Scenario II**:
The User VM's (like RT-Linux or other RT-VMs) serial port device (``ttySn``) is emulated in Hypervisor, The User VM's (like RT-Linux or other RT-VMs) serial port device (``ttySn``) is emulated in the Hypervisor,
the channel from Service OS to User VM: the channel from the Service OS to the User VM:
.. graphviz:: images/s5-scenario-2.dot .. graphviz:: images/s5-scenario-2.dot
:name: s5-scenario-2 :name: s5-scenario-2
How to trigger User VM's S5? Trigger the User VM's S5
============================ ========================
On Service VM side, it uses the ``acrnctl`` tool to trigger the User VM's S5 flow: On the Service VM side, it uses the ``acrnctl`` tool to trigger the User VM's S5 flow:
``acrnctl stop user-vm-name``. Then Device Model will send a ``shutdown`` command ``acrnctl stop user-vm-name``. Then, the Device Model sends a ``shutdown`` command
to User VM through channel, if User VM receives the command, it will send an "ACK" to the User VM through a channel. If the User VM receives the command, it will send an "ACK"
to Device Model. It is the responsibility of Service VM to check if the User VMs to the Device Model. It is the Service VM's responsibility to check if the User VMs
shutdown successfully or not, and decides when to power off itself. shutdown successfully or not, and decides when to power off itself.
What does "life cycle manager" in User VM do? User VM "life-cycle manager"
============================================= ============================
As current S5 reference design, there is a life-cycle manager daemon (life_mngr) running in As part of the current S5 reference design, a life-cycle manager daemon (life_mngr) runs in the
User VM to implement S5. It will wait for the command from Service VM on the User VM to implement S5. It waits for the command from the Service VM on the
paired serial port, there is a simple protocol between Service VM and User VM: paired serial port. The simple protocol between the Service VM and User VM is as follows:
when it receives ``shutdown``, then send "acked" to Service VM, then it can power off When the daemon receives ``shutdown``, it sends "acked" to the Service VM;
User VM. then it can power off the User VM. If the User VM is not ready to power off,
it can ignore the ``shutdown`` command.
However, if the User VM is not ready to power off, it can ignore the ``shutdown`` command.
.. _enable_s5: .. _enable_s5:
Enable S5 Enable S5
********* *********
Enable S5 based on the the particular OS: The procedure for enabling S5 is specific to the particular OS:
* For Linux (LaaG) or Windows (WaaG), refer to the following configurations in * For Linux (LaaG) or Windows (WaaG), refer to the following configurations in the
``devicemodel/samples/nuc/launch_uos.sh`` launch script for ``acrn-dm``. ``devicemodel/samples/nuc/launch_uos.sh`` launch script for ``acrn-dm``.
.. literalinclude:: ../../../../devicemodel/samples/nuc/launch_uos.sh .. literalinclude:: ../../../../devicemodel/samples/nuc/launch_uos.sh
@ -92,9 +90,9 @@ Enable S5 based on the the particular OS:
:emphasize-lines: 2-3,13 :emphasize-lines: 2-3,13
:language: bash :language: bash
.. note:: For RT-Linux, the vUART is emulated in hypervisor, expose the node as ``/dev/ttySn``. .. note:: For RT-Linux, the vUART is emulated in the hypervisor; expose the node as ``/dev/ttySn``.
#. For LaaG and RT-Linux VM, a reference daemon is offered to run: #. For LaaG and RT-Linux VMs, run the life-cycle manager deamon:
a. Use these commands to build the life-cycle manager daemon, ``life_mngr``. a. Use these commands to build the life-cycle manager daemon, ``life_mngr``.
@ -103,14 +101,14 @@ Enable S5 based on the the particular OS:
$ cd acrn-hypervisor/misc/life_mngr $ cd acrn-hypervisor/misc/life_mngr
$ make life_mngr $ make life_mngr
#. Copy ``life_mngr`` and ``life_mngr.service`` into User VM: #. Copy ``life_mngr`` and ``life_mngr.service`` into the User VM:
.. code-block:: none .. code-block:: none
$ scp life_mngr root@<test board address>:/usr/bin/life_mngr $ scp life_mngr root@<test board address>:/usr/bin/life_mngr
$ scp life_mngr.service root@<test board address>:/lib/systemd/system/life_mngr.service $ scp life_mngr.service root@<test board address>:/lib/systemd/system/life_mngr.service
#. Use below commands to enable ``life_mngr.service`` and restart User VM. #. Use the below commands to enable ``life_mngr.service`` and restart the User VM.
.. code-block:: none .. code-block:: none
@ -118,14 +116,14 @@ Enable S5 based on the the particular OS:
# systemctl enable life_mngr.service # systemctl enable life_mngr.service
# reboot # reboot
#. For WaaG VM, a reference daemon is offered to run: #. For the WaaG VM, run the life-cycle manager deamon:
a) Build ``life_mngr_win.exe`` application:: a) Build the ``life_mngr_win.exe`` application::
$ cd acrn-hypervisor/misc $ cd acrn-hypervisor/misc
$ make life_mngr $ make life_mngr
.. note:: If there is no ``x86_64-w64-mingw32-gcc`` compiler, you need run ``swupd bundle-add c-basic-mingw`` .. note:: If there is no ``x86_64-w64-mingw32-gcc`` compiler, you must run ``swupd bundle-add c-basic-mingw``
to install it. to install it.
#) Set up a Windows environment: #) Set up a Windows environment:
@ -139,20 +137,20 @@ Enable S5 based on the the particular OS:
.. figure:: images/Microsoft-Visual-C-install-option-2.png .. figure:: images/Microsoft-Visual-C-install-option-2.png
#) In WaaG, use the :kbd:`WIN + R` shortcut key, input "shell:startup", click :kbd:`OK` #) In WaaG, use the :kbd:`WIN + R` shortcut key, input "shell:startup", click :kbd:`OK`
and then copy ``life_mngr_win.exe`` application into this directory. and then copy the ``life_mngr_win.exe`` application into this directory.
.. figure:: images/run-shell-startup.png .. figure:: images/run-shell-startup.png
.. figure:: images/launch-startup.png .. figure:: images/launch-startup.png
#) Restart the WaaG VM. The COM2 window will automatically open after reboots. #) Restart the WaaG VM. The COM2 window will automatically open after reboot.
.. figure:: images/open-com-success.png .. figure:: images/open-com-success.png
#. If the Service VM is being shut down (transitioning to the S5 state), it can call #. If the Service VM is being shut down (transitioning to the S5 state), it can call
``acrnctl stop vm-name`` to shut down the User VMs. ``acrnctl stop vm-name`` to shut down the User VMs.
.. note:: S5 state is not automatically triggered by a Service VM shutdown, this needs .. note:: S5 state is not automatically triggered by a Service VM shutdown; this needs
to be run before powering off the Service VM. to be run before powering off the Service VM.
How to test How to test
@ -174,13 +172,12 @@ How to test
ps -ef|grep cbc; kill -9 cbc_pid ps -ef|grep cbc; kill -9 cbc_pid
#. Refer to the :ref:`enable_s5` section to set up S5 environment for the User VMs. #. Refer to the :ref:`enable_s5` section to set up the S5 environment for the User VMs.
.. note:: RT-Linux's UUID must use ``495ae2e5-2603-4d64-af76-d4bc5a8ec0e5``, also the .. note:: RT-Linux's UUID must use ``495ae2e5-2603-4d64-af76-d4bc5a8ec0e5``. Also, the
industry EFI image is required for launching RT-Linux VM. industry EFI image is required for launching the RT-Linux VM.
.. note:: Use ``systemctl status life_mngr.service`` command to ensure the service .. note:: Use the ``systemctl status life_mngr.service`` command to ensure the service is working on the LaaG or RT-Linux:
is working on LaaG or RT-Linux:
.. code-block:: console .. code-block:: console
@ -189,16 +186,16 @@ How to test
Active: active (running) since Tue 2019-09-10 07:15:06 UTC; 1min 11s ago Active: active (running) since Tue 2019-09-10 07:15:06 UTC; 1min 11s ago
Main PID: 840 (life_mngr) Main PID: 840 (life_mngr)
.. note:: For WaaG, we need to close ``windbg`` by using ``"bcdedit /set debug off`` command .. note:: For WaaG, we need to close ``windbg`` by using the ``"bcdedit /set debug off`` command
if you executed ``bcdedit /set debug on`` when set up the WaaG, because it occupies the ``COM2``. IF you executed the ``bcdedit /set debug on`` when you set up the WaaG, because it occupies the ``COM2``.
#. Use ``acrnctl stop`` command on Service VM to trigger S5 to the User VMs: #. Use the``acrnctl stop`` command on the Service VM to trigger S5 to the User VMs:
.. code-block:: console .. code-block:: console
# acrnctl stop vm1 # acrnctl stop vm1
#. Use ``acrnctl list`` command to check the User VM status. #. Use the ``acrnctl list`` command to check the User VM status.
.. code-block:: console .. code-block:: console