'\" 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 "May 30, 2006" .SH NAME scsi_hba_attach_setup, scsi_hba_attach, scsi_hba_detach \- SCSI HBA attach and detach routines .SH SYNOPSIS .LP .nf #include \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 .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_lim\fR\fR .ad .RS 16n Pointer to a \fBddi_dma_lim\fR(9S) structure. .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 .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 .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 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.