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