doc: Update "Enable S5 in ACRN" tutorial
Update the "Enable S5 in ACRN" tutorial to: * Make the language clearer at places * Consistent use of "Lifecycle Manager" and "life_mngr" * Change "ACK" to "ACKED" * Use a ReST reference to point at the architectural diagram * Update build instructions * Replace 'literalinclude' by static code-blocks to avoid the content going out of date Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com>
This commit is contained in:
Geoffroy Van Cutsem
David Kinder
parent
b81153145d
commit
e18d99ef65
|
|
@ -51,16 +51,16 @@ The diagram below shows the overall architecture:
|
|||
Initiate a system S5 from within a User VM (e.g. HMI)
|
||||
=====================================================
|
||||
|
||||
As in Figure 56, a request to Service VM initiates the shutdown flow.
|
||||
This could come from a User VM, most likely the HMI (Windows or user-friendly Linux).
|
||||
When a human operator click to initiate the flow, the lifecycle_mgr in it will send
|
||||
the request via vUART to the lifecycle manager in the Service VM which in turn acknowledge
|
||||
the request and trigger the following flow.
|
||||
As shown in the :numref:`s5-architecture`, a request to Service VM initiates the shutdown flow.
|
||||
This could come from a User VM, most likely the HMI (running Windows or Linux).
|
||||
When a human operator initiates the flow, the Lifecycle Manager (``life_mngr``) running in that
|
||||
User VM will send the request via the vUART to the Lifecycle Manager in the Service VM which in
|
||||
turn acknowledges the request and triggers the following flow.
|
||||
|
||||
.. note:: The User VM need to be authorized to be able to request a Shutdown, this is achieved by adding
|
||||
"``--pm_notify_channel uart,allow_trigger_s5``" in the launch script of that VM.
|
||||
``--pm_notify_channel uart,allow_trigger_s5`` in the launch script of that VM.
|
||||
And, there is only one VM in the system can be configured to request a shutdown. If there is a second User
|
||||
VM launched with "``--pm_notify_channel uart,allow_trigger_s5``", ACRN will stop launching it and throw
|
||||
VM launched with ``--pm_notify_channel uart,allow_trigger_s5``, ACRN will stop launching it and throw
|
||||
out below error message:
|
||||
``initiate a connection on a socket error``
|
||||
``create socket to connect life-cycle manager failed``
|
||||
|
|
@ -70,18 +70,18 @@ Trigger the User VM's S5
|
|||
|
||||
On the Service VM side, it uses the ``acrnctl`` tool to trigger the User VM's S5 flow:
|
||||
``acrnctl stop user-vm-name``. Then, the Device Model sends a ``shutdown`` command
|
||||
to the User VM through a channel. If the User VM receives the command, it will send an "ACK"
|
||||
to the Device Model. It is the Service VM's responsibility to check if the User VMs
|
||||
shut down successfully or not, and decides when to power off itself.
|
||||
to the User VM through a channel. If the User VM receives the command, it will send an ``ACKED``
|
||||
to the Device Model. It is the Service VM's responsibility to check whether the User VMs
|
||||
shut down successfully or not, and to decide when to shut the Service VM itself down.
|
||||
|
||||
User VM "Lifecycle Manager"
|
||||
===========================
|
||||
|
||||
As part of the current S5 reference design, a lifecycle manager daemon (life_mngr) runs in the
|
||||
User VM to implement S5. It waits for the command from the Service VM on the
|
||||
paired serial port. The simple protocol between the Service VM and User VM is as follows:
|
||||
When the daemon receives ``shutdown``, it sends "ACKed" to the Service VM;
|
||||
then it can power off the User VM. If the User VM is not ready to power off,
|
||||
As part of the S5 reference design, a Lifecycle Manager daemon (``life_mngr`` in Linux,
|
||||
``life_mngr_win.exe`` in Windows) runs in the User VM to implement S5. It waits for the shutdown
|
||||
request from the Service VM on the serial port. The simple protocol between the Service VM and
|
||||
User VM is as follows: when the daemon receives ``shutdown``, it sends ``ACKED`` to the Service VM;
|
||||
then it shuts down the User VM. If the User VM is not ready to shut down,
|
||||
it can ignore the ``shutdown`` command.
|
||||
|
||||
.. _enable_s5:
|
||||
|
|
@ -91,26 +91,35 @@ Enable S5
|
|||
|
||||
The procedure for enabling S5 is specific to the particular OS:
|
||||
|
||||
* For Linux (LaaG) or Windows (WaaG), refer to the following configurations in the
|
||||
``misc/config_tools/data/sample_launch_scripts/nuc/launch_uos.sh`` launch script for ``acrn-dm``.
|
||||
* For Linux (LaaG) or Windows (WaaG), include these lines in the launch script:
|
||||
|
||||
.. literalinclude:: ../../../../misc/config_tools/data/sample_launch_scripts/nuc/launch_uos.sh
|
||||
:name: laag-waag-script
|
||||
:caption: LaaG/WaaG launch script
|
||||
:linenos:
|
||||
:lines: 97-117
|
||||
:emphasize-lines: 2-4,17
|
||||
:language: bash
|
||||
.. code-block:: bash
|
||||
|
||||
* For RT-Linux, refer to the ``misc/config_tools/data/sample_launch_scripts/nuc/launch_hard_rt_vm.sh`` script:
|
||||
# Power Management (PM) configuration using vUART channel
|
||||
pm_channel="--pm_notify_channel uart"
|
||||
pm_by_vuart="--pm_by_vuart pty,/run/acrn/life_mngr_"$vm_name
|
||||
pm_vuart_node="-s 1:0,lpc -l com2,/run/acrn/life_mngr_"$vm_name
|
||||
|
||||
.. literalinclude:: ../../../../misc/config_tools/data/sample_launch_scripts/nuc/launch_hard_rt_vm.sh
|
||||
:name: rt-script
|
||||
:caption: RT-Linux launch script
|
||||
:linenos:
|
||||
:lines: 42-58
|
||||
:emphasize-lines: 2-3,13
|
||||
:language: bash
|
||||
acrn-dm -A -m $mem_size -s 0:0,hostbridge \
|
||||
...
|
||||
$pm_channel \
|
||||
$pm_by_vuart \
|
||||
$pm_vuart_node \
|
||||
...
|
||||
|
||||
* For RT-Linux, include these lines in the launch script:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Power Management (PM) configuration
|
||||
pm_channel="--pm_notify_channel uart"
|
||||
pm_by_vuart="--pm_by_vuart tty,/dev/ttyS1"
|
||||
|
||||
/usr/bin/acrn-dm -A -m $mem_size -s 0:0,hostbridge \
|
||||
...
|
||||
$pm_channel \
|
||||
$pm_by_vuart \
|
||||
...
|
||||
|
||||
.. note:: For RT-Linux, the vUART is emulated in the hypervisor; expose the node as ``/dev/ttySn``.
|
||||
|
||||
|
|
@ -120,15 +129,15 @@ The procedure for enabling S5 is specific to the particular OS:
|
|||
|
||||
.. code-block:: none
|
||||
|
||||
$ cd acrn-hypervisor/misc/life_mngr
|
||||
$ cd acrn-hypervisor
|
||||
$ make life_mngr
|
||||
|
||||
#. Copy ``life_mngr`` and ``life_mngr.service`` into the User VM:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ 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 build/misc/services/life_mngr root@<test board address>:/usr/bin/life_mngr
|
||||
$ scp build/misc/services/life_mngr.service root@<test board address>:/lib/systemd/system/life_mngr.service
|
||||
|
||||
#. Use the below commands to enable ``life_mngr.service`` and restart the User VM.
|
||||
|
||||
|
|
@ -142,7 +151,7 @@ The procedure for enabling S5 is specific to the particular OS:
|
|||
|
||||
a) Build the ``life_mngr_win.exe`` application::
|
||||
|
||||
$ cd acrn-hypervisor/misc
|
||||
$ cd acrn-hypervisor
|
||||
$ make life_mngr
|
||||
|
||||
.. note:: If there is no ``x86_64-w64-mingw32-gcc`` compiler, you can run ``sudo apt install gcc-mingw-w64-x86-64``
|
||||
|
|
|
|||
Loading…
Reference in New Issue