SCSI_HBA_ATTACH_SETUP(9F) Kernel Functions for Drivers SCSI_HBA_ATTACH_SETUP(9F)

scsi_hba_attach_setup, scsi_hba_detach — SCSI HBA attach and detach routines

#include <sys/scsi/scsi.h>

int
scsi_hba_attach_setup(dev_info_t *dip, ddi_dma_attr_t *hba_dma_attr, scsi_hba_tran_t *hba_tran, int hba_flags);

int
scsi_hba_detach(dev_info_t *dip);

illumos architecture specific (illumos DDI).

dip
Pointer to the dev_info_t structure that refers to the instance of the HBA device.
hba_tran
Pointer to a scsi_hba_tran(9S) structure.
hba_flags
Flag modifiers. The defined flag values are SCSI_HBA_TRAN_CLONE, SCSI_HBA_TRAN_SCB, SCSI_HBA_TRAN_CDB, SCSI_HBA_HBA, and SCSI_HBA_ADDR_COMPLEX.
hba_dma_attr
Pointer to a ddi_dma_attr(9S) structure.

()

The scsi_hba_attach_setup() function registers the hba_dma_attr DMA attributes and the hba_tran transport vectors of each instance of the HBA device defined by dip. 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.

The () function uses the devo_bus_ops field in the dev_ops(9S) structure. The HBA driver should initialize this field to NULL before calling scsi_hba_attach_setup().

If SCSI_HBA_TRAN_CLONE is requested in hba_flags, the hba_tran structure is cloned once for each target that is attached to the HBA. The use of this flag is deprecated, drivers should instead use SCSI_HBA_ADDR_COMPLEX for per-target data.

The structure is cloned before the tran_tgt_init(9E) entry point is called to initialize a target. At all subsequent HBA entry points, including tran_tgt_init(9E), the scsi_hba_tran_t structure passed as an argument or found in a scsi_address(9S) structure is the cloned scsi_hba_tran_t structure, which allows the HBA to use the tran_tgt_private field in the scsi_hba_tran_t structure to point to per-target data. The HBA should free only the same scsi_hba_tran_t structure allocated when the HBA detaches. All cloned scsi_hba_tran_t structures that are allocated by the system are freed by the system.

The flags SCSI_HBA_TRAN_CDB and SCSI_HBA_TRAN_SCB are only valid when () is used. See tran_setup_pkt(9E) for information on using these flags.

The flag SCSI_HBA_ADDR_COMPLEX indicates to the system that this device handles more complex SCSI topologies, such as SAS. When this flag is set, the scsi_address(9S) structure becomes opaque. The driver must not check it for the traditional target and LUN values. Instead, a target and LUN are identified by a unit address which can be retrieved using the scsi_device_unit_address(9F) function.

When operating with the flag SCSI_HBA_ADDR_COMPLEX, the driver may associate private data with the scsi_device(9S) structure. This obviates the need and complexity around using SCSI_HBA_TRAN_CLONE flag. To get and set private data, the driver can use the scsi_device_hba_private_get(9F) and scsi_device_hba_private_set(9F) functions. Notably, the () function should be used during the tran_tgt_init(9E) entry point. The () function should then be used during other SCSI HBA entry points. In addition, the scsi_address_device(9F) function now becomes available to the driver to map between the scsi_device(9S) and scsi_address(9S) structures.

The SCSI_HBA_HBA flag indicates that the HBA driver will only enumerate direct children which are iport(9) instances. This mode of operation is recommended for device drivers as it simplifies the management of discovered devices. This flag is often used in tandem with SCSI_HBA_ADDR_COMPLEX and is recommended for all new SAS-based HBA drivers. For more information on the management of iports and the use of target maps, please see iport(9).

The () function attaches a number of integer-valued properties to dip, unless properties of the same name are already attached to the node. An HBA driver should retrieve these configuration parameters via ddi_prop_get_int(9F), and respect any settings for features provided the HBA.

. The following values may be bitwise-inclusive-ORed together.
If not set, the HBA should not grant Disconnect privileges to target devices.
If not set, the HBA should not operate in Command Tagged Queueing mode.
If not set, the HBA should not operate in parity mode.
If not set, the HBA should not make use of the Quick Arbitration Select feature. Consult your hardware documentation to determine whether your machine supports QAS.
If not set, the HBA should not operate the bus in FAST SCSI mode.
If not set, the HBA should not operate the bus in FAST20 SCSI mode.
If not set, the HBA should not operate the bus in FAST40 SCSI mode.
If not set, the HBA should not operate the bus in FAST80 SCSI mode.
If not set, the HBA should not operate the bus in FAST160 SCSI mode.
If not set, the HBA should not operate the bus in FAST320 SCSI mode.
If not set, the HBA should not operate the bus in WIDE SCSI mode.
If not set, the HBA should not operate the bus in synchronous transfer mode.
SCSI bus or device reset recovery time, in milliseconds.
Default SCSI selection phase timeout value, in milliseconds. Please refer to individual HBA man pages for any HBA-specific information

scsi_hba_detach()

The scsi_hba_detach() function removes the reference to the DMA attributes structure and the transport vector for the given instance of an HBA driver.

The scsi_hba_attach_setup() function should be called from attach(9E). The scsi_hba_detach() function should be called from detach(9E).

The scsi_hba_attach_setup() and scsi_hba_detach() functions return DDI_SUCCESS if the function call succeeds, and return DDI_FAILURE on failure.

iport(9), attach(9E), detach(9E), tran_setup_pkt(9E), tran_tgt_init(9E), ddi_prop_get_int(9F), scsi_address_device(9F), scsi_device_hba_private_get(9F), scsi_device_hba_private_set(9F), scsi_device_unit_address(9F), ddi_dma_attr(9S), dev_ops(9S), scsi_address(9S), scsi_device(9S), scsi_hba_tran(9S)

Writing Device Drivers.

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 () is called.

December 11, 2022 OmniOS