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_LOOKUP_UA 9F 16.Os 17.Sh NAME 18.Nm sas_phymap_lookup_ua , 19.Nm sas_phymap_lookup_uapriv , 20.Nm sas_phymap_phy2ua , 21.Nm sas_phymap_ua_free , 22.Nm sas_phymap_uahasphys , 23.Nm sas_phymap_ua2phys , 24.Nm sas_phymap_phys_next , 25.Nm sas_phymap_phys_free 26.Nd SAS phymap utility functions 27.Sh SYNOPSIS 28.In sys/scsi/scsi.h 29.Ft "char *" 30.Fo sas_phymap_lookup_ua 31.Fa "sas_phymap_t *phymap" 32.Fa "uint64_t local" 33.Fa "uint64_t remote" 34.Fc 35.Ft "void *" 36.Fo sas_phymap_lookup_uapriv 37.Fa "sas_phymap_t *phymap" 38.Fa "char *ua" 39.Fc 40.Ft int 41.Fo sas_phymap_uahasphys 42.Fa "sas_phymap_t *phymap" 43.Fa "char *ua" 44.Fc 45.Ft "char *" 46.Fo sas_phymap_phy2ua 47.Fa "sas_phymap_t *phymap" 48.Fa "int phy" 49.Fc 50.Ft void 51.Fo sas_phymap_ua_free 52.Fa "char *ua" 53.Fc 54.Ft "sas_phymap_phys_t *" 55.Fo sas_phymap_ua2phys 56.Fa "sas_phymap_t *phymap" 57.Fa "char *ua" 58.Fc 59.Ft int 60.Fo sas_phymap_phys_next 61.Fa "sas_phymap_phys_t *phys" 62.Fc 63.Ft void 64.Fo sas_phymap_phys_free 65.Fa "sas_phymap_phys_t *phys" 66.Fc 67.Sh INTERFACE LEVEL 68.Sy Evolving - 69This interface is still evolving in illumos. 70API and ABI stability is 71not guaranteed. 72.Sh PARAMETERS 73.Bl -tag -width Fa 74.It Fa phymap 75Pointer to an allocated phy map. 76.It Fa local 77The World Wide Number (WWN) of the HBA-owned side of the phy. 78.It Fa remote 79The World Wide Number (WWN) of the device that is plugged into the phy. 80.It Fa ua 81A character string that indicates the system generated unit address for 82the logical port. 83.It Fa phy 84A non-negative integer that uniquely identifies a phy on a device. 85.It Fa phys 86An opaque structure that represents a collection of phys on a port. 87.El 88.Sh DESCRIPTION 89The functions described here are all utility functions for operating on 90a phymap and the entities it creates. 91 For more information on phymaps, 92see 93.Xr phymap 9 94and 95.Xr sas_phymap_create 9F . 96.Pp 97The 98.Fn sas_phymap_lookup_ua 99function finds the unit address of the logical port that corresponds to 100the tuple of the 101.Fa local 102and 103.Fa remote 104WWN. 105If a logical port exists for that tuple, then a pointer to its 106system generated unit-address is returned. 107This string is managed by the system and it must not be modified or freed. 108If it cannot be found, then 109.Dv NULL 110is returned. 111.Pp 112The 113.Fn sas_phymap_lookup_uapriv 114function returns the private value that was stored during the activate 115callback of the logical port represented by the unit address 116.Fa ua 117that is a part of the phymap 118.Fa phymap . 119.Pp 120The 121.Fn sas_phymap_uahasphys 122function is used to determine whether or not the logical port 123represented by the unit address specified in 124.Fa ua 125that is a part of the phymap 126.Fa phymap 127has any phys. 128If phys are found, then the function returns 129.Sy 1 . 130.Pp 131The 132.Fn sas_phymap_phy2ua 133function attempts to map a given phy specified by 134.Fa phy 135to its unit-address in the map 136.Fa phymap . 137This function will allocate memory for the character string, thus it can 138be modified. 139The caller must call the 140.Fa sas_phymap_ua_free 141function to release the memory that was allocated. 142The 143.Fa sas_phymap_ua_free 144function should not be used with the string returned from the 145.Fn sas_phymap_lookup_ua 146function. 147.Pp 148The 149.Fn sas_phymap_ua2phys 150function creates a collection of phys that exist on a given logical port 151represented by the unit-address 152.Fa ua 153in the map 154.Fa phymap . 155This set can be iterated by calling the 156.Fn sas_phyap_phys_next 157function. 158Each time the function is called, an entry is returned. 159When the value 160.Sy -1 161is returned it indicates that the set is empty. 162Regardless of whether or not the set has been iterated over, the caller 163must call the 164.Fn sas_phymap_phys_free 165function to release the memory associated with the set. 166.Sh CONTEXT 167All functions may be used in 168.Sy user , 169.Sy kernel , 170and 171.Sy interrupt 172context. 173.Sh RETURN VALUES 174Upon successful completion, the 175.Fn sas_phymap_lookup_ua 176and 177.Fn sas_phymap_phy2ua 178function returns a pointer to the unit-address. 179If the port or phy could not be found or another error occurred, then 180the function returns 181.Dv NULL . 182.Pp 183Upon successful completion, the 184.Fn sas_phymap_lookup_uapriv 185function returns a pointer to the port's private data, if any exists. 186Otherwise, if the port could not be found or another error occurred, then 187the function returns 188.Dv NULL . 189Upon successful completion, the 190.Fn sas_phymap_uahasphys 191returns 192.Sy 1 193to indicate that the unit-address has phys. 194If the unit-address has no phys, then it returns 195.Sy 0 . 196If an error occurred or the port doesn't exist, then the function returns 197.Sy 0 . 198.Pp 199Upon successful completion, the 200.Fn sas_phymap_ua2phys 201function returns a pointer to an allocated phy set. 202Otherwise, it returns 203.Dv NULL . 204.Pp 205The 206.Fn sas_phymap_phys_next 207function returns a non-negative integer indicating a present phy or it 208returns 209.Sy -1 210to indicate that no values remain. 211.Sh SEE ALSO 212.Xr phymap 9 , 213.Xr sas_phymap_create 9F 214