Tribblix: manual page: scsi_address

SCSI_ADDRESS_DEVICE(9F) Kernel Functions for Drivers

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.