Kernel Functions for Drivers pmraisepower(9F)
NAME
pmraisepower, pmlowerpower - Raise or lower power of
components
SYNOPSIS
#include
#include
int pmraisepower(devinfot *dip, int component, int level);
int pmlowerpower(devinfot *dip, int component, int level);
INTERFACE LEVEL
Solaris DI specific (Solaris DI)
PARAMETERS
pmraisepower
dip Pointer to the device's devinfo structure
component The number of the component for which a power
level change is desired
level The power level to which the indicated com-
ponent will be raised
pmlowerpower
dip Pointer to the device's devinfo structure
component Number of the component for which a power level
change is desired
level Power level to which the indicated component
will be lowered
DESCRIPTION
The pmraisepower(9F) function requests the Power Manage-
ment framework to raise the power level of component of dip
to at least level.
The state of the device should be examined before each phy-
sical access. The pmraisepower(9F) function should be
called to set a component to the required power level if
the operation to be performed requires the component to be
SunOS 5.11 Last change: 22 March 2005 1
Kernel Functions for Drivers pmraisepower(9F)
at a power level higher than its current power level.
When pmraisepower(9F) returns with success, the component
is guaranteed to be at least at the requested power level.
All devices that depend on this will be at their full power
level. Since the actual device power level may be higher
than requested by the driver, the driver should not make any
assumption about the absolute power level on successful
return from pmraisepower(9F).
The pmraisepower(9F) function may cause re-entry of the
driver power(9E) to raise the power level. Deadlock may
result if the driver locks are held across the call to
pmraisepower(9F).
The pmlowerpower(9F) function requests the Power Manage-
ment framework to lower the power level of component of dip
to at most level.
Normally, transitions to lower power levels are initiated by
the Power Management framework based on component idleness.
However, when detaching, the driver should also initiate
reduced power levels by setting the power level of all dev-
ice components to their lowest levels. The
pmlowerpower(9F) function is intended for this use only,
and will return DIFAILURE if the driver is not detaching
at the time of the call.
If automatic Power Management is disabled (see dtpower(1M)
and power.conf(4)), pmlowerpower(9F) returns DISUCES
without changing the power level of the component. Other-
wise, when pmlowerpower(9F) returns with success, the com-
ponent is guaranteed to be at most at the requested power
level. Since the actual device power level may be lower than
requested by the driver, the driver should not make any
assumption about the absolute power level on successful
return from pmlowerpower(9F).
The pmlowerpower(9F) function may cause re-entry of the
driver power(9E) to lower the power level. Deadlock may
result if the driver locks are held across the call to
pmlowerpower(9F).
Note -
If these functions are called as a result of entry into
SunOS 5.11 Last change: 22 March 2005 2
Kernel Functions for Drivers pmraisepower(9F)
the driver's attach(9E), detach(9E) or power(9E) entry
point, these functions must be called from the same thread
which entered attach(9E), detach(9E) or power(9E).
RETURN VALUES
The pmraisepower(9F) function returns:
DISUCES Component is now at the requested power level
or higher.
DIFAILURE Component or level is out of range, or the
framework was unable to raise the power level
of the component to the requested level.
The pmlowerpower(9F) function returns:
DISUCES Component is now at the requested power
level or lower, or automatic Power Management
is disabled.
DIFAILURE Component or level is out of range, or the
framework was unable to lower the power level
of the component to the requested level, or
the device is not detaching.
EXAMPLES
A hypothetical disk driver might include this code to handle
pmraisepower(9F):
static int
xxdiskstrategy(struct buf *bp)
{
...
/*
* At this point we have determined that we need to raise the
* power level of the device. Since we have to drop the
* mutex, we need to take care of case where framework is
* lowering power at the same time we are raising power.
* We resolve this by marking the device busy and failing
* lower power in power() entry point when device is busy.
*/
ASERT(mutexowned(xsp->lock));
if (xsp->pmbusycnt < 1) {
/*
SunOS 5.11 Last change: 22 March 2005 3
Kernel Functions for Drivers pmraisepower(9F)
* Component is not already marked busy
*/
if (pmbusycomponent(xsp->dip,
XDISKCOMPONENT) != DISUCES) {
bioerror(bp,EIO);
biodone(bp);
return (0);
}
xsp->pmbusycnt];
}
mutexexit(xsp->lock);
if (pmraisepower(xsp->dip,
XDISKCOMPONENT, XPOWERSPUNUP) != DISUCES) {
bioerror(bp,EIO);
biodone(bp);
return (0);
}
mutexenter(xsp->lock);
....
}
xxdiskpower(devinfo *dip, int comp, int level)
{
...
/*
* We fail the power() entry point if the device is busy and
* request is to lower the power level.
*/
ASERT(mutexowned( xsp->lock));
if (xsp->pmbusycnt >= 1) {
if (level < xsp->curlevel) {
mutexexit( xsp->lock);
return (DIFAILURE);
}
}
...
}
CONTEXT
These functions can be called from user or kernel context.
SunOS 5.11 Last change: 22 March 2005 4
Kernel Functions for Drivers pmraisepower(9F)
ATRIBUTES
See attributes(5) for a description of the following attri-
bute:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface stability Committed
SEE ALSO
power.conf(4), pm(7D), attach(9E), detach(9E), power(9E),
pmbusycomponent(9F), pmidlecomponent(9F), pm(9P), pm-
components(9P)
Writing Device Drivers
SunOS 5.11 Last change: 22 March 2005 5
|
