- Fixed race conditions related to channel state manipulation.
[mirror/scst/.git] / srpt / README
1 SCSI RDMA Protocol (SRP) Target driver for Linux
2 =================================================
3
4 The SRP target driver has been designed to work on top of the Linux
5 InfiniBand kernel drivers -- either the InfiniBand drivers included
6 with a Linux distribution of the OFED InfiniBand drivers. For more
7 information about using the SRP target driver in combination with
8 OFED, see also README.ofed.
9
10 The SRP target driver has been implemented as an SCST driver. This
11 makes it possible to support a lot of I/O modes on real and virtual
12 devices. A few examples of supported device handlers are:
13
14 1. scst_disk. This device handler implements transparent pass-through
15    of SCSI commands and allows SRP to access and to export real
16    SCSI devices, i.e. disks, hardware RAID volumes, tape libraries
17    as SRP LUNs.
18
19 2. scst_vdisk, either in fileio or in blockio mode. This device handler
20    allows to export software RAID volumes, LVM volumes, IDE disks, and
21    normal files as SRP LUNs.
22
23 3. nullio. The nullio device handler allows to measure the performance
24    of the SRP target implementation without performing any actual I/O.
25
26
27 Installation
28 ------------
29
30 Proceed as follows to compile and install the SRP target driver:
31
32 1. To minimize QUEUEFULL conditions, apply the
33    scst_increase_max_tgt_cmds patch as follows:
34
35    cd ${SCST_DIR}
36    patch -p0 < srpt/patches/scst_increase_max_tgt_cmds.patch
37
38 2. Now compile and install SRPT:
39
40    cd ${SCST_DIR}
41    make -s scst_clean scst scst_install
42    make -s srpt_clean srpt srpt_install
43    make -s scstadm scstadm_install
44
45 3. Edit the installed file /etc/init.d/scst and add ib_srpt to the
46    SCST_MODULES variable.
47
48 4. Configure SCST such that it will be started during system boot:
49
50    chkconfig scst on
51
52
53 Configuring the SRP Target System
54 ---------------------------------
55
56 First of all, create the file /etc/scst.conf. Below you can find an
57 example of how you can create this file using the scstadmin tool:
58
59   /etc/init.d/scst stop
60   /etc/init.d/scst start
61
62   scstadmin -ClearConfig /etc/scst.conf
63   scstadmin -adddev disk01 -path /dev/ram0 -handler vdisk -options NV_CACHE
64   scstadmin -adddev disk02 -path /dev/ram1 -handler vdisk -options NV_CACHE
65   scstadmin -assigndev disk01 -group Default -lun 0
66   scstadmin -assigndev disk02 -group Default -lun 1
67   scstadmin -assigndev 4:0:0:0 -group Default -lun 2
68   scstadmin -WriteConfig /etc/scst.conf
69   cat /etc/scst.conf
70
71 Now load the new configuration:
72
73   /etc/init.d/scst reload
74
75 Note: SCSI device ID's in host:ch:id:lun format can be obtained by
76 running the lsscsi command.
77
78
79 Configuring the SRP Initiator System
80 ------------------------------------
81
82 First of all, load the SRP kernel module as follows:
83
84   modprobe ib_srp
85
86 Next, discover the new SRP target by running the ipsrpdm command:
87
88    ipsrpdm -c
89
90 Now let the initiator system log in to the target system:
91
92    ibsrpdm -c | while read target_info; do echo "${target_info}" > /sys/class/infiniband_srp/${SRP_HCA_NAME}/add_target; done
93
94 Finally run lsscsi to display the details of the newly discovered SCSI disks:
95
96    lsscsi
97
98 SRP targets can be recognized in the output of lsscsi by looking for
99 the disk names assigned on the SCST target ("disk01" in the example below):
100
101 [8:0:0:0]    disk    SCST_FIO disk01            102  /dev/sdb
102
103 Notes:
104 * You can edit /etc/infiniband/openib.conf to load srp driver and srp HA daemon
105   automatically ie. set SRP_LOAD=yes, and SRPHA_ENABLE=yes
106 * To set up and use high availability feature you need dm-multipath driver
107   and multipath tool
108 * Please refer to OFED-1.x SRP's user manual for more in-details instructions
109   on how-to enable/use HA feature.
110
111
112 Performance notes
113 -----------------
114
115 * For latency sensitive applications, using the noop scheduler at the initiator
116   side can give significantly better resuts than with other schedulers.
117
118 * In some cases, for instance working with SSD devices, which consume 100%
119   of a single CPU load for data transfers in their internal threads, to
120   maximize IOPS it can be needed to assign for those threads dedicated
121   CPUs using Linux CPU affinity facilities. No IRQ processing should be
122   done on those CPUs. Check that using /proc/interrupts. See taskset
123   command and Documentation/IRQ-affinity.txt in your kernel's source tree
124   for how to assign CPU affinity to tasks and IRQs.
125
126   The reason for that is that processing of coming commands in SIRQ context
127   can be done on the same CPUs as SSD devices' threads doing data
128   transfers. As the result, those threads won't receive all the CPU power
129   and perform worse.
130
131   Alternatively to CPU affinity assignment, you can try to enable SRP
132   target's internal thread. It will allows Linux CPU scheduler to better
133   distribute load among available CPUs. To enable SRP target driver's
134   internal thread you should load ib_srpt module with parameter
135   "thread=1".
136
137
138 Send questions about this driver to scst-devel@lists.sourceforge.net, CC:
139 Vu Pham <vuhuong@mellanox.com> and Bart Van Assche <bart.vanassche@gmail.com>.