1. Introduction 1.1. Project/Component Working Name: GNOME Power Manager 1.2. Name of Document Author/Supplier: Author: Simon Zheng 1.3 Date of This Document: Mar 4th, 2008 2. Background This project provides Solaris users with GNOME Power Manager utitilies. Solaris has integrated HAL in Tamarack project (PSARC/2005/399). Again Battery project (PSARC/2006/601), CPUFreq HAL (PSARC/2007/679) and GNOME Power Management Support (PSARC/2008/021) enhance much more power management properties. Based on them, this project is able to provide desktop users with many new power management features, such as suspending, hibernating, brightness adjustment, lid closure action, CPU frequency scaling, and etc. 3. Business Consideration GNOME Power Manager[1] supplies many modern power management features. It's valuable to attract more developer users for Solaris, especially laptop users. Also, it has been a part of official GNOME release since GNOME 2.14 and is delivered in many Linux distributions at present. So this project can fill the gap between Linux and Solaris too. 4. Technical Description This project will port GNOME Power Manager to Solaris, which stems from GNOME community. Then we'll keep tracking community and provide upstream changes back to them. 4.1 Framework .................................................................................. . +-----------------------+ +------------------------+ +----------------------+ . . |gnome-brightness-applet| | gnome-power-preferences| |gnome-power-statistics| . . +-----------------------+ +------------------------+ +----------------------+ . . ^ ^ ^ . . | (session D-Bus) | (session D-Bus) | (session D-Bus) . . | | | . . V V V . . +--------------------------------------------------+-----------------+ . . | D-Bus interface "org.freedesktop.PowerManagement"| | . . +--------------------------------------------------+ | . . | gnome-power-manager session daemon (unprivileged) | . . | | . . +-----+---------------------------------+----------------------------+ . . GPM ^ ^ . ...............|.................................|................................ | (system D-Bus) | | | JDS consolidation (session) -----------------+---------------------------------+---------------------------------- | | ON consolidation (system) | (system D-Bus) | v V +-----------------------------------------+ +-----------+ | hald (privileged) | | libpolkit | +----------------+ +------------------+ | +-----------+ |hald-addon-acpi | |hald-addon-cpufreq| | |daemon | |daemon | | +--------------------------------------+--+ GNOME Power Manager utitilies are composed of several parts, gnome-power-manager daemon, gnome-power-preferences, gnome-power-statistics, gnome-brightness and D-Bus interfaces "org.freedesktop.PowerManagement". 4.2 gnome-power-manager session daemon gnome-power-manager daemon is a session daemon for GNOME Desktop, which is automatically started by gnome-session when logging in GNOME desktop session. It's unprivileged and run by the user. Basically it's a policy agent talking with HAL and libpolkit. (Here, a gconf policy means an action specified by user and stored in gconf, e.g, an action when battery is low, or an action that will be triggered when lid is closed.) Generally gnome-power-manager listens for HAL events via D-Bus and responds with user-configurable reactions through HAL interfaces, such as suspend, hibernate, set CPU frequency policy, etc. And D-Bus interfaces "org.freedesktop.PowerManagement" are exported to be used for other up-level applications. 4.3 Graphic User Interfaces This project provides some GUIs that serve desktop end user directly, list below. gnome-power-preferences is a GUI configuration program. It allows users to define their preferred policies, e.g. suspend when lid is closed. These policies is enforced by gnome-power-manager daemon. gnome-power-statistics is a GUI program and allows users to visualize the power consumption of laptop hardware. gnome-brightness-applet is a gnome-panel applet, which serves the user for adjusting LCD screen brightness manually. A system-tray status icon controlled by gnome-power-manager daemon also serves the user. It can display battery status and populate shortcut buttons to suspend (suspend to ram) and hibernate (suspend to disk). 4.4 Battery monitor & configuration switching GNOME Power Manager not only reports battery status but also supports relevant power management policies. Using gnome-power-preferences users are able to define different policies for AC and battery. when switching the power source, corresponding policy will be switched accordingly. For example, unplugging AC adapter, GNOME Power Manager immediately replaces battery's policy with AC's. This makes system look smarter. 4.5 Lid switching When lid is closed, HAL notifies GNOME Power Manager through D-Bus. Then GNOME Power Manager triggers a predefined action, such as blank screen,suspend,hibernate,shutdown. Suspend and hibernate depends on HAL interfaces, particularly blanking screen relies on X11 extension DPMS. 4.6 LCD brightness control The user has two ways to toggle brightness adjustment. One is pressing laptop hotkey brightness up/down. The driver in kernel will handle to change brightness, then HAL will notify gnome-power-manager relevant button event through D-Bus. For gnome-power-manager, it will pops up a progress bar to show brightness status. Another way is the user adjust brightness manually from GUI gnome-brightness-applet. In this case, gnome-power-manager will call HAL interface via to set brightness. 4.7 Power button On JDS, pressing power button makes HAL emit a signal to notify gnome-power-manager. Then gnome-power-manager enforces a predefined policy (via HAL interfaces), suspend or hibernate or shutdown, or interact with the user (display the above selectable actions in a dialog to the user throught gnome-sys-supend LSARC/2003/569). 4.8 CPU frequency scaling At present, CPUFreq HAL supports two types of CPU power management policies, "On Demand" and "Performance". "On Demand" means dynamic CPU frequency scaling is performed by monitoring CPU utilization and scaling the frequency when appropriate. "Performance" means getting full CPU utilization all the time. Both policies can be configured from GNOME Power Manager. 4.9 Default policy values Each user logging into JDS for the first time will get some default policy values. like "If suspend is supported on machine, system will suspend when lid close. If suspend is not supported, the action will be to do nothing by default.", "no change in brightness", "no change in cpufreq policy", "Interact with the user when pressing power button". And then, only when the user has enough permission, these gconf policies are presented to the user and allowed to change. 4.10 Screen locking By default, when system is resumed from suspend, hibernate or blanking screen, GPM will automatically lock screen to requrie user passward. To be convient, we also provide the user with a configurable GUI option, which is used to disable or enable screen locking. 4.11 Hardware capability and PolicyKit privilege checking Since the above features aren't present on all systems and to all users. Before showing the user GUI, it needs to check hardware capability or user PolicyKit privilege. Hardware capability is checked through some special HAL properties, like "can_suspend" or "FindDeviceByCapability". User PolicyKit privilege is checked through libpolkit(PSARC/2005/399), which maps PolicyKit privilege to Solaris RBAC authorization. Using libpolkit instead of RBAC directly is for ease of maintenance with code from the GNOME community. Just for UI convenience rather than access control, the following PolicyKit privileges (PSARC/2008/021 defines them and their mapping RBAC authorization in details) will be checked every time the relevant UI component needs to be presented to the user. hal-power-brightness PolicyKit privilege to set brightness hal-power-cpu PolicyKit privilege to set CPU power policy hal-power-suspend PolicyKit privilege to suspend system hal-power-hibernate PolicyKit privilege to hibernate system hal-power-shutdown PolicyKit privilege to shutdown system hal-power-reboot PolicyKit privilege to reboot system There are two possible checking results, "allowed" or "not allowed". If "allowed", the UI component is presented to the user, otherwise the UI is hidden. Please note presenting the user UI is only checkpoint in GNOME Power Manager. When running action via HAL interface, gnome-power-manager itself won't explicitly check PolicyKit privileges since HAL layer is able to check before doing the real action. 4.12 HAL Dependency Basically GNOME Power Manager is a mere consumer of the core functionality provided by the PSARC cases listed below. Some basic HAL API, such as "GetPropertyString" and "SetPropertyString", are provided by "Removable Media Enhancements in Solaris" (PSARC/2005/399). Battery interfaces are from Battery Project (PSARC/2006/601). CPUFreq scaling interfaces is supplied by CPUFreq HAL (PSARC/2007/679). Suspend, hibernate, Brightness, lid and power button are provided by GNOME Power Management Support case (PSARC/2008/021). Especially, GNOME Power Management Support case and CPUFreq HAL case are two putback dependencies for this project. 5. Interface Tables Exported Interface Interface Name Classification Comment ------------------- --------------- -------------- SUNWgnome-power-manager-root Uncommitted GNOME Power Manager - / filesystem /etc/gconf/schemas/gnome-power-manager.schemas Volatile Gconf schema definition file SUNWgnome-power-manager Uncommitted GNOME Power Manager /usr/bin/gnome-power-manager Volatile Session daemon /usr/bin/gnome-power-preferences Volatile Configuration GUI /usr/bin/gnome-power-statistic Volatile GUI to show power consumption statistic /usr/lib/gnome-brightness-applet Volatile gnome-panel applet to adjust brightness /usr/lib/gnome-power-bugreport.sh Volatile Bug reporter tool /usr/lib/gnome-power-cmd.sh Volatile Command-line tool to run suspend/hibernate/shutdown. /usr/lib/bonobo/servers/GNOME_BrightnessApplet.server Volatile Bonobo service configuration file /usr/share/applications/gnome-power-preferences.desktop Volatile Start menu configuration file /usr/share/applications/gnome-power-statistic.desktop Volatile The same as above /usr/share/gnome/autostart/gnome-power-manager.desktop Volatile Autostart configuration /usr/share/dbus-1/services/gnome-power-manager.service Volatile D-Bus services configuration file /usr/share/gnome-2.0/ui/GNOME_BrightnessApplet.xml Volatile Gnome-panel configuration file /usr/share/gnome-power-manager Volatile Installation location for glade files, images /usr/share/gnome/help/gnome-power-manager Volatile GNOME help documentation Exported D-Bus Interface Please see ./power-management-spec-0.2.html. All interfaces are Volatile. Imported Interface Interface Name Classification ARC Case Comment ------------------- --------------- -------------- --------------------------------- GNOME Committed Platform Libraries Committed LSARC/2007/520 GTK+ library GNOME 2.20 gnome-panel Volatile LSARC/2001/348 Window Navigator Construction Kit GNOME Panel D-BUS Volatile LSARC/2006/368 D-Bus library. D-BUS Message Bus System libXext/libX11 Committed PSARC/1998/299 DPMS extension X11R6.4: Update/upgrade of X Server xscreensaver-command CLI Committed LSARC/2001/121 Used to lock screen XScreensaver gnome-sys-suspend CLI Committed LSARC/2003/569 Interact with the user about GNOME sys-suspend suspend action HAL API Volatile PSARC/2005/399 Basic HAL APIs Tamarack: Removable Media Enhancements Battery HAL interfaces Volatile PSARC/2006/601 Transfer ACPI battery event Battery Project CPUfreq HAL interfaces Volatile PSARC/2007/679 Supply CPU freq scaling backend CPUfreq HAL Suspend, brightness, lid, Volatile PSARC/2008/021 Transfer suspend/hibernate, ACPI lid, power button HAL interfaces brightness and power buttons event libpolkit Volatile PSARC/2005/399 Check user PolicyKit privileges hal-power-brightness Volatile PSARC/2008/021 PolicyKit privilege to set brightness hal-power-cpu Volatile PSARC/2008/021 PolicyKit privilege to set CPU power policy hal-power-suspend Volatile PSARC/2008/021 PolicyKit privilege to suspend hal-power-hibernate Volatile PSARC/2008/021 PolicyKit privilege to hibernate hal-power-shutdown Volatile PSARC/2008/021 PolicyKit privilege to shutdown hal-power-reboot Volatile PSARC/2008/021 PolicyKit privilege to reboot 6. Resources and Schedule 6.1 Release Binding Target to a minor release of Solaris 6.2 Resources: 4.00 man month Development Engineering 1.0 man month Test Engineering 0.25 man month RE integration 0.5 man month Doc. writer 0.5 man month Program management 6.3. Consolidation C-team Name: JDS/GNOME 6.4. ARC review type: FastTrack 7. References [1] GNOME Power Manager homepage www.gnome.org/projects/gnome-power-manager Related ARC case LSARC/2007/520 GNOME 2.20 LSARC/2001/348 GNOME Panel LSARC/2006/368 D-BUS Message Bus System PSARC/1998/299 X11R6.4: Update/upgrade of X Server LSARC/2001/121 XScreenSaver LSARC/2003/569 GNOME sys-suspend PSARC/2005/399 Tamarack: Removable Media Enhancements in Solaris PSARC/2006/601 Battery Project PSARC/2007/679 CPUFreq HAL PSARC/2008/021 GNOME Power Manager support Contracts ./contracts/contract-battery-hal.txt ./contracts/contract-cpu-freq-GPM.txt ./contracts/contract-desktop-battery.txt ./contracts/contract-hal.txt ./contracts/contract-GPM-support.txt