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