e9c7ecf87984144ef8f99e2cd02ab3ebb02b1d4f
[mirror/scst/.git] / scst / README
1 Generic SCSI target mid-level for Linux (SCST)
2 ==============================================
3
4 Version 0.9.6, XX XXX 200X
5 --------------------------
6
7 SCST is designed to provide unified, consistent interface between SCSI
8 target drivers and Linux kernel and simplify target drivers development
9 as much as possible. Detail description of SCST's features and internals
10 could be found in "Generic SCSI Target Middle Level for Linux" document
11 SCST's Internet page http://scst.sourceforge.net.
12
13 SCST supports the following I/O modes:
14
15  * Pass-through mode with one to many relationship, i.e. when multiple
16    initiators can connect to the exported pass-through devices, for   
17    the following SCSI devices types: disks (type 0), tapes (type 1),
18    processors (type 3), CDROMs (type 5), MO disks (type 7), medium
19    changers (type 8) and RAID controllers (type 0xC)
20
21  * FILEIO mode, which allows to use files on file systems or block
22    devices as virtual remotely available SCSI disks or CDROMs with
23    benefits of the Linux page cache
24
25  * BLOCKIO mode, which performs direct block IO with a block device,
26    bypassing page-cache for all operations. This mode works ideally with
27    high-end storage HBAs and for applications that either do not need
28    caching between application and disk or need the large block
29    throughput
30
31  * User space mode using scst_user device handler, which allows to
32    implement in the user space virtual SCSI devices in the SCST
33    environment
34
35  * "Performance" device handlers, which provide in pseudo pass-through
36    mode a way for direct performance measurements without overhead of
37    actual data transferring from/to underlying SCSI device
38
39 In addition, SCST supports advanced per-initiator access and devices
40 visibility management, so different initiators could see different set
41 of devices with different access permissions. See below for details.
42
43 This is quite stable (but still beta) version.
44
45 Tested mostly on "vanilla" 2.6.21.1 kernel from kernel.org.
46
47 Installation
48 ------------
49
50 At first, make sure that the link "/lib/modules/`you_kernel_version`/build" 
51 points to the source code for your currently running kernel.
52
53 Then, since in the mainstream kernels scsi_do_req()/scsi_execute_async()
54 work in LIFO order, instead of expected and required FIFO, SCST needs a
55 new functions scsi_do_req_fifo()/scsi_execute_async_fifo() to be added
56 in the kernel. Patch scst_exec_req_fifo.patch from "kernel" directory
57 does that. If it doesn't apply to your kernel, apply it manually, it
58 only adds one of those functions and nothing more. You may not patch the
59 kernel if you don't need pass-through support or STRICT_SERIALIZING is
60 defined during the compilation (see description below).
61
62 To compile SCST type 'make scst'. It will build SCST itself and its
63 device handlers. To install them type 'make scst_install'. The driver
64 modules will be installed in '/lib/modules/`you_kernel_version`/extra'.
65 In addition, scsi_tgt.h, scst_debug.h as well as Module.symvers or
66 Modules.symvers will be copied to '/usr/local/include/scst'. The first
67 file contains all SCST's public data definition, which are used by
68 target drivers. The other ones support debug messages logging and build
69 process.
70
71 Then you can load any module by typing 'modprobe module_name'. The names
72 are:
73
74  - scst - SCST itself
75  - scst_disk - device handler for disks (type 0)
76  - scst_tape - device handler for tapes (type 1)
77  - scst_processor - device handler for processors (type 3)
78  - scst_cdrom - device handler for CDROMs (type 5)
79  - scst_modisk - device handler for MO disks (type 7)
80  - scst_changer - device handler for medium changers (type 8)
81  - scst_raid - device handler for storage array controller (e.g. raid) (type C)
82  - scst_vdisk - device handler for virtual disks (file, device or ISO CD image).
83  - scst_user - user space device handler
84
85 Then, to see your devices remotely, you need to add them to at least
86 "Default" security group (see below how). By default, no local devices
87 are seen remotely. There must be LUN 0 in each security group, i.e. LUs
88 numeration must not start from, e.g., 1.
89
90 IMPORTANT: Without loading appropriate device handler, corresponding devices
91 =========  will be invisible for remote initiators, which could lead to holes
92            in the LUN addressing, so automatic device scanning by remote SCSI 
93            mid-level could not notice the devices. Therefore you will have 
94            to add them manually via 
95            'echo "scsi add-single-device A 0 0 B" >/proc/scsi/scsi',
96            where A - is the host number, B - LUN.
97
98 IMPORTANT: Experience shows that if people work with out of SCST tree target
99 =========  drivers, like target driver for Infiniband or in case if they
100            downloaded and use the released versions of SCST and target
101            drivers, they are too often (actually, almost always) after
102            upgrading SCST core forget to rebuild their target drivers,
103            which then immediately after load crash in the hard to trace
104            manner. So, after you reinstalled SCST core don't forget to
105            rebuild and reinstall all your target drivers, custom dev
106            handlers and necessary user space applications.
107
108 IMPORTANT: In the current version simultaneous access to local SCSI devices
109 =========  via standard high-level SCSI drivers (sd, st, sg, etc.) and
110            SCST's target drivers is unsupported. Especially it is
111            important for execution via sg and st commands that change
112            the state of devices and their parameters, because that could
113            lead to data corruption. If any such command is done, at
114            least related device handler(s) must be restarted. For block
115            devices READ/WRITE commands using direct disk handler look to
116            be safe.
117
118 To uninstall, type 'make scst_uninstall'.
119
120 If you install QLA2x00 target driver's source code in this directory,
121 then you can build, install or uninstall it by typing 'make qla', 'make
122 qla_install' or 'make qla_uninstall' correspondingly. For more details
123 about QLA2x00 target drivers see their README files.
124
125 Device handlers
126 ---------------
127
128 Device specific drivers (device handlers) are plugins for SCST, which
129 help SCST to analyze incoming requests and determine parameters,
130 specific to various types of devices. If an appropriate device handler
131 for a SCSI device type isn't loaded, SCST doesn't know how to handle
132 devices of this type, so they will be invisible for remote initiators
133 (more precisely, "LUN not supported" sense code will be returned).
134
135 In addition to device handlers for real devices, there are VDISK, user
136 space and "performance" device handlers.
137
138 VDISK device handler works over files on file systems and makes from
139 them virtual remotely available SCSI disks or CDROM's. In addition, it
140 allows to work directly over a block device, e.g. local IDE or SCSI disk
141 or ever disk partition, where there is no file systems overhead. Using
142 block devices comparing to sending SCSI commands directly to SCSI
143 mid-level via scsi_do_req()/scsi_execute_async() has advantage that data
144 are transferred via system cache, so it is possible to fully benefit from
145 caching and read ahead performed by Linux's VM subsystem. The only
146 disadvantage here that in the FILEIO mode there is superfluous data
147 copying between the cache and SCST's buffers. This issue is going to be
148 addressed in the next release. Virtual CDROM's are useful for remote
149 installation. See below for details how to setup and use VDISK device
150 handler.
151
152 SCST user space device handler provides an interface between SCST and
153 the user space, which allows to create pure user space devices. The
154 simplest example, where one would want it is if he/she wants to write a
155 VTL. With scst_user he/she can write it purely in the user space. Or one
156 would want it if he/she needs some sophisticated for kernel space
157 processing of the passed data, like encrypting them or making snapshots. 
158
159 "Performance" device handlers for disks, MO disks and tapes in their
160 exec() method skip (pretend to execute) all READ and WRITE operations
161 and thus provide a way for direct link performance measurements without
162 overhead of actual data transferring from/to underlying SCSI device.
163
164 NOTE: Since "perf" device handlers on READ operations don't touch the
165 ====  commands' data buffer, it is returned to remote initiators as it
166       was allocated, without even being zeroed. Thus, "perf" device
167       handlers impose some security risk, so use them with caution.
168
169 Compilation options
170 -------------------
171
172 There are the following compilation options, that could be commented
173 in/out in Makefile:
174
175  - DEBUG - if defined, turns on some debugging code, including some
176    logging. Makes the driver considerably bigger and slower, producing
177    large amount of log data.
178
179  - TRACING - if defined, turns on ability to log events. Makes the
180    driver considerably bigger and lead to some performance loss.
181
182  - EXTRACHECKS - if defined, adds extra validity checks in the various
183    places.
184
185  - USE_EXPECTED_VALUES - if not defined (default), initiator supplied
186    expected data transfer length and direction will be used only for
187    verification purposes to return error or warn in case if one of them
188    is invalid. Instead, locally decoded from SCSI command values will be
189    used. This is necessary for security reasons, because otherwise a
190    faulty initiator can crash target by supplying invalid value in one
191    of those parameters. This is especially important in case of
192    pass-through mode. If USE_EXPECTED_VALUES is defined, initiator
193    supplied expected data transfer length and direction will override
194    the locally decoded values. This might be necessary if internal SCST
195    commands translation table doesn't contain SCSI command, which is
196    used in your environment. You can know that if you have messages like
197    "Unknown opcode XX for YY. Should you update scst_scsi_op_table?" in
198    your kernel log and your initiator returns an error. Also report
199    those messages in the SCST mailing list
200    scst-devel@lists.sourceforge.net. Note, that not all SCSI transports
201    support supplying expected values.
202
203  - DEBUG_TM - if defined, turns on task management functions debugging,
204    when on LUN 0 in the default access control group some of the
205    commands will be delayed for about 60 sec., so making the remote
206    initiator send TM functions, eg ABORT TASK and TARGET RESET. Also
207    define TM_DBG_GO_OFFLINE symbol in the Makefile to 1 if you want that
208    the device eventually become completely unresponsive, or to 0
209    otherwise to circle around ABORTs and RESETs code. Needs DEBUG turned
210    on.
211
212  - STRICT_SERIALIZING - if defined, makes SCST send all commands to
213    underlying SCSI device synchronously, one after one. This makes task
214    management more reliable, with cost of some performance penalty. This
215    is mostly actual for stateful SCSI devices like tapes, where the
216    result of command's execution depends from device's settings defined
217    by previous commands. Disk and RAID devices are stateless in the most
218    cases. The current SCSI core in Linux doesn't allow to abort all
219    commands reliably if they sent asynchronously to a stateful device.
220    Turned off by default, turn it on if you use stateful device(s) and
221    need as much error recovery reliability as possible. As a side
222    effect, no kernel patching is necessary.
223
224  - ALLOW_PASSTHROUGH_IO_SUBMIT_IN_SIRQ - if defined, it will be allowed
225    to submit pass-through commands to real SCSI devices via the SCSI
226    middle layer using scsi_execute_async() function from soft IRQ
227    context (tasklets). This used to be the default, but currently it
228    seems the SCSI middle layer starts expecting only thread context on
229    the IO submit path, so it is disabled now by default. Enabling it
230    will decrease amount of context switches and improve performance. It
231    is more or less safe, in the worst case, if in your configuration the
232    SCSI middle layer really doesn't expect SIRQ context in
233    scsi_execute_async() function, you will get a warning message in the
234    kernel log.
235
236  - SCST_HIGHMEM - if defined on HIGHMEM systems with 2.6 kernels, it
237    allows SCST to use HIGHMEM. This is very experimental feature, which
238    is currently broken and unsupported, since it is unclear, if it
239    brings something valuable, except some performance hit. Note, that
240    SCST_HIGHMEM isn't required for HIGHMEM systems and SCST will work
241    fine on them with SCST_HIGHMEM off.
242   
243  - SCST_STRICT_SECURITY - if defined, makes SCST zero allocated data
244    buffers. Undefining it (default) considerably improves performance
245    and eases CPU load, but could create a security hole (information
246    leakage), so enable it, if you have strict security requirements.
247
248 HIGHMEM kernel configurations are fully supported, but not recommended
249 for performance reasons, except for scst_user, where they are not
250 supported, because this module deals with user supplied memory on a
251 zero-copy manner. If you need to use it, consider change VMSPLIT option
252 or use 64-bit system configuration instead.
253
254 For changing VMSPLIT option (CONFIG_VMSPLIT to be precise) you should in
255 "make menuconfig" command set the following variables:
256
257  - General setup->Configure standard kernel features (for small systems): ON
258
259  - Processor type and features->High Memory Support: OFF
260
261  - Processor type and features->Memory split: according to amount of
262    memory you have. If it is less than 800MB, you may not touch this
263    option at all.
264
265 Module parameters
266 -----------------
267
268 Module scst supports the following parameters:
269
270  - scst_threads - allows to set count of SCST's threads. By default it
271    is CPU count.
272
273  - scst_max_cmd_mem - sets maximum amount of memory in Mb allowed to be
274    consumed by the SCST commands for data buffers at any given time. By
275    default it is approximately TotalMem/4.
276
277 SCST "/proc" commands
278 ---------------------
279
280 For communications with user space programs SCST provides proc-based
281 interface in "/proc/scsi_tgt" directory. It contains the following
282 entries:
283
284   - "help" file, which provides online help for SCST commands
285   
286   - "scsi_tgt" file, which on read provides information of serving by SCST
287     devices and their dev handlers. On write it supports the following
288     command:
289     
290       * "assign H:C:I:L HANDLER_NAME" assigns dev handler "HANDLER_NAME" 
291         on device with host:channel:id:lun
292
293   - "sessions" file, which lists currently connected initiators (open sessions)
294
295   - "sgv" file provides some statistic about with which block sizes
296     commands from remote initiators come and how effective sgv_pool in
297     serving those allocations from the cache, i.e. without memory
298     allocations requests to the kernel. "Size" - is the commands data
299     size upper rounded to power of 2, "Hit" - how many there are
300     allocations from the cache, "Total" - total number of allocations.
301         
302   - "threads" file, which allows to read and set number of SCST's threads
303   
304   - "version" file, which shows version of SCST
305   
306   - "trace_level" file, which allows to read and set trace (logging) level
307     for SCST. See "help" file for list of trace levels.
308
309 Each dev handler has own subdirectory. Most dev handler have only two
310 files in this subdirectory: "trace_level" and "type". The first one is
311 similar to main SCST "trace_level" file, the latter one shows SCSI type
312 number of this handler as well as some text description.
313
314 For example, "echo "assign 1:0:1:0 dev_disk" >/proc/scsi_tgt/scsi_tgt"
315 will assign device handler "dev_disk" to real device sitting on host 1,
316 channel 0, ID 1, LUN 0.
317
318 Access and devices visibility management (LUN masking)
319 ------------------------------------------------------
320
321 Access and devices visibility management allows for an initiator or
322 group of initiators to have different limited set of LUs/LUNs (security
323 group) each with appropriate access permissions. Initiator is
324 represented as a SCST session. Session is bound to security group on its
325 registration time by character "name" parameter of the registration
326 function, which provided by target driver, based on its internal
327 authentication. For example, for FC "name" could be WWN or just loop ID.
328 For iSCSI this could be iSCSI login credentials or iSCSI initiator name.
329 Each security group has set of names assigned to it by system
330 administrator. Session is bound to security group with provided name. If
331 no such groups found, the session bound to either "Default_target_name",
332 or "Default" group, depending from either "Default_target_name" exists
333 or not. In "Default_target_name" target name means name of the target.
334
335 In /proc/scsi_tgt each group represented as "groups/GROUP_NAME/"
336 subdirectory. In it there are files "devices" and "users". File
337 "devices" lists all devices and their LUNs in the group, file "users"
338 lists all names that should be bound to this group.
339
340 To configure access and devices visibility management SCST provides the
341 following files and directories under /proc/scsi_tgt:
342
343   - "add_group GROUP" to /proc/scsi_tgt/scsi_tgt adds group "GROUP"
344   
345   - "del_group GROUP" to /proc/scsi_tgt/scsi_tgt deletes group "GROUP"
346   
347   - "add H:C:I:L lun [READ_ONLY]" to /proc/scsi_tgt/groups/GROUP/devices adds 
348     device with host:channel:id:lun as LUN "lun" in group "GROUP". Optionally,
349     the device could be marked as read only.
350   
351   - "del H:C:I:L" to /proc/scsi_tgt/groups/GROUP/devices deletes device with
352     host:channel:id:lun from group "GROUP"
353   
354   - "add V_NAME lun [READ_ONLY]" to /proc/scsi_tgt/groups/GROUP/devices adds
355     device with virtual name "V_NAME" as LUN "lun" in group "GROUP".
356     Optionally, the device could be marked as read only.
357   
358   - "del V_NAME" to /proc/scsi_tgt/groups/GROUP/devices deletes device with
359     virtual name "V_NAME" from group "GROUP"
360   
361   - "clear" to /proc/scsi_tgt/groups/GROUP/devices clears the list of devices
362     for group "GROUP"
363   
364   - "add NAME" to /proc/scsi_tgt/groups/GROUP/names adds name "NAME" to group 
365     "GROUP"
366   
367   - "del NAME" to /proc/scsi_tgt/groups/GROUP/names deletes name "NAME" from group 
368     "GROUP"
369   
370   - "clear" to /proc/scsi_tgt/groups/GROUP/names clears the list of names
371     for group "GROUP"
372
373 Examples:
374
375  - "echo "add 1:0:1:0 0" >/proc/scsi_tgt/groups/Default/devices" will
376  add real device sitting on host 1, channel 0, ID 1, LUN 0 to "Default"
377  group with LUN 0.
378
379  - "echo "add disk1 1" >/proc/scsi_tgt/groups/Default/devices" will
380  add virtual VDISK device with name "disk1" to "Default" group
381  with LUN 1. 
382
383 VDISK device handler
384 --------------------
385
386 After loading VDISK device handler creates in "/proc/scsi_tgt/"
387 subdirectories "vdisk" and "vcdrom". They have similar layout:
388
389   - "trace_level" and "type" files as described for other dev handlers
390   
391   - "help" file, which provides online help for VDISK commands
392   
393   - "vdisk"/"vcdrom" files, which on read provides information of
394     currently open device files. On write it supports the following
395     command:
396     
397     * "open NAME [PATH] [BLOCK_SIZE] [FLAGS]" - opens file "PATH" as
398       device "NAME" with block size "BLOCK_SIZE" bytes with flags
399       "FLAGS". "PATH" could be empty only for VDISK CDROM. "BLOCK_SIZE"
400       and "FLAGS" are valid only for disk VDISK. The block size must be
401       power of 2 and >= 512 bytes. Default is 512. Possible flags:
402       
403       - WRITE_THROUGH - write back caching disabled
404       
405       - READ_ONLY - read only
406       
407       - O_DIRECT - both read and write caching disabled. This mode
408         isn't currently fully implemented, you should use user space
409         fileio_tgt program in O_DIRECT mode instead (see below).
410
411       - NULLIO - in this mode no real IO will be done, but success will be
412         returned. Intended to be used for performance measurements at the same
413         way as "*_perf" handlers.
414
415       - NV_CACHE - enables "non-volatile cache" mode. In this mode it is
416         assumed that the target has GOOD UPS and software/hardware bug
417         free, i.e. all data from the target's cache are guaranteed
418         sooner or later to go to the media, hence all data
419         synchronization with media operations, like SYNCHRONIZE_CACHE,
420         are ignored (BTW, so violating SCSI standard) in order to bring
421         a bit more performance. Use with extreme caution, since in this
422         mode after a crash of the target journaled file systems don't
423         guarantee the consistency after journal recovery, therefore
424         manual fsck MUST be ran. The main intent for it is to determine
425         the performance impact caused by the cache synchronization.
426         Note, that since usually the journal barrier protection (see
427         "IMPORTANT" below) turned off, enabling NV_CACHE could change
428         nothing, since no data synchronization with media operations
429         will go from the initiator.
430
431       - BLOCKIO - enables block mode, which will perform direct block
432         IO with a block device, bypassing page-cache for all operations.
433         This mode works ideally with high-end storage HBAs and for
434         applications that either do not need caching between application
435         and disk or need the large block throughput. See also below.
436     
437     * "close NAME" - closes device "NAME".
438
439     * "change NAME [PATH]" - changes a virtual CD in the VDISK CDROM.
440
441 For example, "echo "open disk1 /vdisks/disk1" >/proc/scsi_tgt/vdisk/vdisk"
442 will open file /vdisks/disk1 as virtual VDISK disk with name "disk1".
443
444 IMPORTANT: By default for performance reasons VDISK FILEIO devices use write
445 =========  back caching policy. This is generally safe from the consistence of
446            journaled file systems, laying over them, point of view, but
447            your unsaved cached data will be lost in case of
448            power/hardware/software failure, so you must supply your
449            target server with some kind of UPS or disable write back
450            caching using WRITE_THROUGH flag. You also should note, that
451            the file systems journaling over write back caching enabled
452            devices works reliably *ONLY* if the order of journal writes
453            is guaranteed or it uses some kind of data protection
454            barriers (i.e. after writing journal data some kind of
455            synchronization with media operations is used), otherwise,
456            because of possible reordering in the cache, even after
457            successful journal rollback, you very much risk to loose your
458            data on the FS. Currently, Linux IO subsystem guarantees
459            order of write operations only using data protection
460            barriers. Some info about it from the XFS point of view could
461            be found at http://oss.sgi.com/projects/xfs/faq.html#wcache.
462            On Linux initiators for EXT3 and ReiserFS file systems the
463            barrier protection could be turned on using "barrier=1" and
464            "barrier=flush" mount options correspondingly. Note, that
465            usually it turned off by default and the status of barriers
466            usage isn't reported anywhere in the system logs as well as
467            there is no way to know it on the mounted file system (at
468            least no known one). Also note that on some real-life
469            workloads write through caching might perform better, than
470            write back one with the barrier protection turned on.
471
472 IMPORTANT: Some disk and partition table management utilities don't support
473 =========  block sizes >512 bytes, therefore make sure that your favorite one
474            supports it. Currently only cfdisk is known to work only with
475            512 bytes blocks, other utilities like fdisk on Linux or
476            standard disk manager on Windows are proved to work well with
477            non-512 bytes blocks. Note, if you export a disk file or
478            device with some block size, different from one, with which
479            it was already partitioned, you could get various weird
480            things like utilities hang up or other unexpected behavior.
481            Hence, to be sure, zero the exported file or device before
482            the first access to it from the remote initiator with another
483            block size. On Window initiator make sure you "Set Signature"
484            in the disk manager on the imported from the target drive
485            before doing any other partitioning on it. After you
486            successfully mounted a file system over non-512 bytes block
487            size device, the block size stops matter, any program will
488            work with files on such file system.
489
490 BLOCKIO VDISK mode
491 ------------------
492
493 This module works best for these types of scenarios:
494
495 1) Data that are not aligned to 4K sector boundaries and <4K block sizes
496 are used, which is normally found in virtualization environments where
497 operating systems start partitions on odd sectors (Windows and it's
498 sector 63).
499
500 2) Large block data transfers normally found in database loads/dumps and
501 streaming media.
502
503 3) Advanced relational database systems that perform their own caching
504 which prefer or demand direct IO access and, because of the nature of
505 their data access, can actually see worse performance with
506 non-discriminate caching.
507
508 4) Multiple layers of targets were the secondary and above layers need
509 to have a consistent view of the primary targets in order to preserve
510 data integrity which a page cache backed IO type might not provide
511 reliably.
512
513 Also it has an advantage over FILEIO that it doesn't copy data between
514 the system cache and the commands data buffers, so it saves a
515 considerable amount of CPU power and memory bandwidth.
516
517 IMPORTANT: Since data in BLOCKIO and FILEIO modes are not consistent between
518 =========  them, if you try to use a device in both those modes simultaneously,
519            you will almost instantly corrupt your data on that device.
520
521 Pass-through mode
522 -----------------
523
524 In the pass-through mode (i.e. using the pass-through device handlers
525 scst_disk, scst_tape, etc) SCSI commands, coming from remote initiators,
526 are passed to local SCSI hardware on target as is, without any
527 modifications. As any other hardware, the local SCSI hardware can not
528 handle commands with amount of data and/or segments count in
529 scatter-gather array bigger some values. Therefore, when using the
530 pass-through mode you should note that values for maximum number of
531 segments and maximum amount of transferred data for each SCSI command on
532 devices on initiators can not be bigger, than corresponding values of
533 the corresponding SCSI devices on the target. Otherwise you will see
534 symptoms like small transfers work well, but large ones stall and
535 messages like: "Unable to complete command due to SG IO count
536 limitation" are printed in the kernel logs.
537
538 You can't control from the user space limit of the scatter-gather
539 segments, but for block devices usually it is sufficient if you set on
540 the initiators /sys/block/DEVICE_NAME/queue/max_sectors_kb in the same
541 or lower value as in /sys/block/DEVICE_NAME/queue/max_hw_sectors_kb for
542 the corresponding devices on the target.
543
544 For not-block devices SCSI commands are usually generated directly by
545 applications, so, if you experience large transfers stalls, you should
546 check documentation for your application how to limit the transfer
547 sizes.
548
549 User space mode using scst_user dev handler
550 -------------------------------------------
551
552 User space program fileio_tgt uses interface of scst_user dev handler
553 and allows to see how it works in various modes. Fileio_tgt provides
554 mostly the same functionality as scst_vdisk handler with the most
555 noticeable difference that it supports O_DIRECT mode. O_DIRECT mode is
556 basically the same as BLOCKIO, but also supports files, so for some
557 loads it could be significantly faster, than the regular FILEIO access.
558 All the words about BLOCKIO from above apply to O_DIRECT as well. See
559 fileio_tgt's README file for more details.
560
561 Performance
562 -----------
563
564 Before doing any performance measurements note that:
565
566 I. Performance results are very much dependent from your type of load,
567 so it is crucial that you choose access mode (FILEIO, BLOCKIO,
568 O_DIRECT, pass-through), which suits your needs the best.
569
570 II. In order to get the maximum performance you should:
571
572 1. For SCST:
573
574  - Disable in Makefile STRICT_SERIALIZING, EXTRACHECKS, TRACING, DEBUG*,
575    SCST_STRICT_SECURITY, SCST_HIGHMEM
576
577  - For pass-through devices enable ALLOW_PASSTHROUGH_IO_SUBMIT_IN_SIRQ.
578
579 2. For target drivers:
580
581  - Disable in Makefiles EXTRACHECKS, TRACING, DEBUG*
582
583 3. For device handlers, including VDISK:
584
585  - Disable in Makefile TRACING, DEBUG
586
587  - If your initiator(s) use dedicated exported from the target virtual
588    SCSI devices and have more or equal amount of memory, than the
589    target, it is recommended to use O_DIRECT option (currently it is
590    available only with fileio_tgt user space program) or BLOCKIO. With
591    them you could have up to 100% increase in throughput.
592
593 IMPORTANT: Some of the compilation options enabled by default, i.e. SCST
594 =========  is optimized currently rather for development and bug hunting,
595            than for performance.
596
597 If you use SCST version taken directly from its SVN repository, you can
598 set the above options, except ALLOW_PASSTHROUGH_IO_SUBMIT_IN_SIRQ, using
599 debug2perf script file.
600
601 4. For kernel:
602
603  - Don't enable debug/hacking features, i.e. use them as they are by
604    default.
605
606  - The default kernel read-ahead and queuing settings are optimized
607    for locally attached disks, therefore they are not optimal if they
608    attached remotely (SCSI target case), which sometimes could lead to
609    unexpectedly low throughput. You should increase read-ahead size to at
610    least 512KB or even more on all initiators and the target.
611    
612    You should also limit on all initiators maximum amount of sectors per
613    SCSI command. To do it on Linux initiators, run:
614   
615    echo “64” > /sys/block/sdX/queue/max_sectors_kb
616
617    where specify instead of X your imported from target device letter,
618    like 'b', i.e. sdb.
619
620    To increase read-ahead size on Linux, run:
621   
622    blockdev --setra N /dev/sdX
623
624    where N is a read-ahead number in 512-byte sectors and X is a device
625    letter like above.
626
627    Note: you need to set read-ahead setting for device sdX again after
628    you changed the maximum amount of sectors per SCSI command for that
629    device.
630
631  - You may need to increase amount of requests that OS on initiator
632    sends to the target device. To do it on Linux initiators, run
633
634    echo “64” > /sys/block/sdX/queue/nr_requests
635
636    where X is a device letter like above.
637
638    You may also experiment with other parameters in /sys/block/sdX
639    directory, they also affect performance. If you find the best values,
640    please share them with us.
641
642  - Use on the target deadline IO scheduler with read_expire and
643    write_expire increased on all exported devices to 5000 and 20000
644    correspondingly.
645
646  - It is recommended to turn the kernel preemption off, i.e. set
647    the kernel preemption model to "No Forced Preemption (Server)".
648
649 5. For hardware.
650
651  - Make sure that your target hardware (e.g. target FC card) and underlaying
652    IO hardware (e.g. IO card, like SATA, SCSI or RAID to which your
653    disks connected) stay on different PCI buses. They have to work in
654    parallel, so it will be better if they don't compete for the bus. The
655    problem is not only in the bandwidth, which they have to share, but
656    also in the interaction between cards during that competition. In
657    some cases it could lead up to 5-10 times less performance, than
658    expected.
659
660 IMPORTANT: If you use on initiator some versions of Windows (at least W2K)
661 =========  you can't get good write performance for VDISK FILEIO devices with
662            default 512 bytes block sizes. You could get about 10% of the
663            expected one. This is because of partition alignment, which
664            is (simplifying) incompatible with how Linux page cache
665            works, so for each write the corresponding block must be read
666            first. Use 4096 bytes block sizes for VDISK devices and you
667            will have the expected write performance. Actually, any OS on
668            initiators, not only Windows, will benefit from block size
669            max(PAGE_SIZE, BLOCK_SIZE_ON_UNDERLYING_FS), where PAGE_SIZE
670            is the page size, BLOCK_SIZE_ON_UNDERLYING_FS is block size
671            on the underlying FS, on which the device file located, or 0,
672            if a device node is used. Both values are from the target.
673            See also important notes about setting block sizes >512 bytes
674            for VDISK FILEIO devices above.
675
676 Credits
677 -------
678
679 Thanks to:
680
681  * Mark Buechler <mark.buechler@gmail.com> for a lot of useful
682    suggestions, bug reports and help in debugging.
683
684  * Ming Zhang <mingz@ele.uri.edu> for fixes and comments.
685  
686  * Nathaniel Clark <nate@misrule.us> for fixes and comments.
687
688  * Calvin Morrow <calvin.morrow@comcast.net> for testing and useful
689    suggestions.
690
691  * Hu Gang <hugang@soulinfo.com> for the original version of the
692    LSI target driver.
693
694  * Erik Habbinga <erikhabbinga@inphase-tech.com> for fixes and support
695    of the LSI target driver.
696
697  * Ross S. W. Walker <rswwalker@hotmail.com> for the original block IO
698    code and Vu Pham <huongvp@yahoo.com> who updated it for the VDISK dev
699    handler.
700
701  * Michael G. Byrnes <michael.byrnes@hp.com> for fixes.
702
703  * Alessandro Premoli <a.premoli@andxor.it> for fixes
704
705  * Nathan Bullock <nbullock@yottayotta.com> for fixes.
706
707  * Terry Greeniaus <tgreeniaus@yottayotta.com> for fixes.
708
709  * Krzysztof Blaszkowski <kb@sysmikro.com.pl> for many fixes and bug reports.
710
711  * Jianxi Chen <pacers@users.sourceforge.net> for fixing problem with
712    devices >2TB in size
713
714 Vladislav Bolkhovitin <vst@vlnb.net>, http://scst.sourceforge.net