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_CREATE 9F 16*3385b472SRobert Mustacchi.Os 17*3385b472SRobert Mustacchi.Sh NAME 18*3385b472SRobert Mustacchi.Nm sas_phymap_create , 19*3385b472SRobert Mustacchi.Nm sas_phymap_destroy , 20*3385b472SRobert Mustacchi.Nm sas_phymap_phy_add , 21*3385b472SRobert Mustacchi.Nm sas_phymap_phy_rem 22*3385b472SRobert Mustacchi.Nd SAS PHY map functions 23*3385b472SRobert Mustacchi.Sh SYNOPSIS 24*3385b472SRobert Mustacchi.In sys/scsi/scsi.h 25*3385b472SRobert Mustacchi.Ft int 26*3385b472SRobert Mustacchi.Fo sas_phymap_create 27*3385b472SRobert Mustacchi.Fa "dev_info_t *dip" 28*3385b472SRobert Mustacchi.Fa "int settle_usec" 29*3385b472SRobert Mustacchi.Fa "sas_phymap_mode_t mode" 30*3385b472SRobert Mustacchi.Fa "void *mode_argument" 31*3385b472SRobert Mustacchi.Fa "void *phymap_priv" 32*3385b472SRobert Mustacchi.Fa "sas_phymap_activate_cb_t activate_cb" 33*3385b472SRobert Mustacchi.Fa "sas_phymap_deactivate_cb_t deactivate_cb" 34*3385b472SRobert Mustacchi.Fa "sas_phymap_t **phymapout" 35*3385b472SRobert Mustacchi.Fc 36*3385b472SRobert Mustacchi.Ft void 37*3385b472SRobert Mustacchi.Fo sas_phymap_destroy 38*3385b472SRobert Mustacchi.Fa "sas_phymap_t *phymap" 39*3385b472SRobert Mustacchi.Fc 40*3385b472SRobert Mustacchi.Ft int 41*3385b472SRobert Mustacchi.Fo sas_phymap_phy_add 42*3385b472SRobert Mustacchi.Fa "sas_phymap_t *phymap" 43*3385b472SRobert Mustacchi.Fa "int phy" 44*3385b472SRobert Mustacchi.Fa "uint64_t local" 45*3385b472SRobert Mustacchi.Fa "uint64_t remote" 46*3385b472SRobert Mustacchi.Fc 47*3385b472SRobert Mustacchi.Ft int 48*3385b472SRobert Mustacchi.Fo sas_phymap_phy_rem 49*3385b472SRobert Mustacchi.Fa "sas_phymap_t *phymap" 50*3385b472SRobert Mustacchi.Fa "int phy" 51*3385b472SRobert Mustacchi.Fc 52*3385b472SRobert Mustacchi.Ft void 53*3385b472SRobert Mustacchi.Fo (*sas_phymap_activate_cb_t) 54*3385b472SRobert Mustacchi.Fa "void *phymap_priv" 55*3385b472SRobert Mustacchi.Fa "char *ua" 56*3385b472SRobert Mustacchi.Fa "void **ua_privp" 57*3385b472SRobert Mustacchi.Fc 58*3385b472SRobert Mustacchi.Ft void 59*3385b472SRobert Mustacchi.Fo (*sas_phymap_deactivate_cb_t) 60*3385b472SRobert Mustacchi.Fa "void *phymap_priv" 61*3385b472SRobert Mustacchi.Fa "char *ua" 62*3385b472SRobert Mustacchi.Fa "void *ua_priv" 63*3385b472SRobert Mustacchi.Fc 64*3385b472SRobert Mustacchi.Sh INTERFACE LEVEL 65*3385b472SRobert Mustacchi.Sy Evolving - 66*3385b472SRobert MustacchiThis interface is still evolving in illumos. 67*3385b472SRobert MustacchiAPI and ABI stability is 68*3385b472SRobert Mustacchinot guaranteed. 69*3385b472SRobert Mustacchi.Sh PARAMETERS 70*3385b472SRobert Mustacchi.Bl -tag -width Fa 71*3385b472SRobert Mustacchi.It Fa dip 72*3385b472SRobert MustacchiPointer to 73*3385b472SRobert Mustacchi.Vt dev_info 74*3385b472SRobert Mustacchistructure. 75*3385b472SRobert Mustacchi.It Fa settle_usec 76*3385b472SRobert MustacchiA time in microseconds. 77*3385b472SRobert Mustacchi.It Fa mode 78*3385b472SRobert MustacchiMode of operation for the phy map. 79*3385b472SRobert MustacchiShould be set to 80*3385b472SRobert Mustacchi.Dv PHYMAP_MODE_SIMPLE . 81*3385b472SRobert Mustacchi.It Fa mode_priv 82*3385b472SRobert MustacchiDrivers should pass 83*3385b472SRobert Mustacchi.Dv NULL . 84*3385b472SRobert Mustacchi.It Fa phymap_priv 85*3385b472SRobert MustacchiA private argument to be used in callback functions. 86*3385b472SRobert Mustacchi.It Fa activate_cb 87*3385b472SRobert MustacchiAn optional callback that will be called when a new phy is being 88*3385b472SRobert Mustacchiadded to the system. 89*3385b472SRobert Mustacchi.It Fa deactivate_cb 90*3385b472SRobert MustacchiAn optional callback that will be called when an existing phys is 91*3385b472SRobert Mustacchiremoved from the system. 92*3385b472SRobert Mustacchi.It Fa phymapout 93*3385b472SRobert MustacchiPointer where the phy map is stored. 94*3385b472SRobert Mustacchi.It Fa phymap 95*3385b472SRobert MustacchiPointer to an allocated phy map. 96*3385b472SRobert Mustacchi.It Fa phy 97*3385b472SRobert MustacchiA non-negative integer that uniquely identifies a phy on a device. 98*3385b472SRobert Mustacchi.It Fa local 99*3385b472SRobert MustacchiThe World Wide Number (WWN) of the HBA-owned side of the phy. 100*3385b472SRobert Mustacchi.It Fa remote 101*3385b472SRobert MustacchiThe World Wide Number (WWN) of the device that is plugged into the phy. 102*3385b472SRobert Mustacchi.It Fa ua 103*3385b472SRobert MustacchiA character string that indicates the system generated unit address for 104*3385b472SRobert Mustacchithe logical port. 105*3385b472SRobert Mustacchi.It Fa ua_privp 106*3385b472SRobert MustacchiA private value that can be stored for the corresponding unit address. 107*3385b472SRobert Mustacchi.It Fa ua_priv 108*3385b472SRobert MustacchiA private value for the unit address stored into 109*3385b472SRobert Mustacchi.Fa ua_privp . 110*3385b472SRobert Mustacchi.El 111*3385b472SRobert Mustacchi.Sh DESCRIPTION 112*3385b472SRobert MustacchiThe 113*3385b472SRobert Mustacchi.Fn sas_phymap_create 114*3385b472SRobert Mustacchiand 115*3385b472SRobert Mustacchi.Fn sas_phymap_destroy 116*3385b472SRobert Mustacchifunctions create and destroy phymaps which are used to manage a set of 117*3385b472SRobert Mustacchipotentially-active SAS phys and the attached devices. 118*3385b472SRobert MustacchiFor more background, see 119*3385b472SRobert Mustacchi.Xr phymap 9 . 120*3385b472SRobert MustacchiIf the driver in question is not a SAS HBA or a similar fabric-like 121*3385b472SRobert Mustacchidevice, then do not use this interface. 122*3385b472SRobert Mustacchi.Pp 123*3385b472SRobert MustacchiThe phy map maps one or more phys to a logical port-like construct that 124*3385b472SRobert Mustacchiis represented based on the WWNs in question. 125*3385b472SRobert MustacchiThis logical SAS port has a unit address derived from the two WWNs. 126*3385b472SRobert MustacchiWhen the first phy is noted as using these WWNs, then the phymap will 127*3385b472SRobert Mustacchicall any registered callbacks as the port is created. 128*3385b472SRobert MustacchiIf additional phys come online in service of the 129*3385b472SRobert Mustacchisame port, then a new port will not be created. 130*3385b472SRobert Mustacchi.Pp 131*3385b472SRobert MustacchiTo facilitate the mapping between a PHY and the corresponding port unit 132*3385b472SRobert Mustacchiaddress, the 133*3385b472SRobert Mustacchi.Xr sas_phymap_phy2ua 9F 134*3385b472SRobert Mustacchiand 135*3385b472SRobert Mustacchi.Xr sas_phymap_lookup_ua 9F 136*3385b472SRobert Mustacchifunctions are available. 137*3385b472SRobert Mustacchi.Pp 138*3385b472SRobert MustacchiTo create a phy map, the driver uses the 139*3385b472SRobert Mustacchi.Fn sas_phymap_create 140*3385b472SRobert Mustacchifunction. 141*3385b472SRobert MustacchiThe resulting phy map will be stored in the 142*3385b472SRobert Mustacchi.Fa phymapout 143*3385b472SRobert Mustacchiargument. 144*3385b472SRobert MustacchiThe value in 145*3385b472SRobert Mustacchi.Fa settle_usec 146*3385b472SRobert Mustacchiindicates the amount of time that the system should wait to quiesce all 147*3385b472SRobert Mustacchichanges and consider the resulting system stable. 148*3385b472SRobert MustacchiChanges will not be reported until after 149*3385b472SRobert Mustacchi.Fa settle_usec 150*3385b472SRobert Mustacchihave passed. 151*3385b472SRobert Mustacchi.Pp 152*3385b472SRobert MustacchiIf a driver places a function pointer for either the 153*3385b472SRobert Mustacchi.Fa activate_cb 154*3385b472SRobert Mustacchior 155*3385b472SRobert Mustacchi.Fa deactivate cb 156*3385b472SRobert Mustacchithen those functions will be called when phys are added and removed from 157*3385b472SRobert Mustacchithe phy map. 158*3385b472SRobert Mustacchi.Pp 159*3385b472SRobert MustacchiThe value placed in the 160*3385b472SRobert Mustacchi.Fa phymap_priv 161*3385b472SRobert Mustacchiargument will be passed to both callback functions. 162*3385b472SRobert Mustacchi.Pp 163*3385b472SRobert MustacchiTo destroy a phymap, the driver should call the 164*3385b472SRobert Mustacchi.Fn sas_phymap_destroy 165*3385b472SRobert Mustacchifunction. 166*3385b472SRobert MustacchiA side effect of this is that all existing entries in the phy 167*3385b472SRobert Mustacchimap will be removed and their deactivate callbacks will fire. 168*3385b472SRobert Mustacchi.Ss Callbacks 169*3385b472SRobert MustacchiThe phymap provides a means for receiving callbacks when the addition of 170*3385b472SRobert Mustacchia phy causes a new logical port to be created or when the phy being 171*3385b472SRobert Mustacchiremoved is the last phy that is a member of the port. 172*3385b472SRobert MustacchiUnlike with the 173*3385b472SRobert Mustacchi.Xr tgtmap 9 , 174*3385b472SRobert Mustacchithere is no system managed driver that is attached with the phymap. 175*3385b472SRobert MustacchiFor the phymap to be useful to drivers, the callbacks should generally 176*3385b472SRobert Mustacchibe registered. 177*3385b472SRobert Mustacchi.Pp 178*3385b472SRobert MustacchiIt's important to emphasize that the callbacks do not represent phys, 179*3385b472SRobert Mustacchibut instead the logical port that they are bound to. 180*3385b472SRobert MustacchiThis is different 181*3385b472SRobert Mustacchifrom the 182*3385b472SRobert Mustacchi.Xr tgtmap 9 183*3385b472SRobert Mustacchiand 184*3385b472SRobert Mustacchi.Xr iportmap 9 . 185*3385b472SRobert MustacchiCalls to the 186*3385b472SRobert Mustacchi.Fn sas_phymap_phy_add 187*3385b472SRobert Mustacchiand 188*3385b472SRobert Mustacchi.Fn sas_phymap_phy_rem 189*3385b472SRobert Mustacchifunctions may not result in anything being created in the system. 190*3385b472SRobert Mustacchi.Pp 191*3385b472SRobert MustacchiThe 192*3385b472SRobert Mustacchi.Fa activate_cb 193*3385b472SRobert Mustacchicallback occurs whenever a new logical port is created because the first 194*3385b472SRobert Mustacchiphy that references that pair of WWNs has been created. 195*3385b472SRobert MustacchiThe 196*3385b472SRobert Mustacchi.Fa phymap_priv 197*3385b472SRobert Mustacchiargument corresponds to the value passed in the 198*3385b472SRobert Mustacchi.Fn sas_phymap_create 199*3385b472SRobert Mustacchifunction. 200*3385b472SRobert Mustacchi.Pp 201*3385b472SRobert MustacchiThe 202*3385b472SRobert Mustacchi.Fa ua 203*3385b472SRobert Mustacchiargument is a unit-address string that the system constructs based on 204*3385b472SRobert Mustacchithe WWNs passed in the 205*3385b472SRobert Mustacchi.Fa local 206*3385b472SRobert Mustacchiand 207*3385b472SRobert Mustacchi.Fa remote 208*3385b472SRobert Mustacchiarguments to the 209*3385b472SRobert Mustacchi.Fn sas_phymap_phy_add 210*3385b472SRobert Mustacchifunction. 211*3385b472SRobert MustacchiIf this is being used together with an 212*3385b472SRobert Mustacchi.Xr iportmap 9 213*3385b472SRobert Mustacchithen the 214*3385b472SRobert Mustacchi.Fa ua 215*3385b472SRobert Mustacchishould be the name of the added iport. 216*3385b472SRobert Mustacchi.Pp 217*3385b472SRobert MustacchiThe 218*3385b472SRobert Mustacchi.Fa ua_privp 219*3385b472SRobert Mustacchiargument allows for data to be correlated with the unit-address. 220*3385b472SRobert MustacchiThis data is accessible throughout the lifetime of the unit-address 221*3385b472SRobert Mustacchithrough the 222*3385b472SRobert Mustacchi.Xr sas_phymap_lookup_uapriv 9F 223*3385b472SRobert Mustacchifunction and is also made available during the deactivate callback. 224*3385b472SRobert Mustacchi.Pp 225*3385b472SRobert MustacchiThe 226*3385b472SRobert Mustacchi.Fa deactivate_cb 227*3385b472SRobert Mustacchicallback occurs when the logical port is being removed, because the last 228*3385b472SRobert Mustacchiassociated phy has been removed. 229*3385b472SRobert MustacchiThe arguments to this are the same as to the activate callback, with the 230*3385b472SRobert Mustacchiexception that the 231*3385b472SRobert Mustacchi.Fa ua_priv 232*3385b472SRobert Mustacchiargument is the value that was stored in the 233*3385b472SRobert Mustacchi.Fa ua_privp 234*3385b472SRobert Mustacchiargument of the activate callback. 235*3385b472SRobert Mustacchi.Ss Adding and Removing PHYs 236*3385b472SRobert MustacchiTo add a phy to the system, the driver should call the 237*3385b472SRobert Mustacchi.Fn sas_phymap_phy_add 238*3385b472SRobert Mustacchifunction. 239*3385b472SRobert MustacchiThe 240*3385b472SRobert Mustacchi.Fa phy 241*3385b472SRobert Mustacchiargument should indicate the phy identifier of the phy that has come up. 242*3385b472SRobert MustacchiThe 243*3385b472SRobert Mustacchi.Fa local 244*3385b472SRobert MustacchiWWN generally corresponds to the SAS port on the controller, while the 245*3385b472SRobert Mustacchi.Fa remote 246*3385b472SRobert MustacchiWWN is whatever device is on the other side of the phy. 247*3385b472SRobert MustacchiThe system enforces that a given phy only maps to a single port at any 248*3385b472SRobert Mustacchitime. 249*3385b472SRobert Mustacchi.Pp 250*3385b472SRobert MustacchiWhen a phy goes offline, then the driver should call the 251*3385b472SRobert Mustacchi.Fn sas_phymap_phy_rem 252*3385b472SRobert Mustacchifunction using the same phy identifier that it used when adding the phy. 253*3385b472SRobert MustacchiIf this is the last phy that was used for this logical port, then the 254*3385b472SRobert Mustacchicorresponding logical port will be removed and the deactivate callback 255*3385b472SRobert Mustacchifunction, if registered, will be called. 256*3385b472SRobert Mustacchi.Sh CONTEXT 257*3385b472SRobert MustacchiThe 258*3385b472SRobert Mustacchi.Fn sas_phymap_create 259*3385b472SRobert Mustacchiand 260*3385b472SRobert Mustacchi.Fn sas_phymap_destroy 261*3385b472SRobert Mustacchifunctions are generally called during an HBA driver's 262*3385b472SRobert Mustacchi.Xr attach 9E 263*3385b472SRobert Mustacchiand 264*3385b472SRobert Mustacchi.Xr detach 9E 265*3385b472SRobert Mustacchientry points, though may be called by a driver from 266*3385b472SRobert Mustacchi.Sy user 267*3385b472SRobert Mustacchior 268*3385b472SRobert Mustacchi.Sy kernel 269*3385b472SRobert Mustacchicontext. 270*3385b472SRobert Mustacchi.Pp 271*3385b472SRobert MustacchiThe optional 272*3385b472SRobert Mustacchi.Fn activate_cb 273*3385b472SRobert Mustacchiand 274*3385b472SRobert Mustacchi.Fn deactivate_cb 275*3385b472SRobert Mustacchifunctions for a phymap will be called into the driver from 276*3385b472SRobert Mustacchi.Sy kernel 277*3385b472SRobert Mustacchicontext. 278*3385b472SRobert Mustacchi.Pp 279*3385b472SRobert MustacchiThe 280*3385b472SRobert Mustacchi.Fn sas_phymap_phy_add 281*3385b472SRobert Mustacchiand 282*3385b472SRobert Mustacchi.Fn sas_phymap_phy_rem 283*3385b472SRobert Mustacchifunctions may be called from 284*3385b472SRobert Mustacchi.Sy user 285*3385b472SRobert Mustacchior 286*3385b472SRobert Mustacchi.Sy kernel 287*3385b472SRobert Mustacchicontext. 288*3385b472SRobert Mustacchi.Sh RETURN VALUES 289*3385b472SRobert MustacchiUpon successful completion, the 290*3385b472SRobert Mustacchi.Fn sas_phymap_create , 291*3385b472SRobert Mustacchi.Fn sas_phymap_phy_add , 292*3385b472SRobert Mustacchiand 293*3385b472SRobert Mustacchi.Fn sas_phymap_phy_rem 294*3385b472SRobert Mustacchifunctions return 295*3385b472SRobert Mustacchi.Dv DDI_SUCCESS . 296*3385b472SRobert MustacchiOtherwise, 297*3385b472SRobert Mustacchi.Dv DDI_FAILURE 298*3385b472SRobert Mustacchiis returned to indicate failure. 299*3385b472SRobert Mustacchi.Sh SEE ALSO 300*3385b472SRobert Mustacchi.Xr iportmap 9 , 301*3385b472SRobert Mustacchi.Xr phymap 9 , 302*3385b472SRobert Mustacchi.Xr tgtmap 9 , 303*3385b472SRobert Mustacchi.Xr attach 9E , 304*3385b472SRobert Mustacchi.Xr detach 9E , 305*3385b472SRobert Mustacchi.Xr sas_phymap_lookup_ua 9F , 306*3385b472SRobert Mustacchi.Xr sas_phymap_lookup_uapriv 9F , 307*3385b472SRobert Mustacchi.Xr sas_phymap_phy2ua 9F 308