'\" te
.\"  Copyright (c) 2003, Sun Microsystems, Inc.  All Rights Reserved
.TH power 9E "12 Dec 2003" "SunOS 5.11" "Driver Entry Points"
.SH NAME
power \- power a device attached to the system
.SH SYNOPSIS
.LP
.nf
#include <sys/ddi.h>
#include <sys/sunddi.h>

\fBint prefix\fR\fBpower\fR(\fBdev_info_t\fR \fI*dip\fR, \fBint\fR \fIcomponent\fR, \fBint\fR \fIlevel\fR);
.fi

.SH INTERFACE LEVEL
.sp
.LP
Solaris DDI specific (Solaris DDI). This entry point is required. If the driver writer does not supply this entry point, the value \fBNULL\fR must be used in the \fBcb_ops\fR(9S) structure instead.
.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fIdip\fR\fR
.ad
.RS 13n
.rt  
Pointer to the device's \fBdev_info\fR structure.
.RE

.sp
.ne 2
.mk
.na
\fB\fIcomponent\fR\fR
.ad
.RS 13n
.rt  
Component of the driver to be managed.
.RE

.sp
.ne 2
.mk
.na
\fB\fIlevel\fR\fR
.ad
.RS 13n
.rt  
Desired component power level.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBpower\fR(9E) function is the device-specific Power Management entry point. This function is called when the system wants the driver to set the power level of \fIcomponent\fR to \fIlevel\fR. 
.sp
.LP
The \fIlevel\fR argument is the driver-defined power level to which the component needs to be set. Except for power level \fB0\fR, which is interpreted by the framework to mean "powered off," the interpretation of \fIlevel\fR is entirely up to the driver.
.sp
.LP
The \fIcomponent\fR argument is the component of the device to be power-managed. The interpretation of \fIcomponent\fR is entirely up to the driver.
.sp
.LP
When a requested power transition would cause the device to lose state, the driver must save the state of the device in memory. When a requested power transition requires state to be restored, the driver must restore that state.
.sp
.LP
If a requested power transition for one component requires another component to change power state before it can be completed, the driver must call \fBpm_raise_power\fR(9F) to get the other component changed, and the \fBpower\fR(9E) entry point must support being re-entered.
.sp
.LP
If the system requests an inappropriate power transition for the device (for example, a request to power down a device which has just become busy), then the power level should not be changed and power should return \fBDDI_FAILURE\fR.
.SH RETURN VALUES
.sp
.LP
The \fBpower()\fR function returns:
.sp
.ne 2
.mk
.na
\fB\fBDDI_SUCCESS\fR\fR
.ad
.RS 15n
.rt  
Successfully set the power to the requested \fIlevel\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fBDDI_FAILURE\fR\fR
.ad
.RS 15n
.rt  
Failed to set the power to the requested \fIlevel\fR.
.RE

.SH CONTEXT
.sp
.LP
The \fBpower()\fR function is called from user or kernel context only.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted 
.TE

.SH SEE ALSO
.sp
.LP
\fBattach\fR(9E), \fBdetach\fR(9E), \fBpm_busy_component\fR(9F), \fBpm_idle_component\fR(9F), \fBpm_raise_power\fR(9F), \fBcb_ops\fR(9S)
.sp
.LP
\fIWriting Device Drivers for Oracle Solaris 11.2\fR
.sp
.LP
\fIUsing Power Management\fR