man/man9e/power.9e

         te
 Copyright (c) 2003, 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]
 power 9E "12 Dec 2003" "SunOS 5.11" "Driver Entry Points"
 NAME
power - power a device attached to the system
 SYNOPSIS

#include <sys/ddi.h>
#include <sys/sunddi.h>


int prefixpower(dev_info_t *dip, int component, int level);


 INTERFACE LEVEL

Solaris DDI specific (Solaris DDI). This entry point is required. If the driver
writer does not supply this entry point, the value NULL must be used in
the cb_ops(9S) structure instead.
 PARAMETERS

dip

Pointer to the device's dev_info structure.


component

Component of the driver to be managed.


level

Desired component power level.


 DESCRIPTION

The power(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 component to level.

The level argument is the driver-defined power level to which the
component needs to be set. Except for power level 0, which is interpreted
by the framework to mean "powered off," the interpretation of level is
entirely up to the driver.

The component argument is the component of the device to be
power-managed. The interpretation of component is entirely up to the
driver.

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.

If a requested power transition for one component requires another component to
change power state before it can be completed, the driver must call
pm_raise_power(9F) to get the other component changed, and the
power(9E) entry point must support being re-entered.

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 DDI_FAILURE.
 RETURN VALUES

The power() function returns:

DDI_SUCCESS

Successfully set the power to the requested level.


DDI_FAILURE

Failed to set the power to the requested level.


 CONTEXT

The power() function is called from user or kernel context only.
 ATTRIBUTES

See attributes(5) for descriptions of the following attributes:


ATTRIBUTE TYPEATTRIBUTE VALUE
Interface stabilityCommitted


 SEE ALSO

attach(9E), detach(9E), pm_busy_component(9F),
pm_idle_component(9F), pm_raise_power(9F), cb_ops(9S)

Writing Device Drivers

Using Power Management