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