1. OS Support

Products supported: ISP24XX, ISP23XX, ISP63XX, ISP22XX
08/04/2005

This driver works with Linux kernel 2.6.x distributions -- including SuSE Linux Enterprise Server 9 and Red Hat Enterprise Linux 4.

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
• Non Failover and Failover capability

3. Release History

Please refer to Release Notes provided in the package (release.txt).

4. Saving the Driver Source to Diskette

1. Download the qla2xxx-vx.yy.zz-dist.tgz file from QLogic's web-site.
2. If prompted "What would you like to do with this file?" select Save this file to disk.
3. Insert a blank diskette and download to the diskette directly.

5. Installing the Driver

This section makes extensive use of the build.sh script located in driver source (extras/build.sh). This script currently supports driver compilation (installation and updates) on SLES9 and RHEL4 distributions on four main hardware platforms (x86, x86_64, ia64 and ppc64).

The build.sh script supports for following directives:
# ./extras/build.sh

Build the driver sources based on the standard SLES9/RHEL4 build environment.
# ./extras/build.sh clean

Clean driver source directory of all build files (i.e. *.ko, *.o, etc).
# ./extras/build.sh new

Rebuild the driver sources from scratch.
This is essentially a shortcut for:
# ./build.sh clean
# ./build.sh
# ./extras/build.sh install

Build and install the driver module files.

This command performs the following:

1. Builds the driver .ko files.
2. Copies the .ko files to the appropriate /lib/modules/... directory.
3. Adds the appropriate directive in the modprobe.conf[.local] to remove the qla2xxx_conf module when the qla2xxx modules in unloaded.
4. Updates the newly built qla2xxx_conf.ko module with any previously saved data in /etc/qla2xxx.conf.
# ./extras/build.sh initrd

This section is for SLES 9 only. Go to section 5.3.1 for RHEL 4 installation.

Build, install, and update the initrd image.
This command performs the following:

1. All steps in the install directive.
2. Adds an qla2xxx_conf entry into the /etc/sysconfig/kernel INITRD_MODULES if and only if a qla2xxx module already is present in the listing.
3. Rebuilds the initrd image with the /sbin/mk_initrd command.

NOTE: One should insure that the additional qla2xxx_conf module is appropriately added after initiating this directive. The script is coded to do its 'best' at insuring the entry is placed in the proper order.

5.1 Building a Driver from the Source Code

From the source code, you can build a qla2xxx.ko and a qla2200.ko, qla2300.ko, qla2322.ko, qla6312.ko, or qla2400.ko for your host system, and load the driver manually or automatically using a RAMDISK image during system boot time.

1. Insure the appropriate build environment is present on the system. For example, for SLES9, the kernel-headers and kernel-sources RPM files are required.
   # cd /mnt/cdrom/SuSE/RPMS (#cd /mnt/RedHat/RPMS for RHEL 4.)
   # rpm -ivh kernel-source*.rpm
# rpm -ivh kernel-syms*.rpm
   RHEL 4 does not require the kernel source to be installed to build the qla2xxx modules.
2. Using the diskette you created in Section 4, copy the qla2xxx-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/*.[bz2|gz] . (the period at the end is required)
   # tar -xvzf *.tgz
# cd qlogic
# ./drvrsetup (this will extract the source files directory in to the current directory)
   # cd qla2xxx-x.yy.zz
3. Build the Driver modules from the source code by executing the build.sh script.
   # ./extras/build.sh
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. To load the driver directly from the local build directory, load the driver in following in order:
   # insmod qla2xxx_conf.ko or
# insmod qla2xxx.ko or
# insmod qla2300.ko
2. To load the driver using modprobe, install the driver modules (*.ko) files to the appropriate kernel module directory:
   # ./extras/build.sh install
3. Type the following to load the driver:
   # modprobe -v qla2300 (QLA246X/QLE246X, QLA23XX) or,
# modprobe -v qla2322 (QLE236X) or,
# modprobe -v qla2400 (QLA24XX/QLE24XX)
   NOTE: The modprobe -v qla2300 command will automatically load the qla2xxx.ko and qla2xxx_conf components.
4. To unload the driver using modprobe:
   # modprobe -r qla2300
   This will unload qla2300.ko and qla2xxx.ko modules.
   # modprobe -r qla2xxx_conf
   This will unload qla2xxx_conf.ko

5.3 Making a RAMDISK Image to Load the Driver

The build.sh script can be used to update and create and initrd image:
# ./extras/build.sh initrd
This script directive has been tested on SLES9 distributions only.

5.3.1 RHEL 4 RAMDISK Image

To build the RAMDISK image perform the following steps:

1. Follow the steps in section 5.1.
2. Install the driver modules (*.ko) files to the appropriate kernel module directory:
   # ./extras/build.sh install
3. Edit the /etc/modprobe.conf file and add the following entries:
   alias scsi_hostadapter2 qla2xxx_conf (SANsurfer use only)
alias scsi_hostadapter3 qla2322 (QLE236X) or qla2300 (QLA234X) or
alias scsi_hostadapter4 qla2400 (QLA24XX)
4. Change to the /boot directory.
5. Build the RAMDISK image by executing the following command:
   # mkinitrd -f initrd-2.6.[kernel_version].img [kernel_version]
6. Reboot the system to load the RAMDISK image with the QLogic driver.

6. Driver Parameters

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

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

6.2 Driver Command Line Parameters

The driver gets its parameters from the command line itself or from modprobe 'option' directive found in the modprobe.conf[.local] file. The parameters are in simple <keyword>=value format, i.e. ql2xfailover=1. Where <keyword> is one of the following option parameters:
Usage: insmod qla2xxx.ko <keyword>=value

• ql2xfailover - This parameter defines whether failover mode is enable or disable. 0 to disable; 1 to enable. Default: 1.
• ql2xmaxqdepth - This parameter defines the maximum queue depth reported to Scsi Mid-Level per device. The Queue depth specifies the number of outstanding requests per lun. Default: 32.
• ql2xlogintimeout - This parameter defines the Login timeout value in seconds during the initial login. Default: 20 seconds
• qlport_down_retry - This parameter defines how long to wait for a port that returns a PORT-DOWN status before returning I/O back to the OS. Default: 0 (use value specified in NVRAM)
• ql2xretrycount - This parameter defines the maximum number of Scsi Mid-Level retries allowed per command. Default: 20 (standard mode value), 30 (failover mode value)
• displayConfig - This parameter defines whether to display the current configuration. 0 - don't display the configuration; 1 - display the configuration. Default:
• Bind - This parameter defines what target persistent binding method to use: 0 - bind by Portname and 1 - bind by PortID. Default: 0 (portname binding)
• ConfigRequired - This parameter defines how to bind the devices. 0 - Present all the devices discovered to the OS. 1 - Present only the configured devices (i.e. the device defined in /etc/qla2xxx.conf) to the OS. Default: 0
• MaxPathsPerDevice - This parameter defines maximum number of paths to a device. Default: 8 (compile time only)
• MaxRetriesPerPath - This parameter defines how many retries to perform on the current path before failing over to the next path in the path list. Default: 3
• MaxRetriesPerIo - This parameter defines total retries to do before failing the command and returning to the OS with selection timeout (DID_NO_CONNECT). Default: MaxRetriesPerPath * MaxPathsPerDevice ) + 1
• QlFailoverNotifyType - This parameter defines type of failover notification mechanism to use when a failover or failback occurs. Certain storage systems require special CDBs to be issued to do failover or failback. Default: 0 (none)
• FailbackTime - This parameter defines the delay in seconds before a failback is performed to ensure all paths are available. Default: 5 seconds
• RecoveryTime - This parameter defines the recovery time in seconds required before commands can be sent to the restored path. Default: 10 seconds
• A comprehensive list of parameters can be found with the following command line:
  # /sbin/modinfo qla2xxx.ko

7. SNIA API Library Package

Its distributed (qlapi-<api_version>-rel.tgz) as part of driver combo package qla2xxx-vx.yy.zz-dist.tgz. and Source RPM package as well.

7.1 Using Driver Combo Package

Using the diskette you created in Section 4, copy the distribution file - qla2xxx-vx.yy.zz-dist.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
# cd qlogic

7.1.1 Installing SNIA API Library

Type the following command in current directory to install/setup API library:
# ./libinstall (this installs/sets up HBA API library)

7.1.2 Uninstalling SNIA API Library

Type the following command in current directory to remove API library:
# ./libremove (Script file to remove HBA API library)

8. Additional Notes

8.1 Failover Support

8.1.1 How to Disable The Failover Support In The Driver

Failover support can be disabled in the qla2xxx driver by using the ql2xfailover module parameter:
# insmod qla2xxx.ko ql2xfailover=0 ; insmod qla2300.ko

To disable in modprobe.conf add the following after the driver:
# options qla2xxx ql2xfailover=0

NOTE: Failover is enabled by default when the 8.x driver is built.

8.1.2 Configuration Changes Made via SANsurfer

LUN Masking

NOTE: The Linux SCSI mid-layer requires communication to a target via LUN 0. Therefore, the driver will not mask Lun 0 if it is so defined to be by the application.

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:

1. Load the driver:
   # modprobe qla2300
2. Load the qlremote agent.
3. Start the GUI and connect it to the destination system.
4. Make LUN masking changes.
5. Disconnect the host from GUI and stop qlremote agent.
6. Unload the driver:
   modprobe -r qla2300 ; modprobe -r qla2xx_conf
7. Reload the driver:
   # modprobe qla2300
8. Load qlremote agent again.
9. Start the GUI and connect it to the destination system.
10. Now you should see the updated LUN masking configuration.

8.2 Persistent Binding

The Persistent Binding information consists of some adapter configuration entries along with some target entries. Persistent Binding can be specified in two ways: Manually or using SANsurfer. We recommend using SANsurfer for ease of use. 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 qla2300.ko 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-qla0-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 nodename 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)

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 makes 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.3 Configuration Data

Configuration/persistent data is loaded in the driver automatically when the driver is installed and loaded. Normally this information is passed to the driver via the command line, but due to the constraints inherent in using the command line we have provide an alternate method using QLA_OPTS.

8.3.1 QLA_OPTS

QLA_OPTS reads the configuration data from qla2xxx.conf and updates the binary module qla2xxx_conf.ko. The driver automatically tries to load the binary module qla2xxx_conf.ko at driver initialization time. Once loaded, the module passes the configuration information directly
to the driver.

The configuration data and be found in /etc/qla2xxx.conf.

NOTE: Approximately 300K of configuration space has been pre-allocated within the qla2200_conf/qla2300_conf module for configuration/persistent data.

8.3.2 Compatibility With SMS (SANsurfer Management Suite)

QLA_OPTS works seamlessly with updated SMS applications. All appropriate configuration data is written to the _conf.ko module.

8.3.3 Updating Configuration Manually

Manually updating the /etc/qla2xxx.conf file is strongly discouraged. Because it can cause the binary module and the configuration file to get out of sync. However, in the event that some persistent/configuration value needs to be changed manually, first change the /etc/qla2xxx.conf file, then run the following command in the driver's build directory to update the configuration module:
# ./extras/build.sh install

8.4 Booting from SAN

8.4.1 Creating a Driver Disk (DD Kit) image

The driver disk (DD Kit) image enables to install the Red Hat 4/SLES 9 OS and QLogic driver on the Fibre Channel boot disk connected to the QLogic Host Bus adapters.

To build the driver disk image perform the following steps.
(Example RHEL4-U1 IA-32):

1. Download 8.x_linux_driver_ddkit_for_redhat_suse_dist.tgz from the QLogic website (http://qlogic.com/support/drivers_software.asp).
2. Untar the tgz file:
   # tar -xvzf *.tgz
3. Type:
   # dd if=qla2xxx-8.01.00-x86-dd-RHEL4-U1.img of=/dev/fd0 bs=1440k (Requires a 1.44MB Floppy)
   NOTE: For 2Gb HBAs (QLA23xx) the embedded driver may also be used for the initial installation then updated to the latest driver.

8.4.2 RHEL 4 - Using the Driver Disk (DD Kit) image

NOTE: For QLA246X/QLE246X the dd disk must be used for Boot from SAN.

1. At the boot prompt boot:, type linux dd.

2. Continue the OS installation as normal.

8.4.3 RHEL 4 - Boot from SAN installation on non-LUN 0 LUN

The following step is for the RHEL 4 distribution only.

When installing to a LUN other than LUN 0 and LUN0 is present the
following steps must be taken in order to successfully boot from the LUN.

1. At the Boot Loader Configuration screen, select Configure Advance Boot Loader Option and click the Next button.
2. At the Advanced Boot Loader Configuration screen, click the Change Driver Order button.
3. At the Edit Drive Order window move the entry for the boot LUN to the top of the list.
4. Click OK to continue.
5. Continue the OS installation as normal.

9. IP Support

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

To load the driver directly from the local build directory, type the following in order:
# insmod qla2xxx_conf.ko
# insmod qla2xxx.ko
# insmod qla2300.ko
# insmod qla2xip.ko

To load the driver using modprobe:

1. Install the driver modules (*.ko) files to the appropriate kernel module directory:
   # ./extras/build.sh install
2. Type the following to load the driver for qla23xx HBAs:
   # modprobe -v qla2xxx_conf
# modprobe -v qla2300
# modprobe -v qla2xip
   The modprobe -v qla2300 command will automatically load qla2xxx.ko the component.

To unload the driver using modprobe:

1. # modprobe -r qla2xip
1. # modprobe -r qla2300

This will unload qla2300.ko and qla2xxx.ko modules.
2. # modprobe -r qla2xxx_conf

This will unload qla2xxx_conf.ko.

The qla2xip driver will create a network-interface binding to each IP-capable recognized HBA. Binding entries can be viewed from the messages file after the IP driver has loaded:
qla2xip: QLogic IP via Fibre Channel Network Driver
qla2xip: Driver Version 1.0b2, Entry point: e08e5060
qla2xip: Mapping interface fc0 to HBA 210100e08b20a15b
qla2xip: Mapping interface fc1 to HBA 210200e08b40a25b

9.2 Configuring Interfaces

The following is for 2Gb HBAs only (QLA23xx/QLE236x).

You must configure the network interfaces to allow TCP/IP applications running on the host to communicate with other IP-capable QLogic HBAs.

Compile the following basic host information to allow the IP driver to pass TCP/IP data over QLogic HBAs in your host:

• Interface name: fc0 (From above)
• IP Address: 192.168.1.x (A non-routable address)
  Where 'x' is a unique number between (1 and 254)
• Netmask: 255.255.255.0 (Standard class C mask)
• Interface name: fc1 (From above)
• IP Address: 192.168.2.x (A non-routable address)
  Where 'x' is a unique number between (1 and 254)
• Netmask: 255.255.255.0 (Standard class C mask)

Use the ifconfig program to configure an interface with the compiled host information:
# ifconfig fc0 192.168.1.x up

Configure other interfaces (if multiple IP-capable HBAs are present in the host):
# ifconfig fc1 192.168.1.x up

Verify the configured interfaces:
# ifconfig

Output similar to the following should be displayed for the newly configured interfaces:
fc0 Link encap:Ethernet HWaddr 00:E0:8B:20:A1:5B
inet addr:192.168.1.1 Bcast:192.168.1.255 Mask:255.255.255.0
UP BROADCAST RUNNING MTU:4096 Metric:1
RX packets:1214577458 errors:0 dropped:0 overruns:0 frame:0
TX packets:1214213174 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:32
RX bytes:3081095492 (2938.3 Mb) TX bytes:2751945609 (2624.4 Mb)

fc1 Link encap:Ethernet HWaddr 00:E0:8B:40:A2:5B
inet addr:192.168.2.1 Bcast:192.168.2.255 Mask:255.255.255.0
UP BROADCAST RUNNING MTU:4096 Metric:1
RX packets:1204464697 errors:0 dropped:0 overruns:0 frame:0
TX packets:1194873236 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:32
RX bytes:1454694706 (1387.3 Mb) TX bytes:991094469 (945.1 Mb)

Configuration is now complete. Please verify that basic networking is possible between two hosts connected via two HBAs by using a simple ping command:
# ping 192.168.1.2

For additional information concerning Linux networking, please read the Linux Networking HOWTO available from http://www.tldp.org.

10. Limitations

N/A

11. Contacting QLogic

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

Go to Top

©Copyright 2005. All rights reserved worldwide. QLogic, the QLogic logo, and the Powered by QLogic logo are registered trademarks of QLogic Corporation. All other brand and product names are trademarks or registered trademarks of their respective owners.