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