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