Version 0.4.
[mirror/scst/.git] / doc / scst_user_spec.txt
1         SCST USER SPACE DEVICE HANDLER MODULE.
2
3           USER SPACE INTERFACE DESCRIPTION.
4
5                    Version 0.4.
6
7
8                 I. Description.
9
10 SCST user space device handler module scst_user is a device handler for
11 SCST, which provides a way to implement in the user space complete, full
12 feature virtual SCSI devices in the SCST environment.
13
14 This document assumes that the reader is familiar with the SCST
15 architecture and the states through which SCSI commands go during
16 processing in SCST. Module scst_user basically only provides hooks to
17 them. Their description could be found on the SCST web page on
18 http://scst.st.net.
19
20
21                 II. User space API.
22
23 Module scst_user provides /dev/scst_user character device with the
24 following system calls available: 
25
26  - open() - allows to open the device and get a file handle, which
27    will be used in all subsequent actions until close() is called
28
29  - close() - closes file handle returned by open()
30  
31  - poll() - allows to wait until some pending command from SCST to
32    process is available.
33
34  - ioctl() - main call, which allows commands interchange with the SCST
35    core.
36
37 Device /dev/scst_user could be opened in blocking or non-blocking mode
38 using O_NONBLOCK flag. In the blocking mode ioctl()
39 SCST_USER_REPLY_GET_CMD function blocks until there is a new subcommand
40 to process. In the non-blocking mode if there are no pending subcommands
41 SCST_USER_REPLY_GET_CMD function returns immediately with EAGAIN error
42 code, and the user space device handler can use poll() call to get
43 notification about new subcommands arrival. The blocking mode is the
44 default.
45
46
47                 III. IOCTL() functions.
48
49 There are following IOCTL functions available. All of them has one
50 argument. They all, except SCST_USER_REGISTER_DEVICE return 0 for
51 success or -1 in case of error, and errno is set appropriately.
52
53
54                 1. SCST_USER_REGISTER_DEVICE
55
56 SCST_USER_REGISTER_DEVICE - registers new virtual user space device. The
57 argument is:
58
59 struct scst_user_dev
60 {
61         int version;
62         char name[SCST_MAX_NAME];
63         uint8_t type;
64 },
65
66 where:
67
68  - version - is a protocol version, shall be 0x0961
69
70  - name - name of the device
71  
72  - type - SCSI type of the device
73
74 SCST_USER_REGISTER_DEVICE returns registered device's handler or -1
75 in case of error, and errno is set appropriately.
76
77
78                 2. SCST_USER_UNREGISTER_DEVICE 
79
80 SCST_USER_UNREGISTER_DEVICE unregisters virtual user space device. The
81 argument is the device handler returned by SCST_USER_REGISTER_DEVICE
82 command. If there are some pending commands at the time, when
83 SCST_USER_UNREGISTER_DEVICE the function will fail with EBUSY errno set.
84
85
86                 3. SCST_USER_SET_OPTIONS/SCST_USER_GET_OPTIONS
87
88 SCST_USER_SET_OPTIONS/SCST_USER_GET_OPTIONS allows to set or get
89 correspondingly various options that control various aspects of SCSI
90 commands processing.
91
92 The argument is:
93
94 struct scst_user_dev
95 {
96         int h;
97         uint8_t parse_type;
98         uint8_t on_free_cmd_type;
99         uint8_t memory_reuse_type;
100         uint8_t partial_transfers_type;
101         uint32_t partial_len;
102 },
103
104 where (the first item is the default):
105
106  - h - corresponding device handle
107
108  - parse_type - defines how the user space handler wants to process
109    PARSE subcommand. Possible values are:
110   
111    * SCST_USER_PARSE_STANDARD - tells SCST use standard internal parse
112      routine for this SCSI device type.
113    
114    * SCST_USER_PARSE_CALL - tells SCST generate SCST_USER_PARSE for all
115      SCSI commands
116
117  - on_free_cmd_type - defines how the user space handler wants to
118    process ON_FREE_CMD subcommand. Possible values are:
119
120    * SCST_USER_ON_FREE_CMD_CALL - tells SCST generate
121      SCST_USER_ON_FREE_CMD for all SCSI commands
122
123    * SCST_USER_ON_FREE_CMD_IGNORE - tells SCST do nothing on this event.
124
125  - memory_reuse_type - defines how memory allocated by the user space
126    handler for a SCSI commands data buffers is then reused by the SCST
127    core as data buffer for subsequent commands. Possible values are:
128    
129    * SCST_USER_MEM_NO_REUSE - no memory reuse is possible, for each
130      commands the user space handler will each time allocate a dedicated
131      data buffer
132
133    * SCST_USER_MEM_REUSE_READ - memory reuse by only READ-type commands
134      (i.e. which involve data transfer from target to initiator) is
135      allowed. For all WRITE-type commands (i.e. which involves data
136      transfer from initiator to target) the user space handler will
137      each time allocate a dedicated data buffer
138
139    * SCST_USER_MEM_REUSE_WRITE - memory reuse by only WRITE-type
140      commands is allowed. For all WRITE-type commands the user space
141      handler will each time allocate a dedicated data buffer
142
143    * SCST_USER_MEM_REUSE_ALL - unlimited memory reuse is possible.
144
145  - partial_transfers_type - defines if the user space handler supports
146    partial data transfers, when a SCSI command, which required big data
147    transfer, is broken on several subcommands with smaller data
148    transfers. This allows to improve performance by simultaneous data
149    transfers from/to remote initiator and to/from the underlying storage
150    device as well as lower the allocation memory requirements for each
151    (sub)command. All subcommands will have the same unique value in
152    "parent_cmd_h" field and SCST_USER_SUBCOMMAND flag in "partial" field
153    of struct scst_user_scsi_cmd_exec. The final subcommand will also
154    have in that field SCST_USER_SUBCOMMAND_FINAL flag. All the
155    subcommands will have the original unmodified CDB. Possible values
156    are:
157    
158    * SCST_USER_PARTIAL_TRANSFERS_NOT_SUPPORTED - the partial data
159      transfers are not supported
160
161    * SCST_USER_PARTIAL_TRANSFERS_SUPPORTED_ORDERED - the partial data
162      transfers are supported, but all the subcommands must come in order
163      of data chunks. Could be used, e.g., for tape devices.
164
165    * SCST_USER_PARTIAL_TRANSFERS_SUPPORTED - the partial data transfers
166      are supported without limitations.
167
168 Flags parse_type and on_free_cmd_type are designed to improve
169 performance by eliminating context switches to the user space handler,
170 when processing of the corresponding event isn't needed.
171
172 Flag memory_reuse_type is designed to improve performance by eliminating
173 memory allocation, preparation and then freeing each time for each
174 commands, if the same memory will be allocated again and again. See
175 SCST_USER_ALLOC_MEM description below for more info.
176
177 By default, parse_type is SCST_USER_PARSE_STANDARD, on_free_cmd_type is
178 SCST_USER_ON_FREE_CMD_CALL and memory_reuse_type is
179 SCST_USER_MEM_NO_REUSE.
180
181
182                 4. SCST_USER_REPLY_AND_GET_CMD
183
184 If SCST_USER_REPLY_AND_GET_CMD allows at one call reply on the current
185 subcommand from SCST and get the next one. If 0 is returned by ioctl(),
186 SCST_USER_REPLY_AND_GET_CMD returns a SCST subcommand in the argument,
187 which is defined as the following:
188
189 struct scst_user_get_cmd
190 {
191         int h;
192         int subcode;
193         struct scst_user_reply_cmd *reply;
194         int cmd_h;
195         union {
196                 struct scst_user_sess sess;
197                 struct scst_user_sess_descr sess_descr;
198                 struct scst_user_scsi_cmd_parse parse_cmd;
199                 struct scst_user_scsi_cmd_alloc_mem alloc_cmd;
200                 struct scst_user_scsi_cmd_exec exec_cmd;
201                 struct scst_user_scsi_cmd_free_cmd on_free_cmd;
202                 struct scst_user_on_cached_mem_free on_cached_mem_free;
203                 struct scst_user_tm tm_cmd;
204         } payload;
205 },
206
207 where:
208
209  - h - corresponding device handle
210
211  - subcode - subcommand code, see 4.1 below
212
213  - reply - pointer to the reply data or, if NULL, there is no reply, see
214    SCST_USER_REPLY_CMD for description of struct scst_user_reply_cmd
215    fields
216
217  - cmd_h - command handle used to identify the command in the reply.
218
219  - payload - command specific payload
220
221 For all received subcommands the user space device handler shall call
222 SCST_USER_REPLY_AND_GET_CMD or SCST_USER_REPLY_CMD function to tell SCST
223 that the subcommand's processing is finished, although some subcommands
224 don't return a value.
225
226
227                 4.1. Possible subcommands:
228
229
230                 4.1.1. SCST_USER_ATTACH_SESS
231
232 SCST_USER_ATTACH_SESS notifies the user space handler that a new
233 initiator's session is about to be attached to the device. Field
234 "payload" contains struct scst_user_sess, which is defined as the
235 following:
236
237 struct scst_user_sess
238 {
239         int h;
240         uint64_t lun;
241         uint8_t rd_only;
242 },
243
244 where:
245
246  - h - session's handle
247
248  - lun - assigned LUN for this device in this session
249  
250  - rd_only - if true, this device is read only in this session
251  
252 If the user space handler needs more info about the session, it can call
253 SCST_USER_DESCRIBE_SESS subcommand.
254
255 The user space handler should reply with value 0 for success, or
256 negative error code from errno.h otherwise.
257
258
259                 4.1.2. SCST_USER_DETACH_SESS
260
261 SCST_USER_DETACH_SESS notifies the user space handler that the
262 corresponding initiator is about to be detached from the particular
263 device. Field "payload" contains struct scst_user_sess, where only
264 handle field is valid.
265
266 This command doesn't reply anything, although SCST_USER_REPLY_AND_GET_CMD or
267 SCST_USER_REPLY_CMD function must be called.
268
269
270                 4.1.3. SCST_USER_DESCRIBE_SESS
271
272 SCST_USER_DESCRIBE_SESS describes the session. Field "payload" contains
273 struct scst_user_sess_descr, which is defined as the following:
274
275 struct scst_user_sess_descr
276 {
277         char initiator_name[SCST_MAX_NAME];
278         char acg_name[SCST_MAX_NAME];
279 },
280
281 where:
282
283  - initiator_name - name of the initiator port
284
285  - acg_name - name of the corresponding SCST security group, to which
286    this session is assigned.
287
288 This command doesn't reply anything, although
289 SCST_USER_REPLY_AND_GET_CMD or SCST_USER_REPLY_CMD function must be
290 called.
291
292
293                 4.1.4. SCST_USER_PARSE
294
295 SCST_USER_PARSE returns SCSI command on PARSE state of the SCST
296 processing. The PARSE state is intended to check validity of the
297 command, determine data transfer type and the necessary data buffer
298 size. This subcommand is returned only if SCST_USER_SET_OPTIONS
299 parse_type is set to SCST_USER_PARSE_CALL. Otherwise, the standard SCST
300 internal parse routine for this SCSI device type will do all the job.
301
302 Field "payload" contains struct scst_user_scsi_cmd_parse, which is
303 defined as the following:
304
305 struct scst_user_scsi_cmd_parse
306 {
307         int sess_h;
308
309         uint8_t cdb[MAX_COMMAND_SIZE];
310         int cdb_len;
311
312         enum scst_cmd_queue_type queue_type;
313         int timeout;
314         scst_data_direction data_direction;
315         size_t bufflen;
316
317         scst_data_direction expected_data_direction;
318         unsigned int expected_transfer_len;
319         uint8_t expected_values_set;
320 },
321
322 where:
323
324  - sess_h - corresponding session handler
325
326  - cdb - SCSI CDB
327
328  - cdb_len - SCSI CDB length
329  
330  - queue_type - SCSI task attribute (queue type)
331  
332  - timeout - CDB execution timeout
333  
334  - data_direction - command's data flow direction, one of SCST_DATA_*
335    constants
336  
337  - bufflen - command's buffer length
338  
339  - expected_data_direction - remote initiator supplied command's data
340    flow direction
341
342  - expected_transfer_len - remote initiator supplied transfer length
343
344  - expected_values_set - true if expected_data_direction and
345    expected_transfer_len contain valid values
346    
347 In the PARSE state of SCSI commands processing the user space device
348 handler shall check and provide SCST values for command data buffer
349 length, data flow direction and timeout, which it shall reply using the
350 corresponding reply command.
351
352 In case of any error the error reporting should be deferred until
353 SCST_USER_EXEC subcommand, where the appropriate SAM status and sense
354 shall be set.
355    
356
357                 4.4.5. SCST_USER_ALLOC_MEM
358
359 SCST_USER_ALLOC_MEM returns SCSI command on memory allocation state of
360 the SCST processing. On this state the user space device handler shall
361 allocate the command's data buffer with bufflen length and then return
362 it to SCST using the corresponding reply command. There are no special
363 requirements for this memory or its alignment, it could be just what 
364 malloc() returns. Then SCST internally will convert it in SG vector in
365 order to use it itself and by target drivers.
366
367 This command will be returned only if parse_type was set to
368 SCST_USER_PARSE_STANDARD during the device registration, otherwise the
369 user space device handler shall allocate the command data buffer on the
370 PARSE stage.
371
372 Field "payload" contains struct scst_user_scsi_cmd_alloc_mem, which is
373 defined as the following:
374
375 struct scst_user_scsi_cmd_alloc_mem
376 {
377         int sess_h;
378
379         uint8_t cdb[MAX_COMMAND_SIZE];
380         int cdb_len;
381
382         enum scst_cmd_queue_type queue_type;
383         scst_data_direction data_direction;
384         size_t bufflen;
385 },
386
387 where:
388
389  - sess_h - corresponding session handler
390
391  - cdb - SCSI CDB
392
393  - cdb_len - SCSI CDB length
394  
395  - queue_type - SCSI task attribute (queue type )
396  
397  - data_direction - command's data flow direction, one of SCST_DATA_*
398    constants
399
400  - bufflen - command's buffer length
401
402 Memory allocation, preparation and freeing are ones of the most
403 complicated and expensive operations during SCSI commands processing.
404 Module scst_user provides a way to almost completely eliminate those
405 operations by reusing once allocated memory for subsequent SCSI
406 commands. It is controlled by memory_reuse_type option, which could be
407 set by SCST_USER_SET_OPTIONS function. If any type memory reusage is
408 enabled, then SCST will use its internal SGV cache in order to cache
409 allocated and fully built SG vectors for subsequent commands of this
410 type, so for them SCST_USER_ALLOC_MEM subfunction will not be called and
411 in SCST_USER_EXEC buf pointer will point to that reused buffer. 
412
413 SGV cache is a backend cache made on top of Linux kernel SLAB cache. It
414 caches SG vectors with power of 2 data sizes: 4K, 8K, ..., 4M. So, if
415 there is a 5K SCSI command coming, then the user space handler will be
416 asked for 8K allocation, from which only 5K will be used for this
417 particular SCSI command. Then that SG vector will be cached and
418 subsequently reused for all SCSI commands between 4K and 8K. For a
419 subsequent 1M SCSI command the user space handler will be asked for
420 another buffer (while the previous 5K one will be kept), which will not
421 be then reused for 5K SCSI commands, since 1M and 5K vectors belong to
422 different cache data sizes, it will be reused only for commands between
423 512K and 1M. Then, after some time of inactivity or when the system is
424 under memory pressure, the cache entries will be freed and the user
425 space handler will be notified using SCST_USER_ON_CACHED_MEM_FREE.
426
427 Since SGV cache caches SG vectors with power of 2 data sizes, bufflen
428 field could be up to 2 times more, than actually required by the SCSI
429 command.
430
431 The memory reuse could be used in both SCSI tagged and untagged queuing
432 environments. In the SCSI tagged queuing environment the SGV cache will
433 take care that several commands don't use the same buffer simultaneously
434 by asking the user space handler to allocate a new data buffer, when all
435 cached ones are busy.
436
437 Some important notes:
438
439 1. If the user space handler needs to call fork(), it must call
440 madvise() with MADV_DONTFORK flag all allocated data buffers, otherwise
441 parent or child process could loose the connection with them, which
442 could lead to data corruption. See http://lwn.net/Articles/171941/ for
443 details.
444
445 2. The interface assumes that all allocated memory by the user space
446 handler is DMA'able by the target hardware. This is almost always true
447 for most modern systems, except if the target hardware isn't capable of
448 using 64-bit address space and the system has >4GB of memory or the
449 momory addresses are in address space, which is unavailable with 32-bit
450 addresses.
451
452 In case of any error the error reporting should be deferred until
453 SCST_USER_EXEC subcommand, where the appropriate SAM status and sense
454 should be set.
455
456
457                 4.4.6. SCST_USER_EXEC
458
459 SCST_USER_EXEC returns SCSI command on execution state of the SCST
460 processing. The user space handler should execute the SCSI command and
461 reply using the corresponding reply command.
462
463 In some cases for performance reasons for READ-type SCSI commands
464 SCST_USER_ALLOC_MEM subcommand isn't returned before SCST_USER_EXEC.
465 Thus, if buf pointer is NULL and the SCSI command needs data transfer,
466 the user space handler should be prepared to allocate the data buffer
467 with size bufflen. Commands buffer length bufflen could be up to 2 times
468 more, than actually required by the SCSI command. Data length field
469 data_len contains the correct value. All the memory reusage rules,
470 described in 4.4.5, apply to SCST_USER_EXEC as well.
471
472 Field "payload" contains struct scst_user_scsi_cmd_exec, which is
473 defined as the following:
474
475 struct scst_user_scsi_cmd_exec
476 {
477         int sess_h;
478
479         uint8_t cdb[MAX_COMMAND_SIZE];
480         int cdb_len;
481
482         int timeout;
483         size_t data_len;
484         size_t bufflen;
485         uint8_t *buf;
486         enum scst_cmd_queue_type queue_type;
487         scst_data_direction data_direction;
488
489         uint8_t partial;
490         int parent_cmd_h;
491         size_t parent_cmd_data_len;
492         size_t partial_offset;
493 },
494
495 where:
496
497  - sess_h - corresponding session handler
498
499  - cdb - SCSI CDB
500
501  - cdb_len - SCSI CDB length
502
503  - timeout - CDB execution timeout
504  
505  - data_len - command's data length
506  
507  - bufflen - command's buffer length
508  
509  - buf - pointer to command's data buffer or NULL for SCSI commands
510    without data transfer.
511
512  - queue_type - SCSI task attribute (queue type)
513
514  - data_direction - command's data flow direction, one of SCST_DATA_*
515    constants
516
517  - partial - specifies, if the command is a partial subcommand, could
518    have the following OR'ed flags:
519
520    * SCST_USER_SUBCOMMAND - set if the command is a partial subcommand
521    
522    * SCST_USER_SUBCOMMAND_FINAL - set if the subcommand is a final one
523
524  - parent_cmd_h - has the same unique value for all partial data
525    transfers subcommands of one original (parent) command
526
527  - parent_cmd_data_len - for partial data transfers subcommand has the
528    size of the overall data transfer of the original (parent) command
529
530  - partial_offset - has offset of the subcommand in the original
531    (parent) command
532
533 In case of any error it should be reported via appropriate SAM status
534 and sense. If it happens for a subcommand of a partial data transfers
535 command, all other subcommands of this command, which already passed the
536 the user space handler or will be passed in the future, will be aborted,
537 the user space handler should ignore them.
538
539
540                 4.4.7. SCST_USER_ON_FREE_CMD
541
542 SCST_USER_ON_FREE_CMD returns SCSI command when the command is about to
543 be freed. At this stage, the user space device handler could do any
544 necessary cleanups, for instance, free allocated for data buffer memory.
545
546 NOTE! If the memory reusage is enabled, then the data buffer must not be
547 freed, it will be reused by subsequent SCSI commands. The buffer must be
548 freed only on SCST_USER_ON_CACHED_MEM_FREE event.
549
550 Field "payload" contains struct scst_user_scsi_cmd_on_free_cmd, which is
551 defined as the following:
552
553 struct scst_user_scsi_cmd_on_free_cmd
554 {
555         int sess_h;
556
557         uint8_t cdb[MAX_COMMAND_SIZE];
558         int cdb_len;
559
560         enum scst_cmd_queue_type queue_type;
561         scst_data_direction data_direction;
562         size_t data_len;
563         size_t bufflen;
564         uint8_t *buf;
565         int resp_data_len;
566
567         uint8_t status;
568         uint8_t sense_buffer[SCSI_SENSE_BUFFERSIZE];
569 },
570
571 where:
572
573  - sess_h - corresponding session handler
574
575  - cdb - SCSI CDB
576
577  - cdb_len - SCSI CDB length
578  
579  - queue_type - SCSI task attribute (queue type )
580  
581  - data_direction - command's data flow direction, one of SCST_DATA_*
582    constants
583
584  - data_len - command's data length
585  
586  - bufflen - command's buffer length
587
588  - buf - pointer to command's data buffer or NULL for SCSI commands
589    without data transfer.
590
591  - resp_data_len - length of the response data
592
593  - status - SAM status of the commands execution
594    
595  - sense_buffer - sense buffer
596    
597 The user space handler should reply using the corresponding reply
598 command. No error code is returned.
599
600
601                 4.4.9. SCST_USER_ON_CACHED_MEM_FREE
602
603 SCST_USER_ON_CACHED_MEM_FREE subcommand is returned, when SGV cache
604 decided that this buffer isn't needed anymore. This happens after some
605 time of inactivity or when the system is under memory pressure.
606
607 Field "payload" contains struct scst_user_on_cached_mem_free, which is
608 defined as the following:
609
610 struct scst_user_scsi_cmd_alloc_mem
611 {
612         int sess_h;
613
614         uint8_t *buf;
615         size_t bufflen;
616 },
617
618 where:
619
620  - sess_h - corresponding session handler
621
622  - buf - pointer to buffer, which should be freed
623
624  - bufflen - command's buffer length
625
626
627
628                 4.4.10. SCST_USER_TASK_MGMT
629  
630 SCST_USER_TASK_MGMT subcommand returns a task management functions.
631 Field "payload" contains struct scst_user_tm, which is defined as the
632 following:
633
634 struct scst_user_tm
635 {
636         int sess_h;
637         int fn;
638         int cmd_h_to_abort;
639 },
640
641 where:
642
643  - sess_h - corresponding session handler
644
645  - fn - task management function, see below
646
647  - cmd_h_to_abort - handle of command to abort. Valid only if fn is
648    SCST_ABORT_TASK
649    
650 After TM function completed, the user space device handler shall reply
651 using "result" field of the corresponding reply command. It isn't
652 necessary to wait for aborted command(s) finished, the result of TM
653 function could be returned immediately. SCST core will take care that
654 the reply to the TM function isn't sent before all affection SCSI
655 commands finished.
656
657 Possible values of "fn" field:
658
659  - SCST_ABORT_TASK - cmd_h_to_abort shall be aborted
660
661  - SCST_ABORT_TASK_SET - task set on the device shall be aborted
662
663  - SCST_CLEAR_ACA - ACA status shall be cleared
664
665  - SCST_CLEAR_TASK_SET  - task set on the device shall be cleared
666
667  - SCST_LUN_RESET, SCST_TARGET_RESET - reset of the device shall be done
668
669  - SCST_NEXUS_LOSS_SESS - notifies about nexus loss event for the session
670
671  - SCST_ABORT_ALL_TASKS_SESS - all tasks in the session shall be aborted
672  
673  - SCST_NEXUS_LOSS - notifies about global nexus loss event
674  
675  - SCST_ABORT_ALL_TASKS - all tasks shall be aborted
676
677 Possible return values are:
678
679  - SCST_DEV_TM_COMPLETED_SUCCESS - the command is done with success, no
680    further actions required
681   
682  - SCST_DEV_TM_COMPLETED_FAILED - the command is failed, no further
683    actions required
684
685  - SCST_DEV_TM_NOT_COMPLETED - the command partially completed, regular
686    standard actions for the command should be done
687
688
689                 5. SCST_USER_REPLY_CMD
690
691 SCST_USER_REPLY_CMD IOCTL function allows the user space handler to
692 return the result of a command's execution. Its argument is defined as:
693
694 struct scst_user_reply_cmd
695 {
696         int h;
697         int cmd_h;
698         union {
699                 int result;
700                 struct scst_user_scsi_cmd_reply_parse parse_reply;
701                 struct scst_user_scsi_cmd_reply_alloc_mem alloc_reply;
702                 struct scst_user_scsi_cmd_reply_exec exec_reply;
703         } payload;
704 },
705
706 where:
707
708  - h - corresponding device handle
709
710  - cmd_h - command handle used to identify the command in the reply.
711
712  - payload - subcommand specific payload:
713
714 struct scst_user_scsi_cmd_reply_parse
715 {
716         enum scst_cmd_queue_type queue_type;
717         scst_data_direction data_direction;
718         size_t data_len;
719         size_t bufflen;
720         uint8_t *buf;
721 },
722
723 where:
724
725  - queue_type - SCSI task attribute (queue type )
726  
727  - data_direction - command's data flow direction, one of SCST_DATA_* constants
728
729  - data_len - command's data length
730  
731  - bufflen - command's buffer length
732
733  - buf - pointer to command's data buffer or NULL for SCSI commands
734    without data transfer.
735
736 struct scst_user_scsi_cmd_reply_alloc_mem
737 {
738         uint8_t *buf;
739 },
740
741 where:
742
743  - buf - pointer to command's data buffer
744
745 struct scst_user_scsi_cmd_reply_exec
746 {
747         uint8_t *buf;
748         int resp_data_len;
749
750         uint8_t reply_type;
751
752         uint8_t status;
753         uint8_t sense_buffer[SCSI_SENSE_BUFFERSIZE];
754 },
755
756 where:
757
758  - buf - pointer to command's data buffer. Used only when in the
759    original SCST_USER_EXEC subcommand buf field is NULL
760
761  - resp_data_len - length of the response data
762
763  - reply_type - could be one of the following constants:
764  
765      * SCST_EXEC_REPLY_BACKGROUND - tells SCST send to the remote
766        initiator GOOD status, but the command not yet completed by the
767        user space handler, it is being executed in the background. When
768        it will be completed, the user space handler will call
769        SCST_USER_REPLY_CMD again with reply_type
770        SCST_EXEC_REPLY_COMPLETED.
771      
772      * SCST_EXEC_REPLY_COMPLETED - the user space handler completed the command
773
774  - status - SAM status of the commands execution
775    
776  - sense_buffer - sense buffer
777
778
779                 IV. Commands processing flow.
780
781 As the example consider a simple synchronous VTL, which serves one
782 virtual SCSI tape device and can process only one command at time from
783 any initiator. 
784
785 At the beginning the VTL opens using open() call /dev/scst_user in the
786 default blocking mode.
787
788 Then it using SCST_USER_REGISTER_DEVICE ioctl() function registers the
789 tape device. 
790
791 Since only one command at time is supported, the allocated command's
792 data memory could be reused for both READ-type (i.e. which involve data
793 transfer from target to initiator) and WRITE-type (i.e. which involve
794 data transfer from initiator to target) commands. So, the VTL then calls
795 SCST_USER_SET_OPTIONS function with handle h returned by
796 SCST_USER_REGISTER_DEVICE ioctl() and set parse_type to
797 SCST_USER_PARSE_STANDARD, on_free_cmd_type to
798 SCST_USER_ON_FREE_CMD_IGNORE and memory_reuse_type to
799 SCST_USER_MEM_REUSE_ALL.
800
801 Then it prepares struct scst_user_get_cmd with h set to the handle
802 returned by SCST_USER_REGISTER_DEVICE ioctl() and reply set to NULL,
803 calls SCST_USER_REPLY_AND_GET_CMD ioctl() and waits until some initiator
804 connects to its tape device. On that event the VTL receives
805 SCST_USER_ATTACH_SESS subcommand. Since the VTL doesn't use any
806 initiator specific data, it can do nothing on that subcommand, so it
807 prepares scst_user_reply_cmd structure, where:
808
809  - h set to handle returned by SCST_USER_REGISTER_DEVICE ioctl()
810  
811  - cmd_h set to returned by SCST_USER_REPLY_AND_GET_CMD ioctl() cmd_h
812  
813  - payload.result set to 0
814  
815 Then it prepares struct scst_user_get_cmd with h set to the handle
816 returned by SCST_USER_REGISTER_DEVICE ioctl() and reply set to the
817 prepared scst_user_reply_cmd structure, calls
818 SCST_USER_REPLY_AND_GET_CMD ioctl() and waits for some SCSI command
819 arrives from the initiator.
820
821 If the received SCSI command is READ-type one, SCST does the necessary
822 preparations, then the VTL receives SCST_USER_EXEC subcommand, where
823 bufflen and data_len are set correctly, but memory for buffer isn't
824 allocated, so buf field is NULL. The VTL then allocates the data buffer
825 with size bufflen, e.g. by malloc(). Then the VTL reads the data from
826 disk in it, e.g. using O_DIRECT read() function, then prepares
827 scst_user_reply_cmd structure, where:
828
829  - h set to handle returned by SCST_USER_REGISTER_DEVICE ioctl()
830  
831  - cmd_h set to returned by SCST_USER_REPLY_AND_GET_CMD ioctl() cmd_h
832  
833  - payload.exec_reply.buf set to the data buffer, where the data were read
834  
835  - payload.exec_reply.resp_data_len set to length of the read data
836  
837  - payload.exec_reply.reply_type set to SCST_EXEC_REPLY_COMPLETED
838  
839  - payload.exec_reply.status set to the SAM defined status of the
840    operation
841  
842  - payload.exec_reply.sense_buffer filled with the sense data, if
843    necessary
844
845 Then it prepares struct scst_user_get_cmd with h set to the handle
846 returned by SCST_USER_REGISTER_DEVICE ioctl() and reply set to the
847 prepared scst_user_reply_cmd structure, calls
848 SCST_USER_REPLY_AND_GET_CMD ioctl() and waits for the next SCSI command
849 arrives from the initiator. That's all for this SCSI command. For the
850 next one the used data buffer will be reused.
851
852 For WRITE-type SCSI commands the processing is the same, but
853 SCST_USER_ALLOC_MEM will be returned before SCST_USER_EXEC, since the
854 data transfer from the initiator precedes the commands execution.
855
856 In case, if the first command requires 4K data buffer, but the second
857 one - 1M, for it the VTL also will be asked to allocate the buffer.
858 Then, if no more 4K commands come for some time, for it
859 SCST_USER_ON_CACHED_MEM_FREE subcommand will be returned to the VTL in
860 order to ask it to free that buffer.