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