Copyrights updated
[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 QUEUE_FULL 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    This patch increases SCST's per-device queue size from 48 to 64. This
39    helps to avoid QUEUE_FULL conditions because the size of the transmit
40    queue in Linux' SRP initiator is also 64.
41
42    Note: the SCSI layer of kernel 2.6.33 will have dynamic queue depth
43    adjustment. When using SRP initiator systems with kernel 2.6.33 or later,
44    this patch is less important.
45
46 2. Now compile and install SRPT:
47
48    cd ${SCST_DIR}
49    make -s scst_clean scst scst_install
50    make -s srpt_clean srpt srpt_install
51    make -s scstadm scstadm_install
52
53 3. Edit the installed file /etc/init.d/scst and add ib_srpt to the
54    SCST_MODULES variable.
55
56 4. Configure SCST such that it will be started during system boot:
57
58    chkconfig scst on
59
60 The ib_srpt kernel module supports the following parameters:
61 * srp_max_message_size (unsigned integer)
62   Maximum size of an SRP control message in bytes. Examples of SRP control
63   messages are: login request, logout request, data transfer request, ...
64   The larger this parameter, the more scatter/gather list elements can be
65   sent at once. Use the following formula to compute an appropriate value
66   for this parameter: 68 + 16 * (max_sg_elem_count). The default value of
67   this parameter is 2116, which corresponds to an sg list with 128 elements.
68 * srp_max_rdma_size (unsigned integer)
69   Maximum number of bytes that may be transferred at once via RDMA. Defaults
70   to 65536 bytes, which is sufficient to use the full bandwidth of low-latency
71   HCA's such as Mellanox' ConnectX series. Increasing this value may decrease
72   latency for applications transferring large amounts of data at once via
73   direct I/O.
74 * thread (0 or 1)
75   Whether incoming SRP requests will be processed in the IB interrupt that
76   was triggered by the request (thread=0) or on the context of a separate
77   thread (thread=1). The choice thread=0 results in the best performance,
78   while thread=1 makes debugging easier. If a kernel oops is triggered inside
79   an interrupt handler the system will be halted. As a result the call trace
80   associated with the kernel oops will not be written to the kernel log in
81   /var/log/messages. When using thread=1 however, the SRPT code runs in thread
82   context. Any kernel oops generated in thread context will cause the offending
83   thread to be killed. Other threads will keep running and call traces will be
84   written to the on-disk kernel log.
85 * trace_flag (unsigned integer, only available in debug builds)
86   The individual bits of the trace_flag parameter define which categories of
87   trace messages should be sent to the kernel log and which ones not.
88
89
90 Configuring the SRP Target System
91 ---------------------------------
92
93 First of all, create the file /etc/scst.conf. Below you can find an
94 example of how you can create this file using the scstadmin tool:
95
96   /etc/init.d/scst stop
97   /etc/init.d/scst start
98
99   scstadmin -ClearConfig /etc/scst.conf
100   scstadmin -adddev disk01 -path /dev/ram0 -handler vdisk -options NV_CACHE
101   scstadmin -adddev disk02 -path /dev/ram1 -handler vdisk -options NV_CACHE
102   scstadmin -assigndev disk01 -group Default -lun 0
103   scstadmin -assigndev disk02 -group Default -lun 1
104   scstadmin -assigndev 4:0:0:0 -group Default -lun 2
105   scstadmin -WriteConfig /etc/scst.conf
106   cat /etc/scst.conf
107
108 Now load the new configuration:
109
110   /etc/init.d/scst reload
111
112
113 Configuring the SRP Initiator System
114 ------------------------------------
115
116 First of all, load the SRP kernel module as follows:
117
118    modprobe ib_srp
119
120 Next, discover the new SRP target by running the ibsrpdm command:
121
122    ibsrpdm -c
123
124 Now let the initiator system log in to the target system:
125
126    ibsrpdm -c | while read target_info; do echo "${target_info}" > /sys/class/infiniband_srp/${SRP_HCA_NAME}/add_target; done
127
128 Finally run lsscsi to display the details of the newly discovered SCSI disks:
129
130    lsscsi
131
132 SRP targets can be recognized in the output of lsscsi by looking for
133 the disk names assigned on the SCST target ("disk01" in the example below):
134
135    [8:0:0:0]    disk    SCST_FIO disk01            102  /dev/sdb
136
137 Notes:
138 * You can edit /etc/infiniband/openib.conf to load srp driver and srp HA daemon
139   automatically ie. set SRP_LOAD=yes, and SRPHA_ENABLE=yes
140 * To set up and use high availability feature you need dm-multipath driver
141   and multipath tool
142 * Please refer to the OFED-1.x user manual for more in-detail instructions
143   on how to enable and how to use the HA feature. See e.g. http://www.mellanox.com/related-docs/prod_software/Mellanox_OFED_Linux_user_manual_1_40_1.pdf.
144
145
146 Performance Notes - Initiator Side
147 ----------------------------------
148
149 * For latency sensitive applications, using the noop scheduler at the initiator
150   side can give significantly better results than with other schedulers.
151
152 * The following parameters have a small but measureable impact on SRP
153   performance:
154   * /sys/class/block/${dev}/queue/rq_affinity
155   * /proc/irq/${ib_int_no}/smp_affinity
156
157
158 Performance Notes - Target Side
159 ----------------------------------
160
161 * In some cases, for instance working with SSD devices, which consume 100%
162   of a single CPU load for data transfers in their internal threads, to
163   maximize IOPS it can be needed to assign for those threads dedicated
164   CPUs using Linux CPU affinity facilities. No IRQ processing should be
165   done on those CPUs. Check that using /proc/interrupts. See taskset
166   command and Documentation/IRQ-affinity.txt in your kernel's source tree
167   for how to assign CPU affinity to tasks and IRQs.
168
169   The reason for that is that processing of coming commands in SIRQ context
170   can be done on the same CPUs as SSD devices' threads doing data
171   transfers. As the result, those threads won't receive all the CPU power
172   and perform worse.
173
174   Alternatively to CPU affinity assignment, you can try to enable SRP
175   target's internal thread. It will allows Linux CPU scheduler to better
176   distribute load among available CPUs. To enable SRP target driver's
177   internal thread you should load ib_srpt module with parameter
178   "thread=1".
179
180
181 Send questions about this driver to scst-devel@lists.sourceforge.net, CC:
182 Vu Pham <vuhuong@mellanox.com> and Bart Van Assche <bart.vanassche@gmail.com>.