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