1.. _enable-s5:
2
3Enable S5
4#########
5
6About System S5 Support
7***********************
8
9S5 refers to the ACPI “soft off” system state. ACRN system S5 support enables
10you to gracefully shut down or reset the whole system when multiple VMs are
11running. This is done by requesting and waiting for all pre-launched and
12post-launched VMs to gracefully shut themselves down before the Service VM
13triggers a system-wide shutdown or reset.
14
15We recommend using ACRN system S5 support to shut down or reset a system unless
16you have other mechanisms in place to protect external storage from being
17corrupted by a mechanical off.
18
19Dependencies and Constraints
20****************************
21
22Consider the following dependencies and constraints:
23
24* ACRN system S5 support is hardware neutral but requires the deployment of a
25  daemon (named Lifecycle Manager) in all VMs. The Lifecycle Manager manages
26  power state transitions.
27
28* The COM2 port is reserved for the Lifecycle Manager to communicate requests
29  and responses. Console vUARTs and inter-VM UART connections should avoid using
30  COM2 as an interface.
31
32* The S5 feature needs a communication vUART to control a User VM. However, you
33  don't need to configure a vUART connection for S5 via the ACRN Configurator,
34  because ACRN code already has a vUART connection between the Service VM and
35  User VMs by default.
36
37Example Configuration
38*********************
39
40The following steps show how to enable S5 by extending the information provided
41in the :ref:`gsg`. The scenario has a Service VM and one Ubuntu post-launched
42User VM.
43
44#. On the development computer, build the Lifecycle Manager daemon::
45
46      cd acrn-hypervisor
47      make life_mngr
48
49   The build generates files in the ``build/misc/services/life_mngr`` directory.
50
51#. Copy ``life_mngr.conf``, ``s5_trigger_linux.py``, ``life_mngr``, and
52   ``life_mngr.service`` into the Service VM and User VM.
53
54   These commands assume you have a network connection between the development
55   computer and target system. You can also use a USB stick to transfer files.
56
57   .. code-block:: bash
58
59      scp build/misc/services/s5_trigger_linux.py acrn@<target board address>:~/
60      scp build/misc/services/life_mngr acrn@<target board address>:~/
61      scp build/misc/services/life_mngr.service acrn@<target board address>:~/
62      scp build/misc/services/life_mngr.conf acrn@<target board address>:~/
63
64   Log in to the target system and run the following commands::
65
66      sudo mkdir /etc/life_mngr
67      sudo mv ~/life_mngr.conf /etc/life_mngr/
68      sudo mv ~/life_mngr.service /lib/systemd/system/
69      sudo mv ~/life_mngr /usr/bin/
70
71#. Copy ``user_vm_shutdown.py`` from the development computer into the Service
72   VM::
73
74      scp misc/services/life_mngr/user_vm_shutdown.py acrn@<target board address>:~/
75
76#. ACRN code sets the COM2 (``/dev/ttyS1``) as the default communication port of
77   the User VM, so we need only check the S5 vUART of the Service VM. Use the
78   following steps to get the Service VM S5 connection information.
79
80   Log in to the Service VM and run the command ``cat /etc/serial.conf`` to get
81   the connection information between the Service VM and User VM. Output
82   example:
83
84   .. code-block:: console
85
86      # User_VM_id: 1
87      /dev/ttyS8 port 0X9008 irq 0 uart 16550A baud_base 115200
88
89   This example means the Service VM uses the ``/dev/ttyS8`` connection to the
90   User VM's ``/dev/ttyS1``.
91
92#. Configure the S5 feature:
93
94   a. In the Service VM, edit the following options in
95      ``/etc/life_mngr/life_mngr.conf``. Make sure ``VM_NAME`` is the Service VM
96      name specified in the ACRN Configurator. Replace ``/dev/ttyS8`` with your
97      Service VM's S5 vUART, if it was different from the example in the
98      previous step.
99
100      .. code-block:: bash
101
102         VM_TYPE=service_vm
103         VM_NAME= ACRN_Service_VM
104         DEV_NAME=tty:/dev/ttyS8
105         ALLOW_TRIGGER_S5=/dev/ttySn
106
107   #. In the User VM, edit the following options in
108      ``/etc/life_mngr/life_mngr.conf``. Replace ``<User VM name>`` with the
109      VM name specified in the ACRN Configurator.
110
111      .. code-block:: bash
112
113         VM_TYPE=user_vm
114         VM_NAME=<User VM name>
115         DEV_NAME=tty:/dev/ttyS1
116         ALLOW_TRIGGER_S5=/dev/ttySn
117
118#. Enable ``life_mngr.service`` and restart the Service VM and User VM::
119
120      sudo chmod +x /usr/bin/life_mngr
121      sudo systemctl enable life_mngr.service
122      sudo reboot
123
124#. To trigger a system S5, run ``s5_trigger_linux.py`` in the Service VM.
125   The Service VM shuts down (transitioning to the S5 state) and sends a
126   poweroff request to shut down the User VM.
127
128.. note::
129
130   The S5 state is not automatically triggered by a Service VM shutdown; you
131   need to run ``s5_trigger_linux.py`` in the Service VM.