Enable S5 in ACRN¶
S5 is one of the ACPI sleep states that 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 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 damage some components. It can cause corruption and put the system in an unknown or unstable state. On ACRN, the User VM must be shut down before powering off the Service VM. Especially for some use cases, where User VMs could be used in industrial control or other high safety requirement environment, a graceful system shutdown such as the ACRN S5 function is required.
ACRN provides a mechanism to trigger the S5 state transition throughout the system. It uses a vUART channel to communicate between the Service and User VMs. The diagram below shows the overall architecture:
The User VM’s serial port device (
ttySn) is emulated in the Device Model, the channel from the Service VM to the User VM:
The User VM’s (like RT-Linux or other RT-VMs) serial port device (
ttySn) is emulated in the Hypervisor, the channel from the Service OS to the User VM:
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.
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.
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
out below error message:
initiate a connection on a socket error
create socket to connect life-cycle manager failed
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
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.
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,
it can ignore the
The procedure for enabling S5 is specific to the particular OS:
For Linux (LaaG) or Windows (WaaG), refer to the following configurations in the
devicemodel/samples/nuc/launch_uos.shlaunch script for
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
#for memsize setting mem_size=2048M acrn-dm -A -m $mem_size -s 0:0,hostbridge \ -s 2,pci-gvt -G "$2" \ -s 5,virtio-console,@stdio:stdio_port \ -s 6,virtio-hyper_dmabuf \ -s 3,virtio-blk,/home/clear/uos/uos.img \ -s 4,virtio-net,tap0 \ -s 7,virtio-rnd \ --ovmf /usr/share/acrn/bios/OVMF.fd \ $logger_setting \ --mac_seed $mac_seed \ $vm_name } #add following cmdline to grub.cfg and update kernel #when launching LaaG by OVMF #rw rootwait maxcpus=1 nohpet console=tty0 console=hvc0 #console=ttyS0 no_timer_check ignore_loglevel
For RT-Linux, refer to the
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
/usr/bin/acrn-dm -A -m $mem_size -s 0:0,hostbridge \ --lapic_pt \ --rtvm \ --virtio_poll 1000000 \ -U 495ae2e5-2603-4d64-af76-d4bc5a8ec0e5 \ -s 2,passthru,02/0/0 \ -s 3,virtio-console,@stdio:stdio_port \ --ovmf /usr/share/acrn/bios/OVMF.fd \ hard_rtvm } # -s 2,passthru,0/17/0 \ #please using "lspci -nn" check the bdf info # Depends on which partation RT_LaaG is installed in;maybe need to change # /dev/nvme0n1p3 to /dev/sda3 on NUC and uncomment SATA pass-through
For RT-Linux, the vUART is emulated in the hypervisor; expose the node as
For LaaG and RT-Linux VMs, run the lifecycle manager daemon:
Use these commands to build the lifecycle manager daemon,
$ cd acrn-hypervisor/misc/life_mngr $ make life_mngr
life_mngr.serviceinto the User VM:
$ 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
Use the below commands to enable
life_mngr.serviceand restart the User VM.
# chmod +x /usr/bin/life_mngr # systemctl enable life_mngr.service # reboot
For the WaaG VM, run the lifecycle manager daemon:
$ cd acrn-hypervisor/misc $ make life_mngr
If there is no
x86_64-w64-mingw32-gcccompiler, you can run
sudo apt install gcc-mingw-w64-x86-64on Ubuntu to install it.
Set up a Windows environment:
Download the Visual Studio 2019 tool from https://visualstudio.microsoft.com/downloads/, and choose the two options in the below screenshots to install “Microsoft Visual C++ Redistributable for Visual Studio 2015, 2017 and 2019 (x86 or X64)” in WaaG:
In WaaG, use the Windows + R shortcut key, input
shell:startup, click OK and then copy the
life_mngr_win.exeapplication into this directory.
Restart the WaaG VM. The COM2 window will automatically open after reboot.
If the Service VM is being shut down (transitioning to the S5 state), it can call
acrnctl stop vm-nameto shut down the User VMs.
S5 state is not automatically triggered by a Service VM shutdown; this needs to be run before powering off the Service VM.
How to Test¶
As described in Enable vUART Configurations, two vUARTs are defined in pre-defined ACRN scenarios: vUART0/ttyS0 for the console and vUART1/ttyS1 for S5-related communication (as shown in S5 overall architecture).
For Yocto Project (Poky) or Ubuntu rootfs, the
ttyS1conflicts with the S5-related communication use of
vUART1. We can eliminate the conflict by preventing that service from being started either automatically or manually, by masking the service using this commandsystemctl mask serial-getty@ttyS1.service
Refer to the Enable S5 section to set up the S5 environment for the User VMs.
RT-Linux’s UUID must use
495ae2e5-2603-4d64-af76-d4bc5a8ec0e5. Also, the industry EFI image is required for launching the RT-Linux VM.
systemctl status life_mngr.servicecommand to ensure the service is working on the LaaG or RT-Linux:
* life_mngr.service - ACRN lifemngr daemon Loaded: loaded (/usr/lib/systemd/system/life_mngr.service; enabled; vendor p> Active: active (running) since Tue 2019-09-10 07:15:06 UTC; 1min 11s ago Main PID: 840 (life_mngr)
For WaaG, we need to close
windbgby using the
bcdedit /set debug offcommand IF you executed the
bcdedit /set debug onwhen you set up the WaaG, because it occupies the
acrnctl stopcommand on the Service VM to trigger S5 to the User VMs:
# acrnctl stop vm1
acrnctl listcommand to check the User VM status.
# acrnctl list vm1 stopped
Using a coordinating script,
misc/life_mngr/s5_trigger.sh, in conjunction with
the lifecycle manager in each VM, graceful system shutdown can be performed.
s5_trigger.sh manually to root’s home directory.
$ sudo install -p -m 0755 -t ~root misc/life_mngr/s5_trigger.sh
hybrid_rt scenario, the script can send a shutdown command via
in the Service VM, which is connected to
ttyS1 in the pre-launched VM. The
lifecycle manager in the pre-launched VM receives the shutdown command, sends an
ack message, and proceeds to shut itself down accordingly.
The HMI Windows Guest uses the lifecycle manager to send a shutdown request to the Service VM
The lifecycle manager in the Service VM responds with an ack message and executes
After receiving the ack message, the lifecycle manager in the HMI Windows Guest shuts down the guest
s5_trigger.shscript in the Service VM shuts down the Linux Guest by using
acrnctlto send a shutdown request
After receiving the shutdown request, the lifecycle manager in the Linux Guest responds with an ack message and shuts down the guest
s5_trigger.shscript in the Service VM shuts down the Pre-launched RTVM by sending a shutdown request to its
After receiving the shutdown request, the lifecycle manager in the Pre-launched RTVM responds with an ack message
The lifecycle manager in the Pre-launched RTVM shuts down the guest using standard PM registers
After receiving the ack message, the
s5_trigger.shscript in the Service VM shuts down the Service VM
The hypervisor shuts down the system after all of its guests have shut down