Tribblix: manual page: scsi_hba_attach

SCSI_HBA_ATTACH_SETUP(9F) Kernel Functions for Drivers

NAME

scsi_hba_attach_setup, scsi_hba_detach - SCSI HBA attach and detach
routines

SYNOPSIS

#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);

INTERFACE LEVEL

illumos architecture specific (illumos DDI).

PARAMETERS

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.

DESCRIPTION

scsi_hba_attach_setup()
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 scsi_hba_attach_setup() 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
tran_setup_pkt() 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 scsi_device_hba_private_set() function should
be used during the tran_tgt_init(9E) entry point. The
scsi_device_hba_private_get() 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 scsi_hba_attach_setup() 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.

scsi-options
Optional SCSI configuration bits. The following values may be
bitwise-inclusive-ORed together.

SCSI_OPTIONS_DR
If not set, the HBA should not grant Disconnect
privileges to target devices.

SCSI_OPTIONS_TAG
If not set, the HBA should not operate in Command
Tagged Queueing mode.

SCSI_OPTIONS_PARITY
If not set, the HBA should not operate in parity
mode.

SCSI_OPTIONS_QAS
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.

SCSI_OPTIONS_FAST
If not set, the HBA should not operate the bus in
FAST SCSI mode.

SCSI_OPTIONS_FAST20
If not set, the HBA should not operate the bus in
FAST20 SCSI mode.

SCSI_OPTIONS_FAST40
If not set, the HBA should not operate the bus in
FAST40 SCSI mode.

SCSI_OPTIONS_FAST80
If not set, the HBA should not operate the bus in
FAST80 SCSI mode.

SCSI_OPTIONS_FAST160
If not set, the HBA should not operate the bus in
FAST160 SCSI mode.

SCSI_OPTIONS_FAST320
If not set, the HBA should not operate the bus in
FAST320 SCSI mode.

SCSI_OPTIONS_WIDE
If not set, the HBA should not operate the bus in
WIDE SCSI mode.

SCSI_OPTIONS_SYNC
If not set, the HBA should not operate the bus in
synchronous transfer mode.

scsi-reset-delay
SCSI bus or device reset recovery time, in milliseconds.

scsi-selection-timeout
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.

CONTEXT

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

RETURN VALUES

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

NOTES

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

illumos December 11, 2022 illumos