                 QLogic Fibre Channel Driver

Products supported: QLA22XX, QLA23XX

08/07/2003

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
   8.5 Configuration Data
   8.5.1 Limitations With /etc/modules.conf
   8.5.2 QLA_OPTS As An Alternative
   8.5.3 Compatibility With SMS (SANsufer Management Suite)
   8.5.4 Persisting Configuration Data While Upgrading Drivers
   8.5.5 Manual Configuration Update
   8.6 How to Force Rescan of Devices
   8.7 Creating a Driver Disk (DD-Kit) image.

9. Diskette Content

10. Contacting QLogic


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


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

Refer to the SUPPORTED_KERNEL_VERSION.txt file for a list of kernel
versions and different distributions 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 Distribution / Source file to Diskette
-----------------------------------------------------------

1. Download the failover or non-failover distribution file
   - qla2x00-vx.yy.zz-dist.tgz or the driver source file
   - qla2x00-vx.yy.zz.tgz 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 
------------------------

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

For RedHat Distribution:

	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 
	       # rpm -iv kernel-source*.rpm

	2. Using the diskette you created in Section 4, copy the distribution
	   file - qla2x00-vx.yy.zz-dist.tgz or the driver source file - 
	   qla2x00-vx.yy.zz.tgz 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

	       (Execute the following additional steps if you have copied
		the distribution file - qla2x00-vx.yy.zz-dist.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:

	1. Install the kernel-source from the SuSE distribution CD-ROM 
	   by typing:	

	       # yast  or
	       # yast2 

	2. Create a soft link ( /usr/src/linux) to the kernel source 
	   (/usr/src/<linux-version>) by typing:

	       # ln -sf /usr/src/<linux-version> /usr/src/linux

	3. To ensure kernel version synchronization between the driver and
	   running kernel, type the following:

	      	# cd /usr/src/linux
		# make mrproper (completely clean the kernel tree) 
		# cp /boot/vmlinuz.config .config (copy the new config) 
		# make oldconfig (update configuration using .config) 
		# make dep (rebuild the dependencies) 
		# make modules (build the modules) 

	4. Using the diskette you created in Section 4, copy the distribution 
	   file - qla2x00-vx.yy.zz-dist.tgz or the driver source file 
	   - qla2x00-vx.yy.zz.tgz 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

	       (Execute the following additional steps if you have copied
		the distribution file - qla2x00-vx.yy.zz-dist.tgz )
	       
	       # cd qlogic
	       # ./drvrsetup (this will extract the driver source files to the 
			     current directory)

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

	       # make all OSVER=linux


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

For RedHat Distribution:

	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 
	       # rpm -iv kernel-source*.rpm

	2. Using the diskette you created in Section 4, copy the distribution 
	   file - qla2x00-vx.yy.zz-dist.tgz or the driver source file - 
	   qla2x00-vx.yy.zz.tgz 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

	       (Execute the following additional steps if you have copied
		the distribution file - qla2x00-vx.yy.zz-dist.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:

	1. Install the kernel-source from the SuSE distribution CD-ROM
	   by typing:	

	       # yast  or
	       # yast2 

	2. Create a soft link ( /usr/src/linux) to the kernel source 
	   (/usr/src/<linux-version>) by typing:

	       # ln -sf /usr/src/<linux-version> /usr/src/linux

	3. To ensure kernel version synchronization between the driver and
	   running kernel, type the following:

	      	# cd /usr/src/linux
		# make mrproper (completely clean the kernel tree) 
		# cp /boot/vmlinuz.config .config (copy the new config) 
		# make oldconfig (update configuration using .config) 
		# make dep (rebuild the dependencies) 
		# make modules (build the modules) 

	4. Using the diskette you created in Section 4, copy the distribution
	   file - qla2x00-vx.yy.zz-dist.tgz or the driver source file 
	   - qla2x00-vx.yy.zz.tgz 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

	       (Execute the following additional steps if you have copied
		the distribution file - qla2x00-vx.yy.zz-dist.tgz )
	       
	       # cd qlogic
	       # ./drvrsetup (this will extract the driver source files to the 
			     current directory)

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

	       # make all SMP=1 OSVER=linux


NOTE: 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 (build the driver and copy to the right location)

	  For SuSE Distribution:
	
          # make all OSVER=linux install (build the driver and copy to the right location)

       2. 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_conf
       alias scsi_hostadapter1 qla2200
              or
       alias scsi_hostadapter0 qla2300_conf
       alias scsi_hostadapter1 qla2300

   NOTE: Add one entry for each HBA in the system. For example,
      If an QLA2200 and QLA2300 HBAs are installed add the following:

       alias scsi_hostadapter0 qla2200_conf
       alias scsi_hostadapter1 qla2200
       alias scsi_hostadapter2 qla2300_conf
       alias scsi_hostadapter3 qla2300

   For SuSE Distribution:

	You will need to modify the /etc/sysconfig/kernel file to specify
	while modules will be added during initrd creation.

	NOTE: Please ensure the conf module is listed before the actual
	      driver module.  For example:

	    INITRD_MODULES="aic7xxx qla2300_conf qla2300 qla2200_conf qla2200"

4. Type the following command:

   For RedHat Distribution:

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

      On IA-32
      --------
       - Copy the newly built <ramdisk image file name> file to /boot. 	

      On IA-64
      --------
       - Copy the newly built <ramdisk image file name> file to 
         /boot/efi/efi/redhat

   For SuSE Distribution:

         # /sbin/mk_initrd

         By default, the RAMDISK images created are:

         /boot/initrd
         /boot/initrd.suse

	   NOTE: This step will overwrite the original ramdisk image file. 
                 To preserve the original ramdisk image specify a unique 
		 ramdisk image name as follows:

         # /sbin/mk_initrd  -k <kernel name>  -i <ramdisk image file name>
	 

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

   For LILO:
	On IA-32
	--------
	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.
	
	On IA-64 
	--------
	For RedHat Distribution :
	
	Add "initrd=<ramdisk file name>" in 
	/boot/efi/efi/redhat/elilo.conf under one of the kernel entries 
	to use the RAMDISK image.
  
	Reboot system and Select the kernel with the new RAMDISK image 
	to come up.

	For SuSE Distribution :
	
	Add "initrd=/<ramdisk file name>" in 
	/boot/efi/SuSE/elilo.conf under one of the kernel entries 
	to use the RAMDISK image.
  
	Reboot system and Select the kernel with the new RAMDISK image 
	to come up.


   For GRUB:

	For RedHat Distribution :

	a) Add "initrd /<RAMDISK file name>" 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.

	For SuSE Distribution :

	a) Add "initrd (hd0,1)/boot/<RAMDISK file name>" in /boot/grub/menu.lst
	   file under one of the kernel entries to use the RAMDISK image.
	   For example:

		kernel (hd0,1)/boot/vmlinuz root=/dev/hda2  max_scsi_luns=128
		initrd (hd0,1)/boot/initrd

	b) Reboot the system.


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


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.

(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" 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.

	On IA-32
	---------

	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:

	For RedHat Distribution :

	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.

	For SuSE Distribution :

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

	kernel (hd0,1)/boot/vmlinuz root=/dev/hda2  max_scsi_luns=128

	b) Reboot the system.

	On IA-64
	--------
	For RedHat Distribution :

	a) Add the following line to each of the kernel images listed in the
	   /boot/efi/efi/redhat/elilo.conf 

		append="max_scsi_luns=128"
	b) Reboot the system.

	For SuSE Distribution :

	a) Add the following line to each of the kernel images listed in the
	   /boot/efi/SuSE/elilo.conf 

		append="max_scsi_luns=128"
	b) Reboot the 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
	
    and rebuild the RAMDISK image. For details on how to build the RAMDISK 
    image refer to steps 4 and 5 in section 5.3


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>;
OR
<#>-w=<adapter port name value>;    ** shorten format **
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>;
OR
<#1>-<#2>-<#3>-n=<device FC name>;	** shorten format **
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>;
OR
<#1>-<#2>-<#3>-p=<device FC name>;	** shorten format **
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>;
OR
<#1>-<#2>-<#3>-d=<256 bit mask>;	** shorten format **
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.


8.5 Configuration Data
----------------------

To pass the configuration data to the driver, load it using "modprobe" 
instead of "insmod".

8.5.1 Limitations With /etc/modules.conf
----------------------------------------

Due to size constraints inherent in the user-space applications which load
kernel modules, the total amount of configuration data that could be passed via
modules.conf by the modprobe application was around 4096 bytes of information
(with minor tuning of the modutil package).  Of course, as densities of SANs
increase, larger configuration spaces are needed to accommodate the
information.

In general, the following formula can be used to compute an approximate size in
bytes of the configuration data needed to store information pertaining to 'M'
HBAs and 'N' targets/device paths:

	75 + 42*M + 381*N

Plugging in values for common configurations returns some sample results:

	2 same type HBAs - (75 + 2*42 == 159)
	----------------
	1 target	- 75+2*42+381*1	= 540 bytes
	2 targets	- 75+2*42+381*2	= 921 bytes
	3 targets	- 75+2*42+381*3	= 1302 bytes
	4 targets	- 75+2*42+381*4	= 1683 bytes
	5 targets	- 75+2*42+381*5	= 2064 bytes
	...

	3 same type HBAs	(75 + 3*42 == 201)
	----------------
	1 target	- 75+3*42+381*1	= 582 bytes
	2 targets	- 75+3*42+381*2	= 963 bytes
	3 targets	- 75+3*42+381*3	= 1344 bytes
	4 targets	- 75+3*42+381*4	= 1725 bytes
	5 targets	- 75+3*42+381*5	= 2086 bytes
	...
		
Please note, a target in this case does not always indicate a distinct piece of
storage -- it could represent 'n' paths to the same storage, as is the case
with failover in a true-cloud configuration.  As an example, the configuration
data size needed for two storage devices with four paths (via two HBAs) to each
storage (4*2 paths) would need approximately 3200 bytes (75 + 42*2 + 381*8) of
configuration space.

8.5.2 QLA_OPTS As An Alternative
--------------------------------

Modutil (namely modprobe) loads 'option' data present in the modules.conf file
by first loading the module, parsing the 'options' directive of the newly
loaded module for parameters (parameters are simple key=value directives, i.e.
ql2xfailover=1), for each key, scan the memory area where the module was loaded
for the location of the 'key' parameter, and finally, writing the key's 'value'
directly into the pre-defined memory space.  This basic mechanism is similar in
nature to the mechanism employed by the QLA_OPTS application, but does not
suffer from the relatively small size constraints within the modutil package.

There are two important differences between the modutil and QLA_OPTS mechanism:

	1) Configuration data is read from a configuration file in /etc/ with a
	   name based on the ISP type:

		Configuration File  Module name
		------------------  -----------
		/etc/qla2200.conf   qla2200_conf
		/etc/qla2300.conf   qla2300_conf

	2) Option values are written directly (branded) to the corresponding
	   configuration module file.

Approximately 300K of configuration space has been pre-allocated within the
qla2200_conf/qla2300_conf module.

8.5.3 Compatibility With SMS (SANsufer Management Suite)
--------------------------------------------------------

QLA_OPTS will work seamlessly with updated SMS applications.  Originally, when
an SMS application would save a configuration the corresponding data would be
written to the 'options' section of the modules.conf file in a form similar to
the following:

	ql2xopts=scsi-qla0-adapter-port=210000e08b000000\;scsi-qla0-tgt-1-di-0-node=20000020371682e7\;scsi-qla0-tgt-1-di-0-port=21000020371682e7\;scsi-qla0-tgt-1-di-0-pid=0000e2\;scsi-qla0-tgt-1-di-0-control=00\;

Now, the information is written to the appropriate qla2[2|3]00.conf file in
/etc and then branded to the binary file of the corresponding configuration
module (qla2200_conf.o or qla2300_conf.o):

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

Where CURRENT_KERNEL_VERSION is the the result of the command 'uname -r'.  This
operation is performed automatically and requires no user intervention.  Of
course, if the driver was loaded from an initrd image, as before with the
modules.conf interface, the user would be required to rebuild the initrd image
after updating a configuration.

8.5.4 Persisting Configuration Data While Upgrading Drivers
-----------------------------------------------------------

To persist configuration data during a driver update (e.g. 6.05.00b10 ->
6.05.00b11), the 'install' directive during the make process will read the
proper qla[2|3]00.conf file and write the previous configuration into the newly
built configuration module binaries, which are built the same time while the
driver is built.  See section 5.2 for instruction on how to build the driver.

8.5.5 Manual Configuration Update
---------------------------------

Manual update to the /etc/qla2[2|3]00.conf file is strongly discouraged.
The configuration data is actually saved in the qla2200_conf/qla2300_conf
module binary file, and the /etc/qla2[2|3]00.conf file is for reference
purpose only.  Therefore at any time the pair must be kept in sync.

Only correct module configuration can guarantee a successful driver load.
To ensure correct configuration data is written, it is recommended to use
the SMS suite for saving configuration.

However, in the event that some persistent configuration value must be
changed manually, it is possible to first change the /etc/qla2[2|3]00.conf
file, then run "make install" from the driver's build directory to update
the configuration module binary file.

8.6 How To Force Rescan Of Devices
----------------------------------

Starting from driver version v6.06.00b12 there is support for the mechanism
which allows the user to force the driver to do re-scan of the devices to
allow a new device to be added. This triggers the driver to initiate lun
discovery process.

To do this from the command line: 

# echo "scsi-qlascan" > /proc/scsi/<driver-name>/<adapter-id>
(qlogic driver will re-scan)

Where <driver-name> can be either one : qla2100/qla2200/qla2300	
<adapter-id> is the instance number of the HBA.

Once that has been done , user then can force the scsi mid layer to do its
own scan and build the device table entry for the new device:

# 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". 

The scanning has to be done in the above mentioned order. First the driver
(qla2300/qla2200 driver etc) and then the Linux scsi mid layer (i.e. OS scan)
later.

8.7 Creating a Driver Disk (DD Kit) image
-----------------------------------------
The driver disk (DD Kit) image enables to install the RedHat/SLES 8 OS 
and Qlogic driver(qla2300) on the Fibre Channel boot disk connected to the
QLogic Host Bus adapter(QLA23XX).

For RedHat Distribution :

To build the driver disk image file for QLA23XX HBA's and RedHat 
distribution perform the following steps:

(1) Download the sample kit (how_to_build_dd_kit.tgz) provided 
    at the following URL:

	http://www.qlogic.com/support/os_detail.asp?productid=253&osid=26

(2) Untar the tgz file:

	# tar -xvzf *.tgz

(3) Follow the instruction outlined in "HOW-TO-BUILD-dd-kit.txt" file to 
    build the driver disk image file using the sample kit 
    - mod_devel_kit.tgz as an example.

For SuSE Distribution:

On IA-32
--------
The driver disk image for QLA23XX HBA's is provided only for SLES 8 
- IA-32 arch:

(1) Download the driver disk image(-qla2x00_SLES8_IA32_v6.00.06.img.gz)
    from the following URL:	

        http://www.qlogic.com/support/os_detail.asp?productid=253&osid=26

(2) Extract the driver disk image file as follows:

	# gunzip qla2x00_SLES8_IA32_v6.00.06.img.gz

(3) Insert a blank diskette into the diskette drive and copy the extract
    driver disk image to the diskette as follows:
       
        # dd if=qla2x00_SLES8_IA32_v6.00.06.img.gz of=/dev/fd0 bs=1440k
    
(4) Boot the system to be installed from the first installation CD of 
    SLES 8 at Yast2 screen.

(5) Press the "ALT" key and a message will be displayed directing to have 
    the driver diskette ready.
    
(6) Press the <Enter> key.

(7) Insert the driver diskette into the diskette drive when prompted and 
    press the <Enter> key.

(8) Continue with the Yast2 installation process and select one of the
    attached Fibre Channel disk as the installation target.

(9) Continue following the Yast2 installation instructions.

On IA-64
--------
Perform the following steps to install SLES 8 on IA-64 bit platform:

(1) Boot off from the first installation CD and continue with the Yast2
    installation instruction to the point where menu comes up to "Accept
    the Software license terms".Select "Cancel" to abort the installation.
    
(2) The installer will launch another menu as the result of step 1.From
    the "Main Menu" select "Kernel modules (hardware drivers) and press
    "OK".
    
(3) Select Load IDE/SCSI/RAID/SCSI modules and press "OK".

(4) Scroll the cursor down to the following entry: "qla2300: QLogic ISP2300" 	    and press "OK".

(5) Next screen will be:
    "Please enter parameters for qla2300"	
     No parameters are necessary for default load and press "Enter".
     
(6) Wait for the following message : "qla2300 loaded successfully"

(7) Select "Back" to return to the Main Menu.

(8) Select "start installation/system" and press "OK"

(9) Select "start installation/update" and press "OK"

(10) Select "CDROM" and press "OK"

(11) Continue with the Yast2 installation process and select one of the
    attached Fibre Channel disk as the installation target.

(12) Continue following the Yast2 installation instructions.
     
**********************************************************************


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
       qla_devtbl.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
       qla2200_conf.c
       qla2300_conf.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
       qla_opts.c
       qla_opts.h
       revision.notes - Revision history
       release.txt - Release notes
       SUPPORTED_KERNEL_VERSION.txt
       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. 

