QLogic 1GB iSCSI TOE Expansion Card for IBM eServer BladeCenter Storage Driver for For Red Hat Linux Advanced Server 4 and SLES 9 Version 5.00.04 QMC4052_2-6LinuxStorageDriver.txt Version 1.01 10/07/05 ________ CONTENTS ________ 1.0 Overview 2.0 Change History 3.0 Installation and Setup Instructions 4.0 Configuration Information 5.0 Known Issues 6.0 Unattended Mode 7.0 Web Sites and Support Phone Number 8.0 Trademarks and Notices 9.0 Disclaimer _______________ 1.0 Overview _______________ This README describes current 2.6 Linux Kernel Storage Driver version for the QLogic 1GB iSCSI TOE Expansion Card and procedure for updating the driver for the expansion card. 1.1 Dependencies: None ____________________ 2.0 Change History ____________________ QLogic iSCSI Expansion Card 2.6 Linux Kernel Storage Driver 5.00.04 ------------------------------------------------------------------- Rev 5.00.04 KH - Released. Rev 5.00.04b8 RA,KH - Replaced hard coded values of minimum command timeout value (25) with #define variable MIN_CMD_TOV. - Removed -fo suffix from drivers in which failover is not actively enabled. - Made x86_64 compilation warning fixes. - Updated debug printing of circular buffer used for connection event log entries. Rev 5.00.04b7test2 RA,KH - Added the logic for assiging timeout value to iocb - Added the checking of ioctl srb's from being added to driver internal queue. - Fixed the error recovery logic when ioctl cmd times out. - Increased the ioctl cmd timeout value to 60. - Subtract some delta from cmd timeout to attach the timer if its greater than 25 sec. Rev 5.00.04b7 RA,KH - Check timer_pending prior to modifying os command timer. - Updated eh_abort, eh_wait_on_command, eh_device_reset and done routines. Fixed panic/hang after cable pull w/ keep alive timeout expiration. - Removed use of depricated adapter_lock. - Fixed problem where driver unload would trigger adapter reinit on second port of qla4052. Rev 5.00.04b6 RA,KH - Fixed the issue where we attempt to keep on relogin device even after the set ddb mbx cmd timedout from dpc context. - Round IOCTL memory allocations up to a long aligned size. - Backed out timeout shortening fix in send_command_to_isp - Debug print updates. - Make sure adapter is online before placing requests on request queue. - Updated restore factory defaults IOCTL - Added support for MSI (conditionally compiled in, disabled by default) Rev 5.00.04b5 RA,KH - Spinlock fix in delete_device - Scaled down ioctl debug print messages - IOCTL & TAPE cmd fix - Initialize IOCTLs at end of driver initialization - Incorporated sp_get & sp_put - Updated GPL headers Rev 5.00.04b4 RA,KH - Null pointer fixes - Continuous relogin change Rev 5.00.04b3 RA,KH - Ported the following fixes from 5.00.03 GA Release: - Fixed the issue where we are giving firmware very short timeout period per command in qla4xxx_send_command_to_isp(). - Added the code to handle a corner case where driver does not handle the login in progress state. - Ported the following fixes from 5.00.03b19: - Zero out the request queue free slot before putting the new iocb on that slot. - Bypass the sense data for tape and ioctl srb's to the upper layer. Fixed this issue in qla4xxx_check_and_copy_sense() code. - Updated code to obtain dhcp ip address (if available) while waiting for firmware to become ready. - Changed some memory allocation flags from GFP_KERNEL to GFP_ATOMIC in locations that should not block. - Updated some debug print statements. - Updated proc display. - Fixed potential spin lock problem in complete_request. Rev 5.00.04b2 KH - Added support for RESTORE_FACTORY_DEFAULTS IOCTL. - Re-enabled use of extended_error_logging command line parameter. - cmd_entry memset fix. _________________________________________ 3.0 Installation Instructions _________________________________________ This section is divided into the following sections: 1. Saving the Driver Source to Diskette 2. Building a Driver from the Sources Code 3. Load the Driver Manually 4. Making a RAMDISK to Load the Driver Automatically 5. Checking the driver version 6. Uninstalling the Driver Module 7. Upgrading the Driver on iSCSI bootable systems 8. Driver Parameters 9. Additional Notes The kernel sources should be already installed on the system for the relevant kernel or install it from the RedHat/SuSE source CD(s) before proceeding further. Most distributions include the kernel source on the first disc of the distribution CDs. This section makes extensive use of the build.sh script located in driver source (extras/build.sh). This script currently supports driver compilation (installation and updates) on SLES9 and RHEL4 distributions on main hardware platforms. The build.sh script supports for following directives: # ./extras/build.sh Build the driver sources based on the standard SLES9/RHEL4 build environment. # ./extras/build.sh clean Clean driver source directory of all build files (i.e. *.ko, *.o, etc). # ./extras/build.sh new Rebuild the driver sources from scratch. This is essentially a shortcut for: # ./build.sh clean # ./build.sh # ./extras/build.sh install Build and install the driver module files. This command performs the following: 1. Builds the driver .ko files. 2. Copies the .ko files to the appropriate /lib/modules/... directory. 3. Adds the appropriate directive in the modprobe.conf[.local] to remove the qla4xxx_conf module when the qla4xxx modules in unloaded. # ./extras/build.sh initrd Build, install, and update the initrd image. This command performs the following: 1. All steps in the 'install' directive. 2. Adds a qla4xxx_conf entry into the /etc/sysconfig/kernel INITRD_MODULES if and only if a qla4xxx module already is present in the listing. 3. Rebuilds the initrd image with the /sbin/mk_initrd command. NOTE: Refer to the OS specific Driver Disk Kit documentation for the procedure to install iSCSI bootable systems. 3.1 Saving the Driver Source to Diskette --------------------------------------- 1. Download the qla4xxx driver qla4xxx-vx.yy.zz.tar.gz file from QLogic's website. 2. If prompted "What would you like to do with this file?" choose "Save this file to disk." 3. Insert a blank diskette and download to the diskette directly. 3.2 Building a Driver from the Source Code ------------------------------------------- From the source code, you can build a qla4xxx.ko for your host system, and load the driver manually or automatically using a RAMDISK image during system boot time. 1. Using the diskette you created in Section 4, copy the qla4xxx-vx.yy.zz.tar.gz file to /qla4xxx. Follow these steps from the "/" (root) directory: # mkdir qla4xxx # cd qla4xxx # mount /mnt/floppy # cp /mnt/floppy/*.gz] . (the period at the end is required) # tar -xvzf *.gz # cd x.yy.zz 2. Build the Driver modules from the source code by executing the build.sh script. # ./extras/build.sh 3. To load the driver manually, see section 3.2. To make a RAMDISK image to load the driver during system boot time, see section 3.3. 3.3 Load the Driver Manually using INSMOD or MODPROBE ------------------------------------------------------ Before loading the driver manually, first build the driver binary from the driver source files as described in sections 3.1. - To load the driver directly from the local build directory, type the following in order: # insmod qla4xxx.ko - To load the driver using modprobe: 1. Install the driver module *.ko file to the appropriate kernel module directory: # ./extras/build.sh install 2. Type the following to load the driver for qla4xxx HBAs: # modprobe -v qla4xxx - To unload/uninstall the driver: 1. # rmmod qla4xxx or 2. # modprobe -r qla4xxx 3.4 Making a RAMDISK Image to Load the Driver Automatically ------------------------------------------------------------ The build.sh script can be used to update and create and initrd image: # ./extras/build.sh initrd 3.5 Checking the Driver Version -------------------------------- The driver/firmware version can be verified by performing the following command: #cat /proc/scsi/qla4xxx/0 The driver/firmware version can also be viewed using the SANsurfer Manager which is available from the www.QLogic.com website. 3.6 Uninstalling the Driver Module ----------------------------------- Please verify that there are no mounted iSCSI drives before unloading the driver. Please verify that the SANsurfer Application GUI and agent are not running. If the SANsurfer agent is running, it can be stopped with the following command: #pkill iqlremote The driver can be unloaded with the following command: #rmmod qla4xxx 3.7 Upgrading the Driver on iSCSI bootable systems -------------------------------------------------- This is equivalent to including the driver in the ramdisk to load it automatically during boot time. Please refer to section 3.4 on how to include the driver as part of the ramdisk. 3.5 Driver Parameters -------------------- 3.8.1 System Parameters ---------------------- Most driver and device parameters are exported via the sysfs as regular file, so you can change parameters using regular commands. The following path is where device parameters can be found: /sys/class/scsi_device/:::/device/ timeout - In the 2.6 kernel, a command timeout is 30 seconds, so if a command takes longer than 30 seconds, which could happen in a network environment then it may be necessary to increase this timeout value in sysfs for the device. Example: echo 60 >/sys/class/scsi_device/4:0:0:0/device/timeout The Linux driver does not immediately recognize dynamically added devices automatically, therefore, a manual rescan must be performed. rescan - This will initiate a rescan on the device echo "- - -" > /sys/class/scsi_host/hostX/scan Example: echo "- - -" > /sys/class/scsi_host/host6/scan Where "hostX" is replaced by your "Host number". 3.8.2 Multiple LUN Support --------------------------- Support for multiple LUNs can be configured by doing the following: (1) If the SCSI Mid-Layer is compiled as a module, add the following line to the loadable module configuration file modprobe.conf, found under /etc directory to scan for multiple LUNs: options scsi_mod max_luns=255 NOTE: If you have multiple adapters, set max_luns to the largest number of LUNs supported by any one of these adapters. 3.8.3 Driver Command Line Parameters ----------------------------------- The driver gets its parameters from the command line itself or from modprobe 'option' directive found in the modules.conf file. The parameters are in simple =value format, i.e. ql4xdiscoverwait=60, Where is one of the following option parameters: Usage: insmod qla4xxx =value * ql4xmaxqdepth - This parameter defines the maximum queue depth reported to Scsi Mid-Level per device. The Queue depth specifies the number of outstanding requests per lun. (obsolete with sysfs) Default: 2. * ql4xdiscoverywait - This parameter defines how long to wait for a port during boot-time. Default: 60 * ql4xcmdretrycount - This parameter defines the maximum number of Scsi Mid-Level retries allowed per command. Default: 20 * extended_error_logging - This parameter enables debug and defines the debug level to use. The debug information s written to /var/log/messages. Default: 0 (disable) All the available parameters can be viewed using one of the following commands: # modinfo -p qla4xxx.ko Usage examples: # insmod qla4xxx.ko ql4xdiscoverwait=60 _______________________________ 4.0 Configuration Information _______________________________ Detailed information on configuring the QLogic iSCSI HBA can be found in the SANsurfer online help available from the QLogic website. _______________________________ 5.0 Known Issues _______________________________ No known issues _____________________ 6.0 Unattended Mode _____________________ This package does not support Unattended Mode ________________________________________ 7.0 WEB Sites and Support Phone Number ________________________________________ IBM Support Web Site: http://www.ibm.com/pc/support IBM Marketing Netfinity Web Site: http://www.pc.ibm.com/netfinity If you have any questions about this update, or problems applying the update go to the following Help Center World Telephone Numbers URL: 1-800-772-2227 http://www.pc.ibm.com/qtechinfo/YAST-3P2QYL.html. ____________________________ 8.0 Trademarks and Notices ____________________________ The following terms are trademarks of the IBM Corporation in the United States or other countries or both: IBM BladeCenter eServer Microsoft, Windows, and Windows NT are trademarks of Microsoft Corporation in the United States, other countries, or both. Linux is a registered trademark of Linus Torvalds. Intel trademarks or registered trademarks are trademarks of Intel Corporation. Other company, product, and service names may be trademarks or service marks of others. ________________ 9.0 Disclaimer ________________ THIS DOCUMENT IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. IBM DISCLAIMS ALL WARRANTIES, WHETHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE AND MERCHANTABILITY WITH RESPECT TO THE INFORMATION IN THIS DOCUMENT. BY FURNISHING THIS DOCUMENT, IBM GRANTS NO LICENSES TO ANY PATENTS OR COPYRIGHTS. Note to Government Users Note to U.S. Government Users -- Documentation related to restricted rights -- Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corporation.