QLDIRECT
QLogic Optimizing and Multipath Driver
For Windows 2000 and Windows 20003
Contents
========
1. OS Support
2. Hardware Support
3. Supported Features
4. Release History
5. Creating the Driver Diskette
6. Installing the Driver
7. Registry Parameters
8. Hardware Configuration
9. Software Configuration
10. Software Compatibility
11. Diskette Content
12. Known Issues
13. Contacting QLogic
----------------------------------------------------------------------
1. OS Support
=============
This release has been tested with Windows 2000, and with Windows
2003 (build 3791).
----------------------------------------------------------------------
2. Hardware Support
===================
Currently the QLDIRECT.SYS driver only supports the QLA2200 and
QLA23xx families of Fibre Channel Adapters. It requires the use
of the QL2200.SYS or QL2300 'enhanced' miniport driver version
8.00.00 or higher.
----------------------------------------------------------------------
3. Supported Features
=====================
The QLdirect driver has two main features:
* QLdirect provides an optimized IO path that improves parallel
command execution and reduces the CPU overhead for commands.
* QLdirect High Availability (HA) provides HBA failover on Fibre
Channel adapters. The QLogic SAN configuration utility (SANblade
Manager or SANsurfer) is used to specify the primary and alternate
paths to use to access each target device. QLdirect will detect
certain error status codes and miniport events, and retry failed
IO operations on the alternate path. QLdirect will hide the
alternate path from Windows to keep Windows from configuring in a
second copy of a device.
QLdirect is also compatible with the following miniport features:
* QLdirect will support LUN masking in concert with the Fibre Channel
enhanced miniport drivers. This feature allows the QLogic SAN
configuration utility to allocate some LUNs of a target to one host
and mask off other LUNs for use on other hosts.
* QLdirect will support uniquely identifying target devices using
the world-wide node name and the world-wide port name.
----------------------------------------------------------------------
4. Release History
==================
Please refer to Release Notes for release history information.
----------------------------------------------------------------------
5. Creating the Driver Diskette
===============================
To create the QLdirect driver diskette, use the SANsurfer Management
Suite CD-ROM, or go to QLogic's website at http://www.qlogic.com,
click on "Support", then click on "Drivers, Software, and Manuals".
Select the QLogic Fibre Channel Host Bus Adapter of your choice and
the operating system.
Choose "Save this program to disk", specify a temporary location for
the .zip file, then expand the .zip file onto a blank diskette.
----------------------------------------------------------------------
6. Installing the Driver
========================
The QLdirect program is installed using the SETUP.EXE program found
on the distribution medium. To initially install the QLdirect driver
on an installed Windows system, execute SETUP.EXE and follow through
the dialogs displayed. You will need to restart your system to use
the QLdirect driver.
Note that on 64-bit systems, due to an InstallShield limitation, the
driver is installed in the %SystemRoot%\SysWOW64\Drivers directory,
and is then copied to the %SystemRoot%\System32\Drivers directory.
This extra copy of the driver is not removed during deinstallation,
and must be manually removed to eliminate the file.
----------------------------------------------------------------------
7. Registry Parameters
======================
In general, the default parameters that are set up during installation
should be sufficient. All normal parameters are subkeys of:
HKLM\SYSTEM\CurrentControlSet\Services\qldirect
The parameters values in the
HKLM\System\CurrentControlSet\Services\qldirect\Parameters
key can be overridden by values in a
HKLM\System\CurrentControlSet\Services\qldirect_override\Parameters
key. When QLdirect reads registry parameters, it first attempts to
read them from the "qldirect_override\Parameters" key, and if that
fails, it attempts to read them from the "qldirect\Parameters" key.
This is facilitate OEM installations that may override the QLdirect
default installation, without risking that reinstalling QLdirect
will undo the OEM-custom parameters.
The following parameters are selected during installation:
* qldirect\Start
Set to 0 (SERVICE_BOOT_START) if QLdirect must be loaded before the
disk class driver, or 2 (SERVICE_AUTO_START) if QLdirect is loaded
after the disk class driver. The default value of 2 is sufficient
for most systems. The value of 0 is selected for compatibility with
the Clariion CLATF driver, or other filter drivers that are inserted
between the disk class and SCSI port drivers.
* qldirect\Parameters\SrbListSize
Set to a value between 256 and 2048 (default is 1024). This is the
maximum number of outstanding requests expected to any host bus
adapter being controlled by QLdirect. Lower numbers reduce memory
consumption; higher numbers allow for greater efficiency in the
QLdirect driver. QLdirect will dynamically allocate up to 32
times this number dynamically during operation, but a greater
efficiency is achieved if the static value is sufficient.
The following parameters are set during installation. They can be
modified using a registry editor, but should only be changed under the
direction of QLogic Technical Support.
* qldirect\Parameters\Flags
A bitmask of flags used internally by the QLdirect driver. The
following flags are defined:
0x01 bit: Turns on extended error logging in the QLdirect driver.
This may log excessive numbers of events, and should only
be enabled in the course of troubleshooting.
0x02 bit: Turns on statistics gathering in the QLdirect driver.
This increases driver overhead and is not normally used.
* qldirect\Parameters\Optimization
A bitmask of flags used internally by the QLdirect driver. The
following flags are defined:
0x01 bit: Turns on extra optimization in conjunction with the disk
class driver. Used on NT4 only; this option is obsolete.
0x02 bit: Turns on combined timeout checking. This option makes
the one-second QLdirect timeout check more efficient but
less accurate in checking for disk timeouts. It should
normally be left off unless there is a specific performance
issue in the one-second timer routine.
* qldirect\Parameters\FailoverNotifyType
Specifies whether qldirect notifies targets when a failover occurs,
and what method to use to notify the target. Currently this must
be one of the following values:
0 = None: do not send any failover notification to the target.
1 = LUN reset: Notify by sending a LUN reset command to each LUN
of the target when the target is failed over.
2 = CDB: Notify by sending a definable SCSI CDB to each LUN of the
target when the target is failed over. The CDB is defined in
registry parameter FailoverNotifyCdb.
* qldirect\Parameters\FailoverNotifyCdb
A REG_BINARY array of bytes that defines a CDB to be sent to each
LUN of a target to notify the target that a failover has occurred.
Only used if registry parameter FailoverNotifyType = 2. The CDB
should be a valid SCSI CDB. The length of the CDB is whatever
length of data is stored in the registry; the maximum length is 16
bytes. There is no send data or receive data associated with the
CDB. The CDB is sent unmodified to each LUN of the target,
exactly once with no retries. Any errors for this CDB are logged
as warnings in the event log.
* qldirect\Parameters\InspectionInterval
Not currently used.
* qldirect\Parameters\MaxRetriesPerIo
The maximum total retries for one IO operation, before the operation
is returned to the calling driver with error status. Default=49.
* qldirect\Parameters\MaxRetriesPerPath
The maximum retries for one IO operation on the current path, before
the target is failed over to the next path and the operation is
retried. Must be greater than MaxRetriesPerIo. Default=3.
* qldirect\Parameters\PerCpuData
This is a boolean parameter that is set to 1 to force QLdirect to
allocate separate data pools for each CPU on the system, and force
completion processing to be tied to a particular CPU. This uses
a tremendous amount of extra memory for QLdirect, and may exceed
the limits of non-paged pool that can be allocated on machines
that have a large number of processors and/or HBAs. As such,
this option should be thoroughly tested in offline environments
before being enabled with live systems. The benefit of using
this option is that the per-CPU data and processing reduces the
amount of cache contention on large multiprocessor systems, and
can significantly reduce CPU overhead per IO. Default=0.
* qldirect\Parameters\EmulateBuild
This is a DWORD parameter that is set to a Windows 2000 or
Windows.net build number, to cause QLdirect to operate as if it
was running under that operating system build. QLdirect takes
special action depending on certain build numbers. Adding this
parameter to the registry allows support of alternate build
numbers that may not be officially supported by QLdirect.
For example, if QLdirect supports build 3600 and 3650 the same,
and a customer receives a special build 3625 that is not supported
by QLdirect, this parameter could be added and set to 3600 to make
QLdirect run under build 3625 as if it were build 3600.
In general, this parameter should not be added except under the
supervision of QLogic Tech Support or Engineering. Adding this
parameter to an incompatible build can crash the operating system.
* qldirect\Parameters\DisableAutoFailback
This is a DWORD parameter that is set to 1 to disable the
automatic failback feature of QLdirect. For general use, this
parameter should be left at its default value of 0. It is
typically of use only in special configurations or in
troubleshooting situations.
* qldirect\Parameters\TimerCpuNumber
This is a DWORD parameter that is set to the zero-base CPU
number on which to execute QLdirect's one-second timer routine.
QLdirect uses a one-second timer to monitor IOs and check for IO
timeouts. By default, this routine always runs on CPU #0. On
some multiprocessor configurations, it can be useful to move the
overhead of this routine to another processor. For most systems,
the default value of 0 is adequate.
----------------------------------------------------------------------
8. Hardware Configuration
=========================
* The QLdirect driver is compatible with the QLA2200 and QLA23xx
families of QLogic Fibre Channel host bus adapters. All of these
HBAs require that QLdirect is running with the enhanced miniport
drivers V8.0.0 and above. QLdirect will perform IO optimization in
all valid configurations. QLdirect will perform failover in
configurations where multiple paths exist to a supported storage
device.
* QLdirect will perform HBA failover between any combination of
QLA2200 and QLA23xx host bus adapters. Any host bus adapters that
share a device must have the same adapter NVRAM setting for "Max LUNs"
to insure that consistent LUN mapping can be performed. If QLdirect
detects that two HBAs share access to a device, and they do not have
the same NVRAM setting for "Max LUNs", QLdirect will not process IOs
for those HBAs. IO operations will continue through the
non-QLdirect path, but QLdirect will not perform IO optimization or
HBA failover. When QLdirect detects such a configuration problem,
it logs an event in the system event log that describes the problem.
----------------------------------------------------------------------
9. Software Configuration
=========================
* QLdirect is normally used in conjunction with the QLogic SAN
configuration utilities SANblade Manager and SANsurfer. These
utilities are used to set up the configuration and select the
primary and alternate path for each target in the SAN.
* QLdirect HA will currently track up to four target ports for a device
and up to four HBAs providing access to each of those target ports,
for a maximum of 16 possible paths to a device. If QLdirect detects
multiple visible paths to a device, it will automatically set the
second path found to be a hidden path instead of a primary path.
When QLdirect detects such a configuration problem, it logs an event
in the system event log that describes the problem.
When QLdirect marks a second such path as a hidden path, Windows
may see this as a device that was present and has gone away.
Windows may then retry IO operations to this second copy of the
device, and log events in the event log for a device that is not
ready or not available. To correct such a configuration problem,
re-run the QLogic SAN configuration utility, save the
configuration in the registry, and reboot the system.
* QLdirect standard version does not support failover paths, and
will treat failover paths to the device the same as if they are
unconfigured.
* If QLdirect detects that there are too many paths enabled to a
device, it will log an event in the event log describing the
configuration problem. To correct the problem, re-run the QLogic SAN
configuration utility, save the configuration in the registry,
and reboot the system.
----------------------------------------------------------------------
10. Software Compatibility
==========================
QLdirect is sensitive to the driver load order of the system,
especially when the system includes other filter drivers in the
storage driver stack.
CLATF Filter Driver:
For example, QLdirect by default is started at SERVICE_AUTO_START
(Start=2 in the registry). When running with EMC Clariion CLATF
and some other drivers, it must be started at SERVICE_BOOT_START
(Start=0 in the registry).
The QLdirect will detect the installation of CLATF, and will check
the correct radio button in the installation screen. If CLATF is
installed after QLdirect, however, this value may not be correct.
The easiest was to correct the problem is to reinstall QLdirect and
let the QLdirect installation procedure fix up the registry.
There may be other instances where other software products change
the driver load order and affect QLdirect. For example, there is
an IBM Raid filter driver that installs itself to be in the service
group "System Bus Extender". This causes it to be loaded before
QLdirect, and keeps QLdirect from operating. In this configuration,
the driver name is "Twintail". The fix is to change the registry
as follows:
* In HKLM\System\CurrentControlSet\Services\Twintail, change the
Group from "System Bus Extender" to a new group named "twintail".
This will allow you to move this group around in the
ServiceGroupOrder list to control the load order.
* In HKLM\System\CurrentControlSet\Control\ServiceGroupOrder\List,
add the new "twintail" group immediately after the "qldirect"
group, so Twintail will load after QLDirect.
Interrupt Affinity Filter Driver:
Microsoft has an Interrrupt Affinity Filter (IntFiltr) driver
that associates the interrupts from particular devices with
particular CPUs in a multiprocessor configuration. This gives
a performance boost in some situations by reducing CPU cache
contention. This driver is not compatible with QLdirect. It
creates device objects that cannot be processed with QLdirect.
Also, because QLdirect has a common DPC routine for all HBAs
(to handle failover between HBAs), even if the two products
could run together, QLdirect would undo the effect of IntFiltr.
It is not possible for the QLdirect to predict all possible load
order interactions, but the majority of systems do not even have
the potential for such issues. If you believe you have such a
problem with QLdirect and another product, contact QLogic Tech
Support for assistance.
----------------------------------------------------------------------
11. Diskette Contents
=====================
The Driver Diskette contains the following files of note. The
remaining files are used by the InstallShield installation script.
Setup.exe The main installation program.
Readme.txt This text file.
Release.txt Contains Release Notes with release history
information.
----------------------------------------------------------------------
12. Known Issues
================
Updating Windows with QLdirect Installed:
Updating from one version of Windows to another (as opposed
to doing a full installation) can sometimes disable QLdirect.
This is because QLdirect adds a "qldirect" group to the
HKLM\System\CurrentControlSet\Control\ServiceGroupOrder\List
registry parameter to cause it to be loaded at the correct
time, and the upgrade procedure overwrites this list and
removes the "qldirect" group.
This problem is even worse when running with the QLperf
driver, which depends on QLdirect to run before starting
QLperf.
This problem can be corrected by doing a full installation
of Windows followed by an installation of QLdirect; or, by
deinstalling QLdirect and QLperf before doing the upgrade.
----------------------------------------------------------------------
13. Contacting QLogic
=====================
For latest product information, adapter drivers and utilities, or to
report problems related to QLA family of products, please visit
QLogic's website (www.qlogic.com).
----------------------------------------------------------------------
Copyright (c) 1999-2003 QLogic Corporation. All rights reserved.
Download Driver Pack
After your driver has been downloaded, follow these simple steps to install it.
Expand the archive file (if the download file is in zip or rar format).
If the expanded file has an .exe extension, double click it and follow the installation instructions.
Otherwise, open Device Manager by right-clicking the Start menu and selecting Device Manager.
Find the device and model you want to update in the device list.
Double-click on it to open the Properties dialog box.
From the Properties dialog box, select the Driver tab.
Click the Update Driver button, then follow the instructions.
Very important: You must reboot your system to ensure that any driver updates have taken effect.
For more help, visit our Driver Support section for step-by-step videos on how to install drivers for every file type.