1f21f6a60eb2c8a54999a2567e81cec016f2b924
[mirror/scst/.git] / srpt / README_in-tree
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 How-to run
12 -----------
13
14 A. On srp target machine
15 1. Please refer to SCST's README for loading scst driver and its
16 dev_handlers drivers (scst_disk, scst_vdisk block or file IO mode, nullio, ...)
17
18 Example 1: working with real back-end scsi disks
19 a. modprobe scst
20 b. modprobe scst_disk
21 c. cat /proc/scsi_tgt/scsi_tgt
22
23 ibstor00:~ # cat /proc/scsi_tgt/scsi_tgt
24 Device (host:ch:id:lun or name)                             Device handler
25 0:0:0:0                                                     dev_disk
26 4:0:0:0                                                     dev_disk
27 5:0:0:0                                                     dev_disk
28 6:0:0:0                                                     dev_disk
29 7:0:0:0                                                     dev_disk
30
31 Now you want to exclude the first scsi disk and expose the last 4 scsi disks as
32 IB/SRP luns for I/O
33 echo "add 4:0:0:0 0" >/proc/scsi_tgt/groups/Default/devices
34 echo "add 5:0:0:0 1" >/proc/scsi_tgt/groups/Default/devices
35 echo "add 6:0:0:0 2" >/proc/scsi_tgt/groups/Default/devices
36 echo "add 7:0:0:0 3" >/proc/scsi_tgt/groups/Default/devices
37
38 Example 2: working with VDISK FILEIO mode (using md0 device and file 10G-file)
39 a. modprobe scst
40 b. modprobe scst_vdisk
41 c. echo "open vdisk0 /dev/md0" > /proc/scsi_tgt/vdisk/vdisk
42 d. echo "open vdisk1 /10G-file" > /proc/scsi_tgt/vdisk/vdisk
43 e. echo "add vdisk0 0" >/proc/scsi_tgt/groups/Default/devices
44 f. echo "add vdisk1 1" >/proc/scsi_tgt/groups/Default/devices
45
46 Example 3: working with VDISK BLOCKIO mode (using md0 device, sda, and cciss/c1d0)
47 a. modprobe scst
48 b. modprobe scst_vdisk
49 c. echo "open vdisk0 /dev/md0 BLOCKIO" > /proc/scsi_tgt/vdisk/vdisk
50 d. echo "open vdisk1 /dev/sda BLOCKIO" > /proc/scsi_tgt/vdisk/vdisk
51 e. echo "open vdisk2 /dev/cciss/c1d0 BLOCKIO" > /proc/scsi_tgt/vdisk/vdisk
52 f. echo "add vdisk0 0" >/proc/scsi_tgt/groups/Default/devices
53 g. echo "add vdisk1 1" >/proc/scsi_tgt/groups/Default/devices
54 h. echo "add vdisk2 2" >/proc/scsi_tgt/groups/Default/devices
55
56 2. modprobe ib_srpt
57
58
59 B. On initiator machines you can manualy do the following steps:
60 1. modprobe ib_srp
61 2. ipsrpdm -c (to discover new SRP target)
62 3. echo <new target info> > /sys/class/infiniband_srp/srp-mthca0-1/add_target
63 4. fdisk -l (will show new discovered scsi disks)
64
65 Example:
66 Assume that you use port 1 of first HCA in the system ie. mthca0
67
68 [root@lab104 ~]# ibsrpdm -c -d /dev/infiniband/umad0
69 id_ext=0002c90200226cf4,ioc_guid=0002c90200226cf4,
70 dgid=fe800000000000000002c90200226cf5,pkey=ffff,service_id=0002c90200226cf4
71 [root@lab104 ~]# echo id_ext=0002c90200226cf4,ioc_guid=0002c90200226cf4,
72 dgid=fe800000000000000002c90200226cf5,pkey=ffff,service_id=0002c90200226cf4 >
73 /sys/class/infiniband_srp/srp-mthca0-1/add_target
74
75 OR
76
77 + You can edit /etc/infiniband/openib.conf to load srp driver and srp HA daemon
78 automatically ie. set SRP_LOAD=yes, and SRPHA_ENABLE=yes
79 + To set up and use high availability feature you need dm-multipath driver
80 and multipath tool
81 + Please refer to OFED-1.x SRP's user manual for more in-details instructions
82 on how-to enable/use HA feature
83
84 To minimize QUEUE_FULL conditions, you can apply scst_increase_max_tgt_cmds
85 patch from SRPT package from http://sourceforge.net/project/showfiles.php?group_id=110471
86
87
88 Performance notes
89 -----------------
90
91 In some cases, for instance working with SSD devices, which consume 100%
92 of a single CPU load for data transfers in their internal threads, to
93 maximize IOPS it can be needed to assign for those threads dedicated
94 CPUs using Linux CPU affinity facilities. No IRQ processing should be
95 done on those CPUs. Check that using /proc/interrupts. See taskset
96 command and Documentation/IRQ-affinity.txt in your kernel's source tree
97 for how to assign CPU affinity to tasks and IRQs.
98
99 The reason for that is that processing of coming commands in SIRQ context
100 can be done on the same CPUs as SSD devices' threads doing data
101 transfers. As the result, those threads won't receive all the CPU power
102 and perform worse.
103
104 Alternatively to CPU affinity assignment, you can try to enable SRP
105 target's internal thread. It will allows Linux CPU scheduler to better
106 distribute load among available CPUs. To enable SRP target driver's
107 internal thread you should load ib_srpt module with parameter
108 "thread=1".
109
110
111 Send questions about this driver to scst-devel@lists.sourceforge.net, CC:
112 Vu Pham <vuhuong@mellanox.com> and Bart Van Assche <bart.vanassche@gmail.com>.