This patch contains documentation for iSCSI-SCST. Signed-off-by: Vladislav Bolkhovitin <vst@xxxxxxxx> --- 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@xxxxxxxxx> for fixes + + * Krzysztof Blaszkowski <kb@xxxxxxxxxxxxxxx> for many fixes + + * Alexey Kuznetsov <kuznet@xxxxxxxxxxxxx> for comments and help in + debugging + + * Tomasz Chmielewski <mangoo@xxxxxxxx> for testing and suggestions + + * Bart Van Assche <bart.vanassche@xxxxxxxxx> for a lot of help + +Vladislav Bolkhovitin <vst@xxxxxxxx>, http://scst.sourceforge.net -- To unsubscribe from this list: send the line "unsubscribe linux-scsi" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
