2b57e2812627fb7a94a336b46ca79583554c5f5c
[mirror/scst/.git] / doc / scst_user_spec.txt
1         SCST USER SPACE DEVICE HANDLER MODULE.
2
3           USER SPACE INTERFACE DESCRIPTION.
4
5                    Version 0.9.6/1
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         struct scst_user_opt opt;
66         uint32_t block_size;
67         char name[SCST_MAX_NAME];
68 },
69
70 where:
71
72  - version - is a protocol version, shall be DEV_USER_VERSION
73
74  - type - SCSI type of the device
75
76  - opt - device options, see SCST_USER_SET_OPTIONS/SCST_USER_GET_OPTIONS below
77
78  - block_size - block size, shall be divisible by 512 for block devices
79
80  - name - name of the device
81
82 SCST_USER_REGISTER_DEVICE returns registered device's handler or -1
83 in case of error, and errno is set appropriately.
84
85 In order to unregister the device just call close() on its file descriptor.
86
87
88                 3. SCST_USER_SET_OPTIONS/SCST_USER_GET_OPTIONS
89
90 SCST_USER_SET_OPTIONS/SCST_USER_GET_OPTIONS allows to set or get
91 correspondingly various options that control various aspects of SCSI
92 commands processing.
93
94 The argument is:
95
96 struct scst_user_opt
97 {
98         uint8_t parse_type;
99         uint8_t on_free_cmd_type;
100         uint8_t memory_reuse_type;
101         uint8_t prio_queue_type;
102         uint8_t partial_transfers_type;
103         uint32_t partial_len;
104 },
105
106 where:
107
108  - parse_type - defines how the user space handler wants to process
109    PARSE subcommand. Possible values are:
110   
111    * SCST_USER_PARSE_STANDARD - tells SCST use standard internal parser
112      for this SCSI device type.
113    
114    * SCST_USER_PARSE_CALL - tells SCST generate SCST_USER_PARSE for all
115      SCSI commands
116
117    * SCST_USER_PARSE_EXCEPTION - tells SCST generate SCST_USER_PARSE
118      for unknown SCSI commands or SCSI commands that produce errors in
119      the standard parser.
120
121  - on_free_cmd_type - defines how the user space handler wants to
122    process ON_FREE_CMD subcommand. Possible values are:
123
124    * SCST_USER_ON_FREE_CMD_CALL - tells SCST generate
125      SCST_USER_ON_FREE_CMD for all SCSI commands
126
127    * SCST_USER_ON_FREE_CMD_IGNORE - tells SCST do nothing on this event.
128
129  - memory_reuse_type - defines how memory allocated by the user space
130    handler for a SCSI commands data buffers is then reused by the SCST
131    core as data buffer for subsequent commands. Possible values are:
132    
133    * SCST_USER_MEM_NO_REUSE - no memory reuse is possible, for each
134      commands the user space handler will each time allocate a dedicated
135      data buffer
136
137    * SCST_USER_MEM_REUSE_READ - memory reuse by only READ-type commands
138      (i.e. which involve data transfer from target to initiator) is
139      allowed. For all WRITE-type commands (i.e. which involves data
140      transfer from initiator to target) the user space handler will
141      each time allocate a dedicated data buffer
142
143    * SCST_USER_MEM_REUSE_WRITE - memory reuse by only WRITE-type
144      commands is allowed. For all WRITE-type commands the user space
145      handler will each time allocate a dedicated data buffer
146
147    * SCST_USER_MEM_REUSE_ALL - unlimited memory reuse is possible.
148
149  - prio_queue_type - defines if the user space handler need to receive
150    all management subcommands from a separate PRIO queue using
151    SCST_USER_REPLY_AND_GET_PRIO_CMD command. Management subcommands are:
152    SCST_USER_ATTACH_SESS, SCST_USER_DETACH_SESS and SCST_USER_TASK_MGMT.
153    Possible values are:
154
155    * SCST_USER_PRIO_QUEUE_SINGLE - a single queue is used for regular
156      and management subcommands
157
158    * SCST_USER_PRIO_QUEUE_SEPARATE - a separate PRIO queue is used for
159      management subcommands
160
161  - partial_transfers_type - defines if the user space handler supports
162    partial data transfers, when a SCSI command, which required big data
163    transfer, is broken on several subcommands with smaller data
164    transfers. This allows to improve performance by simultaneous data
165    transfers from/to remote initiator and to/from the underlying storage
166    device as well as lower allocation memory requirements for each
167    (sub)command. All subcommands will have the same unique value in
168    "parent_cmd_h" field and SCST_USER_SUBCOMMAND flag in "partial" field
169    of struct scst_user_scsi_cmd_exec. The final subcommand will also
170    have in that field SCST_USER_SUBCOMMAND_FINAL flag. All the
171    subcommands will have the original unmodified CDB. Possible values
172    are:
173    
174    * SCST_USER_PARTIAL_TRANSFERS_NOT_SUPPORTED - the partial data
175      transfers are not supported
176
177    * SCST_USER_PARTIAL_TRANSFERS_SUPPORTED_ORDERED - the partial data
178      transfers are supported, but all the subcommands must come in order
179      of data chunks. Could be used, e.g., for tape devices.
180
181    * SCST_USER_PARTIAL_TRANSFERS_SUPPORTED - the partial data transfers
182      are supported without limitations.
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'e 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
327 where:
328
329  - sess_h - corresponding session handler
330
331  - cdb - SCSI CDB
332
333  - cdb_len - SCSI CDB length
334  
335  - timeout - CDB execution timeout
336
337  - bufflen - command's buffer length
338  
339  - queue_type - SCSI task attribute (queue type)
340  
341  - data_direction - command's data flow direction, one of SCST_DATA_*
342    constants
343
344  - expected_values_set - true if expected_data_direction and
345    expected_transfer_len contain valid values
346    
347  - expected_data_direction - remote initiator supplied command's data
348    flow direction
349
350  - expected_transfer_len - remote initiator supplied transfer length
351
352 In the PARSE state of SCSI commands processing the user space device
353 handler shall check and provide SCST values for command data buffer
354 length, data flow direction and timeout, which it shall reply using the
355 corresponding reply command.
356
357 In case of any error the error reporting should be deferred until
358 SCST_USER_EXEC subcommand, where the appropriate SAM status and sense
359 shall be set.
360    
361
362                 4.4.4. SCST_USER_ALLOC_MEM
363
364 SCST_USER_ALLOC_MEM returns SCSI command on memory allocation state of
365 the SCST processing. On this state the user space device handler shall
366 allocate the command's data buffer with bufflen length and then return
367 it to SCST using the corresponding reply command. Then SCST internally
368 will convert it in SG vector in order to use it itself and by target
369 drivers.
370
371 If the memory reuse type is disabled (i.e. set to SCST_USER_MEM_NO_REUSE)
372 there are no special requirements for buffer memory or its alignment, it
373 could be just what malloc() returned. If the memory reuse type is enabled,
374 the buffer shall be page size aligned, for example using memalign()
375 function.
376
377 Payload contains struct scst_user_scsi_cmd_alloc_mem, which is defined
378 as the following:
379
380 struct scst_user_scsi_cmd_alloc_mem
381 {
382         uint64_t sess_h;
383
384         uint8_t cdb[SCST_MAX_CDB_SIZE];
385         int32_t cdb_len;
386
387         int32_t alloc_len;
388
389         uint8_t queue_type;
390         uint8_t data_direction;
391 },
392
393 where:
394
395  - sess_h - corresponding session handler
396
397  - cdb - SCSI CDB
398
399  - cdb_len - SCSI CDB length
400
401  - alloc_len - command's buffer length
402  
403  - queue_type - SCSI task attribute (queue type )
404
405  - data_direction - command's data flow direction, one of SCST_DATA_*
406    constants
407
408 Memory allocation, preparation and freeing are ones of the most
409 complicated and expensive operations during SCSI commands processing.
410 Module scst_user provides a way to almost completely eliminate those
411 operations by reusing once allocated memory for subsequent SCSI
412 commands. It is controlled by memory_reuse_type option, which could be
413 set by SCST_USER_SET_OPTIONS function. If any type memory reusage is
414 enabled, then SCST will use its internal SGV cache in order to cache
415 allocated and fully built SG vectors for subsequent commands of this
416 type, so for them SCST_USER_ALLOC_MEM subfunction will not be called and
417 in SCST_USER_EXEC pbuf pointer will point to that reused buffer. 
418
419 SGV cache is a backend cache made on top of Linux kernel SLAB cache. It
420 caches SG vectors with power of 2 data sizes: 4K, 8K, ..., 4M. So, if
421 there is a 5K SCSI command coming, then the user space handler will be
422 asked for 8K allocation, from which only 5K will be used for this
423 particular SCSI command. Then that SG vector will be cached and
424 subsequently reused for all SCSI commands between 4K and 8K. For a 1M
425 SCSI command the user space handler will be asked for another buffer
426 (while the previous 5K one will be kept), which will not be then reused
427 for 5K SCSI commands, since 1M and 5K vectors belong to different cache
428 data sizes, it will be reused only for commands between 512K and 1M.
429 Then, after some time of inactivity or when the system is under memory
430 pressure, the cache entries will be freed and the user space handler
431 will be notified using SCST_USER_ON_CACHED_MEM_FREE.
432
433 Since SGV cache caches SG vectors with power of 2 data sizes, alloc_len
434 field could be up to 2 times more, than actually required by the SCSI
435 command.
436
437 The memory reuse could be used in both SCSI tagged and untagged queuing
438 environments. In the SCSI tagged queuing environment the SGV cache will
439 take care that several commands don't use the same buffer simultaneously
440 by asking the user space handler to allocate a new data buffer, when all
441 cached ones are busy.
442
443 Some important notes:
444
445 1. If the user space handler needs to call fork(), it must call
446 madvise() with MADV_DONTFORK flag for all allocated data buffers,
447 otherwise parent or child process could loose the connection with them,
448 which could lead to data corruption. See http://lwn.net/Articles/171941/
449 for details.
450
451 2. The interface assumes that all allocated memory by the user space
452 handler is DMA'able by the target hardware. This is almost always true
453 for most modern systems, except if the target hardware isn't capable of
454 using 64-bit address space and the system has >4GB of memory or the
455 memory addresses are in address space, which is unavailable with 32-bit
456 addresses.
457
458 In case of any error the error reporting should be deferred until
459 SCST_USER_EXEC subcommand, where the appropriate SAM status and sense
460 should be set.
461
462
463                 4.4.5. SCST_USER_EXEC
464
465 SCST_USER_EXEC returns SCSI command on execution state of the SCST
466 processing. The user space handler should execute the SCSI command and
467 reply using the corresponding reply command.
468
469 In some cases for performance reasons for READ-type SCSI commands
470 SCST_USER_ALLOC_MEM subcommand isn't returned before SCST_USER_EXEC.
471 Thus, if pbuf pointer is 0 and the SCSI command needs data transfer,
472 the user space handler should be prepared to allocate the data buffer
473 with size alloc_len, which could be up to 2 times more, than actually
474 required by the SCSI command. But field bufflen will contain the correct
475 value. All the memory reusage rules, described for SCST_USER_ALLOC_MEM,
476 apply to SCST_USER_EXEC as well.
477
478 Payload contains struct scst_user_scsi_cmd_exec, which is defined as the
479 following:
480
481 struct scst_user_scsi_cmd_exec
482 {
483         uint64_t sess_h;
484
485         uint8_t cdb[SCST_MAX_CDB_SIZE];
486         int32_t cdb_len;
487
488         int32_t data_len;
489         int32_t bufflen;
490         int32_t alloc_len;
491         uint64_t pbuf;
492         uint8_t queue_type;
493         uint8_t data_direction;
494         uint8_t partial;
495         uint32_t timeout;
496
497         uint32_t parent_cmd_h;
498         int32_t parent_cmd_data_len;
499         uint32_t partial_offset;
500 },
501
502 where:
503
504  - sess_h - corresponding session handler
505
506  - cdb - SCSI CDB
507
508  - cdb_len - SCSI CDB length
509
510  - data_len - command's data length. Could be different from bufflen for
511    commands like VERIFY, which transfer different amount of data, than
512    process, or even none of them
513  
514  - bufflen - command's buffer length
515
516  - alloc_len - command's buffer length, which should be allocated, if pbuf
517    is 0 and the command requires data transfer
518
519  - pbuf - pointer to command's data buffer or 0 for SCSI commands
520    without data transfer.
521
522  - queue_type - SCSI task attribute (queue type)
523
524  - data_direction - command's data flow direction, one of SCST_DATA_*
525    constants
526
527  - partial - specifies, if the command is a partial subcommand, could
528    have the following OR'ed flags:
529
530    * SCST_USER_SUBCOMMAND - set if the command is a partial subcommand
531    
532    * SCST_USER_SUBCOMMAND_FINAL - set if the subcommand is a final one
533
534  - timeout - CDB execution timeout
535
536  - parent_cmd_h - has the same unique value for all partial data
537    transfers subcommands of one original (parent) command
538
539  - parent_cmd_data_len - for partial data transfers subcommand has the
540    size of the overall data transfer of the original (parent) command
541
542  - partial_offset - has offset of the subcommand in the original
543    (parent) command
544
545 It is guaranteed that only commands of the same queue_type per session
546 can be returned simultaneously.
547
548 In case of any error it should be reported via appropriate SAM status
549 and sense. If it happens for a subcommand of a partial data transfers
550 command, all other subcommands of this command, which already passed the
551 the user space handler or will be passed in the future, will be aborted
552 by scst_user, the user space handler should ignore them.
553
554
555                 4.4.6. SCST_USER_ON_FREE_CMD
556
557 SCST_USER_ON_FREE_CMD returns SCSI command when the command is about to
558 be freed. At this stage, the user space device handler could do any
559 necessary cleanups, for instance, free allocated for data buffer memory.
560
561 NOTE! If the memory reusage is enabled, then the data buffer must not be
562 freed, it will be reused by subsequent SCSI commands. The buffer must be
563 freed only on SCST_USER_ON_CACHED_MEM_FREE event.
564
565 Payload contains struct scst_user_scsi_cmd_on_free_cmd, which is defined
566 as the following:
567
568 struct scst_user_scsi_cmd_on_free_cmd
569 {
570         uint64_t pbuf;
571         int32_t resp_data_len;
572         uint8_t buffer_cached;
573         uint8_t aborted;
574         uint8_t status;
575 },
576
577 where:
578
579  - pbuf - pointer to command's data buffer or 0 for SCSI commands
580    without data transfer.
581
582  - resp_data_len - length of the response data
583
584  - buffer_cached - true, if memory reusage is enabled for this command
585
586  - aborted - true, if command was aborted
587
588  - status - SAM status of the commands execution
589    
590 The user space handler should reply using the corresponding reply
591 command. No error code is needed.
592
593
594                 4.4.7. SCST_USER_ON_CACHED_MEM_FREE
595
596 SCST_USER_ON_CACHED_MEM_FREE subcommand is returned, when SGV cache
597 decided that this buffer isn't needed anymore. This happens after some
598 time of inactivity or when the system is under memory pressure.
599
600 Payload contains struct scst_user_on_cached_mem_free, which is defined
601 as the following:
602
603 struct scst_user_scsi_cmd_alloc_mem
604 {
605         uint64_t pbuf;
606 },
607
608 where:
609
610  - pbuf - pointer to buffer, which should be freed
611
612
613                 4.4.8. SCST_USER_TASK_MGMT
614  
615 SCST_USER_TASK_MGMT subcommand returns a task management functions.
616 Payload contains struct scst_user_tm, which is defined as the following:
617
618 struct scst_user_tm
619 {
620         uint64_t sess_h;
621         uint32_t fn;
622         uint32_t cmd_h_to_abort;
623 },
624
625 where:
626
627  - sess_h - corresponding session handler
628
629  - fn - task management function, see below
630
631  - cmd_h_to_abort - handle of command to abort. Valid only if fn is
632    SCST_ABORT_TASK
633    
634 After TM function is completed, the user space device handler shall
635 reply using "result" field of the corresponding reply command. It isn't
636 necessary to wait for aborted command(s) finished, the result of TM
637 function shall be returned immediately. SCST core will take care that
638 the reply to the TM function isn't sent before all affection SCSI
639 commands finished.
640
641 Possible values of "fn" field:
642
643  - SCST_ABORT_TASK - cmd_h_to_abort shall be aborted
644
645  - SCST_ABORT_TASK_SET - task set on the device shall be aborted
646
647  - SCST_CLEAR_ACA - ACA status shall be cleared
648
649  - SCST_CLEAR_TASK_SET  - task set on the device shall be cleared
650
651  - SCST_LUN_RESET, SCST_TARGET_RESET - reset of the device shall be done
652
653  - SCST_NEXUS_LOSS_SESS - notifies about nexus loss event for the session
654
655  - SCST_ABORT_ALL_TASKS_SESS - all tasks in the session shall be aborted
656  
657  - SCST_NEXUS_LOSS - notifies about global nexus loss event
658  
659  - SCST_ABORT_ALL_TASKS - all tasks shall be aborted
660
661 Possible return values are:
662
663  - SCST_MGMT_STATUS_SUCCESS - success
664
665  - SCST_MGMT_STATUS_TASK_NOT_EXIST - task does not exist
666
667  - SCST_MGMT_STATUS_LUN_NOT_EXIST - LUN does not exist
668
669  - SCST_MGMT_STATUS_FN_NOT_SUPPORTED - task management function not
670    supported
671
672  - SCST_MGMT_STATUS_REJECTED - task management function was rejected
673
674  - SCST_MGMT_STATUS_FAILED - task management function failed
675
676
677                 5. SCST_USER_REPLY_AND_GET_PRIO_CMD
678
679 SCST_USER_REPLY_AND_GET_PRIO_CMD is the same as
680 SCST_USER_REPLY_AND_GET_CMD, except that it returns management (i.e.
681 priority) subcommands from priority queue, if usage of a separate PRIO
682 was configured. 
683
684 Management subcommands are: SCST_USER_ATTACH_SESS, SCST_USER_DETACH_SESS
685 and SCST_USER_TASK_MGMT.
686
687 PRIO queue is always blocking, because poll() doesn't support, when
688 different threads wait with different events mask. Only one thread is
689 woken up on each event and if it isn't interested in such events,
690 another (interested) one will not be woken up.
691
692
693                 6. SCST_USER_REPLY_CMD
694
695 SCST_USER_REPLY_CMD IOCTL function allows the user space handler to
696 return the result of a command's execution. Its argument is defined as:
697
698 struct scst_user_reply_cmd
699 {
700         uint32_t cmd_h;
701         uint32_t subcode;
702         union {
703                 int32_t result;
704                 struct scst_user_scsi_cmd_reply_parse parse_reply;
705                 struct scst_user_scsi_cmd_reply_alloc_mem alloc_reply;
706                 struct scst_user_scsi_cmd_reply_exec exec_reply;
707         };
708 },
709
710 where:
711
712  - cmd_h - command handle used to identify the command in the reply.
713
714  - subcode - subcommand code, see 4.1
715
716 Union contains the subcommand's specific payload:
717
718  - result - subcommand's result code
719
720
721 struct scst_user_scsi_cmd_reply_parse
722 {
723         uint8_t queue_type;
724         uint8_t data_direction;
725         int32_t data_len;
726         int32_t bufflen;
727 },
728
729 where:
730
731  - queue_type - SCSI task attribute (queue type )
732  
733  - data_direction - command's data flow direction, one of SCST_DATA_* constants
734
735  - data_len - command's data length
736  
737  - bufflen - command's buffer length
738
739
740 struct scst_user_scsi_cmd_reply_alloc_mem
741 {
742         uint64_t pbuf;
743 },
744
745 where:
746
747  - pbuf - pointer to command's data buffer
748
749
750 struct scst_user_scsi_cmd_reply_exec
751 {
752         int32_t resp_data_len;
753         uint64_t pbuf;
754
755         uint8_t reply_type;
756
757         uint8_t status;
758         uint8_t sense_len;
759         aligned_u64 psense_buffer;
760 },
761
762 where:
763
764  - resp_data_len - length of the response data
765
766  - pbuf - pointer to command's data buffer. Used only when in the
767    original SCST_USER_EXEC subcommand pbuf field is 0
768
769  - reply_type - could be one of the following constants:
770  
771      * SCST_EXEC_REPLY_BACKGROUND - tells SCST send to the remote
772        initiator GOOD status, but the command not yet completed by the
773        user space handler, it is being executed in the background. When
774        it will be completed, the user space handler will call
775        SCST_USER_REPLY_CMD again with reply_type
776        SCST_EXEC_REPLY_COMPLETED.
777      
778      * SCST_EXEC_REPLY_COMPLETED - the user space handler completed the command
779
780  - status - SAM status of the commands execution
781
782  - sense_len - length of sense data in psense_buffer, if any
783
784  - psense_buffer - pointed to sense buffer
785
786
787                 IV. Commands processing flow example.
788
789 As the example consider a simple synchronous VTL, which serves one
790 virtual SCSI tape device and can process only one command at time from
791 any initiator. 
792
793 At the beginning the VTL opens using open() call /dev/scst_user in the
794 default blocking mode.
795
796 Then it using SCST_USER_REGISTER_DEVICE ioctl() function registers the
797 tape device. Since only one command at time is supported, the allocated
798 command's data memory could be reused for both READ-type (i.e. which
799 involve data transfer from target to initiator) and WRITE-type (i.e.
800 which involve data transfer from initiator to target) commands. So the
801 device is configured with parse_type SCST_USER_PARSE_STANDARD,
802 on_free_cmd_type SCST_USER_ON_FREE_CMD_IGNORE, memory_reuse_type
803 SCST_USER_MEM_REUSE_ALL, prio_queue_type SCST_USER_PRIO_QUEUE_SINGLE and
804 partial_transfers_type SCST_USER_PARTIAL_TRANSFERS_NOT_SUPPORTED.
805
806 Then it prepares struct scst_user_get_cmd with reply set to 0, calls
807 SCST_USER_REPLY_AND_GET_CMD ioctl() and waits until some initiator
808 connects to its tape device. On that event the VTL receives
809 SCST_USER_ATTACH_SESS subcommand. Since the VTL doesn't use any
810 initiator specific data, it can do nothing on that subcommand, so it
811 prepares scst_user_reply_cmd structure, where:
812
813  - cmd_h set to returned by SCST_USER_REPLY_AND_GET_CMD ioctl() cmd_h
814
815  - subcode set to SCST_USER_ATTACH_SESS
816  
817  - result set to 0
818  
819 Then it prepares struct scst_user_get_cmd with reply set to the prepared
820 scst_user_reply_cmd structure, calls SCST_USER_REPLY_AND_GET_CMD ioctl()
821 and waits for some SCSI command arrives from the initiator.
822
823 If the received SCSI command is READ-type one, SCST does the necessary
824 preparations, then the VTL receives SCST_USER_EXEC subcommand, where
825 bufflen and data_len are set correctly, but memory for buffer isn't
826 allocated, so pbuf field is 0. The VTL then allocates the data buffer
827 with size alloc_len, e.g. using malloc(). Then the VTL reads the data
828 from disk in it, e.g. using O_DIRECT read() function, then prepares
829 scst_user_reply_cmd structure, where:
830
831  - cmd_h set to returned by SCST_USER_REPLY_AND_GET_CMD ioctl() cmd_h
832
833  - subcode set to SCST_USER_EXEC
834
835  - exec_reply.resp_data_len set to length of the read data
836
837  - exec_reply.pbuf set to the data buffer, where the data were read
838  
839  - exec_reply.reply_type set to SCST_EXEC_REPLY_COMPLETED
840  
841  - exec_reply.status set to the SAM defined status of the
842    operation
843  
844  - exec_reply.sense_len set and exec_reply.psense_buffer filled with
845    sense data, if necessary
846
847 Then it prepares struct scst_user_get_cmd with reply set to the prepared
848 scst_user_reply_cmd structure, calls SCST_USER_REPLY_AND_GET_CMD ioctl()
849 and waits for the next SCSI command arrives from the initiator. That's
850 all for this SCSI command. For the next one the used data buffer will be
851 reused.
852
853 For WRITE-type SCSI commands the processing is the same, but
854 SCST_USER_ALLOC_MEM will be returned before SCST_USER_EXEC, since the
855 data transfer from the initiator precedes the commands execution.
856
857 In case, if the first command requires 4K data buffer, but the second
858 one - 1M, for it the VTL also will be asked to allocate the buffer.
859 Then, if no more 4K commands come for some time, for it
860 SCST_USER_ON_CACHED_MEM_FREE subcommand will be returned to the VTL in
861 order to ask it to free that buffer.