share/man/man9f/scsi_hba_iportmap_create.9f

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