IBM FAStT Host Adapter Driver and IBM FAStT FC-2 Host Bus Adapter Driver version 5.38.6 for Linux Products supported: IBM FAStT Host adapter IBM FAStT FC-2 Host Bus adapter Last updated: 04/15/2002 Contents 1.0 OS Support 2.0 Supported Features 3.0 Release History 4.0 Host Adapter configuration 4.1 Update IBM FAStT Host Adapter BIOS 4.2 Configure the NOVRAM Setting for the IBM FAStT Host Adapter 5.0 Creating the Driver Diskette 5.1 Driver Disk for Adding Driver to Existing OS 6.0 Installing the Driver using Disk 6.1 RedHat Binary driver install 6.2 Install FAStT_MSJ 6.3 Enable more than 1 scsi device per adapter 6.4 Loading the driver manually 6.5 Loading the driver using a ramdisk image 6.6 Rebuilding the ramdisk image after configuration changes. 7.0 Building a Driver from the Sources Code 7.1 Building a Uni-Processor (UP) Version of the Driver 7.2 Building Symmetric Multi-Processor (SMP) Version of the Driver 8.0 Limitations 9.0 Additional Notes 9.1 Proc Filesystem Support 10.0 Driver file Contents 11.0 WEB Sites and Support Phone Number 12.0 Trademarks and Notices 13.0 Disclaimer ======================================================================= 1.0 OS Support -------------- The 5.38.6 device driver supports the following Linux versions: * RedHat 7.1: 2.4.9-21 kernel versions * RedHat 7.2: 2.4.9-21 kernel versions * SuSE 7.3: 2.4.10 kernel version * TurboLinux 7.0: 2.4.9-3 kernel versions Earlier or later versions of the Linux kernels with these versions are not supported with this release. The binary modules included in this release will load only on RedHat 7.1 and 7.2 using the 2.4.9-21 kernels. The device drivers for SuSE and TurboLinux must be compiled from the driver source code. This readme file makes an assumption that the user has already configured their storage subsystem properly for a Linux server with storage partitioning enabled and configured with the host type set to LINUX. Only like type adapters can be configured as a failover pair. An IBM FAStT Host Adapter cannot failover to an IBM FAStT FC-2 Host Bus Adapter. The IBM FAStT Host Adapter uses the qla2200.o device driver and the IBM FAStT FC-2 Host Bus Adapter uses the qla2300.o device driver. This readme will use the term IBM FAStT Host Adapter to refer to both the IBM FAStT Host Adapter and the IBM FAStT FC-2 Host Bus Adapter. ======================================================================= 2.0 Supported Features ---------------------- 2.1 ISP2x00 Features -------------------- * FCAL - direct attach loop * Point-to-point * Fabric support * Initiator mode only * Fault recovery on down loops * Persistent binding * Extended LUN support up to 255 LUNs * FC tape support * Multi-path failover support ======================================================================= 3.0 Release History ------------------- Rev. 5.38.6 April 02, 2002 RL QLogic - Changed get_disc_port ioctl behavior which returns next available device instance info when a port/target is disconnected. Now return error when query for lost port. Rev. 5.38.5 March 29, 2002 JJ QLogic - Fix stack overflow issue. - Fix proc overflow issue. - Optionally register the adapter to the name server if receiving a lip occurred (0x8010) or link mode up (0x8030). - Return DID_BUS_BUSY status for a cmd completed with target timeout status. Rev. 5.38.4 March 19, 2002 RL QLogic - Added support for returning actual hba speed in a loop configuration. - Corrected ioctl hang due to not getting io_request_lock before issuing login_fabric mbx cmd. Rev. 5.38.3 March 15, 2002 AV QLogic - MODULE_LICENSE is valid for 2.4.9 kernels (inclusively) and above -- resolve spurious 'tainted' kernel issue. - Fix I/O port request call to the kernel. - Fix IOCTL contention case during heavy I/O. Rev. 5.38.2 March 14, 2002 AV QLogic - Cleanup non-essential info messages piped to syslogd. Rev. 5.38.1 March 13, 2002 JJ QLogic - Change version to 5.38.1. - Call qla2x00_cfg_display_devices to print device info to the messages file for MPIO driver. ======================================================================= 4.0 Host Adapter configuration ------------------------------ 4.1 Update IBM FAStT Host Adapter or IBM FAStT FC-2 Host Bus Adapter BIOS --------------------------------------------------------------------- The adapter BIOS can be updated by booting the server to the BIOS update diskette, available from the IBM Support website, then run the following commands: flasutil /f /l flasutil /u This will update the IBM FAStT Host Adapters or IBM FAStT FC-2 Host Bus Adapters in this server. Note: The FAStT adapter BIOS update program will only update like adapters. If you have a server that contains IBM FAStT Host Adapters and IBM FAStT FC-2 Host Bus Adapters you may only update one adapter type at a time. 4.2 Configure the NOVRAM settings for the IBM FAStT Host Adapter and IBM FAStT FC-2 Host Bus Adapter. ------------------------------------------------------------------------- All settings, except for the following, should maintain the IBM defaults. - Host Adapter settings Loop reset delay - 8. - Advanced Adapter Settings LUNs per target - 0 Enable Target Reset - Yes Port down retry count - 12 1. As the host boots, press when prompted. 2. After the Fast!Util program loads, the display will depend on whether there are multiple IBM FAStT Adapters installed. If there are multiple IBM FAStT Adapters, a list of addresses occupied by those Host Adapters will appear. Using the arrow keys, select the desired adapter and press ENTER. The Fast!Util Options menu will then appear. For further information refer to the IBM FAStT Host Adapter publication. ======================================================================= 5.0 Creating the Driver Disks ----------------------------- 5.1 Driver Disk for Adding driver to Existing OS ------------------------------------------------ Download the IBM FAStT Host Adapter driver or the IBM FAStT Host Bus Adapter driver for Linux from the IBM Support website. If prompted "What would you like to do with this file?" choose "Save this file to disk". Insert a blank formatted diskette and download to the diskette directly. This file will be in the .tgz file compression format. Download the IBM FAStT_MSJ for Linux from the IBM Support website. If prompted "What would you like to do with this file?" choose "Save this file to disk". This file will need to be save to your hard disk drive. This file will be in the .tgz file compression format. ======================================================================= 6.0 Installing the driver ------------------------- 6.1 Install FAStT_MSJ --------------------- If FAStT_MSJ for Linux is not currently installed you will need to Install it now. FAStT_MSJ and the qlremote agent are needed to configure this device driver and the host adapters for Multi-path failover. See the FAStT_MSJ publications for instructions on the installation procedure for FAStT_MSJ and the qlremote agent for Linux. FAStT_MSJ is required for proper multi-path and failover configuration. 6.2 RedHat Binary driver install -------------------------------- To install the driver, you will need to perform the following steps to add the driver to your OS. 1. Login as root and create a directory # mkdir qla2x00 2. Change directory to qla2x00 # cd qla2x00 3. Insert the Adapter driver diskette created in Section 5.1 and copy the file to the current directory: # mcopy a:/*.tgz . (Do not forget the . at the end of the mcopy string) 4. Extract the RPM package from the .tgz file by running the command: # tar zxvf %.tgz Replace %.tgz with the name of the file that was downloaded. 5. To invoke the RedHat RPM package manager to install the qla2200.o and the qla2300.o driver for the first time, type the following command: # rpm -iv qla2x00-5.38.6-fo.i686.rpm If you are updating the old qla2200 driver to the current driver, type the following command: # rpm -iv --force qla2x00-5.38.6-fo.i686.rpm 6. The qla2200.o and qla2300.o drivers are added to your boot drive under /lib/modules/2.4.9-21/kernel/drivers/addon/qla2200 and /lib/modules/2.4.9-21smp/kernel/drivers/addon/qla2200 for UP and SMP respectively. However, the driver needs to be loaded before the system can access the devices attached to the IBM FAStT Host Adapters. 6.3 Enable more than 1 scsi device per adapter ---------------------------------------------- 1. For support of up to 32 LUNs the following needs to be added to the modules.conf file. If you have multiple adapters, set max_scsi_luns to the maximum LUNs supported. For RedHat you would add the following to your modules.conf file. options scsi_mod max_scsi_luns=32 Your modules.conf would look something like the following: alias scsi_hostadapter aic7xxx alias scsi_hostadapter2 qla2200 alias scsi_hostadapter3 qla2200 options scsi_mod max_scsi_luns=32 For TurboLinux and SuSE you will need to edit your lilo.conf file to add the append statement in the lilo.conf file to allow the scsi scan to ID more than 1 scsi device per adapter. append= "max_scsi_luns=32" The entry in lilo.conf should look something like: image=/boot/vmlinuz label=linux1 initrd=/boot/initrd.img read-only root=/dev/sda5 append="max_scsi_luns=32" 2. You will then need to run depmod from the command prompt to update your /lib/modules/KERNEL_VERSION/modules.dep file with the information added in your /etc/modules.conf file. # depmod -a 3. You will now need to rebuild you boot image, lilo and reboot so that the options string added above can be loaded. Refer to your Linux distribution documentation to verify the steps to rebuild the boot image and ramdisk for your distribution. 6.4 Loading the Driver manually ------------------------------- To load the driver manually, type the following command: # modprobe qla2200 or # modprobe qla2300 Note: If an older version of the driver is already loaded, that driver must be unloaded prior to this driver being loaded. To unload the driver manually, type: # modprobe -r qla2200 or # modprobe -r qla2300 6.5 Loading the Driver using a ramdisk image -------------------------------------------- 1. Linux may detect new adapters during the system boot, if the adapters are configured during the boot process following entries will be added to your modules.conf file. Verify the modules.conf file and add the following if needed: alias scsi_hostadapter1 qla2200 or alias scsi_hostadapter1 qla2300 to the file /etc/modules.conf If you already have a SCSI device loaded the scsi_hostadapter1 may need to be incremented to scsi_hostadapter2. SuSE 7.3: The SCSI device driver entries are placed in the /etc/rc.config file. Review your SuSE 7.3 documentation for instructions on how to load SCSI device drivers. 2. You will then need to run depmod from the command prompt to update your /lib/modules/KERNEL_VERSION/modules.dep file with the information added in your /etc/modules.conf file. # depmod -a 3. You will now need to load the device driver. To load the driver manually, type the following command: # modprobe qla2200 or # modprobe qla2300 4. Perform the following command to build the ramdisk image that contains the qla2200.o or qla2300.o driver. /sbin/mkinitrd /boot/newinitrd-image Note: is the subdirectory under /lib/modules/"kernel_release" where the qla2200 or qla2300.o module resides. The command "uname -r" will display the current kernel version in use. SuSE 7.3: SuSE Linux uses mk_initrd to build their ramdisk images. Refer to the SuSE 7.3 documentation for the proceedures to build ramdisk images. 5. Modify the /etc/lilo.conf to load the ramdisk image during boot. For example add another entry into lilo.conf: image=/boot/vmlinuz-2.4.9-21 label=linux-2.4.9-21 root=/dev/sda1 initrd=/boot/newinitrd-image 6. Load the new lilo.conf file by executing this command: # lilo 7. Reboot the system, the qla2200.o or qla2300 driver will be loaded by the ramdisk image at boot time. 8. You will now need to configure your device driver for Multi- path I/O using FAStT_MSJ and the qlremote agent. Refer to the FAStT_MSJ publication and readme.txt for these instructions. 9. After the system is configured for multi-path I/O steps 3 - 7 above need to be repeated so that during system boot the proper driver configuration is loaded. 6.6 Rebuilding the ramdisk image after configuration changes. ------------------------------------------------------------- To rebuild your ramdisk image after adding a new LUN or other configuration changes these steps may be followed: 1. Unload the qla2200 or qla2300 driver module by opening a terminal window and typing: # modprobe -r qla2200 or # modprobe -r qla2300 2. Delete the options string in /etc/modules.conf that is added by the FAStT MSJ load-balancing process. This is typically the last line in the /etc/modules.conf file: "options qla2200 ConfigRequired=1 ql2xopts=scsi-qla00- adapter- port=..." 3. In the terminal windows type: depmod -a 4. Reload the qla2200 or qla2300 device drivers typing: # modprobe qla2200 or # modprobe qla2300 5. Run the SMclient to redistribute the logical volumes. 6. Open a terminal windows and run: qlremote 7. Open another terminal window and run: /usr/FAStT_MSJ 8. Connect to local host, configure LUNs to match the preferred paths shown in IBM FAStT Storage manager. Running Storage Subsystem->Profile in the Subsystem Management window will display the world-wide port name for each controller. Ensure that the preferred path in the FAStT_MSJ LUN configuration window matches the controller assignment in IBM FAStT Storage manager. 9. Apply the configuration and exit MSJ. 10. Switch to the terminal window that has qlremote running and to stop qlremote. 11. In the terminal windows type: depmod -a 12. Unload the qla2200 or qla2300 driver and then reload the driver using modprobe so the driver will pull in the new option string that was added by FAStT_MSJ. 13. Then build the boot image, open a terminal window and type: /sbin/mkinitrd -f /boot/ 14. In a terminal window type: /sbin/lilo Otherwise you will not be able to boot your new ramdisk image. 15. Reboot the system to the ram disk image just created. ======================================================================= 7.0 Building a Driver from the Sources Code ------------------------------------------- 7.1 Building a Uni-Processor (UP) Version of the Driver ------------------------------------------------------- 1. Install the kernel-headers and kernel-sources RPM files for the supported kernel. The instructions in this step are for the Redhat 7.1 and 7.2 OS. Refer to your linux vendor documentation for procedures to update the kernel source code for your linux version. # rpm -iv kernel-headers*.rpm # rpm -iv kernel-source*.rpm 2. Using the adapter driver diskette you created in Section 5, copy the qla2x00src-v5.38.6-fo.tgz file to /qla2x00. Follow these steps: # mkdir qla2x00 # cd qla2x00 # mcopy a:*.tgz . # tar -xvzf *.tgz 3. Prepare source headers for a Uni-processor module build by opening a terminal window and changing to the source directory # cd /usr/src/linux-2.4 (Redhat 7.1 and Redhat 7.2) 4. Verify that the correct kernel information is present in the .config file by running make menuconfig at the command prompt. # make menuconfig - select "Processor type and features" press NOTE: Refer to the your server installation documentation to verify that the proper processor family is selected for your server. - deselect "Symmetric multiprocessor" if it is selected. - select Exit to exit the Main Menu. The system prompts: "Do you wish to save your new kernel configuration?". Select "Yes". The system saves a new config file called ".config" in the current directory. 5. Rebuild the dependencies for the kernel. Type the following command at the command prompt: # make dep 6. Change directories back to the directory in step 2 that contains the device driver source code. Build the driver qla2200.o and qla2300.o from the driver source code by typing: To make UP version of ISP2200 driver # make ISP2200=1 To make UP version of ISP2300 driver # make ISP2300=1 To make UP version of ISP2200 and ISP2300 drivers # make all For SuSE 7.3 and TurboLinux 7.0 you will add OSVER=linux to the command line to build the device drivers. # make all OSVER=linux 7. Copy the device driver created above to the proper kernel directory. For Redhat 7.x this is /lib/modules/2.4.9-21/kernel/drivers/addon/qla2200 8. Load the driver by typing: # modprobe qla2200.o or # modprobe qla2300.o 9. Refer to section 6.5 for instructions on building a ramdisk image to load these drivers during system boot. 7.2 Building Symmetric Multi-Processor (SMP) Version of the Driver ---------------------------------------------------------------------------------------------- 1. Install the kernel-headers and kernel-sources RPM files for the supported kernel. The instructions in this step are for the Redhat 7.1 OS. Refer to your linux vendor documentation for procedures to update the kernel source code for your linux version. # rpm -ivh kernel-headers*.rpm # rpm -ivh kernel-source*.rpm 2. Using the adapter driver diskette you created in Section 5 copy the qla2x00src-v5.38.6-fo.tgz file to /qla2x00. Follow these steps: # mkdir qla2x00 # cd qla2x00 # mcopy a:*.tgz . # tar -xvzf *.tgz 3. Prepare source headers for a SMP module build by opening a terminal window and changing to the source directory # cd /usr/src/linux-2.4 (Redhat 7.1) 4. Verify that the correct kernel information is present in the .config file by running make menuconfig at the command prompt. # make menuconfig - select "Processor type and features" press NOTE: Refer to the your server installation documentation to verify that the proper processor family is selected for your server. - select "Symmetric multiprocessor" press - select Exit to exit the Main Menu. The system prompts: "Do you wish to save your new kernel configuration?". Select "Yes". The system saves a new config file called ".config" in the current directory. 5. Rebuild the dependencies for the kernel. Type the following command at the command prompt: # make dep 6. Change directories back to the directory in step 2 that contains the device driver source code. Build the driver qla2200.o and qla2300.o from the driver source code by typing: # make all SMP=1 For SuSE 7.3 and TurboLinux 7.0 you will add OSVER=linux to the command line to build the device drivers. # make all OSVER=linux 7. Copy the device driver created above to the proper kernel directory. For Redhat 7.x this is /lib/modules/2.4.9-21/kernel/drivers/ addon/qla2200 8. Load the driver manually by typing: # modprobe qla2200.o or # modprobe qla2300.o 9. Refer to section 6.5 for instructions on building a ramdisk image to load these drivers during system boot. ======================================================================= 8.0 Limitations --------------- * Failover adapters must be of the same type. An IBM FAStT Host Adapter and an IBM FAStT FC-2 Host Bus Adapter cannot be a failover pair. * The qlremote agent must not be loaded when disk I/O's are running. * Lun masking is not functional in this release. * In the Storage Manager Client Storage Partitioning must be enabled with the host type of 'linux' selected and the UTM must be removed from the 'Linux' storage partition. Otherwise the correct drive information is not presented to the Linux operating system. * Every time a change is made to your configuration you will need to generate a new boot image and launch lilo. This includes changes to LUN ownership and adding LUNs to the storage subsystem. See section 6.6 for instructions on this procedure. * With sequential LUN numbering, if one LUN is missing due to a controller failure the system associates the wrong SCSI device entry with the LUNs after the failed LUN. The result could be that the wrong LUN could be mounted to an incorrect mount point. You should always be aware of this because it can also be caused by adding a LUN out of sequence. You should ensure that the LUNs are number in sequence starting from 0 in storage partitioning. If there is a gap (for example LUN 0, LUN1, LUN3) Linux will quit probing at the gap where LUN 2 should be and all of the following LUNs will be missing. * When updating Firmware or NVSRAM with high disk activity a controller may become unresponsive during the update. IBM recommends that disk I/O be stopped during these code updates. * When adding logical drives to the storage subsystem with the SMclient you will need to unload the device driver and then modprobe the driver to scan the new logical drives. You will then need to reconfigure using FAStT_MSJ and the qlremote agent so these disks will be available for the OS to utilize. After the driver is reconfigured with FAStT_MSJ you will need to repeat section 6.6 in this readme to rebuild your boot image with the new option string created by FAStT_MSJ. * If a configuration change has been made using FAStT_MSJ and you are not able to APPLY or SAVE the configuration you will need to check the options string in your modules.conf file. On occasion this string may get corrupted and need to be deleted before your new configuration will be saved properly. See section 6.6 above. ======================================================================= 9.0 Additional Notes -------------------- 9.1 Proc Filesystem Support --------------------------- The /proc filesystem for the QLA2200 driver can be found in the /proc/scsi/qla2200/ or /proc/scsi/qla2300/ directory. This directory contains a file for each IBM FAStT Host Adapter in the system. Each file will present information about the adapter and transfer statistics for each discovered LUN. 9.2 Known Issue --------------- Durning the device driver load you may see the following warning message: Warning: loading /lib/modules/2.4.9-21smp/kernel/drivers/addon/qla2200/qla2300.o will taint the kernel: no license This is only a warning message and can be ignored. If you would like to stop this warning message you may correct this warning by following these steps. 1. Extract the 5.38.6 device driver source code. 2. Open the qla2x00.c source file in an editor (DO NOT USE NOTEPAD) 3. Goto line 342 and you will see: #if LINUX_VERSION_CODE > KERNEL_VERSION(2,4,9) 4. Change this to read as: #if LINUX_VERSION_CODE >= KERNEL_VERSION(2,4,9) 5. Recompile the device driver as show earlier in this readme file. ======================================================================= 10.0 Driver file Contents ------------------------- The following files can be downloaded from the IBM Support website. 1. qla2x00-5.38.6-1.i686.rpm - (A RedHat Package Manager used for adding the driver or upgrading driver on RedHat 7.1). /lib/modules/2.4.9-21/kernel/drivers/addon/qla2200/qla2200.o /lib/modules/2.4.9-21smp/kernel/drivers/addon/qla2200/qla2200.o /lib/modules/2.4.9-21enterprise/kernel/drivers/addon/qla2200/qla2200.o /lib/modules/2.4.9-21/kernel/drivers/addon/qla2200/qla2300.o /lib/modules/2.4.9-21smp/kernel/drivers/addon/qla2200/qla2300.o /lib/modules/2.4.9-21enterprise/kernel/drivers/addon/qla2200/qla2300.o /usr/share/doc/qla2x00-5.38.6/README.5.38.6.qla2200 /usr/share/doc/qla2x00-5.38.6/release.txt ======================================================================= 11.0 WEB Sites and Support Phone Number --------------------------------------- IBM Support Web Site: http://www.ibm.com/pc/support IBM eServer xSeries Marketing Web Site: http://www.ibm.com/pc/us/eserver/xseries/index.html If you have any questions about this update, or problem applying the update go to the following Help Center World Telephone Numbers URL: http://www.ibm.com/planetwide ======================================================================= 12.0 Trademarks and Notices --------------------------- The following terms are trademarks of the IBM Corporation in the United States or other countries or both: Active Memory Predictive Failure Analysis HelpCenter ServeRAID IBM xSeries IBM TotalStorage Intel, Celeron, MMX, LANDesk, Pentium, Pentium II Xeon, Pentium III Xeon, and Xeon are trademarks of Intel Corporation in the United States, other countries, or both. Microsoft, Windows, and Windows NT are trademarks of Microsoft Corporation in the United States, other countries, or both. UNIX is a registered trademark of The Open Group in the United States and other countries. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Linux is a registered trademark of Linus Torvalds. Other company, product, and service names may be trademarks or service marks of others. ======================================================================= 13.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 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.