Enhanced Guest ACPI PM Feature
Copyright 2015 by Assured Information Security, Inc. Created by Ross Philipson <[email protected]>. This work is licensed under the Creative Commons Attribution 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by/4.0/.
DO NOT EDIT: This page has been migrated to Confluence: https://openxt.atlassian.net/wiki/display/OD/Enhanced+Guest+ACPI+PM+Feature
OpenXT provides enhanced guest ACPI power management support primarily for portable computers and tablets. This Wiki describes how this feature works and contains a section on testing.
There are a number of components that make the ACPI PM feature work. This includes additional guest virtual ACPI firmware, ACPI device model support in QEMU and platform monitoring/reporting in xcpmd (the power/platform management daemon). These will be covered in this order in a “top down” manner.
The feature provides a new power management ACPI SSDT table. An SSDT contains auxiliary ACPI code to be loaded by the kernel in the guest. This SSDT surfaces a number of new devices related to power management including:
- Two battery devices that represent two possible battery slots.
- An AC adapter device.
- Lid device.
- Sleep and Power button devices.
The battery devices indicate the status of the battery – present or missing. When present they report the ACPI standard battery information and the current battery status. The battery status will indicate whether the batteries are charging/discharching and remaining capacity. The AC adapter device reports whether the system (and guest) are on AC power. The lid device reports whether the lid is open or closed. These devices are present on portable computers.
The SSDT also supplies power and sleep buttons. These simulate what occurs when power and sleep buttons are pressed on a system. These are present in all portable and non-portable systems.
All of the above devices receive asynchronous notifications using the standard ACPI event mechanism. Events occur for:
- Battery information changes implying batteries added or removed.
- Battery charge status changes.
- AC power unplugged or plugged in.
- Lid opened or closed.
- Sleep or power button presses.
This is the code that provides the device model emulation for the guest firmware discussed above. The virtual firmware communicates with QEMU through a set of IO ports. QEMU fetches data from Xenstore to furnish the virtual firmware with the information the devices need to report to the guest OS. This exchange is done via those ports.
The model also registers Xenstore watches and raises the required interrupts in the guest to drive the ACPI event mechanism. E.g. when the AC adapter is unplugged, a node is written to Xenstore. The model responds to this in its watch handler and raises the appropriate events in the guest.
This daemon, called xcpmd, is responsible for gathering information from the platform and reporting it. One of the sets of information is about the batteries present on the system. Up to two batteries can be managed. The current information and status about the battery/batteries is written to Xenstore under the /pm node where the QEMU model above reads it.
This daemon is also responsible for monitoring changes to the system:
- Battery plugged in or removed.
- Batter status changing – charging/discharging.
- AC power plugged in or unplugged.
- Lid opened or closed.
- Sleep or power button pressed.
In each case, the daemon responds by writing the nodes to Xenstore, again under /pm, where the QEMU model has registered its watches.
Testing can be done with any guest HVM that support ACPI. No custom drivers or software are needed. The OpenXT tools do not need to be installed. Multiple guests can be tested simultaneously.
The actions a guest OS takes on certain conditions are OS policy specific. These actions have defaults but they can also be changed. When testing, it should be noted what the actions are to validate the tests below.
This ACPI PM feature does not apply to the UIVM. It uses a separate mechanism to obtain the battery information.
NOTE: the UIVM reporting is currently not working correctly or getting the battery information from the same source as this feature. The values displayed by the UIVM may not match the guests. See: https://openxt.atlassian.net/browse/OXT-295 and https://openxt.atlassian.net/browse/OXT-15
- When the AC power adapter is plugged in, the guest should indicate this state, as well as when it is unplugged.
- The guest should update its AC adapter state as the adapter is plugged and unplugged.
- If a system has 1 battery, the guest should show 1 present battery and possibly (e.g. Windows) one empty slot.
- If a system has 2 batteries the guest should show both batteries.
- If a system has more than 2 batteries a maximum of 2 will be displayed in the guest.
- If a system has battery slots but all batteries are removed, the guest will show no batteries (e.g. Linux) or empty slots (e.g. Windows).
- If either battery is hot-pluggable, removing or adding the battery will update the guest accordingly.
- Fully charged batteries should report as such in guests.
- When AC power is removed, one or both batteries should start discharging (the behavior is dependent on system firmware).
- When AC power is restored, one or both batteries should start recharging (the behavior is dependent on system firmware).
- The guest OS may try to average the remaining capacity when 2 batteries are present when reporting the % remaining.
- When the batteries reach diminished capacity level, the guest OS may take certain actions depending on its policy. This is OS specific.
- When the lid is closed, the guest OS should take certain actions based on its policy.
- When the lid is opened, the guest OS should take certain actions based on its policy.
- When the sleep button is pressed, the guest OS should take certain actions based on its policy.
- When the power button is pressed, the guest OS should take certain actions based on its policy.
Information about the real battery hardware can be obtained in a shell in dom0. It can be found in these locations:
/proc/acpi/battery/BATn
/sys/class/power_supply/BATn
The dmidecode utility that reads the SMBIOS will also show battery information.
For Linux guests, the same methods used in dom0 can but used to inspect battery information.
For Windows guests, more in depth information can be gotten about the batteries using this tool: