Devices pm(7D)
NAME
pm - Power Management driver
SYNOPSIS
/dev/pm
DESCRIPTION
The Power Management ( pm) driver provides an interface for
applications to configure devices within the system for
Power Management. The interface is provided through ioctl(2)
commands. The pm driver may be accessed using /dev/pm.
Power Management Framework
The Power Management framework model allows the system to be
viewed as a collection of devices. Each device is a collec-
tion of components that comprise the smallest power manage-
able units. The device driver controls the definition of a
device's power manageable components.
A component can either be busy or idle at the current power
level. Normally, the Power Management framework takes an
idle component to the next lower power level. The Power
Management framework uses two factors to determine this
transition: the component must have been idle for at least
the threshold time, and the device to which the component
belongs must satisfy any dependency requirements. A depen-
dency occurs when a device requires another device to be
power managed before it can be power managed. Dependencies
occur on a per device basis: when a dependency exists, no
components of a device may be managed unless all the devices
it depends upon are first power managed.
Using the commands below, an application may take control of
the Power Management of a device from the Power Management
framework driver and manage the transition of device power
levels directly.
For this set of ioctl commands, arg (see ioctl(2)) points to
a structure of type pmreq defined in :
typedef struct pmreq {
char *physpath; /* physical path of device */
/* to configure. See libdevinfo(3LIB) */
int component; /* device component */
int value; /* power level, threshold value, or count */
void *data; /* command-dependent variable-sized data */
sizet datasize; /* size of data buffer */
} pmreqt;
SunOS 5.11 Last change: 20 Sep 1999 1
Devices pm(7D)
The fields should contain the following data:
physpath Pointer to the physical path of a device. See
libdevinfo(3LIB). For example, for the device
/devices/pseudo/pm@0:pm the physpath value
would be /pseudo/pm@0.
component Non-negative integer specifying which component
is being configured. The numbering starts at
zero.
value Non-negative integer specifying the threshold
value in seconds or the desired power level, or
the number of levels being specified.
data Pointer to a buffer which contains or receives
variable-sized data, such as the name of a dev-
ice upon which this device has a dependency.
size Size of the data buffer.
Not all fields are used in each command.
PMDIRECTPM
The device named by physpath is disabled from being
power managed by the framework. The caller will power
manage the device directly using the PMDIRECTNOTIFY,
PMGETIMEIDLE and PMGETCURENTPOWER,
PMGETFULPOWER and PMSETCURENTPOWER commands. If
the device needs to have its power level changed either
because its driver calls pmraisepower(9F),
pmlowerpower(9F), or pmpowerhaschanged(9F) or
because the device is the parent of another device that
is changing power level or a device that this device
depends on is changing power level, then the power level
change of the device will be blocked and the caller will
be notified as described below for the PMDIRECTNOTIFY
command.
Error codes:
EBUSY Device already disabled for Power Management by
framework.
SunOS 5.11 Last change: 20 Sep 1999 2
Devices pm(7D)
EPERM Caller is neither superuser nor effective group
ID of 0.
PMRELEASEDIRECTPM
The device named by physpath (which must have been the
target of a PMDIRECTPM command) is re-enabled for
Power Management by the framework.
Error codes:
EINVAL Device component out of range.
PMDIRECTNOTIFY PMDIRECTNOTIFYWAIT
These commands allow the process that is directly power
managing a device to be notified of events that could
change the power level of the device. When such an event
occurs, this command returns information about the
event.
arg (see ioctl(2)) points to a structure of type
pmstatechange defined in :
typedef struct pmstatechange {
char *physpath; /* device which has changed state */
int component; /* which component changed state */
#if defined(BIGENDIAN)
ushortt flags; /* PSCEVENTLOST, PSCALOWEST */
ushortt event; /* type of event */
#else
ushortt event; /* type of event *
ushortt flags; /* PSCEVENTLOST, PSCALOWEST */
#endif
timet timestamp; /* time of state change */]
int oldlevel; /* power level changing from */
int newlevel; /* power level changing to */
sizet size; /* size of buffer physpath points to */
} pmstatechanget;
When an event occurs, the struct pointed to by arg is
filled in. If the event type is PSCPENDINGCHANGE, then
the information in the rest of the struct describes an
action that the framework would have taken if the device
were not directly power managed by the caller. The
caller is responsible for completing the indicated level
changes using PMSETCURENTPOWER below.
SunOS 5.11 Last change: 20 Sep 1999 3
Devices pm(7D)
An event type of PSCHASCHANGED indicates that the
driver for the directly power managed device has called
pmpowerhaschanged(9F) due to the device changing
power on its own. It is provided to allow the caller to
track the power state of the device.
The system keeps events in a circular buffer. If the
buffer overflow, the oldest events are lost and when the
event that next follows a lost event is retrieved it
will have PSCEVENTLOST set in flags.
PMDIRECTNOTIFY returns EWOULDBLOCK if no event is
pending, and PMDIRECTNOTIFYWAIT blocks until an event
is available.
pm also supports the poll(2) interface. When an event is
pending a poll(2) call that includes a file descriptor
for /dev/pm and that has POLIN or POLRDNORM set in
its event mask will return.
PMSETCURENTPOWER
Component component of the device named by physpath
(which must contain the physical path of a device
against which the process has issued a PMDIRECTPM com-
mand) is set to power level value. If all components of
the device named by physpath were at level 0, value is
non-zero and some device has a dependency on this dev-
ice, then all components of that device will be brought
to full power before this command returns. Similarly, if
the parent of the target device is powered off, then it
will be brought up as needed before this command
returns. When PMSETCURENTPOWER is issued against a
device, the resulting power change is included in the
event list for PMDIRECTNOTIFY.
Error codes:
EINVAL Device component out of range, or power level
< 0.
EIO Failed to power device or its ancestors or the
devices on which this device has dependency or
their ancestors. Note that this may not indi-
cate a failure, the device driver may have
rejected the command as inappropriate because
the component has become busy.
SunOS 5.11 Last change: 20 Sep 1999 4
Devices pm(7D)
EPERM Caller has not previously issued a successful
PMDIRECTPM command against this device.
PMGETFULPOWER
The highest supported power level of component component
of the device named by physpath is returned.
PMGETCURENTPOWER
The current power level of component component of the
device named by physpath is returned.
Error codes:
EAGAIN Device component power level is not currently
known.
PMGETIMEIDLE
PMGETIMEIDLE returns the number of seconds that com-
ponent component of the device named by physpath has
been idle. If the device is not idle, then 0 is
returned.
Note that because the state of the device may change
between the time the process issues the PMGETIMEIDLE
command and the time the process issues a
PMSETCURENTPOWER command to reduce the power level
of an idle component, the process must be prepared to
deal with a PMSETCURENTPOWER command returning
failure because the driver has rejected the command as
inappropriate because the device component has become
busy. This can be differentiated from other types of
failures by issuing the PMGETIMEIDLE command again
to see if the component has become busy.
ERORS
Upon error, the commands will return -1, and set errno. In
addition to the error codes listed above by command, the
following error codes are common to all commands:
EFAULT Bad address passed in as argument.
SunOS 5.11 Last change: 20 Sep 1999 5
Devices pm(7D)
ENODEV Device is not power manageable, or device is not
configured.
ENXIO Too many opens attempted.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface stability Unstable
SEE ALSO
pmconfig(1M), Intro(2), ioctl(2), libdevinfo(3LIB),
power.conf(4), attributes(5), attach(9E), detach(9E),
power(9E), pmbusycomponent(9F), pmidlecomponent(9F),
pmlowerpower(9F), pmpowerhaschanged(9F),
pmraisepower(9F)
Writing Device Drivers
SunOS 5.11 Last change: 20 Sep 1999 6
|
