Small docs update

git-svn-id: http://svn.code.sf.net/p/scst/svn/trunk@589 d57e44dd-8a1f-0410-8b47-8ef2f437770f

iscsi-scst/README

@@ -64,8 +64,9 @@ 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
+kernel. Then you should enable CONFIG_TCP_ZERO_COPY_TRANSFER_COMPLETION_NOTIFICATION
+kernel config option. 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:
 

iscsi-scst/README_in-tree

@@ -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

iscsi-scst/kernel/iscsi.c

@@ -25,7 +25,9 @@
 
 #if !defined(CONFIG_TCP_ZERO_COPY_TRANSFER_COMPLETION_NOTIFICATION)
 #warning "Patch put_page_callback-<kernel-version>.patch not applied on your \
-	kernel. ISCSI-SCST will be working with not the best performance."
+	kernel or CONFIG_TCP_ZERO_COPY_TRANSFER_COMPLETION_NOTIFICATION \
+	config option not set. ISCSI-SCST will be working with not the best \
+	performance. Refer README file for details."
 #endif
 
 #define ISCSI_INIT_WRITE_WAKE		0x1
@@ -2961,9 +2963,10 @@ static int __init iscsi_init(void)
 		goto out_free_dummy;
 	}
 #else
-	PRINT_INFO("%s", "Patch put_page_callback-<kernel-version>.patch "
-		"not applied on your kernel. Running in the performance "
-		"degraded mode. Refer README file for details");
+	PRINT_WARNING("%s",
+		"CONFIG_TCP_ZERO_COPY_TRANSFER_COMPLETION_NOTIFICATION "
+		"not enabled in your kernel. ISCSI-SCST will be working with "
+		"not the best performance. Refer README file for details.");
 #endif
 
 	ctr_major = register_chrdev(0, ctr_name, &ctr_fops);

scripts/generate-kernel-patch

@@ -229,6 +229,7 @@ do
   add_file "${f}" "drivers/scst/iscsi-scst/${f#iscsi-scst/kernel/}"
 done
 
+add_file "iscsi-scst/README_in-tree"               "Documentation/scst/README.iscsi"
 
 # Directory drivers/scst/qla2x00-target/
 

scst/README

@@ -65,6 +65,10 @@ only adds one of those functions and nothing more. You may not patch the
 kernel if you don't need pass-through support or CONFIG_SCST_STRICT_SERIALIZING is
 defined during the compilation (see description below).
 
+Then, to get the maximum performance you should apply export_alloc_io_context
+patch. This patch simply makes alloc_io_context() function be available
+for modules, not only for built-in in kernel code.
+
 To compile SCST type 'make scst'. It will build SCST itself and its
 device handlers. To install them type 'make scst_install'. The driver
 modules will be installed in '/lib/modules/`you_kernel_version`/extra'.

scst/README_in-tree

@@ -671,11 +671,9 @@ using debug2perf Makefile target.
    directory, they also affect performance. If you find the best values,
    please share them with us.
 
- - On the target deadline IO scheduler with read_expire and
-   write_expire increased on all exported devices to 5000 and 15000
-   correspondingly should be the fastest for BLOCKIO, but for FILEIO
-   seems CFQ often outperforms it. So, try on your load and use the best
-   one.
+ - On the target CFQ IO scheduler. In most cases it has performance
+   advantage over other IO schedulers, sometimes huge (2+ times
+   aggregate throughput increase).
 
  - It is recommended to turn the kernel preemption off, i.e. set
    the kernel preemption model to "No Forced Preemption (Server)".

scst/src/scst_main.c

@@ -1693,6 +1693,14 @@ static int __init init_scst(void)
 	BUILD_BUG_ON(SCST_DATA_READ != DMA_FROM_DEVICE);
 	BUILD_BUG_ON(SCST_DATA_NONE != DMA_NONE);
 
+#if LINUX_VERSION_CODE >= KERNEL_VERSION(2, 6, 25)
+#if !defined(SCST_ALLOC_IO_CONTEXT_EXPORTED)
+	PRINT_WARNING("%s", "Patch export_alloc_io_context was not applied on "
+		"your kernel. SCST will be working with not the best "
+		"performance."
+#endif
+#endif
+
 	mutex_init(&scst_mutex);
 	INIT_LIST_HEAD(&scst_template_list);
 	INIT_LIST_HEAD(&scst_dev_list);