This README describes IBM HS20 Fibre Channel Expansion Card device driver version 6.0 for the supported Linux Products listed below. IBM HS20 Fibre Channel Expansion Card Refer to the IBM Support Website listed in "Web Sites and Support" section in this ReadMe document for the latest information and updated README file. Last updated: 3/6/2003 ============================================ CONTENTS ------------------------------------------------------------------------ 1.0 OS SUPPORT 2.0 SUPPORTED FEATURES 3.0 RELEASE HISTORY 4.0 IBM HS20 FIBRE CHANNEL EXPANSION CARD CONFIGURATION 4.1 UPDATING BIOS 4.2 CONFIGURING THE NOVRAM SETTINGS 5.0 CREATING THE DRIVER DISKETTE 6.0 BUILDING A DRIVER FROM THE SOURCE CODE 6.1 BUILDING A UNI-PROCESSOR (UP) VERSION OF THE DRIVER 6.2 BUILDING A SYMMETRIC MULTI-PROCESSOR (SMP) VERSION OF THE DRIVER 7.0 LOADING AND CONFIGURING THE DRIVER 7.1 ENABLING MORE THAN ONE SCSI DEVICE PER ADAPTER 7.2 LOADING THE DRIVER MANUALLY 7.3 LOADING THE DRIVER USING A RAMDISK IMAGE 7.4 REBUILDING THE RAMDISK IMAGE AFTER CONFIGURATION CHANGES 8.0 LIMITATIONS 9.0 ADDITIONAL NOTES 10.0 DRIVER FILE CONTENTS 11.0 WEB SITES AND SUPPORT 12.0 TRADEMARKS 13.0 NOTICES ============================================ 1.0 OS SUPPORT ------------------------------------------------------------------------ The 6.0 device driver supports the following Linux versions using the vendor kernels: * RedHat 7.3: 2.4.9.34 kernel version * RedHat Advanced Server 2.1: 2.4.9.E.10 kernel version * SuSE 7.3: 2.4.18-xGB kernel * SuSE 8.0 Professional: 2.4.18-xGB kernel Earlier versions of the Linux kernels or generic kernels used with these Linux versions are not supported with this release. The driver package contains the driver source code only. The device driver must be compiled from the source code for your specific configuration. 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. The IBM HS20 Fibre Channel Expansion Card uses the qla2300.o device driver. ============================================ 2.0 SUPPORTED 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 ------------------------------------------------------------------------ Refer to the revision.notes file located in driver package. ============================================ 4.0 IBM HS20 FIBRE CHANNEL EXPANSION CARD CONFIGURATION ------------------------------------------------------------------------ This section describes procedures for updating BIOS and configuring NOVRAM settings of HS20 Fibre Channel Expansion card. 4.1 UPDATING BIOS The expansion card 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 /i flasutil /u /i 4.2 CONFIGURING THE NOVRAM SETTINGS 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 Fast!Util Options menu will then appear. For further information refer to the IBM IBM HS20 Fibre Channel Expansion Card Installation and User's Guide. ============================================ 5.0 CREATING THE DRIVER DISKETTE ------------------------------------------------------------------------ Download the IBM IBM HS20 Fibre Channel Expansion Card driver source code for Linux from the IBM Support website listed in Support section of this Readme document. 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. ============================================ 6.0 BUILDING A DRIVER FROM THE SOURCE CODE ------------------------------------------------------------------------ From the source code you can build a qla2300.o for your UP or SMP systems, and load the driver manually or automatically using a RAMDISK image during system boot time. PREREQUISITES: *Verify that both kernel-headers and kernel-source RPMS are already installed. # rpm -qa | grep kernel 6.1 BUILDING A UNI-PROCESSOR (UP) VERSION OF THE DRIVER 1. Install the kernel-headers and kernel-sources RPM files for the supported kernel. NOTE: The instructions in this procedure are for the Redhat 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 i2xLNX-v6.0-fo-dist.tgz file to /i2x00-v6.0. Follow these steps: # mcopy a:*.tgz . # tar -xzf *.tgz This will create a folder named "i2x00-v6.0" and extract out the following files to the "i2x00-v6.0" folder: README.combopkg Readme file for this package. drvrsetup Script file to copy driver source files included in the driver source tgz file. (See NOTE) i2xLNXsrc-.tgz Compressed binary distribution file for driver sources. This file is the same type of driver source tgz file as the ones used for distributing earlier versions of the QLA2X00 drivers. libinstall Script file to install/setup Expansion Card API library. libremove Script file to remove Expansion Card API library. qlapi--rel.tgz Compressed binary distribution file for API library. 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) 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 qla2300.o from the driver source code by typing: To make UP version of ISP2300 driver # make ISP2300=1 Or to make UP version of all type ISP2xxx drivers # make all For SuSE 7.3 and Turyou 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. 8. Modify the modules.conf (RedHat) to load the correct device driver modules. Your modules.conf would look something like the following: alias scsi_hostadapter aic7xxx alias scsi_hostadapter2 qla2300 alias scsi_hostadapter3 qla2300 options scsi_mod max_scsi_luns=32 9. Load the driver manually by typing: # modprobe qla2300.o 6.2 BUILDING A SYMMETRIC MULTI-PROCESSOR (SMP) VERSION OF THE DRIVER 1. Install the kernel-headers and kernel-sources RPM files for the supported kernel. NOTE: The instructions in this procedure are for the Redhat 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 i2xLNX-v6.0-fo-dist.tgz file to /i2x00-v6.0. Follow these steps: # mcopy a:*.tgz . # tar -xzf *.tgz This will create a folder named "i2x00-v6.0" and extract out the following files to the "i2x00-v6.0" folder: README.combopkg Readme file for this package. drvrsetup Script file to copy driver source files included in the driver source tgz file. (See NOTE) i2xLNXsrc-.tgz Compressed binary distribution file for driver sources. This file is the same type of driver source tgz file as the ones used for distributing earlier versions of the QLA2X00 drivers. libinstall Script file to install/setup Expansion Card API library. libremove Script file to remove Expansion Card API library. qlapi--rel.tgz Compressed binary distribution file for API library. 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) 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 qla2300.o from the driver source code by typing: # make all SMP=1 For SuSE Linux 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. 8. Modify the modules.conf (RedHat) to load the correct device driver modules. Your modules.conf would look something like the following: alias scsi_hostadapter aic7xxx alias scsi_hostadapter2 qla2300 alias scsi_hostadapter3 qla2300 options scsi_mod max_scsi_luns=32 9. Load the driver manually by typing: # modprobe qla2300.o ============================================ 7.0 LOADING AND CONFIGURING THE DRIVER ------------------------------------------------------------------------ This section describes the different methods for loading and configuring the HS20 FC Expansion Card driver. 7.1 ENABLING MORE THAN ONE 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 qla2300 alias scsi_hostadapter3 qla2300 options scsi_mod max_scsi_luns=32 For 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. 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. 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. 7.2 LOADING THE DRIVER MANUALLY To load the driver manually, type the following command: # 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 qla2300 7.3 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 to the file /etc/modules.conf alias scsi_hostadapter1 qla2300 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. Note: This will be different for SuSE 8.0. 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 qla2300 4. Perform the following command to build the ramdisk image that contains the qla2300.o driver. /sbin/mkinitrd /boot/newinitrd-image Note: is the subdirectory under /lib/modules/"kernel_release" where the 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 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 /FAStT_Tools/FAStT_MSJ directory on the IBM HS20 Fibre Channel Expansion Card Support CD for information and files for this program. 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. 7.4 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 qla2300 driver module by opening a terminal window and typing: # 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 qla2300 ConfigRequired=1 ql2xopts=scsi-qla00- adapter- port=..." Refer to /FAStT_Tools/FAStT_MSJ directory on the IBM HS20 Fibre Channel Expansion Card Support CD for information and files for this program. 3. In the terminal windows type: depmod -a 4. Reload the qla2300 device drivers typing: # 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 NOTE: Refer to /FAStT_Tools/FAStT_MSJ directory on the IBM HS20 Fibre Channel Expansion Card Support CD for information and files for this program. 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 press to stop qlremote. 11. In the terminal windows type: depmod -a 12. Unload the 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. ============================================ 8.0 LIMITATIONS ------------------------------------------------------------------------ * 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 7.4 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. * 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. ============================================ 9.0 ADDITIONAL NOTES ------------------------------------------------------------------------ *Proc Filesystem Support The /proc filesystem for the driver can be found in the /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. ============================================ 10.0 DRIVER FILE CONTENTS ------------------------------------------------------------------------ i2x00-v6.0/ drvrsetup libinstall libremove i2xLNXsrc-v6.0-fo.tgz Config.in exioct.h exioctln.h inioct.h listops.h makefile Makefile.kernel ql2200_fw.h ql2200ip_fw.h ql2300_fw.h ql2300ip_fw.h qla2200.c qla2300.c qla2x00.c qla2x00.h qla2x00_ioctl.c qla_cfg.c qla_cfg.h qla_cfgln.c qla_dbg.h qla_debug.h qla_def.h qla_fo.c qla_fo.cfg qla_fo.h qla_gbl.h qla_inioct.c qla_ip.c qla_ip.h qla_mbx.c qla_mbx.h qla_settings.h qla_vendor.c qla_version.h qlfo.h qlfolimits.h qlfoln.h README.i2xLNX-v6.0.txt release.txt revision.notes sdm_fo.h qlapi-1.27b-rel.tgz doc/ doc/hbaapi.pdf doc/readme hba.conf lib/ lib/libqlsdm.so README.combopkg ============================================ 11.0 WEB SITES AND SUPPORT ------------------------------------------------------------------------- IBM Support Web Site: http://www.ibm.com/pc/support IBM eServer xSeries BladeCenter Marketing Web Site: http://www.ibm.com/servers/eserver/bladecenter If you have any questions or problems about this package go to the following Help Center World Telephone Numbers URL: http://www.ibm.com/planetwide ============================================ 12.0 TRADEMARKS ------------------------------------------------------------------------- IBM is a trademark of IBM Corporation in the United States, other countries, or both. The following terms are trademarks of the IBM Corporation in the United States or other countries or both: eServer BladeCenter Linux is a registered trademark of Linus Torvalds. Other company, product, and service names may be trademarks or service marks of others. ============================================ 13.0 NOTICES ------------------------------------------------------------------------- INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some jurisdictions do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. (C) Copyright IBM Corporation 1999, 2003. All rights reserved. Note to U.S. Government Users Restricted Rights -- Use, duplication, or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.