How to Configure the FC QLogic Target Driver for 22xx/23xx/24xx/25xx/26xx Adapters

TARGET SYSTEM


  1. 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:
    [root@proj ]# dmesg -c >/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.
    The above information not only contains the HBA model number (QLE2562) but also the RISC controller ID (ISP2532).
  2. Download the Linux version of the QConvergeConsoleCLI software package from http://driverdownloads.qlogic.com/ and install that software package.
  3. Download the appropriate firmware for your QLogic card from http://driverdownloads.qlogic.com/. 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, FC session gets closed with qla2x00t, scst-devel mailing list, January 2010.

    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):
    qla2xxx 0000:13:00.0: Firmware image unavailable.
    qla2xxx 0000:13:00.0: Failed to initialize adapter
  4. 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:
    ISP ModelFirmware file
    name
    ISP 21XXql2100_fw.bin
    ISP 22XXql2200_fw.bin
    ISP 2300ql2300_fw.bin
    ISP 2322ql2322_fw.bin
    ISP 24XXql2400_fw.bin
    ISP 25XXql2500_fw.bin
    ISP 2031ql2600_fw.bin
    ISP 27XXql2700_fw.bin
  5. 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, Re: [ANNOUNCE]: qla2x00t QLogic git integration into the SCST build tree, scst-devel mailing list, September 5, 2014). An example:
    [root@proj ]# /opt/QLogic_Corporation/QConvergeConsoleCLI/qaucli -fc -b all /lib/firmware/ql2500_fw.bin
  6. 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-`uname -r` 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
  7. Download the latest QLogic SCST target driver:
    [root@proj ]# git clone git://git.qlogic.com/scst-qla2xxx.git
  8. 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://svn.code.sf.net/p/scst/svn/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.
  9. In the SCST directory, create a soft link to the QLogic driver:
    [root@proj ]# cd scst
    [root@proj scst]# ln -s ../scst-qla2xxx/drivers/scsi/qla2xxx qla2x00t_git
  10. 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.
  11. 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 ]# cd /usr/src
    [root@proj src ]# tar -xjf /usr/src/linux-3.11.8.tar.bz2
    Instructions for obtaining a distribution-specific kernel source tree vary. An example for Debian:
    [root@proj src ]# apt-get install linux-source-`uname -r`
    [root@proj src ]# tar xjf linux-source-`uname -r`.tar.bz2
  12. The next step is to configure the kernel:
    [root@proj linux ]# pwd
    /usr/src/linux
    [root@proj linux ]# make menuconfig
    If you have built a 32-bit kernel make sure to disable HIGHMEM4G and HIGHMEM64G, i.e.
    [root@proj linux ]# grep -i highmem .config
    CONFIG_NOHIGHMEM=y
    # CONFIG_HIGHMEM4G is not set
    # CONFIG_HIGHMEM64G is not set
    If you have built a 32-bit kernel on a system with more than 1GB of memory, consider to change CONFIG_VMSPLIT option to an appropriate value.
  13. Next, build and install the kernel:
    [root@proj linux ]# make -j$(ls -1d /sys/devices/system/cpu/cpu[0-9]* | wc -l) bzImage modules
    [root@proj linux ]# make modules_install install
  14. Reboot the system and during boot select the freshly built kernel to boot from.
  15. Unload the qla2xxx kernel module provided by your Linux distribution and blacklist it:
    [root@proj ]# echo blacklist qla2xxx >/etc/modprobe.d/blacklist-qla2xxx.conf
    [root@proj ]# rmmod qla2xxx
  16. 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 scst ]# pwd
    /root/scst
    [root@proj scst ]# make 2release
  17. 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:
    [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
    Verify that compilation and installation succeeded:
    [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   
    
  18. 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:
    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
  19. 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:
    [root@proj ]# type update-initrd >/dev/null 2>&1 && update-initrd -c -k `uname -r`
    [root@proj ]# type update-initramfs >/dev/null 2>&1 && update-initramfs -c -k `uname -r`
    [root@proj ]# if type mkinitrd >/dev/null 2>&1; then
    if { rpm -q sles-release || rpm -q openSUSE-release; } >/dev/null 2>&1;
    then mkinitrd; else mkinitrd -f /boot/initramfs-`uname -r`.img `uname -r`; fi; fi
  20. 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
  21. The next step is to install scstadmin:
    [root@proj ]# make -C scstadmin -s install
  22. 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 generate an scstadmin config file, e.g. as follows:
    modprobe qla2x00tgt
    find /sys/kernel/scst_tgt/targets/qla2x00t -name enabled | \
    while read f; do echo 1 >$f & done; wait
    find /sys -name issue_lip | while read f; do echo 1 >$f & done; wait
    {
    cat <<EOF
    HANDLER vdisk_fileio {
            DEVICE disk1 {
                    filename /mnt/disk1
            }
    }
    EOF
    for p in /sys/kernel/scst_tgt/targets/qla2x00t/*; do
    [ -d $p ] || continue
    cat <<EOF
    
    TARGET_DRIVER qla2x00t {
            TARGET $(basename $p) {
                    enabled 1
    
                    LUN 0 disk1
            }
    }
    EOF
    done
    } >scst.conf
    Check the generated config file. If it looks fine to you, move it to the default location:
    mv -i scst.conf /etc/scst.conf
    The SCST configuration in 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
    
  23. If you want to configure LUN masking the next step is to configure one initiator group per initiator. To do that you need to discover the initiator port WWNs. One way to discover these is as follows:
    [root@proj ]# ls -d /sys/kernel/scst_tgt/targets/qla2x00t/*/sessions/*|sed 's,.*/,,' | sort -u
    10:00:00:00:c9:95:c7:1a
    10:00:00:00:c9:95:c7:1b
    21:00:00:24:ff:46:c0:84
    21:00:00:24:ff:46:c0:85
    21:00:00:24:ff:6c:ca:d8
    21:00:00:24:ff:6c:ca:d9
    21:00:00:24:ff:6c:ca:da
    21:00:00:24:ff:6c:ca:db
    More information about initiator group configuration together with an example can be found in the scst.conf man page.

INITIATOR SYSTEM

  1. 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.
  2. 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.