6bc310ea12f9b244ec8eb560d159069380fe6ed9
[mirror/scst/.git] / doc / scst_user_spec.txt
1         SCST USER SPACE DEVICE HANDLER MODULE.
2
3           USER SPACE INTERFACE DESCRIPTION.
4
5                    Version 0.3.
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
47                 III. IOCTL() functions.
48
49 There are following IOCTL functions available. All of them has one
50 argument. They all, except SCST_USER_REGISTER_DEVICE return 0 for
51 success or -1 in case of error, and errno is set appropriately.
52
53
54                 1. SCST_USER_REGISTER_DEVICE
55
56 SCST_USER_REGISTER_DEVICE - registers new virtual user space device. The
57 argument is:
58
59 struct scst_user_dev
60 {
61         int version;
62         char name[SCST_MAX_NAME];
63         uint8_t type;
64 },
65
66 where:
67
68  - version - is a protocol version, shall be 0x0961
69
70  - name - name of the device
71  
72  - type - SCSI type of the device
73
74 SCST_USER_REGISTER_DEVICE returns registered device's handler or -1
75 in case of error, and errno is set appropriately.
76
77
78                 2. SCST_USER_UNREGISTER_DEVICE 
79
80 SCST_USER_UNREGISTER_DEVICE unregisters virtual user space device. The
81 argument is the device handler returned by SCST_USER_REGISTER_DEVICE
82 command. If there are some pending commands at the time, when
83 SCST_USER_UNREGISTER_DEVICE the function will fail with EBUSY errno set.
84
85
86                 3. SCST_USER_SET_OPTIONS/SCST_USER_GET_OPTIONS
87
88 SCST_USER_SET_OPTIONS/SCST_USER_GET_OPTIONS allows to set or get
89 correspondingly various options that control various aspects of SCSI
90 commands processing.
91
92 The argument is:
93
94 struct scst_user_dev
95 {
96         int h;
97         uint8_t parse_type;
98         uint8_t on_free_cmd_type;
99         uint8_t memory_reuse_type;
100 },
101
102 where:
103
104  - h - corresponding device handle
105
106  - parse_type - defines how the user space handler wants to process
107    PARSE subcommand. Possible values are:
108   
109    * SCST_USER_PARSE_STANDARD - tells SCST use standard internal parse
110      routine for this SCSI device type.
111    
112    * SCST_USER_PARSE_CALL - tells SCST generate SCST_USER_PARSE for all
113      SCSI commands
114
115  - on_free_cmd_type - defines how the user space handler wants to
116    process ON_FREE_CMD subcommand. Possible values are:
117   
118    * SCST_USER_ON_FREE_CMD_IGNORE - tells SCST do nothing on this event.
119    
120    * SCST_USER_ON_FREE_CMD_CALL - tells SCST generate
121      SCST_USER_ON_FREE_CMD for all SCSI commands
122
123  - memory_reuse_type - defines how memory allocated by the user space
124    handler for a SCSI commands data buffers is then reused by the SCST
125    core as data buffer for subsequent commands. Possible values are:
126    
127    * SCST_USER_MEM_NO_REUSE - no memory reuse is possible, for each
128      commands the user space handler will each time allocate a dedicated
129      data buffer
130
131    * SCST_USER_MEM_REUSE_READ - memory reuse by only READ-type commands
132      (i.e. which involve data transfer from target to initiator) is
133      allowed. For all WRITE-type commands (i.e. which involves data
134      transfer from initiator to target) the user space handler will
135      each time allocate a dedicated data buffer
136
137    * SCST_USER_MEM_REUSE_WRITE - memory reuse by only WRITE-type
138      commands is allowed. For all WRITE-type commands the user space
139      handler will each time allocate a dedicated data buffer
140
141    * SCST_USER_MEM_REUSE_ALL - unlimited memory reuse is possible.
142
143 Flags parse_type and on_free_cmd_type are designed to improve
144 performance by eliminating context switches to the user space handler,
145 when processing of the corresponding event isn't needed.
146
147 Flag memory_reuse_type is designed to improve performance by eliminating
148 memory allocation, preparation and then freeing each time for each
149 commands, if the same memory will be allocated again and again. See
150 SCST_USER_ALLOC_MEM description below for more info.
151
152 By default, parse_type is SCST_USER_PARSE_STANDARD, on_free_cmd_type is
153 SCST_USER_ON_FREE_CMD_CALL and memory_reuse_type is
154 SCST_USER_MEM_NO_REUSE.
155
156
157                 4. SCST_USER_REPLY_AND_GET_CMD
158
159 If SCST_USER_REPLY_AND_GET_CMD allows at one call reply on the current
160 subcommand from SCST and get the next one. If 0 is returned by ioctl(),
161 SCST_USER_REPLY_AND_GET_CMD returns a SCST subcommand in the argument,
162 which is defined as the following:
163
164 struct scst_user_get_cmd
165 {
166         int h;
167         int subcode;
168         struct scst_user_reply_cmd *reply;
169         int cmd_h;
170         union {
171                 struct scst_user_sess sess;
172                 struct scst_user_sess_descr sess_descr;
173                 struct scst_user_scsi_cmd_parse parse_cmd;
174                 struct scst_user_scsi_cmd_alloc_mem alloc_cmd;
175                 struct scst_user_scsi_cmd_exec exec_cmd;
176                 struct scst_user_scsi_cmd_free_cmd on_free_cmd;
177                 struct scst_user_on_cached_mem_free on_cached_mem_free;
178                 struct scst_user_tm tm_cmd;
179         } payload;
180 },
181
182 where:
183
184  - h - corresponding device handle
185
186  - subcode - subcommand code, see 4.1 below
187
188  - reply - pointer to the reply data or, if NULL, there is no reply, see
189    SCST_USER_REPLY_CMD for description of struct scst_user_reply_cmd
190    fields
191
192  - cmd_h - command handle used to identify the command in the reply.
193
194  - payload - command specific payload
195
196 For all received subcommands the user space device handler shall call
197 SCST_USER_REPLY_AND_GET_CMD or SCST_USER_REPLY_CMD function to tell SCST
198 that the subcommand's processing is finished, although some subcommands
199 don't return a value.
200
201
202                 4.1. Possible subcommands:
203
204
205                 4.1.1. SCST_USER_ATTACH_SESS
206
207 SCST_USER_ATTACH_SESS notifies the user space handler that a new
208 initiator's session is about to be attached to the device. Field
209 "payload" contains struct scst_user_sess, which is defined as the
210 following:
211
212 struct scst_user_sess
213 {
214         int h;
215         uint64_t lun;
216         uint8_t rd_only;
217 },
218
219 where:
220
221  - h - session's handle
222
223  - lun - assigned LUN for this device in this session
224  
225  - rd_only - if true, this device is read only in this session
226  
227 If the user space handler needs more info about the session, it can call
228 SCST_USER_DESCRIBE_SESS subcommand.
229
230 The user space handler should reply with value 0 for success, or
231 negative error code from errno.h otherwise.
232
233
234                 4.1.2. SCST_USER_DETACH_SESS
235
236 SCST_USER_DETACH_SESS notifies the user space handler that the
237 corresponding initiator is about to be detached from the particular
238 device. Field "payload" contains struct scst_user_sess, where only
239 handle field is valid.
240
241 This command doesn't reply anything, although SCST_USER_REPLY_AND_GET_CMD or
242 SCST_USER_REPLY_CMD function must be called.
243
244
245                 4.1.3. SCST_USER_DESCRIBE_SESS
246
247 SCST_USER_DESCRIBE_SESS describes the session. Field "payload" contains
248 struct scst_user_sess_descr, which is defined as the following:
249
250 struct scst_user_sess_descr
251 {
252         char initiator_name[SCST_MAX_NAME];
253         char acg_name[SCST_MAX_NAME];
254 },
255
256 where:
257
258  - initiator_name - name of the initiator port
259
260  - acg_name - name of the corresponding SCST security group, to which
261    this session is assigned.
262
263 This command doesn't reply anything, although
264 SCST_USER_REPLY_AND_GET_CMD or SCST_USER_REPLY_CMD function must be
265 called.
266
267
268                 4.1.4. SCST_USER_PARSE
269
270 SCST_USER_PARSE returns SCSI command on PARSE state of the SCST
271 processing. The PARSE state is intended to check validity of the
272 command, determine data transfer type and the necessary data buffer
273 size. This subcommand is returned only if SCST_USER_SET_OPTIONS
274 parse_type is set to SCST_USER_PARSE_CALL. Otherwise, the standard SCST
275 internal parse routine for this SCSI device type will do all the job.
276
277 Field "payload" contains struct scst_user_scsi_cmd_parse, which is
278 defined as the following:
279
280 struct scst_user_scsi_cmd_parse
281 {
282         int sess_h;
283
284         uint8_t cdb[MAX_COMMAND_SIZE];
285         int cdb_len;
286
287         enum scst_cmd_queue_type queue_type;
288         int timeout;
289         scst_data_direction data_direction;
290         size_t bufflen;
291
292         scst_data_direction expected_data_direction;
293         unsigned int expected_transfer_len;
294         uint8_t expected_values_set;
295 },
296
297 where:
298
299  - sess_h - corresponding session handler
300
301  - cdb - SCSI CDB
302
303  - cdb_len - SCSI CDB length
304  
305  - queue_type - SCSI task attribute (queue type)
306  
307  - timeout - CDB execution timeout
308  
309  - data_direction - command's data flow direction, one of SCST_DATA_*
310    constants
311  
312  - bufflen - command's buffer length
313  
314  - expected_data_direction - remote initiator supplied command's data
315    flow direction
316
317  - expected_transfer_len - remote initiator supplied transfer length
318
319  - expected_values_set - true if expected_data_direction and
320    expected_transfer_len contain valid values
321    
322 In the PARSE state of SCSI commands processing the user space device
323 handler shall check and provide SCST values for command data buffer
324 length, data flow direction and timeout, which it shall reply using the
325 corresponding reply command.
326
327 In case of any error the error reporting should be deferred until
328 SCST_USER_EXEC subcommand, where the appropriate SAM status and sense
329 shall be set.
330    
331
332                 4.4.5. SCST_USER_ALLOC_MEM
333
334 SCST_USER_ALLOC_MEM returns SCSI command on memory allocation state of
335 the SCST processing. On this state the user space device handler shall
336 allocate the command's data buffer with bufflen length and then return
337 it to SCST using the corresponding reply command. There are no special
338 requirements for this memory or its alignment, it could be just what 
339 malloc() returns. Then SCST internally will convert it in SG vector in
340 order to use it itself and by target drivers.
341
342 This command will be returned only if parse_type was set to
343 SCST_USER_PARSE_STANDARD during the device registration, otherwise the
344 user space device handler shall allocate the command data buffer on the
345 PARSE stage.
346
347 Field "payload" contains struct scst_user_scsi_cmd_alloc_mem, which is
348 defined as the following:
349
350 struct scst_user_scsi_cmd_alloc_mem
351 {
352         int sess_h;
353
354         uint8_t cdb[MAX_COMMAND_SIZE];
355         int cdb_len;
356
357         enum scst_cmd_queue_type queue_type;
358         scst_data_direction data_direction;
359         size_t bufflen;
360 },
361
362 where:
363
364  - sess_h - corresponding session handler
365
366  - cdb - SCSI CDB
367
368  - cdb_len - SCSI CDB length
369  
370  - queue_type - SCSI task attribute (queue type )
371  
372  - data_direction - command's data flow direction, one of SCST_DATA_*
373    constants
374
375  - bufflen - command's buffer length
376
377 Memory allocation, preparation and freeing are ones of the most
378 complicated and expensive operations during SCSI commands processing.
379 Module scst_user provides a way to almost completely eliminate those
380 operations by reusing once allocated memory for subsequent SCSI
381 commands. It is controlled by memory_reuse_type option, which could be
382 set by SCST_USER_SET_OPTIONS function. If any type memory reusage is
383 enabled, then SCST will use its internal SGV cache in order to cache
384 allocated and fully built SG vectors for subsequent commands of this
385 type, so for them SCST_USER_ALLOC_MEM subfunction will not be called and
386 in SCST_USER_EXEC buf pointer will point to that reused buffer. 
387
388 SGV cache is a backend cache made on top of Linux kernel SLAB cache. It
389 caches SG vectors with power of 2 data sizes: 4K, 8K, ..., 4M. So, if
390 there is a 5K SCSI command coming, then the user space handler will be
391 asked for 8K allocation, from which only 5K will be used for this
392 particular SCSI command. Then that SG vector will be cached and
393 subsequently reused for all SCSI commands between 4K and 8K. For a
394 subsequent 1M SCSI command the user space handler will be asked for
395 another buffer (while the previous 5K one will be kept), which will not
396 be then reused for 5K SCSI commands, since 1M and 5K vectors belong to
397 different cache data sizes, it will be reused only for commands between
398 512K and 1M. Then, after some time of inactivity or when the system is
399 under memory pressure, the cache entries will be freed and the user
400 space handler will be notified using SCST_USER_ON_CACHED_MEM_FREE.
401
402 Since SGV cache caches SG vectors with power of 2 data sizes, bufflen
403 field could be up to 2 times more, than actually required by the SCSI
404 command.
405
406 The memory reuse could be used in both SCSI tagged and untagged queuing
407 environments. In the SCSI tagged queuing environment the SGV cache will
408 take care that several commands don't use the same buffer simultaneously
409 by asking the user space handler to allocate a new data buffer, when all
410 cached ones are busy.
411
412 In case of any error the error reporting should be deferred until
413 SCST_USER_EXEC subcommand, where the appropriate SAM status and sense
414 should be set.
415
416
417                 4.4.6. SCST_USER_EXEC
418
419 SCST_USER_EXEC returns SCSI command on execution state of the SCST
420 processing. The user space handler should execute the SCSI command and
421 reply using the corresponding reply command.
422
423 In some cases for performance reasons for READ-type SCSI commands
424 SCST_USER_ALLOC_MEM subcommand isn't returned before SCST_USER_EXEC.
425 Thus, if buf pointer is NULL and the SCSI command needs data transfer,
426 the user space handler should be prepared to allocate the data buffer
427 with size bufflen. Commands buffer length bufflen could be up to 2 times
428 more, than actually required by the SCSI command. Data length field
429 data_len contains the correct value. All the memory reusage rules,
430 described in 4.4.5, apply to SCST_USER_EXEC as well.
431
432 Field "payload" contains struct scst_user_scsi_cmd_exec, which is
433 defined as the following:
434
435 struct scst_user_scsi_cmd_exec
436 {
437         int sess_h;
438
439         uint8_t cdb[MAX_COMMAND_SIZE];
440         int cdb_len;
441
442         enum scst_cmd_queue_type queue_type;
443         int timeout;
444         scst_data_direction data_direction;
445         size_t data_len;
446         size_t bufflen;
447         uint8_t *buf;
448 },
449
450 where:
451
452  - sess_h - corresponding session handler
453
454  - cdb - SCSI CDB
455
456  - cdb_len - SCSI CDB length
457  
458  - queue_type - SCSI task attribute (queue type)
459
460  - timeout - CDB execution timeout
461  
462  - data_direction - command's data flow direction, one of SCST_DATA_*
463    constants
464
465  - data_len - command's data length
466  
467  - bufflen - command's buffer length
468  
469  - buf - pointer to command's data buffer or NULL for SCSI commands
470    without data transfer.
471
472 In case of any error it should be reported via appropriate SAM status
473 and sense.
474
475
476                 4.4.7. SCST_USER_ON_FREE_CMD
477
478 SCST_USER_ON_FREE_CMD returns SCSI command when the command is about to
479 be freed. At this stage, the user space device handler could do any
480 necessary cleanups, for instance, free allocated for data buffer memory.
481
482 NOTE! If the memory reusage is enabled, then the data buffer must not be
483 freed, it will be reused by subsequent SCSI commands. The buffer must be
484 freed only on SCST_USER_ON_CACHED_MEM_FREE event.
485
486 Field "payload" contains struct scst_user_scsi_cmd_on_free_cmd, which is
487 defined as the following:
488
489 struct scst_user_scsi_cmd_on_free_cmd
490 {
491         int sess_h;
492
493         uint8_t cdb[MAX_COMMAND_SIZE];
494         int cdb_len;
495
496         enum scst_cmd_queue_type queue_type;
497         scst_data_direction data_direction;
498         size_t data_len;
499         size_t bufflen;
500         uint8_t *buf;
501         int resp_data_len;
502
503         uint8_t status;
504         uint8_t sense_buffer[SCSI_SENSE_BUFFERSIZE];
505 },
506
507 where:
508
509  - sess_h - corresponding session handler
510
511  - cdb - SCSI CDB
512
513  - cdb_len - SCSI CDB length
514  
515  - queue_type - SCSI task attribute (queue type )
516  
517  - data_direction - command's data flow direction, one of SCST_DATA_*
518    constants
519
520  - data_len - command's data length
521  
522  - bufflen - command's buffer length
523
524  - buf - pointer to command's data buffer or NULL for SCSI commands
525    without data transfer.
526
527  - resp_data_len - length of the response data
528
529  - status - SAM status of the commands execution
530    
531  - sense_buffer - sense buffer
532    
533 The user space handler should reply using the corresponding reply
534 command. No error code is returned.
535
536
537                 4.4.9. SCST_USER_ON_CACHED_MEM_FREE
538
539 SCST_USER_ON_CACHED_MEM_FREE subcommand is returned, when SGV cache
540 decided that this buffer isn't needed anymore. This happens after some
541 time of inactivity or when the system is under memory pressure.
542
543 Field "payload" contains struct scst_user_on_cached_mem_free, which is
544 defined as the following:
545
546 struct scst_user_scsi_cmd_alloc_mem
547 {
548         int sess_h;
549
550         uint8_t *buf;
551         size_t bufflen;
552 },
553
554 where:
555
556  - sess_h - corresponding session handler
557
558  - buf - pointer to buffer, which should be freed
559
560  - bufflen - command's buffer length
561
562
563
564                 4.4.10. SCST_USER_TASK_MGMT
565  
566 SCST_USER_TASK_MGMT subcommand returns a task management functions.
567 Field "payload" contains struct scst_user_tm, which is defined as the
568 following:
569
570 struct scst_user_tm
571 {
572         int sess_h;
573         int fn;
574         int cmd_h_to_abort;
575 },
576
577 where:
578
579  - sess_h - corresponding session handler
580
581  - fn - task management function, see below
582
583  - cmd_h_to_abort - handle of command to abort. Valid only if fn is
584    SCST_ABORT_TASK
585    
586 After TM function completed, the user space device handler shall reply
587 using "result" field of the corresponding reply command. It isn't
588 necessary to wait for aborted command(s) finished, the result of TM
589 function could be returned immediately. SCST core will take care that
590 the reply to the TM function isn't sent before all affection SCSI
591 commands finished.
592
593 Possible values of "fn" field:
594
595  - SCST_ABORT_TASK - cmd_h_to_abort shall be aborted
596
597  - SCST_ABORT_TASK_SET - task set on the device shall be aborted
598
599  - SCST_CLEAR_ACA - ACA status shall be cleared
600
601  - SCST_CLEAR_TASK_SET  - task set on the device shall be cleared
602
603  - SCST_LUN_RESET, SCST_TARGET_RESET - reset of the device shall be done
604
605  - SCST_NEXUS_LOSS_SESS - notifies about nexus loss event for the session
606
607  - SCST_ABORT_ALL_TASKS_SESS - all tasks in the session shall be aborted
608  
609  - SCST_NEXUS_LOSS - notifies about global nexus loss event
610  
611  - SCST_ABORT_ALL_TASKS - all tasks shall be aborted
612
613 Possible return values are:
614
615  - SCST_DEV_TM_COMPLETED_SUCCESS - the command is done with success, no
616    further actions required
617   
618  - SCST_DEV_TM_COMPLETED_FAILED - the command is failed, no further
619    actions required
620
621  - SCST_DEV_TM_NOT_COMPLETED - the command partially completed, regular
622    standard actions for the command should be done
623
624
625                 5. SCST_USER_REPLY_CMD
626
627 SCST_USER_REPLY_CMD IOCTL function allows the user space handler to
628 return the result of a command's execution. Its argument is defined as:
629
630 struct scst_user_reply_cmd
631 {
632         int h;
633         int cmd_h;
634         union {
635                 int result;
636                 struct scst_user_scsi_cmd_reply_parse parse_reply;
637                 struct scst_user_scsi_cmd_reply_alloc_mem alloc_reply;
638                 struct scst_user_scsi_cmd_reply_exec exec_reply;
639         } payload;
640 },
641
642 where:
643
644  - h - corresponding device handle
645
646  - cmd_h - command handle used to identify the command in the reply.
647
648  - payload - subcommand specific payload:
649
650 struct scst_user_scsi_cmd_reply_parse
651 {
652         enum scst_cmd_queue_type queue_type;
653         scst_data_direction data_direction;
654         size_t data_len;
655         size_t bufflen;
656         uint8_t *buf;
657 },
658
659 where:
660
661  - queue_type - SCSI task attribute (queue type )
662  
663  - data_direction - command's data flow direction, one of SCST_DATA_* constants
664
665  - data_len - command's data length
666  
667  - bufflen - command's buffer length
668
669  - buf - pointer to command's data buffer or NULL for SCSI commands
670    without data transfer.
671
672 struct scst_user_scsi_cmd_reply_alloc_mem
673 {
674         uint8_t *buf;
675 },
676
677 where:
678
679  - buf - pointer to command's data buffer
680
681 struct scst_user_scsi_cmd_reply_exec
682 {
683         uint8_t *buf;
684         int resp_data_len;
685
686         uint8_t status;
687         uint8_t sense_buffer[SCSI_SENSE_BUFFERSIZE];
688 },
689
690 where:
691
692  - buf - pointer to command's data buffer. Used only when in the
693    original SCST_USER_EXEC subcommand buf field is NULL
694
695  - resp_data_len - length of the response data
696
697  - status - SAM status of the commands execution
698    
699  - sense_buffer - sense buffer
700
701
702                 IV. Commands processing flow.
703
704 As the example consider a simple synchronous VTL, which serves one
705 virtual SCSI tape device and can process only one command at time from
706 any initiator. 
707
708 At the beginning the VTL opens using open() call /dev/scst_user in the
709 default blocking mode.
710
711 Then it using SCST_USER_REGISTER_DEVICE ioctl() function registers the
712 tape device. 
713
714 Since only one command at time is supported, the allocated command's
715 data memory could be reused for both READ-type (i.e. which involve data
716 transfer from target to initiator) and WRITE-type (i.e. which involve
717 data transfer from initiator to target) commands. So, the VTL then calls
718 SCST_USER_SET_OPTIONS function with handle h returned by
719 SCST_USER_REGISTER_DEVICE ioctl() and set parse_type to
720 SCST_USER_PARSE_STANDARD, on_free_cmd_type to
721 SCST_USER_ON_FREE_CMD_IGNORE and memory_reuse_type to
722 SCST_USER_MEM_REUSE_ALL.
723
724 Then it prepares struct scst_user_get_cmd with h set to the handle
725 returned by SCST_USER_REGISTER_DEVICE ioctl() and reply set to NULL,
726 calls SCST_USER_REPLY_AND_GET_CMD ioctl() and waits until some initiator
727 connects to its tape device. On that event the VTL receives
728 SCST_USER_ATTACH_SESS subcommand. Since the VTL doesn't use any
729 initiator specific data, it can do nothing on that subcommand, so it
730 prepares scst_user_reply_cmd structure, where:
731
732  - h set to handle returned by SCST_USER_REGISTER_DEVICE ioctl()
733  
734  - cmd_h set to returned by SCST_USER_REPLY_AND_GET_CMD ioctl() cmd_h
735  
736  - payload.result set to 0
737  
738 Then it prepares struct scst_user_get_cmd with h set to the handle
739 returned by SCST_USER_REGISTER_DEVICE ioctl() and reply set to the
740 prepared scst_user_reply_cmd structure, calls
741 SCST_USER_REPLY_AND_GET_CMD ioctl() and waits for some SCSI command
742 arrives from the initiator.
743
744 If the received SCSI command is READ-type one, SCST does the necessary
745 preparations, then the VTL receives SCST_USER_EXEC subcommand, where
746 bufflen and data_len are set correctly, but memory for buffer isn't
747 allocated, so buf field is NULL. The VTL then allocates the data buffer
748 with size bufflen, e.g. by malloc(). Then the VTL reads the data from
749 disk in it, e.g. using O_DIRECT read() function, then prepares
750 scst_user_reply_cmd structure, where:
751
752  - h set to handle returned by SCST_USER_REGISTER_DEVICE ioctl()
753  
754  - cmd_h set to returned by SCST_USER_REPLY_AND_GET_CMD ioctl() cmd_h
755  
756  - payload.exec_reply.buf set to the data buffer, where the data were read
757  
758  - payload.exec_reply.resp_data_len set to length of the read data
759  
760  - payload.exec_reply.status set to the SAM defined status of the
761    operation
762  
763  - payload.exec_reply.sense_buffer filled with the sense data, if
764    necessary
765
766 Then it prepares struct scst_user_get_cmd with h set to the handle
767 returned by SCST_USER_REGISTER_DEVICE ioctl() and reply set to the
768 prepared scst_user_reply_cmd structure, calls
769 SCST_USER_REPLY_AND_GET_CMD ioctl() and waits for the next SCSI command
770 arrives from the initiator. That's all for this SCSI command. For the
771 next one the used data buffer will be reused.
772
773 For WRITE-type SCSI commands the processing is the same, but
774 SCST_USER_ALLOC_MEM will be returned before SCST_USER_EXEC, since the
775 data transfer from the initiator precedes the commands execution.
776
777 In case, if the first command requires 4K data buffer, but the second
778 one - 1M, then for it the VTL also will be asked to allocate the buffer.
779 Then, if no more 4K commands come for some time, for it
780 SCST_USER_ON_CACHED_MEM_FREE subcommand will be returned to the VTL in
781 order to ask it to free that buffer.