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

'\" te
.\" Copyright (c) 2006 Sun Microsystems, Inc., All Rights Reserved
.\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
.\" 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 "May 24, 2014"
.SH NAME
scsi_hba_attach_setup, 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_detach\fR(\fBdev_info_t *\fR\fIdip\fR);
.fi

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

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

.sp
.ne 2
.na
\fB\fIhba_flags\fR\fR
.ad
.RS 16n
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
.na
\fB\fIhba_options\fR\fR
.ad
.RS 16n
Optional features provided by the HBA driver for future extensions; must be
\fINULL\fR.
.RE

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

.SH DESCRIPTION
.sp
.SS "scsi_hba_attach_setup(\|)"
.sp
.LP
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 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_setup()\fR function uses 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_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_setup()\fR function attaches
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
.na
\fB\fBscsi-options\fR\fR
.ad
.RS 26n
\fBOptional\fR \fBSCSI\fR \fBconfiguration bits\fR
.RE

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

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

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

.sp
.ne 2
.na
\fB\fBSCSI_OPTIONS_QAS\fR\fR
.ad
.RS 26n
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
.na
\fB\fBSCSI_OPTIONS_FAST\fR\fR
.ad
.RS 26n
If not set, the HBA should not operate the bus in FAST SCSI mode.
.RE

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

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

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

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

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

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

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

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

.sp
.ne 2
.na
\fB\fBscsi-selection-timeout\fR\fR
.ad
.RS 26n
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
attributes structure and the transport vector for the given instance of an HBA
driver.
.SH RETURN VALUES
.sp
.LP
The \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_setup()\fR function 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),
\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.