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