--- GPM_spec_v1.txt 2008-01-15 15:06:17.252545000 +0800 +++ GPM_spec_v2.txt 2008-01-16 11:27:33.546855000 +0800 @@ -6,14 +6,15 @@ Author: Simon Zheng 1.3 Date of This Document: - Dec 27th, 2007 + Jau 15th, 2008 2. Background This project provides Solaris users with a GNOME Power Manager infrastructure. -Solaris has integrated HAL via PSARC/2005/399 Tamarack project, and PSARC 2006/601 -Battery project and PSARC/2007/679 CPUFreq HAL enhance more power management -properties. Based on them, GNOME Power Manager will be able to support many -power management features, such as suspending, hibernating, brightness adjustment, +Solaris has integrated HAL via Tamarack project (PSARC/2005/399), and 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, GNOME Power Manager is able to provide desktop users with many power +management features, such as suspending, hibernating, brightness adjustment, lid closure action, CPU frequency scaling, and etc. 3. Business Consideration @@ -29,108 +30,140 @@ 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-brightness-applet gnome-power-statistics gnome-power-preference | - | | - +--------------------------------+ | - | D-Bus interface | | - | org.freedesktop.PowerManagement| | - +--------------------------------+ | - | gnome-power-manager | | - | daemon | | - +--------------------------------+--------------------------------------+ - ^ - | (D-bus) - | JDS consolidation (up) ------------------+-------------------------------------------------------------- - | ON consolidation (below) - | (D-bus) - v - +-----------------------------------------+ - | HAL daemon (hald) | - +----------------+ +------------------+ | - |hald-addon-acpi | |hald-addon-cpufreq| | - |daemon | |daemon | | - +-------------------------------------+---+ - ^ | - | +-----------------+ - | | Power.conf | - | | pmconfig utility| - | +-----------------+ - | | user space ----------+-------------------------+--------------------------------------- - | | kernel space - v v - +-------------------+ +-------------------+ - | battery, lid | | power management | - | brightness drivers| | framewok | - +-------------------+ +-------------------+ GNOME Power Manager infrastructure is composed of several parts, gnome-power-manager daemon, gnome-power-preferences, gnome-power-statistics, gnome-brightness and D-Bus interfaces "org.freedesktop.PowerManagement". -gnome-power-manager daemon is a backend session-daemon which is automatically started -by gnome-session when logging in GNOME desktop session. It provides a complete and -integrated solution to power management under GNOME desktop environment. It supports -suspending, hibernating, screen blanking, lid closure action, CPU frequency scaling, -and etc. +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 +layer and libpolkit. (Here, a policy points 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 receives HAL event via D-Bus and +then enforces predefined policy by calling HAL interface to do the real action, 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 favorite policies in terms of power source. These policies are enforced by -gnome-power-manager daemon. +their preferred policies, e.g. suspend when lid is closed. These policies is enforced +by gnome-power-manager daemon. -gnome-power-statistics is also a GUI program and allows users to visualize the power +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 for displaying and -adjusting LCD screen brightness level. +gnome-brightness-applet is a gnome-panel applet, which serves the user for adjusting +LCD screen brightness manually. -And D-Bus interfaces "org.freedesktop.PowerManagement" are exported to be used for -other up-level applications. +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.2 Battery monitor & configuration switching -GNOME Power Manager not only reports battery status but also supports power +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. The policy may be an action when battery -becomes very low, or what action would be triggered when lid is closed. Then, -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.3 Brightness, lid and power buttons -On laptop, when brightness up/down is pressed, gnome-power-manager will receive -relevant button event and then pop up a progress bar to show brightness status. -When lid is closed, GNOME Power Manager will trigger a defined action, such as -blank screen, suspend, hibernate. Pressing power button, it will also do the -specified policy. All above buttons events require HAL support. +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. -4.4 CPU frequency scaling +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.5 Suspend/hibernate and its capability and authorization checking -Suspend (suspend to RAM) and hibernate (suspend to disk) functionalities are based on -the HAL D-Bus interface "org.freedesktop.Hal.Device.SystemPowerManagement". Before -showing users suspend/hibernate configuration, GNOME Power Manager will check both -hardware capability and user authorization. Hardware capability checking relies on -HAL's interface "power_management.can_suspend", and user authorization checking uses -HAL's libpolkit. - -4.6 Dependency -GNOME Power Manager heavily depends on HAL layer. Some basic HAL calling methods, -such as "GetPropertyString" and "SetPropertyString", are provided by "Removable -Media Enhancements in Solaris" (PSARC/2005/399). Libpolkit is also from the same. -Battery interfaces are from Battery Project (PSARC/2006/601). CPUFreq scaling -interfaces is supplied by CPUFreq HAL (PSARC/2007/679). Other interfaces about -suspend/hibernate, Brightness, lid and power button are under development and will -be provided soon. In addition, screen blanking depends on X11 DPMS extension -(PSARC/1998/299). +4.9 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.10 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 @@ -202,19 +235,22 @@ Tamarack: Removable Media Enhancements - libpolkit Volatile PSARC/2005/399 Check permission to suspend/hibernate - Tamarack: Removable - Media Enhancements - - Battery HAL Volatile PSARC/2006/601 Transfer ACPI battery event + Battery HAL interfaces Volatile PSARC/2006/601 Transfer ACPI battery event Battery Project - CPUfreq HAL Volatile PSARC/2007/679 Supply CPU freq scaling backend - CPUfreq HAL + CPUfreq HAL interfaces Volatile PSARC/2007/679 Supply CPU freq scaling backend + CPUfreq HAL - HAL suspend/hibernate,lid, Volatile TBD in PSARC soon Transfer suspend/hibernate, ACPI lid, - brightness, power buttons event brightness and power buttons event + 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 @@ -233,12 +269,9 @@ 7. References -[1] GNOME Power Mnanger homepage +[1] GNOME Power Manager homepage www.gnome.org/projects/gnome-power-manager -[2] OpenSolaris laptop project - http://www.opensolaris.org/os/community/laptop/ - Related ARC case LSARC/2007/520 GNOME 2.20 LSARC/2001/348 GNOME Panel @@ -247,4 +280,10 @@ PSARC/2005/399 Tamarack: Removable Media Enhancements in Solaris PSARC/2006/601 Battery Project PSARC/2007/679 CPUFreq HAL - TBD in PSARC soon Suspend/hibernate, lid, brightness and power buttons HAL & driver + 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