'\" te
.\" Copyright (c) 2006 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 scsi_hba_attach_setup 9F "30 May 2006" "SunOS 5.11" "Kernel Functions for Drivers"
.SH NAME
scsi_hba_attach_setup, scsi_hba_attach, scsi_hba_detach \- SCSI HBA attach and
detach routines
.SH SYNOPSIS
.LP
.nf
#include <sys/scsi/scsi.h>



\fBint\fR \fBscsi_hba_attach_setup\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_dma_attr_t *\fR\fIhba_dma_attr\fR,
     \fBscsi_hba_tran_t *\fR\fIhba_tran\fR, \fBint\fR \fIhba_flags\fR);
.fi

.LP
.nf
\fBint\fR \fBscsi_hba_attach\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_dma_lim_t *\fR\fIhba_lim\fR, 
     \fBscsi_hba_tran_t *\fR\fIhba_tran\fR, \fBint\fR \fIhba_flags\fR, \fBvoid *\fR\fIhba_options\fR);
.fi

.LP
.nf
\fBint\fR \fBscsi_hba_detach\fR(\fBdev_info_t *\fR\fIdip\fR);
.fi

.SH INTERFACE LEVEL
.sp
.LP
Solaris architecture specific (Solaris DDI).
.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fIdip\fR\fR
.ad
.RS 16n
.rt  
Pointer to the \fBdev_info_t\fR structure that refers to the instance of the
HBA device.
.RE

.sp
.ne 2
.mk
.na
\fB\fIhba_lim\fR\fR
.ad
.RS 16n
.rt  
Pointer to a \fBddi_dma_lim\fR(9S) structure.
.RE

.sp
.ne 2
.mk
.na
\fB\fIhba_tran\fR\fR
.ad
.RS 16n
.rt  
Pointer to a \fBscsi_hba_tran\fR(9S) structure.
.RE

.sp
.ne 2
.mk
.na
\fB\fIhba_flags\fR\fR
.ad
.RS 16n
.rt  
Flag modifiers. The defined flag values are \fBSCSI_HBA_TRAN_CLONE\fR,
\fBSCSI_HBA_TRAN_SCB\fR, and \fBSCSI_HBA_TRAN_CDB\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fIhba_options\fR\fR
.ad
.RS 16n
.rt  
Optional features provided by the HBA driver for future extensions; must be
\fINULL\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fIhba_dma_attr\fR\fR
.ad
.RS 16n
.rt  
Pointer to a \fBddi_dma_attr\fR(9S) structure.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBscsi_hba_attach_setup()\fR function is the recommended interface over
the \fBscsi_hba_attach()\fR function.
.SS "scsi_hba_attach_setup(\|) scsi_hba_attach(\|)"
.sp
.LP
The \fBscsi_hba_attach()\fR function registers the \fIhba_lim\fR DMA limits and
the \fIhba_tran\fR transport vectors of each instance of the HBA device defined
by \fIdip\fR. The \fBscsi_hba_attach_setup()\fR function registers the
\fIhba_dma_attr\fR DMA attributes and the \fIhba_tran\fR transport vectors of
each instance of the HBA device defined by \fIdip\fR. The HBA driver can pass
different DMA limits or DMA attributes and the transport vectors for each
instance of the device to support any constraints imposed by the  HBA itself.
.sp
.LP
The \fBscsi_hba_attach()\fR and \fBscsi_hba_attach_setup()\fR functions use the
\fBdev_bus_ops\fR field in the \fBdev_ops\fR(9S) structure. The HBA driver
should initialize this field to \fINULL\fR before calling
\fBscsi_hba_attach()\fR or \fBscsi_hba_attach_setup()\fR.
.sp
.LP
If \fBSCSI_HBA_TRAN_CLONE\fR is requested in \fIhba_flags\fR, the
\fBhba_tran\fR structure is cloned once for each target that is attached to the
HBA. The structure is cloned before the \fBtran_tgt_init\fR(9E) entry point is
called to initialize a target. At all subsequent HBA entry points, including
\fBtran_tgt_init\fR(9E), the \fBscsi_hba_tran_t\fR structure passed as an
argument or found in a \fBscsi_address\fR structure is the cloned
\fBscsi_hba_tran_t\fR structure,which allows the HBA to use the
\fBtran_tgt_private\fR field in the \fBscsi_hba_tran_t\fR structure to point to
per-target data. The HBA should free only the same \fBscsi_hba_tran_t\fR
structure allocated when the HBA detaches. All cloned \fBscsi_hba_tran_t\fR
structures that are allocated by the system are freed by the system.
.sp
.LP
The flags \fBSCSI_HBA_TRAN_CDB\fR and \fBSCSI_HBA_TRAN_SCB\fR are only valid
when \fBtran_setup_pkt()\fR is used. See \fBtran_setup_pkt\fR(9E) for
information on using these flags.
.sp
.LP
The \fBscsi_hba_attach()\fR and \fBscsi_hba_attach_setup()\fR functions attach
a number of integer-valued properties to \fIdip\fR, unless properties of the
same name are already attached to the node. An HBA driver should retrieve these
configuration parameters via \fBddi_prop_get_int\fR(9F), and respect any
settings for features provided the HBA.
.sp
.ne 2
.mk
.na
\fB\fBscsi-options\fR\fR
.ad
.RS 26n
.rt  
\fBOptional\fR \fBSCSI\fR \fBconfiguration bits\fR
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCSI_OPTIONS_DR\fR\fR
.ad
.RS 26n
.rt  
If not set, the HBA should not grant Disconnect privileges to target devices.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCSI_OPTIONS_TAG\fR\fR
.ad
.RS 26n
.rt  
If not set, the HBA should not operate in Command Tagged Queueing mode.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCSI_OPTIONS_PARITY\fR\fR
.ad
.RS 26n
.rt  
If not set, the HBA should not operate in parity mode.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCSI_OPTIONS_QAS\fR\fR
.ad
.RS 26n
.rt  
If not set, the HBA should not make use of the Quick Arbitration Select
feature. Consult your Sun hardware documentation to determine whether your
machine supports QAS.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCSI_OPTIONS_FAST\fR\fR
.ad
.RS 26n
.rt  
If not set, the HBA should not operate the bus in FAST SCSI mode.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCSI_OPTIONS_FAST20\fR\fR
.ad
.RS 26n
.rt  
If not set, the HBA should not operate the bus in FAST20 SCSI mode.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCSI_OPTIONS_FAST40\fR\fR
.ad
.RS 26n
.rt  
If not set, the HBA should not operate the bus in FAST40 SCSI mode.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCSI_OPTIONS_FAST80\fR\fR
.ad
.RS 26n
.rt  
If not set, the HBA should not operate the bus in FAST80 SCSI mode.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCSI_OPTIONS_FAST160\fR\fR
.ad
.RS 26n
.rt  
If not set, the HBA should not operate the bus in FAST160 SCSI mode.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCSI_OPTIONS_FAST320\fR\fR
.ad
.RS 26n
.rt  
If not set, the HBA should not operate the bus in FAST320 SCSI mode.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCSI_OPTIONS_WIDE\fR\fR
.ad
.RS 26n
.rt  
If not set, the HBA should not operate the bus in WIDE SCSI mode.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCSI_OPTIONS_SYNC\fR\fR
.ad
.RS 26n
.rt  
If not set, the HBA should not operate the bus in synchronous transfer mode.
.RE

.sp
.ne 2
.mk
.na
\fB\fBscsi-reset-delay\fR\fR
.ad
.RS 26n
.rt  
SCSI bus or device reset recovery time, in milliseconds.
.RE

.sp
.ne 2
.mk
.na
\fB\fBscsi-selection-timeout\fR\fR
.ad
.RS 26n
.rt  
Default SCSI selection phase timeout value, in milliseconds. Please refer to
individual HBA man pages for any HBA-specific information
.RE

.SS "scsi_hba_detach(\|)"
.sp
.LP
The \fBscsi_hba_detach()\fR function removes the reference to the DMA limits or
attributes structure and the transport vector for the given instance of an HBA
driver.
.SH RETURN VALUES
.sp
.LP
The \fBscsi_hba_attach()\fR, \fBscsi_hba_attach_setup()\fR, and
\fBscsi_hba_detach()\fR functions return \fBDDI_SUCCESS\fR if the function call
succeeds, and return \fBDDI_FAILURE\fR on failure.
.SH CONTEXT
.sp
.LP
The \fBscsi_hba_attach()\fR and \fBscsi_hba_attach_setup()\fR functions should
be called from \fBattach\fR(9E). The \fBscsi_hba_detach()\fR function should be
called from \fBdetach\fR(9E).
.SH SEE ALSO
.sp
.LP
\fBattach\fR(9E), \fBdetach\fR(9E), \fBtran_setup_pkt\fR(9E),
\fBtran_tgt_init\fR(9E), \fBddi_prop_get_int\fR(9F), \fBddi_dma_attr\fR(9S),
\fBddi_dma_lim\fR(9S), \fBdev_ops\fR(9S), \fBscsi_address\fR(9S),
\fBscsi_hba_tran\fR(9S)
.sp
.LP
\fIWriting Device Drivers\fR
.SH NOTES
.sp
.LP
It is the HBA driver's responsibility to ensure that no more transport requests
will be taken on behalf of any SCSI target device driver after
\fBscsi_hba_detach()\fR is called.
.sp
.LP
The \fBscsi_hba_attach()\fR function is obsolete and will be discontinued in a
future release. This function is replaced by \fBscsi_hba_attach_setup()\fR.