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