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