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

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

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

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

dip
Pointer to dev_info structure.
mode
One of the following values:
The target map operates by full-set reporting.
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 .
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:
The target is some form of SCSI device such as a parallel SCSI, SATA, SAS, SES, etc.
The target is a SCSI Management Protocol device.
deact
One of the following values, indicating why the target is being removed:
The device is being deactivated because it is gone.
The device is being deactivated because the configuration callback failed.
The device is being deactivated because it was added and removed during the stabilization period and therefore is considered unstable.

The () 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 () 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 () 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 () 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.

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 () and () 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 () 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 () 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 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 () 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 () 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 () 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.

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 () function, ensuring that both the tgt_addr and type arguments match those that were used when calling the scsi_hba_tgtmap_tgt_add() function.

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 () using the address of a target that has been registered using the given tgt_addr.

This will cause the framework to issue a 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.

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

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.

sd(4D), ses(4D), tgtmap(9), attach(9E), detach(9E), tran_start(9E), timeout(9F), scsi_device(9S)

January 29, 2022 OmniOS