illumos: manual page: scsi_hba_tgtmap_tgt

SCSI_HBA_TGTMAP_CREATE(9F) Kernel Functions for Drivers

NAME

scsi_hba_tgtmap_create, scsi_hba_tgtmap_destroy, scsi_hba_tgtmap_set_begin,
scsi_hba_tgtmap_set_add, scsi_hba_tgtmap_set_end,
scsi_hba_tgtmap_set_flush, scsi_hba_tgtmap_tgt_add,
scsi_hba_tgtmap_tgt_remove - SCSI target map functions

SYNOPSIS

#include <sys/scsi/scsi.h>

int
scsi_hba_tgtmap_create(dev_info_t *dip, scsi_tgtmap_mode_t mode,
int csync_usec, int settle_usec, void *tgtmap_priv,
scsi_tgt_activate_cb_t activate_cb,
scsi_tgt_deactivate_cb_t deactivate_cb, scsi_hba_tgtmap_t **tgtmapout);

void
scsi_hba_tgtmap_destroy(scsi_hba_tgtmap_t *tgtmap);

void
(*scsi_tgt_activate_cb_t)(void *tgtmap_priv, char *tgt_addr,
scsi_tgtmap_tgt_type_t type, void **tgt_privp);

boolean_t
(*scsi_tgt_deactivate_cb_t)(void *tgtmap_priv, char *tgt_addr,
scsi_tgtmap_tgt_type_t type, void *tgt_priv,
scsi_tgtmap_deact_rsn_t deact);

int
scsi_hba_tgtmap_set_begin(scsi_hba_tgtmap_t *tgtmap);

int
scsi_hba_tgtmap_set_add(scsi_hba_tgtmap_t *tgtmap,
scsi_tgtmap_tgt_type_t type, char *tgt_addr, void *tgt_priv);

int
scsi_hba_tgtmap_set_end(scsi_hba_tgtmap_t *tgtmap, uint_t flags);

int
scsi_hba_tgtmap_set_flush(scsi_hba_tgtmap_t *tgtmap);

int
scsi_hba_tgtmap_tgt_add(scsi_hba_tgtmap_t *tgtmap,
scsi_tgtmap_tgt_type_t type, char *tgt_addr, void *tgt_priv);

int
scsi_hba_tgtmap_tgt_remove(scsi_hba_tgtmap_t *tgtmap,
scsi_tgtmap_tgt_type_t type, char *tgt_addr);

INTERFACE LEVEL

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

PARAMETERS

dip Pointer to dev_info structure.

mode One of the following values:

SCSI_TM_FULLSET
The target map operates by full-set reporting.

SCSI_TM_PERADDR
The target map operates by per-address
reporting.

csync_usec A time in microseconds.

settle_usec A time in microseconds.

tgtmap_priv A private value to be passed to callback functions.

activate_cb An optional callback that will be called when a new device is
being added to the system.

deactivate_cb
An optional callback that will be called when an existing
devices is removed from the system.

tgtmapout Pointer where the target map handle is stored.

tgtmap Pointer to an allocated target map.

flags Flags that modify the behavior of the function. Currently
reserved and should be passed as 0.

tgt_addr The address of the target map entry the callback is acting
upon.

type One of the following values, indicating the type of the
target:

SCSI_TGT_SCSI_DEVICE
The target is some form of SCSI device such as
a parallel SCSI, SATA, SAS, SES, etc.

SCSI_TGT_SMP_DEVICE
The target is a SCSI Management Protocol
device.

deact One of the following values, indicating why the target is
being removed:

SCSI_TGT_DEACT_RSN_GONE
The device is being deactivated because it is
gone.

SCSI_TGT_DEACT_RSN_CFG_FAIL
The device is being deactivated because the
configuration callback failed.

SCSI_TGT_DEACT_RSN_UNSTBL
The device is being deactivated because it was
added and removed during the stabilization
period and therefore is considered unstable.

DESCRIPTION

The scsi_hba_tgtmap_create() and scsi_hba_tgtmap_destroy() functions are
used to create and destroy target maps. A target map is used to manage
SCSI and SMP (SCSI Management Protocol) devices. For more background on
target maps, see tgtmap(9).

To create a target map, the driver should call the scsi_hba_tgtmap_create()
function. Upon successful completion, a pointer to the target map will be
placed in the tgtmapout argument.

The dip argument should correspond to one of the HBA driver's iports. The
overall driver instance cannot be used here. Target maps are only
supported on iports.

The mode argument describes how addresses are reported into the target map
and the functions used to add and remove devices. If mode is
SCSI_TM_FULLSET then the driver must always report all the devices that are
in the set and will be told when the corresponding devices have been
removed. See the section Full-Set Reporting for more information.

Otherwise, the driver should set the mode argument to SCSI_TM_PERADDR and
use the scsi_hba_tgtmap_tgt_add() and scsi_hba_tgtmap_tgt_remove()
functions. See the section Per-Address Reporting for more information.

The csync_usec and settle_usec are both times measured in microseconds that
control two different properties of the target map and how it behaves. The
value in settle_usec indicates the amount of time that the system should
wait to quiesce all changes and consider the resulting system stable.
Changes will not be reported until after settle_usec have passed.
csync_usec indicates how much time needs to elapse after creation before an
initial enumeration has been completed.

The activate_cb and deactivate_cb arguments are optional function pointers
that will be run in the context of devices being added and removed from the
system. This allows the HBA driver to perform any required operations
prior to the system attaching a target driver such as sd(4D) or ses(4D) in
the activate case and after the system has detached the driver, in the
removal case.

To destroy a target map, a caller should use the scsi_hba_tgtmap_destroy()
function. Destroying a target map causes all currently present devices to
be deactivated, as though they were removed, prior to the final destruction
of the target map.

Callbacks

Target maps allow for callbacks to be registered and called when devices
are being added and removed from the system. A driver specifies these when
the target map is created by passing in function pointers to the
activate_cb() and deactivate_cb() arguments.

When a new address is registered in a target map and the driver has
specified a function in the activate_cb argument, the driver will
eventually have their activation function called. This call will be
asynchronous with respect to the adding and removing of entries, regardless
of whether the target map is using per-address or full-set reporting. This
call will occur before any driver is bound to the discovered address.

The tgtmap_priv argument will point to the optional, private argument that
was passed to the scsi_hba_tgtmap_create() function when the target map was
created. The tgt_addr and tgt_type will describe the address and type of
the new device and will correspond with the values passed into either the
scsi_hba_tgtmap_set_add() or scsi_hba_tgtmap_tgt_add() functions.

The tgt_privp argument is a modifiable private value. Initially, tgt_privp
points to the value passed in as tgt_priv to either the
scsi_hba_tgtmap_set_add() or scsi_hba_tgtmap_tgt_add() functions. The
driver may change the value as needed. It will receive the value stored in
tgt_privp during the deactivate callback.

When a target map has been updated to indicate that a device has been
removed, then the driver will receive a deactivation callback if it
registered one. The deactivate callback will occur after a driver has been
detached from the corresponding device.

The tgtmap_priv, tgt_addr, and type arguments to the callback function are
the same as for the activate case. The tgt_priv pointer will be set to the
value that was passed when the device was added and will reflect any
updates made during an activate callback, if present.

The deact argument gives the driver some amount of information as to why
device was being removed. The deactivation reason provides the driver more
information about why the address was being removed from the target map
which can be useful in the cases that it itself did not issue it.

The return value indicates whether or not some amount of rediscovery of the
address is desired or not. This is only meaningful in the case where the
deact argument was SCSI_TGT_DEACT_RSN_CFG_FAIL. If the driver does wish to
attempt rediscovery, then it should return B_TRUE. Otherwise, the driver
should return B_FALSE. If in doubt, use the return value B_FALSE. Note,
even if the driver returns B_TRUE, no action may be taken by the system.

Full-Set Reporting
Full-Set reporting is one way of managing a target map. In full-set
reporting, whenever an update is being made, the entire data set is
reported to the target map. The target map then determines which addresses
are new, which have been removed, and which have stayed the same and
updates the system state appropriately. If devices have been added or
removed from the system, then any activate and deactivate endpoints will be
called.

To begin a new report, the driver should call the
scsi_hba_tgtmap_set_begin() function. Once the report has begun, the
driver should add devices by calling the scsi_hba_tgtmap_set_add()
function. Once all devices have been added, the driver should call the
scsi_hba_tgtmap_set_end() function to indicate that the target map
processing has ended. If driver wishes to discard a report that has begun,
but not yet terminated, then the driver should call the
scsi_hba_tgtmap_set_flush() function.

When adding entries, the driver should indicate the address of the device
in tgt_addr. This will generally be a world wide number (WWN) in a unit-
addressable form. However, the driver may use its own synthetic numbering.
This address will be passed to the activate callbacks and will also be used
as the address of the scsi_device(9S) in the tran_start(9E) entry point.

The type argument indicates how the kernel will interpret the type of
device. At this time, devices are broken into two broad categories.
Things which are some kind of SCSI device, whether parallel, SCSI, SATA
behind a SATL, SES, etc. should use the type SCSI_TGT_SCSI_DEVICE. The
other group, SCSI_TGT_SMP_DEVICE, is for SCSI Management Protocol (SMP)
devices.

The tgt_priv argument will be passed to the activate and deactivate
callbacks, allowing the driver to pass around data corresponding to this
address.

Per-Address Reporting
When using a target map with per-address reporting, the driver is
responsible for indicating what devices have been added and removed. This
is useful for various hardware configurations where all entries and
removals are processes in a highly-reliable fashion where hardware cannot
drop entries.

To add a new device, the driver should call the scsi_hba_tgtmap_tgt_add
function. The tgt_addr and type arguments describe the address and what
kind of device the address corresponds to. For more information, see the
previous section, Full-Address Reporting. The tgt_priv argument will be
passed along to the activate and deactivate functions, allowing the driver
to associate a value with the address in question.

When a device has been removed, the driver should call the
scsi_hba_tgtmap_tgt_remove() function, ensuring that both the tgt_addr and
type arguments match those that were used when calling the
scsi_hba_tgtmap_tgt_add() function.

CONTEXT

The scsi_hba_tgtmap_create() and scsi_hba_tgtmap_destroy() functions are
generally called from the context of the attach(9E) and detach(9E) entry
points of HBA drivers and their iports, though may also be called from user
or kernel context.

The optional activate_cb() and deactivate_cb() functions for a target map
will be called into the driver from kernel context.

The scsi_hba_tgtmap_set_begin(), scsi_hba_tgtmap_set_add(),
scsi_hba_tgtmap_set_end(), scsi_hba_tgtmap_set_flush(),
scsi_hba_tgtmap_tgt_add(), and scsi_hba_tgtmap_tgt_remove() functions may
be called from user or kernel context. It is recommended that device
drivers do not call these functions from interrupt context and instead
should schedule deferred work with a task queue or with timeout(9F) if they
receive notifications during an interrupt that causes them to need to call
these functions.

RETURN VALUES

Upon successful completion, the scsi_hba_tgtmap_create(),
scsi_hba_tgtmap_destroy(), scsi_hba_tgtmap_set_begin(),
scsi_hba_tgtmap_set_add(), scsi_hba_tgtmap_set_end(),
scsi_hba_tgtmap_set_flush(), scsi_hba_tgtmap_tgt_add(), and
scsi_hba_tgtmap_tgt_remove() functions return DDI_SUCCESS. Otherwise,
DDI_FAILURE is returned.