'\" te
.\" Copyright (c) 2005, Sun Microsystems, Inc.  All Rights Reserved
.\" 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.
.\" 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.
.\" 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]
.TH PM_RAISE_POWER 9F "Mar 22, 2005"
.SH NAME
pm_raise_power, pm_lower_power \- Raise or lower power of components
.SH SYNOPSIS
.LP
.nf
#include <sys/ddi.h>
#include <sys/sunddi.h>

\fBint\fR \fBpm_raise_power\fR(\fBdev_info_t *\fR\fIdip,\fR int \fIcomponent\fR, int \fIlevel\fR);
.fi

.LP
.nf
\fBint\fR \fBpm_lower_power\fR(\fBdev_info_t *\fR\fIdip,\fR int \fIcomponent\fR, int \fIlevel\fR);
.fi

.SH INTERFACE LEVEL
.sp
.LP
Solaris DDI specific (Solaris DDI)
.SH PARAMETERS
.SS "pm_raise_power"
.sp
.ne 2
.na
\fB\fIdip\fR\fR
.ad
.RS 13n
Pointer to the device's \fBdev_info\fR structure
.RE

.sp
.ne 2
.na
\fB\fIcomponent\fR\fR
.ad
.RS 13n
The number of the \fIcomponent\fR for which a power level change is desired
.RE

.sp
.ne 2
.na
\fB\fIlevel\fR\fR
.ad
.RS 13n
The power level to which the indicated \fIcomponent\fR will be raised
.RE

.SS "pm_lower_power"
.sp
.ne 2
.na
\fB\fIdip\fR\fR
.ad
.RS 13n
Pointer to the device's \fBdev_info\fR structure
.RE

.sp
.ne 2
.na
\fB\fIcomponent\fR\fR
.ad
.RS 13n
Number of the \fIcomponent\fR for which a power level change is desired
.RE

.sp
.ne 2
.na
\fB\fIlevel\fR\fR
.ad
.RS 13n
Power level to which the indicated \fIcomponent\fR will be lowered
.RE

.SH DESCRIPTION
.sp
.LP
The \fBpm_raise_power\fR(9F) function requests the Power Management framework
to raise the power level of \fIcomponent \fRof \fIdip\fR to at least \fIlevel.
\fR
.sp
.LP
The state of the device should be examined before each physical access. The
\fBpm_raise_power\fR(9F) function should be called to set a \fIcomponent \fR to
the required power level if the operation to be performed requires the
\fIcomponent \fR to be at a power level higher than its current power level.
.sp
.LP
When \fBpm_raise_power\fR(9F) returns with success, the \fIcomponent \fR 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
\fBpm_raise_power\fR(9F).
.sp
.LP
The \fBpm_raise_power\fR(9F) function may cause re-entry of the driver
\fBpower\fR(9E) to raise the power level. Deadlock may result if the driver
locks are held across the call to \fBpm_raise_power\fR(9F).
.sp
.LP
The \fBpm_lower_power\fR(9F) function requests the Power Management framework
to lower the power level of \fIcomponent \fRof \fIdip\fR to at most
\fIlevel\fR.
.sp
.LP
Normally, transitions to lower power levels are initiated by the Power
Management framework based on \fIcomponent\fR idleness. However, when
detaching, the driver should also initiate reduced power levels by setting the
power level of all device components to their lowest levels. The
\fBpm_lower_power\fR(9F) function is intended for this use only, and will
return \fBDDI_FAILURE\fR if the driver is not detaching at the time of the
call.
.sp
.LP
If automatic Power Management is disabled (see \fBdtpower\fR(1M) and
\fBpower.conf\fR(4)), \fBpm_lower_power\fR(9F) returns \fBDDI_SUCCESS\fR
without changing the power level of the component. Otherwise, when
\fBpm_lower_power\fR(9F) returns with success, the \fIcomponent \fR 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
\fBpm_lower_power\fR(9F).
.sp
.LP
The \fBpm_lower_power\fR(9F) function may cause re-entry of the driver
\fBpower\fR(9E) to lower the power level. Deadlock may result if the driver
locks are held across the call to \fBpm_lower_power\fR(9F).
.LP
Note -
.sp
.RS 2
If these functions are called as a result of entry into the driver's
\fBattach\fR(9E), \fBdetach\fR(9E) or \fBpower\fR(9E) entry point, these
functions must be called from the same thread which entered \fBattach\fR(9E),
\fBdetach\fR(9E) or \fBpower\fR(9E).
.RE
.SH RETURN VALUES
.sp
.LP
The \fBpm_raise_power\fR(9F) function returns:
.sp
.ne 2
.na
\fB\fBDDI_SUCCESS\fR\fR
.ad
.RS 15n
\fIComponent\fR is now at the requested power level or higher.
.RE

.sp
.ne 2
.na
\fB\fBDDI_FAILURE\fR\fR
.ad
.RS 15n
\fIComponent \fRor \fIlevel\fR is out of range, or the framework was unable to
raise the power level of the component to the requested level.
.RE

.sp
.LP
The \fBpm_lower_power\fR(9F) function returns:
.sp
.ne 2
.na
\fB\fBDDI_SUCCESS\fR\fR
.ad
.RS 15n
\fI Component \fR is now at the requested power level or lower, or automatic
Power Management is disabled.
.RE

.sp
.ne 2
.na
\fB\fBDDI_FAILURE\fR\fR
.ad
.RS 15n
\fI Component \fR or \fIlevel\fR 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.
.RE

.SH EXAMPLES
.sp
.LP
A hypothetical disk driver might include this code to handle
\fBpm_raise_power\fR(9F):
.sp
.in +2
.nf
static int
xxdisk_strategy(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.
        */

        ASSERT(mutex_owned(xsp->lock));
        if (xsp->pm_busycnt < 1) {
       /*
		   * Component is not already marked busy
		   */
         if (pm_busy_component(xsp->dip,
		        XXDISK_COMPONENT) != DDI_SUCCESS) {
			       bioerror(bp,EIO);
			       biodone(bp);
			       return (0);
		           }
		           xsp->pm_busycnt++;
        }
        mutex_exit(xsp->lock);
        if (pm_raise_power(xsp->dip,
	          XXDISK_COMPONENT, XXPOWER_SPUN_UP) != DDI_SUCCESS) {
		          bioerror(bp,EIO);
		          biodone(bp);
		          return (0);
        }
	      mutex_enter(xsp->lock);

	      ....

}


xxdisk_power(dev_info *dip, int comp, int level)
{

\&...

       /*
        * We fail the power() entry point if the device is busy and
        * request is to lower the power level.

*/

        ASSERT(mutex_owned( xsp->lock));
        if (xsp->pm_busycnt >= 1) {
		       if (level < xsp->cur_level) {
                        mutex_exit( xsp->lock);
                        return (DDI_FAILURE);
                }
        }

\&...

}
.fi
.in -2

.SH CONTEXT
.sp
.LP
These functions can be called from user or kernel context.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for a description of the following attribute:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface stability	Committed
.TE

.SH SEE ALSO
.sp
.LP
\fBpower.conf\fR(4), \fBpm\fR(7D), \fBattach\fR(9E), \fBdetach\fR(9E),
\fBpower\fR(9E), \fBpm_busy_component\fR(9F), \fBpm_idle_component\fR(9F),
\fBpm\fR(9P), \fBpm-components\fR(9P)
.sp
.LP
\fIWriting Device Drivers\fR