illumos: manual page: sas_phymap_phy

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

NAME

sas_phymap_create, sas_phymap_destroy, sas_phymap_phy_add,
sas_phymap_phy_rem - SAS PHY map functions

SYNOPSIS

#include <sys/scsi/scsi.h>

int
sas_phymap_create(dev_info_t *dip, int settle_usec, sas_phymap_mode_t mode,
void *mode_argument, void *phymap_priv,
sas_phymap_activate_cb_t activate_cb,
sas_phymap_deactivate_cb_t deactivate_cb, sas_phymap_t **phymapout);

void
sas_phymap_destroy(sas_phymap_t *phymap);

int
sas_phymap_phy_add(sas_phymap_t *phymap, int phy, uint64_t local,
uint64_t remote);

int
sas_phymap_phy_rem(sas_phymap_t *phymap, int phy);

void
(*sas_phymap_activate_cb_t)(void *phymap_priv, char *ua, void **ua_privp);

void
(*sas_phymap_deactivate_cb_t)(void *phymap_priv, char *ua, void *ua_priv);

INTERFACE LEVEL

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

PARAMETERS

dip Pointer to dev_info structure.

settle_usec A time in microseconds.

mode Mode of operation for the phy map. Should be set to
PHYMAP_MODE_SIMPLE.

mode_priv Drivers should pass NULL.

phymap_priv A private argument to be used in callback functions.

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

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

phymapout Pointer where the phy map is stored.

phymap Pointer to an allocated phy map.

phy A non-negative integer that uniquely identifies a phy on a
device.

local The World Wide Number (WWN) of the HBA-owned side of the phy.

remote The World Wide Number (WWN) of the device that is plugged
into the phy.

ua A character string that indicates the system generated unit
address for the logical port.

ua_privp A private value that can be stored for the corresponding unit
address.

ua_priv A private value for the unit address stored into ua_privp.

DESCRIPTION

The sas_phymap_create() and sas_phymap_destroy() functions create and
destroy phymaps which are used to manage a set of potentially-active SAS
phys and the attached devices. For more background, see phymap(9). If the
driver in question is not a SAS HBA or a similar fabric-like device, then
do not use this interface.

The phy map maps one or more phys to a logical port-like construct that is
represented based on the WWNs in question. This logical SAS port has a
unit address derived from the two WWNs. When the first phy is noted as
using these WWNs, then the phymap will call any registered callbacks as the
port is created. If additional phys come online in service of the same
port, then a new port will not be created.

To facilitate the mapping between a PHY and the corresponding port unit
address, the sas_phymap_phy2ua(9F) and sas_phymap_lookup_ua(9F) functions
are available.

To create a phy map, the driver uses the sas_phymap_create() function. The
resulting phy map will be stored in the phymapout argument. 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.

If a driver places a function pointer for either the activate_cb or
deactivate cb then those functions will be called when phys are added and
removed from the phy map.

The value placed in the phymap_priv argument will be passed to both
callback functions.

To destroy a phymap, the driver should call the sas_phymap_destroy()
function. A side effect of this is that all existing entries in the phy
map will be removed and their deactivate callbacks will fire.

Callbacks

The phymap provides a means for receiving callbacks when the addition of a
phy causes a new logical port to be created or when the phy being removed
is the last phy that is a member of the port. Unlike with the tgtmap(9),
there is no system managed driver that is attached with the phymap. For
the phymap to be useful to drivers, the callbacks should generally be
registered.

It's important to emphasize that the callbacks do not represent phys, but
instead the logical port that they are bound to. This is different from
the tgtmap(9) and iportmap(9). Calls to the sas_phymap_phy_add() and
sas_phymap_phy_rem() functions may not result in anything being created in
the system.

The activate_cb callback occurs whenever a new logical port is created
because the first phy that references that pair of WWNs has been created.
The phymap_priv argument corresponds to the value passed in the
sas_phymap_create() function.

The ua argument is a unit-address string that the system constructs based
on the WWNs passed in the local and remote arguments to the
sas_phymap_phy_add() function. If this is being used together with an
iportmap(9) then the ua should be the name of the added iport.

The ua_privp argument allows for data to be correlated with the unit-
address. This data is accessible throughout the lifetime of the unit-
address through the sas_phymap_lookup_uapriv(9F) function and is also made
available during the deactivate callback.

The deactivate_cb callback occurs when the logical port is being removed,
because the last associated phy has been removed. The arguments to this
are the same as to the activate callback, with the exception that the
ua_priv argument is the value that was stored in the ua_privp argument of
the activate callback.

Adding and Removing PHYs

To add a phy to the system, the driver should call the sas_phymap_phy_add()
function. The phy argument should indicate the phy identifier of the phy
that has come up. The local WWN generally corresponds to the SAS port on
the controller, while the remote WWN is whatever device is on the other
side of the phy. The system enforces that a given phy only maps to a
single port at any time.

When a phy goes offline, then the driver should call the
sas_phymap_phy_rem() function using the same phy identifier that it used
when adding the phy. If this is the last phy that was used for this
logical port, then the corresponding logical port will be removed and the
deactivate callback function, if registered, will be called.

CONTEXT

The sas_phymap_create() and sas_phymap_destroy() functions are generally
called during an HBA driver's attach(9E) and detach(9E) entry points,
though may be called by a driver from user or kernel context.

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

The sas_phymap_phy_add() and sas_phymap_phy_rem() functions may be called
from user or kernel context.

RETURN VALUES

Upon successful completion, the sas_phymap_create(), sas_phymap_phy_add(),
and sas_phymap_phy_rem() functions return DDI_SUCCESS. Otherwise,
DDI_FAILURE is returned to indicate failure.