Tribblix: manual page: sas_phymap_lookup

SAS_PHYMAP_LOOKUP_UA(9F) Kernel Functions for Drivers

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.