From: Vladislav Bolkhovitin <vst@vlnb•net>
To: linux-scsi@vger•kernel.org
Cc: James Bottomley <James.Bottomley@HansenPartnership•com>,
Andrew Morton <akpm@linux-foundation•org>,
FUJITA Tomonori <fujita.tomonori@lab•ntt.co.jp>,
Mike Christie <michaelc@cs•wisc.edu>,
Jeff Garzik <jeff@garzik•org>,
Boaz Harrosh <bharrosh@panasas•com>,
Linus Torvalds <torvalds@linux-foundation•org>,
linux-kernel@vger•kernel.org, scst-devel@lists•sourceforge.net,
Bart Van Assche <bart.vanassche@gmail•com>,
"Nicholas A. Bellinger" <nab@linux-iscsi•org>,
netdev@vger•kernel.org
Subject: [PATCH][RFC 22/23]: Documentation for iSCSI-SCST
Date: Wed, 10 Dec 2008 22:02:56 +0300 [thread overview]
Message-ID: <49401260.5050501@vlnb.net> (raw)
In-Reply-To: <494009D7.4020602@vlnb.net>
This patch contains documentation for iSCSI-SCST.
Signed-off-by: Vladislav Bolkhovitin <vst@vlnb•net>
---
Documentation/scst/README.iscsi | 127 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 127 insertions(+)
diff -uprN orig/linux-2.6.27/Documentation/scst/README.iscsi linux-2.6.27/Documentation/scst/README.iscsi
--- orig/linux-2.6.27/Documentation/scst/README.iscsi
+++ linux-2.6.27/Documentation/scst/README.iscsi
@@ -0,0 +1,127 @@
+iSCSI SCST target driver
+========================
+
+Version 1.0.1/0.4.16r155, XX XXXX 2008
+--------------------------------------
+
+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
+
+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.
+For that you should enable CONFIG_TCP_ZERO_COPY_TRANSFER_COMPLETION_NOTIFICATION
+kernel config option. This is highly recommended, but not required. Basically,
+you should consider usage of this option 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.
+
+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. It is highly recommended to use scstadmin utility for
+that purpose. 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.
+
+
+Performance advices
+-------------------
+
+1. If you use Windows XP or Windows 2003+ as initiators, you should
+consider to decrease TcpAckFrequency parameter to 1. See
+http://support.microsoft.com/kb/328890/ or google for "TcpAckFrequency"
+for more details.
+
+
+Compilation options
+-------------------
+
+There are the following compilation options, that could be commented
+in/out in the kernel's module Makefile:
+
+ - CONFIG_SCST_DEBUG - turns on some debugging code, including some logging.
+ Makes the driver considerably bigger and slower, producing large amount of
+ log data.
+
+ - CONFIG_SCST_TRACING - turns on ability to log events. Makes the driver
+ considerably bigger and leads to some performance loss.
+
+ - CONFIG_SCST_EXTRACHECKS - adds extra validity checks in the various places.
+
+ - CONFIG_SCST_ISCSI_DEBUG_DIGEST_FAILURES - simulates digest failures in
+ random places.
+
+
+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
next prev parent reply other threads:[~2008-12-10 19:03 UTC|newest]
Thread overview: 52+ messages / expand[flat|nested] mbox.gz Atom feed top
2008-12-10 18:26 [PATCH][RFC 0/23] New SCSI target framework (SCST) and 4 target drivers Vladislav Bolkhovitin
2008-12-10 19:01 ` [PATCH][RFC 21/23]: iSCSI target driver Vladislav Bolkhovitin
2008-12-11 22:55 ` Nicholas A. Bellinger
2008-12-11 22:59 ` Nicholas A. Bellinger
2008-12-12 19:26 ` Vladislav Bolkhovitin
2008-12-10 19:02 ` Vladislav Bolkhovitin [this message]
2008-12-10 19:04 ` [PATCH][RFC 23/23]: Support for zero-copy TCP transmit of user space data Vladislav Bolkhovitin
2008-12-10 21:45 ` Evgeniy Polyakov
2008-12-11 18:16 ` Vladislav Bolkhovitin
2008-12-11 19:12 ` James Bottomley
2008-12-12 19:25 ` Vladislav Bolkhovitin
2008-12-12 19:37 ` James Bottomley
2008-12-15 17:58 ` Vladislav Bolkhovitin
2008-12-15 23:18 ` Christoph Hellwig
2008-12-16 18:57 ` Vladislav Bolkhovitin
2008-12-18 18:35 ` [RFC]: " Vladislav Bolkhovitin
2008-12-18 18:43 ` David M. Lloyd
2008-12-19 17:37 ` Vladislav Bolkhovitin
2008-12-19 19:07 ` Jens Axboe
2008-12-19 19:17 ` Vladislav Bolkhovitin
2008-12-19 19:27 ` Jens Axboe
2008-12-19 21:58 ` Evgeniy Polyakov
2008-12-23 19:11 ` Vladislav Bolkhovitin
2008-12-19 11:27 ` Andi Kleen
2008-12-19 17:38 ` Vladislav Bolkhovitin
2008-12-19 18:00 ` Andi Kleen
2008-12-19 17:57 ` Vladislav Bolkhovitin
2008-12-16 16:00 ` [PATCH][RFC 23/23]: " Bart Van Assche
2008-12-16 17:41 ` Evgeniy Polyakov
2008-12-19 20:21 ` Jeremy Fitzhardinge
2008-12-19 22:04 ` Evgeniy Polyakov
2008-12-19 22:21 ` Jeremy Fitzhardinge
2008-12-19 22:33 ` Evgeniy Polyakov
2008-12-20 1:56 ` Jeremy Fitzhardinge
2008-12-20 2:02 ` Herbert Xu
2008-12-20 6:14 ` Jeremy Fitzhardinge
2008-12-20 6:51 ` Herbert Xu
2008-12-20 7:43 ` Jeremy Fitzhardinge
2008-12-20 8:10 ` Herbert Xu
2008-12-20 10:32 ` Evgeniy Polyakov
2008-12-20 19:39 ` Jeremy Fitzhardinge
2008-12-22 0:43 ` Rusty Russell
2008-12-23 19:14 ` Vladislav Bolkhovitin
2008-12-23 19:16 ` Vladislav Bolkhovitin
2008-12-23 21:38 ` Evgeniy Polyakov
2008-12-24 14:37 ` Vladislav Bolkhovitin
2008-12-24 14:44 ` Evgeniy Polyakov
2008-12-24 17:46 ` Vladislav Bolkhovitin
2008-12-24 18:08 ` Evgeniy Polyakov
2008-12-30 17:37 ` Vladislav Bolkhovitin
2008-12-30 21:35 ` Evgeniy Polyakov
2008-12-23 19:13 ` Vladislav Bolkhovitin
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=49401260.5050501@vlnb.net \
--to=vst@vlnb$(echo .)net \
--cc=James.Bottomley@HansenPartnership$(echo .)com \
--cc=akpm@linux-foundation$(echo .)org \
--cc=bart.vanassche@gmail$(echo .)com \
--cc=bharrosh@panasas$(echo .)com \
--cc=fujita.tomonori@lab$(echo .)ntt.co.jp \
--cc=jeff@garzik$(echo .)org \
--cc=linux-kernel@vger$(echo .)kernel.org \
--cc=linux-scsi@vger$(echo .)kernel.org \
--cc=michaelc@cs$(echo .)wisc.edu \
--cc=nab@linux-iscsi$(echo .)org \
--cc=netdev@vger$(echo .)kernel.org \
--cc=scst-devel@lists$(echo .)sourceforge.net \
--cc=torvalds@linux-foundation$(echo .)org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox