share/man/man9e/power.9e

   1 '\" te
   2 .\"  Copyright (c) 2003, 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 POWER 9E "Sep 16, 2016"
   7 .SH NAME
   8 power \- power a device attached to the system
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/ddi.h>
  13 #include <sys/sunddi.h>
  14
  15
  16
  17 \fBint prefix\fR\fBpower\fR(\fBdev_info_t\fR \fI*dip\fR, \fBint\fR \fIcomponent\fR, \fBint\fR \fIlevel\fR);
  18 .fi
  19
  20 .SH INTERFACE LEVEL
  21 .LP
  22 Solaris DDI specific (Solaris DDI). This entry point is required. If the driver
  23 writer does not supply this entry point, the value \fBNULL\fR must be used in
  24 the \fBdev_ops\fR(9S) structure instead.
  25 .SH PARAMETERS
  26 .ne 2
  27 .na
  28 \fB\fIdip\fR\fR
  29 .ad
  30 .RS 13n
  31 Pointer to the device's \fBdev_info\fR structure.
  32 .RE
  33
  34 .sp
  35 .ne 2
  36 .na
  37 \fB\fIcomponent\fR\fR
  38 .ad
  39 .RS 13n
  40 Component of the driver to be managed.
  41 .RE
  42
  43 .sp
  44 .ne 2
  45 .na
  46 \fB\fIlevel\fR\fR
  47 .ad
  48 .RS 13n
  49 Desired component power level.
  50 .RE
  51
  52 .SH DESCRIPTION
  53 .LP
  54 The \fBpower\fR(9E) function is the device-specific Power Management entry
  55 point. This function is called when the system wants the driver to set the
  56 power level of \fIcomponent\fR to \fIlevel\fR.
  57 .sp
  58 .LP
  59 The \fIlevel\fR argument is the driver-defined power level to which the
  60 component needs to be set. Except for power level \fB0\fR, which is interpreted
  61 by the framework to mean "powered off," the interpretation of \fIlevel\fR is
  62 entirely up to the driver.
  63 .sp
  64 .LP
  65 The \fIcomponent\fR argument is the component of the device to be
  66 power-managed. The interpretation of \fIcomponent\fR is entirely up to the
  67 driver.
  68 .sp
  69 .LP
  70 When a requested power transition would cause the device to lose state, the
  71 driver must save the state of the device in memory. When a requested power
  72 transition requires state to be restored, the driver must restore that state.
  73 .sp
  74 .LP
  75 If a requested power transition for one component requires another component to
  76 change power state before it can be completed, the driver must call
  77 \fBpm_raise_power\fR(9F) to get the other component changed, and the
  78 \fBpower\fR(9E) entry point must support being re-entered.
  79 .sp
  80 .LP
  81 If the system requests an inappropriate power transition for the device (for
  82 example, a request to power down a device which has just become busy), then the
  83 power level should not be changed and power should return \fBDDI_FAILURE\fR.
  84 .SH RETURN VALUES
  85 .LP
  86 The \fBpower()\fR function returns:
  87 .sp
  88 .ne 2
  89 .na
  90 \fB\fBDDI_SUCCESS\fR\fR
  91 .ad
  92 .RS 15n
  93 Successfully set the power to the requested \fIlevel\fR.
  94 .RE
  95
  96 .sp
  97 .ne 2
  98 .na
  99 \fB\fBDDI_FAILURE\fR\fR
 100 .ad
 101 .RS 15n
 102 Failed to set the power to the requested \fIlevel\fR.
 103 .RE
 104
 105 .SH CONTEXT
 106 .LP
 107 The \fBpower()\fR function is called from user or kernel context only.
 108 .SH ATTRIBUTES
 109 .LP
 110 See \fBattributes\fR(5) for descriptions of the following attributes:
 111 .sp
 112
 113 .sp
 114 .TS
 115 box;
 116 c | c
 117 l | l .
 118 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 119 _
 120 Interface stability     Committed
 121 .TE
 122
 123 .SH SEE ALSO
 124 .LP
 125 \fBattach\fR(9E), \fBdetach\fR(9E), \fBpm_busy_component\fR(9F),
 126 \fBpm_idle_component\fR(9F), \fBpm_raise_power\fR(9F), \fBdev_ops\fR(9S)
 127 .sp
 128 .LP
 129 \fIWriting Device Drivers\fR
 130 .sp
 131 .LP
 132 \fIUsing Power Management\fR