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_TGTMAP_CREATE 9F 16.Os 17.Sh NAME 18.Nm scsi_hba_tgtmap_create , 19.Nm scsi_hba_tgtmap_destroy , 20.Nm scsi_hba_tgtmap_set_begin , 21.Nm scsi_hba_tgtmap_set_add , 22.Nm scsi_hba_tgtmap_set_end , 23.Nm scsi_hba_tgtmap_set_flush , 24.Nm scsi_hba_tgtmap_tgt_add , 25.Nm scsi_hba_tgtmap_tgt_remove 26.Nd SCSI target map functions 27.Sh SYNOPSIS 28.In sys/scsi/scsi.h 29.Ft int 30.Fo scsi_hba_tgtmap_create 31.Fa "dev_info_t *dip" 32.Fa "scsi_tgtmap_mode_t mode" 33.Fa "int csync_usec" 34.Fa "int settle_usec" 35.Fa "void *tgtmap_priv" 36.Fa "scsi_tgt_activate_cb_t activate_cb" 37.Fa "scsi_tgt_deactivate_cb_t deactivate_cb" 38.Fa "scsi_hba_tgtmap_t *tgtmapout" 39.Fc 40.Ft void 41.Fo scsi_hba_tgtmap_destroy 42.Fa "scsi_hba_tgtmap_t *tgtmap" 43.Fc 44.Ft void 45.Fo (*scsi_tgt_activate_cb_t) 46.Fa "void *tgtmap_priv" 47.Fa "char *tgt_addr" 48.Fa "scsi_tgtmap_tgt_type_t type" 49.Fa "void **tgt_privp" 50.Fc 51.Ft boolean_t 52.Fo (*scsi_tgt_deactivate_cb_t) 53.Fa "void *tgtmap_priv" 54.Fa "char *tgt_addr" 55.Fa "scsi_tgtmap_tgt_type_t type" 56.Fa "void *tgt_priv" 57.Fa "scsi_tgtmap_deact_rsn_t deact" 58.Fc 59.Ft int 60.Fo scsi_hba_tgtmap_set_begin 61.Fa "scsi_hba_tgtmap_t *map" 62.Fc 63.Ft int 64.Fo scsi_hba_tgtmap_set_add 65.Fa "scsi_hba_tgtmap_t *tgtmap" 66.Fa "scsi_tgtmap_tgt_type_t type" 67.Fa "char *tgt_addr" 68.Fa "void *tgt_priv" 69.Fc 70.Ft int 71.Fo scsi_hba_tgtmap_set_end 72.Fa "scsi_hba_tgtmap_t *map" 73.Fc 74.Ft int 75.Fo scsi_hba_tgtmap_set_flush 76.Fa "scsi_hba_tgtmap_t *map" 77.Fc 78.Ft int 79.Fo scsi_hba_tgtmap_tgt_add 80.Fa "scsi_hba_tgtmap_t *tgtmap" 81.Fa "scsi_tgtmap_tgt_type_t type" 82.Fa "char *tgt_addr" 83.Fa "void *tgt_priv" 84.Fc 85.Ft int 86.Fo scsi_hba_tgtmap_tgt_remove 87.Fa "scsi_hba_tgtmap_t *tgtmap" 88.Fa "scsi_tgtmap_tgt_type_t type" 89.Fa "char *tgt_addr" 90.Fc 91.Sh INTERFACE LEVEL 92.Sy Evolving - 93This interface is still evolving in illumos. 94API and ABI stability is 95not guaranteed. 96.Sh PARAMETERS 97.Bl -tag -width Fa 98.It Fa dip 99Pointer to 100.Vt dev_info 101structure. 102.It Fa mode 103One of the following values: 104.Bl -tag -width Dv 105.It Dv SCSI_TM_FULLSET 106The target map operates by full-set reporting. 107.It Dv SCSI_TM_PERADDR 108The target map operates by per-address reporting. 109.El 110.It Fa csync_usec 111A time in microseconds. 112.It Fa settle_usec 113A time in microseconds. 114.It Fa tgtmap_priv 115A private value to be passed to callback functions. 116.It Fa activate_cb 117An optional callback that will be called when a new device is being 118added to the system. 119.It Fa deactivate_cb 120An optional callback that will be called when an existing devices is 121removed from the system. 122.It Fa tgtmapout 123Pointer where the target map is stored. 124.It Fa tgtmap 125Pointer to an allocated target map. 126.It Fa tgt_addr 127The address of the target map entry the callback is acting upon. 128.It Fa type 129One of the following values, indicating the type of the target: 130.Bl -tag -width Dv 131.It Dv SCSI_TGT_SCSI_DEVICE 132The target is some form of SCSI device such as a parallel SCSI, SATA, 133SAS, SES, etc. 134.It Dv SCSI_TGT_SMP_DEVICE 135The target is a SCSI Management Protocol device. 136.El 137.It Fa deact 138One of the following values, indicating why the target is being removed: 139.Bl -tag -width Dv 140.It Dv SCSI_TGT_DEACT_RSN_GONE 141The device is being deactivated because it is gone. 142.It Dv SCSI_TGT_DEACT_RSN_CFG_FAIL 143The device is being deactivated because the configuration callback 144failed. 145.It Dv SCSI_TGT_DEACT_RSN_UNSTBL 146The device is being deactivated because it was added and removed during 147the stabilization period and therefore is considered unstable. 148.El 149.El 150.Sh DESCRIPTION 151The 152.Fn scsi_hba_tgtmap_create 153and 154.Fn scsi_hba_tgtmap_destroy 155functions are used to create and destroy target maps. 156A target map is used to manage SCSI and SMP (SCSI Management Protocol) 157devices. 158For more background on target maps, see 159.Xr tgtmap 9 . 160.Pp 161To create a target map, the driver should call the 162.Fn scsi_hba_tgtmap_create 163function. 164Upon successful completion, a pointer to the target map will be placed 165in the 166.Fa tgtmapout 167argument. 168.Pp 169The 170.Fa dip 171argument should correspond to the HBA driver's device node or one of its 172iports. 173.Pp 174The 175.Fa mode 176argument describes how addresses are reported into the target map and 177the functions used to add and remove devices. 178If 179.Fa mode 180is 181.Dv SCSI_TM_FULLSET 182then the driver must always report all the devices that are in the set 183and will be told when the corresponding devices have been removed. 184See 185the section 186.Sx Full-Set Reporting 187for more information. 188.Pp 189Otherwise, the driver should set the 190.Fa mode 191argument to 192.Dv SCSI_TM_PERADDR 193and use the 194.Fn scsi_hba_tgtmap_tgt_add 195and 196.Fn scsi_hba_tgtmap_tgt_destroy 197functions. 198See the section 199.Sx Per-Address Reporting 200for more information. 201.Pp 202The 203.Fa csync_usec 204and 205.Fa settle_usec 206are both times measured in microseconds that control two different 207properties of the target map and how it behaves. 208The value in 209.Fa settle_usec 210indicates the amount of time that the system should wait to quiesce all 211changes and consider the resulting system stable. 212Changes will not be reported until after 213.Fa settle_usec 214have passed. 215.Fa csync_usec 216indicates how much time needs to elapse after creation before an initial 217enumeration has been completed. 218.Pp 219The 220.Fa activate_cb 221and 222.Fa deactivate_cb 223arguments are optional function pointers that will be run in the context 224of devices being added and removed from the system. 225This allows the HBA driver to perform any required operations prior to 226the system attaching a target driver such as 227.Xr sd 7D 228or 229.Xr ses 7D 230in the activate case and after the system has detached the driver, in 231the removal case. 232.Pp 233To destroy a target map, a caller should use the 234.Fn scsi_hba_tgtmap_destroy 235function. 236Destroying a target map causes all currently present devices 237to be deactivated, as though they were removed, prior to the 238final destruction of the target map. 239.Ss Callbacks 240Target maps allow for callbacks to be registered and called when 241devices are being added and removed from the system. 242A driver specifies these when the target map is created by passing in 243function pointers to 244the 245.Fn activate_cb 246and 247.Fn deactivate_cb 248arguments. 249.Pp 250When a new address is registered in a target map and the driver has 251specified a function in the 252.Fa activate_cb 253argument, the driver will eventually have their activation function 254called. 255This call will be asynchronous with respect to the adding and 256removing of entries, regardless of whether the target map is using 257per-address or full-set reporting. 258This call will occur before any driver is bound to the discovered 259address. 260.Pp 261The 262.Fa tgtmap_priv 263argument will point to the optional, private argument that was passed 264to the 265.Fn scsi_hba_tgtmap_create 266function when the target map was created. 267The 268.Fa tgt_addr 269and 270.Fa tgt_type 271will describe the address and type of the new device and will correspond 272with the values passed into either the 273.Fn scsi_hba_tgtmap_set_add 274or 275.Fn scsi_hba_tgtmap_tgt_add 276functions. 277.Pp 278The 279.Fa tgt_privp 280argument is a modifiable private value. 281Initially, 282.Fa tgt_privp 283points to the value passed in as 284.Fa tgt_priv 285to either the 286.Fn scsi_hba_tgtmap_set_add 287or 288.Fn scsi_hba_tgtmap_tgt_add 289functions. 290The driver may change the value as needed. 291It will receive the value stored in 292.Fa tgt_privp 293during the deactivate callback. 294.Pp 295When a target map has been updated to indicate that a device has been 296removed, then the driver will receive a deactivation callback if it 297registered one. 298The deactivate callback will occur after a driver has 299been detached from the corresponding device. 300.Pp 301The 302.Fa tgtmap_priv , 303.Fa tgt_addr , 304and 305.Fa type 306arguments to the callback function are the same as for the activate 307case. 308The 309.Fa tgt_priv 310pointer will be set to the value that was passed when the device was 311added and will reflect any updates made during an activate callback, if 312present. 313.Pp 314The 315.Fa deact 316argument gives the driver some amount of information as to why device 317was being removed. 318The deactivation reason provides the driver 319more information about why the address was being removed from the target 320map which can be useful in the cases that it itself did not issue it. 321.Pp 322The return value indicates whether or not some amount of rediscovery of 323the address is desired or not. 324This is only meaningful in the case where the 325.Fa deact 326argument was 327.Dv SCSI_TGT_DEACT_RSN_CFG_FAIL . 328If the driver does wish to attempt rediscovery, then it should return 329.Dv B_TRUE . 330Otherwise, the driver should return 331.Dv B_FALSE . 332If in doubt, use the return value 333.Dv B_FALSE . 334Note, even if the driver returns 335.Dv B_TRUE , 336no action may be taken by the system. 337.Ss Full-Set Reporting 338Full-Set reporting is one way of managing a target map. 339In full-set reporting, whenever an update is being made, the entire data 340set is reported to the target map. 341The target map then determines which 342addresses are new, which have been removed, and which have stayed the 343same and updates the system state appropriately. 344If devices have been added or removed from the system, then any activate 345and deactivate endpoints will be called. 346.Pp 347To begin a new report, the driver should call the 348.Fn scsi_hba_tgtmap_set_begin 349function. 350Once the report has begun, the driver should add devices by calling the 351.Fn scsi_hba_tgtmap_set_add 352function. 353Once all devices have been added, the driver should call the 354.Fn scsi_hba_tgtmap_set_end 355function to indicate that the target map processing has ended. 356If driver wishes to discard a report that has begun, but not yet 357terminated, then the driver should call the 358.Fn scsi_hba_tgtmap_set_flush 359function. 360.Pp 361When adding entries, the driver should indicate the address of the 362device in 363.Fa tgt_addr . 364This will generally be a world wide number (WWN) in a unit-addressable 365form. 366However, the driver may use its own synthetic numbering. 367This address will be passed to the activate callbacks and will also be 368used as the address of the 369.Xr scsi_device 9S 370in the 371.Xr tran_start 9E 372entry point. 373.Pp 374The 375.Fa type 376argument indicates how the kernel will interpret the type of device. 377At this time, devices are broken into two broad categories. 378Things which are some kind of SCSI device, whether parallel, SCSI, SATA 379behind a SATL, SES, etc. should use the type 380.Dv SCSI_TGT_SCSI_DEVICE . 381The other group, 382.Dv SCSI_TGT_SMP_DEVICE , 383is for SCSI Management Protocol (SMP) devices. 384.Pp 385The 386.Fa tgt_priv 387argument will be passed to the activate and deactivate callbacks, 388allowing the driver to pass around data corresponding to this address. 389.Ss Per-Address Reporting 390When using a target map with per-address reporting, the driver is 391responsible for indicating what devices have been added and removed. 392This is useful for various hardware configurations where all entries and 393removals are processes in a highly-reliable fashion where hardware 394cannot drop entries. 395.Pp 396To add a new device, the driver should call the 397.Fa scsi_hba_tgtmap_tgt_add 398function. 399The 400.Fa tgt_addr 401and 402.Fa type 403arguments describe the address and what kind of device the address 404corresponds to. 405For more information, see the previous section, 406.Sx Full-Address Reporting . 407The 408.Fa tgt_priv 409argument will be passed along to the activate and deactivate functions, 410allowing the driver to associate a value with the address in question. 411.Pp 412When a device has been removed, the driver should call the 413.Fn scsi_hba_tgtmap_tgt_remove 414function, ensuring that both the 415.Fa tgt_addr 416and 417.Fa type 418arguments match those that were used when calling the 419.Fn scsi_hba_tgtmap_tgt_add 420function. 421.Sh CONTEXT 422The 423.Fn scsi_hba_tgtmap_create 424and 425.Fn scsi_hba_tgtmap_destroy 426functions are generally called from the context of the 427.Xr attach 9E 428and 429.Xr detach 9E 430entry points of HBA drivers and their iports, though may also be called 431from 432.Sy user 433or 434.Sy kernel 435context. 436.Pp 437The optional 438.Fn activate_cb 439and 440.Fn deactivate_cb 441functions for a target map will be called into the driver from 442.Sy kernel 443context. 444.Pp 445The 446.Fn scsi_hba_tgtmap_set_begin , 447.Fn scsi_hba_tgtmap_set_add , 448.Fn scsi_hba_tgtmap_set_end , 449.Fn scsi_hba_tgtmap_set_flush , 450.Fn scsi_hba_tgtmap_tgt_add , 451and 452.Fn scsi_hba_tgtmap_tgt_remove 453functions may be called from 454.Sy user 455or 456.Sy kernel 457context. 458It is recommended that device drivers do not call these functions from 459.Sy interrupt 460context and instead should schedule deferred work with a task queue 461or with 462.Xr timeout 9F 463if they receive notifications during an interrupt that causes them to 464need to call these functions. 465.Sh RETURN VALUES 466Upon successful completion, the 467.Fn scsi_hba_tgtmap_create , 468.Fn scsi_hba_tgtmap_destroy , 469.Fn scsi_hba_tgtmap_set_begin , 470.Fn scsi_hba_tgtmap_set_add , 471.Fn scsi_hba_tgtmap_set_end , 472.Fn scsi_hba_tgtmap_set_flush , 473.Fn scsi_hba_tgtmap_tgt_add , 474and 475.Fn scsi_hba_tgtmap_tgt_remove 476functions return 477.Dv DDI_SUCCESS . 478Otherwise, 479.Dv DDI_FAILURE 480is returned. 481.Sh SEE ALSO 482.Xr sd 7D , 483.Xr ses 7D , 484.Xr tgtmap 9 , 485.Xr attach 9E , 486.Xr detach 9E , 487.Xr tran_start 9E , 488.Xr timeout 9F , 489.Xr scsi_device 9S 490