Changes suggested by Sam Haxor <generationgnu@yahoo.com>
[mirror/scst/.git] / doc / scst_pg.sgml
1 <!doctype linuxdoc system>
2
3 <article>
4
5 <title>Generic SCSI Target Middle Level for Linux</title>
6
7 <author>
8         <name>Vladislav Bolkhovitin</name>
9 </author>
10
11 <date>Version 0.9.5 2006/12/01, actual for SCST 0.9.5 and later</date>
12
13 <abstract>
14 This document describes SCSI target mid-level for Linux (SCST), its
15 architecture and drivers from the driver writer's point of view. 
16 </abstract>
17
18 <toc>
19
20 <sect>Introduction
21
22 <p>
23 SCST is a SCSI target mid-level subsystem for Linux. It is designed to
24 provide unified, consistent interface between SCSI target drivers and
25 Linux kernel and simplify target drivers development as much as
26 possible. It has the following features:
27
28 <itemize> 
29
30 <item> Very low overhead, fine-grained locks and simplest commands
31 processing path, which allow to reach maximum possible performance and
32 scalability that close to theoretical limit.
33
34 <item> Incoming requests can be processed in the caller's context or in
35 one of the internal SCST's tasklets, therefore no extra context switches
36 required. 
37
38 <item> Complete SMP support.
39
40 <item> Undertakes most problems, related to execution contexts, thus
41 practically eliminating one of the most complicated problem in the
42 kernel drivers development. For example, a target driver for QLogic
43 22xx/23xx cards, which has all necessary features, is about 2000
44 lines of code long, that is at least in several times less, than the
45 initiator one.
46
47 <item> Performs all required pre- and post- processing of incoming
48 requests and all necessary error recovery functionality. 
49
50 <item> Emulates necessary functionality of SCSI host adapter, because
51 from a remote initiator's point of view SCST acts as a SCSI host with
52 its own devices. Some of the emulated functions are the following:
53
54         <itemize>
55         
56         <item> Generation of necessary UNIT ATTENTIONs, their storage and
57         delivery to all connected remote initiators (sessions).
58
59         <item> RESERVE/RELEASE functionality. 
60
61         <item> CA/ACA conditions.
62         
63         <item> All types of RESETs and other task management functions.
64         
65         <item> REPORT LUNS command as well as SCSI address space management
66         in order to have consistent address space on all remote initiators,
67         since local SCSI devices could not know about each other to report
68         via REPORT LUNS command. Additionally, SCST responds with error on
69         all commands to non-existing devices and provides access control
70         (not implemented yet), so different remote initiators could see
71         different set of devices.
72
73         <item> Other necessary functionality (task attributes, etc.) as
74         specified in SAM-2, SPC-2, SAM-3, SPC-3 and other SCSI standards.
75         
76         </itemize>
77  
78 <item> Device handlers architecture provides extra reliability and
79 security via verifying all incoming requests and allows to make any
80 additional requests processing, which is completely independent from
81 target drivers, for example, data caching or device dependent
82 exceptional conditions treatment.
83
84 </itemize>
85
86 Interoperability between SCST and local SCSI initiators (like sd, st) is
87 the additional issue that SCST is going to address (it is not
88 implemented yet). It is necessary, because local SCSI initiators can
89 change the state of the device, for example RESERVE the device, or some
90 of its parameters and that would be done behind SCST, which could lead
91 to various problems. Thus, RESERVE/RELEASE commands, locally generated
92 UNIT ATTENTIONs, etc. should be intercepted and processed as if local
93 SCSI initiators act as remote SCSI initiators connected to SCST. This
94 feature requires some the kernel modification. Since in the current
95 version it is not implemented, SCST and the target drivers are able to
96 work with any unpatched 2.4 kernel version.
97
98 Interface between SCST and the target drivers is based on work, done by
99 University of New Hampshire Interoperability Labs (UNH IOL).
100
101 All described below data structures and function could be found in
102 <bf/scst.h/. The SCST's Internet page is
103 <url url="http://scst.sourceforge.net">.
104
105 <sect>Terms and Definitions
106
107 <p><bf/SCSI initiator device/
108
109 A SCSI device that originates service and task management requests to be
110 processed by a SCSI target device and receives device service and task
111 management responses from SCSI target devices.
112
113 Think of the 'SCSI LLDD' as a BE (Back End) driver.
114
115 <bf/SCSI target device/
116
117 A SCSI device that receives device service and task management requests
118 for processing and sends device service and task management responses
119 to SCSI initiator devices or drivers. 
120
121 Think of the 'Target Driver' as an FE (Front End) driver.
122
123 The FE driver interfaces to the initiators (via the
124 storage-fabric-cloud) and also to the upper edge of the SCST. Whereas
125 the BE driver interfaces to the targets, i.e. disk-enclosures/JBODs/tapes etc.
126 and also to the bottom edge of the SCST.
127
128 <bf/SCST session/
129
130 SCST session is the object that describes relationship between a remote
131 initiator and SCST via a target driver. All the commands from the remote
132 initiator is passed to SCST in the session. For example, for connection
133 oriented protocols, like iSCSI, SCST session could be mapped to the TCP
134 connection (as well as iSCSI session). SCST session is the close
135 equivalent of I_T nexus object.
136
137 <bf/Local SCSI initiator/
138
139 A SCSI initiator that is located on the same host as SCST subsystem.
140 Examples are sg and st drivers.
141
142 <bf/Remote SCSI initiator/
143
144 A SCSI initiator that is located on the remote host for SCST subsystem
145 and makes client connections to SCST via SCSI target drivers.
146
147 <bf/SCSI target driver/
148
149 A Linux hardware or logical driver that acts as a SCSI target for remote
150 SCSI initiators, i.e. accepts remote connections, passes incoming SCSI
151 requests to SCST and sends SCSI responses from SCST back to their
152 originators.
153
154 <bf/Device handler driver/
155
156 Also known as "device type specific driver" or "dev handler", is plugin
157 for SCST, which helps SCST to analyze incoming requests and determine
158 parameters, specific to various types of devices as well as perform some
159 processing. See appropriate section for details.
160
161 <sect>SCST Architecture
162
163 <p> 
164 SCST accepts commands and passes them to SCSI mid-level at the same
165 way as SCSI high-level drivers (sg, sd, st) do. Figure 1 shows
166 interaction between SCST, its drivers and Linux SCSI subsystem.
167
168 <figure>
169 <eps file="fig1.png">
170 <img src="fig1.png">
171 <caption>
172  <newline> Interaction between SCST, its drivers and Linux SCSI subsystem.
173 </caption>
174 </figure>
175
176 <sect>Target driver registration
177
178 <p>
179 To work with SCST a target driver must register its template in SCST by
180 calling scst_register_target_template(). The template lets SCST know the
181 target driver's entry points. It is defined as the following:
182
183 <sect1>Structure scst_tgt_template
184
185 <p>
186 <verb>
187 struct scst_tgt_template 
188 {
189         int sg_tablesize;
190         const char name[15];
191
192         unsigned unchecked_isa_dma:1;
193         unsigned use_clustering:1;
194
195         unsigned xmit_response_atomic:1; 
196         unsigned rdy_to_xfer_atomic:1;
197         unsigned report_aen_atomic:1;
198
199         int (* detect) (struct scst_tgt_template *tgt_template);
200         int (* release)(struct scst_tgt *tgt);
201
202         int (* xmit_response)(struct scst_cmd *cmd);
203         int (* rdy_to_xfer)(struct scst_cmd *cmd);
204         
205         void (*on_free_cmd) (struct scst_cmd *cmd);
206
207         void (* task_mgmt_fn_done)(struct scst_mgmt_cmd *mgmt_cmd);
208         void (* report_aen)(int mgmt_fn, const uint8_t *lun, int lun_len);
209         
210         int (*proc_info) (char *buffer, char **start, off_t offset,
211                 int length, int *eof, struct scst_tgt *tgt, int inout);
212 }
213 </verb>
214
215 Where:
216
217 <itemize>
218
219 <item><bf/sg_tablesize/ - allows checking whether scatter/gather can be
220 used or not and, if yes, sets the maximum supported count of
221 scatter/gather entries
222
223 <item><bf/name/ - the name of the template. Must be unique to identify
224 the template. Must be defined.
225
226 <item><bf/unchecked_isa_dma/ - true, if this target adapter uses
227 unchecked DMA onto an ISA bus.
228
229 <item><bf/use_clustering/ - true, if this target adapter wants to use
230 clustering (i.e. smaller number of segments).
231
232 <item><bf/xmit_response_atomic/, <bf/rdy_to_xfer_atomic/ - true, if the
233 corresponding function supports execution in the atomic (non-sleeping)
234 context.
235
236 <item><bf/int (* detect) (struct scst_tgt_template *tgt_template)/ - this
237 function is intended to detect the target adapters that are present in
238 the system. Each found adapter should be registered by calling
239 <bf/scst_register()/. The function should return a value >= 0 to signify
240 the number of detected target adapters. A negative value should be
241 returned whenever there is an error. Must be defined.
242
243 <item><bf/int (* release)(struct scst_tgt *tgt)/ - this function is
244 intended to free up the resources allocated to the device. The function
245 should return 0 to indicate successful release or a negative value if
246 there are some issues with the release. In the current version of SCST
247 the return value is ignored. Must be defined.
248
249 <item><bf/int (* xmit_response)(struct scst_cmd *cmd)/ - this
250 function is equivalent to the SCSI queuecommand(). The target should
251 transmit the response data and the status in the struct scst_cmd. See
252 below for details. Must be defined.
253
254 <item><bf/int (* rdy_to_xfer)(struct scst_cmd *cmd)/ - this function
255 informs the driver that data buffer corresponding to the said command
256 have now been allocated and it is OK to receive data for this command.
257 This function is necessary because a SCSI target does not have any
258 control over the commands it receives. Most lower-level protocols have a
259 corresponding function which informs the initiator that buffers have
260 been allocated e.g., XFER_RDY in Fibre Channel. After the data is
261 actually received the low-level driver should call <bf/scst_rx_data()/
262 in order to continue processing this command. Returns one of the 
263 <bf/SCST_TGT_RES_*/ constants, described below. Pay attention to
264 "atomic" attribute of the command, which can be get via
265 <bf/scst_cmd_atomic()/: it is true if the function called in the atomic
266 (non-sleeping) context. Must be defined.
267
268 <item><bf/void (*on_free_cmd)(struct scst_cmd *cmd)/ - this function
269 called to notify the driver that the command is about to be freed.
270 Necessary, because for aborted commands <bf/xmit_response()/ could not be
271 called. Could be used on IRQ context. Must be defined.
272
273 <item><bf/void (* task_mgmt_fn_done)(struct scst_mgmt_cmd *mgmt_cmd)/ -
274 this function informs the driver that a received task management
275 function has been completed. Completion status could be get via
276 <bf/scst_mgmt_cmd_get_status()/. No return value expected. Must be
277 defined, if the target supports task management functionality.
278
279 <item><bf/int (* report_aen)(int mgmt_fn, const uint8_t *lun, int
280 lun_len)/ - this function is used for Asynchronous Event Notification.
281 It is the responsibility of the driver to notify any/all initiators
282 about the Asynchronous Event reported. Returns one of the
283 <bf/SCST_TGT_RES_*/ constants, described below. Must be defined, if
284 low-level protocol supports AEN. This feature is not implemented yet.
285
286 <item><bf/int (*proc_info) (char *buffer, char **start, off_t offset,
287 int length, int *eof, struct scst_tgt *tgt, int inout)/ - this function
288 can be used to export the driver's statistics and other information to
289 the world outside the kernel. Parameters:
290
291         <enum>
292         
293         <item> <bf/buffer, start, offset, length, eof/ - have the same
294         meaning as for <bf/read_proc_t/ function of the kernel
295         
296         <item> <bf/tgt/ - pointer to the target, for which the function
297         is called
298         
299         <item> <bf/inout/ - read/write direction flag, 0 - for reads, other
300         value - for writes
301         
302         </enum>
303
304 If the driver needs to create additional files in its /proc
305 subdirectory, it can use <bf/scst_proc_get_tgt_root()/ function to get
306 the root proc_dir_entry.
307
308 </itemize>
309
310 Functions <bf/xmit_response()/, <bf/rdy_to_xfer()/ are expected to be
311 non-blocking, i.e. return immediately and don't wait for actual data 
312 transfer to finish. Blocking in such command could negatively impact on
313 overall system performance. If blocking is necessary, it is worth to
314 consider creating dedicated thread(s) in target driver, to which the
315 commands would be passed and which would perform blocking operations
316 instead of SCST. If the function allowed to sleep or not is defined by
317 "atomic" attribute of the cmd that can be get via
318 <bf/scst_cmd_atomic()/, which is true, if sleeping is not allowed. In
319 this case, if the function requires sleeping, it can return
320 <bf/SCST_TGT_RES_NEED_THREAD_CTX/ in order to be recalled in the thread
321 context, where sleeping is allowed.
322
323 Functions <bf/task_mgmt_fn_done()/ and <bf/report_aen()/ are recommended
324 to be non-blocking as well. Blocking there will stop all management
325 processing for all target drivers in the system (there is only one
326 management thread in the system).
327
328 Functions <bf/xmit_response()/, <bf/rdy_to_xfer()/ and <bf/report_aen()/
329 can return the following error codes:
330
331 <itemize>
332
333 <item><bf/SCST_TGT_RES_SUCCESS/ - success.
334
335 <item><bf/SCST_TGT_RES_QUEUE_FULL/ - internal device queue is full, retry
336 again later.
337
338 <item><bf/SCST_TGT_RES_NEED_THREAD_CTX/ - it is impossible to complete 
339 requested task in atomic context. The command should be restarted in the
340 thread context as described above.
341
342 <item><bf/SCST_TGT_RES_FATAL_ERROR/ - fatal error, i.e. it is unable to
343 perform requested operation. If returned by <bf/xmit_response()/ the
344 command will be destroyed, if by <bf/rdy_to_xfer()/,
345 <bf/xmit_response()/ will be called with <bf/HARDWARE ERROR/ sense data.
346
347 </itemize>
348
349 <sect2>More about <bf/xmit_response()/
350
351 <p> 
352 As already written above, function <bf/xmit_response()/ should transmit
353 the response data and the status from the cmd parameter. Either it
354 should transmit the data or the status is defined by bits of the value,
355 returned by <bf/scst_cmd_get_tgt_resp_flags()/. They are:
356
357 <itemize>
358
359 <item><bf/SCST_TSC_FLAG_DATA/ - set if there are data to be sent
360
361 <item><bf/SCST_TSC_FLAG_STATUS/ - set if the command is finished and
362 there is status/sense to be sent
363
364 </itemize>
365
366 If <bf/SCST_TSC_FLAG_DATA/ is set, the data contained in the buffer,
367 returned by <bf/scst_cmd_get_buffer()/ (pay attention to
368 <bf/scst_cmd_get_use_sg()/ for scatter/gather) with length, returned by
369 <bf/scst_cmd_get_resp_data_len()/. It is recommended to use
370 <bf/scst_get_buf_*()/scst_put_buf()/ family of function instead of
371 direct access to the data buffers, because they hide all HIGHMEM and
372 SG/plain buffer issues.
373
374 If <bf/SCST_TSC_FLAG_STATUS/ is set the status could be received by the
375 appropriate <bf/scst_cmd_get_*_status()/ functions (see below).
376
377 The sense, if any, is contained in the buffer, returned by
378 <bf/scst_cmd_get_sense_buffer()/, with length, returned by
379 <bf/scst_cmd_get_sense_buffer_len()/. SCST always works in
380 <bf/autosense/ mode. If a low-level SCSI driver/device doesn't support
381 autosense mode, SCST will issue REQUEST SENSE command, if necessary.
382 Thus, if CHECK CONDITION established, target driver will always see
383 sense in the sense buffer and isn't required to request the sense
384 manually.
385
386 It is possible, that <bf/SCST_TSC_FLAG_DATA/ is set, but
387 <bf/SCST_TSC_FLAG_STATUS/ is not set. In this case the driver should
388 only transmit the data, but not finish the command and transmit the
389 status. Function <bf/xmit_response()/ will be called again either to
390 transmit the status or data once more.
391
392 After the response is completely sent, the target should call
393 <bf/scst_tgt_cmd_done()/ function in order to allow SCST to free the
394 command. 
395
396 Function <bf/xmit_response()/ returns one of the <bf/SCST_TGT_RES_*/
397 constants, described above. Pay attention to "atomic" attribute of the
398 cmd, which can be get via <bf/scst_cmd_atomic()/: it is true if the
399 function called in the atomic (non-sleeping) context.
400
401 <sect1>Target driver registration functions
402
403 <sect2>scst_register_target_template()
404
405 <p>
406 Function <bf/scst_register_target_template()/ is defined as the following:
407
408 <verb>
409 int scst_register_target_template(
410         struct scst_tgt_template *vtt)
411 </verb>
412
413 Where:
414
415 <itemize>
416 <item><bf/vtt/ - pointer to the target driver template
417 </itemize>
418
419 Returns 0 on success or appropriate error code otherwise.
420
421 <sect2>scst_register()
422
423 <p>
424 Function <bf/scst_register()/ is defined as the following:
425
426 <verb>
427 struct scst_tgt *scst_register(
428         struct scst_tgt_template *vtt)
429 </verb>
430
431 Where:
432
433 <itemize>
434 <item><bf/vtt/ - pointer to the target driver template
435 </itemize>
436
437 Returns target structure based on template vtt or NULL in case of error.
438
439 <sect>Target driver unregistration
440
441 <p>
442 In order to unregister itself target driver should at first call
443 <bf/scst_unregister()/ for all its adapters and then call
444 <bf/scst_unregister_target_template()/ for its template.
445
446 <sect1>scst_unregister()
447
448 <p>
449 Function <bf/scst_unregister()/ is defined as the following:
450
451 <verb>
452 void scst_unregister(
453         struct scst_tgt *tgt)
454 </verb>
455
456 Where:
457
458 <itemize>
459 <item><bf/tgt/ - pointer to the target driver structure
460 </itemize>
461
462 <sect1>scst_unregister_target_template()
463
464 <p>
465 Function <bf/scst_unregister_target_template()/ is defined as the following:
466
467 <verb>
468 void scst_unregister_target_template(
469         struct scst_tgt_template *vtt)
470 </verb>
471
472 Where:
473
474 <itemize>
475 <item><bf/vtt/ - pointer to the target driver template
476 </itemize>
477
478 <sect>SCST session registration
479
480 <p>
481 When target driver determines that it needs to create new SCST session
482 (for example, by receiving new TCP connection), it should call
483 <bf/scst_register_session()/, that is defined as the following:
484
485 <verb>
486 struct scst_session *scst_register_session(
487         struct scst_tgt *tgt,
488         int atomic,
489         const char *initiator_name,
490         void *data,
491         void (*result_fn) (
492                 struct scst_session *sess,
493                 void *data, 
494                 int result));
495 </verb>
496
497 Where:
498
499 <itemize>
500
501 <item><bf/tgt/ - target
502
503 <item><bf/atomic/ - true, if the function called in the atomic context 
504
505 <item><bf/initiator_name/ - remote initiator's name, any NULL-terminated
506 string, e.g. iSCSI name, which used as the key to found appropriate
507 access control group. Could be NULL, then "default" group is used.  The
508 groups are set up via /proc interface.
509
510 <item><bf/data/ - data that will be used as the second
511 parameter for <bf/bf/result_fn/()/ function
512
513 <item><bf/result_fn/ - pointer to the function that will be
514 asynchronously called when session initialization finishes. Can be NULL.
515 Parameters:
516
517         <itemize>
518
519         <item><bf/sess/ - session
520
521         <item><bf/data/ - target driver supplied to
522         <bf/scst_register_session()/ data
523
524         <item><bf/result/ - session initialization result, 0 on success or
525         appropriate error code otherwise
526
527         </itemize>
528
529 </itemize>
530
531 A session creation and initialization is a complex task, which requires
532 sleeping state, so it can't be fully done in interrupt context.
533 Therefore the "bottom half" of it, if <bf/scst_register_session()/ is
534 called from atomic context, will be done in SCST thread context. In this
535 case <bf/scst_register_session()/ will return not completely initialized
536 session, but the target driver can supply commands to this session via
537 <bf/scst_rx_cmd()/. Those commands processing will be delayed inside
538 SCST until the session initialization is finished, then their processing
539 will be restarted. The target driver will be notified about finish of
540 the session initialization by function <bf/result_fn()/. On success the
541 target driver could do nothing, but if the initialization fails, the
542 target driver must ensure that no more new commands being sent or will
543 be sent to SCST after <bf/result_fn()/ returns. All already sent to SCST
544 commands for failed session will be returned in <bf/xmit_response()/
545 with BUSY status. In case of failure the driver shall call
546 <bf/scst_unregister_session()/ inside <bf/result_fn()/, it will NOT be
547 called automatically. Thus, <bf/scst_register_session()/ can be called
548 even on IRQ context. 
549
550 Session registration is illustrated on Figure 2 and Figure 3.
551
552 <figure>
553 <eps file="fig2.png">
554 <img src="fig2.png">
555 <caption>
556  <newline> Session registration when <bf/atomic/ parameter is false
557 </caption>
558 </figure>
559
560 <figure>
561 <eps file="fig3.png">
562 <img src="fig3.png">
563 <caption>
564  <newline> Session registration when <bf/atomic/ parameter is true 
565 </caption>
566 </figure>
567
568 <sect>SCST session unregistration
569
570 <p>
571 SCST session unregistration basically is the same, except that instead of
572 atomic parameter there is <bf/wait/ one.
573
574 <verb>
575 void scst_unregister_session(
576         struct scst_session *sess, 
577         int wait,
578         void (* unreg_done_fn)(
579                 struct scst_session *sess))
580 </verb>
581
582 Where:
583
584 <itemize>
585
586 <item><bf/sess/ - session to be unregistered
587
588 <item><bf/wait/ - if true, instructs to wait until all commands, which
589 currently executing and belonged to the session, finished. Otherwise,
590 target driver should be prepared to receive <bf/xmit_response()/ for
591 the session after <bf/scst_unregister_session()/ returns.
592
593 <item><bf/unreg_done_fn/ - pointer to the function that will be
594 asynchronously called when the last session's command finishes and the
595 session is about to be completely freed. Can be NULL. Parameter:
596
597         <itemize>
598
599         <item><bf/sess/ - session
600
601         </itemize>
602         
603 </itemize>
604
605 All outstanding commands will be finished regularly. After
606 <bf/scst_unregister_session()/ returned no new commands must be sent to
607 SCST via <bf/scst_rx_cmd()/. Also, the caller must ensure that no
608 <bf/scst_rx_cmd()/ or <bf/scst_rx_mgmt_fn_*()/ is called in parallel
609 with <bf/scst_unregister_session()/. 
610
611 Function <bf/scst_unregister_session()/ can be called before
612 <bf/result_fn()/ of <bf/scst_register_session()/ called, i.e. during the
613 session registration/initialization.
614
615 <sect>The commands processing and interaction between SCST and its drivers
616
617 <p>
618 The commands processing by SCST started when target driver calls
619 <bf/scst_rx_cmd()/. This function returns SCST's command. Then the target
620 driver finishes the command's initialization, if necessary, for
621 example, storing necessary target driver specific data there, and calls
622 <bf/scst_cmd_init_done()/ telling SCST that it can start the processing.
623 Then SCST translates the command's LUN to local device, determines the
624 command's data direction and required data buffer size by calling
625 appropriate device handler's <bf/parse()/ function. Then:
626
627 <itemize>
628
629 <item>If the command required no data transfer, it will be passed to
630 SCSI mid-level directly or via device handler's <bf/exec()/ call.
631
632 <item>If the command is a <bf/READ/ command (data to the remote/local initiator),
633 necessary space will be allocated and then the command will be passed
634 to SCSI mid-level directly or via device handler's <bf/exec()/ call.
635
636 <item>If the command is a <bf/WRITE/ command (data from the remote/local initiator),
637 necessary space will be allocated, then the target's <bf/rdy_to_xfer()/
638 function will be called, telling the target that the space is ready and
639 it can start data transferring. When all the data are read from the
640 target, it will call <bf/scst_rx_data()/, and the command will be passed
641 to SCSI mid-level directly or via device handler's <bf/exec()/ call.
642
643 </itemize>
644
645 When the command is finished by SCSI mid-level, device handler's
646 <bf/dev_done()/ is called to notify it about the command's
647 completion. Then in order to send the response the target's
648 <bf/xmit_response()/ is called. When the response, including data, if
649 any, is transmitted, the target will call <bf/scst_tgt_cmd_done()/
650 telling SCST that it can free the command and its data buffer.
651
652 Then during the command's deallocation device handler's and the target's
653 <bf/on_free_cmd()/ will be called in this order, if set.
654
655 This sequence is illustrated on Figure 4. To simplify the picture, sign
656 "..." means SCST's waiting state for the corresponding command to
657 complete. During this state SCST and its drivers continue processing of
658 other commands, if there are any. One way arrow, for example to
659 <bf/xmit_response()/, means that after this function returns, nothing
660 valuable for the current command will be done and SCST goes sleeping or
661 to the next command processing until corresponding event happens.
662  
663 <figure>
664 <eps file="fig4.png">
665 <img src="fig4.png">
666 <caption>
667  <newline> The commands processing flow
668 </caption>
669 </figure>
670
671 Additionally, before calling <bf/scst_cmd_init_done()/ the target driver can
672 set the following the command's flags or parameters:
673
674 <itemize>
675
676 <item> <bf/DATA_BUF_ALLOCED/ - set if the data buffer is already 
677 allocated. The flag is set via <bf/scst_cmd_set_data_buff_alloced()/ and
678 get via <bf/scst_cmd_get_data_buff_alloced()/. Useful, for instance, for
679 iSCSI unsolicited data. 
680
681 <item> Expected transfer length and direction via
682 <bf/scst_cmd_set_expected()/ as supplied by remote initiator, if any.
683 This values will be used only if the command's opcode is unknown for
684 SCST, for example for vendor-specific commands. If these values not set
685 and opcode isn't known, the command will be completed by SCST in
686 preprocessing phase with <bf/INVALID OPCODE/ sense.
687
688 </itemize>
689
690 <sect1>The commands processing functions
691
692 <sect2>scst_rx_cmd()
693
694 <p>
695 Function <bf/scst_rx_cmd()/ creates and sends new command to SCST. Returns
696 the command on success or NULL otherwise. It is defined as the
697 following:
698
699 <verb>
700 struct scst_cmd *scst_rx_cmd(
701         struct scst_session *sess, 
702         const uint8_t *lun, 
703         int lun_len,
704         const uint8_t *cdb, 
705         int cdb_len, 
706         int atomic)
707 </verb>
708
709 Where:
710
711 <itemize>
712
713 <item><bf/sess/ - SCST's session
714
715 <item><bf/lun/ - pointer to device's LUN as specified in SCSI
716 Architecture Model 2/3 without any byte order translation. Extended
717 addressing method is not supported.
718
719 <item><bf/lun_len/ - LUN's length
720
721 <item><bf/cdb/ - SCSI CDB
722
723 <item><bf/cdb_len/ - CDB's length
724
725 <item><bf/atomic/ - if true, the command will be allocated with
726 GFP_ATOMIC flag, otherwise GFP_KERNEL will be used
727
728 </itemize>
729
730 <sect2>scst_cmd_init_done()
731
732 <p>
733 Function <bf/scst_cmd_init_done()/ notifies SCST that the driver finished
734 its part of the command initialization, and the command is ready for
735 execution. It is defined as the following:
736
737 <verb>
738 void scst_cmd_init_done(
739         struct scst_cmd *cmd, 
740         int pref_context)
741 </verb>
742
743 Where:
744
745 <itemize>
746
747 <item><bf/cmd/ - the command
748
749 <item><bf/pref_context/ - preferred command execution context. See
750 <bf/SCST_CONTEXT_*/ constants below for details.
751
752 </itemize>
753
754 <sect2>scst_rx_data()
755
756 <p>
757 Function <bf/scst_rx_data()/ notifies SCST that the driver received all
758 the necessary data and the command is ready for further processing. It
759 is defined as the following:
760
761 <verb>
762 void scst_rx_data(
763         struct scst_cmd *cmd, 
764         int status,
765         int pref_context)
766 </verb>
767
768 Where:
769
770 <itemize>
771
772 <item><bf/cmd/ - the command
773
774 <item><bf/status/ - completion status, see below.
775
776 <item><bf/pref_context/ - preferred command execution context. See
777 <bf/SCST_CONTEXT_*/ constants below for details.
778
779 </itemize>
780
781 Parameter <bf/status/ can have one of the following values:
782
783 <itemize>
784
785 <item><bf/SCST_RX_STATUS_SUCCESS/ - success
786
787 <item><bf/SCST_RX_STATUS_ERROR/ - data receiving finished with error, so
788 SCST should set the sense and finish the command by calling
789 <bf/xmit_response()/
790
791 <item><bf/SCST_RX_STATUS_ERROR_SENSE_SET/ - data receiving finished with 
792 error and the sense is set, so SCST should finish the command by calling 
793 <bf/xmit_response()/
794
795 <item><bf/SCST_RX_STATUS_ERROR_FATAL/ - data receiving finished with
796 fatal error, so SCST should finish the command, but don't call
797 <bf/xmit_response()/. In this case the driver must free all associated
798 with the command data before calling <bf/scst_rx_data()/.
799
800 </itemize>
801
802 <sect2>scst_tgt_cmd_done()
803
804 <p>
805 Function <bf/scst_tgt_cmd_done()/ notifies SCST that the driver sent the
806 data and/or response. It must not been called if there are an error and
807 <bf/xmit_response()/ returned something other, than
808 <bf/SCST_TGT_RES_SUCCESS/. It is defined as the following:
809
810 <verb>
811 void scst_tgt_cmd_done(
812         struct scst_cmd *cmd)
813 </verb>
814
815 Where:
816 <itemize>
817 <item><bf/cmd/ - the command
818 </itemize>
819
820 <sect1>The commands processing context
821
822 <p>
823 Execution context often is a major problem in the kernel drivers
824 development, because many contexts, like IRQ one, greatly limit
825 available functionality, therefore require additional complex code in
826 order to pass processing to more simple context. SCST does its best to
827 undertake most of the context handling. 
828
829 On the initialization time SCST creates for internal command processing
830 as many threads as there are processors in the system or specified by
831 user via <bf/scst_threads/ module parameter. Similarly, as many tasklets
832 created as there are processors in the system.
833
834 Each command can be processed in one of four contexts:
835
836 <enum>
837 <item>Directly, i.e. in the caller's context, without limitations
838 <item>Directly atomically, i.e. with sleeping forbidden
839 <item>In the SCST's internal per processor or per session thread
840 <item>In the SCST's per processor tasklet
841 </enum>
842
843 The target driver sets this context as pref_context parameter for 
844 <bf/scst_cmd_init_done()/ and <bf/scst_rx_data()/. Additionally, target's
845 template's <bf/xmit_response_atomic/ and <bf/rdy_to_xfer_atomic/ flags
846 have direct influence on the context. If one of them is false, the
847 corresponding function will never be called in the atomic context and,
848 if necessary, the command will be rescheduled to one of the SCST's 
849 threads.
850
851 SCST in some circumstances can change preferred context to less
852 restrictive one, for example, for large data buffer allocation, if
853 there is not enough GFP_ATOMIC memory. 
854
855 <sect2>Preferred context constants
856
857 <p>
858 There are the following preferred context constants: 
859
860 <itemize>
861
862 <item><bf/SCST_CONTEXT_DIRECT/ - sets direct command processing (i.e.
863 regular function calls in the current context) sleeping is allowed, no
864 context restrictions. Supposed to be used when calling from thread
865 context where no locks are held and the driver's architecture allows
866 sleeping without performance degradation or anything like that.
867
868 <item><bf/SCST_CONTEXT_DIRECT_ATOMIC/ - sets direct command processing 
869 (i.e. regular function calls in the current context), sleeping is not
870 allowed. Supposed to be used when calling on thread context where there
871 are locks held, when calling on softirq context or the driver's
872 architecture does not allow sleeping without performance degradation or
873 anything like that.
874
875 <item><bf/SCST_CONTEXT_TASKLET/ - tasklet or thread context required for 
876 the command processing. Supposed to be used when calling from IRQ
877 context.
878
879 <item><bf/SCST_CONTEXT_THREAD/ - thread context required for the
880 command processing. Supposed to be used if the driver's architecture
881 does not allow using any of above.
882
883 </itemize>
884
885 <sect>Task management functions
886
887 <p>
888 There are the following task management functions supported:
889
890 <itemize>
891
892 <item> <bf/SCST_ABORT_TASK/ - <bf/ABORT_TASK/ task management function,
893 aborts the specified task (command). Returns completion status via
894 <bf/task_mgmt_fn_done()/ when the command (task) is actually aborted.
895
896 <item> <bf/SCST_ABORT_TASK_SET/ - <bf/ABORT_TASK_SET/ task management
897 function, aborts all tasks (commands) on the specified device. Returns
898 the success via <bf/task_mgmt_fn_done()/ immediately, not waiting for
899 the commands being actually aborted.
900
901 <item> <bf/SCST_CLEAR_ACA/ - <bf/CLEAR_ACA/ task management function,
902 currently does nothing.
903
904 <item> <bf/SCST_CLEAR_TASK_SET/ - <bf/CLEAR_TASK_SET/ task management
905 function, the same as <bf/SCST_ABORT_TASK_SET/.
906
907 <item> <bf/SCST_LUN_RESET/ - <bf/LUN_RESET/ task management function,
908 implemented via <bf/scsi_reset_provider()/ call for the specified device
909 with <bf/SCSI_TRY_RESET_DEVICE/ parameter.
910
911 <item> <bf/SCST_TARGET_RESET/ - <bf/TARGET_RESET/ task management
912 function, implemented via <bf/scsi_reset_provider()/ call for all the
913 hosts in the system (one device per each host) with
914 <bf/SCSI_TRY_RESET_BUS/ parameter at first and then, if failed, with
915 <bf/SCSI_TRY_RESET_HOST/.
916
917 </itemize>
918
919 <sect1>scst_rx_mgmt_fn_tag()
920
921 <p>
922 Function <bf/scst_rx_mgmt_fn_tag()/ tells SCST to perform the specified
923 task management function, based on the command's tag. Can be used only
924 for <bf/SCST_ABORT_TASK/.
925
926 It is defined as the following:
927
928 <verb>
929 int scst_rx_mgmt_fn_tag(
930         struct scst_session *sess, 
931         int fn, 
932         uint32_t tag,
933         int atomic, 
934         void *tgt_specific)
935 </verb>
936
937 Where:
938
939 <itemize>
940
941 <item> <bf/sess/ - the session, on which the command should be performed.
942
943 <item> <bf/fn/ - task management function, one of the constants above.
944
945 <item> <bf/tag/ - the command's tag.
946
947 <item> <bf/atomic/ - true, if the function called in the atomic context.
948
949 <item> <bf/tgt_specific/ - pointer to the target driver specific data,
950 can be retrieved in <bf/task_mgmt_fn_done()/ via
951 <bf/scst_mgmt_cmd_get_status()/ function.
952
953 </itemize>
954
955 Returns 0 if the command was successfully created and scheduled for
956 execution, error code otherwise. On success, the completion status of
957 the command will be reported asynchronously via <bf/task_mgmt_fn_done()/
958 driver's callback.
959
960 <sect1>scst_rx_mgmt_fn_lun()
961
962 <p>
963 Function <bf/scst_rx_mgmt_fn_lun()/ tells SCST to perform the specified
964 task management function, based on the LUN. Currently it can be used for
965 any function, except <bf/SCST_ABORT_TASK/.
966
967 It is defined as the following:
968
969 <verb>
970 int scst_rx_mgmt_fn_lun(
971         struct scst_session *sess, 
972         int fn,
973         const uint8_t *lun, 
974         int lun_len,
975         int atomic, 
976         void *tgt_specific);
977 </verb>
978
979 Where:
980
981 <itemize>
982
983 <item> <bf/sess/ - the session, on which the command should be performed.
984
985 <item> <bf/fn/ - task management function, one of the constants above.
986
987 <item> <bf/lun/ - LUN, the format is the same as for <bf/scst_rx_cmd()/.
988
989 <item> <bf/lun_len/ - LUN's length.
990
991 <item> <bf/atomic/ - true, if the function called in the atomic context.
992
993 <item> <bf/tgt_specific/ - pointer to the target driver specific data,
994 can be retrieved in <bf/task_mgmt_fn_done()/ via
995 <bf/scst_mgmt_cmd_get_status()/ function.
996
997 </itemize>
998
999 Returns 0 if the command was successfully created and scheduled for
1000 execution, error code otherwise. On success, the completion status of
1001 the command will be reported asynchronously via <bf/task_mgmt_fn_done()/
1002 driver's callback.
1003
1004 <sect>Device specific drivers (device handlers)
1005
1006 <p>
1007 Device specific drivers are plugins for SCST, which help SCST to analyze
1008 incoming requests and determine parameters, specific to various types
1009 of devices. Device handlers are intended for the following:
1010
1011 <itemize>
1012
1013 <item>To get data transfer length and direction directly from CDB and
1014 current device's configuration exactly as an end-target SCSI device
1015 does. This serves two purposes:
1016
1017         <itemize>
1018         
1019         <item> Improves security and reliability by not trusting the data
1020         supplied by remote initiator via SCSI low-level protocol.
1021         
1022         <item> Some low-level SCSI protocols don't provide data transfer
1023         length and direction, so that information can be get only
1024         directly from CDB and current device's configuration. For
1025         example, for tape devices to get data transfer size it might be
1026         necessary to know block size setting.
1027         
1028         </itemize>
1029
1030 <item>To process some exceptional conditions, like ILI on tape devices.
1031
1032 <item>To initialize incoming commands with some device-specific
1033 parameters, like timeout value.
1034
1035 <item>To allow some additional device-specific commands pre-, post- 
1036 processing or alternative execution, like copying data from system
1037 cache, and do that completely independently from target drivers.
1038
1039 </itemize>
1040
1041 Device handlers performs very lightweight processing and therefore
1042 should not considerably affect performance or CPU load. They are
1043 considered to be part of SCST, so they could directly access any fields
1044 in SCST's structures as well as use the corresponding functions.
1045
1046 Without appropriate device handler SCST hides devices of this type from
1047 remote initiators and returns <bf/HARDWARE ERROR/ sense data to any
1048 requests to them.
1049
1050 <sect1>Device specific driver registration
1051
1052 <sect2>scst_register_dev_driver()
1053
1054 <p>
1055 To work with SCST a device specific driver must register itself in SCST by
1056 calling <bf/scst_register_dev_driver()/. It is defined as the following:
1057
1058 <verb>
1059 int scst_register_dev_driver(
1060         struct scst_dev_type *dev_type)
1061 </verb>
1062
1063 Where:
1064
1065 <itemize>
1066 <item><bf/dev_type/ - device specific driver's description structure
1067 </itemize>
1068
1069 The function returns 0 on success or appropriate error code otherwise.
1070
1071 <sect2>Structure <bf/scst_dev_type/
1072
1073 <p>
1074 Structure <bf/scst_dev_type/ is defined as the following:
1075
1076 <verb>
1077 struct scst_dev_type
1078 {
1079         char name[15];
1080         int type;
1081  
1082         unsigned parse_atomic:1;
1083         unsigned exec_atomic:1;
1084         unsigned dev_done_atomic:1;
1085         
1086         int (*init) (struct scst_dev_type *dev_type);
1087         void (*release) (struct scst_dev_type *dev_type);
1088  
1089         int (*attach) (struct scst_device *dev);
1090         void (*detach) (struct scst_device *dev);
1091  
1092         int (*attach_tgt) (struct scst_tgt_device *tgt_dev);
1093         void (*detach_tgt) (struct scst_tgt_device *tgt_dev);
1094  
1095         int (*parse) (struct scst_cmd *cmd);
1096         int (*exec) (struct scst_cmd *cmd, 
1097                 void (*scst_cmd_done)(struct scsi_cmnd *cmd, int next_state));
1098         int (*dev_done) (struct scst_cmd *cmd);
1099         int (*task_mgmt_fn) (struct scst_mgmt_cmd *mgmt_cmd, 
1100                 struct scst_tgt_dev *tgt_dev, struct scst_cmd *cmd_to_abort);
1101         int (*on_free_cmd) (struct scst_cmd *cmd);
1102         
1103         int (*proc_info) (char *buffer, char **start, off_t offset,
1104                 int length, int *eof, struct scst_dev_type *dev_type,
1105                 int inout)
1106  
1107         struct module *module;
1108 }
1109 </verb>
1110
1111 Where:
1112
1113 <itemize>
1114
1115 <item><bf/name/ - the name of the device handler. Must be defined and
1116 unique
1117
1118 <item><bf/type/ - SCSI type of the supported device. Must be defined.
1119
1120 <item><bf/parse_atomic/, <bf/exec_atomic/, <bf/dev_done_atomic/ - true,
1121 if corresponding function supports execution in the atomic
1122 (non-sleeping) context
1123
1124 <item><bf/int (*init) (struct scst_dev_type *dev_type)/ - called on the
1125 device handler load, before the first attach(). Returns 0 on success,
1126 error code otherwise.
1127
1128 <item><bf/void (*release) (struct scst_dev_type *dev_type)/ - called on
1129 the device handler unload, after final detach()
1130
1131 <item><bf/int (*attach) (struct scst_device *dev)/ - called when new
1132 device is attaching to the device handler
1133
1134 <item><bf/void (*detach) (struct scst_device *dev)/ - called when new
1135 device is detaching from the device handler
1136
1137 <item><bf/int (*attach_tgt) (struct scst_tgt_device *tgt_dev)/ - called
1138 when new tgt_device (session) is attaching to the device handler
1139
1140 <item><bf/void (*detach_tgt) (struct scst_tgt_device *tgt_dev)/ - called
1141 when tgt_device (session) is detaching from the device handler
1142
1143 <item><bf/int (*parse) (struct scst_cmd *cmd, const struct scst_info_cdb
1144 *cdb_info)/ - called to parse CDB from the command. It should initialize
1145 <bf/cmd->bufflen/ and <bf/cmd->data_direction/ (see below
1146 <bf/SCST_DATA_*/ constants) if necessary, otherwise defaults based on
1147 <bf/cdb_info/ will be used. Parameter <bf/cdb_info/ provides some info
1148 about the CDB (see below). Pay attention to "atomic" attribute of the
1149 cmd, which can be via by <bf/scst_cmd_atomic()/: it is true if the
1150 function called in the atomic (non-sleeping) context. Returns the 
1151 command's next state or <bf/SCST_CMD_STATE_DEFAULT/, if the next default 
1152 state should be used, or <bf/SCST_CMD_STATE_NEED_THREAD_CTX/ if the 
1153 function called in atomic context, but requires sleeping. In the last
1154 case, the function will be recalled in the thread context, where
1155 sleeping is allowed. Additionally, <bf/SCST_CMD_DATA_BUF_ALLOCED/ flag
1156 can be set by <bf/parse()/ (see above). Must be defined.
1157
1158 <item><bf/int (*exec) (struct scst_cmd *cmd, void (*scst_cmd_done)( struct
1159 scst_cmd *cmd, int next_state))/ - called to execute CDB. The result of
1160 the CDB execution is reported via <bf/scst_cmd_done()/ callback. Pay
1161 attention to "atomic" attribute of the command, which can be get via
1162 <bf/scst_cmd_atomic()/: it is true if the function called in the
1163 atomic (non-sleeping) context. For <bf/scst_cmd_done()/ parameter
1164 <bf/next_state/ is the command's next state or
1165 <bf/SCST_CMD_STATE_DEFAULT/, if the next default state should be used.
1166 Using this function modules <bf/devdisk_perf/ and <bf/devtape_perf/ were
1167 implemented. These modules in their <bf/exec()/ method skip (pretend to
1168 execute) all READ and WRITE operations and thus allow direct link
1169 performance measurements without overhead of actual data transferring
1170 from/to underlying SCSI device. See also <bf/scst_is_cmd_local()/ below.
1171 Returns:
1172
1173         <itemize>
1174
1175         <item><bf/SCST_EXEC_COMPLETED/ - the command is done, go to
1176         other ones
1177
1178         <item><bf/SCST_EXEC_NEED_THREAD/ - thread context is required to
1179         execute the command. <bf/Exec()/ will be called again in the
1180         thread context.
1181
1182         <item><bf/SCST_EXEC_NOT_COMPLETED/ - the command should be sent
1183         to SCSI mid-level.
1184         
1185         </itemize>
1186
1187 <item><bf/int (*dev_done) (struct scst_cmd *cmd)/ - called to notify
1188 device handler about the result of the command's execution and perform
1189 some post processing. If <bf/parse()/ function is called,
1190 <bf/dev_done()/ is guaranteed to be called as well. The command's fields
1191 <bf/tgt_resp_flags/ and <bf/resp_data_len/ should be set by this
1192 function, but SCST offers good defaults. Pay attention to "atomic"
1193 attribute of the command, which can be get via
1194 <bf/scst_cmd_atomic()/: it is true if the function called in the
1195 atomic (non-sleeping) context. Returns the command's next state or
1196 <bf/SCST_CMD_STATE_DEFAULT/, if the next default state should be used,
1197 or <bf/SCST_CMD_STATE_NEED_THREAD_CTX/ if the function called in atomic
1198 context, but requires sleeping. In the last case, the function will be
1199 recalled in the thread context, where sleeping is allowed.
1200
1201 <item><bf/int (*task_mgmt_fn) (struct scst_mgmt_cmd *mgmt_cmd,  struct
1202 scst_tgt_dev *tgt_dev, struct scst_cmd *cmd_to_abort)/ - called to
1203 execute a task management command. Returns: 
1204
1205         <itemize>
1206
1207         <item><bf/SCST_DEV_TM_COMPLETED_SUCCESS/ - the command is done
1208         with success, no further actions required
1209
1210         <item><bf/SCST_DEV_TM_COMPLETED_FAILED/ - the command is failed, 
1211         no further actions required
1212
1213         <item><bf/SCST_DEV_TM_NOT_COMPLETED/ - regular standard actions
1214         for the command should be done
1215
1216         </itemize>
1217
1218 <bf/NOTE/: for <bf/SCST_ABORT_TASK/ called under spinlock
1219
1220 <item><bf/void (*on_free_cmd) (struct scst_cmd *cmd)/ - called to notify
1221 device handler that the command is about to be freed. Could be called on
1222 IRQ context.
1223
1224 <item><bf/int (*proc_info) (char *buffer, char **start, off_t offset,
1225 int length, int *eof, struct scst_dev_type *dev_type, int inout)/ - this
1226 function can be used to export the handler's statistics and other
1227 information to the world outside the kernel. Parameters:
1228
1229         <enum>
1230         
1231         <item> <bf/buffer, start, offset, length, eof/ - have the same
1232         meaning as for <bf/read_proc_t/ function of the kernel
1233         
1234         <item> <bf/dev_type/ - pointer to the device handler, for which
1235         the function is called
1236         
1237         <item> <bf/inout/ - read/write direction flag, 0 - for reads, other
1238         value - for writes
1239         
1240         </enum>
1241
1242 If the driver needs to create additional files in its /proc
1243 subdirectory, it can use <bf/scst_proc_get_dev_type_root()/ function to get
1244 the root proc_dir_entry.
1245
1246 <item><bf/struct module *module/ - pointer to device handler's module
1247
1248 </itemize>
1249
1250 Structure <bf/scst_info_cdb/ is defined as the following:
1251
1252 <verb>
1253 struct scst_info_cdb
1254 {
1255         enum scst_cdb_flags flags;
1256         scst_data_direction direction;
1257         unsigned int transfer_len;
1258         unsigned short cdb_len;
1259         const char *op_name;
1260 }
1261 </verb>
1262
1263 Where:
1264
1265 <itemize>
1266
1267 <item><bf/flags/ - CDB's flags can be (OR'ed):
1268
1269         <itemize>
1270
1271         <item><bf/SCST_TRANSFER_LEN_TYPE_FIXED/ - set if data length in
1272         CDB set in blocks
1273
1274         <item><bf/SCST_SMALL_TIMEOUT/ - set if CDB requires small timeout
1275
1276         <item><bf/SCST_LONG_TIMEOUT/ - set if CDB requires long timeout
1277         
1278         </itemize>
1279
1280 <item><bf/direction/ - one of the <bf/SCST_DATA_*/ constants (see below)
1281
1282 <item><bf/transfer_len/ - CDB's data length as set in CDB
1283
1284 <item><bf/cdb_len/ - CDB's length
1285
1286 <item><bf/op_name/ - the name of the command
1287
1288 </itemize>
1289
1290 Field <bf/cmd->data_direction/, set by <bf/parse()/, can have one of the
1291 following values:
1292
1293 <itemize>
1294
1295 <item><bf/SCST_DATA_UNKNOWN/ - data flow direction is unknown
1296
1297 <item><bf/SCST_DATA_WRITE/ - data flow direction is <bf/WRITE/ (from
1298 target to initiator)
1299
1300 <item><bf/SCST_DATA_READ/ - data flow direction is <bf/READ/ (from
1301 initiator to target)
1302
1303 <item><bf/SCST_DATA_NONE/ - there is no data transfer
1304
1305 </itemize>
1306
1307 <sect1>Device specific driver unregistration
1308
1309 <p>
1310 Device specific driver is unregistered by calling
1311 <bf/scst_unregister_dev_driver()/. It is defined as the following:
1312
1313 <verb>
1314 void scst_unregister_dev_driver(
1315         struct scst_dev_type *dev_type)
1316 </verb>
1317
1318 Where:
1319
1320 <itemize>
1321 <item><bf/dev_type/ - device specific driver's description structure
1322 </itemize>
1323
1324 <sect>SCST commands' states
1325
1326 <p> 
1327 There are the following states, which a SCST command passes through
1328 during execution and which could be returned by device handler's
1329 <bf/parse()/ and <bf/dev_done()/ (but not all states are allowed to be
1330 returned): 
1331
1332 <itemize>
1333
1334 <item><bf/SCST_CMD_STATE_INIT_WAIT/ - the command is created, but 
1335 <bf/scst_cmd_init_done()/ not called
1336
1337 <item><bf/SCST_CMD_STATE_INIT/ - LUN translation (i.e. <bf/cmd->tgt_dev/
1338 assignment) state
1339
1340 <item><bf/SCST_CMD_STATE_REINIT/ - again LUN translation, used if device
1341 handler wants to restart the command on another LUN
1342
1343 <item><bf/SCST_CMD_STATE_DEV_PARSE/ - device handler's <bf/parse()/ is going
1344 to be called
1345
1346 <item><bf/SCST_CMD_STATE_PREPARE_SPACE/ - allocation of the command's
1347 data buffer
1348
1349 <item><bf/SCST_CMD_STATE_RDY_TO_XFER/ - target driver's
1350 <bf/rdy_to_xfer()/ is going to be called
1351
1352 <item><bf/SCST_CMD_STATE_DATA_WAIT/ - waiting for data from the initiator
1353 (until <bf/scst_rx_data()/ called)
1354
1355 <item><bf/SCST_CMD_STATE_SEND_TO_MIDLEV/ - the command is going to be
1356 sent to SCSI mid-level for execution
1357
1358 <item><bf/SCST_CMD_STATE_EXECUTING/ - waiting for the command's execution 
1359 finish
1360
1361 <item><bf/SCST_CMD_STATE_DEV_DONE/ - device handler's <bf/dev_done()/ is
1362 going to be called
1363
1364 <item><bf/SCST_CMD_STATE_XMIT_RESP/ - target driver's
1365 <bf/xmit_response()/ is going to be called
1366
1367 <item><bf/SCST_CMD_STATE_XMIT_WAIT/ - waiting for data/response's
1368 transmission finish (until <bf/scst_tgt_cmd_done()/ called)
1369
1370 <item><bf/SCST_CMD_STATE_FINISHED/ - the command finished and going to be 
1371 freed
1372
1373 </itemize>
1374
1375 <sect>SCST's structures manipulation functions
1376
1377 <p>
1378 Target drivers must not directly access any fields in SCST's structures,
1379 they must use only described below functions.
1380
1381 <sect1>SCST target driver manipulation functions
1382
1383 <sect2>scst_tgt_get_tgt_specific() and scst_tgt_set_tgt_specific()
1384
1385 <p> 
1386 Function <bf/scst_tgt_get_tgt_specific()/ returns pointer to the target
1387 driver specific data, set by <bf/scst_tgt_set_tgt_specific()/. It is
1388 defined as the following:
1389
1390 <verb>
1391 void *scst_tgt_get_tgt_specific(
1392         struct scst_tgt *tgt)
1393 </verb>
1394
1395 Function <bf/scst_tgt_set_tgt_specific()/ stores the target driver
1396 specific data that could be retrieved later by
1397 by<bf/scst_tgt_get_tgt_specific()/. It is defined as the following:
1398
1399 <verb>
1400 void scst_tgt_set_tgt_specific(
1401         struct scst_tgt *tgt,
1402         void *val)
1403 </verb>
1404
1405 Where:
1406
1407 <itemize>
1408 <item><bf/tgt/ - pointer to the SCST target structure
1409 <item><bf/val/ - pointer to the target driver specific data
1410 </itemize>
1411
1412 <sect1>SCST session manipulation functions
1413
1414 <sect2>scst_sess_get_tgt_specific() and scst_sess_set_tgt_specific()
1415
1416 <p>
1417 Function <bf/scst_sess_get_tgt_specific()/ returns pointer to the target
1418 driver specific data, set by <bf/scst_sess_set_tgt_specific()/. It is
1419 defined as the following:
1420
1421 <verb>
1422 void *scst_sess_get_tgt_specific(
1423         struct scst_session *sess)
1424 </verb>
1425
1426 Function <bf/scst_sess_set_tgt_specific()/ stores the target driver
1427 specific data that could be retrieved later by
1428 by<bf/scst_sess_get_tgt_specific()/. It is defined as the following:
1429
1430 <verb>
1431 void scst_sess_set_tgt_specific(
1432         struct scst_session *sess,
1433         void *val)
1434 </verb>
1435
1436 Where:
1437
1438 <itemize>
1439 <item><bf/sess/ - pointer to the SCST session structure
1440 <item><bf/val/ - pointer to the target driver specific data
1441 </itemize>
1442
1443 <sect1>SCST command manipulation functions
1444
1445 <sect2>scst_cmd_atomic()
1446
1447 <p>
1448 Function <bf/scst_cmd_atomic()/ returns true if the command is
1449 being executed in the atomic context or false otherwise. It is defined
1450 as the following:
1451
1452 <verb>
1453 int scst_cmd_atomic(
1454         struct scst_cmd *cmd)
1455 </verb>
1456
1457 Where:
1458
1459 <itemize>
1460 <item><bf/cmd/ - pointer to the command to check
1461 </itemize>
1462
1463 <sect2>scst_cmd_get_session()
1464
1465 <p>
1466 Function <bf/scst_cmd_get_session()/ returns the command's session. It
1467 is defined as the following:
1468
1469 <verb>
1470 struct scst_session *scst_cmd_get_session(
1471         struct scst_cmd *cmd)
1472 </verb>
1473
1474 Where:
1475
1476 <itemize>
1477 <item><bf/cmd/ - pointer to the command
1478 </itemize>
1479
1480 <sect2>scst_cmd_get_resp_data_len()
1481
1482 <p>
1483 Function <bf/scst_cmd_get_resp_data_len()/ returns the command's
1484 response data length. It is defined as the following:
1485
1486 <verb>
1487 unsigned int scst_cmd_get_resp_data_len(
1488         struct scst_cmd *cmd)
1489 </verb>
1490
1491 Where:
1492
1493 <itemize>
1494 <item><bf/cmd/ - pointer to the command
1495 </itemize>
1496
1497 <sect2>scst_cmd_get_tgt_resp_flags()
1498
1499 <p>
1500 Function <bf/scst_cmd_get_tgt_resp_flags()/ returns the command's
1501 response data response flags (SCST_TSC_FLAG_* constants). It is defined
1502 as the following:
1503
1504 <verb>
1505 int scst_cmd_get_tgt_resp_flags(
1506         struct scst_cmd *cmd)
1507 </verb>
1508
1509 Where:
1510
1511 <itemize>
1512 <item><bf/cmd/ - pointer to the command
1513 </itemize>
1514
1515 <sect2>scst_cmd_get_buffer()
1516
1517 <p>
1518 Function <bf/scst_cmd_get_buffer()/ returns the command's data buffer.
1519 It is defined as the following:
1520
1521 <verb>
1522 void *scst_cmd_get_buffer(
1523         struct scst_cmd *cmd)
1524 </verb>
1525
1526 Where:
1527
1528 <itemize>
1529 <item><bf/cmd/ - pointer to the command
1530 </itemize>
1531
1532 It is recommended to use <bf/scst_get_buf_*()/scst_put_buf()/ family of
1533 function instead of direct access to the data buffers, because they hide
1534 all HIGHMEM and SG/plain buffer issues.
1535
1536 <sect2>scst_cmd_get_bufflen()
1537
1538 <p>
1539 Function <bf/scst_cmd_get_bufflen()/ returns the command's data buffer
1540 length. It is defined as the following:
1541
1542 <verb>
1543 unsigned int scst_cmd_get_bufflen(
1544         struct scst_cmd *cmd)
1545 </verb>
1546
1547 Where:
1548
1549 <itemize>
1550 <item><bf/cmd/ - pointer to the command
1551 </itemize>
1552
1553 It is recommended to use <bf/scst_get_buf_*()/scst_put_buf()/ family of
1554 function instead of direct access to the data buffers, because they hide
1555 all HIGHMEM and SG/plain buffer issues.
1556
1557 <sect2>scst_cmd_get_use_sg()
1558
1559 <p>
1560 Function <bf/scst_cmd_get_use_sg()/ returns the command's <bf/use_sg/
1561 value. Its meaning is the same as for <bf/scsi_cmnd/. The function is
1562 defined as the following:
1563
1564 <verb>
1565 unsigned short scst_cmd_get_use_sg(
1566         struct scst_cmd *cmd)
1567 </verb>
1568
1569 Where:
1570
1571 <itemize>
1572 <item><bf/cmd/ - pointer to the command
1573 </itemize>
1574
1575 It is recommended to use <bf/scst_get_buf_*()/scst_put_buf()/ family of
1576 function instead of direct access to the data buffers, because they hide
1577 all HIGHMEM and SG/plain buffer issues.
1578
1579 <sect2>scst_cmd_get_data_direction()
1580
1581 <p>
1582 Function <bf/scst_cmd_get_data_direction()/ returns the command's data
1583 direction (SCST_DATA_* constants). It is defined as the following:
1584
1585 <verb>
1586 scst_data_direction scst_cmd_get_data_direction(
1587         struct scst_cmd *cmd)
1588 </verb>
1589
1590 Where:
1591
1592 <itemize>
1593 <item><bf/cmd/ - pointer to the command
1594 </itemize>
1595
1596 <sect2>scst_cmd_get_status()
1597
1598 <p>
1599 Functions <bf/scst_cmd_get_status()/ returns the status byte from
1600 host device. It is defined as the following:
1601
1602 <verb>
1603 uint8_t scst_cmd_get_status(
1604         struct scst_cmd *cmd)
1605 </verb>
1606
1607 Where:
1608
1609 <itemize>
1610 <item><bf/cmd/ - pointer to the command
1611 </itemize>
1612
1613 <sect2>scst_cmd_get_masked_status()
1614
1615 <p>
1616 Functions <bf/scst_cmd_get_masked_status()/ returns the status byte set
1617 from host device by status_byte(). It is defined as the following:
1618
1619 <verb>
1620 uint8_t scst_cmd_get_masked_status(
1621         struct scst_cmd *cmd)
1622 </verb>
1623
1624 Where:
1625
1626 <itemize>
1627 <item><bf/cmd/ - pointer to the command
1628 </itemize>
1629
1630 <sect2>scst_cmd_get_msg_status()
1631
1632 <p>
1633 Functions <bf/scst_cmd_get_msg_status()/ returns the status from host
1634 adapter itself. It is defined as the following:
1635
1636 <verb>
1637 uint8_t scst_cmd_get_msg_status(
1638         struct scst_cmd *cmd)
1639 </verb>
1640
1641 Where:
1642
1643 <itemize>
1644 <item><bf/cmd/ - pointer to the command
1645 </itemize>
1646
1647 <sect2>scst_cmd_get_host_status()
1648
1649 <p>
1650 Functions <bf/scst_cmd_get_host_status()/ returns the status set by
1651 low-level driver to indicate its status. It is defined as the following:
1652
1653 <verb>
1654 uint16_t scst_cmd_get_host_status(
1655         struct scst_cmd *cmd)
1656 </verb>
1657
1658 Where:
1659
1660 <itemize>
1661 <item><bf/cmd/ - pointer to the command
1662 </itemize>
1663
1664 <sect2>scst_cmd_get_driver_status()
1665
1666 <p>
1667 Functions <bf/scst_cmd_get_driver_status()/ returns the status set by
1668 SCSI mid-level. It is defined as the following:
1669
1670 <verb>
1671 uint16_t scst_cmd_get_driver_status(
1672         struct scst_cmd *cmd)
1673 </verb>
1674
1675 Where:
1676
1677 <itemize>
1678 <item><bf/cmd/ - pointer to the command
1679 </itemize>
1680
1681 <sect2>scst_cmd_get_sense_buffer()
1682
1683 <p>
1684 Functions <bf/scst_cmd_get_sense_buffer()/ returns pointer to the sense
1685 buffer. It is defined as the following:
1686
1687 <verb>
1688 uint8_t *scst_cmd_get_sense_buffer(
1689         struct scst_cmd *cmd)
1690 </verb>
1691
1692 Where:
1693
1694 <itemize>
1695 <item><bf/cmd/ - pointer to the command
1696 </itemize>
1697
1698 <sect2>scst_cmd_get_sense_buffer_len()
1699
1700 <p>
1701 Functions <bf/scst_cmd_get_sense_buffer_len()/ returns the sense buffer
1702 length. It is defined as the following:
1703
1704 <verb>
1705 int scst_cmd_get_sense_buffer_len(
1706         struct scst_cmd *cmd)
1707 </verb>
1708
1709 Where:
1710
1711 <itemize>
1712 <item><bf/cmd/ - pointer to the command
1713 </itemize>
1714
1715 <sect2>scst_cmd_get_tag() and scst_cmd_set_tag()
1716
1717 <p> Function <bf/scst_cmd_get_tag()/ returns the command's tag, set by
1718 <bf/scst_cmd_set_tag()/. It is defined as the following:
1719
1720 <verb>
1721 uint32_t scst_cmd_get_tag(
1722         struct scst_cmd *cmd)
1723 </verb>
1724
1725 Function <bf/scst_cmd_set_tag()/ sets command's tag that could be
1726 retrieved later by <bf/scst_cmd_get_tag()/. It is defined as the
1727 following:
1728
1729 <verb>
1730 void scst_cmd_set_tag(
1731         struct scst_cmd *cmd,
1732         uint32_t tag)
1733 </verb>
1734
1735 Where:
1736
1737 <itemize>
1738 <item><bf/cmd/ - pointer to the command
1739 <item><bf/tag/ - the tag
1740 </itemize>
1741
1742 <sect2>scst_cmd_get_tgt_specific() and scst_cmd_get_tgt_specific_lock()
1743
1744 <p>
1745 Functions <bf/scst_cmd_get_tgt_specific()/ and
1746 <bf/scst_cmd_get_tgt_specific_lock()/ return pointer to the target
1747 driver specific data, set by <bf/scst_cmd_set_tgt_specific()/ or
1748 <bf/scst_cmd_set_tgt_specific_lock()/. Both function are basically the
1749 same, but the later one additionally takes lock, which helps to prevent
1750 some races. See <bf/scst_find_cmd()/ below for details.
1751
1752 They are defined as the following:
1753
1754 <verb>
1755 void *scst_cmd_get_tgt_specific(
1756         struct scst_cmd *cmd)
1757 </verb>
1758
1759 <verb>
1760 void *scst_cmd_get_tgt_specific_lock(
1761         struct scst_cmd *cmd)
1762 </verb>
1763
1764 Where:
1765
1766 <itemize>
1767 <item><bf/cmd/ - pointer to the command
1768 </itemize>
1769
1770 <sect2>scst_cmd_set_tgt_specific() and scst_cmd_set_tgt_specific_lock()
1771
1772 <p>
1773 Functions <bf/scst_cmd_set_tgt_specific()/ and
1774 <bf/scst_cmd_set_tgt_specific_lock()/ store the target driver specific
1775 data,  that could be retrieved later by <bf/scst_cmd_get_tgt_specific()/
1776 or <bf/scst_cmd_get_tgt_specific_lock()/. Both function are basically
1777 the same, but the later one additionally takes lock, which helps to
1778 prevent some races. See <bf/scst_find_cmd()/ below for details.
1779
1780 They are defined as the following:
1781
1782 <verb>
1783 void *scst_cmd_set_tgt_specific(
1784         struct scst_cmd *cmd,
1785         void *val)
1786 </verb>
1787
1788 <verb>
1789 void *scst_cmd_set_tgt_specific_lock(
1790         struct scst_cmd *cmd,
1791         void *val)
1792 </verb>
1793
1794 Where:
1795
1796 <itemize>
1797 <item><bf/cmd/ - pointer to the command
1798 <item><bf/val/ - pointer to the target driver specific data
1799 </itemize>
1800
1801 <sect2>scst_cmd_get_data_buff_alloced() and scst_cmd_set_data_buff_alloced()
1802
1803 <p>
1804 Function <bf/scst_cmd_get_data_buff_alloced()/ returns the state of the
1805 <bf/SCST_CMD_DATA_BUF_ALLOCED/ flag. It is defined as the following:
1806
1807 <verb>
1808 int scst_cmd_get_data_buff_alloced(
1809         struct scst_cmd *cmd)
1810 </verb>
1811
1812 Function <bf/scst_cmd_set_data_buff_alloced()/ tells SCST that the data
1813 buffer is alloced by target driver or device handler by setting the
1814 <bf/SCST_CMD_DATA_BUF_ALLOCED/ flag on. Could be useful, for instance,
1815 for iSCSI unsolicited data. It is defined as the following:
1816
1817 <verb>
1818 void scst_cmd_set_data_buff_alloced(
1819         struct scst_cmd *cmd)
1820 </verb>
1821
1822 Where:
1823
1824 <itemize>
1825 <item><bf/cmd/ - pointer to the command
1826 </itemize>
1827
1828 <sect2>scst_cmd_set_expected(), scst_cmd_is_expected_set(),
1829 scst_cmd_get_expected_data_direction() and
1830 scst_cmd_get_expected_transfer_len()
1831
1832 <p>
1833 Function <bf/scst_cmd_set_expected()/ tells SCST expected data transfer
1834 direction and its length, as supplied by remote initiator. It is defined
1835 as the following:
1836
1837 <verb>
1838 void scst_cmd_set_expected(
1839         struct scst_cmd *cmd,
1840         scst_data_direction expected_data_direction,
1841         unsigned int expected_transfer_len)
1842 </verb>
1843
1844 Function <bf/scst_cmd_is_expected_set()/ returns true, if the expected
1845 values were set by target driver and false otherwise. It is defined as
1846 the following:
1847
1848 <verb>
1849 int scst_cmd_is_expected_set(
1850         struct scst_cmd *cmd)
1851 </verb>
1852
1853 Function <bf/scst_cmd_get_expected_data_direction()/ returns expected
1854 data direction set by target driver, if any. If this value was not set,
1855 the return value is undefined. It is defined as the following:
1856
1857 <verb>
1858 scst_data_direction scst_cmd_get_expected_data_direction(
1859         struct scst_cmd *cmd)
1860 </verb>
1861
1862 Function <bf/scst_cmd_get_expected_transfer_len()/ returns expected
1863 transfer length set by target driver, if any. If this value was not set,
1864 the return value is undefined. It is defined as the following:
1865
1866 <verb>
1867 unsigned int scst_cmd_get_expected_transfer_len(
1868         struct scst_cmd *cmd)
1869 </verb>
1870
1871 Where:
1872
1873 <itemize>
1874 <item><bf/cmd/ - pointer to the command
1875 <item><bf/expected_data_direction/ - expected data direction
1876 <item><bf/expected_transfer_len/ - expected transfer length
1877 </itemize>
1878
1879 <sect2>scst_get_buf_first(), scst_get_buf_next(),
1880 scst_put_buf() and scst_get_buf_count()
1881
1882 <p>
1883 These functions are designed to simplify and unify access to the
1884 commands data (SG vector or plain data buffer) in all possible
1885 conditions, including HIGHMEM environment, and should be used instead of
1886 direct access.
1887
1888 Function <bf/scst_get_buf_first()/ starts access to the data. It is defined
1889 as the following:
1890
1891 <verb>
1892 int scst_get_buf_first(
1893         struct scst_cmd *cmd, 
1894         uint8_t **buf)
1895 </verb>
1896
1897 Where:
1898
1899 <itemize>
1900 <item><bf/cmd/ - pointer to the command
1901 <item><bf/buf/ - pointer, where pointer to the first data chunk will be put
1902 </itemize>
1903
1904 Returns the length of the chunk of data for success, 0 for the end of
1905 data, negative error code otherwise. 
1906
1907 Function <bf/scst_get_buf_next()/ continues access to the data. It is defined
1908 as the following:
1909
1910 <verb>
1911 int scst_get_buf_next(
1912         struct scst_cmd *cmd, 
1913         uint8_t **buf)
1914 </verb>
1915
1916 Where:
1917
1918 <itemize>
1919 <item><bf/cmd/ - pointer to the command
1920 <item><bf/buf/ - pointer, where pointer to the next data chunk will be put
1921 </itemize>
1922
1923 Returns the length of the chunk of data for success, 0 for the end of
1924 data, negative error code otherwise. 
1925
1926 Function <bf/scst_put_buf()/ tells SCST that the user of the chunk of
1927 data, returned by <bf/scst_get_buf_first()/ or <bf/scst_get_buf_next()/,
1928 finished accessing the data. This function must be called for all chunks
1929 of data, returned by <bf/scst_get_buf_first()/ or
1930 <bf/scst_get_buf_next()/. It is defined as the following:
1931
1932 <verb>
1933 void scst_put_buf(
1934         struct scst_cmd *cmd, 
1935         uint8_t *buf)
1936 </verb>
1937
1938 Where:
1939
1940 <itemize>
1941 <item><bf/cmd/ - pointer to the command
1942 <item><bf/buf/ - pointer to the data chunk
1943 </itemize>
1944
1945 Function <bf/scst_get_buf_count()/ returns the approximate higher
1946 rounded count of data chunks that <bf/scst_get_buf_[first|next]()/ will
1947 return. It is defined as the following:
1948
1949 <verb>
1950 int scst_get_buf_count(
1951         struct scst_cmd *cmd)
1952 </verb>
1953
1954 Where:
1955
1956 <itemize>
1957 <item><bf/cmd/ - pointer to the command
1958 </itemize>
1959
1960 <sect1>SCST task management commands manipulation functions
1961
1962 <sect2>scst_mgmt_cmd_get_tgt_specific()
1963
1964 <p>
1965 Function <bf/scst_mgmt_cmd_get_tgt_specific()/ returns pointer to the
1966 target driver specific data, set on call of <bf/scst_rx_mgmt_fn_tag()/
1967 or <bf/scst_rx_mgmt_fn_lun()/. It is defined as the following:
1968
1969 <verb>
1970 void *scst_mgmt_cmd_get_tgt_specific(
1971         struct scst_mgmt_cmd *mcmd)
1972 </verb>
1973
1974 Where:
1975
1976 <itemize>
1977 <item><bf/mcmd/ - pointer to the task management command
1978 </itemize>
1979
1980 <sect2>scst_mgmt_cmd_get_status()
1981
1982 <p>
1983 Functions <bf/scst_mgmt_cmd_get_status()/ returns task management
1984 command's completion status. It is defined as the following:
1985
1986 <verb>
1987 void *scst_mgmt_cmd_get_status(
1988         struct scst_mgmt_cmd *mcmd)
1989 </verb>
1990
1991 Where:
1992
1993 <itemize>
1994 <item><bf/mcmd/ - pointer to the task management command
1995 </itemize>
1996
1997 The following status values are possible:
1998
1999 <itemize>
2000
2001 <item> SCST_MGMT_STATUS_SUCCESS - the task management command completed
2002 successfully
2003
2004 <item> SCST_MGMT_STATUS_FAILED - the task management command failed.
2005
2006 </itemize>
2007
2008 <sect>Miscellaneous functions
2009
2010 <sect1>scst_find_cmd_by_tag()
2011
2012 <p>
2013 Function <bf/scst_find_cmd_by_tag()/ is designed to find SCST's command
2014 based on the supplied tag comparing it with one that previously set by
2015 <bf/scst_cmd_set_tag()/. This value should be set by the target driver
2016 on the command's initialization time.
2017
2018 It is defined as the following:
2019
2020 <verb>
2021 struct scst_cmd *scst_find_cmd_by_tag(
2022         struct scst_session *sess, 
2023         uint32_t tag)
2024 </verb>
2025
2026 Where:
2027
2028 <itemize>
2029 <item><bf/sess/ - session to which the command belongs
2030 <item><bf/tag/ - the tag
2031 </itemize>
2032
2033 Returns found command or NULL otherwise.
2034
2035 <sect1>scst_find_cmd()
2036
2037 <p>
2038 Function <bf/scst_find_cmd()/ is designed to find SCST's command. For example,
2039 it can be used to find the command by internal serial number that was
2040 supplied by a remote target's response.
2041
2042 It is defined as the following:
2043
2044 <verb>
2045 struct scst_cmd *scst_find_cmd(
2046         struct scst_session *sess, 
2047         void *data, 
2048         int (*cmp_fn)(struct scst_cmd *cmd, void *data))
2049 </verb>
2050
2051 Where:
2052
2053 <itemize>
2054
2055 <item><bf/sess/ - session to which the command belongs
2056
2057 <item><bf/data/ - comparison data that will be passed to <bf/cmp_fn()/
2058 as is
2059
2060 <item><bf/cmp_fn/ - comparison callback function that will be called for
2061 each the session's command. Should return true if the command is found,
2062 false otherwise. Parameters:
2063
2064         <itemize>
2065         <item><bf/cmd/ - the command to compare
2066         <item><bf/data/ - comparison data.
2067         </itemize>
2068
2069 </itemize>
2070
2071 Returns found command or NULL otherwise.
2072
2073 <bf/IMPORTANT/
2074
2075 SCST is designed in a such way that any command is always processed only
2076 by one thread at any time, so no locking is necessary. But there is one
2077 exception from that rule, it is <bf/scst_find_cmd()/ function. Since it
2078 calls the callback over all commands of the session in the internal
2079 lists, despite of the command's current state, there is a race
2080 possibility accessing to target specific data pointer between
2081 <bf/scst_cmd_set_tgt_specific()/ caller and <bf/cmp_fn()/, which usually
2082 calls <bf/scst_cmd_get_tgt_specific()/ from the different context. The
2083 only place, where it is safe to call <bf/scst_cmd_set_tgt_specific()/
2084 without the race probability, is between <bf/scst_rx_cmd()/ and
2085 <bf/scst_cmd_init_done()/. Thus, if you call
2086 <bf/scst_cmd_set_tgt_specific()/ only there, there is nothing to worry,
2087 always use the functions without "lock" suffix. Otherwise, be careful
2088 and, if necessary, use "lock" functions. In addition, <bf/cmp_fn()/ is
2089 allowed to use only target specific data and forbidden to call any
2090 SCST's functions.
2091
2092 <sect1>scst_get_cdb_info()
2093
2094 <p>
2095 Function <bf/scst_get_cdb_info()/ provides various CDB info. It is
2096 defined as the following:
2097
2098 <verb>
2099 int scst_get_cdb_info(
2100         const uint8_t *cdb_p, 
2101         int dev_type, 
2102         struct scst_info_cdb *info_p)
2103 </verb>
2104
2105 Where:
2106
2107 <itemize>
2108
2109 <item><bf/cdb_p/ - pointer to CDB
2110
2111 <item><bf/dev_type/ - SCSI device type
2112
2113 <item><bf/info_p/ - the result structure, see description in device
2114 handler's <bf/parse()/ chapter
2115
2116 </itemize>
2117
2118 Returns 0 on success, -1 otherwise.
2119
2120 <sect1>scst_to_dma_dir()
2121
2122 <p>
2123 Function <bf/scst_to_dma_dir()/ translates SCST's data direction to
2124 DMA one. It is defined as the following:
2125
2126 <verb>
2127 int scst_to_dma_dir(
2128         int scst_dir)
2129 </verb>
2130
2131 Where:
2132
2133 <itemize>
2134 <item><bf/scst_dir/ - one of the <bf/SCST_DATA_*/ constants
2135 </itemize>
2136
2137 Returns the corresponding <bf/PCI_DMA_*/ constant.
2138
2139 <sect1>scst_is_cmd_local()
2140
2141 <p>
2142 Function <bf/scst_is_cmd_local()/ checks if the command is handled
2143 by SCST (i.e. locally, as, e.g., REPORT LUNS command). Intended to be
2144 used in device handler's <bf/exec()/, when the device handler wants to
2145 perform all the commands, except ones that should be done by SCST
2146 itself. 
2147
2148 It is defined as the following:
2149
2150 <verb>
2151 int scst_is_cmd_local(
2152         struct scst_cmd *cmd)
2153 </verb>
2154
2155 Where:
2156
2157 <itemize>
2158 <item><bf/cmd/ - the command, which CDB should be checked
2159 </itemize>
2160
2161 Returns 1, if the command's CDB is locally handled by SCST or 0
2162 otherwise
2163
2164 <sect1>scst_register_virtual_device() and scst_unregister_virtual_device()
2165
2166 <p>
2167 These functions provide a way for device handlers to register a virtual
2168 (emulated) device, which will be visible only by remote initiators. For
2169 example, FILEIO device handler uses files on file system to makes from
2170 them virtual remotely available SCSI disks.
2171
2172 Function <bf/scst_register_virtual_device()/ registers a virtual device.
2173 During the registration the device handlers functions <bf/init()/ and
2174 <bf/attach()/ will be called, if defined. The function is defined as the
2175 following:
2176
2177 <verb>
2178 int scst_register_virtual_device(
2179         struct scst_dev_type *dev_handler)
2180 </verb>
2181
2182 Where:
2183
2184 <itemize>
2185 <item><bf/dev_handler/ - device handler's descriptor
2186 </itemize>
2187
2188 Returns assigned to the device ID on success, or negative value otherwise.
2189
2190 Function <bf/scst_unregister_virtual_device()/ unregisters a virtual
2191 device. During the unregistration the device handlers functions
2192 <bf/detach()/ and <bf/release()/ will be called, if defined. The
2193 function is defined as the following:
2194
2195 <verb>
2196 void scst_unregister_virtual_device(
2197         int id)
2198 </verb>
2199
2200 Where:
2201
2202 <itemize>
2203 <item><bf/id/ - the device's ID, returned by 
2204 <bf/scst_register_virtual_device()/
2205 </itemize>
2206
2207 <sect1>scst_add_threads() and scst_del_threads()
2208
2209 <p>
2210 These functions allows to add or delete some SCST threads. For example,
2211 if <bf/exec()/ function in your device handler works synchronously, i.e.
2212 wait for job's completion, in order to prevent performance loss you
2213 can add for SCST as many threads as there are devices serviced by your
2214 device handler.
2215
2216 Function <bf/scst_add_threads()/ starts requested number of threads. It
2217 is defined as the following:
2218
2219 <verb>
2220 int scst_add_threads(
2221         int num)
2222 </verb>
2223
2224 Where:
2225
2226 <itemize>
2227 <item><bf/num/ - number of the threads to start
2228 </itemize>
2229
2230 Returns 0 on success, error code otherwise.
2231
2232 Function <bf/scst_del_threads()/ stops requested number of threads. It
2233 is defined as the following:
2234
2235 <verb>
2236 void scst_del_threads(
2237         int num)
2238 </verb>
2239
2240 Where:
2241
2242 <itemize>
2243 <item><bf/num/ - number of the threads to stop
2244 </itemize>
2245
2246 <sect1>scst_proc_get_tgt_root()
2247
2248 <p>
2249 Function <bf/scst_proc_get_tgt_root()/ returns target driver's root
2250 entry in SCST's /proc hierarchy. The driver can create own
2251 files/directories here, which should be deleted in the driver's
2252 release(). It is defined as the following:
2253
2254 <verb>
2255 struct proc_dir_entry *scst_proc_get_tgt_root(
2256         struct scst_tgt_template *vtt)
2257 </verb>
2258
2259 Where:
2260
2261 <itemize>
2262 <item><bf/vtt/ - pointer to the driver's template
2263 </itemize>
2264
2265 Returns proc_dir_entry on success, NULL otherwise.
2266
2267 <sect1>scst_proc_get_dev_type_root()
2268
2269 <p>
2270 Function <bf/scst_proc_get_dev_type_root()/ returns device handler's
2271 root entry in SCST's /proc hierarchy. The driver can create own
2272 files/directories here, which should be deleted in the driver's
2273 detach() or release(). It is defined as the following:
2274
2275 <verb>
2276 struct proc_dir_entry *scst_proc_get_dev_type_root(
2277         struct scst_dev_type *dtt)
2278 </verb>
2279
2280 Where:
2281
2282 <itemize>
2283 <item><bf/dtt/ - pointer to the handler's description structure
2284 </itemize>
2285
2286 Returns proc_dir_entry on success, NULL otherwise.
2287
2288 </article>