Patch from Bart Van Assche <bart.vanassche@gmail.com>:
[mirror/scst/.git] / srpt / README.ofed
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 By interfacing with SCST driver we are able to work and  support a lot IO
10 modes on real or virtual devices in the backend
11 1. scst_disk  -- interfacing with scsi sub-system to claim and export real
12 scsi devices ie. disks, hardware raid volumes, tape library as SRP's luns
13
14 2. scst_vdisk -- fileio and blockio modes. This allows you to turn software raid
15 volumes, LVM volumes, IDE disks, and normal files into SRP's luns (required to
16 work with latest scst's svn tree)
17
18 3. NULLIO mode will allow you to measure the performance without sending IOs
19 to *real* devices
20
21
22 Prerequisites
23 -------------
24 1. First it is required to download and install SCST driver. Please
25 refer to SCST's Internet page http://scst.sourceforge.net for download
26 and installation instructions. You can also find SCST's design document, 
27 svn repository development tree and utility tools for basic storage
28 management
29
30 a. git clone git://git.openfabrics.org/~vu/srpt_inc ~/srpt_inc
31 b. Checking out scst's svn development tree revision 245
32 svn co https://scst.svn.sourceforge.net/svnroot/scst/trunk/scst -r 245
33 c. cd scst
34 d. patch -p0 < ~/srpt_inc/scst_r245.patch
35 e. make and make install
36
37 2. Download/install IB low-level driver from OFED package or linux kernel tree
38 a. SRP target is part of OFED-1.3
39 or
40 b. Download and install OFED-1.x (x > 1) with kernel_ib development package rpm
41 or
42 c. Built and installed Infiniband driver in Linux "vanilla" kernel tree
43    from kernel.org
44
45 3. Download SRP target driver from openfabrics.org (needed for 2b, 2c)
46 git clone git://git.openfabrics.org/~vu/srpt.git ~/srpt
47
48
49 Installation
50 ------------
51 A. For OFED-1.3
52 ----------------
53 SRP target is part of ofed-1.3. Go through normal installation with srpt enable
54
55
56 B. Instruction to included in and built with OFED-1.2.5 development tree
57 -----------------------------------------------------------------------
58 1. cd /usr/src/ofa_kernel-1.2.5 or /usr/src/ofa_kernel-1.2.c or
59 ~/ofa_1_2_c_kernel-200708xx-yyyy
60 2. patch -p1 < ~/srpt_inc/add_srpt_01.patch 
61 3. patch -p1 < ~/srpt_inc/add_srpt_03.patch 
62 4. patch -p1 < ~/srpt_inc/add_srpt_04.patch 
63 5. cp -r ~/srpt drivers/infiniband/ulp/srpt
64 6. ./configure --with-core-mod --with-mthca-mod --without-mthca_debug-mod
65    --with-srp-target-mod <and any other modules/drivers as needed>
66 7. make and make install
67
68 C. Instruction to be included in and built with OFED-1.2 development tree
69 --------------------------------------------------------------------------
70 1. cd /usr/src/ofa_kernel-1.2 or /usr/src/ofa_kernel-1.2 or
71 ~/ofa_1_2_kernel-200708xx-yyyy
72 2. patch -p1 < ~/srpt_inc/add_srpt_01.patch
73 3. patch -p1 < ~/srpt_inc/add_srpt_03.patch
74 4. patch -p1 < ~/srpt_inc/add_srpt_04.patch
75 5. cp -r ~/srpt drivers/infiniband/ulp/srpt
76 6. patch -p1 < ~/srpt_inc/add_srpt_ofed_1_2.patch
77 7. ./configure --with-core-mod --with-mthca-mod --without-mthca_debug-mod
78    --with-srp-target-mod <and any other modules/drivers as needed>
79 8. make and make install
80
81 D. Instruction to be included in and built with "vanilla" kernel development tree
82 ----------------------------------------------------------------------------------
83 1. cd /usr/src/linux-2.6.1x
84 2. patch -p1 < ~/srpt_inc/add_srpt_03.patch
85 3. cp -r ~/srpt drivers/infiniband/ulp/srpt
86 4. configure and build SRP target module driver as normal
87
88
89 How-to run
90 -----------
91 A. On srp target machine
92 1. Please refer to SCST's README for loading scst driver and its
93 dev_handlers drivers (scst_disk, scst_vdisk block or file IO mode, nullio, ...)
94
95 Example 1: working with real back-end scsi disks
96 a. modprobe scst
97 b. modprobe scst_disk
98 c. cat /proc/scsi_tgt/scsi_tgt
99
100 ibstor00:~ # cat /proc/scsi_tgt/scsi_tgt 
101 Device (host:ch:id:lun or name)                             Device handler
102 0:0:0:0                                                     dev_disk
103 4:0:0:0                                                     dev_disk
104 5:0:0:0                                                     dev_disk
105 6:0:0:0                                                     dev_disk
106 7:0:0:0                                                     dev_disk
107
108 Now you want to exclude the first scsi disk and expose the last 4 scsi disks as
109 IB/SRP luns for I/O
110 echo "add 4:0:0:0 0" >/proc/scsi_tgt/groups/Default/devices
111 echo "add 5:0:0:0 1" >/proc/scsi_tgt/groups/Default/devices
112 echo "add 6:0:0:0 2" >/proc/scsi_tgt/groups/Default/devices
113 echo "add 7:0:0:0 3" >/proc/scsi_tgt/groups/Default/devices
114
115 Example 2: working with VDISK FILEIO mode (using md0 device and file 10G-file)
116 a. modprobe scst
117 b. modprobe scst_vdisk
118 c. echo "open vdisk0 /dev/md0" > /proc/scsi_tgt/vdisk/vdisk
119 d. echo "open vdisk1 /10G-file" > /proc/scsi_tgt/vdisk/vdisk
120 e. echo "add vdisk0 0" >/proc/scsi_tgt/groups/Default/devices
121 f. echo "add vdisk1 1" >/proc/scsi_tgt/groups/Default/devices
122
123 Example 3: working with VDISK BLOCKIO mode (using md0 device, sda, and cciss/c1d0)
124 a. modprobe scst
125 b. modprobe scst_vdisk
126 c. echo "open vdisk0 /dev/md0 BLOCKIO" > /proc/scsi_tgt/vdisk/vdisk
127 d. echo "open vdisk1 /dev/sda BLOCKIO" > /proc/scsi_tgt/vdisk/vdisk
128 e. echo "open vdisk2 /dev/cciss/c1d0 BLOCKIO" > /proc/scsi_tgt/vdisk/vdisk
129 f. echo "add vdisk0 0" >/proc/scsi_tgt/groups/Default/devices
130 g. echo "add vdisk1 1" >/proc/scsi_tgt/groups/Default/devices
131 h. echo "add vdisk2 2" >/proc/scsi_tgt/groups/Default/devices
132
133 2. modprobe ib_srpt
134
135
136 B. On initiator machines you can manualy do the following steps:
137 1. modprobe ib_srp
138 2. ipsrpdm -c (to discover new SRP target)
139 3. echo <new target info> > /sys/class/infiniband_srp/srp-mthca0-1/add_target
140 4. fdisk -l (will show new discovered scsi disks)
141
142 Example:
143 Assume that you use port 1 of first HCA in the system ie. mthca0
144
145 [root@lab104 ~]# ibsrpdm -c -d /dev/infiniband/umad0
146 id_ext=0002c90200226cf4,ioc_guid=0002c90200226cf4,
147 dgid=fe800000000000000002c90200226cf5,pkey=ffff,service_id=0002c90200226cf4
148 [root@lab104 ~]# echo id_ext=0002c90200226cf4,ioc_guid=0002c90200226cf4,
149 dgid=fe800000000000000002c90200226cf5,pkey=ffff,service_id=0002c90200226cf4 >
150 /sys/class/infiniband_srp/srp-mthca0-1/add_target
151
152 OR
153
154 + You can edit /etc/infiniband/openib.conf to load srp driver and srp HA daemon
155 automatically ie. set SRP_LOAD=yes, and SRPHA_ENABLE=yes
156 + To set up and use high availability feature you need dm-multipath driver
157 and multipath tool
158 + Please refer to OFED-1.x SRP's user manual for more in-details instructions
159 on how-to enable/use HA feature
160
161
162 TO DO
163 ------
164 + Stress test and stabilize the code
165 + Performance tuning