share/man/man9p/pm-components.9p

   1 '\" te
   2 .\" Copyright (c) 2004 Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH PM-COMPONENTS 9P "Jan 6, 2004"
   7 .SH NAME
   8 pm-components \- Power Management device property
   9 .SH DESCRIPTION
  10 .sp
  11 .LP
  12 A device is power manageable if the power consumption of the device can be
  13 reduced when it is idle. In general, a power manageable device consists of a
  14 number of power manageable hardware units called components. Each component is
  15 separately controllable and has its own set of power parameters.
  16 .sp
  17 .LP
  18 An example of a one-component power manageable device is a disk whose spindle
  19 motor can be stopped to save power when the disk is idle. An example of a
  20 two-component power manageable device is a frame buffer card with a connected
  21 monitor. The frame buffer electronics (with power that can be reduced when not
  22 in use) comprises the first component. The second component is the monitor,
  23 which can enter in a lower power mode when not in use. The combination of frame
  24 buffer electronics and monitor is considered as one device by the system.
  25 .sp
  26 .LP
  27 In the Power Management framework, all components are considered equal and
  28 completely independent of each other. If this is not true for a particular
  29 device, the device driver must ensure that undesirable state combinations do
  30 not occur. Each component is created in the idle state.
  31 .sp
  32 .LP
  33 The \fBpm-components\fR property describes the Power Management model of a
  34 device driver to the Power Management framework. It lists each power manageable
  35 component by name and lists the power level supported by each component by
  36 numerical value and name. Its syntax and interpretation is described below.
  37 .sp
  38 .LP
  39 This property is only interpreted by the system immediately after the device
  40 has successfully attached, or upon the first call into Power Management
  41 framework, whichever comes first. Changes in the property made by the driver
  42 after the property has been interpreted will not be recognized.
  43 .sp
  44 .LP
  45 \fBpm-components\fR is a string array property. The existence of the
  46 \fBpm-components\fR property indicates that a device implements power
  47 manageable components and describes the Power Management model implemented by
  48 the device driver. The existence of \fBpm-components\fR also indicates to the
  49 framework that device is ready for Power Management if automatic device Power
  50 Management is enabled. See \fBpower.conf\fR(4).
  51 .sp
  52 .LP
  53 The \fBpm-component\fR property syntax is:
  54 .LP
  55 .nf
  56 pm-components="NAME=component name","numeric power level=power level name",  "numeric power level=power level name"  [, "numeric power level=power level name" ...]  [, "NAME=component name", "numeric power level=power level name",  "numeric power level=power level name" [, "numeric power level=power level name"...]...];
  57 .fi
  58
  59 .sp
  60 .LP
  61 The start of each new component is represented by a string consisting of
  62 \fBNAME=\fR followed by the name of the component. This should be a short name
  63 that a user would recognize, such as "Monitor" or "Spindle Motor." The
  64 succeeding elements in the string array must be strings consisting of the
  65 numeric value (can be decimal or 0x <hexadecimal number>) of a power level the
  66 component supports, followed by an equal sign followed by a short descriptive
  67 name for that power level. Again, the names should be descriptive, such as
  68 "On," "Off," "Suspend", "Standby," etc. The next component continues the array
  69 in the same manner, with a string that starts out \fBNAME=\fR, specifying the
  70 beginning of a new component (and its name), followed by specifications of the
  71 power levels the component supports.
  72 .sp
  73 .LP
  74 The components must be listed in increasing order according to the component
  75 number as interpreted by the driver's \fBpower\fR(9E) routine. (Components are
  76 numbered sequentially from 0). The power levels must be listed in increasing
  77 order of power consumption. Each component must support at least two power
  78 levels, or there is no possibility of power level transitions. If a power level
  79 value of 0 is used, it must be the first one listed for that component. A power
  80 level value of 0 has a special meaning (off) to the Power Management framework.
  81 .SH EXAMPLES
  82 .sp
  83 .LP
  84 An example of a \fBpm-components\fR entry from the \fB\&.conf\fR file of a
  85 driver which implements a single power managed component consisting of a disk
  86 spindle motor is shown below. This is component 0 and it supports 2 power
  87 level, which represent spindle stopped or full speed.
  88 .sp
  89 .in +2
  90 .nf
  91 pm-components="NAME=Spindle Motor", "0=Stopped", "1=Full Speed";
  92 \&...
  93 .fi
  94 .in -2
  95 .sp
  96
  97 .sp
  98 .LP
  99 Below is an example of how the above entry would be implemented in the
 100 \fBattach\fR(9E) function of the driver.
 101 .sp
 102 .in +2
 103 .nf
 104 static char *pmcomps[] = {
 105   "NAME=Spindle Motor",
 106     "0=Stopped",
 107     "1=Full Speed"
 108 };
 109
 110 \&...
 111
 112 xxattach(dev_info_t *dip, ddi_attach_cmd_t cmd)
 113 {
 114 \&...
 115     if (ddi_prop_update_string_array(DDI_DEV_T_NONE, dip, "pm-components",
 116        &pmcomp[0], sizeof (pmcomps) / sizeof (char *)) !=DDI_PROP_SUCCESS)
 117                        goto failed;
 118 }
 119 .fi
 120 .in -2
 121 .sp
 122
 123 .sp
 124 .LP
 125 Below is an example for a frame buffer which implements two components.
 126 Component 0 is the frame buffer electronics which supports four different power
 127 levels. Component 1 represents the state of Power Management of the attached
 128 monitor.
 129 .sp
 130 .in +2
 131 .nf
 132 pm-components="NAME=Frame Buffer", "0=Off"
 133         "1=Suspend", "2=Standby", "3=On",
 134                 "NAME=Monitor", "0=Off", "1=Suspend", "2=Standby,"
 135                 "3=On;
 136 .fi
 137 .in -2
 138 .sp
 139
 140 .SH ATTRIBUTES
 141 .sp
 142 .LP
 143 See attributes(5) for descriptions of the following attributes:
 144 .sp
 145
 146 .sp
 147 .TS
 148 box;
 149 c | c
 150 l | l .
 151 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 152 _
 153 Interface stability     Committed
 154 .TE
 155
 156 .SH SEE ALSO
 157 .sp
 158 .LP
 159 \fBpower.conf\fR(4), \fBpm\fR(7D), \fBattach\fR(9E), \fBdetach\fR(9E),
 160 \fBddi_prop_update_string_array\fR(9F) \fBpm_busy_component\fR(9F),
 161 \fBpm_idle_component\fR(9F)
 162 .sp
 163 .LP
 164 \fIWriting Device Drivers\fR