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