                    QLogic iSCSI Driver
     for Red Hat Linux 8.0/9.0/Advanced Server 2.1/3.0
                       and SLES 8

Products supported:  QLA4010

07/08/2004



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 an 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
   5.3  Making a RAMDISK to Load the Driver Automatically

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 Persistent Binding Support
   8.3 Dynamically Added Devices

9.  Diskette Content

10. Contacting QLogic


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


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

This driver works with Red Hat Linux 8.0/9.0, Advanced Server 2.1/3.0
and SLES 8. Earlier or later versions of Linux are not supported in
this release.


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


2. Supported Features
---------------------

* Support up to 128 targets
* Support up to 128 LUNs


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


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

Please refer to Release Notes (release.txt).


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


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

Download qla4xxxsrc-v3.xx.tgz file from QLogic's website. If prompted
"What would you like to do with this file?" choose "Save this file
to disk". 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.
      Refer to the Driver Disk Kit documentation for the procedure to
      build Driver Diskettes.


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

From the source code you can build qla4010.o
drivers for your uniprocessor (UP) or symmetric multiprocessor (SMP)
system, then 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 (not required for Red Hat 9.0)
	       # rpm -iv kernel-source*.rpm (not required for Red Hat 9.0)
	
	2. Using the diskette you created in Section 4, copy the driver
	   source file - qla4xxxsrc-v3.xx.tgz to the qla4xxx directory:

	       # mkdir /usr/src/linux/drivers/scsi/qla4xxx
	       # cd /usr/src/linux/drivers/scsi/qla4xxx
	       # mount /mnt/floppy
	       # cp /mnt/floppy/*.tgz . (the period at the end is required)
	       # tar -xvzf *.tgz

	 3. Build the Driver qla4010.o from the source code by
	    typing:

	       # make SMP=0
	
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 source file
	   qla4xxxsrc-v3.xx.tgz to the qla4xxx directory:

	       # mkdir /usr/src/linux/drivers/scsi/qla4xxx
	       # cd /usr/src/linux/drivers/scsi/qla4xxx
	       # mcopy a:*.tgz . (the period at the end is required)
	       # tar -xvzf *.tgz

	5. Build the Driver qla4010.o from the source code by
	   typing:

	       # make SMP=0 OSVER=linux

NOTE: Please refer to Makefile for additional supported command
      line parameters.

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 Symmetric Multiprocessor (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 (not required for Red Hat 9.0)
	       # rpm -iv kernel-source*.rpm (not required for Red Hat 9.0)
	
	2. Prepare source headers for a SMP module build by first changing
	   to the kernel source directory:
	
	       # cd /usr/src/linux-2.4
	
	3. Type "make menuconfig" to configure additional support:
	
		(Make sure built-in support is selected for the following options)
	
	       - Select "Processor type and features" <Enter>
	
	       - Select "Symmetric multiproccessor"
	
	       - Select Exit to exit the Processor Menu.
	
	       - Select "SCSI Support" <Enter>
	
	       - Select "SCSI Disk Support"
	
	       - Select "SCSI Generic Support"
	
	       - Select Exit to exit the SCSI Menu.
	
	       - 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.
	
	4. Under kernel source directory type the following:
	
	       # make dep
	
	5. Using the diskette you created in Section 4, copy the driver
	   source file - qla4xxxsrc-v3.xx.tgz to the qla4xxx directory.
	   Follow these steps:
	
	       # mkdir /usr/src/linux/drivers/scsi/qla4xxx
	       # cd /usr/src/linux/drivers/scsi/qla4xxx
	       # mount /mnt/floppy
	       # cp /mnt/floppy/*.tgz . (the period at the end is required)
	       # tar -xvzf *.tgz
	
	6. Build qla4010.o driver from the source code by typing:
	
	       # make

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 source file
	   qla4xxxsrc-v3.xx.tgz to the qla4xxx directory. Follow these steps:

	       # mkdir /usr/src/linux/drivers/scsi/qla4xxx
	       # cd /usr/src/linux/drivers/scsi/qla4xxx
	       # mcopy a:*.tgz . (the period at the end is required)
	       # tar -xvzf *.tgz

	5. Build the Driver qla4010.o from the source code by
	   typing:

	       # make OSVER=linux

NOTE: Please refer to Makefile for additional supported command
      line parameters.

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

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.

- (For Advanced Users) To load the driver directly from the local build
  directory, type the following:

              # insmod ./qla4010.o

- To load the driver using modprobe:

       1. Copy driver binary files.  Type the following:

                # cp qla4010.o /lib/modules/<kernel version>/kernel/drivers/scsi/
          or
	  For RedHat Distribution:
		
		# make install (build the driver and copy to the right location)
		
          For SuSE Distribution:
	
		# make install OSVER=linux (build the driver and copy to the right location)


       2. Update the module dependency file.  You can either run "depmod -a"
          or make sure that the following line is in the
          /lib/modules/<kernel release version>/modules.dep file:


          /lib/modules/<kernel version>/kernel/drivers/scsi/qla4010.o: \
          /lib/modules/<kernel version>/kernel/drivers/scsi/scsi_mod.o

       3. Type the following to load the driver:

                   # modprobe qla4010


5.3  Making a RAMDISK to Load the Driver Automatically
-------------------------------------------------------
Perform the following steps to load the driver as a RAMDISK image
every time the system is rebooted.

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/
   by typing:

       # make install

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

              alias scsi_hostadapter0 qla4010

       NOTE: Add one entry for each HBA in the system. For example,
       If two QLA4010 HBAs are installed, add the following:

       alias scsi_hostadapter0 qla4010
       alias scsi_hostadapter1 qla4010

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

4. Type the following command to build the RAMDISK image that
   contains the qla4010.o module:

   For RedHat Distribution:

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

       Examples:
       # mkinitrd -f /boot/newinitrd-image.img 2.4.7-10
       # mkinitrd -f /boot/newinitrd-image.img 2.4.7-10smp

       NOTE: To get your kernel version before using the above comand, type:
       # uname -r

       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
       --------
	a) Add "initrd=/boot/<ramdisk file name>" in
           /etc/lilo.conf under one of the kernel entries
	   to use the RAMDISK image.

	b) Run "lilo" and reboot system. Select the kernel
	   with the new RAMDISK image to come up.
	
       On IA-64
       --------
	For RedHat Distribution:
	
	a) Add "initrd=<ramdisk file name>" in
	   /boot/efi/efi/redhat/elilo.conf under one of the kernel entries
	   to use the RAMDISK image.

	b) Reboot system and Select the kernel with the new RAMDISK image
	   to come up.

	For SuSE Distribution:
	
	a) Add "initrd=/<ramdisk file name>" in
	   /boot/efi/SuSE/elilo.conf under one of the kernel entries
	   to use the RAMDISK image.

	b) 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, NVRAM
Parameters and Driver Command Line Parameters sections.


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

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

Support for multiple LUNs may 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" (as described in BUILD_KERNEL.txt) 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:

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

              append="max_scsi_luns=128"

       b) Run "lilo" and reboot system.

   For GRUB:

       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 /vmlinuz-2.4.7-10 ro root=/dev/hda2 max_scsi_luns=128

       b) Reboot 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

  NOTE: If the SCSI Mid-Layer is loaded via the RAMDISK (i.e. Standard
        RedHat installations) then rebuild the RAMDISK.  (see section
	5.3)


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

None.


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

To display a list and description of supported command line parameters,
type the following at the command prompt:

	
	# modinfo qla4010.o
	

 Usage examples:

        # insmod qla4010.o ql4xmaxqdepth=2
        # insmod qla4010.o ql4xcmdretrycount=20
        # insmod qla4010.o displayConfig=1


Please refer to the Additional Notes section for a description of driver
command line parameters not described in modinfo.
	

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


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

Untested on 64-bit systems.


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


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


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

The /proc filesystem for the QLA4010 driver can be found
in the /proc/scsi/qla4010/ directory. This
directory contains a file for each QLogic iSCSI adapter in the system.
Each file presents information about the adapter and each discovered
lun.

Example:
    
    cat /proc/scsi/qla4010/3
    cat /proc/scsi/qla4010/4


8.2  Persistent Binding Support
--------------------------------

The Persistent Binding information consists of only adapter parameter
entries at this time.  Persistent Binding can be specified in two ways--
manually or using SANblade. We recommend using SANblade for ease of use.

Currently, there is a limit on the size of the binding information pass
thru the command line when using modprobe (4k) or when embedding the driver
in the kernel. These limits will be addressed in the future.

Persistent Binding can be specified in two ways-- manually or using
SANblade. We recommend using SANblade for ease of use.

The following is the procedure to manually add persistent binding
commands:

1. Displaying configuration

	displayConfig=<1 or 0>
	
   This command line parameter specifies whether to display the
   configuration information of discovered targets. If set to 1 then the
   driver will write the configuration information to console which is
   normally echoed to the /var/log/messages file.

2. Persistent Parameter(s)

   - Adapter descriptions:

	scsi-qla<#>-mac=<adapter mac address value>;
	
     The adapter is designated by qla<#>, where the <#> is the adapter
     instance number (NOT host number) in decimal format.

     The <adapter mac address value> parameter specifies the 6-byte
     M.A.C. address in hexadecimal format to be used for the adapter.

     Example:
	scsi-qla0-mac=00c0dd00f252\;
     host adapter instance 0 has a M.A.C address of 00-c0-dd-00-f2-52

3. Retrieving the Persistent information found during target discovery

   The driver displays the current configuration information at the end of
   the /var/log/messages file when the driver it initially loaded when the
   displayConfig=1 option is specified on the commandline (see above).

   The driver prints the configuration information in the required format
   to put directly on the command line. The best way to extract this
   information 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
   all the lines into a single line.

   The following example loads the driver and retrieves the information
   piped to temporary file:
	
   # insmod ./qla4010.o displayConfig=1
   # grep "scsi-qla" /var/log/messages > /tmp/info.cfg

   The /tmp/info.cfg file will contain the following driver bindings
   for the discovered ports:

	scsi-qla0-mac=00c0dd00f252\;
	scsi-qla1-mac=00c0dd00f253\;

4. Add binding information to the modules.conf file

   The /etc/modules.conf file is used by the modutil package (insmod/modprobe)
   as a means to pass configuration information to device driver.  Modprobe
   will load the driver and automatically read the /etc/modules.conf
   configuration file whereas insmod will only load the driver.

   a) Concatenated the above lines together to form a single long line as
      follows:

	options qla4010 displayConfig=1 ql4xopts=scsi-qla0-mac=00c0dd00f252\;scsi-qla1-mac=00c0dd00f253\;

      NOTE: The string should only span one line, do not attempt to split
	    onto multiple lines.
	
   b) Edit and save the above 'options' string into the /etc/modules.conf
      NOTE: After updating any information in the /etc/modules.conf file,
	    update module dependencies by executing the following command:

	# depmod -a

5. Loading driver with new persistent binding information
   To configure and load the qla4010 module with the driver
   persistent information you must do the following:

	
	# /sbin/modprobe -v qla4010


8.3 Dynamically Added Devices
------------------------------

Linux does not immediately recognize dynamically added devices.
Therefore, a manual scan must be performed using the /proc/scsi
interface.

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


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


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

The qla4xxxsrc-v3.xx.tgz files can be extracted into the following
files:

       Makefile.kernel
       Makefile
       Config.in
       ql4drvr.c
       ql4ioctl.c
       ql4nvram.c
       ql4print.c
       qla4000.c
       qla4010.c
       qla_opts.c
       ql4_sem.h
       ql4lists.h
       ql4nvram.h
       ql4print.h
       qla4x_fw.h
       qla4xxx.h
       qla_opts.h
       qlinioct.h
       qlisioct.h
       qlisioln.h
       qla4xxx.release.notes.txt
       revision.notes
       BUILD_KERNEL.txt
       README.qla4xxx - 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.


