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