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