1*3385b472SRobert Mustacchi.\" 2*3385b472SRobert Mustacchi.\" This file and its contents are supplied under the terms of the 3*3385b472SRobert Mustacchi.\" Common Development and Distribution License ("CDDL"), version 1.0. 4*3385b472SRobert Mustacchi.\" You may only use this file in accordance with the terms of version 5*3385b472SRobert Mustacchi.\" 1.0 of the CDDL. 6*3385b472SRobert Mustacchi.\" 7*3385b472SRobert Mustacchi.\" A full copy of the text of the CDDL should have accompanied this 8*3385b472SRobert Mustacchi.\" source. A copy of the CDDL is also available via the Internet at 9*3385b472SRobert Mustacchi.\" http://www.illumos.org/license/CDDL. 10*3385b472SRobert Mustacchi.\" 11*3385b472SRobert Mustacchi.\" 12*3385b472SRobert Mustacchi.\" Copyright (c) 2017, Joyent, Inc. 13*3385b472SRobert Mustacchi.\" 14*3385b472SRobert Mustacchi.Dd Apr 20, 2017 15*3385b472SRobert Mustacchi.Dt SAS_PHYMAP_LOOKUP_UA 9F 16*3385b472SRobert Mustacchi.Os 17*3385b472SRobert Mustacchi.Sh NAME 18*3385b472SRobert Mustacchi.Nm sas_phymap_lookup_ua , 19*3385b472SRobert Mustacchi.Nm sas_phymap_lookup_uapriv , 20*3385b472SRobert Mustacchi.Nm sas_phymap_phy2ua , 21*3385b472SRobert Mustacchi.Nm sas_phymap_ua_free , 22*3385b472SRobert Mustacchi.Nm sas_phymap_uahasphys , 23*3385b472SRobert Mustacchi.Nm sas_phymap_ua2phys , 24*3385b472SRobert Mustacchi.Nm sas_phymap_phys_next , 25*3385b472SRobert Mustacchi.Nm sas_phymap_phys_free 26*3385b472SRobert Mustacchi.Nd SAS phymap utility functions 27*3385b472SRobert Mustacchi.Sh SYNOPSIS 28*3385b472SRobert Mustacchi.In sys/scsi/scsi.h 29*3385b472SRobert Mustacchi.Ft "char *" 30*3385b472SRobert Mustacchi.Fo sas_phymap_lookup_ua 31*3385b472SRobert Mustacchi.Fa "sas_phymap_t *phymap" 32*3385b472SRobert Mustacchi.Fa "uint64_t local" 33*3385b472SRobert Mustacchi.Fa "uint64_t remote" 34*3385b472SRobert Mustacchi.Fc 35*3385b472SRobert Mustacchi.Ft "void *" 36*3385b472SRobert Mustacchi.Fo sas_phymap_lookup_uapriv 37*3385b472SRobert Mustacchi.Fa "sas_phymap_t *phymap" 38*3385b472SRobert Mustacchi.Fa "char *ua" 39*3385b472SRobert Mustacchi.Fc 40*3385b472SRobert Mustacchi.Ft int 41*3385b472SRobert Mustacchi.Fo sas_phymap_uahasphys 42*3385b472SRobert Mustacchi.Fa "sas_phymap_t *phymap" 43*3385b472SRobert Mustacchi.Fa "char *ua" 44*3385b472SRobert Mustacchi.Fc 45*3385b472SRobert Mustacchi.Ft "char *" 46*3385b472SRobert Mustacchi.Fo sas_phymap_phy2ua 47*3385b472SRobert Mustacchi.Fa "sas_phymap_t *phymap" 48*3385b472SRobert Mustacchi.Fa "int phy" 49*3385b472SRobert Mustacchi.Fc 50*3385b472SRobert Mustacchi.Ft void 51*3385b472SRobert Mustacchi.Fo sas_phymap_ua_free 52*3385b472SRobert Mustacchi.Fa "char *ua" 53*3385b472SRobert Mustacchi.Fc 54*3385b472SRobert Mustacchi.Ft "sas_phymap_phys_t *" 55*3385b472SRobert Mustacchi.Fo sas_phymap_ua2phys 56*3385b472SRobert Mustacchi.Fa "sas_phymap_t *phymap" 57*3385b472SRobert Mustacchi.Fa "char *ua" 58*3385b472SRobert Mustacchi.Fc 59*3385b472SRobert Mustacchi.Ft int 60*3385b472SRobert Mustacchi.Fo sas_phymap_phys_next 61*3385b472SRobert Mustacchi.Fa "sas_phymap_phys_t *phys" 62*3385b472SRobert Mustacchi.Fc 63*3385b472SRobert Mustacchi.Ft void 64*3385b472SRobert Mustacchi.Fo sas_phymap_phys_free 65*3385b472SRobert Mustacchi.Fa "sas_phymap_phys_t *phys" 66*3385b472SRobert Mustacchi.Fc 67*3385b472SRobert Mustacchi.Sh INTERFACE LEVEL 68*3385b472SRobert Mustacchi.Sy Evolving - 69*3385b472SRobert MustacchiThis interface is still evolving in illumos. 70*3385b472SRobert MustacchiAPI and ABI stability is 71*3385b472SRobert Mustacchinot guaranteed. 72*3385b472SRobert Mustacchi.Sh PARAMETERS 73*3385b472SRobert Mustacchi.Bl -tag -width Fa 74*3385b472SRobert Mustacchi.It Fa phymap 75*3385b472SRobert MustacchiPointer to an allocated phy map. 76*3385b472SRobert Mustacchi.It Fa local 77*3385b472SRobert MustacchiThe World Wide Number (WWN) of the HBA-owned side of the phy. 78*3385b472SRobert Mustacchi.It Fa remote 79*3385b472SRobert MustacchiThe World Wide Number (WWN) of the device that is plugged into the phy. 80*3385b472SRobert Mustacchi.It Fa ua 81*3385b472SRobert MustacchiA character string that indicates the system generated unit address for 82*3385b472SRobert Mustacchithe logical port. 83*3385b472SRobert Mustacchi.It Fa phy 84*3385b472SRobert MustacchiA non-negative integer that uniquely identifies a phy on a device. 85*3385b472SRobert Mustacchi.It Fa phys 86*3385b472SRobert MustacchiAn opaque structure that represents a collection of phys on a port. 87*3385b472SRobert Mustacchi.El 88*3385b472SRobert Mustacchi.Sh DESCRIPTION 89*3385b472SRobert MustacchiThe functions described here are all utility functions for operating on 90*3385b472SRobert Mustacchia phymap and the entities it creates. 91*3385b472SRobert Mustacchi For more information on phymaps, 92*3385b472SRobert Mustacchisee 93*3385b472SRobert Mustacchi.Xr phymap 9 94*3385b472SRobert Mustacchiand 95*3385b472SRobert Mustacchi.Xr sas_phymap_create 9F . 96*3385b472SRobert Mustacchi.Pp 97*3385b472SRobert MustacchiThe 98*3385b472SRobert Mustacchi.Fn sas_phymap_lookup_ua 99*3385b472SRobert Mustacchifunction finds the unit address of the logical port that corresponds to 100*3385b472SRobert Mustacchithe tuple of the 101*3385b472SRobert Mustacchi.Fa local 102*3385b472SRobert Mustacchiand 103*3385b472SRobert Mustacchi.Fa remote 104*3385b472SRobert MustacchiWWN. 105*3385b472SRobert MustacchiIf a logical port exists for that tuple, then a pointer to its 106*3385b472SRobert Mustacchisystem generated unit-address is returned. 107*3385b472SRobert MustacchiThis string is managed by the system and it must not be modified or freed. 108*3385b472SRobert MustacchiIf it cannot be found, then 109*3385b472SRobert Mustacchi.Dv NULL 110*3385b472SRobert Mustacchiis returned. 111*3385b472SRobert Mustacchi.Pp 112*3385b472SRobert MustacchiThe 113*3385b472SRobert Mustacchi.Fn sas_phymap_lookup_uapriv 114*3385b472SRobert Mustacchifunction returns the private value that was stored during the activate 115*3385b472SRobert Mustacchicallback of the logical port represented by the unit address 116*3385b472SRobert Mustacchi.Fa ua 117*3385b472SRobert Mustacchithat is a part of the phymap 118*3385b472SRobert Mustacchi.Fa phymap . 119*3385b472SRobert Mustacchi.Pp 120*3385b472SRobert MustacchiThe 121*3385b472SRobert Mustacchi.Fn sas_phymap_uahasphys 122*3385b472SRobert Mustacchifunction is used to determine whether or not the logical port 123*3385b472SRobert Mustacchirepresented by the unit address specified in 124*3385b472SRobert Mustacchi.Fa ua 125*3385b472SRobert Mustacchithat is a part of the phymap 126*3385b472SRobert Mustacchi.Fa phymap 127*3385b472SRobert Mustacchihas any phys. 128*3385b472SRobert MustacchiIf phys are found, then the function returns 129*3385b472SRobert Mustacchi.Sy 1 . 130*3385b472SRobert Mustacchi.Pp 131*3385b472SRobert MustacchiThe 132*3385b472SRobert Mustacchi.Fn sas_phymap_phy2ua 133*3385b472SRobert Mustacchifunction attempts to map a given phy specified by 134*3385b472SRobert Mustacchi.Fa phy 135*3385b472SRobert Mustacchito its unit-address in the map 136*3385b472SRobert Mustacchi.Fa phymap . 137*3385b472SRobert MustacchiThis function will allocate memory for the character string, thus it can 138*3385b472SRobert Mustacchibe modified. 139*3385b472SRobert MustacchiThe caller must call the 140*3385b472SRobert Mustacchi.Fa sas_phymap_ua_free 141*3385b472SRobert Mustacchifunction to release the memory that was allocated. 142*3385b472SRobert MustacchiThe 143*3385b472SRobert Mustacchi.Fa sas_phymap_ua_free 144*3385b472SRobert Mustacchifunction should not be used with the string returned from the 145*3385b472SRobert Mustacchi.Fn sas_phymap_lookup_ua 146*3385b472SRobert Mustacchifunction. 147*3385b472SRobert Mustacchi.Pp 148*3385b472SRobert MustacchiThe 149*3385b472SRobert Mustacchi.Fn sas_phymap_ua2phys 150*3385b472SRobert Mustacchifunction creates a collection of phys that exist on a given logical port 151*3385b472SRobert Mustacchirepresented by the unit-address 152*3385b472SRobert Mustacchi.Fa ua 153*3385b472SRobert Mustacchiin the map 154*3385b472SRobert Mustacchi.Fa phymap . 155*3385b472SRobert MustacchiThis set can be iterated by calling the 156*3385b472SRobert Mustacchi.Fn sas_phyap_phys_next 157*3385b472SRobert Mustacchifunction. 158*3385b472SRobert MustacchiEach time the function is called, an entry is returned. 159*3385b472SRobert MustacchiWhen the value 160*3385b472SRobert Mustacchi.Sy -1 161*3385b472SRobert Mustacchiis returned it indicates that the set is empty. 162*3385b472SRobert MustacchiRegardless of whether or not the set has been iterated over, the caller 163*3385b472SRobert Mustacchimust call the 164*3385b472SRobert Mustacchi.Fn sas_phymap_phys_free 165*3385b472SRobert Mustacchifunction to release the memory associated with the set. 166*3385b472SRobert Mustacchi.Sh CONTEXT 167*3385b472SRobert MustacchiAll functions may be used in 168*3385b472SRobert Mustacchi.Sy user , 169*3385b472SRobert Mustacchi.Sy kernel , 170*3385b472SRobert Mustacchiand 171*3385b472SRobert Mustacchi.Sy interrupt 172*3385b472SRobert Mustacchicontext. 173*3385b472SRobert Mustacchi.Sh RETURN VALUES 174*3385b472SRobert MustacchiUpon successful completion, the 175*3385b472SRobert Mustacchi.Fn sas_phymap_lookup_ua 176*3385b472SRobert Mustacchiand 177*3385b472SRobert Mustacchi.Fn sas_phymap_phy2ua 178*3385b472SRobert Mustacchifunction returns a pointer to the unit-address. 179*3385b472SRobert MustacchiIf the port or phy could not be found or another error occurred, then 180*3385b472SRobert Mustacchithe function returns 181*3385b472SRobert Mustacchi.Dv NULL . 182*3385b472SRobert Mustacchi.Pp 183*3385b472SRobert MustacchiUpon successful completion, the 184*3385b472SRobert Mustacchi.Fn sas_phymap_lookup_uapriv 185*3385b472SRobert Mustacchifunction returns a pointer to the port's private data, if any exists. 186*3385b472SRobert MustacchiOtherwise, if the port could not be found or another error occurred, then 187*3385b472SRobert Mustacchithe function returns 188*3385b472SRobert Mustacchi.Dv NULL . 189*3385b472SRobert MustacchiUpon successful completion, the 190*3385b472SRobert Mustacchi.Fn sas_phymap_uahasphys 191*3385b472SRobert Mustacchireturns 192*3385b472SRobert Mustacchi.Sy 1 193*3385b472SRobert Mustacchito indicate that the unit-address has phys. 194*3385b472SRobert MustacchiIf the unit-address has no phys, then it returns 195*3385b472SRobert Mustacchi.Sy 0 . 196*3385b472SRobert MustacchiIf an error occurred or the port doesn't exist, then the function returns 197*3385b472SRobert Mustacchi.Sy 0 . 198*3385b472SRobert Mustacchi.Pp 199*3385b472SRobert MustacchiUpon successful completion, the 200*3385b472SRobert Mustacchi.Fn sas_phymap_ua2phys 201*3385b472SRobert Mustacchifunction returns a pointer to an allocated phy set. 202*3385b472SRobert MustacchiOtherwise, it returns 203*3385b472SRobert Mustacchi.Dv NULL . 204*3385b472SRobert Mustacchi.Pp 205*3385b472SRobert MustacchiThe 206*3385b472SRobert Mustacchi.Fn sas_phymap_phys_next 207*3385b472SRobert Mustacchifunction returns a non-negative integer indicating a present phy or it 208*3385b472SRobert Mustacchireturns 209*3385b472SRobert Mustacchi.Sy -1 210*3385b472SRobert Mustacchito indicate that no values remain. 211*3385b472SRobert Mustacchi.Sh SEE ALSO 212*3385b472SRobert Mustacchi.Xr phymap 9 , 213*3385b472SRobert Mustacchi.Xr sas_phymap_create 9F 214