- Update to the latest IET r145
[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/3
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         uint32_t sn;
340 },
341
342 where:
343
344  - sess_h - corresponding session handler
345
346  - cdb - SCSI CDB
347
348  - cdb_len - SCSI CDB length
349  
350  - timeout - CDB execution timeout
351
352  - bufflen - command's buffer length
353  
354  - queue_type - SCSI task attribute (queue type)
355  
356  - data_direction - command's data flow direction, one of SCST_DATA_*
357    constants
358
359  - expected_values_set - true if expected_data_direction and
360    expected_transfer_len contain valid values
361    
362  - expected_data_direction - remote initiator supplied command's data
363    flow direction
364
365  - expected_transfer_len - remote initiator supplied transfer length
366
367  - sn - command's SN, which might be used for task management
368
369 In the PARSE state of SCSI commands processing the user space device
370 handler shall check and provide SCST values for command data buffer
371 length, data flow direction and timeout, which it shall reply using the
372 corresponding reply command.
373
374 In case of any error the error reporting should be deferred until
375 SCST_USER_EXEC subcommand, where the appropriate SAM status and sense
376 shall be set.
377    
378
379                 4.4.4. SCST_USER_ALLOC_MEM
380
381 SCST_USER_ALLOC_MEM returns SCSI command on memory allocation state of
382 the SCST processing. On this state the user space device handler shall
383 allocate the command's data buffer with bufflen length and then return
384 it to SCST using the corresponding reply command. Then SCST internally
385 will convert it in SG vector in order to use it itself and by target
386 drivers.
387
388 If the memory reuse type is disabled (i.e. set to SCST_USER_MEM_NO_REUSE)
389 there are no special requirements for buffer memory or its alignment, it
390 could be just what malloc() returned. If the memory reuse type is enabled,
391 the buffer shall be page size aligned, for example using memalign()
392 function.
393
394 Payload contains struct scst_user_scsi_cmd_alloc_mem, which is defined
395 as the following:
396
397 struct scst_user_scsi_cmd_alloc_mem
398 {
399         uint64_t sess_h;
400
401         uint8_t cdb[SCST_MAX_CDB_SIZE];
402         int32_t cdb_len;
403
404         int32_t alloc_len;
405
406         uint8_t queue_type;
407         uint8_t data_direction;
408
409         uint32_t sn;
410 },
411
412 where:
413
414  - sess_h - corresponding session handler
415
416  - cdb - SCSI CDB
417
418  - cdb_len - SCSI CDB length
419
420  - alloc_len - command's buffer length
421  
422  - queue_type - SCSI task attribute (queue type )
423
424  - data_direction - command's data flow direction, one of SCST_DATA_*
425    constants
426
427  - sn - command's SN, which might be used for task management
428
429 Memory allocation, preparation and freeing are ones of the most
430 complicated and expensive operations during SCSI commands processing.
431 Module scst_user provides a way to almost completely eliminate those
432 operations by reusing once allocated memory for subsequent SCSI
433 commands. It is controlled by memory_reuse_type option, which could be
434 set by SCST_USER_SET_OPTIONS function. If any type memory reusage is
435 enabled, then SCST will use its internal SGV cache in order to cache
436 allocated and fully built SG vectors for subsequent commands of this
437 type, so for them SCST_USER_ALLOC_MEM subfunction will not be called and
438 in SCST_USER_EXEC pbuf pointer will point to that reused buffer. 
439
440 SGV cache is a backend cache made on top of Linux kernel SLAB cache. It
441 caches SG vectors with power of 2 data sizes: 4K, 8K, ..., 4M. So, if
442 there is a 5K SCSI command coming, then the user space handler will be
443 asked for 8K allocation, from which only 5K will be used for this
444 particular SCSI command. Then that SG vector will be cached and
445 subsequently reused for all SCSI commands between 4K and 8K. For a 1M
446 SCSI command the user space handler will be asked for another buffer
447 (while the previous 5K one will be kept), which will not be then reused
448 for 5K SCSI commands, since 1M and 5K vectors belong to different cache
449 data sizes, it will be reused only for commands between 512K and 1M.
450 Then, after some time of inactivity or when the system is under memory
451 pressure, the cache entries will be freed and the user space handler
452 will be notified using SCST_USER_ON_CACHED_MEM_FREE.
453
454 Since SGV cache caches SG vectors with power of 2 data sizes, alloc_len
455 field could be up to 2 times more, than actually required by the SCSI
456 command.
457
458 The memory reuse could be used in both SCSI tagged and untagged queuing
459 environments. In the SCSI tagged queuing environment the SGV cache will
460 take care that several commands don't use the same buffer simultaneously
461 by asking the user space handler to allocate a new data buffer, when all
462 cached ones are busy.
463
464 Some important notes:
465
466 1. If the user space handler needs to call fork(), it must call
467 madvise() with MADV_DONTFORK flag for all allocated data buffers,
468 otherwise parent or child process could loose the connection with them,
469 which could lead to data corruption. See http://lwn.net/Articles/171941/
470 for details.
471
472 2. The interface assumes that all allocated memory by the user space
473 handler is DMA'able by the target hardware. This is almost always true
474 for most modern systems, except if the target hardware isn't capable of
475 using 64-bit address space and the system has >4GB of memory or the
476 memory addresses are in address space, which is unavailable with 32-bit
477 addresses.
478
479 In case of any error the error reporting should be deferred until
480 SCST_USER_EXEC subcommand, where the appropriate SAM status and sense
481 should be set.
482
483
484                 4.4.5. SCST_USER_EXEC
485
486 SCST_USER_EXEC returns SCSI command on execution state of the SCST
487 processing. The user space handler should execute the SCSI command and
488 reply using the corresponding reply command.
489
490 In some cases for performance reasons for READ-type SCSI commands
491 SCST_USER_ALLOC_MEM subcommand isn't returned before SCST_USER_EXEC.
492 Thus, if pbuf pointer is 0 and the SCSI command needs data transfer,
493 the user space handler should be prepared to allocate the data buffer
494 with size alloc_len, which could be up to 2 times more, than actually
495 required by the SCSI command. But field bufflen will contain the correct
496 value. All the memory reusage rules, described for SCST_USER_ALLOC_MEM,
497 apply to SCST_USER_EXEC as well.
498
499 Payload contains struct scst_user_scsi_cmd_exec, which is defined as the
500 following:
501
502 struct scst_user_scsi_cmd_exec
503 {
504         uint64_t sess_h;
505
506         uint8_t cdb[SCST_MAX_CDB_SIZE];
507         int32_t cdb_len;
508
509         int32_t data_len;
510         int32_t bufflen;
511         int32_t alloc_len;
512         uint64_t pbuf;
513         uint8_t queue_type;
514         uint8_t data_direction;
515         uint8_t partial;
516         uint32_t timeout;
517
518         uint32_t sn;
519
520         uint32_t parent_cmd_h;
521         int32_t parent_cmd_data_len;
522         uint32_t partial_offset;
523 },
524
525 where:
526
527  - sess_h - corresponding session handler
528
529  - cdb - SCSI CDB
530
531  - cdb_len - SCSI CDB length
532
533  - data_len - command's data length. Could be different from bufflen for
534    commands like VERIFY, which transfer different amount of data, than
535    process, or even none of them
536  
537  - bufflen - command's buffer length
538
539  - alloc_len - command's buffer length, which should be allocated, if pbuf
540    is 0 and the command requires data transfer
541
542  - pbuf - pointer to command's data buffer or 0 for SCSI commands
543    without data transfer.
544
545  - queue_type - SCSI task attribute (queue type)
546
547  - data_direction - command's data flow direction, one of SCST_DATA_*
548    constants
549
550  - partial - specifies, if the command is a partial subcommand, could
551    have the following OR'ed flags:
552
553    * SCST_USER_SUBCOMMAND - set if the command is a partial subcommand
554    
555    * SCST_USER_SUBCOMMAND_FINAL - set if the subcommand is a final one
556
557  - timeout - CDB execution timeout
558
559  - sn - command's SN, which might be used for task management
560
561  - parent_cmd_h - has the same unique value for all partial data
562    transfers subcommands of one original (parent) command
563
564  - parent_cmd_data_len - for partial data transfers subcommand has the
565    size of the overall data transfer of the original (parent) command
566
567  - partial_offset - has offset of the subcommand in the original
568    (parent) command
569
570 It is guaranteed that only commands of the same queue_type per session
571 can be returned simultaneously.
572
573 In case of any error it should be reported via appropriate SAM status
574 and sense. If it happens for a subcommand of a partial data transfers
575 command, all other subcommands of this command, which already passed the
576 the user space handler or will be passed in the future, will be aborted
577 by scst_user, the user space handler should ignore them.
578
579
580                 4.4.6. SCST_USER_ON_FREE_CMD
581
582 SCST_USER_ON_FREE_CMD returns SCSI command when the command is about to
583 be freed. At this stage, the user space device handler could do any
584 necessary cleanups, for instance, free allocated for data buffer memory.
585
586 NOTE! If the memory reusage is enabled, then the data buffer must not be
587 freed, it will be reused by subsequent SCSI commands. The buffer must be
588 freed only on SCST_USER_ON_CACHED_MEM_FREE event.
589
590 Payload contains struct scst_user_scsi_on_free_cmd, which is defined
591 as the following:
592
593 struct scst_user_scsi_on_free_cmd
594 {
595         uint64_t pbuf;
596         int32_t resp_data_len;
597         uint8_t buffer_cached;
598         uint8_t aborted;
599         uint8_t status;
600         uint8_t delivery_status;
601 },
602
603 where:
604
605  - pbuf - pointer to command's data buffer or 0 for SCSI commands
606    without data transfer.
607
608  - resp_data_len - length of the response data
609
610  - buffer_cached - true, if memory reusage is enabled for this command
611
612  - aborted - true, if command was aborted
613
614  - status - SAM status of the commands execution
615
616  - delivery_status - status of cmd's status/data delivery to remote
617    initiator. Can be:
618    
619    * SCST_CMD_DELIVERY_SUCCESS - delivery succeeded
620
621    * SCST_CMD_DELIVERY_FAILED - delivery failed
622
623 The user space handler should reply using the corresponding reply
624 command. No error code is needed.
625
626
627                 4.4.7. SCST_USER_ON_CACHED_MEM_FREE
628
629 SCST_USER_ON_CACHED_MEM_FREE subcommand is returned, when SGV cache
630 decided that this buffer isn't needed anymore. This happens after some
631 time of inactivity or when the system is under memory pressure.
632
633 Payload contains struct scst_user_on_cached_mem_free, which is defined
634 as the following:
635
636 struct scst_user_scsi_cmd_alloc_mem
637 {
638         uint64_t pbuf;
639 },
640
641 where:
642
643  - pbuf - pointer to buffer, which should be freed
644
645
646                 4.4.8. SCST_USER_TASK_MGMT
647  
648 SCST_USER_TASK_MGMT subcommand returns a task management functions.
649 Payload contains struct scst_user_tm, which is defined as the following:
650
651 struct scst_user_tm
652 {
653         uint64_t sess_h;
654         uint32_t fn;
655         uint32_t cmd_h_to_abort;
656         uint32_t cmd_sn;
657         uint8_t cmd_sn_set;
658 },
659
660 where:
661
662  - sess_h - corresponding session handler
663
664  - fn - task management function, see below
665
666  - cmd_h_to_abort - handle of command to abort. Valid only if fn is
667    SCST_ABORT_TASK
668
669  - cmd_sn - if cmd_sn_set is set, contains maximum commands SN, which
670    this task management function affects. See iSCSI RFC 3720 10.5.1 for
671    more details.
672
673  - cmd_sn_set - specifies if cmd_sn is valid
674    
675 After TM function is completed, the user space device handler shall
676 reply using "result" field of the corresponding reply command. It isn't
677 necessary to wait for aborted command(s) finished, the result of TM
678 function shall be returned immediately. SCST core will take care that
679 the reply to the TM function isn't sent before all affection SCSI
680 commands finished.
681
682 Possible values of "fn" field:
683
684  - SCST_ABORT_TASK - cmd_h_to_abort shall be aborted
685
686  - SCST_ABORT_TASK_SET - task set on the device shall be aborted
687
688  - SCST_CLEAR_ACA - ACA status shall be cleared
689
690  - SCST_CLEAR_TASK_SET  - task set on the device shall be cleared
691
692  - SCST_LUN_RESET, SCST_TARGET_RESET - reset of the device shall be done
693
694  - SCST_NEXUS_LOSS_SESS - notifies about nexus loss event for the session
695
696  - SCST_ABORT_ALL_TASKS_SESS - all tasks in the session shall be aborted
697  
698  - SCST_NEXUS_LOSS - notifies about global nexus loss event
699  
700  - SCST_ABORT_ALL_TASKS - all tasks shall be aborted
701
702 Possible return values are:
703
704  - SCST_MGMT_STATUS_SUCCESS - success
705
706  - SCST_MGMT_STATUS_TASK_NOT_EXIST - task does not exist
707
708  - SCST_MGMT_STATUS_LUN_NOT_EXIST - LUN does not exist
709
710  - SCST_MGMT_STATUS_FN_NOT_SUPPORTED - task management function not
711    supported
712
713  - SCST_MGMT_STATUS_REJECTED - task management function was rejected
714
715  - SCST_MGMT_STATUS_FAILED - task management function failed
716
717
718                 5. SCST_USER_REPLY_AND_GET_PRIO_CMD
719
720 SCST_USER_REPLY_AND_GET_PRIO_CMD is the same as
721 SCST_USER_REPLY_AND_GET_CMD, except that it returns management (i.e.
722 priority) subcommands from priority queue, if usage of a separate PRIO
723 was configured. 
724
725 Management subcommands are: SCST_USER_ATTACH_SESS, SCST_USER_DETACH_SESS
726 and SCST_USER_TASK_MGMT.
727
728 PRIO queue is always blocking, because poll() doesn't support, when
729 different threads wait with different events mask. Only one thread is
730 woken up on each event and if it isn't interested in such events,
731 another (interested) one will not be woken up.
732
733
734                 6. SCST_USER_REPLY_CMD
735
736 SCST_USER_REPLY_CMD IOCTL function allows the user space handler to
737 return the result of a command's execution. Its argument is defined as:
738
739 struct scst_user_reply_cmd
740 {
741         uint32_t cmd_h;
742         uint32_t subcode;
743         union {
744                 int32_t result;
745                 struct scst_user_scsi_cmd_reply_parse parse_reply;
746                 struct scst_user_scsi_cmd_reply_alloc_mem alloc_reply;
747                 struct scst_user_scsi_cmd_reply_exec exec_reply;
748         };
749 },
750
751 where:
752
753  - cmd_h - command handle used to identify the command in the reply.
754
755  - subcode - subcommand code, see 4.1
756
757 Union contains the subcommand's specific payload:
758
759  - result - subcommand's result code
760
761
762 struct scst_user_scsi_cmd_reply_parse
763 {
764         uint8_t queue_type;
765         uint8_t data_direction;
766         int32_t data_len;
767         int32_t bufflen;
768 },
769
770 where:
771
772  - queue_type - SCSI task attribute (queue type )
773  
774  - data_direction - command's data flow direction, one of SCST_DATA_* constants
775
776  - data_len - command's data length
777  
778  - bufflen - command's buffer length
779
780
781 struct scst_user_scsi_cmd_reply_alloc_mem
782 {
783         uint64_t pbuf;
784 },
785
786 where:
787
788  - pbuf - pointer to command's data buffer
789
790
791 struct scst_user_scsi_cmd_reply_exec
792 {
793         int32_t resp_data_len;
794         uint64_t pbuf;
795
796         uint8_t reply_type;
797
798         uint8_t status;
799         uint8_t sense_len;
800         aligned_u64 psense_buffer;
801 },
802
803 where:
804
805  - resp_data_len - length of the response data
806
807  - pbuf - pointer to command's data buffer. Used only when in the
808    original SCST_USER_EXEC subcommand pbuf field is 0
809
810  - reply_type - could be one of the following constants:
811  
812      * SCST_EXEC_REPLY_BACKGROUND - tells SCST send to the remote
813        initiator GOOD status, but the command not yet completed by the
814        user space handler, it is being executed in the background. When
815        it will be completed, the user space handler will call
816        SCST_USER_REPLY_CMD again with reply_type
817        SCST_EXEC_REPLY_COMPLETED.
818      
819      * SCST_EXEC_REPLY_COMPLETED - the user space handler completed the command
820
821  - status - SAM status of the commands execution
822
823  - sense_len - length of sense data in psense_buffer, if any
824
825  - psense_buffer - pointed to sense buffer
826
827
828                 IV. Commands processing flow example.
829
830 As the example consider a simple synchronous VTL, which serves one
831 virtual SCSI tape device and can process only one command at time from
832 any initiator. 
833
834 At the beginning the VTL opens using open() call /dev/scst_user in the
835 default blocking mode.
836
837 Then it using SCST_USER_REGISTER_DEVICE ioctl() function registers the
838 tape device. Since only one command at time is supported, the allocated
839 command's data memory could be reused for both READ-type (i.e. which
840 involve data transfer from target to initiator) and WRITE-type (i.e.
841 which involve data transfer from initiator to target) commands. So the
842 device is configured with parse_type SCST_USER_PARSE_STANDARD,
843 on_free_cmd_type SCST_USER_ON_FREE_CMD_IGNORE, memory_reuse_type
844 SCST_USER_MEM_REUSE_ALL, prio_queue_type SCST_USER_PRIO_QUEUE_SINGLE and
845 partial_transfers_type SCST_USER_PARTIAL_TRANSFERS_NOT_SUPPORTED.
846
847 Then it prepares struct scst_user_get_cmd with reply set to 0, calls
848 SCST_USER_REPLY_AND_GET_CMD ioctl() and waits until some initiator
849 connects to its tape device. On that event the VTL receives
850 SCST_USER_ATTACH_SESS subcommand. Since the VTL doesn't use any
851 initiator specific data, it can do nothing on that subcommand, so it
852 prepares scst_user_reply_cmd structure, where:
853
854  - cmd_h set to returned by SCST_USER_REPLY_AND_GET_CMD ioctl() cmd_h
855
856  - subcode set to SCST_USER_ATTACH_SESS
857  
858  - result set to 0
859  
860 Then it prepares struct scst_user_get_cmd with reply set to the prepared
861 scst_user_reply_cmd structure, calls SCST_USER_REPLY_AND_GET_CMD ioctl()
862 and waits for some SCSI command arrives from the initiator.
863
864 If the received SCSI command is READ-type one, SCST does the necessary
865 preparations, then the VTL receives SCST_USER_EXEC subcommand, where
866 bufflen and data_len are set correctly, but memory for buffer isn't
867 allocated, so pbuf field is 0. The VTL then allocates the data buffer
868 with size alloc_len, e.g. using malloc(). Then the VTL reads the data
869 from disk in it, e.g. using O_DIRECT read() function, then prepares
870 scst_user_reply_cmd structure, where:
871
872  - cmd_h set to returned by SCST_USER_REPLY_AND_GET_CMD ioctl() cmd_h
873
874  - subcode set to SCST_USER_EXEC
875
876  - exec_reply.resp_data_len set to length of the read data
877
878  - exec_reply.pbuf set to the data buffer, where the data were read
879  
880  - exec_reply.reply_type set to SCST_EXEC_REPLY_COMPLETED
881  
882  - exec_reply.status set to the SAM defined status of the
883    operation
884  
885  - exec_reply.sense_len set and exec_reply.psense_buffer filled with
886    sense data, if necessary
887
888 Then it prepares struct scst_user_get_cmd with reply set to the prepared
889 scst_user_reply_cmd structure, calls SCST_USER_REPLY_AND_GET_CMD ioctl()
890 and waits for the next SCSI command arrives from the initiator. That's
891 all for this SCSI command. For the next one the used data buffer will be
892 reused.
893
894 For WRITE-type SCSI commands the processing is the same, but
895 SCST_USER_ALLOC_MEM will be returned before SCST_USER_EXEC, since the
896 data transfer from the initiator precedes the commands execution.
897
898 In case, if the first command requires 4K data buffer, but the second
899 one - 1M, for it the VTL also will be asked to allocate the buffer.
900 Then, if no more 4K commands come for some time, for it
901 SCST_USER_ON_CACHED_MEM_FREE subcommand will be returned to the VTL in
902 order to ask it to free that buffer.