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 18, 2017 15.Dt SCSI_HBA_IPORTMAP_CREATE 9F 16.Os 17.Sh NAME 18.Nm scsi_hba_iportmap_create , 19.Nm scsi_hba_iportmap_destroy , 20.Nm scsi_hba_iportmap_iport_add , 21.Nm scsi_hba_iportmap_iport_remove 22.Nd create and manage an iportmap 23.Sh SYNOPSIS 24.In sys/scsi/scsi.h 25.Ft int 26.Fo scsi_hba_iportmap_create 27.Fa "dev_info_t *dip" 28.Fa "int csync_usec" 29.Fa "int settle_usec" 30.Fa "scsi_hba_iportmap_t **iportmapout" 31.Fc 32.Ft void 33.Fo scsi_hba_iportmap_destroy 34.Fa "scsi_hba_iportmap_t *iportmap" 35.Fc 36.Ft int 37.Fo scsi_hba_iportmap_iport_add 38.Fa "scsi_hba_iportmap_t *iportmap" 39.Fa "char *ua" 40.Fa "void *priv" 41.Fc 42.Ft int 43.Fo scsi_hba_iportmap_iport_remove 44.Fa "scsi_hba_iportmap_t *iportmap" 45.Fa "char *ua" 46.Fc 47.Sh INTERFACE LEVEL 48.Sy Evolving - 49This interface is still evolving in illumos. 50API and ABI stability is not guaranteed. 51.Sh PARAMETERS 52.Bl -tag -width Fa 53.It Fa dip 54Pointer to 55.Vt dev_info 56structure. 57.It Fa csync_usec 58A time in microseconds. 59.It Fa settle_usec 60A time in microseconds. 61.It Fa iportmap 62An allocated iportmap. 63.It Fa iportmapout 64Pointer where the iportmap is stored. 65.It Fa ua 66A character string that represents a unit address for an iport. 67.It Fa priv 68Drivers should pass 69.Dv NULL 70for this field. 71.El 72.Sh DESCRIPTION 73The 74.Fn scsi_hba_iportmap_create 75and 76.Fn scsi_hba_iportmap_destroy 77functions are used by HBA drivers to create and destroy an iportmap. 78For more information on an iportmap and its purpose, see 79.Xr iportmap 9 . 80.Pp 81The 82.Fa csync_usec 83and 84.Fa settle_usec 85are both times measured in microseconds that control two different 86properties of the iportmap and how it behaves. 87The value in 88.Fa settle_usec 89indicates the amount of time that the system should wait to quiesce all 90changes and consider the resulting system stable. 91Changes will not be reported until after 92.Fa settle_usec 93have passed. 94.Fa csync_usec 95indicates how much time needs to elapse after creation before an initial 96enumeration has been completed. 97.Pp 98The 99.Vt dev_info 100structure passed into 101.Fa dip 102is usually the HBA driver's 103.Vt dev_info 104structure. 105.Pp 106When the 107.Fn scsi_hba_iportmap_iport 108function returns, 109.Fa iportmapout 110will be populated with a pointer to an iportmap that can be used to add 111and remove iports. 112.Pp 113To destroy the iportmap, drivers should use the 114.Fn scsi_hba_iportmap_destroy 115function. 116As part of destroying the iportmap, all associated iports will 117be detached from the system by having the driver's 118.Xr detach 9E 119entry point called. 120.Pp 121When the driver needs to add an iport to the system, generally in 122response to a hotplug event, then the driver should call the 123.Fn scsi_hba_iportmap_iport_add 124function. 125The value of 126.Fa ua 127should be a character string that uniquely identifies the device. 128If the driver is using a phymap, then this unit address should be the 129same one as the phymap's callback provided. 130Otherwise, the driver sets 131.Fa ua 132to a unique string which is generally the iport's WWN. 133.Pp 134When the corresponding iport needs to be removed, then the driver should 135call the 136.Fn scsi_hba_iportmap_remove 137function. 138The iport to remove is indicated by the 139.Fa ua 140argument, which should match the value passed into the 141.Fn scsi_hba_iportmap_add 142function. 143.Sh CONTEXT 144The 145.Fn scsi_hba_iportmap_create 146function is generally called during a driver's 147.Xr attach 9E 148entry point. 149.Pp 150The 151.Fn scsi_hba_iportmap_destroy 152function is generally called during a driver's 153.Xr detach 9E 154entry point. 155.Pp 156The 157.Fn scsi_hba_iportmap_iport_add 158and 159.Fn scsi_hba_iportmap_iport_remove 160functions should be called from 161.Sy kernel 162context. 163.Sh RETURN VALUES 164Upon successful completion, the 165.Fn scsi_hba_iportmap_create , 166.Fn scsi_hba_iportmap_iport_add , 167and 168.Fn scsi_hba_iportmap_iport_remove 169functions return 170.Dv DDI_SUCCESS. 171Otherwise, 172.Dv DDI_FAILURE 173is returned. 174.Sh SEE ALSO 175.Xr iport 9 , 176.Xr iportmap 9 , 177.Xr attach 9E , 178.Xr detach 9E 179