Tribblix: manual page: sas_phymap

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.