illumos: manual page: scsi_device_hba_private

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

NAME

scsi_address_device, scsi_device_unit_address, scsi_device_hba_private_get,
scsi_device_hba_private_set - SCSI Complex addressing utility functions

SYNOPSIS

#include <sys/scsi/scsi.h>

struct scsi_device *
scsi_address_device(struct scsi_address *sa);

void *
scsi_device_hba_private_get(struct scsi_device *sd);

void
scsi_device_hba_private_set(struct scsi_device *sd, void *data);

char *
scsi_device_unit_address(struct scsi_device *sd);

INTERFACE LEVEL

Evolving - This interface is still evolving in illumos. API and ABI
stability is not guaranteed.

PARAMETERS

sa Pointer to a scsi_address(9S) structure.

sd Pointer to a scsi_device(9S) structure.

data A private value that the driver can get and set.

DESCRIPTION

These functions provide useful services for SCSI HBA drivers that use
complex addressing. In complex addressing mode, the scsi_address(9S)
structure is treated as an opaque structure and is not a simple target and
LUN. To use these functions, the driver must have enabled complex
addressing by passing the SCSI_HBA_ADDR_COMPLEX flag into the hba_flags
argument of the scsi_hba_attach_setup(9F) function. If the
SCSI_HBA_ADDR_COMPLEX flag was not passed, then the driver must not call
the scsi_device_hba_private_get(), scsi_device_hba_private_set(), or
scsi_device_unit_address() functions.

The scsi_address_device() function maps the scsi_address(9S) function back
to its corresponding scsi_device(9S) structure. If the
SCSI_HBA_ADDR_COMPLEX flag has not been set, then the function will return
NULL. This can be used as a way to check if the flag has been set on the
device.

The scsi_device_hba_private_set() function, allows a driver to set a
private data value on the scsi_device(9S) structure, which it can later
retrieve through the scsi_device_hba_private_get() function. Most drivers
will set a value during the tran_start(9E) entry point and then reference
the data structure later on. This is designed to simplify the management
of mapping between driver data structures and the corresponding system
objects.

The scsi_device_unit_address() function returns the unit address of the
scsi_device(9S) structure. The returned string should not be modified by
the device driver. The unit address string comes from values that are
passed when the device is enumerated, generally through an instance of an
iport(9).

CONTEXT

These functions may be used in user, kernel, and interrupt context.

RETURN VALUES

Upon successful completion, the scsi_address_device() function returns a
pointer to the scsi_device(9S) structure. Otherwise, if an error occurred
NULL is returned.

The scsi_device_hba_private_get() function returns a data value registered
via the scsi_device_hba_private_set() function. If the
scsi_device_hba_private_set() was never called, NULL is returned.

Upon successful completion, the scsi_device_unit_address() returns a
pointer to a character string with the device's unit address. Otherwise,
NULL is returned.

If the SCSI_HBA_ADDR_COMPLEX flag has not been set for the HBA structure or
iport, then the scsi_address_device(), scsi_device_hba_private_get(), and
scsi_device_unit_address() functions return NULL.