1 files changed, 180 insertions, 0 deletions
diff --git a/usr/src/man/man9e/attach.9e b/usr/src/man/man9e/attach.9e
new file mode 100644
index 0000000000..b98b9d0379
--- /dev/null
+++ b/usr/src/man/man9e/attach.9e
@@ -0,0 +1,180 @@
+'\" te
+.\"  Copyright (c) 2004, 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 attach 9E "7 Jan 2004" "SunOS 5.11" "Driver Entry Points"
+.SH NAME
+attach \- Attach a device to the system, or resume it
+.SH SYNOPSIS
+.LP
+.nf
+#include <sys/ddi.h>
+#include <sys/sunddi.h>
+
+
+
+\fBint prefix\fR\fBattach\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_attach_cmd_t\fR \fIcmd\fR);
+.fi
+
+.SH INTERFACE LEVEL
+.sp
+.LP
+Solaris DDI specific (Solaris DDI)
+.SH PARAMETERS
+.sp
+.ne 2
+.mk
+.na
+\fB\fIdip\fR\fR
+.ad
+.RS 7n
+.rt  
+A pointer to the device's \fBdev_info\fR structure.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fIcmd\fR\fR
+.ad
+.RS 7n
+.rt  
+Attach type. Possible values are \fBDDI_ATTACH\fR and \fBDDI_RESUME\fR. Other
+values are reserved. The driver must return \fBDDI_FAILURE\fR if reserved
+values are passed to it.
+.RE
+
+.SH DESCRIPTION
+.sp
+.LP
+The \fBattach\fR(9E) function is the device-specific initialization entry
+point. This entry point is \fBrequired\fR and must be written.
+.SS "DDI_ATTACH"
+.sp
+.LP
+The \fBDDI_ATTACH\fR command must be provided in the \fBattach\fR(9E) entry
+point. \fBDDI_ATTACH\fR is used to initialize a given device instance. When
+\fBattach\fR(9E) is called with \fIcmd\fR set to \fBDDI_ATTACH\fR, all normal
+kernel services (such as \fBkmem_alloc\fR(9F)) are available for use by the
+driver. Device interrupts are not blocked when attaching a device to the
+system.
+.sp
+.LP
+The \fBattach\fR(9E) function is called once for each instance of the device on
+the system with \fIcmd\fR set to \fBDDI_ATTACH\fR. Until \fBattach\fR(9E)
+succeeds, the only driver entry point which may be called is \fBgetinfo\fR(9E).
+See the \fIWriting Device Drivers\fR for more information. The instance number
+may be obtained using \fBddi_get_instance\fR(9F).
+.sp
+.LP
+At attach time, all components of a power-manageable device are assumed to be
+at unknown levels. Before using the device, the driver needs to bring the
+required component(s) to a known power level. The \fBpm_raise_power\fR(9F)
+function can be used to set the power level of a component. This function must
+not be called before data structures referenced in \fBpower\fR(9E) have been
+initialized.
+.SS "DDI_RESUME"
+.sp
+.LP
+The \fBattach()\fR function may be called with \fIcmd\fR set to
+\fBDDI_RESUME\fR after \fBdetach\fR(9E) has been successfully called with
+\fIcmd\fR set to \fBDDI_SUSPEND\fR.
+.sp
+.LP
+When called with \fIcmd\fR set to \fBDDI_RESUME\fR, \fBattach()\fR must restore
+the hardware state of a device (power may have been removed from the device),
+allow pending requests to continue, and service new requests. In this case, the
+driver must not make any assumptions about the state of the hardware, but must
+restore the state of the device except for the power level of components.
+.sp
+.LP
+If the device driver uses the automatic device Power Management interfaces
+(driver exports the \fBpm-components\fR(9P) property), the Power Management
+framework sets its notion of the power level of each component of a device to
+\fBunknown\fR while processing a \fBDDI_RESUME\fR command.
+.sp
+.LP
+The driver can deal with components during \fBDDI_RESUME\fR in one of the
+following ways:
+.RS +4
+.TP
+1.
+If the driver can determine the power level of the component without having
+to power it up (for example, by calling \fBddi_peek\fR(9F) or some other
+device-specific method) then it should notify the power level to the framework
+by calling \fBpm_power_has_changed\fR(9F).
+.RE
+.RS +4
+.TP
+2.
+The driver must also set its own notion of the power level of the component
+to \fBunknown\fR. The system will consider the component idle or busy based on
+the most recent call to \fBpm_idle_component\fR(9F) or
+\fBpm_busy_component\fR(9F) for that component. If the component is idle for
+sufficient time, the framework will call into the driver's \fBpower\fR(9E)
+entry point to turn the component off. If the driver needs to access the
+device, then it must call \fBpm_raise_power\fR(9F) to bring the component up to
+the level needed for the device access to succeed. The driver must honor any
+request to set the power level of the component, since it cannot make any
+assumption about what power level the component has (or it should have called
+\fBpm_power_has_changed\fR(9F) as outlined above). As a special case of this,
+the driver may bring the component to a known state because it wants to perform
+an operation on the device as part of its \fBDDI_RESUME\fR processing (such as
+loading firmware so that it can detect hot-plug events).
+.RE
+.SH RETURN VALUES
+.sp
+.LP
+The \fBattach()\fR function returns:
+.sp
+.ne 2
+.mk
+.na
+\fB\fBDDI_SUCCESS\fR\fR
+.ad
+.RS 15n
+.rt  
+Successful completion
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fBDDI_FAILURE\fR\fR
+.ad
+.RS 15n
+.rt  
+Operation failed
+.RE
+
+.SH ATTRIBUTES
+.sp
+.LP
+See \fBattributes\fR(5) for descriptions of the following attributes:
+.sp
+
+.sp
+.TS
+tab() box;
+cw(2.75i) |cw(2.75i) 
+lw(2.75i) |lw(2.75i) 
+.
+ATTRIBUTE TYPEATTRIBUTE VALUE
+_
+Interface StabilityCommitted
+.TE
+
+.SH SEE ALSO
+.sp
+.LP
+\fBcpr\fR(7), \fBpm\fR(7D), \fBpm\fR(9P), \fBpm-components\fR(9P),
+\fBdetach\fR(9E), \fBgetinfo\fR(9E), \fBidentify\fR(9E), \fBopen\fR(9E),
+\fBpower\fR(9E), \fBprobe\fR(9E), \fBddi_add_intr\fR(9F),
+\fBddi_create_minor_node\fR(9F), \fBddi_get_instance\fR(9F),
+\fBddi_map_regs\fR(9F), \fBkmem_alloc\fR(9F), \fBpm_raise_power\fR(9F)
+.sp
+.LP
+\fIWriting Device Drivers\fR