e85846474fe779432e5555e8aa30ae37c65a129f
[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.2
6
7
8                 I. Description.
9
10 SCST user space device handler module scst_user is a device handler for
11 SCST, which provides a way to implement in the user space complete, full
12 feature virtual SCSI devices in the SCST environment.
13
14 This document assumes that the reader is familiar with the SCST
15 architecture and the states through which SCSI commands go during
16 processing in SCST. Module scst_user basically only provides hooks to
17 them. Their description could be found on the SCST web page on
18 http://scst.st.net.
19
20
21                 II. User space API.
22
23 Module scst_user provides /dev/scst_user character device with the
24 following system calls available: 
25
26  - open() - allows to open the device and get a file handle, which
27    will be used in all subsequent actions until close() is called
28
29  - close() - closes file handle returned by open()
30  
31  - poll() - allows to wait until some pending command from SCST to
32    process is available.
33
34  - ioctl() - main call, which allows commands interchange with the SCST
35    core.
36
37 Device /dev/scst_user could be opened in blocking or non-blocking mode
38 using O_NONBLOCK flag. In the blocking mode ioctl()
39 SCST_USER_REPLY_GET_CMD function blocks until there is a new subcommand
40 to process. In the non-blocking mode if there are no pending subcommands
41 SCST_USER_REPLY_GET_CMD function returns immediately with EAGAIN error
42 code, and the user space device handler can use poll() call to get
43 notification about new subcommands arrival. The blocking mode is the
44 default.
45
46 The module scst_user API is defined in scst_user.h file.
47
48
49                 III. IOCTL() functions.
50
51 There are following IOCTL functions available. All of them has one
52 argument. They all, except SCST_USER_REGISTER_DEVICE return 0 for
53 success or -1 in case of error, and errno is set appropriately.
54
55
56                 1. SCST_USER_REGISTER_DEVICE
57
58 SCST_USER_REGISTER_DEVICE - registers new virtual user space device. The
59 argument is:
60
61 struct scst_user_dev_desc
62 {
63         uint8_t version;
64         uint8_t type;
65         uint8_t has_own_order_mgmt;
66         struct scst_user_opt opt;
67         uint32_t block_size;
68         char name[SCST_MAX_NAME];
69 },
70
71 where:
72
73  - version - is a protocol version, shall be DEV_USER_VERSION
74
75  - type - SCSI type of the device
76
77  - has_own_order_mgmt - set it in non-zero, if device implements own
78    ORDERED commands management, i.e. guarantees commands execution order
79    requirements, specified by SAM.
80
81  - opt - device options, see SCST_USER_SET_OPTIONS/SCST_USER_GET_OPTIONS below
82
83  - block_size - block size, shall be divisible by 512 for block devices
84
85  - name - name of the device
86
87 SCST_USER_REGISTER_DEVICE returns registered device's handler or -1
88 in case of error, and errno is set appropriately.
89
90 In order to unregister the device, 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         int32_t in_bufflen;
345
346         uint8_t queue_type;
347         uint8_t data_direction;
348
349         uint8_t expected_values_set;
350         uint8_t expected_data_direction;
351         int32_t expected_transfer_len;
352
353         uint32_t sn;
354 },
355
356 where:
357
358  - sess_h - corresponding session handler
359
360  - cdb - SCSI CDB
361
362  - cdb_len - SCSI CDB length
363  
364  - ext_cdb_len - size of extended CDB, see SCST_USER_GET_EXTENDED_CDB
365    for more details
366  
367  - timeout - CDB execution timeout
368
369  - bufflen - command's buffer length
370  
371  - in_bufflen - for bidirectional commands command's IN, i.e. from
372    initiator to target, buffer length
373  
374  - queue_type - SCSI task attribute (queue type)
375  
376  - data_direction - command's data flow direction, one of SCST_DATA_*
377    constants
378
379  - expected_values_set - true if expected_data_direction and
380    expected_transfer_len contain valid values
381    
382  - expected_data_direction - remote initiator supplied command's data
383    flow direction
384
385  - expected_transfer_len - remote initiator supplied transfer length
386
387  - sn - command's SN, which might be used for task management
388
389 In the PARSE state of SCSI commands processing the user space device
390 handler shall check and provide SCST values for command data buffer
391 length, data flow direction and timeout, which it shall reply using the
392 corresponding reply command.
393
394 In case of any error the error reporting should be deferred until
395 SCST_USER_EXEC subcommand, where the appropriate SAM status and sense
396 shall be set.
397    
398
399                 4.4.4. SCST_USER_ALLOC_MEM
400
401 SCST_USER_ALLOC_MEM returns SCSI command on memory allocation state of
402 the SCST processing. On this state the user space device handler shall
403 allocate the command's data buffer with bufflen length and then return
404 it to SCST using the corresponding reply command. Then SCST internally
405 will convert it in SG vector in order to use it itself and by target
406 drivers.
407
408 If the memory reuse type is disabled (i.e. set to SCST_USER_MEM_NO_REUSE)
409 there are no special requirements for buffer memory or its alignment, it
410 could be just what malloc() returned. If the memory reuse type is enabled,
411 the buffer shall be page size aligned, for example using memalign()
412 function.
413
414 Payload contains struct scst_user_scsi_cmd_alloc_mem, which is defined
415 as the following:
416
417 struct scst_user_scsi_cmd_alloc_mem
418 {
419         uint64_t sess_h;
420
421         uint8_t cdb[SCST_MAX_CDB_SIZE];
422         uint16_t cdb_len;
423         uint16_t ext_cdb_len;
424
425         int32_t alloc_len;
426
427         uint8_t queue_type;
428         uint8_t data_direction;
429
430         uint32_t sn;
431 },
432
433 where:
434
435  - sess_h - corresponding session handler
436
437  - cdb - SCSI CDB
438
439  - cdb_len - SCSI CDB length
440
441  - ext_cdb_len - size of extended CDB, see SCST_USER_GET_EXTENDED_CDB
442    for more details
443
444  - alloc_len - command's buffer length
445  
446  - queue_type - SCSI task attribute (queue type )
447
448  - data_direction - command's data flow direction, one of SCST_DATA_*
449    constants
450
451  - sn - command's SN, which might be used for task management
452
453 Memory allocation, preparation and freeing are ones of the most
454 complicated and expensive operations during SCSI commands processing.
455 Module scst_user provides a way to almost completely eliminate those
456 operations by reusing once allocated memory for subsequent SCSI
457 commands. It is controlled by memory_reuse_type option, which could be
458 set by SCST_USER_SET_OPTIONS function. If any type memory reusage is
459 enabled, then SCST will use its internal SGV cache in order to cache
460 allocated and fully built SG vectors for subsequent commands of this
461 type, so for them SCST_USER_ALLOC_MEM subfunction will not be called and
462 in SCST_USER_EXEC pbuf pointer will point to that reused buffer. 
463
464 SGV cache is a backend cache made on top of Linux kernel SLAB cache. It
465 caches SG vectors with power of 2 data sizes: 4K, 8K, ..., 4M. So, if
466 there is a 5K SCSI command coming, then the user space handler will be
467 asked for 8K allocation, from which only 5K will be used for this
468 particular SCSI command. Then that SG vector will be cached and
469 subsequently reused for all SCSI commands between 4K and 8K. For a 1M
470 SCSI command the user space handler will be asked for another buffer
471 (while the previous 5K one will be kept), which will not be then reused
472 for 5K SCSI commands, since 1M and 5K vectors belong to different cache
473 data sizes, it will be reused only for commands between 512K and 1M.
474 Then, after some time of inactivity or when the system is under memory
475 pressure, the cache entries will be freed and the user space handler
476 will be notified using SCST_USER_ON_CACHED_MEM_FREE.
477
478 Since SGV cache caches SG vectors with power of 2 data sizes, alloc_len
479 field could be up to 2 times more, than actually required by the SCSI
480 command.
481
482 The memory reuse could be used in both SCSI tagged and untagged queuing
483 environments. In the SCSI tagged queuing environment the SGV cache will
484 take care that several commands don't use the same buffer simultaneously
485 by asking the user space handler to allocate a new data buffer, when all
486 cached ones are busy.
487
488 Some important notes:
489
490 1. If the user space handler needs to call fork(), it must call
491 madvise() with MADV_DONTFORK flag for all allocated data buffers,
492 otherwise parent or child process could loose the connection with them,
493 which could lead to data corruption. See http://lwn.net/Articles/171941/
494 for details.
495
496 2. The interface assumes that all allocated memory by the user space
497 handler is DMA'able by the target hardware. This is almost always true
498 for most modern systems, except if the target hardware isn't capable of
499 using 64-bit address space and the system has >4GB of memory or the
500 memory addresses are in address space, which is unavailable with 32-bit
501 addresses.
502
503 In case of any error the error reporting should be deferred until
504 SCST_USER_EXEC subcommand, where the appropriate SAM status and sense
505 should be set.
506
507
508                 4.4.5. SCST_USER_EXEC
509
510 SCST_USER_EXEC returns SCSI command on execution state of the SCST
511 processing. The user space handler should execute the SCSI command and
512 reply using the corresponding reply command.
513
514 In some cases for performance reasons for READ-type SCSI commands
515 SCST_USER_ALLOC_MEM subcommand isn't returned before SCST_USER_EXEC.
516 Thus, if pbuf pointer is 0 and the SCSI command needs data transfer,
517 the user space handler should be prepared to allocate the data buffer
518 with size alloc_len, which could be up to 2 times more, than actually
519 required by the SCSI command. But field bufflen will contain the correct
520 value. All the memory reusage rules, described for SCST_USER_ALLOC_MEM,
521 apply to SCST_USER_EXEC as well.
522
523 Payload contains struct scst_user_scsi_cmd_exec, which is defined as the
524 following:
525
526 struct scst_user_scsi_cmd_exec
527 {
528         uint64_t sess_h;
529
530         uint8_t cdb[SCST_MAX_CDB_SIZE];
531         uint16_t cdb_len;
532         uint16_t ext_cdb_len;
533
534         int32_t data_len;
535         int32_t bufflen;
536         int32_t alloc_len;
537         uint64_t pbuf;
538         uint8_t queue_type;
539         uint8_t data_direction;
540         uint8_t partial;
541         uint32_t timeout;
542
543         aligned_u64 p_in_buf;
544         int32_t in_bufflen;
545
546         uint32_t sn;
547
548         uint32_t parent_cmd_h;
549         int32_t parent_cmd_data_len;
550         uint32_t partial_offset;
551 },
552
553 where:
554
555  - sess_h - corresponding session handler
556
557  - cdb - SCSI CDB
558
559  - cdb_len - SCSI CDB length
560
561  - ext_cdb_len - size of extended CDB, see SCST_USER_GET_EXTENDED_CDB
562    for more details
563
564  - data_len - command's data length. Could be different from bufflen for
565    commands like VERIFY, which transfer different amount of data, than
566    process, or even none of them
567  
568  - bufflen - command's buffer length
569
570  - alloc_len - command's buffer length, which should be allocated, if pbuf
571    is 0 and the command requires data transfer
572
573  - pbuf - pointer to command's data buffer or 0 for SCSI commands
574    without data transfer.
575
576  - queue_type - SCSI task attribute (queue type)
577
578  - data_direction - command's data flow direction, one of SCST_DATA_*
579    constants
580
581  - partial - specifies, if the command is a partial subcommand, could
582    have the following OR'ed flags:
583
584    * SCST_USER_SUBCOMMAND - set if the command is a partial subcommand
585    
586    * SCST_USER_SUBCOMMAND_FINAL - set if the subcommand is a final one
587
588  - timeout - CDB execution timeout
589
590  - p_in_buf - for bidirectional commands pointer on command's IN, i.e. from
591    initiator to target, data buffer or 0 for SCSI commands without data
592    transfer
593
594  - in_bufflen - for bidirectional commands command's IN, i.e. from
595    initiator to target, buffer length
596
597  - sn - command's SN, which might be used for task management
598
599  - parent_cmd_h - has the same unique value for all partial data
600    transfers subcommands of one original (parent) command
601
602  - parent_cmd_data_len - for partial data transfers subcommand has the
603    size of the overall data transfer of the original (parent) command
604
605  - partial_offset - has offset of the subcommand in the original
606    (parent) command
607
608 It is guaranteed that only commands of the same queue_type per session
609 can be returned simultaneously.
610
611 In case of any error it should be reported via appropriate SAM status
612 and sense. If it happens for a subcommand of a partial data transfers
613 command, all other subcommands of this command, which already passed the
614 the user space handler or will be passed in the future, will be aborted
615 by scst_user, the user space handler should ignore them.
616
617
618                 4.4.6. SCST_USER_ON_FREE_CMD
619
620 SCST_USER_ON_FREE_CMD returns SCSI command when the command is about to
621 be freed. At this stage, the user space device handler could do any
622 necessary cleanups, for instance, free allocated for data buffer memory.
623
624 NOTE! If the memory reusage is enabled, then the data buffer must not be
625 freed, it will be reused by subsequent SCSI commands. The buffer must be
626 freed only on SCST_USER_ON_CACHED_MEM_FREE event.
627
628 Payload contains struct scst_user_scsi_on_free_cmd, which is defined
629 as the following:
630
631 struct scst_user_scsi_on_free_cmd
632 {
633         uint64_t pbuf;
634         int32_t resp_data_len;
635         uint8_t buffer_cached;
636         uint8_t aborted;
637         uint8_t status;
638         uint8_t delivery_status;
639 },
640
641 where:
642
643  - pbuf - pointer to command's data buffer or 0 for SCSI commands
644    without data transfer.
645
646  - resp_data_len - length of the response data
647
648  - buffer_cached - true, if memory reusage is enabled for this command
649
650  - aborted - true, if command was aborted
651
652  - status - SAM status of the commands execution
653
654  - delivery_status - status of cmd's status/data delivery to remote
655    initiator. Can be:
656    
657    * SCST_CMD_DELIVERY_SUCCESS - delivery succeeded
658
659    * SCST_CMD_DELIVERY_FAILED - delivery failed
660
661 The user space handler should reply using the corresponding reply
662 command. No error code is needed.
663
664
665                 4.4.7. SCST_USER_ON_CACHED_MEM_FREE
666
667 SCST_USER_ON_CACHED_MEM_FREE subcommand is returned, when SGV cache
668 decided that this buffer isn't needed anymore. This happens after some
669 time of inactivity or when the system is under memory pressure.
670
671 Payload contains struct scst_user_on_cached_mem_free, which is defined
672 as the following:
673
674 struct scst_user_scsi_cmd_alloc_mem
675 {
676         uint64_t pbuf;
677 },
678
679 where:
680
681  - pbuf - pointer to buffer, which should be freed
682
683
684                 4.4.8. SCST_USER_TASK_MGMT
685  
686 SCST_USER_TASK_MGMT subcommand returns a task management functions.
687 Payload contains struct scst_user_tm, which is defined as the following:
688
689 struct scst_user_tm
690 {
691         uint64_t sess_h;
692         uint32_t fn;
693         uint32_t cmd_h_to_abort;
694         uint32_t cmd_sn;
695         uint8_t cmd_sn_set;
696 },
697
698 where:
699
700  - sess_h - corresponding session handler
701
702  - fn - task management function, see below
703
704  - cmd_h_to_abort - handle of command to abort. Valid only if fn is
705    SCST_ABORT_TASK
706
707  - cmd_sn - if cmd_sn_set is set, contains maximum commands SN, which
708    this task management function affects. See iSCSI RFC 3720 10.5.1 for
709    more details.
710
711  - cmd_sn_set - specifies if cmd_sn is valid
712    
713 After TM function is completed, the user space device handler shall
714 reply using "result" field of the corresponding reply command. It isn't
715 necessary to wait for aborted command(s) finished, the result of TM
716 function shall be returned immediately. SCST core will take care that
717 the reply to the TM function isn't sent before all affection SCSI
718 commands finished.
719
720 Possible values of "fn" field:
721
722  - SCST_ABORT_TASK - cmd_h_to_abort shall be aborted
723
724  - SCST_ABORT_TASK_SET - task set on the device shall be aborted
725
726  - SCST_CLEAR_ACA - ACA status shall be cleared
727
728  - SCST_CLEAR_TASK_SET  - task set on the device shall be cleared
729
730  - SCST_LUN_RESET, SCST_TARGET_RESET - reset of the device shall be done
731
732  - SCST_NEXUS_LOSS_SESS - notifies about nexus loss event for the session
733
734  - SCST_ABORT_ALL_TASKS_SESS - all tasks in the session shall be aborted
735  
736  - SCST_NEXUS_LOSS - notifies about global nexus loss event
737  
738  - SCST_ABORT_ALL_TASKS - all tasks shall be aborted
739
740 Possible return values are:
741
742  - SCST_MGMT_STATUS_SUCCESS - success
743
744  - SCST_MGMT_STATUS_TASK_NOT_EXIST - task does not exist
745
746  - SCST_MGMT_STATUS_LUN_NOT_EXIST - LUN does not exist
747
748  - SCST_MGMT_STATUS_FN_NOT_SUPPORTED - task management function not
749    supported
750
751  - SCST_MGMT_STATUS_REJECTED - task management function was rejected
752
753  - SCST_MGMT_STATUS_FAILED - task management function failed
754
755
756                 5. SCST_USER_REPLY_CMD
757
758 SCST_USER_REPLY_CMD IOCTL function allows the user space handler to
759 return the result of a command's execution. Its argument is defined as:
760
761 struct scst_user_reply_cmd
762 {
763         uint32_t cmd_h;
764         uint32_t subcode;
765         union {
766                 int32_t result;
767                 struct scst_user_scsi_cmd_reply_parse parse_reply;
768                 struct scst_user_scsi_cmd_reply_alloc_mem alloc_reply;
769                 struct scst_user_scsi_cmd_reply_exec exec_reply;
770         };
771 },
772
773 where:
774
775  - cmd_h - command handle used to identify the command in the reply.
776
777  - subcode - subcommand code, see 4.1
778
779 Union contains the subcommand's specific payload:
780
781  - result - subcommand's result code
782
783
784 struct scst_user_scsi_cmd_reply_parse
785 {
786         uint8_t queue_type;
787         uint8_t data_direction;
788         uint8_t write_medium;
789         int32_t data_len;
790         int32_t bufflen;
791 },
792
793 where:
794
795  - queue_type - SCSI task attribute (queue type )
796  
797  - data_direction - command's data flow direction, one of SCST_DATA_* constants
798
799  - write_medium - true, if command writes data to medium, so should be
800    forbidden for read-only devices, false otherwise
801
802  - data_len - command's data length
803  
804  - bufflen - command's buffer length
805
806
807 struct scst_user_scsi_cmd_reply_alloc_mem
808 {
809         uint64_t pbuf;
810 },
811
812 where:
813
814  - pbuf - pointer to command's data buffer
815
816
817 struct scst_user_scsi_cmd_reply_exec
818 {
819         int32_t resp_data_len;
820         uint64_t pbuf;
821
822         uint8_t reply_type;
823
824         uint8_t status;
825         uint8_t sense_len;
826         aligned_u64 psense_buffer;
827 },
828
829 where:
830
831  - resp_data_len - length of the response data
832
833  - pbuf - pointer to command's data buffer. Used only when in the
834    original SCST_USER_EXEC subcommand pbuf field is 0
835
836  - reply_type - could be one of the following constants:
837  
838      * SCST_EXEC_REPLY_BACKGROUND - tells SCST send to the remote
839        initiator GOOD status, but the command not yet completed by the
840        user space handler, it is being executed in the background. When
841        it will be completed, the user space handler will call
842        SCST_USER_REPLY_CMD again with reply_type
843        SCST_EXEC_REPLY_COMPLETED.
844      
845      * SCST_EXEC_REPLY_COMPLETED - the user space handler completed the command
846
847  - status - SAM status of the commands execution
848
849  - sense_len - length of sense data in psense_buffer, if any
850
851  - psense_buffer - pointed to sense buffer
852
853
854                 6. SCST_USER_FLUSH_CACHE
855
856 SCST_USER_FLUSH_CACHE - flushes SGV cache for the corresponding virtual
857 user space device and queues for all cached memory buffers corresponding
858 SCST_USER_ON_CACHED_MEM_FREE subcommands.
859
860 During execution of SCST_USER_FLUSH_CACHE at least one another thread
861 must process all coming subcommands, otherwise after timeout it will
862 fail with EBUSY error.
863
864 SCST_USER_FLUSH_CACHE doesn't have any parameters.
865
866 SCST_USER_FLUSH_CACHE returns 0 on success or -1 in case of error,
867 and errno is set appropriately.
868
869
870                 7. SCST_USER_DEVICE_CAPACITY_CHANGED
871
872 SCST_USER_DEVICE_CAPACITY_CHANGED - queues CAPACITY DATA HAS CHANGED
873 Unit Attention or corresponding Asynchronous Event to the corresponding
874 virtual device. It will notify remote initiators, connected to the
875 device, and allow them to automatically refresh new device size. You
876 should use SCST_USER_DEVICE_CAPACITY_CHANGED after resize of the device.
877
878 SCST_USER_DEVICE_CAPACITY_CHANGED doesn't have any parameters.
879
880 SCST_USER_DEVICE_CAPACITY_CHANGED returns 0 on success or -1 in case of
881 error, and errno is set appropriately.
882
883
884                 8. SCST_USER_GET_EXTENDED_CDB
885
886 SCST_USER_GET_EXTENDED_CDB - requests extended CDB, if CDB size is more
887 than SCST_MAX_CDB_SIZE bytes. In this case SCST_USER_GET_EXTENDED_CDB
888 returns additional CDB data beyond SCST_MAX_CDB_SIZE bytes.
889
890 SCST_USER_GET_EXTENDED_CDB has the following arguments:
891
892 struct scst_user_get_ext_cdb {
893         uint32_t cmd_h;
894         aligned_u64 ext_cdb_buffer;
895 },
896
897 where:
898
899  - cmd_h - command handle used to identify the command in the reply.
900
901  - ext_cdb_buffer - pointer to buffer, where extended CDB will be copied.
902
903 SCST_USER_GET_EXTENDED_CDB returns 0 on success or -1 in case of error,
904 and errno is set appropriately.
905
906
907                 IV. Commands processing flow example.
908
909 As the example consider a simple synchronous VTL, which serves one
910 virtual SCSI tape device and can process only one command at time from
911 any initiator. 
912
913 At the beginning the VTL opens using open() call /dev/scst_user in the
914 default blocking mode.
915
916 Then it using SCST_USER_REGISTER_DEVICE ioctl() function registers the
917 tape device. Since only one command at time is supported, the allocated
918 command's data memory could be reused for both READ-type (i.e. which
919 involve data transfer from target to initiator) and WRITE-type (i.e.
920 which involve data transfer from initiator to target) commands. So the
921 device is configured with parse_type SCST_USER_PARSE_STANDARD,
922 on_free_cmd_type SCST_USER_ON_FREE_CMD_IGNORE, memory_reuse_type
923 SCST_USER_MEM_REUSE_ALL and partial_transfers_type
924 SCST_USER_PARTIAL_TRANSFERS_NOT_SUPPORTED.
925
926 Then it prepares struct scst_user_get_cmd with reply set to 0, calls
927 SCST_USER_REPLY_AND_GET_CMD ioctl() and waits until some initiator
928 connects to its tape device. On that event the VTL receives
929 SCST_USER_ATTACH_SESS subcommand. Since the VTL doesn't use any
930 initiator specific data, it can do nothing on that subcommand, so it
931 prepares 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_ATTACH_SESS
936  
937  - result set to 0
938  
939 Then it prepares struct scst_user_get_cmd with reply set to the prepared
940 scst_user_reply_cmd structure, calls SCST_USER_REPLY_AND_GET_CMD ioctl()
941 and waits for some SCSI command arrives from the initiator.
942
943 If the received SCSI command is READ-type one, SCST does the necessary
944 preparations, then the VTL receives SCST_USER_EXEC subcommand, where
945 bufflen and data_len are set correctly, but memory for buffer isn't
946 allocated, so pbuf field is 0. The VTL then allocates the data buffer
947 with size alloc_len, e.g. using malloc(). Then the VTL reads the data
948 from disk in it, e.g. using O_DIRECT read() function, then prepares
949 scst_user_reply_cmd structure, where:
950
951  - cmd_h set to returned by SCST_USER_REPLY_AND_GET_CMD ioctl() cmd_h
952
953  - subcode set to SCST_USER_EXEC
954
955  - exec_reply.resp_data_len set to length of the read data
956
957  - exec_reply.pbuf set to the data buffer, where the data were read
958  
959  - exec_reply.reply_type set to SCST_EXEC_REPLY_COMPLETED
960  
961  - exec_reply.status set to the SAM defined status of the
962    operation
963  
964  - exec_reply.sense_len set and exec_reply.psense_buffer filled with
965    sense data, if necessary
966
967 Then it prepares struct scst_user_get_cmd with reply set to the prepared
968 scst_user_reply_cmd structure, calls SCST_USER_REPLY_AND_GET_CMD ioctl()
969 and waits for the next SCSI command arrives from the initiator. That's
970 all for this SCSI command. For the next one the used data buffer will be
971 reused.
972
973 For WRITE-type SCSI commands the processing is the same, but
974 SCST_USER_ALLOC_MEM will be returned before SCST_USER_EXEC, since the
975 data transfer from the initiator precedes the commands execution.
976
977 In case, if the first command requires 4K data buffer, but the second
978 one - 1M, for it the VTL also will be asked to allocate the buffer.
979 Then, if no more 4K commands come for some time, for it
980 SCST_USER_ON_CACHED_MEM_FREE subcommand will be returned to the VTL in
981 order to ask it to free that buffer.
982
983 Vladislav Bolkhovitin