                 QLogic Fibre Channel Driver
     for Red Hat Linux 7.2, 7.3, 8.0 and Advanced Server 2.1
             and Suse Linux 7.3, and Enterprise 7

Products supported: QLA22XX, QLA23XX

09/10/2002

Contents
--------

1. OS Support

2. Supported Features

3. Release History

4. Saving the Driver Source to Diskette

5. Installing the Driver

   5.1  Building the driver from the Source
   5.1.1. Building a Uni-Processor (UP) version of the driver
   5.1.2. Building a Symmetric Multi-Processor(SMP) version of the
          Driver
   5.2  Load the Driver Manually using INSMOD or MODPROBE
   5.3  Making a RAMDISK Image to Load the Driver

6. Driver Parameters

   6.1  System Parameters
   6.1.1  Multiple LUN Support
   6.2  NVRAM Parameters
   6.3  Driver Command Line Parameters

7. Limitations

8. Additional Notes

   8.1 Proc Filesystem Support
   8.2 Co-existence of QLogic 4.x and 6.x Linux Drivers
   8.3 Failover Support 
   8.3.1 How to enable the  Failover support in the Driver
   8.3.2 Using SANsurfer with QLA2XXX Driver the First Time
   8.3.3 Configuration Changes Made via SANsurfer
   8.4 Persistent Binding	

9. Diskette Content

10. Contacting QLogic


**********************************************************************


1. OS Support 
-------------

This driver works with Red Hat Linux 7.2, 7.3, and Advanced Server 
2.1 and Suse Linux 7.3 and Enterprise 7. Earlier or later versions 
of Linux may be supported but were not tested at the time of this 
release. Refer to the SUPPORTED_KERNEL_VERSION.txt file for a list
of kernel versions tested with this release.


**********************************************************************


2. 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
* IPFC support
* Non Failover and Failover capability


**********************************************************************


3. Release History
------------------

Please refer to Release Notes (release.txt).


**********************************************************************


4. Saving the Driver Source to Diskette
---------------------------------------

1. Download the failover or non-failover qla2x00-vx.yy.zz-dist.tgz
   distribution file from QLogic's website.

   * Failover compressed file has suffix "fo" while non failover 
     does not.		

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.


**********************************************************************


5. Installing the Driver 
------------------------

NOTE: Refer to the file BUILD_KERNEL.txt for instructions on how 
      to build a custom kernel with the QLogic Driver embedded.

5.1  Building a Driver from the Source Code 
-------------------------------------------

From the source code, you can build a qla2200.o or qla2300.o for
your UP or SMP system, and load the driver manually or automatically
using a RAMDISK image during system boot time.


5.1.1 Building a Uni-Processor (UP) Version of the Driver
---------------------------------------------------------

1. Extract the kernel-headers and kernel-sources RPM files from the 
   first RedHat CD:

       # cd /mnt/cdrom/RedHat/RPMS
       # rpm -iv kernel-headers*.rpm (not required for Red Hat 7.3)
       # rpm -iv kernel-source*.rpm

2. Using the diskette you created in Section 4, copy the
   qla2x00-vx.yy.zz-dist.tgz file to /qla2x00. Follow these steps from
   the "/" (root) directory:

       # mkdir qla2x00
       # cd qla2x00
       # mount /mnt/floppy
       # cp /mnt/floppy/*.tgz . (the period at the end is required)
       # tar -xvzf *.tgz
       # cd qlogic
       # ./drvrsetup (this will extract the driver source files to the 
                     current directory)

3. Build the Driver qla2200.o and qla2300.o from the source code by
   typing:

       # make all

   For SuSE Distribution:
	
       # make all OSVER=linux

4. To load the driver manually, see section 5.2. To make a RAMDISK
   image to load the driver during system boot time, see section 5.3.


5.1.2. Building a Symmetric Multi-Processor (SMP) Version of the Driver
-----------------------------------------------------------------------

1. Extract the kernel-headers and kernel-source RPM files from the 
   first RedHat CD:

       # cd /mnt/cdrom/RedHat/RPMS
       # rpm -iv kernel-headers*.rpm (not required for Red Hat 7.3)
       # rpm -iv kernel-source*.rpm

2. Using the diskette you created in Section 4, copy the
   qla2x00-vx.yy.zz-dist.tgz file to /qla2x00. Follow these steps from
   the "/" (root) directory:

       # mkdir qla2x00
       # cd qla2x00
       # mount /mnt/floppy
       # cp /mnt/floppy/*.tgz . (the period at the end is required)
       # tar -xvzf *.tgz
       # cd qlogic
       # ./drvrsetup (this will extract the driver source files to the
                     current directory)

3. Build the Driver qla2200.o and qla2300.o from the source code by
   typing:

       # make all SMP=1

   For SuSE Distribution:
	
       # make all SMP=1 OSVER=linux

4. To load the driver manually, see section 5.2. To make a RAMDISK 
   image to load the driver during system boot time, see section 5.3.


5.2  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 5.1.1 and 5.1.2.

- To load the driver directly from the local build directory, type
  the following:

       # insmod qla2200.o
               or
       # insmod qla2300.o        

- To load the driver using modprobe:

       1. Build the driver qla2200.o and qla2300.o from the source
          code by typing:

          # make all install

	  For SuSE Distribution:
	
       	  # make all OSVER=linux install

       2. To ensure that the older driver binary included in the
          original distribution does not interfere with the updated
          version, please rename the old driver binary as follows:

          # cd /lib/modules/<kernel_version>/kernel/drivers/addon/qla2200
          # mv qla2200.o qla2200_rh.o
          # mv qla2300.o qla2300_rh.o

       3. Type the following to load the Driver:

          # modprobe qla2200
                  or
          # modprobe qla2300


5.3  Making a RAMDISK Image to Load the Driver
----------------------------------------------

1. Build the Driver binary files (see 5.1.1 and 5.1.2).

2. Copy the files to:

     /lib/modules/<kernel version>/kernel/drivers/scsi/


NOTE:  To ensure that the older Driver binary included in the original
       distribution does not interfere with the updated version, 
       please rename the old Driver binary as follows:

       # cd /lib/modules/<kernel_version>/kernel/drivers/addon/qla2200
       # mv qla2200.o qla2200_rh.o
       # mv qla2300.o qla2300_rh.o

3. Add the following line to /etc/modules.conf.

       alias scsi_hostadapter0 qla2200
              or
       alias scsi_hostadapter0 qla2300

NOTE: Must add one entry for each HBA in the system. For example,
      If two QLA2200 hbas are installed add the following:

      alias scsi_hostadapter0 qla2200
      alias scsi_hostadapter1 qla2200

4. Type the following command:

         # mkinitrd -f <ramdisk image file name> <kernel version>

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 file to /boot.

   For SuSE Distribution:

       - Type the following command:

         # /sbin/mk_initrd

       NOTE: By default, the RAMDISK images created are:

         /boot/initrd
         /boot/initrd.suse

5. Configure the boot loader with the new RAMDISK image.  

   For LILO:

	Add "initrd=/boot/<ramdisk file name>" in 
	/etc/lilo.conf under one of the kernel entries 
	to use the RAMDISK image.
  
	Run "lilo" and reboot system. Select the kernel 
	with the new RAMDISK image to come up.

   For GRUB:

	Add "initrd=/boot/<RAMDISK file name>" in 
	/etc/grub.conf under one of the kernel entries 
	to use the RAMDISK image.

**********************************************************************


6. Driver Parameters
--------------------

The Driver parameters are divided into System Parameters and NVRAM 
Parameters sections.


6.1  System Parameters
----------------------

6.1.1  Multiple LUN Support
--------------------------

Support for multiple LUNs can be configured in one of three ways. 
Currently, the maximum number of LUNs that can be scanned for each
device is 128.

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 step 6, section 5.1) 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.

- If the SCSI Mid-Layer is compiled in the kernel, at boot time type the 
following at the boot prompt:

boot: linux max_scsi_luns=128

- 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

- If the SCSI Mid-Layer is not compiled as a module, the boot loader
can be configured to scan for multiple LUNs each time the system
boots.

For LILO, perform the following steps:

a) Add the following line to each of the kernel images listed in the
   /etc/lilo.conf file:

append="max_scsi_luns=128"

b) Run "lilo" and reboot the system.

For GRUB, perform the following steps:

a) Append the max_scsi_luns parameters to each of the kernel images 
listed in the /etc/grub.conf file. For example:

kernel /vmlinux-2.4.7-10 ro root=/dev/hda2 max_scsi_luns=128

b) Reboot the system.


6.2  NVRAM Parameters
---------------------

The NVRAM features described below are hard-coded in the Driver. The 
changes made for the particular NVRAM feature in the Fast!Util do not
take effect unless otherwise noted.

None.


6.3  Driver Command Line Parameters
-----------------------------------

The available command line options can be viewed using one 
or all of the three Linux commands depending on board type:

	# modinfo -p qla2300
	# modinfo -p qla2200
	# modinfo -p qla2100

The option "ql2xopts=" has additional sub-options as follows:

 verbose - Verbose detail debug information - on by default

 quiet   - Driver does not display normal messages to console:
              Waiting for LIP to complete....
              scsi%d: Topology - %s, Host Loop address 0x%x
              scsi(%d): LIP occurred
              scsi(%d): LIP reset occurred

 Usage examples:

           # insmod qla2200.o ql2xfailover=1
           # insmod qla2200.o qlport_down_retry=60
           # insmod qla2300.o ql2xopts="quiet"


**********************************************************************


7. Limitations
--------------

	N/A
 

**********************************************************************


8. Additional Notes
---------------------


8.1  Proc Filesystem Support
-----------------------------

The /proc filesystem for the QLA2200 and QLA2300 driver can be found
in the /proc/scsi/qla2200/ and /proc/scsi/qla2300/ directories. These 
directories contain a file for each QLogic Fibre Channel adapter
in the system. Each file will present information about the adapter
and transfer statistics for each discovered LUN.


8.2  Co-existence of QLogic 4.x and 6.x Linux Drivers
-----------------------------------------------------

The 4.x driver provides support for QLA2100, QLA2200, and QLA23xx.
The 6.x driver supports the QLA2200 and QLA23xx only. To make the
drivers "co-exist", perform the following:

  Option 1.  4.x support for QLA2100
             6.x support for QLA2200 and QLA23xx

	 o Remove QLA2200/QLA2300/QLA2312 support from the 4.x series
           driver:

	 - Edit the qla2x00.c file

	 - Look for the following line:

		{"QLA2300 ", QLA2300_DEVICE_ID,           MAX_BUSES,

	   OR

		{"QLA2312 ", QLA2312_DEVICE_ID,           MAX_BUSES,

	 - Above the found line, add this line:

	 	 #if 0

	 - The resulting lines should read as:

	 	 #if 0
	 	 {"QLA2300 ", QLA2300_DEVICE_ID,           MAX_BUSES,

	   OR

	 	 #if 0
	 	 {"QLA2312 ", QLA2312_DEVICE_ID,           MAX_BUSES,

	 - Look for the following line:

	 	 {"QLA2100 ", QLA2100_DEVICE_ID,           MAX_BUSES,

	 - Above the found line, add this line:

	 	 #endif

	 - The resulting lines should read as:

	 	 #endif
	 	 {"QLA2100 ", QLA2100_DEVICE_ID,           MAX_BUSES,

  Option 2.  4.x support for QLA2100 and QLA2200
             6.x support for QLA23xx

         o Remove QLA2300/QLA2312 support from the 4.x series driver:

	 - Edit the qla2x00.c file

	 - Look for the following line:

		{"QLA2300 ", QLA2300_DEVICE_ID,           MAX_BUSES,

	   OR

		{"QLA2312 ", QLA2312_DEVICE_ID,           MAX_BUSES,

	 - Above the found line, add this line:

	 	 #if 0

	 - The resulting lines should read as:

	 	 #if 0
	 	 {"QLA2300 ", QLA2300_DEVICE_ID,           MAX_BUSES,

	   OR

	 	 #if 0
	 	 {"QLA2312 ", QLA2312_DEVICE_ID,           MAX_BUSES,

	 - Look for the following line:

	 	 {"QLA2200 ", QLA2200_DEVICE_ID,           MAX_BUSES,

	 - Above the found line, add this line:

	 	 #endif

	 - The resulting lines should read as:

	 	 #endif
	 	 {"QLA2200 ", QLA2200_DEVICE_ID,           MAX_BUSES,


8.3 Failover Support
---------------------

8.3.1 How to enable the  Failover support in the Driver
-------------------------------------------------------

Failover support can be enabled in the QLA2XXX driver by enabling the
macro MPIO_SUPPORT in qla_settings.h file ie

#define MPIO_SUPPORT                    1

or specifying the option on the commandline:
	insmod qla2300 ql2xfailover=1

Note: The failover distribution package, qla2x00-vx.yy.zz-fo-dist.tgz, 
has the above macro enabled by default.

8.3.2 Using SANsurfer with QLA2XXX Driver the First Time
________________________________________________________

1. To work with SANsurfer, the driver should always be built
   with MPIO_SUPPORT set to 1 in qla_settings.h.

2. Add the following parameter in modules.conf file:

   options qla2200 ConfigRequired=1 ql2xopts=
             or
   options qla2300 ConfigRequired=1 ql2xopts=

3. Now you can load the driver and SANsurfer.


8.3.3 Configuration Changes Made via SANsurfer
--------------------------------------------

1. LUN Masking

   For the new LUN masking configuration to take effect, the
   driver must be reloaded.  The following is an example of
   the sequence of actions to take:

   - Load the driver:

     modprobe <driver>

   - Load the qlremote agent.

   - Start the GUI and connect it to the destination system.

   - Make LUN masking changes.

   - Disconnect the host from GUI and stop qlremote agent.

   - Unload the driver:

     modprobe -r <driver>

   - Reload the driver:

     modprobe <driver>

   - Load qlremote agent again.

   - Start the GUI and connect it to the destination system.

   Now you should see the updated LUN masking configuration.

Please note that when using modprobe to load the driver, the
length of the option line specified in /etc/modules.conf file
has a limit of 2K characters. Any longer option line will cause
a string overflow error from modprobe.


8.4 Persistent Binding
______________________


The Persistent Binding information consists of some adapter parameter
entries along with some target entries. However, the Linux entries 
have been shorten to save space on the command line. Currently, there
is no limit on the size of the command line when using modprobe. But,
if you embedded the driver in the kernel you are using lilo that has 
a string size limitation.

Persistent Binding  can be specified in two ways. Manually or using
SANsurfer. We recommend using SANsurfer for ease of use. Reference 
section 8.3.3 for additonal information about SANsurfer. The 
following is the procedure to manually add persistent binding 
commands: 

The driver displays the current configuration when the displayConfig
command line option is specified. The persistent binding 
configuration is found in /var/log/messages file. It prints the 
configuration information in the format required by the driver.
The best way to extract configuration messages is to use grep and 
direct the output to a file. You need to remove the Linux timestamp at
the beginning of each message and combine them together on single line.
For example
        #insmod qla2200 displayConfig=1
        #grep "scsi-qla" /var/log/messages > /tmp/info.cfg

The format of the persistent binding commands is as follows: 

Device descriptions

scsi-qla<#>-adapter-port=<adapter port name value>;
The designated by qla<#>, where the <#> is the adapter instance number.

The parameter specifies the FC port name to be used for the adapter.
where <adapter port name value> is the FC port name value in hexa-
    decimal format.  If this entry is not specified in the conf file,
    the default value is the adapter's port name as saved in the NVRAM.
Example:
scsi-qla00-adapter-port=210000e08b01158d\;

host adapter instance 0 has a portname of 210000e08b01158d

scsi-qla<#1>-tgt-<#2>-di-<#3>-node=<device FC name>;
This parameter associates the specified <device FC name> with the
SCSI target ID value specified by <#2> and a device id value specified
by <#3>. where <device FC name> type is the FC node name of the 
device, and <#2> is the SCSI target ID to be assigned to the device 
and <#3> is the device unique id.
Where
   <#1>   Specifies the adapter instance number   
   <#2>   Specifies the SCSI ID of Target
   <#3>   Specifies the path/device id	

scsi-qla<#1>-tgt-<#2>-di-<#3>-port=<device FC name>;
This parameter associates the specified <device FC name> with the
SCSI target ID value specified by <#2> and a device id value specified
by <#3>. where <device FC name> type is the FC port 
Where
   <#1>   Specifies the adapter instance number   
   <#2>   Specifies the SCSI ID of Target
   <#3>   Specifies the path/device id	(always 0 for non-failover)

name of the device, and <#2> is the SCSI target ID to be assigned to 
the device and <#3> is the device unique id.

scsi-qla<#1>-tgt-<#2>-di-<#3>-disabled=<256 bit mask>;
This parameter associates the specified <256 bit mask> with the
SCSI target ID value specified by <#2> and a device id value specified
by <#3>. 

Where
   <#1>   Specifies the adapter instance number   
   <#2>   Specifies the SCSI ID of Target
   <#3>   Specifies the path/device id	

<256 bit mask>
msb                                                            lsb
 000000000000000000000000000000000000000000000000000000000000000F

the mask above will make the first four luns, 3, 2, 1, and 0 of a 
given Target disabled on that target/path.

This mask specification is heavily type checked to be a sequence of
64 hex digits.

**********************************************************************


9. Diskette Content 
--------------------

The qla2x00src-vx.yy.zz-*.tgz files within the downloaded
distribution package can be extracted into the following files:

       listops.h
       Makefile.kernel
       Config.in
       makefile
       qla_settings.h
       qla_debug.h
       ql2100_fw.h
       ql2200_fw.h
       ql2300_fw.h
       ql2200ip_fw.h
       ql2300ip_fw.h
       qla2100.c
       qla2200.c
       qla2300.c
       qla2x00.c
       qla2x00.h
       qla2x00_ioctl.c
       qla_vendor.c
       qla_cfg.c
       qla_cfgln.c
       qla_fo.c
       qla_fo.cfg 
       qla_inioct.c
       qla_ip.c
       qla_mbx.c
       qla_mbx.h
       exioctln.h
       exioct.h
       inioct.h
       qla_cfg.h
       qla_fo.h
       qla_gbl.h
       qla_ip.h
       qlfo.h
       qlfolimits.h
       qlfoln.h
       qla_version.h
       revision.notes - Revision history
       release.txt - Release notes
       README.qla2x00 - This file


**********************************************************************


10. Contacting QLogic 
---------------------

Please visit QLogic's website (www.qlogic.com). On this site you will
find product information, our latest drivers, and links for technical
assistance if needed.


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


    Copyright (c) 2003 QLogic Corporation. All rights reserved 
    worldwide. 
