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

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

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

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

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.

The () 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 () 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 () function. A side effect of this is that all existing entries in the phy map will be removed and their deactivate callbacks will fire.

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

To add a phy to the system, the driver should call the () 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 () 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.

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.

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.

iportmap(9), phymap(9), tgtmap(9), attach(9E), detach(9E), sas_phymap_lookup_ua(9F), sas_phymap_lookup_uapriv(9F), sas_phymap_phy2ua(9F)

April 20, 2017 OmniOS