usr/src/man/man9f/ddi_removing_power.9f

   1 '\" te
   2 .\" Copyright (c) 2002, 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 DDI_REMOVING_POWER 9F "Mar 14, 2001"
   7 .SH NAME
   8 ddi_removing_power \- check whether \fBDDI_SUSPEND\fR might result in power
   9 being removed from a device
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/ddi.h>
  14 #include <sys/sunddi.h>
  15
  16
  17
  18 \fBint\fR \fBddi_removing_power\fR(\fBdev_info_t\fR \fI*dip\fR);
  19 .fi
  20
  21 .SH INTERFACE LEVEL
  22 .sp
  23 .LP
  24 Solaris DDI specific (Solaris DDI)
  25 .SH DESCRIPTION
  26 .sp
  27 .LP
  28 The \fBddi_removing_power()\fR function indicates whether a currently pending
  29 call into a driver's \fBdetach\fR(9E) entry point with a command of
  30 \fBDDI_SUSPEND\fR is likely to result in power being removed from the device.
  31 .sp
  32 .LP
  33 \fBddi_removing_power()\fR can return true and power still not be removed from
  34 the device due to a failure to suspend and power off the system.
  35 .SH PARAMETERS
  36 .sp
  37 .LP
  38 The \fBddi_removing_power()\fR function supports the following parameter:
  39 .sp
  40 .ne 2
  41 .na
  42 \fB\fIdip\fR\fR
  43 .ad
  44 .RS 7n
  45 pointer to the device's \fBdev_info\fR structure
  46 .RE
  47
  48 .SH RETURN VALUES
  49 .sp
  50 .LP
  51 The \fBddi_removing_power()\fR function returns:
  52 .sp
  53 .ne 2
  54 .na
  55 \fB\fB1\fR\fR
  56 .ad
  57 .RS 5n
  58 Power might be removed by the framework as a result of the pending
  59 \fBDDI_SUSPEND\fR call.
  60 .RE
  61
  62 .sp
  63 .ne 2
  64 .na
  65 \fB\fB0\fR\fR
  66 .ad
  67 .RS 5n
  68 Power will not be removed by the framework as a result of the pending
  69 \fBDDI_SUSPEND\fR call.
  70 .RE
  71
  72 .SH EXAMPLES
  73 .LP
  74 \fBExample 1 \fRProtecting a Tape from Abrupt Power Removal
  75 .sp
  76 .LP
  77 A tape driver that has hardware that would damage the tape if power is removed
  78 might include this code in its \fBdetach\fR(9E) code:
  79
  80 .sp
  81 .in +2
  82 .nf
  83 int
  84      xxdetach(dev_info_t *dip, ddi_detach_cmd_t cmd)
  85      {
  86
  87      ...
  88           case DDI_SUSPEND:
  89           /*
  90            * We do not allow DDI_SUSPEND if power will be removed and
  91            * we have a device that damages tape when power is removed
  92            * We do support DDI_SUSPEND for Device Reconfiguration,
  93            * however.
  94            */
  95              if (ddi_removing_power(dip) && xxdamages_tape(dip))
  96                 return (DDI_FAILURE);
  97           ...
  98 .fi
  99 .in -2
 100
 101 .SH ATTRIBUTES
 102 .sp
 103 .LP
 104 See \fBattributes\fR(5) for descriptions of the following attributes:
 105 .sp
 106
 107 .sp
 108 .TS
 109 box;
 110 c | c
 111 l | l .
 112 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 113 _
 114 Interface Stability     Committed
 115 .TE
 116
 117 .SH SEE ALSO
 118 .sp
 119 .LP
 120 \fBattributes\fR(5), \fBcpr\fR(7), \fBattach\fR(9E), \fBdetach\fR(9E)
 121 .sp
 122 .LP
 123 \fIWriting Device Drivers\fR