# Copyright (c) 1999, 2010, Oracle and/or its affiliates. All rights reserved. # # Permission is hereby granted, free of charge, to any person obtaining a # copy of this software and associated documentation files (the "Software"), # to deal in the Software without restriction, including without limitation # the rights to use, copy, modify, merge, publish, distribute, sublicense, # and/or sell copies of the Software, and to permit persons to whom the # Software is furnished to do so, subject to the following conditions: # # The above copyright notice and this permission notice (including the next # paragraph) shall be included in all copies or substantial portions of the # Software. # # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL # THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER # DEALINGS IN THE SOFTWARE. # # Originally submitted as PSARC/1999/188 # Server side has only been implemented in Xsun, not Xorg 1.0 Introduction 1.1 Project/Component Working Name: FBPM (Frame Buffer Power Management) Extension to the Xserver. 1.2 Purpose The purpose of this fast track page is to request approval for the addition of the FBPM extension to the Xserver. 2.0 Description 2.1 Background 2.1.1 Power Management The EPA through the E-Star program has mandated that computers use less power when not in use. This can be done by slowing down the CPU clock and selectively removing power from parts of the system that are in an idle state. There are timers that control when power states change and a sequence of ever more aggressive power reductions, until the system is in its lowest possible power mode. Any activity at the keyboard or some external command, can bring the system back up to a higher power state. The FBPM extension is an implementation that allows the Xserver to control the power level of the frame buffer. It is a requirement that the Xserver have this control, in order to maintain an orderly shutdown and powerup of the display system. 2.1.2 DPMS DPMS was created as part of the X Consortium X11R6.4 standard. Display Power Management Signaling (DPMS) is an implementation of the E-Star requirements. DPMS controls only the monitor portion of the system and not the frame buffer. It does however provide the timing functions that FBPM will use while controlling the frame buffer power. Excalibur is the first system that will support the latest E-Star standard. It will have the ability to control the power consumption of various parts of the system, including the Frame Buffer. In the future Sun will have frame buffers that implement up to 4 power states. Some frame buffer vendors already have this capability in their hardware. 2.2 The problem By default Excalibur will "turn off" the framebuffer (ie reduce power by >90%) after the system is idle for 30 minutes (as per E-Star standard). It's required that the user be able to modify this time interval or disable FBPM using the new dtpower application (see PSARC/1999/251). 2.3 Proposed Solution 2.3.1 FBPM control Add an extension to the Xserver that allows the user to control FBPM functions. 2.3.2 Why not just DPMS Although DPMS is the cornerstone of FBPM, DPMS is a standard X Consortium extension. DPMS was not designed to control frame buffer power, and Sun would violate the standard if we modified our DPMS extension to do so. 2.3.3 xset, command line control The xset program is modified to support user command line control over the FBPM functionality, as follows: xset +fbpm /* Enable FBPM */ xset -fbpm /* Disable FBPM */ xset fbpm force on /* Set FBPM to on */ xset fbpm force standby /* Set FBPM to standby */ xset fbpm force suspend /* Set FBPM to suspend */ xset fbpm force off /* Set FBPM to off */ 2.3.4 exported library functions The following public functions will be added to libXext.so.0 (this is the standard location for X Extensions). * FBPMQueryExtension Find out if the extension is available. * FBPMGetVersion Get the version of the extension. * FBPMCapable Find out if the hardware can do FBPM. * FBPMEnable Enable FBPM. * FBPMDisable Disable FBPM. * FBPMInfo Read back info about FBPM. * FBPMForce Force the frame buffer into the specified power state. 2.3.5 exported Xsun DDX interface functions * FBPMPMInit Initialize interface between FBPM and DDX. 3.0 Motivation The proposed FBPM extension is required to support E-Star frame buffer power management on Excalibur. 4.0 Interfaces 4.1 Exported Interfaces xset CLI Stable [Additions to the xset command line interface (see 2.3.3)] FBPMQueryExtension Stable FBPMGetVersion Stable FBPMCapable Stable FBPMEnable Stable FBPMDisable Stable FBPMInfo Stable FBPMForce Stable FBPMPMInit Stable ======================================================================= Detailed spec on each new interface: ----------------------------------------------------------------------- Bool FBPMEnable(Display* display) display is the X Display. FBPMEnable() returns true if the DDX/framebuffer was able to perform the request, false otherwise. Since the FBPM state changes are synched with the DPMS state changes, whenever DPMS(state) == FBPM(state), then FBPM state changes will follow all further DPMS state changes. Note: It is not possible to turn the frame buffer off if the monitor is on. ----------------------------------------------------------------------- void FBPMDisable(Display* display) display is the X Display. This call disables FBPM, and the frame buffer will always be ON regardless of DPMS or any other power management. This is the way that all current Sun systems behave (i.e. if the system has power, the frame buffer is ON). NOTE: If FBPMDisable() is called when the frame buffer is in any state other than ON, the frame buffer state is changed to ON. ------------------------------------------------------------------------ Bool FBPMInfo(Display* display, int* level) display is the X Display. level returns the frame buffer's current power level (FBPMModeOn, FBPMModeStandby, FBPMModeSuspend, FBPMModeOff). FBPMInfo() returns TRUE if FBPM is enabled, FALSE if FBPM is disabled. ------------------------------------------------------------------------ Bool FBPMQueryExtension(Display* display, int* event_base, int* error_base) This is the standard X Windows extension function which the X client uses to determine whether the Xserver supports the FBPM extension. ------------------------------------------------------------------------ Status FBPMForceLevel(Display *display, int level) display is the X Display. level is the power level (or state) that the user want. They can be FBPMModeOn, FBPMModeStandby, FBPMModeSuspend, and FBPMModeOff. FBPMForceLevel returns BadValue if a requested state is not one of the legal states. TRUE is returned otherwise. FBPMForceLevel is provided primarily for debugging DDX code. It is desirable to force the DDX to a certain state and then observe the code and hardware functions. ------------------------------------------------------------------------ void FBPMPMInit(int screen, void* Procs) NOTE: Only a frame buffer DDX is allowed to call FBPMPMInit(). FBPMPMInit() will not be in the FBPM man page. It will be documented in the Solaris DDX OpenGraphics interface docs. screen is the Display's screen number. Procs is the standard DDX function vector interface. If the DDX/framebuffer does not support frame buffer power management, then the DDX will not call FBPMPMInit(), the function vector will be NULL, and the FBPM extension is disabled. ------------------------------------------------------------------------- Bool FBPMDDXStateChange(int current, int new, int FBPMswitch, int pm_fd, char* fb_name, Screen pScreen) This is the DDX function vector for frame buffer power management (it will be documented in the Solaris DDX OpenGraphics interface docs). FBPM sends all extension requests to the DDX by calling this DDX function. The DDX passes those requests to the appropriate drivers. current is the current DPMS power level. new is the requested frame buffer power level. Default behavior is for new to be the same as current (i.e. by default the frame buffer power level changes in sync with the DPMS power level). FBPMswitch is a control that signals DDX that FBPM is on. Since DDX will manage the DPMS monitor levels, it needs to know if the user has unlinked FBPM. pm_fd is the file descriptor for /dev/pm. The Xserver opens the device and passes the fd to the DDX. fb_name is the name string for the frame buffer. Xserver knows this name, however it is hidden from the DDX layer. pScreen is the pointer to the Screen struct. DPMSDDXStateChange() returns true if the DDX was able to complete the request, false otherwise.