mirror of
https://github.com/SCST-project/scst.git
synced 2026-05-17 10:41:26 +00:00
994b72d114
- PRIO queue was removed from scst_user. Instead, all priority commands now queued in the head of the regular queue. The corresponding code was removed from fileio_tgt as well. It necessary, in the future the priority queue can be easily restored from this patch. - pre_unreg_sess() was removed from struct scst_dev_type. The corresponding code was removed from SCST core as well - Almost all /proc/scsi_tgt commands now can fail after timeout (90 seconds) with EBUSY - Fixed possible incorrect command's retry if double RESET UA is detected. - Many minor changes and cleanups Also docs were updated. git-svn-id: http://svn.code.sf.net/p/scst/svn/trunk@403 d57e44dd-8a1f-0410-8b47-8ef2f437770f
206 lines
8.6 KiB
Plaintext
206 lines
8.6 KiB
Plaintext
iSCSI SCST target driver
|
|
========================
|
|
|
|
Version 0.9.6/XXXX, XX XXX 200X
|
|
-------------------------------
|
|
|
|
This driver is a forked with all respects version of iSCSI Enterprise
|
|
Target (IET) (http://iscsitarget.sourceforge.net/) with updates to work
|
|
over SCST as well as with many improvements and bugfixes (see ChangeLog
|
|
file). The reason of fork is that the necessary changes are intrusive
|
|
and with the current IET merge policy, where only simple bugfix-like
|
|
patches, which doesn't touch the core code, could be merged, it is very
|
|
unlikely that they will be merged in the main IET trunk.
|
|
|
|
To let it be installed and work at the same host together with IET
|
|
simultaneously all the driver's modules and files were renamed:
|
|
|
|
* ietd.conf -> iscsi-scstd.conf
|
|
* ietadm -> iscsi-scst-adm
|
|
* ietd -> iscsi-scstd
|
|
* iscsi-target -> iscsi-scst
|
|
* iscsi-target.ko -> iscsi-scst.ko
|
|
|
|
This version is compatible with SCST version 0.9.6 and higher.
|
|
|
|
Tested on 2.6.21.1 kernel, but it should also work on other versions,
|
|
starting from 2.6.16.x.
|
|
|
|
Installation
|
|
------------
|
|
|
|
Basically as in README-IET, where file names are changed as specified
|
|
above.
|
|
|
|
Only vanilla kernels from kernel.org are supported, but it should work
|
|
on vendors' kernels, if you manage to successfully compile on them. The
|
|
main problem with vendor's kernels is that they often contain patches,
|
|
which will appear only in the next version of the vanilla kernel,
|
|
therefore it's quite hard to track such changes. Thus, if during
|
|
compilation for some vendor kernel your compiler complains about
|
|
redefinition of some symbol, you should either switch to vanilla kernel,
|
|
or change as necessary the corresponding to that symbol "#if
|
|
LINUX_VERSION_CODE" statement.
|
|
|
|
If during compilation you see message like "*** No rule to make target
|
|
`xxx.h', needed by `yyy.o'. Stop.", then your autogenerated
|
|
dependencies don't match your compiler configuration anymore. You should
|
|
run "make extraclean" to remove them. On the next compilation they will
|
|
be regenerated.
|
|
|
|
If you experience problems during kernel module load or running, check
|
|
your system and/or kernel logs (or run dmesg command for the few most
|
|
recent kernel messages).
|
|
|
|
To use full power of TCP zero-copy transmit functions, especially
|
|
dealing with user space supplied via scst_user module memory, iSCSI-SCST
|
|
needs to be notified when Linux networking finished data transmission.
|
|
Patch put_page_callback-<kernel-version>.patch provides such
|
|
functionality. The corresponding version of it should be applied on your
|
|
kernel. This is highly recommended, but not required. Basically, you
|
|
should consider using of this patch as some optimization, which IET
|
|
doesn't have, so if you don't use it, you will just revert to the
|
|
original IET behavior, when for data transmission:
|
|
|
|
- For in-kernel allocated memory (scst_vdisk and pass-through
|
|
handlers) usage of SGV cache on transmit path (READ-type commands)
|
|
will be disabled. The performance hit will be not big, but performance
|
|
will still remain better, than for IET, because SGV cache will remain
|
|
used on receive path while IET doesn't have such feature.
|
|
|
|
- For user space allocated memory (scst_user handler) all transmitted
|
|
data will be additionally copied into temporary TCP buffers. The
|
|
performance hit will be quite noticeable.
|
|
|
|
Note, that if your network hardware does not support TX offload
|
|
functions of has them disabled, then TCP zero-copy transmit functions on
|
|
your system will not be used by Linux networking in any case, so
|
|
put_page_callback patch will not be able to improve performance for you.
|
|
You can check your network hardware offload capabilities by command
|
|
"ethtool -k ethX", where X is the network device number. At least
|
|
"tx-checksumming" and "scatter-gather" should be enabled.
|
|
|
|
If you have in your kernel log error messages like:
|
|
|
|
iscsi-scst: ***ERROR*** net_priv isn't NULL and != ref_cmd
|
|
|
|
with the corresponding kernel BUG dump, then put_page_callback patch you
|
|
use isn't sufficient for your kernel. This might be because the kernel
|
|
you use has some additional patches applied, which affect the
|
|
functionality, which put_page_callback patch provides. For example,
|
|
Fedora or Gentoo use kernels, which, although have version number like
|
|
2.6.18, are greatly differ from the "vanilla" kernel 2.6.18,
|
|
maintained by Linus Torvalds for that the put_page_callback patch was
|
|
created. In this case I would recommend you either:
|
|
|
|
- Search net/ in your kernel source for "put_page" and "get_page" functions.
|
|
If you find any in some place, except in net/sunrpc/svc.c and
|
|
net/core/pktgen.c, then, most likely, you found the reason of your
|
|
problem. Replace them by "net_put_page" and "net_get_page"
|
|
correspondingly and try again. If the problem is solved, then please
|
|
prepare a new put_page_callback patch and send it to the SCST mailing
|
|
list scst-devel@lists.sourceforge.net.
|
|
|
|
or
|
|
|
|
- Unapply this patch and use iSCSI-SCST without it. Also report this
|
|
problem to the SCST mailing list scst-devel@lists.sourceforge.net.
|
|
|
|
Usage
|
|
-----
|
|
|
|
ISCSI parameters like iSNS, CHAP and target parameters are configured in
|
|
iscsi-scstd.conf. All LUN information is configured using the regular
|
|
SCST interface. The LUN information in iscsi-scstd.conf will be ignored.
|
|
This is because now responsibilities are divided (as it should be)
|
|
between the target driver (iSCSI-SCST) and the SCST core as it logically
|
|
should be: the target driver is responsible for handling targets and
|
|
their parameters, SCST core is responsible for handling backstorage.
|
|
|
|
If you need to configure different LUs for different targets you should
|
|
create for each target group "Default_target_name", where "target_name"
|
|
means name of the target, for example:
|
|
"Default_iqn.2007-05.com.example:storage.disk1.sys1.xyz", and add there
|
|
all necessary LUNs. Check SCST README file for details.
|
|
|
|
Check SCST README file how to tune for the best performance.
|
|
|
|
If under high load you experience I/O stalls or see in the kernel log
|
|
abort or reset messages, then try to reduce QueuedCommands parameter in
|
|
iscsi-scstd.conf file for the corresponding target to some lower value,
|
|
like 8 (default is 32). See also SCST README file for more details about
|
|
that issue.
|
|
|
|
CAUTION: Working of target and initiator on the same host isn't
|
|
======== supported. See SCST README file for details.
|
|
|
|
Compilation options
|
|
-------------------
|
|
|
|
There are the following compilation options, that could be commented
|
|
in/out in the kernel's module Makefile:
|
|
|
|
- DEBUG - turns on some debugging code, including some logging. Makes
|
|
the driver considerably bigger and slower, producing large amount of
|
|
log data.
|
|
|
|
- TRACING - turns on ability to log events. Makes the driver considerably
|
|
bigger and lead to some performance loss.
|
|
|
|
- EXTRACHECKS - adds extra validity checks in the various places.
|
|
|
|
- DEBUG_DIGEST_FAILURES - simulates digest failures in random places.
|
|
|
|
Known issues
|
|
------------
|
|
|
|
Currently some iscsi-scst-adm functionality is broken. But, from one
|
|
side, at the moment I don't have time to look at it and, from other
|
|
side, in contrast to IET, in iSCSI-SCST this utility doesn't worth much,
|
|
since all devices management is done using SCST's /proc interface.
|
|
What's remained for iscsi-scst-adm is managing iSCSI targets and their
|
|
parameters, but in any case changing of any negotiable iSCSI parameter
|
|
needs renegotiation, i.e. the corresponding session restart, i.e.
|
|
iSCSI-SCST restart. But, if you decide to fix iscsi-scst-adm, I will
|
|
appreciate your patches.
|
|
|
|
Creating version of put_page_callback patch for your kernel
|
|
-----------------------------------------------------------
|
|
|
|
If you need your own version of put_page_callback patch for your custom
|
|
kernel, for which there is no prepared version, you can create it
|
|
yourself. This is pretty mechanical work, you don't need to understand
|
|
how it works, you only need to do the following two steps:
|
|
|
|
1. Apply the closest version of put_page_callback-<kernel-version>.patch
|
|
on your kernel. Resolve only failed hanks from include/ and
|
|
net/core/utils.c, ignore other failures.
|
|
|
|
2. Search net/ in your kernel source for "put_page" and "get_page"
|
|
functions. Replace them by "net_put_page" and "net_get_page"
|
|
correspondingly.
|
|
|
|
That's all. Then please send your new
|
|
put_page_callback-<kernel-version>.patch to the SCST mailing list
|
|
scst-devel@lists.sourceforge.net.
|
|
|
|
Credits
|
|
-------
|
|
|
|
Thanks to:
|
|
|
|
* IET developers for IET
|
|
|
|
* Ming Zhang <blackmagic02881@gmail.com> for fixes
|
|
|
|
* Krzysztof Blaszkowski <kb@sysmikro.com.pl> for many fixes
|
|
|
|
* Alexey Kuznetsov <kuznet@ms2.inr.ac.ru> for comments and help in
|
|
debugging
|
|
|
|
* Tomasz Chmielewski <mangoo@wpkg.org> for testing and suggestions
|
|
|
|
* Bart Van Assche <bart.vanassche@gmail.com> for a lot of help
|
|
|
|
Vladislav Bolkhovitin <vst@vlnb.net>, http://scst.sourceforge.net
|