Patch from Vu Pham <vuhuong@mellanox.com>: SRP target driver
[mirror/scst/.git] / srpt / README
1 SCSI RDMA Protocol (SRP) Target driver for Linux
2 =================================================
3
4 SRP Target driver is designed to work directly on top of OpenFabrics
5 OFED-1.x software stack (http://www.openfabrics.org) or Infiniband
6 drivers in Linux kernel tree (kernel.org). It also interfaces with 
7 Generic SCSI target mid-level driver - SCST (http://scst.sourceforge.net)
8
9 NOTES: This SRP Target driver can only compile and work with IB driver
10        in Linux vanilla kernel. It does not compile and work with IB
11        driver in OFED-1.x packages
12
13        If you want to work with IB driver in OFED-1.x package, you should
14        read and follow instruction in README.ofed file
15
16
17 Installation
18 ------------
19 $ make 
20 $ make install
21
22 To minimize QUEUEFULL conditions, please apply scst_increase_max_tgt_cmds
23 patch and recompile scst
24
25 $ cd ~scst/trunk
26 $ patch -p0 < srpt/patches/scst_increasa_max_tgt_cmds.patch
27 $ make scst scst_install srpt srpt_install
28
29
30 How-to run
31 -----------
32 A. On srp target machine
33 1. Please refer to SCST's README for loading scst driver and its
34 dev_handlers drivers (scst_disk, scst_vdisk block or file IO mode, nullio, ...)
35
36 Example 1: working with real back-end scsi disks
37 a. modprobe scst
38 b. modprobe scst_disk
39 c. cat /proc/scsi_tgt/scsi_tgt
40
41 ibstor00:~ # cat /proc/scsi_tgt/scsi_tgt 
42 Device (host:ch:id:lun or name)                             Device handler
43 0:0:0:0                                                     dev_disk
44 4:0:0:0                                                     dev_disk
45 5:0:0:0                                                     dev_disk
46 6:0:0:0                                                     dev_disk
47 7:0:0:0                                                     dev_disk
48
49 Now you want to exclude the first scsi disk and expose the last 4 scsi disks as
50 IB/SRP luns for I/O
51 echo "add 4:0:0:0 0" >/proc/scsi_tgt/groups/Default/devices
52 echo "add 5:0:0:0 1" >/proc/scsi_tgt/groups/Default/devices
53 echo "add 6:0:0:0 2" >/proc/scsi_tgt/groups/Default/devices
54 echo "add 7:0:0:0 3" >/proc/scsi_tgt/groups/Default/devices
55
56 Example 2: working with VDISK FILEIO mode (using md0 device and file 10G-file)
57 a. modprobe scst
58 b. modprobe scst_vdisk
59 c. echo "open vdisk0 /dev/md0" > /proc/scsi_tgt/vdisk/vdisk
60 d. echo "open vdisk1 /10G-file" > /proc/scsi_tgt/vdisk/vdisk
61 e. echo "add vdisk0 0" >/proc/scsi_tgt/groups/Default/devices
62 f. echo "add vdisk1 1" >/proc/scsi_tgt/groups/Default/devices
63
64 Example 3: working with VDISK BLOCKIO mode (using md0 device, sda, and cciss/c1d0)
65 a. modprobe scst
66 b. modprobe scst_vdisk
67 c. echo "open vdisk0 /dev/md0 BLOCKIO" > /proc/scsi_tgt/vdisk/vdisk
68 d. echo "open vdisk1 /dev/sda BLOCKIO" > /proc/scsi_tgt/vdisk/vdisk
69 e. echo "open vdisk2 /dev/cciss/c1d0 BLOCKIO" > /proc/scsi_tgt/vdisk/vdisk
70 f. echo "add vdisk0 0" >/proc/scsi_tgt/groups/Default/devices
71 g. echo "add vdisk1 1" >/proc/scsi_tgt/groups/Default/devices
72 h. echo "add vdisk2 2" >/proc/scsi_tgt/groups/Default/devices
73
74 2. modprobe ib_srpt
75
76
77 B. On initiator machines you can manualy do the following steps:
78 1. modprobe ib_srp
79 2. ipsrpdm -c (to discover new SRP target)
80 3. echo <new target info> > /sys/class/infiniband_srp/srp-mthca0-1/add_target
81 4. fdisk -l (will show new discovered scsi disks)
82
83 Example:
84 Assume that you use port 1 of first HCA in the system ie. mthca0
85
86 [root@lab104 ~]# ibsrpdm -c -d /dev/infiniband/umad0
87 id_ext=0002c90200226cf4,ioc_guid=0002c90200226cf4,
88 dgid=fe800000000000000002c90200226cf5,pkey=ffff,service_id=0002c90200226cf4
89 [root@lab104 ~]# echo id_ext=0002c90200226cf4,ioc_guid=0002c90200226cf4,
90 dgid=fe800000000000000002c90200226cf5,pkey=ffff,service_id=0002c90200226cf4 >
91 /sys/class/infiniband_srp/srp-mthca0-1/add_target
92
93 OR
94
95 + You can edit /etc/infiniband/openib.conf to load srp driver and srp HA daemon
96 automatically ie. set SRP_LOAD=yes, and SRPHA_ENABLE=yes
97 + To set up and use high availability feature you need dm-multipath driver
98 and multipath tool
99 + Please refer to OFED-1.x SRP's user manual for more in-details instructions
100 on how-to enable/use HA feature
101
102
103 TO DO
104 ------
105 + Stress test and stabilize the code
106 + Performance tuning