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