illumos: manual page: sas_phymap

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

NAME

sas_phymap_lookup_ua, sas_phymap_lookup_uapriv, sas_phymap_phy2ua,
sas_phymap_ua_free, sas_phymap_uahasphys, sas_phymap_ua2phys,
sas_phymap_phys_next, sas_phymap_phys_free - SAS phymap utility functions

SYNOPSIS

#include <sys/scsi/scsi.h>

char *
sas_phymap_lookup_ua(sas_phymap_t *phymap, uint64_t local,
uint64_t remote);

void *
sas_phymap_lookup_uapriv(sas_phymap_t *phymap, char *ua);

int
sas_phymap_uahasphys(sas_phymap_t *phymap, char *ua);

char *
sas_phymap_phy2ua(sas_phymap_t *phymap, int phy);

void
sas_phymap_ua_free(char *ua);

sas_phymap_phys_t *
sas_phymap_ua2phys(sas_phymap_t *phymap, char *ua);

int
sas_phymap_phys_next(sas_phymap_phys_t *phys);

void
sas_phymap_phys_free(sas_phymap_phys_t *phys);

INTERFACE LEVEL

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

PARAMETERS

phymap Pointer to an allocated phy map.

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.

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

phys An opaque structure that represents a collection of phys on a
port.

DESCRIPTION

The functions described here are all utility functions for operating on a
phymap and the entities it creates.
For more information on phymaps, see phymap(9) and sas_phymap_create(9F).

The sas_phymap_lookup_ua() function finds the unit address of the logical
port that corresponds to the tuple of the local and remote WWN. If a
logical port exists for that tuple, then a pointer to its system generated
unit-address is returned. This string is managed by the system and it must
not be modified or freed. If it cannot be found, then NULL is returned.

The sas_phymap_lookup_uapriv() function returns the private value that was
stored during the activate callback of the logical port represented by the
unit address ua that is a part of the phymap phymap.

The sas_phymap_uahasphys() function is used to determine whether or not the
logical port represented by the unit address specified in ua that is a part
of the phymap phymap has any phys. If phys are found, then the function
returns 1.

The sas_phymap_phy2ua() function attempts to map a given phy specified by
phy to its unit-address in the map phymap. This function will allocate
memory for the character string, thus it can be modified. The caller must
call the sas_phymap_ua_free function to release the memory that was
allocated. The sas_phymap_ua_free function should not be used with the
string returned from the sas_phymap_lookup_ua() function.

The sas_phymap_ua2phys() function creates a collection of phys that exist
on a given logical port represented by the unit-address ua in the map
phymap. This set can be iterated by calling the sas_phyap_phys_next()
function. Each time the function is called, an entry is returned. When
the value -1 is returned it indicates that the set is empty. Regardless of
whether or not the set has been iterated over, the caller must call the
sas_phymap_phys_free() function to release the memory associated with the
set.

CONTEXT

All functions may be used in user, kernel, and interrupt context.

RETURN VALUES

Upon successful completion, the sas_phymap_lookup_ua() and
sas_phymap_phy2ua() function returns a pointer to the unit-address. If the
port or phy could not be found or another error occurred, then the function
returns NULL.

Upon successful completion, the sas_phymap_lookup_uapriv() function returns
a pointer to the port's private data, if any exists. Otherwise, if the
port could not be found or another error occurred, then the function
returns NULL. Upon successful completion, the sas_phymap_uahasphys()
returns 1 to indicate that the unit-address has phys. If the unit-address
has no phys, then it returns 0. If an error occurred or the port doesn't
exist, then the function returns 0.

Upon successful completion, the sas_phymap_ua2phys() function returns a
pointer to an allocated phy set. Otherwise, it returns NULL.

The sas_phymap_phys_next() function returns a non-negative integer
indicating a present phy or it returns -1 to indicate that no values
remain.