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