components/x11/sun-ext-protos/files/docs/FBPM.txt

   1 # Copyright (c) 1999, 2010, Oracle and/or its affiliates. All rights reserved.
   2 #
   3 # Permission is hereby granted, free of charge, to any person obtaining a
   4 # copy of this software and associated documentation files (the "Software"),
   5 # to deal in the Software without restriction, including without limitation
   6 # the rights to use, copy, modify, merge, publish, distribute, sublicense,
   7 # and/or sell copies of the Software, and to permit persons to whom the
   8 # Software is furnished to do so, subject to the following conditions:
   9 #
  10 # The above copyright notice and this permission notice (including the next
  11 # paragraph) shall be included in all copies or substantial portions of the
  12 # Software.
  13 #
  14 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  15 # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  16 # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  17 # THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  18 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  19 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  20 # DEALINGS IN THE SOFTWARE.
  21 #
  22 # Originally submitted as PSARC/1999/188
  23 # Server side has only been implemented in Xsun, not Xorg
  24
  25 1.0 Introduction
  26
  27 1.1 Project/Component Working Name:
  28
  29 FBPM (Frame Buffer Power Management) Extension to the Xserver.
  30
  31 1.2 Purpose
  32
  33 The purpose of this fast track page is to request approval for the
  34 addition of the FBPM extension to the Xserver.
  35
  36 2.0 Description
  37
  38 2.1 Background
  39
  40 2.1.1 Power Management
  41
  42 The EPA through the E-Star program has mandated that computers use less
  43 power when not in use.  This can be done by slowing down the CPU clock
  44 and selectively removing power from parts of the system that are in an
  45 idle state.  There are timers that control when power states change
  46 and a sequence of ever more aggressive power reductions, until the
  47 system is in its lowest possible power mode.  Any activity at the keyboard
  48 or some external command, can bring the system back up to a higher power
  49 state.
  50
  51 The FBPM extension is an implementation that allows the Xserver to control
  52 the power level of the frame buffer.  It is a requirement that the Xserver
  53 have this control, in order to maintain an orderly shutdown and powerup
  54 of the display system.
  55
  56 2.1.2 DPMS
  57
  58 DPMS was created as part of the X Consortium X11R6.4 standard. Display
  59 Power Management Signaling (DPMS) is an implementation of the
  60 E-Star requirements.   DPMS controls only the monitor portion of the system
  61 and not the frame buffer.  It does however provide the timing functions
  62 that FBPM will use while controlling the frame buffer power.
  63
  64 Excalibur is the first system that will support the latest E-Star standard.
  65 It will have the ability to control the power consumption of various parts
  66 of the system, including the Frame Buffer.
  67
  68 In the future Sun will have frame buffers that implement up to 4 power states.
  69 Some frame buffer vendors already have this capability in their hardware.
  70
  71 2.2 The problem
  72
  73 By default Excalibur will "turn off" the framebuffer (ie reduce power by >90%)
  74 after the system is idle for 30 minutes (as per E-Star standard).
  75 It's required that the user be able to modify this time interval or disable
  76 FBPM using the new dtpower application (see PSARC/1999/251).
  77
  78 2.3 Proposed Solution
  79
  80 2.3.1 FBPM control
  81
  82 Add an extension to the Xserver that allows the user to control FBPM functions.
  83
  84 2.3.2 Why not just DPMS
  85
  86 Although DPMS is the cornerstone of FBPM, DPMS is a standard X Consortium
  87 extension.  DPMS was not designed to control frame buffer power, and
  88 Sun would violate the standard if we modified our DPMS extension to do so.
  89
  90 2.3.3 xset, command line control
  91
  92 The xset program is modified to support user command line control over the
  93 FBPM functionality, as follows:
  94 xset +fbpm                /* Enable FBPM */
  95 xset -fbpm                /* Disable FBPM */
  96 xset fbpm force on        /* Set FBPM to on */
  97 xset fbpm force standby   /* Set FBPM to standby */
  98 xset fbpm force suspend   /* Set FBPM to suspend */
  99 xset fbpm force off       /* Set FBPM to off */
 100
 101
 102 2.3.4 exported library functions
 103
 104 The following public functions will be added to libXext.so.0 (this is
 105 the standard location for X Extensions).
 106
 107 * FBPMQueryExtension
 108 Find out if the extension is available.
 109
 110 * FBPMGetVersion
 111 Get the version of the extension.
 112
 113 * FBPMCapable
 114 Find out if the hardware can do FBPM.
 115
 116 * FBPMEnable
 117 Enable FBPM.
 118
 119 * FBPMDisable
 120 Disable FBPM.
 121
 122 * FBPMInfo
 123 Read back info about FBPM.
 124
 125 * FBPMForce
 126 Force the frame buffer into the specified power state.
 127
 128 2.3.5 exported Xsun DDX interface functions
 129
 130 * FBPMPMInit
 131 Initialize interface between FBPM and DDX.
 132
 133
 134 3.0 Motivation
 135
 136 The proposed FBPM extension is required to support E-Star
 137 frame buffer power management on Excalibur.
 138
 139 4.0 Interfaces
 140
 141 4.1 Exported Interfaces
 142
 143 xset CLI                        Stable
 144         [Additions to the xset command line interface (see 2.3.3)]
 145
 146 FBPMQueryExtension              Stable
 147 FBPMGetVersion                  Stable
 148 FBPMCapable                     Stable
 149 FBPMEnable                      Stable
 150 FBPMDisable                     Stable
 151 FBPMInfo                        Stable
 152 FBPMForce                       Stable
 153 FBPMPMInit                      Stable
 154
 155 =======================================================================
 156
 157 Detailed spec on each new interface:
 158 -----------------------------------------------------------------------
 159
 160 Bool FBPMEnable(Display* display)
 161
 162  display is the X Display.
 163
 164
 165  FBPMEnable() returns true if the DDX/framebuffer was able to perform
 166  the request, false otherwise.
 167
 168  Since the FBPM state changes are synched with the DPMS state changes,
 169  whenever DPMS(state) == FBPM(state), then FBPM state changes will
 170  follow all further DPMS state changes.
 171
 172  Note: It is not possible to turn the frame buffer off if the monitor
 173  is on.
 174
 175 -----------------------------------------------------------------------
 176
 177 void FBPMDisable(Display* display)
 178
 179  display is the X Display.
 180
 181  This call disables FBPM, and the frame buffer will always be ON
 182  regardless of DPMS or any other power management. This is the way
 183  that all current Sun systems behave (i.e. if the system has power,
 184  the frame buffer is ON).
 185
 186  NOTE: If FBPMDisable() is called when the frame buffer is in any
 187  state other than ON, the frame buffer state is changed to ON.
 188
 189
 190 ------------------------------------------------------------------------
 191
 192 Bool FBPMInfo(Display* display, int* level)
 193
 194  display is the X Display.
 195
 196  level returns the frame buffer's current power level (FBPMModeOn,
 197  FBPMModeStandby, FBPMModeSuspend, FBPMModeOff).
 198
 199  FBPMInfo() returns TRUE if FBPM is enabled, FALSE if FBPM is
 200  disabled.
 201
 202 ------------------------------------------------------------------------
 203
 204 Bool FBPMQueryExtension(Display* display, int* event_base,
 205                         int* error_base)
 206
 207  This is the standard X Windows extension function which the X client
 208  uses to determine whether the Xserver supports the FBPM extension.
 209
 210 ------------------------------------------------------------------------
 211
 212 Status FBPMForceLevel(Display *display, int level)
 213
 214  display is the X Display.
 215
 216  level is the power level (or state) that the user want.  They can be
 217  FBPMModeOn, FBPMModeStandby, FBPMModeSuspend, and FBPMModeOff.
 218
 219  FBPMForceLevel returns BadValue if a requested state is not one of
 220  the legal states.  TRUE is returned otherwise.
 221
 222  FBPMForceLevel is provided primarily for debugging DDX code.  It is
 223  desirable to force the DDX to a certain state and then observe the
 224  code and hardware functions.
 225
 226 ------------------------------------------------------------------------
 227
 228 void FBPMPMInit(int screen, void* Procs)
 229
 230  NOTE: Only a frame buffer DDX is allowed to call FBPMPMInit().
 231  FBPMPMInit() will not be in the FBPM man page. It will be documented
 232  in the Solaris DDX OpenGraphics interface docs.
 233
 234  screen is the Display's screen number.
 235
 236  Procs is the standard DDX function vector interface. If the
 237  DDX/framebuffer does not support frame buffer power management, then
 238  the DDX will not call FBPMPMInit(), the function vector will be NULL,
 239  and the FBPM extension is disabled.
 240
 241 -------------------------------------------------------------------------
 242
 243 Bool FBPMDDXStateChange(int current, int new, int FBPMswitch, int pm_fd,
 244                         char* fb_name, Screen pScreen)
 245
 246  This is the DDX function vector for frame buffer power management (it
 247  will be documented in the Solaris DDX OpenGraphics interface
 248  docs). FBPM sends all extension requests to the DDX by calling this
 249  DDX function. The DDX passes those requests to the appropriate
 250  drivers.
 251
 252  current is the current DPMS power level.
 253
 254  new is the requested frame buffer power level. Default behavior is
 255  for new to be the same as current (i.e. by default the frame buffer
 256  power level changes in sync with the DPMS power level).
 257
 258  FBPMswitch is a control that signals DDX that FBPM is on.  Since DDX
 259  will manage the DPMS monitor levels, it needs to know if the user has
 260  unlinked FBPM.
 261
 262  pm_fd is the file descriptor for /dev/pm.  The Xserver opens the
 263  device and passes the fd to the DDX.
 264
 265  fb_name is the name string for the frame buffer.  Xserver knows this
 266  name, however it is hidden from the DDX layer.
 267
 268  pScreen is the pointer to the Screen struct.
 269
 270  DPMSDDXStateChange() returns true if the DDX was able to complete the
 271  request, false otherwise.