Table of Contents
A Power Management specification has been in used informally used for a few years on the GNOME desktop. There has never been any standardised nomenclature or API to allow desktops such as KDE and XFCE to interoperate. This has lead to technologies that have often been incompatible and resulted in poor integration of power management into desktop applications.
This specification aims to help this problem, by defining a standard API that can be implemented by desktop session daemons to integrate with existing infrastructure. This can be used by desktop applications to become more power aware.
org.freedesktop.PowerManagement is the only
compulsory interface to implement, although other optional interfaces
exist and others may be proposed in the future for other aspects of
session power management.
These use cases should direct the API towards real world application, rather than a generic theoretical interface.
A logout GUI dialog should only present the sleep options to the user that are likely to succeed.
A simulation that will take many hours should have an option on the dialog to hibernate when finished.
A partition editor should not attempt to apply changes when the battery is discharging and low.
A video player should use a less precise codec to save power when the system is in a low power state.
The interfaces are session-wide.
| DBUS Service: | org.freedesktop.PowerManagement |
| DBUS Interface: | org.freedesktop.PowerManagement |
| DBUS Path: | /org/freedesktop/PowerManagement |
Methods on interface org.freedesktop.PowerManagement
define a compulsory base layer for interoperability.
The Shutdown and Reboot methods are deprecated and will be removed as soon as there is an implemented session management DBUS API.
Table 1. Methods on interface org.freedesktop.PowerManagement
| Name | Input Parameters | Return Values | Throws Error | Description |
|---|---|---|---|---|
Suspend | PermissionDenied, NoHardwareSupport | Attempt to suspend the system. | ||
Hibernate | PermissionDenied, NoHardwareSupport | Attempt to hibernate the system. | ||
Shutdown | PermissionDenied, NoHardwareSupport | Attempt to shutdown the system. | ||
Reboot | PermissionDenied, NoHardwareSupport | Attempt to reboot the system. | ||
CanSuspend | bool can_suspend | If the current session user is able to suspend the system. | ||
CanHibernate | bool can_hibernate | If the current session user is able to hibernate the system. | ||
CanShutdown | bool can_shutdown | If the current session user is able to shutdown the system. | ||
CanReboot | bool can_reboot | If the current session user is able to reboot the system. | ||
GetPowerSaveStatus | bool save_power | This may be set on AC or battery power, both, or neither depending on the users preference setting. This setting may also change with the battery level changing. Programs should respect this value and not perform non-essential tasks when we are trying to save power. | ||
GetOnBattery | bool on_battery | Returns the system power state, i.e. if we are running on battery power. This method may still return true on AC using a desktop system if the computer is using backup power from a monitored UPS. | ||
GetLowBattery | bool low_battery | Returns true if the battery is low and discharging. This may be measured with time remaining or percentage change, and the exact threshold level is an implementation detail. Programs that cannot deal with a low power action such as suspend or hibernate should not run if this method returns true. |
Table 2. Signals emitted from interface org.freedesktop.PowerManagement
| Name | Return Values | Description |
|---|---|---|
CanSuspendChanged | bool can_suspend | Signals the suspend status has changed. |
CanHibernateChanged | bool can_hibernate | Signals the hibernate status has changed. |
CanShutdownChanged | bool can_shutdown | Signals the shutdown status has changed. |
CanRebootChanged | bool can_reboot | Signals the reboot status has changed. |
PowerSaveStatusChanged | bool save_power | Signals the low power mode has changed.. |
OnBatteryChanged | bool on_battery | Signals the battery discharge state has changed. |
LowBatteryChanged | bool on_battery | Signals the battery low power state has changed. |
| DBUS Interface: | org.freedesktop.PowerManagement.Inhibit |
| DBUS Path: | /org/freedesktop/PowerManagement/Inhibit |
When the power manager detects an idle session and system, it can perform a system suspend or hibernate, known as an idle sleep action. We can prevent the session power manager daemon from doing this action using the inhibit interface.
An automatic inhibit should be taken by the file manager if there is a slow network copy that will take many minutes to complete.
A cookie is a randomly assigned 32bit unsigned integer used to identify the inhibit. It is required as the same application may want to call inhibit multiple times, without managing the inhibit calls itself.
Inhibit and UnInhibit are easy to use, requiring only the cookie to be stored in the client application. Below is a simple python demonstration showing an inhibit action.
#!/usr/bin/python
import dbus
import time
bus = dbus.Bus(dbus.Bus.TYPE_SESSION)
devobj = bus.get_object('org.freedesktop.PowerManagement', '/org/freedesktop/PowerManagement')
dev = dbus.Interface (devobj, "org.freedesktop.PowerManagement.Inhibit")
cookie = dev.Inhibit('Nautilus', 'Copying files from /media/SANVOL')
time.sleep(10)
dev.UnInhibit(cookie)
Table 3. Methods on interface org.freedesktop.PowerManagement.Inhibit
| Name | Input Parameters | Return Values | Throws Error | Description |
|---|---|---|---|---|
Inhibit | string application, string reason | uint cookie | PermissionDenied | Inhibits the computer from performing an idle sleep action. Useful if you want to do an operation of long duration without the computer suspending. Reason and application should be translated strings where possible. |
UnInhibit | uint cookie | CookieNotFound |
Allows the computer to perform the idle sleep or user action if the
number of inhibit calls is zero.
If there are multiple cookies outstanding, clearing one cookie
does not allow the action to happen.
If the program holding the cookie exits from the session bus without
calling UnInhibit() then it is automatically removed.
| |
HasInhibit | bool has_inhibit | Returns false if we have no valid inhibits. This will return true if the number of inhibit cookies is greater than zero. |
Table 4. Signals emitted from interface org.freedesktop.PowerManagement.Inhibit
| Name | Return Values | Description |
|---|---|---|
HasInhibitChanged | bool has_inhibit | Signals the inhibit valid state has changed. |
This section describes the standard nomenclature that should be used by programmers when implementing the Power Management Specification.
Standby is the action where the CPU is held in a low power state, and the display turned off, but no data is saved to the hard disk. The exact behavior of standby can depend on your BIOS and hardware. It normally takes a split second to standby and resume. You cannot remove the battery when on laptop power or work will be lost.
| Forward action: | STANDBY |
| Reverse action: | CONTINUE |
Other valid names for standby are ACPI S1.
Suspend is the action where the computer freezes all activity, and copies working data to memory. It then turns off the screen, and goes into a low-power mode. It normally takes a few seconds to suspend and a few seconds to resume. You cannot remove the battery when on battery power or work will be lost.
| Forward action: | SUSPEND |
| Reverse action: | RESUME |
Other valid names for standby are ACPI S3 and
suspend-to-ram.
Hibernate is the action where the computer freezes all activity and swaps data to disk, turns off the screen and powers down. This takes over one minute to swap the complete memory to disk, and nearly one minute to thaw.
| Forward action: | HIBERNATE |
| Reverse action: | THAW |
Other valid names for standby are ACPI S4 and
suspend-to-disk.
Version 0.1, 26 March 2007, Richard Hughes.
Initial version for review.
Version 0.2, 02 April 2007, Richard Hughes.
Removed Standby due to common consensus and added the Use Cases section. Renamed GetBatteryState to GetOnBattery. Deprecated Shutdown and Reboot methods - they will be removed when we can call these on the session manager. Added Inhibit interface. Replace DeniedByPolicy with PermissionDenied.