share/man/man9/iport.9

   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 IPORT 9
  16 .Os
  17 .Sh NAME
  18 .Nm iport ,
  19 .Nm iportmap ,
  20 .Nm phymap ,
  21 .Nm tgtmap
  22 .Nd SCSI Device Management Concepts
  23 .Sh DESCRIPTION
  24 The
  25 .Sy iport ,
  26 .Sy iportmap ,
  27 .Sy phymap ,
  28 and
  29 .Sy tgtmap
  30 abstractions enable host bus adapter (HBA) drivers to represent the
  31 devices that they are responsible for enumerating, as well as the
  32 relationships between these devices.
  33 These interfaces simplify device drivers by taking care of the creation
  34 and destruction of device nodes in the devices tree for enumerated
  35 devices as well as performing some amount of hysteresis.
  36 .Pp
  37 These abstractions are used in tandem with SCSI complex addressing.
  38 A device driver that uses these interfaces generally passes both the
  39 .Dv SCSI_HBA_HBA
  40 flag and the
  41 .Dv SCSI_HBA_ADDR_COMPLEX
  42 in the
  43 .Fa hba_flags
  44 argument to
  45 .Xr scsi_hba_attach_setup 9F .
  46 .Ss iport
  47 The
  48 .Sy iport ,
  49 or initiator port, abstracts a collection of attached devices.
  50 One way to view an iport is that each iport maps to a phy on the HBA.
  51 A phy refers to a physical connector between the HBA and devices.
  52 A phy may be made up of individual lanes.
  53 A lane is connected to a device, for example a disk driver.
  54 Multiple lanes maybe plugged into the same device, for example, an
  55 expander.
  56 When a phy connects to a device with a single lane, this is often
  57 called a
  58 .Em narrow phy .
  59 When a phy connects to a device with multiple lanes, this is often
  60 called a
  61 .Em wide phy .
  62 .Pp
  63 Consider a device that has two physical ports, and thus two phys.
  64 Each phy has four lanes, thus we describe the phy as having a mask of
  65 0xf.
  66 Each bit in the mask corresponds to a specific lane.
  67 In this example, each phy would be represented in the system by an iport
  68 and may enumerate a different device for each lane of the phy.
  69 If an expander is attached to one or more of the lanes of a phy, then
  70 additional devices will be enumerated under the expander and be added to
  71 that phy's iport.
  72 .Pp
  73 Another example to consider is when each lane of a phy is directly
  74 connected to a single disk through a passive backplane.
  75 In this case, each lane may represent its own iport, since the
  76 management of each is independent, basically there are many devices each
  77 with a mask of 0x1.
  78 .Pp
  79 iports do not need to map to a physical phy.
  80 Some HBAs support a combination of both physical and virtual devices.
  81 In that case, the driver may create two different iports, one for the
  82 physical devices and one for the virtual devices.
  83 .Pp
  84 One property of iports is that they're attached separately from the main
  85 device and therefore have their own
  86 .Xr scsi_hba_tran 9S
  87 structure.
  88 As a result, that means that a driver can provide different
  89 entry points for each iport, especially if they represent different
  90 classes of resources, for example one iport for all physical devices and
  91 one for all virtual devices.
  92 This allows for a driver to return different capabilities, among other
  93 behaviors and entry points, for these different iports.
  94 One specific case of this is that while physical devices may provide a
  95 means to get to a SCSI WWN, virtual devices may not have a WWN and
  96 instead must use a different addressing format.
  97 .Pp
  98 iports are considered children of the device driver that attach them,
  99 but they are bound to the same driver.
 100 This means that when an iport is created, the
 101 .Xr attach 9E
 102 and
 103 .Xr probe 9E
 104 entry points of the parent driver (usually indicated by passing a
 105 .Vt dev_info
 106 structure) will be called.
 107 Similarly, when an iport is removed from the system, then the driver's
 108 .Xr detach 9E
 109 entry point will be called.
 110 A driver can determine whether an iport is being attached or not by
 111 calling the
 112 .Xr scsi_hba_iport_unit_address 9F
 113 function.
 114 The value will return
 115 .Dv NULL
 116 if the attaching device represents the driver.
 117 .Pp
 118 To manage iports, drivers have two different options.
 119 If the set of iport an HBA supports are static, then they should use the
 120 .Xr scsi_hba_iport_register 9F
 121 function to register an iport.
 122 .Pp
 123 If instead, the set of iports are dynamic and map to the coming and
 124 going of phys discovered by the driver (or some other dynamic source),
 125 then the driver should use the iportmap set of functions.
 126 See the section
 127 .Sx phymap and iportmap
 128 for more information.
 129 .Ss tgtmap
 130 The target map represents a set of devices that have been enumerated
 131 under an iport.
 132 Each device is represented by a string, which is an address of some
 133 kind.
 134 Usually a physical device's WWN is used.
 135 .Pp
 136 By using a target map, the operating system will take
 137 responsibility for notifying the driver when devices have come and gone
 138 from a target map, once it has settled, and it will also take
 139 responsibility for having device nodes come and go, meaning that the
 140 device driver does not need to know anything about the devices tree or
 141 worry about other parts of being a nexus driver.
 142 .Pp
 143 Target maps come in two forms which change how the HBA driver is
 144 responsible for reporting changes:
 145 .Bl -enum
 146 .It
 147 Full-set
 148 .It
 149 Per-address
 150 .El
 151 .Pp
 152 In the full-set mode, the driver always reports the full set of current
 153 devices that it sees.
 154 When the driver finishes the report, the operating system will inform
 155 the driver of addresses that were added and addresses that were removed.
 156 These addresses correspond to newly found devices and recently removed
 157 devices, respectively.
 158 The full-set mode allows for a simpler device driver, particularly if
 159 addition and removal notifications may be dropped by the hardware.
 160 .Pp
 161 When using the per-address mode of a target map, the HBA driver is
 162 responsible for indicating which addresses have come and gone from the
 163 system.
 164 .Pp
 165 In either mode, the driver will receive two callbacks, if they have been
 166 registered when the target map was created.
 167 The first callback fires before a target driver like sd, ses, etc. is
 168 attached.
 169 The second callback fires after the corresponding driver has been
 170 attached.
 171 These allow the HBA driver to perform any operations that are
 172 required on the devices.
 173 .Pp
 174 Each target map has two different sets of devices that it manages in
 175 this form.
 176 The devices are separated into the following groups:
 177 .Bl -enum
 178 .It
 179 SCSI Devices
 180 .It
 181 SMP (SCSI Management Protocol) devices
 182 .El
 183 .Pp
 184 All SATA, SCSI, SAS, SES, etc. devices all are considered part of the
 185 first category.
 186 .Pp
 187 Target maps can be created and destroyed with the
 188 .Xr scsi_hba_tgtmap_create 9F
 189 and
 190 .Xr scsi_hba_tgtmap_destroy 9F
 191 functions.
 192 .Pp
 193 The following functions are used to manage target maps operating in
 194 full-set mode:
 195 .Bl -dash
 196 .It
 197 .Xr scsi_hba_tgtmap_set_begin 9F
 198 .It
 199 .Xr scsi_hba_tgtmap_set_add 9F
 200 .It
 201 .Xr scsi_hba_tgtmap_set_end 9F
 202 .It
 203 .Xr scsi_hba_tgtmap_set_flush 9F
 204 .El
 205 .Pp
 206 The following functions are used to manage target maps operating in
 207 per-address mode:
 208 .Bl -dash
 209 .It
 210 .Xr scsi_hba_tgtmap_tgt_add 9F
 211 .It
 212 .Xr scsi_hba_tgtmap_tgt_remove 9F
 213 .El
 214 .Ss phymap and iportmap
 215 The phymap and iportmap are often used together to represent complex SAS
 216 topologies.
 217 The phymap provides a way to see what phys have been grouped together
 218 under the same SAS port.
 219 The SAS port is represented by the
 220 .Dq local
 221 and
 222 .Dq remote
 223 WWNs.
 224 When additional phys come online, if they end up referring to the
 225 same WWNs, then they'll map to the same port.
 226 .Pp
 227 The iportmap is used to maintain a dynamic set of iports related to a
 228 device.
 229 The iports are each identified by an address, which is generally
 230 a unit address string.
 231 For example, when a new phy is added to the phymap which represents a
 232 new SAS port being used, then a corresponding iport will be created and
 233 associated with that entry from the phymap.
 234 Once the iport has been created, a normal target map can be created on
 235 top of it to handle detected SCSI and SMP devices.
 236 .Pp
 237 Both the phymap and iportmap operate in a similar fashion to the
 238 per-address mode of a tgtmap.
 239 Entries can be added and removed through direct functions.
 240 The phymap provides callbacks similar to the tgtmap; however, the
 241 iportmap does not.
 242 This is because when an iport is added or removed, a new node is added
 243 to the devices tree and the driver's
 244 .Xr attach 9E
 245 entry point is called with a new
 246 .Vt dev_info_t
 247 structure representing the iport.
 248 .Pp
 249 During the phymap callback, the HBA driver should create a new iport
 250 with the unit address passed in from the callback function.
 251 This relationship is important when taking advantage of the ability to
 252 map between an iport and the set of phys that it represents.
 253 .Pp
 254 The following functions are used to manage iportmaps:
 255 .Bl -dash
 256 .It
 257 .Xr scsi_hba_iportmap_create 9F
 258 .It
 259 .Xr scsi_hba_iportmap_iport_add 9F
 260 .It
 261 .Xr scsi_hba_iportmap_iport_remove 9F
 262 .It
 263 .Xr scsi_hba_iportmap_destroy 9F
 264 .El
 265 .Pp
 266 The following functions are used to manage phymaps:
 267 .Bl -dash
 268 .It
 269 .Xr sas_phymap_create 9F
 270 .It
 271 .Xr sas_phymap_destroy 9F
 272 .It
 273 .Xr sas_phymap_phy_add 9F
 274 .It
 275 .Xr sas_phymap_phy_rem 9F
 276 .El
 277 .Ss SCSI Complex Addressing
 278 Traditionally, SCSI devices were represented by a simple structure, the
 279 .Xr scsi_address 9S .
 280 This represented devices by a simple target and lun number.
 281 While this interface is useful for simple devices and traditional
 282 parallel SCSI devices, it is not as useful for SAS-era devices where the
 283 SCSI bus is now a fabric.
 284 A driver may opt into such a complex addressing mode by setting the
 285 .Dv SCSI_HBA_ADDR_COMPLEX
 286 flag.
 287 .Pp
 288 When this flag is set, the HBA driver must treat the SCSI address
 289 as an opaque structure.
 290 Once in this mode, the driver may get and set a private data structure
 291 on the SCSI device.
 292 This is facilitated by the
 293 .Xr scsi_device_hba_private_set 9F
 294 and
 295 .Xr scsi_device_hba_private_get 9F
 296 functions.
 297 In addition, the system provides a means to map between the
 298 .Xr scsi_address 9S
 299 structure and the corresponding
 300 .Xr scsi_device 9S
 301 structure.
 302 This is performed by the
 303 .Xr scsi_device_unit_address 9F
 304 function.
 305 .Sh SEE ALSO
 306 .Xr attach 9E ,
 307 .Xr detach 9E ,
 308 .Xr sas_phymap_create 9F ,
 309 .Xr sas_phymap_destroy 9F ,
 310 .Xr sas_phymap_phy_add 9F ,
 311 .Xr sas_phymap_phy_rem 9F ,
 312 .Xr scsi_device_hba_private_get 9F ,
 313 .Xr scsi_device_hba_private_set 9F ,
 314 .Xr scsi_device_unit_address 9F ,
 315 .Xr scsi_hba_attach_setup 9F ,
 316 .Xr scsi_hba_iport_register 9F ,
 317 .Xr scsi_hba_iport_unit_address 9F ,
 318 .Xr scsi_hba_iportmap_create 9F ,
 319 .Xr scsi_hba_iportmap_destroy 9F ,
 320 .Xr scsi_hba_iportmap_iport_add 9F ,
 321 .Xr scsi_hba_iportmap_iport_remove 9F ,
 322 .Xr scsi_hba_tgtmap_create 9F ,
 323 .Xr scsi_hba_tgtmap_destroy 9F ,
 324 .Xr scsi_hba_tgtmap_set_add 9F ,
 325 .Xr scsi_hba_tgtmap_set_begin 9F ,
 326 .Xr scsi_hba_tgtmap_set_end 9F ,
 327 .Xr scsi_hba_tgtmap_set_flush 9F ,
 328 .Xr scsi_hba_tgtmap_tgt_add 9F ,
 329 .Xr scsi_hba_tgtmap_tgt_remove 9F ,
 330 .Xr scsi_address 9S ,
 331 .Xr scsi_device 9S ,
 332 .Xr scsi_hba_tran 9S