'\" 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]
.TH DDI_DEV_IS_NEEDED 9F "Dec 7, 2003"
.SH NAME
ddi_dev_is_needed \- inform the system that a device's component is required
.SH SYNOPSIS
.LP
.nf
#include <sys/ddi.h>
#include <sys/sunddi.h>



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

.SH INTERFACE LEVEL
.sp
.LP
Solaris DDI specific (Solaris DDI)
.SH PARAMETERS
.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
Component of the driver which is needed.
.RE

.sp
.ne 2
.na
\fB\fIlevel\fR\fR
.ad
.RS 13n
Power level at which the component is needed.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBddi_dev_is_needed()\fR function is obsolete and will be removed in a
future release. It is recommended that device drivers use
\fBpm_raise_power\fR(9F) and \fBpm_lower_power\fR(9F).
.sp
.LP
The \fBddi_dev_is_needed()\fR function informs the system that a device
component is needed at the specified power level. The \fIlevel\fR argument must
be non-zero.
.sp
.LP
This function sets a \fIcomponent\fR to the required level and sets all devices
which depend on this to their normal power levels.
.sp
.LP
The state of the device should be examined before each physical access. The
\fBddi_dev_is_needed()\fR function should be called to set a \fIcomponent\fR to
the required power level if the operation to be performed requires the
component to be at a power level other than its current level.
.sp
.LP
The \fBddi_dev_is_needed()\fR function might cause re-entry of the driver.
Deadlock may result if driver locks are held across the call to
\fBddi_dev_is_needed()\fR.
.SH RETURN VALUES
.sp
.LP
The \fBddi_dev_is_needed()\fR function returns:
.sp
.ne 2
.na
\fB\fBDDI_SUCCESS\fR\fR
.ad
.RS 15n
Power successfully set to the requested level.
.RE

.sp
.ne 2
.na
\fB\fBDDI_FAILURE\fR\fR
.ad
.RS 15n
An error occurred.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRdisk driver code
.sp
.LP
A hypothetical disk driver might include this code:

.sp
.in +2
.nf
     static int
xxdisk_spun_down(struct xxstate *xsp)
{
		return (xsp->power_level[DISK_COMPONENT] < POWER_SPUN_UP);
}
static int
xxdisk_strategy(struct buf *bp)
{

\&.\|.\|.

	mutex_enter(&xxstate_lock);
	/*
	* Since we have to drop the mutex, we have to do this in a loop
	* in case we get preempted and the device gets taken away from
	* us again
	*/
	while (device_spun_down(sp)) {
		mutex_exit(&xxstate_lock);
		if (ddi_dev_is_needed(xsp->mydip,
			XXDISK_COMPONENT, XXPOWER_SPUN_UP) != DDI_SUCCESS) {
				bioerror(bp,EIO);
				biodone(bp);
		return (0);
	}
		mutex_enter(&xxstate_lock);
	}
	xsp->device_busy++;
	mutex_exit(&xxstate_lock);

\&.\|.\|.

}
.fi
.in -2

.SH CONTEXT
.sp
.LP
This function can be called from user or kernel context.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Obsolete
.TE

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