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