qla2x00t: Update QLogic target documentation

The legacy and newer QLogic guides disagree about the default driver,
supported adapters, NPIV, sysfs layout and module lifecycle. The
HOWTO also carries SVN, kernel replacement, firmware flashing and
discovery commands that can disrupt active storage.

Commit 7aade0a109 ("Makefile: Make the qla2x00t-32gbit driver
the default QLogic FC driver") selected the newer tree by default.
Commit a788a4efd7 ("Newer version of QLogic target driver with 16G
(26xx/83xx) support") added that tree and disabled legacy NPIV target
callbacks. Commit 08e532715d ("Remove procfs support") removed the
old management path.

Use each qla2xxx_pci_tbl[] and qla_os.c for hardware and firmware facts.
Document QLA_32GBIT=no, current per-port sysfs state, reset effects
and the matched qla2xxx_scst and qla2x00tgt modules. Replace unsafe
generic recipes with repository or vendor sources and mark every HBA,
fabric, target and backing-device operation as live.
This commit is contained in:
Gleb Chesnokov
2026-08-21 10:05:36 +03:00
parent b836a17e35
commit df124ce643
4 changed files with 207 additions and 383 deletions
+6 -1
View File
@@ -19,4 +19,9 @@ the previous version of the SCST QLogic target driver are:
{ PCI_DEVICE(PCI_VENDOR_ID_QLOGIC, PCI_DEVICE_ID_QLOGIC_ISP2281) },
{ PCI_DEVICE(PCI_VENDOR_ID_QLOGIC, PCI_DEVICE_ID_QLOGIC_ISP2089) },
{ PCI_DEVICE(PCI_VENDOR_ID_QLOGIC, PCI_DEVICE_ID_QLOGIC_ISP2289) },
- Works in combination with Linux kernel v3.15 and later.
- The repository-supported kernel list is the ABT_KERNELS list in
../../nightly/conf/nightly.conf. For generated in-tree patches,
../../scripts/generate-kernel-patch selects the legacy QLogic tree for
kernels before v3.18 and this tree otherwise. For out-of-tree builds,
use the current compatibility guards and ../../scst/include/backport.h
rather than this driver's historical Linux v5.1 base as policy.
+100 -206
View File
@@ -4,7 +4,7 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>
QLogic FC Target Driver How-to for 22xx/23xx/24xx/25xx/26xx Adapters
QLogic FC Target Driver How-to
</title>
<style type="text/css">
pre {color:brown;}
@@ -13,109 +13,70 @@ body > ol > li {padding-bottom:1ex;}
<body>
<div style="text-align: center;">
<strong>How to Configure the FC QLogic Target Driver for
22xx/23xx/24xx/25xx/26xx Adapters</strong></div>
<strong>How to Configure the FC QLogic Target Driver</strong></div>
<br><br>
<p><strong>WARNING:</strong> This procedure changes live kernel, HBA,
firmware, boot, Fibre Channel fabric and storage state. It unloads and
blacklists drivers, can flash HBA firmware, rebuilds an initial RAM disk,
writes sysfs, enables target ports and exports writable storage. Do not run
it without authorization for the exact host, HBA ports, firmware image,
fabric, initiators and backing devices. Verify recovery and rollback plans
before changing firmware or boot configuration.</p>
<div style="text-align: center;"> <strong>TARGET SYSTEM</strong></div>
<br><br>
<ol>
<li>
Look up the model numbers of the FC HBA and of the FC HBA RISC controller. If
it is not easy to access the label printed on the HBA, one way to look up
these model numbers is as follows:
<pre>[root@proj ]# dmesg -c &gt;/dev/null
[root@proj ]# rmmod qla2xxx
[root@proj ]# modprobe qla2xxx
[root@proj ]# dmesg | grep -E 'qla2xxx .* QLogic | Found an ISP'
qla2xxx [0000:01:00.0]-001d: Found an ISP2532 irq 16 iobase 0xffffc9000413e000.
qla2xxx [0000:01:00.0]-00fb:164: QLogic QLE2562 - PCI-Express Dual Channel 8Gb Fibre Channel HBA.
qla2xxx [0000:01:00.1]-001d: Found an ISP2532 irq 17 iobase 0xffffc9000417c000.
qla2xxx [0000:01:00.1]-00fb:165: QLogic QLE2562 - PCI-Express Dual Channel 8Gb Fibre Channel HBA.</pre>
The above information not only contains the HBA model number (QLE2562) but
also the RISC controller ID (ISP2532).
</li>
<li>(Optional) Download the Linux version of the QConvergeConsoleCLI software package
from <a href="http://driverdownloads.qlogic.com/">http://driverdownloads.qlogic.com/</a>
and install that software package.
Identify the exact HBA PCI device, board model and firmware from existing
hardware inventory, read-only sysfs attributes and retained kernel logs.
Do not clear the kernel log or unload and reload a storage driver merely to
identify the adapter. The current supported PCI IDs are defined by
<code>qla2xxx_pci_tbl[]</code> in the selected tree's
<a href="../qla_os.c">legacy</a> or
<a href="../../qla2x00t-32gbit/qla_os.c">newer</a> qla2xxx source.
</li>
<li>
Download the appropriate firmware for your QLogic card from
<a href="http://driverdownloads.qlogic.com/">http://driverdownloads.qlogic.com/</a>.
It is strongly recommended to use firmware version 5.x or higher for
24xx/25xx adapters. More information about this subject can be found in
the following e-mail thread: Vladislav Bolkhovitin and Artur Piechocki,
<a href="http://sourceforge.net/mailarchive/forum.php?thread_name=4B4CD39F.6020401%40vlnb.net&amp;forum_name=scst-devel"><em>FC
session gets closed with qla2x00t</em></a>, scst-devel mailing list, January 2010.
<br><br>
If no firmware image is available when the QLogic kernel module is loaded,
the following error message will appear in the system log
(/var/log/messages or /var/log/syslog):
<pre>qla2xxx 0000:13:00.0: Firmware image unavailable.
qla2xxx 0000:13:00.0: Failed to initialize adapter</pre>
Obtain firmware and any management utility from current vendor or
distribution support for the exact PCI and board model. Do not treat the
historical version recommendation in this document as current vendor
policy.
</li>
<li>
The <code>ql2xfwloadbin</code> module parameter controls whether the driver
requests a firmware file, loads firmware from adapter flash or uses its
default semantics. When file loading is selected, use the exact
<code>FW_FILE_*</code> name defined by the selected tree's
<a href="../qla_os.c">legacy</a> or
<a href="../../qla2x00t-32gbit/qla_os.c">newer</a> qla2xxx source. Do not
rename an arbitrary firmware image according to a historical model table.
</li>
<li>
If the approved deployment requires updating firmware stored in the HBA,
follow the current vendor or distribution procedure for the exact board
model. Perform the update in a maintenance window with a tested recovery
plan. SCST does not define a universal HBA flash command.
</li>
<li>
Install the current build prerequisites listed in
<a href="../../INSTALL.md">INSTALL.md</a>. Distribution package names and
supported kernel versions change over time; the lists in that document and
<code>nightly/conf/nightly.conf</code> are authoritative.
</li>
<li>
Copy the firmware image (.BIN) file to the /lib/firmware directory and
rename it such that the kernel driver can find it. The file name that should
be used for the firmware file depends on the RISC controller ID:
<table border="1" summary="">
<tr><th><b>ISP Model</b></th><th><b>Firmware file<br>name</b></th></tr>
<tr><td>ISP 21XX</td><td>ql2100_fw.bin</td></tr>
<tr><td>ISP 22XX</td><td>ql2200_fw.bin</td></tr>
<tr><td>ISP 2300</td><td>ql2300_fw.bin</td></tr>
<tr><td>ISP 2322</td><td>ql2322_fw.bin</td></tr>
<tr><td>ISP 24XX</td><td>ql2400_fw.bin</td></tr>
<tr><td>ISP 25XX</td><td>ql2500_fw.bin</td></tr>
<tr><td>ISP 2031</td><td>ql2600_fw.bin</td></tr>
<tr><td>ISP 27XX</td><td>ql2700_fw.bin</td></tr>
</table>
</li>
<li>
Update the firmware image in the HBA. Although the QLogic kernel driver is
able to load the firmware from /lib/firmware, QLogic recommends to update
the firmware image that resides in the HBA (see also Quinn Tran,
<a href="http://sourceforge.net/p/scst/mailman/message/32801228/"><em>Re:
[ANNOUNCE]: qla2x00t QLogic git integration into the SCST build
tree</em></a>, scst-devel mailing list, September 5, 2014). An example:
<pre>[root@proj ]# /opt/QLogic_Corporation/QConvergeConsoleCLI/qaucli -fc -b all /lib/firmware/ql2500_fw.bin</pre>
</li>
<li>Install the necessary kernel development packages. On a Debian system
these packages can be installed as follows:
<pre>[root@proj ]# apt-get install gcc linux-headers-`uname -r` lsscsi patch subversion</pre>
On RHEL/CentOS/SL systems these packages can be installed as follows:
<pre>[root@proj ]# yum install gcc kernel-devel lsscsi patch subversion</pre>
And on SUSE systems these packages can be installed by running the following command:
<pre>[root@proj ]# zypper install gcc kernel-devel lsscsi patch subversion</pre>
Obtain a current SCST release or Git checkout as described by the project
<a href="../../README.md">README</a>. The remaining relative paths assume
commands are run from the root of that source tree.
</li>
<li>
Download the SCST source code. That source code can be downloaded either
from the <a href="http://scst.sourceforge.net/downloads.html">SCST
downloads page</a> or from the SCST Subversion source code
repository.<br><br>
In what follows it is assumed that the SCST trunk has been retrieved
via Subversion. Installing a released SCST version is identical to
installing the trunk after all downloaded SCST source code archives have
been extracted in a single directory. The structure of that directory will
be identical to that of the SCST trunk.
<pre>[root@proj ]# svn co https://svn.code.sf.net/p/scst/svn/trunk scst</pre>
After the above command finished a directory called 'scst' will have been
created in the current directory, which is /root in this how-to.
</li>
<li>
If you want to use the latest QLogic SCST target driver from the QLogic git,
use the driver from the qla2x00t-32gbit directory. Please note that this
driver has not yet reached the same maturity level as the driver in the
qla2x00t directory.
The top-level build selects <code>qla2x00t-32gbit</code>, the newer QLogic
tree, by default. Set <code>QLA_32GBIT=no</code> for both build and install
only when selecting the alternative legacy <code>qla2x00t</code> tree. Do
not mix an initiator/HBA module from one tree with the target adapter from
the other.
</li>
<li id="blacklist">
@@ -125,92 +86,35 @@ Unload the qla2xxx kernel module provided by your Linux distribution and blackli
</li>
<li id="release">
Select a build mode that suits your needs, e.g. optimal performance or
debugging SCST. The default mode is debug mode. Here is how to switch to
release mode:
<pre>[root@proj scst ]# pwd
/root/scst
[root@proj scst ]# make 2release</pre>
Select the build mode from the source-tree root. For example, select the
release mode before compiling:
<pre>[root@proj scst ]# make 2release</pre>
</li>
<li>
Now build the SCST kernel modules. But first verify that the link
"/lib/modules/`uname -r`/build" points to the kernel headers of the
currently running kernel. Build and install SCST, e.g. as follows:
<pre>[root@proj ]# cd /root/scst
[root@proj scst ]# BUILD_2X_MODULE=y CONFIG_SCSI_QLA_FC=y CONFIG_SCSI_QLA2XXX_TARGET=y make all install</pre>
Verify that compilation and installation succeeded:
<pre>[root@proj scst]# ls -l /lib/modules/`uname -r`/extra/qla2*
-rw-r--r-- 1 root root 36756 Jun 20 18:46 qla2x00tgt.ko
-rw-r--r-- 1 root root 160192 Jun 20 18:46 qla2xxx_scst.ko
</pre>
Build and install SCST by following
<a href="../../INSTALL.md">INSTALL.md</a>. For a source build, keep
<code>BUILD_2X_MODULE=y</code>, <code>CONFIG_SCSI_QLA_FC=y</code> and
<code>CONFIG_SCSI_QLA2XXX_TARGET=y</code> consistent across the separate
build and privileged install commands. Also keep the same
<code>QLA_32GBIT</code> selection in both commands.
</li>
<li>
Insert the kernel modules.<br> The kernel modules have been installed in
'/lib/modules/`your_kernel_version`/extra'.<br> In addition, scst.h,
scst_debug.h as well as Module.symvers or Modules.symvers have been copied
to '/usr/local/include/scst'.<br> The first file contains all SCST's public
interfaces used by target drivers. The other files allow target drivers to
generate debug messages and support the kernel module build process.
<pre>[root@proj scst]# ls -l /lib/modules/`uname -r`/extra
total 232
drwxr-xr-x 2 root root 4096 Jun 20 18:43 dev_handlers
-rw-r--r-- 1 root root 36756 Jun 20 18:46 qla2x00tgt.ko
-rw-r--r-- 1 root root 160192 Jun 20 18:46 qla2xxx_scst.ko
-rw-r--r-- 1 root root 190848 Jun 20 18:43 scst.ko
[root@proj scst]# ls -l /lib/modules/`uname -r`/extra/dev_handlers
total 192
-rw-r--r-- 1 root root 11757 Jun 20 18:43 scst_cdrom.ko
-rw-r--r-- 1 root root 10111 Jun 20 18:43 scst_changer.ko
-rw-r--r-- 1 root root 12420 Jun 20 18:43 scst_disk.ko
-rw-r--r-- 1 root root 12449 Jun 20 18:43 scst_modisk.ko
-rw-r--r-- 1 root root 10131 Jun 20 18:43 scst_processor.ko
-rw-r--r-- 1 root root 10081 Jun 20 18:43 scst_raid.ko
-rw-r--r-- 1 root root 12563 Jun 20 18:43 scst_tape.ko
-rw-r--r-- 1 root root 37937 Jun 20 18:43 scst_user.ko
-rw-r--r-- 1 root root 50194 Jun 20 18:43 scst_vdisk.ko</pre>
where:
<ul>
<li>scst - SCST itself.</li>
<li>scst_disk - device handler for disks (type 0).</li>
<li>scst_tape - device handler for tapes (type 1).</li>
<li>scst_processor - device handler for processors (type 3).</li>
<li>scst_cdrom - device handler for CDROMs (type 5).</li>
<li>scst_modisk - device handler for MO disks (type 7).</li>
<li>scst_changer - device handler for medium changers (type 8).</li>
<li>scst_raid - device handler for storage array controller (e.g. raid) (type C).</li>
<li>scst_vdisk - device handler for virtual disks (file, device or ISO CD image)..</li>
<li>scst_user - user space device handler.</li>
</ul>
<br>
You can insert any of these kernel modules with the 'modprobe' program. As
you can see, I've inserted all SCST kernel modules !!!
<pre>[root@proj ]# for m in scst qla2xxx_scst qla2x00tgt scst_vdisk scst_user scst_disk ...; do modprobe $m; done</pre>
This will result in the following dmesg output:
<pre>scst: SCST version 2.0.0 loaded successfully (max mem for commands 16251MB, per device 6500MB)
scst: Enabled features: TRACING
scst: Target template qla2x00tgt registered successfully
scst: Virtual device handler vdisk for type 0 registered successfully
scst: Virtual device handler "scst_user" registered successfully</pre>
Load only the modules required by the approved configuration, using the
service or manual workflow documented in <a href="../../INSTALL.md">
INSTALL.md</a>. The <code>qla2xxx_scst</code> initiator/HBA module and
<code>qla2x00tgt</code> target adapter must come from the same selected
source tree. Do not use historical module sizes or log transcripts to
validate the installation.
</li>
<li>
Back up and rebuild the initial RAM disk such that the qla2xxx kernel module in
that RAM disk will be replaced by qla2xxx_scst. How to do this depends on your
Linux distribution. The initial RAM disk can be rebuilt e.g. as follows:
<pre>[root@proj ]# type update-initrd >/dev/null 2>&amp;1 &amp;&amp; update-initrd -c -k `uname -r`
[root@proj ]# type update-initramfs >/dev/null 2>&amp;1 &amp;&amp; update-initramfs -c -k `uname -r`
[root@proj ]# if type mkinitrd >/dev/null 2>&amp;1; then
if { rpm -q sles-release || rpm -q openSUSE-release; } >/dev/null 2>&amp;1;
then mkinitrd; else mkinitrd -f /boot/initramfs-`uname -r`.img `uname -r`; fi; fi</pre>
If the approved deployment requires <code>qla2xxx_scst</code> in the initial
RAM disk, back up the current image and follow the distribution's procedure
for the exact installed kernel. Verify that the replacement modules are
present before rebuilding and retain a bootable recovery entry. There is no
portable SCST command that can safely select or replace an initial RAM disk.
</li>
<li>
@@ -227,8 +131,11 @@ Now let's create our virtual device:
/mnt/disk1: data</pre>
</li>
<li>The next step is to install scstadmin:
<pre>[root@proj ]# make -C scstadmin -s install</pre>
<li>
The repository-wide source or package installation workflow includes
<code>scstadmin</code>. Verify that the installed command matches the SCST
version before applying the configuration below; do not perform a second
uncoordinated installation from this HOWTO.
</li>
<li id="qlini_mode"> Initiator and target modes <br><br>
@@ -249,11 +156,16 @@ Now let's create our virtual device:
Use mode "enabled" if you need your QLA adapters to work in both initiator and target modes at the same time.<br>
You can always see which modes are currently active in active_mode sysfs attribute.<br>
In all the modes you can at any time use sysfs attribute ini_mode_force_reverse to force enable or disable initiator mode on any particular port. Setting this attribute to 1 will reverse current status of the initiator mode from enabled to disabled and vice versa.<br>
Changing ini_mode_force_reverse requests an ISP abort and waits for the HBA
to return online.<br>
<br>
<b>qla2x00t-32gbit</b> (new qlogic driver): <br><br>
Use mode "dual" if you need your QLA adapters to work in both initiator and target modes at the same time. In this mode, each qlogic host has individual <b>qlini_mode</b>, <b>ql2xexchoffld</b>, <b>ql2xiniexchg</b> attributes that can be changed dynamically.<br>
For example, you can change qlini_mode to "disabled" for specific qlogic host:
<pre>echo "disabled" > /sys/devices/pci0000:80/0000:80:02.0/0000:81:00.0/host1/scsi_host/host1/qlini_mode</pre>
<pre>echo "disabled" > /sys/class/scsi_host/host1/qlini_mode</pre>
An accepted dynamic mode change can request an ISP abort, and some
transitions are rejected while target mode is active. Check the target
state and kernel log before and after changing the attribute.
</li>
<li id="target-mode">
@@ -264,11 +176,11 @@ Now let's create our virtual device:
The simplest way to do that is to generate an scstadmin config file, e.g. as
follows:
<pre>modprobe qla2x00tgt
find /sys/kernel/scst_tgt/targets/qla2x00t -name enabled | \
while read f; do echo 1 >$f &amp; done; wait
find /sys -name issue_lip | while read f; do echo 1 >$f &amp; done; wait
{
<strong>WARNING:</strong> This template enumerates every discovered QLogic
target port and maps LUN 0 without initiator groups. Restrict the generated
targets and access controls before applying it.
<pre>{
cat &lt;&lt;EOF
HANDLER vdisk_fileio {
DEVICE disk1 {
@@ -291,24 +203,15 @@ EOF
done
} >scst.conf</pre>
Check the generated config file. If it looks fine to you, move it to the
default location:
<pre>mv -i scst.conf /etc/scst.conf</pre>
Review the generated file against the current configuration, restrict its
targets and initiators and preserve a backup before placing it at
<code>/etc/scst.conf</code>. Do not replace an existing configuration by
following an unreviewed example.
The SCST configuration in that file can be applied via scstadmin:
Applying the file is a live operation that opens the backing file, maps the
LUN and enables each configured target:
<pre>[root@proj ]# scstadmin -config /etc/scst.conf
Collecting current configuration: done.
-> Checking configuration file 'qq' for errors.
-> Done, 0 warnings found.
-> Opening device 'disk1' using handler 'vdisk_fileio': done.
-> Adding device 'disk1' at LUN 0 to driver/target 'qla2x00t/25:00:00:f0:98:87:92:f3': done.
-> Enabling driver/target 'qla2x00t/25:00:00:f0:98:87:92:f3': done.
All done.</pre>
<pre>[root@proj ]# scstadmin -config /etc/scst.conf</pre>
The same can be done directly via the sysfs interface of SCST:
@@ -339,25 +242,16 @@ The same can be done directly via the sysfs interface of SCST:
<br>
<ol>
<li>
A quote from the SCST README:<blockquote><em> Without loading appropriate
device handler, corresponding device will be invisible for remote
initiators, hence we have to add them manually.</em></blockquote> But as
I've already loaded the device handler (scst_vdisk) on the target, I don't
have to perform any additional steps.
</li>
<li>
After <a href="#target-mode">enabling the target mode</a> on the target, to
see new targets and devices on the initiator you need have to trigger a
rescan on the initiator. That is possible either by rebooting the initiator
or by unloading and reloading the initiator kernel module. Automatic
discovery isn't supported by all known initiators, so you need a way to make
SCSI subsystem on the initiator to do the new devices discovery and hence be
able to see the new devices attached.
see new targets and devices on the initiator, use the discovery procedure
for that initiator driver and the exact fabric port. Do not use a reboot or
module unload as a generic discovery method: either can disrupt unrelated
sessions and storage. A LIP or other fabric rediscovery is also a live
operation and must be scoped to the intended port.
Alternatively, if your initiator already connected to the target and you
simply added new devices to it, you can try to run a manual rescan as follows:
If the initiator is already connected and only new LUNs were added, rescan
the corresponding SCSI host as follows:
<pre>[root@initiator ]# echo "- - -" >/sys/class/scsi_host/hostX/scan</pre>
where X is the host number.
+100 -175
View File
@@ -1,16 +1,15 @@
Target driver for QLogic 2[2-6]xx/8[1-3]xx Fibre Channel cards
==============================================================
Target driver for QLogic Fibre Channel adapters
================================================
Version 3.11.0-pre, 29 December 2025
----------------------------
This is target driver for QLogic 2[2-6]xx/8[1-3]xx Fibre Channel cards.
Particularly, this driver supports 16G Hilda QLogic chip based adapters
(however, post-Hilda QLogic chips not supported). This driver should
also support FCoE, but that has never been verified. It has passed
intensive internal SanDisk tests. It is stable and production ready.
This driver is in stable maintenance mode in favor of the QLogic git
driver, which has support for all the latest QLogic adapters.
This is the legacy target driver for the QLogic Fibre Channel adapters
matched by qla2xxx_pci_tbl[] in ../qla_os.c. It should also support
FCoE, but that has never been verified. It has passed intensive internal
SanDisk tests. It is stable and production ready. This driver is in
stable maintenance mode in favor of the default qla2x00t-32gbit tree,
which supports newer QLogic adapters.
This driver consists from two parts: the target mode driver itself and
the changed initiator driver from Linux kernel, which is, particularly,
@@ -20,10 +19,10 @@ necessary callbacks, but it's still capable to work as initiator only.
Mode, when a host acts as the initiator and the target simultaneously,
is supported as well.
This version is compatible with SCST core version 3.2.0 and higher and
Linux kernel 2.6.26 and higher. Sorry, kernels below 2.6.26 are not
supported, because it's too hard to backport used initiator driver to
older kernels.
This source is maintained and tested with the SCST core in this
repository. The current supported and tested kernel set is maintained
in ../../nightly/conf/nightly.conf; do not infer current support from
historical minimum-version statements.
See also "ToDo" file for list of known issues and unimplemented
features.
@@ -32,58 +31,31 @@ features.
Installation
------------
Only vanilla kernels from kernel.org and RHEL/CentOS 5.2 kernels are
supported, but SCST should work on other (vendors') kernels, if you
manage to successfully compile it on them. The main problem with
vendors' kernels is that they often contain patches, which will appear
only in the next version of the vanilla kernel, therefore it's quite
hard to track such changes. Thus, if during compilation for some vendor
kernel your compiler complains about redefinition of some symbol, you
should either switch to vanilla kernel, or add or change as necessary
the corresponding to that symbol "#if LINUX_VERSION_CODE" statement.
Follow ../../INSTALL.md for prerequisites and source or package
workflows. This legacy tree is not selected by default. For a source
build from the repository root, select it together with the matching
out-of-tree initiator driver:
Before installation make sure that the link
"/lib/modules/`you_kernel_version`/build" points to the source code for
your currently running kernel.
BUILD_2X_MODULE=y CONFIG_SCSI_QLA_FC=y \
CONFIG_SCSI_QLA2XXX_TARGET=y QLA_32GBIT=no make all
If your kernel version is <2.6.28, then you should consider applying
kernel patch scst_fc_vport_create.patch from the "kernel" subdirectory.
Without it, creating and removing NPIV targets using SCST sysfs
interface will be disabled. NOTE: you will still be able to create and
remove NPIV targets using the standard Linux interface (i.e. echoing
wwpn:wwnn into /sys/class/fc_host/hostX/vport_create and
/sys/class/fc_host/hostX/vport_delete).
Then you should replace (or link) by the initiator driver from this
package "qla2xxx" subdirectory in kernel_source/drivers/scsi/ of the
currently running kernel and using your favorite kernel configuration
tool enable in the QLogic QLA2XXX Fibre Channel driver target mode
support (CONFIG_SCSI_QLA2XXX_TARGET). Then rebuild the kernel and its
modules. During this step you will compile the initiator driver. To
install it, install the built kernel and its modules.
Then edit qla2x00-target/Makefile and set SCST_INC_DIR variable to point
to the directory, where SCST's public include files are located. If you
install QLA2x00 target driver's source code in the SCST's directory,
then SCST_INC_DIR will be set correctly for you.
Also you can set SCST_DIR variable to the directory, where SCST was
built, but this is optional. If you don't set it or set incorrectly,
during the compilation you will get a bunch of harmless warnings like
"WARNING: "scst_rx_data" [/XXX/qla2x00tgt.ko] undefined!"
To compile the target driver, type 'make' in qla2x00-target/
subdirectory. It will build qla2x00tgt.ko module.
To install the target driver, type 'make install' in qla2x00-target/
subdirectory. The target driver will be installed in
/lib/modules/`you_kernel_version`/extra. To uninstall it, type 'make
uninstall'.
The build produces the matching qla2xxx_scst initiator/HBA module and
qla2x00tgt target adapter with the required SCST symbol dependencies.
Do not copy these sources into a kernel tree or edit Makefile include
paths. Installation is a separate privileged operation; use
../../INSTALL.md for the current procedure.
Usage
-----
WARNING: The commands in this section act on live kernel, HBA, Fibre
Channel fabric and storage state. Do not run them until the exact host,
ports, initiators and backing devices have been identified and approved.
The examples load or reload modules, issue a LIP, write sysfs, enable a
target and export writable storage; they are not safe production
defaults.
After the drivers are loaded and adapters successfully initialized by
the initiator driver, including firmware image load, you should
configure exported devices using the corresponding interface of SCST
@@ -93,36 +65,31 @@ purpose.
Then target mode should be enabled via a sysfs interface on a per card
basis, like:
echo "1" >/sys/kernel/scst_tgt/targets/qla2x00t/target/enabled
echo "1" >/sys/kernel/scst_tgt/targets/qla2x00t/25:00:00:f0:98:87:92:f3/enabled
See below for full description of the driver's sysfs interface.
With the obsolete proc interface you should instead use
target_mode_enabled under the appropriate scsi_host entry, like:
echo "1" >/sys/class/scsi_host/host0/target_mode_enabled
You can find some installation and configuration HOWTOs in
http://scst.sourceforge.net/qla2x00t-howto.html and
https://forums.openfiler.com/viewtopic.php?id=3422.
See ../doc/qla2x00t-howto.html for the in-tree installation and
configuration HOWTO.
IMPORTANT USAGE NOTES
---------------------
1. It is strongly recommended to use firmware version 5.x or higher for
24xx/25xx adapters. See
http://sourceforge.net/mailarchive/forum.php?thread_name=4B4CD39F.6020401%40vlnb.net&forum_name=scst-devel
for more details why. Recent report also suggest that openSUSE ships FW
8.6.0 that leads to severe "scst: TM fn ABORT_TASK/0" errors on the
target side, but using the latest 8.7.0 firmware from QLogic works well.
1. Obtain firmware from current vendor or distribution support for the
exact board model. The ql2xfwloadbin module parameter and the
FW_FILE_* definitions in ../qla_os.c describe the driver's firmware
source selection and exact request_firmware() names. See the in-tree
HOWTO for the safety requirements.
2. If you reload qla2x00tgt module, you should also reload qla2xxx
module, otherwise your initiators could not see the target, when it is
enabled after qla2x00tgt module load.
2. The qla2x00tgt target adapter and qla2xxx_scst initiator/HBA module
are a matched pair. Do not reload only one of them. Unloading either
module is a live storage operation and requires all affected targets,
sessions and initiator use to be stopped first.
3. You need to issue LIP after you enabled a target, if you enabled it
after one or more its initiators already started.
3. If a target is enabled after its initiators have started, use the
discovery procedure for the initiator driver and exact fabric port. A
LIP is a live fabric operation, not a safe generic discovery command.
Initiator and target modes
@@ -154,81 +121,54 @@ In all the modes you can at any time use sysfs attribute
ini_mode_force_reverse to force enable or disable initiator mode on any
particular port. Setting this attribute to 1 will reverse current status
of the initiator mode from enabled to disabled and vice versa.
Changing this attribute requests an ISP abort and waits for the HBA to
return online.
Explicit confirmation
---------------------
This option should (actually, almost always must) be enabled by echoing
"1" in /sys/kernel/scst_tgt/targets/qla2x00t/target/host/explicit_conform_enabled,
if a target card exports at least one stateful SCSI device, like tape,
This option should (actually, almost always must) be enabled by writing
"1" to the explicit_confirmation attribute in the target port
subdirectory under /sys/kernel/scst_tgt/targets/qla2x00t if a target
card exports at least one stateful SCSI device, like tape,
and class 2 isn't used, otherwise link-level errors could lead to loss
of the target/initiator state synchronization. Also check if initiator
supports this feature, it is reported in the kernel logs ("confirmed
completion supported" or not). No major performance degradation was
noticed, if it is enabled. Supported only for 23xx+. Disabled by
default.
For NPIV targets this option is set on their parent targets and shared
among all NPIV targets on this hardware target.
default. Changing this attribute requests an ISP abort and waits for the
HBA to return online.
Class 2
-------
Class 2 is the close equivalent of TCP in the network world. If you
enable it, all the Fibre Channel packets will be acknowledged. By
default, class 3 is used, which is UDP-like. Enable class 2 by echoing
"1" in /sys/kernel/scst_tgt/targets/qla2x00t/target/host/class2_enabled.
This option needs a special firmware with class 2 support. Disabled by
default.
default, class 3 is used, which is UDP-like. Enable class 2 by writing
"1" to class2_enabled through the target's host link. This option needs
a special firmware with class 2 support. Disabled by default. Changing
it requests an ISP abort.
N_Port ID Virtualization
------------------------
Unfortunately, due to severe problems in the original qla2xxx driver,
NPIV in this version is not supported. If you need NPIV, you can use
previous version 2.1 of this driver.
N_Port ID Virtualization (NPIV) is a Fibre Channel facility allowing
multiple N_Port IDs to share a single physical N_Port. NPIV is fully
supported by this driver. You must have 24xx+ ISPs with NPIV-supporting
and NPIV-switches switch(es) to use this facility.
You can add NPIV targets by echoing:
add_target target_name node_name=node_name_value; parent_host=parent_host_value
in /sys/kernel/scst_tgt/targets/qla2x00t/mgmt.
Removing NPIV targets is done by echoing:
del_target target_name
in/sys/kernel/scst_tgt/targets/qla2x00t/mgmt.
Also, you can create and remove NPIV targets using the standard Linux
interface (i.e. echoing wwpn:wwnn into /sys/class/fc_host/hostX/vport_create
and /sys/class/fc_host/hostX/vport_delete).
It is recommended to use scstadmin utility and its config file to
configure virtual NPIV targets instead of the above direct interface.
NPIV target mode is disabled in this driver. The target template does not
register add_target or del_target callbacks, and no qla2x00t management file
for virtual targets is created. Do not use instructions from older releases
to create NPIV targets with this driver.
Compilation options
-------------------
There are the following compilation options, that could be commented
in/out in Makefile:
- CONFIG_SCST_DEBUG - turns on some debugging code, including some logging.
Makes the driver considerably bigger and slower, producing large amount of
log data.
- CONFIG_SCST_TRACING - turns on ability to log events. Makes the driver
considerably bigger and leads to some performance loss.
CONFIG_SCST_DEBUG and CONFIG_SCST_TRACING are selected consistently for
the core and its consumers by the repository build mode; use the
top-level 2debug, 2release or 2perf target instead of editing this
driver's Makefile. The QLogic-only options below are disabled ccflags-y
definitions in qla2x00-target/Kbuild and require an intentional source
configuration change and rebuild.
- CONFIG_QLA_TGT_DEBUG_WORK_IN_THREAD - makes SCST process incoming
commands from the qla2x00t target driver and call the driver's
@@ -253,23 +193,22 @@ entries:
- None, one or more subdirectories for targets with name equal to port
names of the corresponding targets.
- trace_level - allows to enable and disable various tracing
facilities. See content of this file for help how to use it.
- trace_level - when tracing or debugging support is built, allows
tracing facilities to be changed. Read the file for usage help.
- version - read-only attribute, which allows to see version of
this driver and enabled optional features.
- mgmt - main management entry, which allows to configure NPIV targets.
See content of this file for help how to use it.
- hw_target (hardware target only) - read-only attribute with value 1.
It allows to distinguish hardware and virtual targets.
Each target subdirectory contains the following entries:
Each target subdirectory contains selected entries described below.
The complete common target interface is defined by ../../scst/SysfsRules
and the current SCST sysfs implementation.
- host - link pointing on the corresponding scsi_host of the initiator
driver
- hw_target - read-only attribute with value 1. It identifies a
hardware target.
- ini_groups - subdirectory defining initiator groups for this target,
used to define per-initiator access control. See SCST core README for
more details.
@@ -286,6 +225,14 @@ Each target subdirectory contains the following entries:
- explicit_confirmation - allows to enable explicit confirmations, see
above.
- abort_isp - write-only recovery attribute. Any write requests an ISP
abort and waits for the HBA to return online. This can disrupt live
Fibre Channel traffic.
- node_name and port_name - read or override the hardware target WWNs.
Changing either while the target is enabled requests an ISP abort and
HBA reinitialization.
- rel_tgt_id - allows to read or write SCSI Relative Target Port
Identifier attribute. This identifier is used to identify SCSI Target
Ports by some SCSI commands, mainly by Persistent Reservations
@@ -295,12 +242,6 @@ Each target subdirectory contains the following entries:
until rel_tgt_id becomes unique. This attribute initialized unique by
SCST by default.
- node_name (NPIV targets only) - read-only attribute, which allows to see
the target World Wide Node Name.
- parent_host (NPIV target only) - read-only attribute, which allows to see
the parent HBA World Wide Port Name (WWPN).
Subdirectory "sessions" contains one subdirectory for each connected
session with name equal to port name of the connected initiator.
@@ -313,28 +254,11 @@ Each session subdirectory contains the following entries:
- commands - contains overall number of SCSI commands in this session.
Below is a sample script, which configures 2 virtual disk "disk1" using
/disk1 image for usage with 25:00:00:f0:98:87:92:f3 hardware target, and
"disk2" using /disk2 image for usage with 50:50:00:00:00:00:00:11 NPIV
target. All initiators connected to this targets will see those devices.
#!/bin/bash
modprobe scst
modprobe scst_vdisk
echo "add_device disk1 filename=/disk1; nv_cache=1" >/sys/kernel/scst_tgt/handlers/vdisk_fileio/mgmt
echo "add_device disk2 filename=/disk2; nv_cache=1" >/sys/kernel/scst_tgt/handlers/vdisk_fileio/mgmt
modprobe qla2x00tgt
echo "add_target 50:50:00:00:00:00:00:11 node_name=50:50:00:00:00:00:00:00;parent_host=25:00:00:f0:98:87:92:f3" >\
/sys/kernel/scst_tgt/targets/qla2x00t/mgmt
echo "add disk1 0" >/sys/kernel/scst_tgt/targets/qla2x00t/25:00:00:f0:98:87:92:f3/luns/mgmt
echo "add disk2 0" >/sys/kernel/scst_tgt/targets/qla2x00t/50:50:00:00:00:00:00:11/luns/mgmt
echo 1 >/sys/kernel/scst_tgt/targets/qla2x00t/25:00:00:f0:98:87:92:f3/enabled
echo 1 >/sys/kernel/scst_tgt/targets/qla2x00t/50:50:00:00:00:00:00:11/enabled
WARNING: The scripts below perform live module and sysfs operations,
enable an FC target and export hard-coded SCSI devices, backing paths
and WWNs. They are interface examples, not runnable defaults. Do not
use them without substituting an approved test configuration and
following the scstadmin workflow referenced above.
Below is another sample script, which configures 1 real local SCSI disk
0:0:1:0 for usage with 25:00:00:f0:98:87:92:f3 target:
@@ -380,8 +304,8 @@ echo "add 25:00:00:f0:99:87:94:a3" >/sys/kernel/scst_tgt/targets/qla2x00t/25:00:
echo 1 >/sys/kernel/scst_tgt/targets/qla2x00t/25:00:00:f0:98:87:92:f3/enabled
The resulting overall SCST sysfs hierarchy with initiator
25:00:00:f0:99:87:94:a3 connected will look like:
An abridged view of the resulting SCST sysfs hierarchy with initiator
25:00:00:f0:99:87:94:a3 connected looks like:
/sys/kernel/scst_tgt
|-- devices
@@ -494,9 +418,11 @@ The resulting overall SCST sysfs hierarchy with initiator
|-- targets
| `-- qla2x00t
| |-- 25:00:00:f0:98:87:92:f3
| | |-- abort_isp
| | |-- enabled
| | |-- explicit_confirmation
| | |-- host -> ../../../../../class/scsi_host/host4
| | |-- hw_target
| | |-- ini_groups
| | | |-- 25:00:00:f0:99:87:94:a3
| | | | |-- initiators
@@ -522,8 +448,9 @@ The resulting overall SCST sysfs hierarchy with initiator
| | | | |-- device -> ../../../../../devices/cdrom
| | | | `-- read_only
| | | `-- mgmt
| | |-- node_name
| | |-- port_name
| | |-- rel_tgt_id
| | |-- hw_target
| | `-- sessions
| | `-- 25:00:00:f0:99:87:94:a3
| | |-- active_commands
@@ -532,7 +459,6 @@ The resulting overall SCST sysfs hierarchy with initiator
| | `-- luns -> ../../ini_groups/25:00:00:f0:99:87:94:a3/luns
| |-- trace_level
| |-- version
| `-- mgmt
|-- threads
|-- trace_level
`-- version
@@ -544,13 +470,12 @@ Performance advices
1. If you are going to use your target in an VM environment, for
instance as a shared storage with VMware, make sure all your VMs
connected to the target via *separate* sessions. You can check it using
SCST proc or sysfs interface. You should use available facilities, like
NPIV, to make separate sessions for each VM. If you miss it, you can
greatly loose performance of parallel access to your target from
different VMs. This isn't related to the case if your VMs are using the
same shared storage, like with VMFS, for instance. In this case all your
VM hosts will be connected to the target via separate sessions, which is
enough.
the SCST sysfs interface. Use the facilities available in the fabric
and initiators to make separate sessions for each VM; this legacy target
driver does not provide NPIV. Without separate sessions, parallel access
from different VMs can lose considerable performance. This does not
apply when VM hosts using shared storage such as VMFS already connect
through separate sessions.
2. See SCST core's README for more advices. Especially pay attention to
have io_grouping_type option set correctly.
+1 -1
View File
@@ -1,7 +1,7 @@
Known issues and unimplemented features
---------------------------------------
- NPIV targets not quite work. If you need NPIV, use QLogic git driver
- NPIV target mode is disabled. Use qla2x00t-32gbit for NPIV.
- Minor "ToDo"'s spread in the code.