13385b472SRobert Mustacchi.\" 23385b472SRobert Mustacchi.\" This file and its contents are supplied under the terms of the 33385b472SRobert Mustacchi.\" Common Development and Distribution License ("CDDL"), version 1.0. 43385b472SRobert Mustacchi.\" You may only use this file in accordance with the terms of version 53385b472SRobert Mustacchi.\" 1.0 of the CDDL. 63385b472SRobert Mustacchi.\" 73385b472SRobert Mustacchi.\" A full copy of the text of the CDDL should have accompanied this 83385b472SRobert Mustacchi.\" source. A copy of the CDDL is also available via the Internet at 93385b472SRobert Mustacchi.\" http://www.illumos.org/license/CDDL. 103385b472SRobert Mustacchi.\" 113385b472SRobert Mustacchi.\" 12c2af9d80SRobert Mustacchi.\" Copyright 2019, Joyent, Inc. 13094cd349SRobert Mustacchi.\" Copyright 2022 Oxide Computer Company 14*e302d6afSGarrett D'Amore.\" Copyright 2022 RackTop Systems, Inc. 153385b472SRobert Mustacchi.\" 16094cd349SRobert Mustacchi.Dd January 29, 2022 173385b472SRobert Mustacchi.Dt SCSI_HBA_TGTMAP_CREATE 9F 183385b472SRobert Mustacchi.Os 193385b472SRobert Mustacchi.Sh NAME 203385b472SRobert Mustacchi.Nm scsi_hba_tgtmap_create , 213385b472SRobert Mustacchi.Nm scsi_hba_tgtmap_destroy , 22*e302d6afSGarrett D'Amore.Nm scsi_hba_tgtmap_scan_luns , 233385b472SRobert Mustacchi.Nm scsi_hba_tgtmap_set_begin , 243385b472SRobert Mustacchi.Nm scsi_hba_tgtmap_set_add , 253385b472SRobert Mustacchi.Nm scsi_hba_tgtmap_set_end , 263385b472SRobert Mustacchi.Nm scsi_hba_tgtmap_set_flush , 273385b472SRobert Mustacchi.Nm scsi_hba_tgtmap_tgt_add , 283385b472SRobert Mustacchi.Nm scsi_hba_tgtmap_tgt_remove 293385b472SRobert Mustacchi.Nd SCSI target map functions 303385b472SRobert Mustacchi.Sh SYNOPSIS 313385b472SRobert Mustacchi.In sys/scsi/scsi.h 323385b472SRobert Mustacchi.Ft int 333385b472SRobert Mustacchi.Fo scsi_hba_tgtmap_create 343385b472SRobert Mustacchi.Fa "dev_info_t *dip" 353385b472SRobert Mustacchi.Fa "scsi_tgtmap_mode_t mode" 363385b472SRobert Mustacchi.Fa "int csync_usec" 373385b472SRobert Mustacchi.Fa "int settle_usec" 383385b472SRobert Mustacchi.Fa "void *tgtmap_priv" 393385b472SRobert Mustacchi.Fa "scsi_tgt_activate_cb_t activate_cb" 403385b472SRobert Mustacchi.Fa "scsi_tgt_deactivate_cb_t deactivate_cb" 416ec1c666SRobert Mustacchi.Fa "scsi_hba_tgtmap_t **tgtmapout" 423385b472SRobert Mustacchi.Fc 433385b472SRobert Mustacchi.Ft void 443385b472SRobert Mustacchi.Fo scsi_hba_tgtmap_destroy 453385b472SRobert Mustacchi.Fa "scsi_hba_tgtmap_t *tgtmap" 463385b472SRobert Mustacchi.Fc 473385b472SRobert Mustacchi.Ft void 483385b472SRobert Mustacchi.Fo (*scsi_tgt_activate_cb_t) 493385b472SRobert Mustacchi.Fa "void *tgtmap_priv" 503385b472SRobert Mustacchi.Fa "char *tgt_addr" 513385b472SRobert Mustacchi.Fa "scsi_tgtmap_tgt_type_t type" 523385b472SRobert Mustacchi.Fa "void **tgt_privp" 533385b472SRobert Mustacchi.Fc 543385b472SRobert Mustacchi.Ft boolean_t 553385b472SRobert Mustacchi.Fo (*scsi_tgt_deactivate_cb_t) 563385b472SRobert Mustacchi.Fa "void *tgtmap_priv" 573385b472SRobert Mustacchi.Fa "char *tgt_addr" 583385b472SRobert Mustacchi.Fa "scsi_tgtmap_tgt_type_t type" 593385b472SRobert Mustacchi.Fa "void *tgt_priv" 603385b472SRobert Mustacchi.Fa "scsi_tgtmap_deact_rsn_t deact" 613385b472SRobert Mustacchi.Fc 62*e302d6afSGarrett D'Amore.Ft void 63*e302d6afSGarrett D'Amore.Fo scsi_hba_tgtmap_scan_luns 64*e302d6afSGarrett D'Amore.Fa "scsi_hba_tgtmap_t *tgtmap" 65*e302d6afSGarrett D'Amore.Fa "char *tgt_addr" 66*e302d6afSGarrett D'Amore.Fc 673385b472SRobert Mustacchi.Ft int 683385b472SRobert Mustacchi.Fo scsi_hba_tgtmap_set_begin 69c2af9d80SRobert Mustacchi.Fa "scsi_hba_tgtmap_t *tgtmap" 703385b472SRobert Mustacchi.Fc 713385b472SRobert Mustacchi.Ft int 723385b472SRobert Mustacchi.Fo scsi_hba_tgtmap_set_add 733385b472SRobert Mustacchi.Fa "scsi_hba_tgtmap_t *tgtmap" 743385b472SRobert Mustacchi.Fa "scsi_tgtmap_tgt_type_t type" 753385b472SRobert Mustacchi.Fa "char *tgt_addr" 763385b472SRobert Mustacchi.Fa "void *tgt_priv" 773385b472SRobert Mustacchi.Fc 783385b472SRobert Mustacchi.Ft int 793385b472SRobert Mustacchi.Fo scsi_hba_tgtmap_set_end 80c2af9d80SRobert Mustacchi.Fa "scsi_hba_tgtmap_t *tgtmap" 81c2af9d80SRobert Mustacchi.Fa "uint_t flags" 823385b472SRobert Mustacchi.Fc 833385b472SRobert Mustacchi.Ft int 843385b472SRobert Mustacchi.Fo scsi_hba_tgtmap_set_flush 85c2af9d80SRobert Mustacchi.Fa "scsi_hba_tgtmap_t *tgtmap" 863385b472SRobert Mustacchi.Fc 873385b472SRobert Mustacchi.Ft int 883385b472SRobert Mustacchi.Fo scsi_hba_tgtmap_tgt_add 893385b472SRobert Mustacchi.Fa "scsi_hba_tgtmap_t *tgtmap" 903385b472SRobert Mustacchi.Fa "scsi_tgtmap_tgt_type_t type" 913385b472SRobert Mustacchi.Fa "char *tgt_addr" 923385b472SRobert Mustacchi.Fa "void *tgt_priv" 933385b472SRobert Mustacchi.Fc 943385b472SRobert Mustacchi.Ft int 953385b472SRobert Mustacchi.Fo scsi_hba_tgtmap_tgt_remove 963385b472SRobert Mustacchi.Fa "scsi_hba_tgtmap_t *tgtmap" 973385b472SRobert Mustacchi.Fa "scsi_tgtmap_tgt_type_t type" 983385b472SRobert Mustacchi.Fa "char *tgt_addr" 993385b472SRobert Mustacchi.Fc 1003385b472SRobert Mustacchi.Sh INTERFACE LEVEL 1013385b472SRobert Mustacchi.Sy Evolving - 1023385b472SRobert MustacchiThis interface is still evolving in illumos. 1033385b472SRobert MustacchiAPI and ABI stability is 1043385b472SRobert Mustacchinot guaranteed. 1053385b472SRobert Mustacchi.Sh PARAMETERS 1063385b472SRobert Mustacchi.Bl -tag -width Fa 1073385b472SRobert Mustacchi.It Fa dip 1083385b472SRobert MustacchiPointer to 1093385b472SRobert Mustacchi.Vt dev_info 1103385b472SRobert Mustacchistructure. 1113385b472SRobert Mustacchi.It Fa mode 1123385b472SRobert MustacchiOne of the following values: 1133385b472SRobert Mustacchi.Bl -tag -width Dv 1143385b472SRobert Mustacchi.It Dv SCSI_TM_FULLSET 1153385b472SRobert MustacchiThe target map operates by full-set reporting. 1163385b472SRobert Mustacchi.It Dv SCSI_TM_PERADDR 1173385b472SRobert MustacchiThe target map operates by per-address reporting. 1183385b472SRobert Mustacchi.El 1193385b472SRobert Mustacchi.It Fa csync_usec 1203385b472SRobert MustacchiA time in microseconds. 1213385b472SRobert Mustacchi.It Fa settle_usec 1223385b472SRobert MustacchiA time in microseconds. 1233385b472SRobert Mustacchi.It Fa tgtmap_priv 1243385b472SRobert MustacchiA private value to be passed to callback functions. 1253385b472SRobert Mustacchi.It Fa activate_cb 1263385b472SRobert MustacchiAn optional callback that will be called when a new device is being 1273385b472SRobert Mustacchiadded to the system. 1283385b472SRobert Mustacchi.It Fa deactivate_cb 1293385b472SRobert MustacchiAn optional callback that will be called when an existing devices is 1303385b472SRobert Mustacchiremoved from the system. 1313385b472SRobert Mustacchi.It Fa tgtmapout 1326ec1c666SRobert MustacchiPointer where the target map handle is stored. 1333385b472SRobert Mustacchi.It Fa tgtmap 1343385b472SRobert MustacchiPointer to an allocated target map. 135c2af9d80SRobert Mustacchi.It Fa flags 136c2af9d80SRobert MustacchiFlags that modify the behavior of the function. 137c2af9d80SRobert MustacchiCurrently reserved and should be passed as 138c2af9d80SRobert Mustacchi.Sy 0 . 1393385b472SRobert Mustacchi.It Fa tgt_addr 1403385b472SRobert MustacchiThe address of the target map entry the callback is acting upon. 1413385b472SRobert Mustacchi.It Fa type 1423385b472SRobert MustacchiOne of the following values, indicating the type of the target: 1433385b472SRobert Mustacchi.Bl -tag -width Dv 1443385b472SRobert Mustacchi.It Dv SCSI_TGT_SCSI_DEVICE 1453385b472SRobert MustacchiThe target is some form of SCSI device such as a parallel SCSI, SATA, 1463385b472SRobert MustacchiSAS, SES, etc. 1473385b472SRobert Mustacchi.It Dv SCSI_TGT_SMP_DEVICE 1483385b472SRobert MustacchiThe target is a SCSI Management Protocol device. 1493385b472SRobert Mustacchi.El 1503385b472SRobert Mustacchi.It Fa deact 1513385b472SRobert MustacchiOne of the following values, indicating why the target is being removed: 1523385b472SRobert Mustacchi.Bl -tag -width Dv 1533385b472SRobert Mustacchi.It Dv SCSI_TGT_DEACT_RSN_GONE 1543385b472SRobert MustacchiThe device is being deactivated because it is gone. 1553385b472SRobert Mustacchi.It Dv SCSI_TGT_DEACT_RSN_CFG_FAIL 1563385b472SRobert MustacchiThe device is being deactivated because the configuration callback 1573385b472SRobert Mustacchifailed. 1583385b472SRobert Mustacchi.It Dv SCSI_TGT_DEACT_RSN_UNSTBL 1593385b472SRobert MustacchiThe device is being deactivated because it was added and removed during 1603385b472SRobert Mustacchithe stabilization period and therefore is considered unstable. 1613385b472SRobert Mustacchi.El 1623385b472SRobert Mustacchi.El 1633385b472SRobert Mustacchi.Sh DESCRIPTION 1643385b472SRobert MustacchiThe 1653385b472SRobert Mustacchi.Fn scsi_hba_tgtmap_create 1663385b472SRobert Mustacchiand 1673385b472SRobert Mustacchi.Fn scsi_hba_tgtmap_destroy 1683385b472SRobert Mustacchifunctions are used to create and destroy target maps. 1693385b472SRobert MustacchiA target map is used to manage SCSI and SMP (SCSI Management Protocol) 1703385b472SRobert Mustacchidevices. 1713385b472SRobert MustacchiFor more background on target maps, see 1723385b472SRobert Mustacchi.Xr tgtmap 9 . 1733385b472SRobert Mustacchi.Pp 1743385b472SRobert MustacchiTo create a target map, the driver should call the 1753385b472SRobert Mustacchi.Fn scsi_hba_tgtmap_create 1763385b472SRobert Mustacchifunction. 1773385b472SRobert MustacchiUpon successful completion, a pointer to the target map will be placed 1783385b472SRobert Mustacchiin the 1793385b472SRobert Mustacchi.Fa tgtmapout 1803385b472SRobert Mustacchiargument. 1813385b472SRobert Mustacchi.Pp 1823385b472SRobert MustacchiThe 1833385b472SRobert Mustacchi.Fa dip 184094cd349SRobert Mustacchiargument should correspond to one of the HBA driver's iports. 185094cd349SRobert MustacchiThe overall driver instance cannot be used here. 186094cd349SRobert MustacchiTarget maps are only supported on iports. 1873385b472SRobert Mustacchi.Pp 1883385b472SRobert MustacchiThe 1893385b472SRobert Mustacchi.Fa mode 1903385b472SRobert Mustacchiargument describes how addresses are reported into the target map and 1913385b472SRobert Mustacchithe functions used to add and remove devices. 1923385b472SRobert MustacchiIf 1933385b472SRobert Mustacchi.Fa mode 1943385b472SRobert Mustacchiis 1953385b472SRobert Mustacchi.Dv SCSI_TM_FULLSET 1963385b472SRobert Mustacchithen the driver must always report all the devices that are in the set 1973385b472SRobert Mustacchiand will be told when the corresponding devices have been removed. 1983385b472SRobert MustacchiSee 1993385b472SRobert Mustacchithe section 2003385b472SRobert Mustacchi.Sx Full-Set Reporting 2013385b472SRobert Mustacchifor more information. 2023385b472SRobert Mustacchi.Pp 2033385b472SRobert MustacchiOtherwise, the driver should set the 2043385b472SRobert Mustacchi.Fa mode 2053385b472SRobert Mustacchiargument to 2063385b472SRobert Mustacchi.Dv SCSI_TM_PERADDR 2073385b472SRobert Mustacchiand use the 2083385b472SRobert Mustacchi.Fn scsi_hba_tgtmap_tgt_add 2093385b472SRobert Mustacchiand 210094cd349SRobert Mustacchi.Fn scsi_hba_tgtmap_tgt_remove 2113385b472SRobert Mustacchifunctions. 2123385b472SRobert MustacchiSee the section 2133385b472SRobert Mustacchi.Sx Per-Address Reporting 2143385b472SRobert Mustacchifor more information. 2153385b472SRobert Mustacchi.Pp 2163385b472SRobert MustacchiThe 2173385b472SRobert Mustacchi.Fa csync_usec 2183385b472SRobert Mustacchiand 2193385b472SRobert Mustacchi.Fa settle_usec 2203385b472SRobert Mustacchiare both times measured in microseconds that control two different 2213385b472SRobert Mustacchiproperties of the target map and how it behaves. 2223385b472SRobert MustacchiThe value in 2233385b472SRobert Mustacchi.Fa settle_usec 2243385b472SRobert Mustacchiindicates the amount of time that the system should wait to quiesce all 2253385b472SRobert Mustacchichanges and consider the resulting system stable. 2263385b472SRobert MustacchiChanges will not be reported until after 2273385b472SRobert Mustacchi.Fa settle_usec 2283385b472SRobert Mustacchihave passed. 2293385b472SRobert Mustacchi.Fa csync_usec 2303385b472SRobert Mustacchiindicates how much time needs to elapse after creation before an initial 2313385b472SRobert Mustacchienumeration has been completed. 2323385b472SRobert Mustacchi.Pp 2333385b472SRobert MustacchiThe 2343385b472SRobert Mustacchi.Fa activate_cb 2353385b472SRobert Mustacchiand 2363385b472SRobert Mustacchi.Fa deactivate_cb 2373385b472SRobert Mustacchiarguments are optional function pointers that will be run in the context 2383385b472SRobert Mustacchiof devices being added and removed from the system. 2393385b472SRobert MustacchiThis allows the HBA driver to perform any required operations prior to 2403385b472SRobert Mustacchithe system attaching a target driver such as 241bbf21555SRichard Lowe.Xr sd 4D 2423385b472SRobert Mustacchior 243bbf21555SRichard Lowe.Xr ses 4D 2443385b472SRobert Mustacchiin the activate case and after the system has detached the driver, in 2453385b472SRobert Mustacchithe removal case. 2463385b472SRobert Mustacchi.Pp 2473385b472SRobert MustacchiTo destroy a target map, a caller should use the 2483385b472SRobert Mustacchi.Fn scsi_hba_tgtmap_destroy 2493385b472SRobert Mustacchifunction. 2503385b472SRobert MustacchiDestroying a target map causes all currently present devices 2513385b472SRobert Mustacchito be deactivated, as though they were removed, prior to the 2523385b472SRobert Mustacchifinal destruction of the target map. 2533385b472SRobert Mustacchi.Ss Callbacks 2543385b472SRobert MustacchiTarget maps allow for callbacks to be registered and called when 2553385b472SRobert Mustacchidevices are being added and removed from the system. 2563385b472SRobert MustacchiA driver specifies these when the target map is created by passing in 2573385b472SRobert Mustacchifunction pointers to 2583385b472SRobert Mustacchithe 2593385b472SRobert Mustacchi.Fn activate_cb 2603385b472SRobert Mustacchiand 2613385b472SRobert Mustacchi.Fn deactivate_cb 2623385b472SRobert Mustacchiarguments. 2633385b472SRobert Mustacchi.Pp 2643385b472SRobert MustacchiWhen a new address is registered in a target map and the driver has 2653385b472SRobert Mustacchispecified a function in the 2663385b472SRobert Mustacchi.Fa activate_cb 2673385b472SRobert Mustacchiargument, the driver will eventually have their activation function 2683385b472SRobert Mustacchicalled. 2693385b472SRobert MustacchiThis call will be asynchronous with respect to the adding and 2703385b472SRobert Mustacchiremoving of entries, regardless of whether the target map is using 2713385b472SRobert Mustacchiper-address or full-set reporting. 2723385b472SRobert MustacchiThis call will occur before any driver is bound to the discovered 2733385b472SRobert Mustacchiaddress. 2743385b472SRobert Mustacchi.Pp 2753385b472SRobert MustacchiThe 2763385b472SRobert Mustacchi.Fa tgtmap_priv 2773385b472SRobert Mustacchiargument will point to the optional, private argument that was passed 2783385b472SRobert Mustacchito the 2793385b472SRobert Mustacchi.Fn scsi_hba_tgtmap_create 2803385b472SRobert Mustacchifunction when the target map was created. 2813385b472SRobert MustacchiThe 2823385b472SRobert Mustacchi.Fa tgt_addr 2833385b472SRobert Mustacchiand 2843385b472SRobert Mustacchi.Fa tgt_type 2853385b472SRobert Mustacchiwill describe the address and type of the new device and will correspond 2863385b472SRobert Mustacchiwith the values passed into either the 2873385b472SRobert Mustacchi.Fn scsi_hba_tgtmap_set_add 2883385b472SRobert Mustacchior 2893385b472SRobert Mustacchi.Fn scsi_hba_tgtmap_tgt_add 2903385b472SRobert Mustacchifunctions. 2913385b472SRobert Mustacchi.Pp 2923385b472SRobert MustacchiThe 2933385b472SRobert Mustacchi.Fa tgt_privp 2943385b472SRobert Mustacchiargument is a modifiable private value. 2953385b472SRobert MustacchiInitially, 2963385b472SRobert Mustacchi.Fa tgt_privp 2973385b472SRobert Mustacchipoints to the value passed in as 2983385b472SRobert Mustacchi.Fa tgt_priv 2993385b472SRobert Mustacchito either the 3003385b472SRobert Mustacchi.Fn scsi_hba_tgtmap_set_add 3013385b472SRobert Mustacchior 3023385b472SRobert Mustacchi.Fn scsi_hba_tgtmap_tgt_add 3033385b472SRobert Mustacchifunctions. 3043385b472SRobert MustacchiThe driver may change the value as needed. 3053385b472SRobert MustacchiIt will receive the value stored in 3063385b472SRobert Mustacchi.Fa tgt_privp 3073385b472SRobert Mustacchiduring the deactivate callback. 3083385b472SRobert Mustacchi.Pp 3093385b472SRobert MustacchiWhen a target map has been updated to indicate that a device has been 3103385b472SRobert Mustacchiremoved, then the driver will receive a deactivation callback if it 3113385b472SRobert Mustacchiregistered one. 3123385b472SRobert MustacchiThe deactivate callback will occur after a driver has 3133385b472SRobert Mustacchibeen detached from the corresponding device. 3143385b472SRobert Mustacchi.Pp 3153385b472SRobert MustacchiThe 3163385b472SRobert Mustacchi.Fa tgtmap_priv , 3173385b472SRobert Mustacchi.Fa tgt_addr , 3183385b472SRobert Mustacchiand 3193385b472SRobert Mustacchi.Fa type 3203385b472SRobert Mustacchiarguments to the callback function are the same as for the activate 3213385b472SRobert Mustacchicase. 3223385b472SRobert MustacchiThe 3233385b472SRobert Mustacchi.Fa tgt_priv 3243385b472SRobert Mustacchipointer will be set to the value that was passed when the device was 3253385b472SRobert Mustacchiadded and will reflect any updates made during an activate callback, if 3263385b472SRobert Mustacchipresent. 3273385b472SRobert Mustacchi.Pp 3283385b472SRobert MustacchiThe 3293385b472SRobert Mustacchi.Fa deact 3303385b472SRobert Mustacchiargument gives the driver some amount of information as to why device 3313385b472SRobert Mustacchiwas being removed. 3323385b472SRobert MustacchiThe deactivation reason provides the driver 3333385b472SRobert Mustacchimore information about why the address was being removed from the target 3343385b472SRobert Mustacchimap which can be useful in the cases that it itself did not issue it. 3353385b472SRobert Mustacchi.Pp 3363385b472SRobert MustacchiThe return value indicates whether or not some amount of rediscovery of 3373385b472SRobert Mustacchithe address is desired or not. 3383385b472SRobert MustacchiThis is only meaningful in the case where the 3393385b472SRobert Mustacchi.Fa deact 3403385b472SRobert Mustacchiargument was 3413385b472SRobert Mustacchi.Dv SCSI_TGT_DEACT_RSN_CFG_FAIL . 3423385b472SRobert MustacchiIf the driver does wish to attempt rediscovery, then it should return 3433385b472SRobert Mustacchi.Dv B_TRUE . 3443385b472SRobert MustacchiOtherwise, the driver should return 3453385b472SRobert Mustacchi.Dv B_FALSE . 3463385b472SRobert MustacchiIf in doubt, use the return value 3473385b472SRobert Mustacchi.Dv B_FALSE . 3483385b472SRobert MustacchiNote, even if the driver returns 3493385b472SRobert Mustacchi.Dv B_TRUE , 3503385b472SRobert Mustacchino action may be taken by the system. 3513385b472SRobert Mustacchi.Ss Full-Set Reporting 3523385b472SRobert MustacchiFull-Set reporting is one way of managing a target map. 3533385b472SRobert MustacchiIn full-set reporting, whenever an update is being made, the entire data 3543385b472SRobert Mustacchiset is reported to the target map. 3553385b472SRobert MustacchiThe target map then determines which 3563385b472SRobert Mustacchiaddresses are new, which have been removed, and which have stayed the 3573385b472SRobert Mustacchisame and updates the system state appropriately. 3583385b472SRobert MustacchiIf devices have been added or removed from the system, then any activate 3593385b472SRobert Mustacchiand deactivate endpoints will be called. 3603385b472SRobert Mustacchi.Pp 3613385b472SRobert MustacchiTo begin a new report, the driver should call the 3623385b472SRobert Mustacchi.Fn scsi_hba_tgtmap_set_begin 3633385b472SRobert Mustacchifunction. 3643385b472SRobert MustacchiOnce the report has begun, the driver should add devices by calling the 3653385b472SRobert Mustacchi.Fn scsi_hba_tgtmap_set_add 3663385b472SRobert Mustacchifunction. 3673385b472SRobert MustacchiOnce all devices have been added, the driver should call the 3683385b472SRobert Mustacchi.Fn scsi_hba_tgtmap_set_end 3693385b472SRobert Mustacchifunction to indicate that the target map processing has ended. 3703385b472SRobert MustacchiIf driver wishes to discard a report that has begun, but not yet 3713385b472SRobert Mustacchiterminated, then the driver should call the 3723385b472SRobert Mustacchi.Fn scsi_hba_tgtmap_set_flush 3733385b472SRobert Mustacchifunction. 3743385b472SRobert Mustacchi.Pp 3753385b472SRobert MustacchiWhen adding entries, the driver should indicate the address of the 3763385b472SRobert Mustacchidevice in 3773385b472SRobert Mustacchi.Fa tgt_addr . 3783385b472SRobert MustacchiThis will generally be a world wide number (WWN) in a unit-addressable 3793385b472SRobert Mustacchiform. 3803385b472SRobert MustacchiHowever, the driver may use its own synthetic numbering. 3813385b472SRobert MustacchiThis address will be passed to the activate callbacks and will also be 3823385b472SRobert Mustacchiused as the address of the 3833385b472SRobert Mustacchi.Xr scsi_device 9S 3843385b472SRobert Mustacchiin the 3853385b472SRobert Mustacchi.Xr tran_start 9E 3863385b472SRobert Mustacchientry point. 3873385b472SRobert Mustacchi.Pp 3883385b472SRobert MustacchiThe 3893385b472SRobert Mustacchi.Fa type 3903385b472SRobert Mustacchiargument indicates how the kernel will interpret the type of device. 3913385b472SRobert MustacchiAt this time, devices are broken into two broad categories. 3923385b472SRobert MustacchiThings which are some kind of SCSI device, whether parallel, SCSI, SATA 3933385b472SRobert Mustacchibehind a SATL, SES, etc. should use the type 3943385b472SRobert Mustacchi.Dv SCSI_TGT_SCSI_DEVICE . 3953385b472SRobert MustacchiThe other group, 3963385b472SRobert Mustacchi.Dv SCSI_TGT_SMP_DEVICE , 3973385b472SRobert Mustacchiis for SCSI Management Protocol (SMP) devices. 3983385b472SRobert Mustacchi.Pp 3993385b472SRobert MustacchiThe 4003385b472SRobert Mustacchi.Fa tgt_priv 4013385b472SRobert Mustacchiargument will be passed to the activate and deactivate callbacks, 4023385b472SRobert Mustacchiallowing the driver to pass around data corresponding to this address. 4033385b472SRobert Mustacchi.Ss Per-Address Reporting 4043385b472SRobert MustacchiWhen using a target map with per-address reporting, the driver is 4053385b472SRobert Mustacchiresponsible for indicating what devices have been added and removed. 4063385b472SRobert MustacchiThis is useful for various hardware configurations where all entries and 4073385b472SRobert Mustacchiremovals are processes in a highly-reliable fashion where hardware 4083385b472SRobert Mustacchicannot drop entries. 4093385b472SRobert Mustacchi.Pp 4103385b472SRobert MustacchiTo add a new device, the driver should call the 4113385b472SRobert Mustacchi.Fa scsi_hba_tgtmap_tgt_add 4123385b472SRobert Mustacchifunction. 4133385b472SRobert MustacchiThe 4143385b472SRobert Mustacchi.Fa tgt_addr 4153385b472SRobert Mustacchiand 4163385b472SRobert Mustacchi.Fa type 4173385b472SRobert Mustacchiarguments describe the address and what kind of device the address 4183385b472SRobert Mustacchicorresponds to. 4193385b472SRobert MustacchiFor more information, see the previous section, 4203385b472SRobert Mustacchi.Sx Full-Address Reporting . 4213385b472SRobert MustacchiThe 4223385b472SRobert Mustacchi.Fa tgt_priv 4233385b472SRobert Mustacchiargument will be passed along to the activate and deactivate functions, 4243385b472SRobert Mustacchiallowing the driver to associate a value with the address in question. 4253385b472SRobert Mustacchi.Pp 4263385b472SRobert MustacchiWhen a device has been removed, the driver should call the 4273385b472SRobert Mustacchi.Fn scsi_hba_tgtmap_tgt_remove 4283385b472SRobert Mustacchifunction, ensuring that both the 4293385b472SRobert Mustacchi.Fa tgt_addr 4303385b472SRobert Mustacchiand 4313385b472SRobert Mustacchi.Fa type 4323385b472SRobert Mustacchiarguments match those that were used when calling the 4333385b472SRobert Mustacchi.Fn scsi_hba_tgtmap_tgt_add 4343385b472SRobert Mustacchifunction. 435*e302d6afSGarrett D'Amore.Ss Scanning for Logical Units 436*e302d6afSGarrett D'AmoreSCSI targets may contain logical units 437*e302d6afSGarrett D'Amore.Pq LUNS 438*e302d6afSGarrett D'Amorethat are created or destroyed by the target dynamically. 439*e302d6afSGarrett D'AmoreIn order to facilitate discovery of logical units, the HBA may call 440*e302d6afSGarrett D'Amore.Fn scsi_hba_tgtmap_scan_luns 441*e302d6afSGarrett D'Amoreusing the address of a target that has been registered using the given 442*e302d6afSGarrett D'Amore.Fa tgt_addr . 443*e302d6afSGarrett D'Amore.Pp 444*e302d6afSGarrett D'AmoreThis will cause the framework to issue a 445*e302d6afSGarrett D'Amore.Sy REPORT_LUNS 446*e302d6afSGarrett D'Amorecommand, to enumerate any present logical units. 447*e302d6afSGarrett D'AmoreLogical units that are no longer present will be pruned from the system, 448*e302d6afSGarrett D'Amoreand any new ones will be created. 4493385b472SRobert Mustacchi.Sh CONTEXT 4503385b472SRobert MustacchiThe 4513385b472SRobert Mustacchi.Fn scsi_hba_tgtmap_create 4523385b472SRobert Mustacchiand 4533385b472SRobert Mustacchi.Fn scsi_hba_tgtmap_destroy 4543385b472SRobert Mustacchifunctions are generally called from the context of the 4553385b472SRobert Mustacchi.Xr attach 9E 4563385b472SRobert Mustacchiand 4573385b472SRobert Mustacchi.Xr detach 9E 4583385b472SRobert Mustacchientry points of HBA drivers and their iports, though may also be called 4593385b472SRobert Mustacchifrom 4603385b472SRobert Mustacchi.Sy user 4613385b472SRobert Mustacchior 4623385b472SRobert Mustacchi.Sy kernel 4633385b472SRobert Mustacchicontext. 4643385b472SRobert Mustacchi.Pp 4653385b472SRobert MustacchiThe optional 4663385b472SRobert Mustacchi.Fn activate_cb 4673385b472SRobert Mustacchiand 4683385b472SRobert Mustacchi.Fn deactivate_cb 4693385b472SRobert Mustacchifunctions for a target map will be called into the driver from 4703385b472SRobert Mustacchi.Sy kernel 4713385b472SRobert Mustacchicontext. 4723385b472SRobert Mustacchi.Pp 4733385b472SRobert MustacchiThe 474*e302d6afSGarrett D'Amore.Fn scsi_hba_tgtmap_scan_luns , 4753385b472SRobert Mustacchi.Fn scsi_hba_tgtmap_set_begin , 4763385b472SRobert Mustacchi.Fn scsi_hba_tgtmap_set_add , 4773385b472SRobert Mustacchi.Fn scsi_hba_tgtmap_set_end , 4783385b472SRobert Mustacchi.Fn scsi_hba_tgtmap_set_flush , 4793385b472SRobert Mustacchi.Fn scsi_hba_tgtmap_tgt_add , 4803385b472SRobert Mustacchiand 4813385b472SRobert Mustacchi.Fn scsi_hba_tgtmap_tgt_remove 4823385b472SRobert Mustacchifunctions may be called from 4833385b472SRobert Mustacchi.Sy user 4843385b472SRobert Mustacchior 4853385b472SRobert Mustacchi.Sy kernel 4863385b472SRobert Mustacchicontext. 487*e302d6afSGarrett D'AmoreDevice drivers should not call these functions from 4883385b472SRobert Mustacchi.Sy interrupt 489*e302d6afSGarrett D'Amorecontext and should instead schedule deferred work with a task queue 4903385b472SRobert Mustacchior with 4913385b472SRobert Mustacchi.Xr timeout 9F 492*e302d6afSGarrett D'Amoreif a need to call these arises while handling an interrupt. 4933385b472SRobert Mustacchi.Sh RETURN VALUES 4943385b472SRobert MustacchiUpon successful completion, the 4953385b472SRobert Mustacchi.Fn scsi_hba_tgtmap_create , 4963385b472SRobert Mustacchi.Fn scsi_hba_tgtmap_destroy , 4973385b472SRobert Mustacchi.Fn scsi_hba_tgtmap_set_begin , 4983385b472SRobert Mustacchi.Fn scsi_hba_tgtmap_set_add , 4993385b472SRobert Mustacchi.Fn scsi_hba_tgtmap_set_end , 5003385b472SRobert Mustacchi.Fn scsi_hba_tgtmap_set_flush , 5013385b472SRobert Mustacchi.Fn scsi_hba_tgtmap_tgt_add , 5023385b472SRobert Mustacchiand 5033385b472SRobert Mustacchi.Fn scsi_hba_tgtmap_tgt_remove 5043385b472SRobert Mustacchifunctions return 5053385b472SRobert Mustacchi.Dv DDI_SUCCESS . 5063385b472SRobert MustacchiOtherwise, 5073385b472SRobert Mustacchi.Dv DDI_FAILURE 5083385b472SRobert Mustacchiis returned. 5093385b472SRobert Mustacchi.Sh SEE ALSO 510bbf21555SRichard Lowe.Xr sd 4D , 511bbf21555SRichard Lowe.Xr ses 4D , 5123385b472SRobert Mustacchi.Xr tgtmap 9 , 5133385b472SRobert Mustacchi.Xr attach 9E , 5143385b472SRobert Mustacchi.Xr detach 9E , 5153385b472SRobert Mustacchi.Xr tran_start 9E , 5163385b472SRobert Mustacchi.Xr timeout 9F , 5173385b472SRobert Mustacchi.Xr scsi_device 9S 518