share/man/man9e/attach.9e

   1 '\" te
   2 .\"  Copyright (c) 2004, 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 ATTACH 9E "Jan 7, 2004"
   7 .SH NAME
   8 attach \- Attach a device to the system, or resume it
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/ddi.h>
  13 #include <sys/sunddi.h>
  14
  15
  16
  17 \fBint prefix\fR\fBattach\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_attach_cmd_t\fR \fIcmd\fR);
  18 .fi
  19
  20 .SH INTERFACE LEVEL
  21 .sp
  22 .LP
  23 Solaris DDI specific (Solaris DDI)
  24 .SH PARAMETERS
  25 .sp
  26 .ne 2
  27 .na
  28 \fB\fIdip\fR\fR
  29 .ad
  30 .RS 7n
  31 A pointer to the device's \fBdev_info\fR structure.
  32 .RE
  33
  34 .sp
  35 .ne 2
  36 .na
  37 \fB\fIcmd\fR\fR
  38 .ad
  39 .RS 7n
  40 Attach type. Possible values are \fBDDI_ATTACH\fR and \fBDDI_RESUME\fR. Other
  41 values are reserved. The driver must return \fBDDI_FAILURE\fR if reserved
  42 values are passed to it.
  43 .RE
  44
  45 .SH DESCRIPTION
  46 .sp
  47 .LP
  48 The \fBattach\fR(9E) function is the device-specific initialization entry
  49 point. This entry point is \fBrequired\fR and must be written.
  50 .SS "DDI_ATTACH"
  51 .sp
  52 .LP
  53 The \fBDDI_ATTACH\fR command must be provided in the \fBattach\fR(9E) entry
  54 point. \fBDDI_ATTACH\fR is used to initialize a given device instance. When
  55 \fBattach\fR(9E) is called with \fIcmd\fR set to \fBDDI_ATTACH\fR, all normal
  56 kernel services (such as \fBkmem_alloc\fR(9F)) are available for use by the
  57 driver. Device interrupts are not blocked when attaching a device to the
  58 system.
  59 .sp
  60 .LP
  61 The \fBattach\fR(9E) function is called once for each instance of the device on
  62 the system with \fIcmd\fR set to \fBDDI_ATTACH\fR. Until \fBattach\fR(9E)
  63 succeeds, the only driver entry point which may be called is \fBgetinfo\fR(9E).
  64 See the \fIWriting Device Drivers\fR for more information. The instance number
  65 may be obtained using \fBddi_get_instance\fR(9F).
  66 .sp
  67 .LP
  68 At attach time, all components of a power-manageable device are assumed to be
  69 at unknown levels. Before using the device, the driver needs to bring the
  70 required component(s) to a known power level. The \fBpm_raise_power\fR(9F)
  71 function can be used to set the power level of a component. This function must
  72 not be called before data structures referenced in \fBpower\fR(9E) have been
  73 initialized.
  74 .SS "DDI_RESUME"
  75 .sp
  76 .LP
  77 The \fBattach()\fR function may be called with \fIcmd\fR set to
  78 \fBDDI_RESUME\fR after \fBdetach\fR(9E) has been successfully called with
  79 \fIcmd\fR set to \fBDDI_SUSPEND\fR.
  80 .sp
  81 .LP
  82 When called with \fIcmd\fR set to \fBDDI_RESUME\fR, \fBattach()\fR must restore
  83 the hardware state of a device (power may have been removed from the device),
  84 allow pending requests to continue, and service new requests. In this case, the
  85 driver must not make any assumptions about the state of the hardware, but must
  86 restore the state of the device except for the power level of components.
  87 .sp
  88 .LP
  89 If the device driver uses the automatic device Power Management interfaces
  90 (driver exports the \fBpm-components\fR(9P) property), the Power Management
  91 framework sets its notion of the power level of each component of a device to
  92 \fBunknown\fR while processing a \fBDDI_RESUME\fR command.
  93 .sp
  94 .LP
  95 The driver can deal with components during \fBDDI_RESUME\fR in one of the
  96 following ways:
  97 .RS +4
  98 .TP
  99 1.
 100 If the driver can determine the power level of the component without having
 101 to power it up (for example, by calling \fBddi_peek\fR(9F) or some other
 102 device-specific method) then it should notify the power level to the framework
 103 by calling \fBpm_power_has_changed\fR(9F).
 104 .RE
 105 .RS +4
 106 .TP
 107 2.
 108 The driver must also set its own notion of the power level of the component
 109 to \fBunknown\fR. The system will consider the component idle or busy based on
 110 the most recent call to \fBpm_idle_component\fR(9F) or
 111 \fBpm_busy_component\fR(9F) for that component. If the component is idle for
 112 sufficient time, the framework will call into the driver's \fBpower\fR(9E)
 113 entry point to turn the component off. If the driver needs to access the
 114 device, then it must call \fBpm_raise_power\fR(9F) to bring the component up to
 115 the level needed for the device access to succeed. The driver must honor any
 116 request to set the power level of the component, since it cannot make any
 117 assumption about what power level the component has (or it should have called
 118 \fBpm_power_has_changed\fR(9F) as outlined above). As a special case of this,
 119 the driver may bring the component to a known state because it wants to perform
 120 an operation on the device as part of its \fBDDI_RESUME\fR processing (such as
 121 loading firmware so that it can detect hot-plug events).
 122 .RE
 123 .SH RETURN VALUES
 124 .sp
 125 .LP
 126 The \fBattach()\fR function returns:
 127 .sp
 128 .ne 2
 129 .na
 130 \fB\fBDDI_SUCCESS\fR\fR
 131 .ad
 132 .RS 15n
 133 Successful completion
 134 .RE
 135
 136 .sp
 137 .ne 2
 138 .na
 139 \fB\fBDDI_FAILURE\fR\fR
 140 .ad
 141 .RS 15n
 142 Operation failed
 143 .RE
 144
 145 .SH ATTRIBUTES
 146 .sp
 147 .LP
 148 See \fBattributes\fR(5) for descriptions of the following attributes:
 149 .sp
 150
 151 .sp
 152 .TS
 153 box;
 154 c | c
 155 l | l .
 156 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 157 _
 158 Interface Stability     Committed
 159 .TE
 160
 161 .SH SEE ALSO
 162 .sp
 163 .LP
 164 \fBcpr\fR(7), \fBpm\fR(7D), \fBpm\fR(9P), \fBpm-components\fR(9P),
 165 \fBdetach\fR(9E), \fBgetinfo\fR(9E), \fBidentify\fR(9E), \fBopen\fR(9E),
 166 \fBpower\fR(9E), \fBprobe\fR(9E), \fBddi_add_intr\fR(9F),
 167 \fBddi_create_minor_node\fR(9F), \fBddi_get_instance\fR(9F),
 168 \fBddi_map_regs\fR(9F), \fBkmem_alloc\fR(9F), \fBpm_raise_power\fR(9F)
 169 .sp
 170 .LP
 171 \fIWriting Device Drivers\fR