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