Tribblix: manual page: scsi_hba_tgtmap

SCSI_HBA_TGTMAP_CREATE(9F) Kernel Functions for Drivers

NAME

scsi_hba_tgtmap_create, scsi_hba_tgtmap_destroy,
scsi_hba_tgtmap_scan_luns, 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);

void
scsi_hba_tgtmap_scan_luns(scsi_hba_tgtmap_t *tgtmap, char *tgt_addr);

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.

Scanning for Logical Units

SCSI targets may contain logical units (LUNS) that are created or
destroyed by the target dynamically. In order to facilitate discovery
of logical units, the HBA may call scsi_hba_tgtmap_scan_luns() using
the address of a target that has been registered using the given
tgt_addr.

This will cause the framework to issue a REPORT_LUNS command, to
enumerate any present logical units. Logical units that are no longer
present will be pruned from the system, and any new ones will be
created.

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_scan_luns(), 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. Device drivers should not call these functions from
interrupt context and should instead schedule deferred work with a task
queue or with timeout(9F) if a need to call these arises while handling
an interrupt.

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.