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