561 lines
18 KiB
XML
561 lines
18 KiB
XML
<?xml version="1.0" encoding="UTF-8" ?>
|
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
|
|
|
|
<book id="dpms">
|
|
|
|
<bookinfo>
|
|
<title>X Display Power Management Signaling (DPMS) Extension Protocol Specification</title>
|
|
<subtitle>X Project Team Standard</subtitle>
|
|
<releaseinfo>Version 1.0</releaseinfo>
|
|
<authorgroup>
|
|
<author>
|
|
<firstname>Rob </firstname><surname>Lembree</surname>
|
|
<affiliation><orgname>Digital Equipment Corporation</orgname></affiliation>
|
|
<email>lembree@zk3.dec.com</email>
|
|
</author>
|
|
</authorgroup>
|
|
<corpname>X Consortium Standard</corpname>
|
|
<copyright><year>1996</year><holder>Digital Equipment Corporation</holder></copyright>
|
|
<affiliation><orgname>X Consortium</orgname></affiliation>
|
|
<productnumber>X Version 11, Release 6.8</productnumber>
|
|
|
|
<legalnotice>
|
|
<para>
|
|
Permission to use, copy, modify, distribute, and sell this
|
|
documentation for any purpose is hereby granted without fee,
|
|
provided that the above copyright notice and this permission
|
|
notice appear in all copies. Digital Equipment Corporation
|
|
makes no representations about the suitability for any purpose
|
|
of the information in this document. This documentation is
|
|
provided "as is" without express or implied warranty.
|
|
</para>
|
|
|
|
</legalnotice>
|
|
</bookinfo>
|
|
|
|
<chapter id="Overview">
|
|
<title>Overview</title>
|
|
<para>
|
|
This extension provides X Protocol control over the VESA Display
|
|
Power Management Signaling (DPMS) characteristics of video boards
|
|
under control of the X Window System.<footnote>
|
|
<para>
|
|
<emphasis remap='I'>X Window System</emphasis> is a trademark of The Open Group.
|
|
</para>
|
|
</footnote>
|
|
</para>
|
|
|
|
|
|
<para>
|
|
<!-- .LP -->
|
|
Traditionally, the X Window System has provided for both blanking and
|
|
non-blanking screen savers. Timeouts associated with these built-in
|
|
screen saver mechanisms are limited to idle (dwell) time, and a change
|
|
timeout that specifies the change interval for non-blanking screen savers.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
The United States' Environmental Protection Agency (EPA) Energy Star program
|
|
requires that monitors power down after some idle time by default.
|
|
While it is possible to simply overload the existing screen saver timeouts,
|
|
this solution leaves the non-privileged user little to no control over
|
|
the DPMS characteristics of his or her system. For example, disabling
|
|
DPMS would require some unintended side effect in the core screen saver,
|
|
such as disabling the changing of a non-blanking screen saver. Providing
|
|
clients with this control requires an extension to the core X Window System
|
|
Protocol, and this extension seeks to fill this gap.
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
The design goal of the DPMS extension is to be a logical extension to
|
|
the traditional screen saver. The protocol and sample implementation is
|
|
designed to use the same date types and time units as the screen saver.
|
|
The sample implementation works independently from the screen saver so that
|
|
policy as it pertains to the interaction between screen saver and DPMS can
|
|
be deferred to the user or screen saver application. The extension has
|
|
been tested with and shown to work correctly with both the internal blanking
|
|
and non-blanking screen savers, as well as with screen saver extension
|
|
clients.
|
|
</para>
|
|
<para>
|
|
The DPMS extension is designed to be simple, yet export sufficient
|
|
VESA DPMS information to enable full function clients to be written.
|
|
Included is the ability to sense DPMS capability, set and get DPMS timeouts,
|
|
enable and disable individual DPMS modes, enable and disable DPMS (without
|
|
destroying timeout values), and sense current DPMS on/off state and
|
|
power level.
|
|
</para>
|
|
<para>
|
|
There are four power levels specified by the Video Electronics Standards
|
|
Association (VESA) Display Power Management Signaling (DPMS) standard.
|
|
These are:
|
|
</para>
|
|
|
|
<literallayout class="monospaced">
|
|
<function>DPMS Extension Power Levels</function>
|
|
0 DPMSModeOn In use
|
|
1 DPMSModeStandby Blanked, low power
|
|
2 DPMSModeSuspend Blanked, lower power
|
|
3 DPMSModeOff Shut off, awaiting activity
|
|
</literallayout>
|
|
|
|
<para>
|
|
It is logical to assume that successive DPMS modes be chronologically
|
|
at the same time or later than one another, and the protocol is designed
|
|
to enforce this rule.
|
|
</para>
|
|
|
|
<para>
|
|
Note however that a concious decision is made to decouple the timeouts
|
|
associated with screen saver from the DPMS timeouts. While it might be
|
|
considered logical to require that the first non-zero DPMS timeout be
|
|
greater than or equal to the screen saver timeout, this is intentionally
|
|
omitted, leaving this policy decision to the user or the screen saver
|
|
application. In the case of a laptop where power may be scarce, the
|
|
importance of power savings should supersede the screen saver. If the
|
|
laptop user plugs the unit in and power is no longer a scarce commodity,
|
|
it may be decided to make DPMS less aggressive, or disable it completely.
|
|
</para>
|
|
</chapter>
|
|
|
|
<chapter id="Requests">
|
|
<title>Requests</title>
|
|
<para>
|
|
<function>DPMSGetVersion</function>
|
|
</para>
|
|
|
|
<informaltable frame="none">
|
|
<tgroup cols='1' align='left'>
|
|
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
|
<tbody>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>client_major_version</emphasis>: CARD16
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>client_minor_version</emphasis>: CARD16
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>=></entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>server_major_version</emphasis>: CARD16
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>server_minor_version</emphasis>: CARD16
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>
|
|
If supplied, the <emphasis remap='I'>client_major_version</emphasis> and
|
|
<emphasis remap='I'>client_minor_version</emphasis> indicate what version
|
|
of the protocol the
|
|
client wants the server to implement. The server version numbers
|
|
returned indicate the protocol this extension actually supports. This
|
|
might not equal the version sent by the client. An implementation can
|
|
(but need not) support more than one version simultaneously. The
|
|
<emphasis remap='I'>server_major_version</emphasis> and the
|
|
<emphasis remap='I'>server_minor_version</emphasis> are a
|
|
mechanism to support future revisions of the Display Power Management
|
|
Signaling protocol which may be necessary. In general, the major version
|
|
would increment for incompatible changes, and the minor version would
|
|
increment for small, upward-compatible changes. Servers that support the
|
|
protocol defined in this document will return a
|
|
<emphasis remap='I'>server_major_version</emphasis>
|
|
of one (1), and a <emphasis remap='I'>server_minor_version</emphasis>
|
|
of one (1).
|
|
</para>
|
|
|
|
<para>
|
|
<function>DPMSCapable</function>
|
|
</para>
|
|
|
|
<informaltable frame="none">
|
|
<tgroup cols='1' align='left'>
|
|
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
|
<tbody>
|
|
<row rowsep="0">
|
|
<entry>=></entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>capable</emphasis>: BOOL
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>
|
|
This request is used to determine whether or not the currently running
|
|
server's devices are capable of DPMS operations. The truth value of this
|
|
request is implementation defined, but is generally based on the capabilities
|
|
of the graphic card and monitor combination. Also, the return value in the
|
|
case of heterogeneous multi-head servers is implementation defined.
|
|
</para>
|
|
|
|
<para>
|
|
<function>DPMSGetTimeouts</function>
|
|
</para>
|
|
|
|
<informaltable frame="none">
|
|
<tgroup cols='1' align='left'>
|
|
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
|
<tbody>
|
|
<row rowsep="0">
|
|
<entry>=></entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>standby_timeout</emphasis>: CARD16
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>suspend_timeout</emphasis>: CARD16
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>off_timeout</emphasis>: CARD16
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>
|
|
This request returns the current values of the DPMS timeout values. All
|
|
values are in units of seconds.
|
|
</para>
|
|
|
|
<para>
|
|
<emphasis remap='I'>standby_timeout</emphasis> is the amount of time
|
|
of inactivity before standby
|
|
mode is invoked. The actual effects of this mode are implementation defined,
|
|
but in the case of DPMS compliant hardware, it is implemented by shutting off
|
|
the horizontal sync signal, and pulsing the vertical sync signal. Standby
|
|
mode provides the quickest monitor recovery time. Note also that many
|
|
monitors implement this mode identically to suspend mode. A value of
|
|
zero indicates that this mode is disabled.
|
|
</para>
|
|
|
|
<para>
|
|
<emphasis remap='I'>suspend_timeout</emphasis> is the amount of time
|
|
of inactivity before the second
|
|
level of power savings is invoked. Suspend mode's physical and electrical
|
|
characteristics are implementation defined, but in DPMS compliant hardware,
|
|
results in the pulsing of the horizontal sync signal, and shutting off of
|
|
the vertical sync signal. Suspend mode recovery is considered to be slower
|
|
than standby mode, but faster than off mode, however this is monitor
|
|
dependent. As noted above, many monitors implement this mode identically to
|
|
standby mode. A value of zero indicates that this mode is disabled.
|
|
</para>
|
|
|
|
<para>
|
|
<emphasis remap='I'>off_timeout</emphasis> is the amount of time of
|
|
inactivity before the third and
|
|
final level of power savings is invoked. Off mode's physical and electrical
|
|
characteristics are implementation defined, but in DPMS compliant hardware,
|
|
is implemented by shutting off both horizontal and vertical sync signals,
|
|
resulting in the power-down of the monitor. Recovery time is implementation
|
|
dependant, but frequently is similar to the power-up time of the monitor. A
|
|
value of zero indicates that this mode is disabled.
|
|
</para>
|
|
|
|
<para>
|
|
<function>DPMSSetTimeouts</function>
|
|
</para>
|
|
|
|
<informaltable frame="none">
|
|
<tgroup cols='1' align='left'>
|
|
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
|
<tbody>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>standby_timeout</emphasis>: CARD16
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>suspend_timeout</emphasis>: CARD16
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>off_timeout</emphasis>: CARD16
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>=></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
|
|
<para>
|
|
All values are in units of seconds.
|
|
<emphasis remap='I'>standby_timeout</emphasis> is the amount of
|
|
time of inactivity before standby mode will be invoked. This is the
|
|
lightest level of power savings, and the monitor is generally immediately
|
|
ready upon detection of user activity. This is most often implemented by
|
|
shutting off the horizontal sync signal to the monitor.
|
|
A value of zero disables this mode.
|
|
</para>
|
|
|
|
<para>
|
|
The <emphasis remap='I'>suspend_timeout</emphasis> specifies the amount
|
|
of time of inactivity
|
|
before the screen is placed into suspend mode. Suspend mode is the
|
|
middle level of power savings, resulting in a slightly longer recovery
|
|
upon detection of activity. Suspend mode is most often implemented by
|
|
pulsing the horizontal sync signal, and removing the vertical sync
|
|
signal. A value of zero disables this mode.
|
|
</para>
|
|
|
|
<para>
|
|
The <emphasis remap='I'>off_timeout</emphasis> specifies the amount of
|
|
time of inactivity before
|
|
the monitor is shut off. Off mode is the deepest level of power management,
|
|
resulting in the greatest power savings and the longest recovery time.
|
|
Off mode is most often implemented by removing both the horizontal and
|
|
vertical signals. A value of zero disables this mode.
|
|
</para>
|
|
<para>
|
|
The values of successive power levels must be greater than or equal
|
|
to the value of the previous (non-zero) level. A BadValue error is generated
|
|
if an illegal combination is detected.
|
|
</para>
|
|
<para>
|
|
<function>DPMSEnable</function>
|
|
</para>
|
|
<para>
|
|
=>
|
|
</para>
|
|
|
|
<para>
|
|
This request enables the DPMS characteristics of the server, using the
|
|
server's currently stored timeouts. If DPMS is already enabled, no change is
|
|
effected.
|
|
</para>
|
|
|
|
<para>
|
|
<function>DPMSDisable</function>
|
|
</para>
|
|
<para>
|
|
=>
|
|
</para>
|
|
|
|
<para>
|
|
This request disables the DPMS characteristics of the server. It does
|
|
not affect the core or extension screen savers. If DPMS is already
|
|
disabled, no change is effected. This request is provided so that DPMS
|
|
may be disabled without damaging the server's stored timeout values.
|
|
</para>
|
|
|
|
<para>
|
|
<function>DPMSForceLevel</function>
|
|
</para>
|
|
|
|
<informaltable frame="none">
|
|
<tgroup cols='1' align='left'>
|
|
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
|
<tbody>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>power_level</emphasis>: CARD16
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>=></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>
|
|
This request forces a specific DPMS level on the server. If DPMS is
|
|
disabled, a BadMatch error is generated. If an erroneous power level
|
|
is specified, a BadValue error is returned, and the error value contains
|
|
the bad value. If the power level specified is already in effect, no
|
|
changes occur. Power Level must be one of DPMSModeOn, DPMSModeStandby,
|
|
DPMSModeSuspend or DPMSModeOff.
|
|
</para>
|
|
|
|
<para>
|
|
<function>DPMSInfo</function>
|
|
</para>
|
|
|
|
<informaltable frame="none">
|
|
<tgroup cols='1' align='left'>
|
|
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
|
<tbody>
|
|
<row rowsep="0">
|
|
<entry>=></entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>power_level</emphasis>: CARD16
|
|
</entry>
|
|
</row>
|
|
<row rowsep="0">
|
|
<entry>
|
|
<emphasis remap='I'>state</emphasis>: BOOL
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>
|
|
This request returns information about the current DPMS state of the
|
|
display. <emphasis remap='I'>state</emphasis> is one of DPMSEnabled
|
|
or DPMSDisabled.
|
|
If <emphasis remap='I'>state</emphasis> is DPMSEnabled,
|
|
<emphasis remap='I'>power_level</emphasis> is returned as one
|
|
of DPMSModeOn, DPMSModeStandby, DPMSModeSuspend or DPMSModeOff, otherwise
|
|
it is undefined.
|
|
</para>
|
|
|
|
</chapter>
|
|
|
|
<chapter id="Events_and_Errors">
|
|
<title>Events and Errors</title>
|
|
<para>
|
|
No new events or errors are defined by this extension.
|
|
</para>
|
|
</chapter>
|
|
|
|
<chapter id="Encoding">
|
|
<title>Encoding</title>
|
|
<para>
|
|
Please refer to the X11 Protocol Encoding document as this document uses
|
|
conventions established there.
|
|
</para>
|
|
|
|
<para>
|
|
The name of this extension is "DPMS".
|
|
</para>
|
|
|
|
<literallayout class="monospaced">
|
|
<function>DPMSGetVersion</function>
|
|
1 CARD8 opcode
|
|
1 0 DPMS opcode
|
|
2 2 request length
|
|
2 CARD16 client_major_version
|
|
2 CARD16 client_minor_version
|
|
=>
|
|
1 1 Reply
|
|
1 unused
|
|
2 CARD16 sequence number
|
|
4 0 length
|
|
2 CARD16 server_major_version
|
|
2 CARD16 server_minor_version
|
|
20 unused
|
|
</literallayout>
|
|
|
|
<literallayout class="monospaced">
|
|
<function>DPMSCapable</function>
|
|
1 CARD8 opcode
|
|
1 1 DPMS opcode
|
|
2 1 request length
|
|
=>
|
|
1 1 Reply
|
|
1 unused
|
|
2 CARD16 sequence number
|
|
4 0 length
|
|
1 BOOL capable
|
|
23 unused
|
|
</literallayout>
|
|
|
|
<literallayout class="monospaced">
|
|
<function>DPMSGetTimeouts</function>
|
|
1 CARD8 opcode
|
|
1 2 DPMS opcode
|
|
2 1 request length
|
|
=>
|
|
1 1 Reply
|
|
1 unused
|
|
2 CARD16 sequence number
|
|
4 0 length
|
|
2 CARD16 standby_timeout
|
|
2 CARD16 suspend_timeout
|
|
2 CARD16 off_timeout
|
|
18 unused
|
|
</literallayout>
|
|
|
|
<literallayout class="monospaced">
|
|
<function>DPMSSetTimeouts</function>
|
|
1 CARD8 opcode
|
|
1 3 DPMS opcode
|
|
2 3 request length
|
|
2 CARD16 standby_timeout
|
|
2 CARD16 suspend_timeout
|
|
2 CARD16 off_timeout
|
|
2 unused
|
|
=>
|
|
</literallayout>
|
|
|
|
<literallayout class="monospaced">
|
|
<function>DPMSEnable</function>
|
|
1 CARD8 opcode
|
|
1 4 DPMS opcode
|
|
2 1 request length
|
|
=>
|
|
</literallayout>
|
|
|
|
<literallayout class="monospaced">
|
|
<function>DPMSDisable</function>
|
|
1 CARD8 opcode
|
|
1 5 DPMS opcode
|
|
2 1 request length
|
|
=>
|
|
</literallayout>
|
|
|
|
<literallayout class="monospaced">
|
|
<function>DPMSForceLevel</function>
|
|
1 CARD8 opcode
|
|
1 6 DPMS opcode
|
|
2 2 request length
|
|
2 power_level
|
|
0 DPMSModeOn
|
|
1 DPMSModeStandby
|
|
2 DPMSModeSuspend
|
|
3 DPMSModeOff
|
|
2 unused
|
|
=>
|
|
</literallayout>
|
|
|
|
<literallayout class="monospaced">
|
|
<function>DPMSInfo</function>
|
|
1 CARD8 opcode
|
|
1 7 DPMS opcode
|
|
2 1 request length
|
|
=>
|
|
1 1 Reply
|
|
1 unused
|
|
2 CARD16 sequence number
|
|
4 0 length
|
|
2 power_level
|
|
0 DPMSModeOn
|
|
1 DPMSModeStandby
|
|
2 DPMSModeSuspend
|
|
3 DPMSModeOff
|
|
1 BOOL state
|
|
21 unused
|
|
|
|
</literallayout>
|
|
</chapter>
|
|
</book>
|