srpt/README

   1 SCSI RDMA Protocol (SRP) Target driver for Linux
   2 =================================================
   3
   4 The SRP Target driver is designed to work directly on top of the
   5 OpenFabrics OFED-1.x software stack (http://www.openfabrics.org) or
   6 the Infiniband drivers in the Linux kernel tree
   7 (http://www.kernel.org). The SRP target driver also interfaces with
   8 the generic SCSI target mid-level driver called SCST
   9 (http://scst.sourceforge.net).
  10
  11 NOTES: This SRP Target driver can only be compiled and will only work
  12 with the IB drivers in the vanilla Linux kernel. It does not compile
  13 and work with the IB drivers included in any of the OFED-1.x packages.
  14
  15 If you want to work with the IB drivers in one of the OFED-1.x
  16 packages, you should read and follow instruction in README.ofed file.
  17
  18
  19 Installation
  20 ------------
  21 If you have obtained SCST from the SCST SVN repository as an out-of-tree
  22 kernel subsystem, proceed as follows to compile and install the SRP target
  23 driver:
  24
  25 $ make
  26 $ make install
  27
  28 To minimize QUEUEFULL conditions, please apply scst_increase_max_tgt_cmds
  29 patch and recompile scst
  30
  31 $ cd ~scst/trunk
  32 $ patch -p0 < srpt/patches/scst_increase_max_tgt_cmds.patch
  33 $ make scst scst_install srpt srpt_install
  34
  35 On the other hand, if you have obtained the SCST source code included
  36 with the Linux kernel source code, enable and build the SRP target driver
  37 in the same way as any other kernel module. Make sure to enable SCST itself
  38 and InfiniBand before attempting to enable the SRP target driver.
  39
  40
  41 How-to run
  42 -----------
  43 A. On srp target machine
  44 1. Please refer to SCST's README for loading scst driver and its
  45 dev_handlers drivers (scst_disk, scst_vdisk block or file IO mode, nullio, ...)
  46
  47 Example 1: working with real back-end scsi disks
  48 a. modprobe scst
  49 b. modprobe scst_disk
  50 c. cat /proc/scsi_tgt/scsi_tgt
  51
  52 ibstor00:~ # cat /proc/scsi_tgt/scsi_tgt
  53 Device (host:ch:id:lun or name)                             Device handler
  54 0:0:0:0                                                     dev_disk
  55 4:0:0:0                                                     dev_disk
  56 5:0:0:0                                                     dev_disk
  57 6:0:0:0                                                     dev_disk
  58 7:0:0:0                                                     dev_disk
  59
  60 Now you want to exclude the first scsi disk and expose the last 4 scsi disks as
  61 IB/SRP luns for I/O
  62 echo "add 4:0:0:0 0" >/proc/scsi_tgt/groups/Default/devices
  63 echo "add 5:0:0:0 1" >/proc/scsi_tgt/groups/Default/devices
  64 echo "add 6:0:0:0 2" >/proc/scsi_tgt/groups/Default/devices
  65 echo "add 7:0:0:0 3" >/proc/scsi_tgt/groups/Default/devices
  66
  67 Example 2: working with VDISK FILEIO mode (using md0 device and file 10G-file)
  68 a. modprobe scst
  69 b. modprobe scst_vdisk
  70 c. echo "open vdisk0 /dev/md0" > /proc/scsi_tgt/vdisk/vdisk
  71 d. echo "open vdisk1 /10G-file" > /proc/scsi_tgt/vdisk/vdisk
  72 e. echo "add vdisk0 0" >/proc/scsi_tgt/groups/Default/devices
  73 f. echo "add vdisk1 1" >/proc/scsi_tgt/groups/Default/devices
  74
  75 Example 3: working with VDISK BLOCKIO mode (using md0 device, sda, and cciss/c1d0)
  76 a. modprobe scst
  77 b. modprobe scst_vdisk
  78 c. echo "open vdisk0 /dev/md0 BLOCKIO" > /proc/scsi_tgt/vdisk/vdisk
  79 d. echo "open vdisk1 /dev/sda BLOCKIO" > /proc/scsi_tgt/vdisk/vdisk
  80 e. echo "open vdisk2 /dev/cciss/c1d0 BLOCKIO" > /proc/scsi_tgt/vdisk/vdisk
  81 f. echo "add vdisk0 0" >/proc/scsi_tgt/groups/Default/devices
  82 g. echo "add vdisk1 1" >/proc/scsi_tgt/groups/Default/devices
  83 h. echo "add vdisk2 2" >/proc/scsi_tgt/groups/Default/devices
  84
  85 2. modprobe ib_srpt
  86
  87
  88 B. On initiator machines you can manually do the following steps:
  89 1. modprobe ib_srp
  90 2. ipsrpdm -c (to discover new SRP target)
  91 3. echo <new target info> > /sys/class/infiniband_srp/srp-mthca0-1/add_target
  92 4. fdisk -l (will show new discovered scsi disks)
  93
  94 Example:
  95 Assume that you use port 1 of first HCA in the system ie. mthca0
  96
  97 [root@lab104 ~]# ibsrpdm -c -d /dev/infiniband/umad0
  98 id_ext=0002c90200226cf4,ioc_guid=0002c90200226cf4,
  99 dgid=fe800000000000000002c90200226cf5,pkey=ffff,service_id=0002c90200226cf4
 100 [root@lab104 ~]# echo id_ext=0002c90200226cf4,ioc_guid=0002c90200226cf4,
 101 dgid=fe800000000000000002c90200226cf5,pkey=ffff,service_id=0002c90200226cf4 >
 102 /sys/class/infiniband_srp/srp-mthca0-1/add_target
 103
 104 OR
 105
 106 + You can edit /etc/infiniband/openib.conf to load srp driver and srp HA daemon
 107 automatically ie. set SRP_LOAD=yes, and SRPHA_ENABLE=yes
 108 + To set up and use high availability feature you need dm-multipath driver
 109 and multipath tool
 110 + Please refer to OFED-1.x SRP's user manual for more in-details instructions
 111 on how-to enable/use HA feature
 112
 113
 114 Performance notes
 115 -----------------
 116
 117 In some cases, for instance working with SSD devices, which consume 100%
 118 of a single CPU load for data transfers in their internal threads, to
 119 maximize IOPS it can be needed to assign for those threads dedicated
 120 CPUs using Linux CPU affinity facilities. No IRQ processing should be
 121 done on those CPUs. Check that using /proc/interrupts. See taskset
 122 command and Documentation/IRQ-affinity.txt in your kernel's source tree
 123 for how to assign CPU affinity to tasks and IRQs.
 124
 125 The reason for that is that processing of coming commands in SIRQ context
 126 can be done on the same CPUs as SSD devices' threads doing data
 127 transfers. As the result, those threads won't receive all the CPU power
 128 and perform worse.
 129
 130 Alternatively to CPU affinity assignment, you can try to enable SRP
 131 target's internal thread. It will allows Linux CPU scheduler to better
 132 distribute load among available CPUs. To enable SRP target driver's
 133 internal thread you should load ib_srpt module with parameter
 134 "thread=1".
 135
 136
 137 Send questions about this driver to scst-devel@lists.sourceforge.net, CC:
 138 Vu Pham <vuhuong@mellanox.com> and Bart Van Assche <bart.vanassche@gmail.com>.