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