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