How to configure QLogic target driver for 22xx/23xx/24xx/25xx adapters

How to configure QLogic target driver for 22xx/23xx/24xx/25xx adapters. Step by step guide.

ON TARGET

Download the appropriate firmware for your QLogic card from ftp://ftp.qlogic.com/outgoing/linux/firmware/ and save it in the /lib/firmware directory. 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 thread on the scst-devel mailing list: FC session gets closed with qla2x00t.

If no firmware image is available when the QLogic kernel module is loaded, the following error message will appear in the kernel log (/var/log/messages):
```
qla2xxx 0000:13:00.0: Firmware image unavailable.
qla2xxx 0000:13:00.0: Failed to initialize adapter
```
In this case I had to download ql2300_fw.bin.
Install the necessary kernel development packages. On a Debian system these packages can be installed as follows:
```
[root@proj ]# apt-get install gcc libncurses5-dev linux-headers lsscsi patch subversion
```
On RHEL/CentOS/SL systems these packages can be installed as follows:
```
[root@proj ]# yum install gcc ncurses-devel kernel-devel lsscsi patch subversion
```
And on SUSE systems these packages can be installed by running the following command:
```
[root@proj ]# zypper install gcc ncurses-devel kernel-devel lsscsi patch subversion
```
Download the SCST source code. That source code can be downloaded either from the SCST downloads page or from the SCST Subversion source code repository.

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.
```
[root@proj ]# svn co https://scst.svn.sourceforge.net/svnroot/scst/trunk scst
```
After the above command finished a directory called 'scst' will have been created in the current directory, which is /root in this how-to.

Unload the qla2xxx kernel module provided by your Linux distribution and blacklist it:

[root@proj ]# rmmod qla2xxx
[root@proj ]# echo blacklist qla2xxx >/etc/modprobe.d/blacklist-qla2xxx.conf

Find out whether you will need SCSI pass-through and/or the iSCSI zero-copy optimization. If not, skip the kernel download, patch, rebuild and reboot steps and continue with the SCST build step.
Decide whether you want to start from a vanilla Linux kernel source tree or from the kernel source tree specific to your Linux distribution. Vanilla kernel sources can be downloaded from http://www.kernel.org/pub/linux/kernel/. Unzip the downloaded archive under /usr/src:
```
[root@proj src ]# tar -xjf /usr/src/linux-2.6.26.tar.bz2
```
Instructions for obtaining a distribution-specific kernel source tree vary. An example for Debian:
```
[root@proj src ]# apt-get install linux-source-2.6
[root@proj src ]# tar xjf linux-source-2.6.32.tar.bz2
```

Create the necessary symbolic links:

[root@proj src ]# pwd
/usr/src
[root@proj src ]# ln -s /usr/src/linux-2.6.26 linux
[root@proj src ]# ln -s /usr/src/linux-2.6.26 kernel

Patch the kernel that has just been downloaded:

[root@proj ]# cd /usr/src/linux-2.6.26
[root@proj linux-2.6.26]# patch -p1 < /root/scst/scst/kernel/scst_exec_req_fifo-2.6.26.patch

Now build the kernel.

Make sure you disable kernel hacking feature and HIGHMEM4G|HIGHMEM64G, i.e.

[root@proj ]# grep -i highmem /usr/src/linux/.config
CONFIG_NOHIGHMEM=y
# CONFIG_HIGHMEM4G is not set
# CONFIG_HIGHMEM64G is not set

If you have a system with more than 1GB of memory, consider to change CONFIG_VMSPLIT option to the corresponding value.

[root@proj linux ]# pwd
/usr/src/linux
[root@proj linux ]# make menuconfig
[root@proj linux ]# make bzImage
[root@proj linux ]# make modules
[root@proj linux ]# make modules_install
[root@proj linux ]# make install

Reboot the system and during boot select the freshly built kernel to boot from.
OPTIONAL step: clean up the kernel modules directory before building the SCST kernel modules.
This is only necessary if you encounter the following error message: "scst: disagrees about version of symbol struct_module".

That error message indicates that a kernel module load was compiled against kernel headers that did not match the running kernel. Doing a clean rebuild of the kernel and SCST should make the above error go away. To make sure nothing of the old kernel is left, do a clean rebuild of the Linux kernel and SCST as follows:
```
[root@proj linux ] pwd
/usr/src/linux
[root@proj linux ] make oldconfig
[root@proj linux ] make clean
[root@proj linux ] rm -rf /lib/modules/`uname -r`
[root@proj linux ] make modules
[root@proj linux ] make modules_install
[root@proj linux ] make install
[root@proj linux ] reboot
```
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:
```
[root@proj trunk ] pwd
/root/scst
[root@proj trunk ] make 2release
```

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

[root@proj ]# cd /root/scst/scst/src
[root@proj ]# make all
[root@proj ]# make install

Build the QLogic target driver as follows:

Change the working directory to the SCST source tree.
```
[root@proj trunk]# pwd
/root/scst
```

Install the qla2xxx initiator kernel module from the SCST tree:

[root@proj trunk]# BUILD_2X_MODULE=y CONFIG_SCSI_QLA_FC=y CONFIG_SCSI_QLA2XXX_TARGET=y \
make -s -C qla2x00t/qla2x00-target install

Verify that compilation and installation succeeded:

[root@proj trunk]# 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

Insert the kernel modules.
The kernel modules have been installed in '/lib/modules/`your_kernel_version`/extra'.
In addition, scst.h, scst_debug.h as well as Module.symvers or Modules.symvers have been copied to '/usr/local/include/scst'.
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.

[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

where:

scst - SCST itself.
scst_disk - device handler for disks (type 0).
scst_tape - device handler for tapes (type 1).
scst_processor - device handler for processors (type 3).
scst_cdrom - device handler for CDROMs (type 5).
scst_modisk - device handler for MO disks (type 7).
scst_changer - device handler for medium changers (type 8).
scst_raid - device handler for storage array controller (e.g. raid) (type C).
scst_vdisk - device handler for virtual disks (file, device or ISO CD image)..
scst_user - user space device handler.

You can insert any of these kernel modules with the 'modprobe' program. As you can see, I've inserted all SCST kernel modules !!!

[root@proj ]# for m in scst qla2xxx_scst qla2x00tgt scst_vdisk scst_user scst_disk ...; do modprobe $m; done

This will result in the following dmesg output:

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

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. For Debian systems, the initial RAM disk can be rebuilt by running the following command:
```
[root@proj ]# update-initrd -c -k $(uname -r)
```
For Ubuntu systems:
```
[root@proj ]# update-initramfs -c -k $(uname -r)
```
For RHEL/CentOS/SL systems:
```
[root@proj ]# mkinitrd -f /boot/initramfs-$(uname -r).img $(uname -r)
```
And for SUSE systems:
```
[root@proj ]# mkinitrd
```

Now let's create our virtual device:

[root@proj ]# dd if=/dev/zero of=/mnt/disk1 bs=1024k count=512
512+0 records in
512+0 records out

[root@proj ]# ls -l /mnt/disk1
-rw-r--r--  1 root root 536870912 Jun 23 13:27 /mnt/disk1

[root@proj ]# file /mnt/disk1
/mnt/disk1: data

To see the device on the initiator we have to add it in the LUNs set of our target.
We must have a LUN with number 0 (LUs numeration must not start from, e.g., 1).

The simplest way to do that is to write an scstadmin config file:

HANDLER vdisk_fileio {
	DEVICE disk1 {
		filename /mnt/disk1
	}
}

TARGET_DRIVER qla2x00t {
	TARGET 25:00:00:f0:98:87:92:f3 {
		LUN 0 disk1

		enabled 1
	}
}

Before we can apply that file we have to install scstadmin first:

[root@proj ]# make -C scstadmin -s install

Let's save our configuration file as /etc/scst.conf.

That file can be applied via scstadmin:

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

The same can be done directly via the sysfs interface of SCST:

[root@proj ]# echo "add_device disk1 filename=/mnt/disk1" >/sys/kernel/scst_tgt/handlers/vdisk_fileio/mgmt
[root@proj ]# echo "add disk1 0" >/sys/kernel/scst_tgt/targets/qla2x00t/25:00:00:f0:98:87:92:f3/luns/mgmt
[root@proj ]# echo "1" >/sys/kernel/scst_tgt/targets/qla2x00t/25:00:00:f0:98:87:92:f3/enabled

ON INITIATOR

A quote from the SCST README:
Without loading appropriate device handler, corresponding device will be invisible for remote initiators, hence we have to add them manually.
But as I've already loaded the device handler (scst_vdisk) on the target, I don't have to perform any additional steps.
After enabling the target mode 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. 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:
```
[root@initiator ]# echo "- - -" >/sys/class/scsi_host/hostX/scan
```
where X is the host number.