1c10c16deSRichard Lowe.\" Copyright (c) 2006 Sun Microsystems, Inc., All Rights Reserved
2b89e420aSGarrett D'Amore.\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
33385b472SRobert Mustacchi.\" Copyright (c) 2017, Joyent, Inc.
4c10c16deSRichard Lowe.\" 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.
5c10c16deSRichard Lowe.\" 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.
6c10c16deSRichard Lowe.\" 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]
7*c77843b0SRobert Mustacchi.Dd December 11, 2022
83385b472SRobert Mustacchi.Dt SCSI_HBA_ATTACH_SETUP 9F
93385b472SRobert Mustacchi.Os
103385b472SRobert Mustacchi.Sh NAME
113385b472SRobert Mustacchi.Nm scsi_hba_attach_setup ,
123385b472SRobert Mustacchi.Nm scsi_hba_detach
133385b472SRobert Mustacchi.Nd SCSI HBA attach and detach routines
143385b472SRobert Mustacchi.Sh SYNOPSIS
153385b472SRobert Mustacchi.In sys/scsi/scsi.h
163385b472SRobert Mustacchi.Ft int
173385b472SRobert Mustacchi.Fo scsi_hba_attach_setup
183385b472SRobert Mustacchi.Fa "dev_info_t *dip"
193385b472SRobert Mustacchi.Fa "ddi_dma_attr_t *hba_dma_attr"
203385b472SRobert Mustacchi.Fa "scsi_hba_tran_t *hba_tran"
213385b472SRobert Mustacchi.Fa "int hba_flags"
223385b472SRobert Mustacchi.Fc
233385b472SRobert Mustacchi.Ft int
243385b472SRobert Mustacchi.Fo scsi_hba_detach
253385b472SRobert Mustacchi.Fa "dev_info_t *dip"
263385b472SRobert Mustacchi.Fc
273385b472SRobert Mustacchi.Sh INTERFACE LEVEL
283385b472SRobert Mustacchiillumos architecture specific (illumos DDI).
293385b472SRobert Mustacchi.Sh PARAMETERS
303385b472SRobert Mustacchi.Bl -tag -width Fa
313385b472SRobert Mustacchi.It Fa dip
323385b472SRobert MustacchiPointer to the
333385b472SRobert Mustacchi.Vt dev_info_t
343385b472SRobert Mustacchistructure that refers to the instance of the HBA device.
353385b472SRobert Mustacchi.It Fa hba_tran
363385b472SRobert MustacchiPointer to a
373385b472SRobert Mustacchi.Xr scsi_hba_tran 9S
383385b472SRobert Mustacchistructure.
393385b472SRobert Mustacchi.It Fa hba_flags
403385b472SRobert MustacchiFlag modifiers.
413385b472SRobert MustacchiThe defined flag values are
423385b472SRobert Mustacchi.Dv SCSI_HBA_TRAN_CLONE ,
433385b472SRobert Mustacchi.Dv SCSI_HBA_TRAN_SCB ,
443385b472SRobert Mustacchi.Dv SCSI_HBA_TRAN_CDB ,
453385b472SRobert Mustacchi.Dv SCSI_HBA_HBA ,
463385b472SRobert Mustacchiand
473385b472SRobert Mustacchi.Dv SCSI_HBA_ADDR_COMPLEX .
483385b472SRobert Mustacchi.It Fa hba_dma_attr
493385b472SRobert MustacchiPointer to a
503385b472SRobert Mustacchi.Xr ddi_dma_attr 9S
513385b472SRobert Mustacchistructure.
523385b472SRobert Mustacchi.El
533385b472SRobert Mustacchi.Sh DESCRIPTION
543385b472SRobert Mustacchi.Ss Fn scsi_hba_attach_setup
553385b472SRobert MustacchiThe
563385b472SRobert Mustacchi.Fn scsi_hba_attach_setup
573385b472SRobert Mustacchifunction registers the
583385b472SRobert Mustacchi.Fa hba_dma_attr
593385b472SRobert MustacchiDMA attributes and the
603385b472SRobert Mustacchi.Fa hba_tran
613385b472SRobert Mustacchitransport vectors of each instance of the HBA device defined by
623385b472SRobert Mustacchi.Fa dip .
633385b472SRobert MustacchiThe HBA driver can pass different DMA attributes and the transport
643385b472SRobert Mustacchivectors for each instance of the device to support any constraints
653385b472SRobert Mustacchiimposed by the  HBA itself.
663385b472SRobert Mustacchi.Pp
673385b472SRobert MustacchiThe
683385b472SRobert Mustacchi.Fn scsi_hba_attach_setup
693385b472SRobert Mustacchifunction uses the
70*c77843b0SRobert Mustacchi.Vt devo_bus_ops
713385b472SRobert Mustacchifield in the
723385b472SRobert Mustacchi.Xr dev_ops 9S
733385b472SRobert Mustacchistructure.
743385b472SRobert MustacchiThe HBA driver should initialize this field to
753385b472SRobert Mustacchi.Dv NULL
763385b472SRobert Mustacchibefore calling
773385b472SRobert Mustacchi.Fn scsi_hba_attach_setup .
783385b472SRobert Mustacchi.Pp
793385b472SRobert MustacchiIf
803385b472SRobert Mustacchi.Dv SCSI_HBA_TRAN_CLONE
813385b472SRobert Mustacchiis requested in
823385b472SRobert Mustacchi.Fa hba_flags ,
833385b472SRobert Mustacchithe
84779e7536SJason King.Fa hba_tran
853385b472SRobert Mustacchistructure is cloned once for each target that is attached to the
863385b472SRobert MustacchiHBA.
873385b472SRobert MustacchiThe use of this flag is deprecated, drivers should instead use
883385b472SRobert Mustacchi.Dv SCSI_HBA_ADDR_COMPLEX
893385b472SRobert Mustacchifor per-target data.
903385b472SRobert Mustacchi.Pp
913385b472SRobert MustacchiThe structure is cloned before the
923385b472SRobert Mustacchi.Xr tran_tgt_init 9E
933385b472SRobert Mustacchientry point is called to initialize a target.
943385b472SRobert MustacchiAt all subsequent HBA
953385b472SRobert Mustacchientry points, including
963385b472SRobert Mustacchi.Xr tran_tgt_init 9E ,
973385b472SRobert Mustacchithe
983385b472SRobert Mustacchi.Vt scsi_hba_tran_t
993385b472SRobert Mustacchistructure passed as an
1003385b472SRobert Mustacchiargument or found in a
1013385b472SRobert Mustacchi.Xr scsi_address 9S
1023385b472SRobert Mustacchistructure is the cloned
1033385b472SRobert Mustacchi.Vt scsi_hba_tran_t
1043385b472SRobert Mustacchistructure, which allows the HBA to use the
1053385b472SRobert Mustacchi.Vt tran_tgt_private
1063385b472SRobert Mustacchifield in the
1073385b472SRobert Mustacchi.Vt scsi_hba_tran_t
1083385b472SRobert Mustacchistructure to point to per-target data.
1093385b472SRobert MustacchiThe HBA should free only the same
1103385b472SRobert Mustacchi.Vt scsi_hba_tran_t
1113385b472SRobert Mustacchistructure allocated when the HBA detaches.
1123385b472SRobert MustacchiAll cloned
1133385b472SRobert Mustacchi.Vt scsi_hba_tran_t
114c10c16deSRichard Lowestructures that are allocated by the system are freed by the system.
1153385b472SRobert Mustacchi.Pp
1163385b472SRobert MustacchiThe flags
1173385b472SRobert Mustacchi.Dv SCSI_HBA_TRAN_CDB
1183385b472SRobert Mustacchiand
1193385b472SRobert Mustacchi.Dv SCSI_HBA_TRAN_SCB
1203385b472SRobert Mustacchiare only valid
1213385b472SRobert Mustacchiwhen
1223385b472SRobert Mustacchi.Fn tran_setup_pkt
1233385b472SRobert Mustacchiis used.
1243385b472SRobert MustacchiSee
1253385b472SRobert Mustacchi.Xr tran_setup_pkt 9E
1263385b472SRobert Mustacchifor information on using these flags.
1273385b472SRobert Mustacchi.Pp
1283385b472SRobert MustacchiThe flag
1293385b472SRobert Mustacchi.Dv SCSI_HBA_ADDR_COMPLEX
1303385b472SRobert Mustacchiindicates to the system that this device handles more complex SCSI
1313385b472SRobert Mustacchitopologies, such as SAS.
1323385b472SRobert MustacchiWhen this flag is set, the
1333385b472SRobert Mustacchi.Xr scsi_address 9S
1343385b472SRobert Mustacchistructure becomes opaque.
1353385b472SRobert MustacchiThe driver must not check it for the traditional target and LUN values.
1363385b472SRobert MustacchiInstead, a target and LUN are identified by a unit address which can be
1373385b472SRobert Mustacchiretrieved using the
1383385b472SRobert Mustacchi.Xr scsi_device_unit_address 9F
1393385b472SRobert Mustacchifunction.
1403385b472SRobert Mustacchi.Pp
1413385b472SRobert MustacchiWhen operating with the flag
14241de07bdSRobert Mustacchi.Dv SCSI_HBA_ADDR_COMPLEX ,
1433385b472SRobert Mustacchithe driver may associate private data with the
1443385b472SRobert Mustacchi.Xr scsi_device 9S
1453385b472SRobert Mustacchistructure.
1463385b472SRobert MustacchiThis obviates the need and complexity around using
1473385b472SRobert Mustacchi.Dv SCSI_HBA_TRAN_CLONE
1483385b472SRobert Mustacchiflag.
1493385b472SRobert MustacchiTo get and set private data, the driver can use the
1503385b472SRobert Mustacchi.Xr scsi_device_hba_private_get 9F
1513385b472SRobert Mustacchiand
1523385b472SRobert Mustacchi.Xr scsi_device_hba_private_set 9F
1533385b472SRobert Mustacchifunctions.
1543385b472SRobert MustacchiNotably, the
1553385b472SRobert Mustacchi.Fn scsi_device_hba_private_set
1563385b472SRobert Mustacchifunction should be used during the
1573385b472SRobert Mustacchi.Xr tran_tgt_init 9E
1583385b472SRobert Mustacchientry point.
1593385b472SRobert MustacchiThe
1603385b472SRobert Mustacchi.Fn scsi_device_hba_private_get
1613385b472SRobert Mustacchifunction should then be used during other SCSI HBA entry points.
1623385b472SRobert MustacchiIn addition, the
1633385b472SRobert Mustacchi.Xr scsi_address_device 9F
1643385b472SRobert Mustacchifunction now becomes available to the driver to map between the
1653385b472SRobert Mustacchi.Xr scsi_device 9S
1663385b472SRobert Mustacchiand
1673385b472SRobert Mustacchi.Xr scsi_address 9S
1683385b472SRobert Mustacchistructures.
1693385b472SRobert Mustacchi.Pp
1703385b472SRobert MustacchiThe
1713385b472SRobert Mustacchi.Dv SCSI_HBA_HBA
1723385b472SRobert Mustacchiflag indicates that the HBA driver will only enumerate direct children
1733385b472SRobert Mustacchiwhich are
1743385b472SRobert Mustacchi.Xr iport 9
1753385b472SRobert Mustacchiinstances.
1763385b472SRobert MustacchiThis mode of operation is recommended for device drivers as
1773385b472SRobert Mustacchiit simplifies the management of discovered devices.
1783385b472SRobert MustacchiThis flag is often used in tandem with
1793385b472SRobert Mustacchi.Dv SCSI_HBA_ADDR_COMPLEX
1803385b472SRobert Mustacchiand is recommended for all new SAS-based HBA drivers.
1813385b472SRobert MustacchiFor more information on the management of iports and the use of target
1823385b472SRobert Mustacchimaps, please see
1833385b472SRobert Mustacchi.Xr iport 9 .
1843385b472SRobert Mustacchi.Pp
1853385b472SRobert MustacchiThe
1863385b472SRobert Mustacchi.Fn scsi_hba_attach_setup
1873385b472SRobert Mustacchifunction attaches a number of integer-valued properties to
1883385b472SRobert Mustacchi.Fa dip ,
1893385b472SRobert Mustacchiunless properties of the same name are already attached to the node.
1903385b472SRobert MustacchiAn HBA driver should retrieve these configuration parameters via
1913385b472SRobert Mustacchi.Xr ddi_prop_get_int 9F ,
1923385b472SRobert Mustacchiand respect any settings for features provided the HBA.
1933385b472SRobert Mustacchi.Bl -tag -width Sy
1943385b472SRobert Mustacchi.It Sy scsi-options
1953385b472SRobert Mustacchi.Sy Optional SCSI configuration bits .
1963385b472SRobert MustacchiThe following values may be bitwise-inclusive-ORed together.
1973385b472SRobert Mustacchi.Bl -tag -width Dv
1983385b472SRobert Mustacchi.It Dv SCSI_OPTIONS_DR
199c10c16deSRichard LoweIf not set, the HBA should not grant Disconnect privileges to target devices.
2003385b472SRobert Mustacchi.It Dv SCSI_OPTIONS_TAG
201c10c16deSRichard LoweIf not set, the HBA should not operate in Command Tagged Queueing mode.
2023385b472SRobert Mustacchi.It Dv SCSI_OPTIONS_PARITY
203c10c16deSRichard LoweIf not set, the HBA should not operate in parity mode.
2043385b472SRobert Mustacchi.It Dv SCSI_OPTIONS_QAS
205c10c16deSRichard LoweIf not set, the HBA should not make use of the Quick Arbitration Select
2063385b472SRobert Mustacchifeature.
2073385b472SRobert MustacchiConsult your hardware documentation to determine whether your
208c10c16deSRichard Lowemachine supports QAS.
2093385b472SRobert Mustacchi.It Dv SCSI_OPTIONS_FAST
210c10c16deSRichard LoweIf not set, the HBA should not operate the bus in FAST SCSI mode.
2113385b472SRobert Mustacchi.It Dv SCSI_OPTIONS_FAST20
212c10c16deSRichard LoweIf not set, the HBA should not operate the bus in FAST20 SCSI mode.
2133385b472SRobert Mustacchi.It Dv SCSI_OPTIONS_FAST40
214c10c16deSRichard LoweIf not set, the HBA should not operate the bus in FAST40 SCSI mode.
2153385b472SRobert Mustacchi.It Dv SCSI_OPTIONS_FAST80
216c10c16deSRichard LoweIf not set, the HBA should not operate the bus in FAST80 SCSI mode.
2173385b472SRobert Mustacchi.It Dv SCSI_OPTIONS_FAST160
218c10c16deSRichard LoweIf not set, the HBA should not operate the bus in FAST160 SCSI mode.
2193385b472SRobert Mustacchi.It Dv SCSI_OPTIONS_FAST320
220c10c16deSRichard LoweIf not set, the HBA should not operate the bus in FAST320 SCSI mode.
2213385b472SRobert Mustacchi.It Dv SCSI_OPTIONS_WIDE
222c10c16deSRichard LoweIf not set, the HBA should not operate the bus in WIDE SCSI mode.
2233385b472SRobert Mustacchi.It Dv SCSI_OPTIONS_SYNC
224c10c16deSRichard LoweIf not set, the HBA should not operate the bus in synchronous transfer mode.
2253385b472SRobert Mustacchi.El
2263385b472SRobert Mustacchi.It Sy scsi-reset-delay
227c10c16deSRichard LoweSCSI bus or device reset recovery time, in milliseconds.
2283385b472SRobert Mustacchi.It Sy scsi-selection-timeout
2293385b472SRobert MustacchiDefault SCSI selection phase timeout value, in milliseconds.
2303385b472SRobert MustacchiPlease refer to individual HBA man pages for any HBA-specific
2313385b472SRobert Mustacchiinformation
2323385b472SRobert Mustacchi.El
2333385b472SRobert Mustacchi.Ss Fn scsi_hba_detach
2343385b472SRobert MustacchiThe
2353385b472SRobert Mustacchi.Fn scsi_hba_detach
2363385b472SRobert Mustacchifunction removes the reference to the DMA attributes structure and the
2373385b472SRobert Mustacchitransport vector for the given instance of an HBA driver.
2383385b472SRobert Mustacchi.Sh CONTEXT
2393385b472SRobert MustacchiThe
2403385b472SRobert Mustacchi.Fn scsi_hba_attach_setup
2413385b472SRobert Mustacchifunction should be called from
2423385b472SRobert Mustacchi.Xr attach 9E .
2433385b472SRobert MustacchiThe
2443385b472SRobert Mustacchi.Fn scsi_hba_detach
2453385b472SRobert Mustacchifunction should be called from
2463385b472SRobert Mustacchi.Xr detach 9E .
2473385b472SRobert Mustacchi.Sh RETURN VALUES
2483385b472SRobert MustacchiThe
2493385b472SRobert Mustacchi.Fn scsi_hba_attach_setup
2503385b472SRobert Mustacchiand
2513385b472SRobert Mustacchi.Fn scsi_hba_detach
2523385b472SRobert Mustacchifunctions return
2533385b472SRobert Mustacchi.Dv DDI_SUCCESS
2543385b472SRobert Mustacchiif the function call succeeds, and return
2553385b472SRobert Mustacchi.Dv DDI_FAILURE
2563385b472SRobert Mustacchion failure.
2573385b472SRobert Mustacchi.Sh SEE ALSO
2583385b472SRobert Mustacchi.Xr iport 9 ,
2593385b472SRobert Mustacchi.Xr attach 9E ,
2603385b472SRobert Mustacchi.Xr detach 9E ,
2613385b472SRobert Mustacchi.Xr tran_setup_pkt 9E ,
2623385b472SRobert Mustacchi.Xr tran_tgt_init 9E ,
2633385b472SRobert Mustacchi.Xr ddi_prop_get_int 9F ,
2643385b472SRobert Mustacchi.Xr scsi_address_device 9F ,
2653385b472SRobert Mustacchi.Xr scsi_device_hba_private_get 9F ,
2663385b472SRobert Mustacchi.Xr scsi_device_hba_private_set 9F ,
2673385b472SRobert Mustacchi.Xr scsi_device_unit_address 9F ,
2683385b472SRobert Mustacchi.Xr ddi_dma_attr 9S ,
2693385b472SRobert Mustacchi.Xr dev_ops 9S ,
2703385b472SRobert Mustacchi.Xr scsi_address 9S ,
2713385b472SRobert Mustacchi.Xr scsi_device 9S ,
2723385b472SRobert Mustacchi.Xr scsi_hba_tran 9S
2733385b472SRobert Mustacchi.Pp
2743385b472SRobert Mustacchi.Rs
2753385b472SRobert Mustacchi.%T Writing Device Drivers
2763385b472SRobert Mustacchi.Re
2773385b472SRobert Mustacchi.Sh NOTES
278c10c16deSRichard LoweIt is the HBA driver's responsibility to ensure that no more transport requests
279c10c16deSRichard Lowewill be taken on behalf of any SCSI target device driver after
2803385b472SRobert Mustacchi.Fn scsi_hba_detach
2813385b472SRobert Mustacchiis called.
282