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