- Fixes build problem in perf mode
[mirror/scst/.git] / iscsi-scst / README
1 iSCSI SCST target driver
2 ========================
3
4 Version 0.9.6/XXXX, XX XXX 200X
5 -------------------------------
6
7 This driver is a forked with all respects version of iSCSI Enterprise
8 Target (IET) (http://iscsitarget.sourceforge.net/) with updates to work
9 over SCST as well as with many improvements and bugfixes (see ChangeLog
10 file). The reason of fork is that the necessary changes are intrusive
11 and with the current IET merge policy, where only simple bugfix-like
12 patches, which doesn't touch the core code, could be merged, it is very
13 unlikely that they will be merged in the main IET trunk.
14
15 To let it be installed and work at the same host together with IET
16 simultaneously all the driver's modules and files were renamed:
17
18  * ietd.conf -> iscsi-scstd.conf
19  * ietadm -> iscsi-scst-adm
20  * ietd -> iscsi-scstd
21  * iscsi-target -> iscsi-scst
22  * iscsi-target.ko -> iscsi-scst.ko
23
24 This version is compatible with SCST version 0.9.6 and higher.
25
26 Tested on 2.6.21.1 kernel, but it should also work on other versions,
27 starting from 2.6.16.x.
28
29 Installation
30 ------------
31
32 Basically as in README-IET, where file names are changed as specified
33 above.
34
35 To use full power of TCP zero-copy transmit functions, especially
36 dealing with user space supplied via scst_user module memory, iSCSI-SCST
37 needs to be notified when Linux networking finished data transmission.
38 Patch put_page_callback-<kernel-version>.patch provides such
39 functionality. The corresponding version of it should be applied on your
40 kernel. This is highly recommended, but not required. Basically, you
41 should consider using of this patch as some optimization, which IET
42 doesn't have, so if you don't use it, you will just revert to the
43 original IET behavior, when for data transmission:
44
45  - For in-kernel allocated memory (scst_vdisk and pass-through
46    handlers) usage of SGV cache on transmit path (READ-type commands)
47    will be disabled. The performance hit will be not big, but performance
48    will still remain better, than for IET, because SGV cache will remain
49    used on receive path and IET doesn't have such feature.
50
51  - For user space allocated memory (scst_user handler) all transmitted
52    data will be additionally copied into temporary TCP buffers. The
53    performance hit will be quite noticeable.
54
55 Note, that if your network hardware does not support TX offload
56 functions of has them disabled, then TCP zero-copy transmit functions on
57 your system will not be used by Linux networking in any case, so
58 put_page_callback patch will not be able to improve performance for you.
59 You can check your network hardware offload capabilities by command
60 "ethtool -k ethX", where X is the network device number. At least
61 "tx-checksumming" and "scatter-gather" should be enabled.
62
63 If you have in your kernel log error messages like:
64
65 iscsi-scst: ***ERROR*** net_priv isn't NULL and != ref_cmd
66
67 with the corresponding kernel BUG dump, then put_page_callback patch you
68 use isn't sufficient for your kernel. This might be because the kernel
69 you use has some additional patches applied, which affect the
70 functionality, which put_page_callback patch provides. For example,
71 Fedora or Gentoo use kernels, which, although have version number like
72 2.6.18, are greatly differ from the "vanilla" kernel 2.6.18,
73 maintained by Linus Torvalds for that the put_page_callback patch was
74 created. In this case I would recommend you either:
75
76  - Search net/ in your kernel source for "put_page" and "get_page" functions.
77    If you find any in some place, except in net/sunrpc/svc.c and
78    net/core/pktgen.c, then, most likely, you found the reason of your
79    problem. Replace them by "net_put_page" and "net_get_page"
80    correspondingly and try again. If the problem is solved, then please
81    prepare a new put_page_callback patch and send it to the SCST mailing
82    list scst-devel@lists.sourceforge.net.
83
84 or
85
86  - Unapply this patch and use iSCSI-SCST without it. Also report this
87    problem to the SCST mailing list scst-devel@lists.sourceforge.net.
88
89 Usage
90 -----
91
92 ISCSI parameters like iSNS, CHAP and target parameters are configured in
93 iscsi-scstd.conf. All LUN information is configured using the regular
94 SCST interface. The LUN information in iscsi-scstd.conf will be ignored.
95 This is because now responsibilities are divided (as it should be)
96 between the target driver (iSCSI-SCST) and the SCST core as it logically
97 should be: the target driver is responsible for handling targets and
98 their parameters, SCST core is responsible for handling backstorage.
99
100 If you need to configure different LUs for different targets you should
101 create for each target group "Default_target_name", where target name
102 means name of the target, for example:
103 "Default_iqn.2007-05.com.example:storage.disk1.sys1.xyz", and add there
104 all necessary LUNs. Check SCST README file for details.
105
106 Compilation options
107 -------------------
108
109 There are the following compilation options, that could be commented
110 in/out in the kernel's module Makefile:
111
112  - DEBUG - turns on some debugging code, including some logging. Makes
113    the driver considerably bigger and slower, producing large amount of
114    log data.
115
116  - TRACING - turns on ability to log events. Makes the driver considerably
117    bigger and lead to some performance loss.
118
119  - EXTRACHECKS - adds extra validity checks in the various places.
120
121  - DEBUG_DIGEST_FAILURES - simulates digest failures in random places.
122
123 Creating version of put_page_callback patch for your kernel
124 -----------------------------------------------------------
125
126 If you need your own version of put_page_callback patch for your custom
127 kernel, for which there is no prepared version, you can create it
128 yourself. This is pretty mechanical work, you don't need to understand
129 how it works, you only need to do the following two steps:
130
131 1. Apply the closest version of put_page_callback-<kernel-version>.patch
132 on your kernel. Resolve only failed hanks from include/ and
133 net/core/utils.c, ignore other failures.
134
135 2. Search net/ in your kernel source for "put_page" and "get_page"
136 functions. Replace them by "net_put_page" and "net_get_page"
137 correspondingly. 
138
139 That's all. Then please send your new
140 put_page_callback-<kernel-version>.patch to the SCST mailing list
141 scst-devel@lists.sourceforge.net.
142
143 Credits
144 -------
145
146 Thanks to:
147
148  * IET developers for IET
149
150  * Ming Zhang <blackmagic02881@gmail.com> for fixes
151
152  * Krzysztof Blaszkowski <kb@sysmikro.com.pl> for many fixes
153
154  * Alexey Kuznetsov <kuznet@ms2.inr.ac.ru> for comments and help in
155    debugging
156
157  * Tomasz Chmielewski <mangoo@wpkg.org> for testing and suggestions
158  
159 Vladislav Bolkhovitin <vst@vlnb.net>, http://scst.sourceforge.net