
This folder contains 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: 12/17/2002

=======================================================================

Contents
--------
1.0 OS Support
2.0 Supported Features
3.0 Release History
4.0 IBM HS20 Fibre Channel Expansion Card configuration
4.1 Update IBM HS20 Fibre Channel Expansion Card BIOS
4.2 Configure the NOVRAM Setting for the IBM HS20 Fibre Channel Expansion Card
5.0 Creating the Driver Diskette
5.1 Driver Disk for Adding Driver to Existing OS
6.0 Building a Driver from the Sources Code 
6.1 Building a Uni-Processor (UP) Version of the Driver
6.2 Building Symmetric Multi-Processor (SMP) Version of the Driver
7.0 Loading and Configuing the driver
7.1 Enable more than 1 scsi device per adapter
7.2 Install FAStT_MSJ
7.3 Loading the driver manually
7.4 Loading the driver using a ramdisk image
7.5 Rebuilding the ramdisk image after configuration changes.
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 6.0 device driver supports the following Linux versions using the 
vendor kernels:
EDIT THIS
* 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. 

This driver package contains the driver source code only. 
The device driver must be compiled from the souce 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
----------------------

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

Please refer to the Revision Notes.

=======================================================================
4.0  IBM HS20 Fibre Channel Expansion Card configuration
------------------------------

4.1 Update IBM HS20 Fibre Channel Expansion Card
    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 Configure the NOVRAM settings for the IBM IBM HS20 Fibre Channel Expansion Card
-------------------------------------------------------------------------

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 <CTRL-Q> 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 Download the IBM HS20 Fibre Channel Expansion Card driver source code 
------------------------------------------------------------------------

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 Sources 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:

	a) 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.

   The instructions in this step 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-<driver version>.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-<api lib version>-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 <space bar>

   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 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 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-<driver version>.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-<api lib version>-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 <space bar>

   NOTE: Refer to the your server installation  documentation to verify 
   that the proper processor family is selected for your server.  

   - select "Symmetric multiprocessor" press <space bar>

   - 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 Load and configure the driver
---------------------------------

7.1 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 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.3 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.4 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 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. 

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

   Note: <kernel_version> 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 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.


7.5 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=..."

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 
    <CTL - C> 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/<boot image> <kernel level>

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.5 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 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 Phone Number
---------------------------------------

    11.1  IBM Support Web Site:
                http://www.ibm.com/pc/support

    11.2  IBM eServer xSeries BladeCenter Marketing Web Site:
                http://www.ibm.com/servers/eserver/bladecenter

    11.3 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 and Notices
---------------------------

The following terms are trademarks of the IBM Corporation in the United 
States or other countries or both:


IBM xSeries 
IBM BladeCenter


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.







