QLogic 1GB iSCSI TOE Expansion Card for IBM eServer BladeCenter Storage Driver for Red Hat Enterprise Linux 3 Advanced Server Version 3.23 QMC4052_2-4LinuxStorageDriver.txt Version 1.00 07/20/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.4 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.4 Linux Kernel Storage Driver 3.23 ---------------------------------------------------------------- -Initial Version _________________________________________ 3.0 Installation Instructions _________________________________________ This section is divided into the following sections: 1. Saving he 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. 3.1. Saving the Driver Source to Diskette --------------------------------------- Download qla4xxxsrc-v3.xx.tgz file from QLogic's website. If prompted "What would you like to do with this file?" choose "Save this file to disk". Insert a blank diskette and download to the diskette directly. 3.2 Building a Driver from the Sources Code -------------------------------------------- From the source code you can build qla4022.o drivers for your uniprocessor (UP) or symmetric multiprocessor (SMP) system, then load the driver manually or automatically using a RAMDISK image during system boot time. 3.2.1 Building a Uni-Processor (UP) Version of the Driver --------------------------------------------------------- 1. Using the diskette you created in Section 3.1, copy the driver source file - qla4xxxsrc-v3.xx.tgz to the qla4xxx directory: # mkdir /usr/src/linux/drivers/scsi/qla4xxx # cd /usr/src/linux/drivers/scsi/qla4xxx # mount /mnt/floppy # cp /mnt/floppy/*.tgz . (the period at the end is required) # tar -xvzf *.tgz 2. Build the Driver qla4022.o from the source code by typing: # make SMP=0 NOTE: Please refer to Makefile for additional supported command line parameters. NOTE: To load the driver manually, see section 3.3. To make a RAMDISK image to load the driver during system boot time, see section 3.4. 3.2.2. Building Symmetric Multiprocessor (SMP) Version of the Driver --------------------------------------------------------------------- 1. Prepare source headers for a SMP module build by first changing to the kernel source directory: # cd /usr/src/linux-2.4 2. Type "make menuconfig" to configure additional support: (Make sure built-in support is selected for the following options) - Select "Processor type and features" - Select "Symmetric multiproccessor" - Select Exit to exit the Processor Menu. - Select "SCSI Support" - Select "SCSI Disk Support" - Select "SCSI Generic Support" - Select Exit to exit the SCSI Menu. - Select Exit to exit the Main Menu. The system prompts: "Do you wish to save your new kernelconfiguration?". Select "Yes". The system saves a new config file called ".config" in the current directory. 3. Under kernel source directory type the following: # make dep 4. Using the diskette you created in Section 3.1, copy the driver source file - qla4xxxsrc-v3.xx.tgz to the qla4xxx directory. Follow these steps: # mkdir /usr/src/linux/drivers/scsi/qla4xxx # cd /usr/src/linux/drivers/scsi/qla4xxx # mount /mnt/floppy # cp /mnt/floppy/*.tgz . (the period at the end is required) # tar -xvzf *.tgz 5. Build qla4022.o driver from the source code by typing: # make NOTE: Please refer to Makefile for additional supported command line parameters. NOTE: To load the driver manually, see section 3.3. To make a RAMDISK image to load the driver during system boot time, see section 3.4. 3.3 Load the Driver Manually ------------------------------ Before loading the driver manually, first build the driver binary from the driver source files as described in sections 3.2.1 and 3.2.2. - (For Advanced Users) To load the driver directly from the local build directory, type the following: # insmod ./qla4022.o - To load the driver using modprobe: 1. Copy driver binary files. Type the following: # cp qla4022.o /lib/modules//kernel/drivers/scsi/ or # make install (build the driver and copy to the right location) 2. Update the module dependency file. You can either run "depmod -a" or make sure that the following line is in the /lib/modules//modules.dep file: /lib/modules//kernel/drivers/scsi/qla4022.o: \ /lib/modules//kernel/drivers/scsi/scsi_mod.o 3. Type the following to load the driver: # modprobe qla4022 To verify that the driver module is loaded, execute the command : # lsmod The qla4022 module should be listed when the Driver is loaded successfully. 3.4 Making a RAMDISK to Load the Driver Automatically ------------------------------------------------------- Perform the following steps to load the driver as a RAMDISK image every time the system is rebooted. 1. Build the driver binary files (see 3.2.1 and 3.2.2). 2. Copy the files to /lib/modules//kernel/drivers/scsi/ by typing: # make install 3. Add the following line to /etc/modules.conf. alias scsi_hostadapter0 qla4022 4. Type the following command to build the RAMDISK image that contains the qla4022.o module: # mkinitrd -f Examples: # mkinitrd -f /boot/newinitrd-image.img 2.4.7-10 # mkinitrd -f /boot/newinitrd-image.img 2.4.7-10smp NOTE: To get your kernel version before using the above comand, type: # uname -r NOTE: This step will overwrite the original ramdisk image file if executed within the /boot directory. Specify a unique Ramdisk image name to preserve the original ramdisk image. - Copy the newly built file to /boot. 5. Configure the boot loader with the new RAMDISK image. For LILO: a) Add "initrd=/boot/" in /etc/lilo.conf under one of the kernel entries to use the RAMDISK image. b) Run "lilo" and reboot system. Select the kernel with the new RAMDISK image to come up. For GRUB: a) Add "initrd /" in /etc/grub.conf file under one of the kernel entries to use the RAMDISK image. For example: kernel /vmlinuz-2.4.18-14 ro root=LABEL=/ initrd /initrd-2.4.18-14.img b) Reboot the system. 3.5 Checking the Driver Version -------------------------------- The driver/firmware version can be verified by performing the following command: #cat /proc/scsi/qla4022/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 is 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 qla4022 3.7 Upgrading the Driver on iSCSI bootable systems -------------------------------------------------- 1. Download the new Driver Source file, qla4xxxsrc-v3.xx.tgz from the QLogic Website www.QLogic.com. 2. Copy the Driver Source file to a local temp directory on the iSCSI bootable system. Untar the Driver Sources by using: #[temp] tar xvzf qla4xxxsrc-v3.xx.tgz 3. Copy the files to /lib/modules//kernel/drivers/scsi/ by typing: #[temp] make install #[temp] cd /lib/modules//update/ #[update] rm -f qla4022.o #[update] cp /lib/modules//kernel/drivers/scsi/qla4022.o 4. Type the following command to re-build the RAMDISK image that contains the qla4022.o module: # mkinitrd -f Examples: # mkinitrd -f /boot/newinitrd-image.img 2.4.7-10 # mkinitrd -f /boot/newinitrd-image.img 2.4.7-10smp NOTE: To get your kernel version before using the above command, type: # uname -r NOTE: This step will overwrite the original ramdisk image file if executed within the /boot directory. Specify a unique ramdisk image name to preserve the original ramdisk image. - Copy the newly built file to /boot. 5. Configure the boot loader with the new RAMDISK image. For LILO: a) Add "initrd=/boot/" in /etc/lilo.conf under one of the kernel entries to use the RAMDISK image. b) Run "lilo" and reboot system. Select the kernel with the new RAMDISK image to come up. For GRUB: a) Add "initrd /" in /etc/grub.conf file under one of the kernel entries to use the RAMDISK image. For example: kernel /vmlinuz-2.4.18-14 ro root=LABEL=/ initrd /initrd-2.4.18-14.img b) Reboot the system. 6. Verify the steps outlined in Step 3.5 to check the newly installed driver version. 3.8 Driver Parameters -------------------- The driver parameters are divided into System Parameters, NVRAM Parameters and Driver Command Line Parameters sections. 3.8.1 System Parameters ---------------------- 3.8.1a Multiple LUN Support --------------------------- Support for multiple LUNs may be configured in one of three ways. Currently, the maximum number of luns that can be scanned for each device is 128. 1) The kernel must be configured to have multiple LUN support enabled in order for non-zero LUNs to be configured and accessible. Use "make menuconfig" (as described in BUILD_KERNEL.txt) to build a kernel which has the option under SCSI Support enabled to probe all LUNs on SCSI devices. NOTE: If you have multiple adapters, set max_scsi_luns to the largest number of LUNs supported by any one of these adapters. 2) If the SCSI Mid-Layer is compiled in the kernel, the boot loader can be configured to scan for multiple LUNs each time the system boots. For LILO: a) Add the following line to each of the kernel image listed in the /etc/lilo.conf file: append="max_scsi_luns=128" b) Run "lilo" and reboot system. For GRUB: a) Append the max_scsi_luns parameters to each of the kernel images listed in the /etc/grub.conf file. For example: kernel /vmlinuz-2.4.7-10 ro root=/dev/hda2 max_scsi_luns=128 b) Reboot system. 3) If the SCSI Mid-Layer is compiled as a module, add the following line to the /etc/modules.conf file to scan for multiple luns at each boot. options scsi_mod max_scsi_luns=128 NOTE: If the SCSI Mid-Layer is loaded via the RAMDISK (i.e. Standard RedHat installations) then rebuild the RAMDISK. (see section 3.4) 3.8.2 NVRAM Parameters --------------------- None. 3.8.3 Driver Command Line Parameters ----------------------------------- To display a list and description of supported command line parameters, type the following at the command prompt: # modinfo qla4022.o Here are the parameters: * 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. Default: 2 * ql4xdiscoverywait - This parameter defines how long to wait for a port during boot-time. Default: 15 * 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 is written to /var/log/messages. 1 = Log errors only, 2 = Log debug information and errors. Default: 0 (disable) Usage example: # insmod qla4010.o ql4xmaxqdepth=2 ql4xcmdretrycount=20 3.9 Additional Notes --------------------- 3.9.1 Proc Filesystem Support ----------------------------- The /proc filesystem for the QLA4022 driver can be found in the /proc/scsi/qla4022/ directory. This directory contains a file for each port on the QLogic iSCSI adapter. Each file presents information about the adapter and each discovered lun. Example: cat /proc/scsi/qla4022/0 cat /proc/scsi/qla4022/1 3.9.2 Dynamically Added Devices ------------------------------ Linux does not immediately recognize dynamically added devices. Therefore, a manual scan must be performed using the /proc/scsi interface. Example: # echo "scsi add-single-device 0 1 2 3" >/proc/scsi/scsi (scsi mid layer will re-scan) Where "0 1 2 3" is replaced by your "Host Channel Id Lun". _______________________________ 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.