602c9eb0ff4db615dd85a599d0a4df705d63ecfe
[mirror/scst/.git] / qla2x00t / qla2x00-target / qla2x00t-howto.html
1 <html>
2 <head>
3 <title>
4 How to configure QLogic target driver for 22xx/23xx/24xx/25xx adapters
5 </title>
6 <body>
7
8 <div style="text-align: center;"> <strong>How to configure QLogic target driver for 22xx/23xx/24xx/25xx adapters. Step by step guide.</strong></br></br></div>\r
9 \r
10                     <div style="text-align: center;"> <strong>ON TARGET</strong></div><br><br>\r
11 \r
12 1: Get the Linux kernel sources for version >= 2.6.26 from kernel.org</br>\r
13     <br>I've downloaded kernel version 2.6.26</br>\r
14     <br><a href="ftp://ftp.kernel.org/pub/linux/kernel/v2.6/linux-2.6.26.tar.bz2">ftp://ftp.kernel.org/pub/linux/kernel/v2.6/linux-2.6.26.tar.bz2</a></br></br></br>\r
15 \r
16 2: Get the appropiate firmware for your QLogic card from<a href="ftp://ftp.qlogic.com/outgoing/linux/firmware">\r
17    ftp://ftp.qlogic.com/outgoing/linux/firmware/</a> and put it under /lib/firmware.\r
18    It is strongly recommended to use firmware version 5.x or higher for 24xx/25xx adapters. See
19    <a href="http://sourceforge.net/mailarchive/forum.php?thread_name=4B4CD39F.6020401%40vlnb.net&forum_name=scst-devel">here</a>
20    for more details why.
21
22    </br></br>
23
24     Without a firmware image during boot or when you manually insert the QLogic module, you'll\r
25     get the following error mesage in the logs(/var/log/messages)\r
26
27     </br></br>
28
29     &lt snip &gt</br>\r
30 \r
31     qla2xxx 0000:13:00.0: Firmware image unavailable.</br>\r
32     qla2xxx 0000:13:00.0: Failed to initialize adapter</br>\r
33     &lt snip &gt</br></br>\r
34 \r
35     In this case I had to download ql2300_fw.bin</br></br></br>\r
36 \r
37 3: Unzip it under /usr/src/</br>\r
38     [root@proj src ] bunzip2 /usr/src/linux-2.6.26.tar.bz2</br>\r
39     [root@server src ] tar -xvf /usr/src/linux-2.6.26.tar</br></br></br>\r
40    \r
41 4: Create symlinks</br>\r
42     [root@proj src ] pwd</br>\r
43     /usr/src</br>\r
44     [root@proj src ] ln -s /usr/src/linux-2.6.26 linux</br>\r
45     [root@proj src ] ln -s /usr/src/linux-2.6.26 kernel</br></br></br>\r
46 \r
47 5: Get the SCST code from their SVN code base.</br>\r
48     [root@proj ] svn co https://scst.svn.sourceforge.net/svnroot/scst</br>\r
49     If the command returns successfully then you'll have 'scst'</br>\r
50     directory under your current directory ( here it is /root )</br></br>\r
51    \r
52     Please check if svn (open source version control system) is installed on\r
53     your Linux box.</br></br></br>\r
54 \r
55 6:  Change directory to ~scst/trunk/</br>\r
56     [root@proj trunk]# pwd</br>\r
57     /root/scst/trunk</br></br>\r
58 \r
59     [root@proj trunk]# ls</br>\r
60     AskingQuestions        iscsi-release.patch  mpt                       qla2x00t-release.patch  scripts    scst-full_perf.patch  usr                  www\r
61     doc                    iscsi-scst           qla2x00t                  qla_isp                 scst       scst-release.patch    usr-full_perf.patch\r
62     iscsi-full_perf.patch  Makefile             qla2x00t-full_perf.patch  README                  scstadmin  srpt                  usr-release.patch</br></br>\r
63
64 7:  Patch the kernel (the kernel version you've downloaded in step 1)</br>\r
65     [root@proj ] cp /root/scst/trunk/scst/kernel/scst_exec_req_fifo-2.6.26.patch /usr/src</br></br>\r
66    \r
67     [root@proj ] cd /usr/src</br>\r
68     [root@proj src] patch -p0 &lt scst_exec_req_fifo-2.6.26.patch</br></br></br>\r
69 \r
70 8: Replace the QLogic FC driver code in the kernel source tree with the modified version \r
71     of QLogic FC driver code from scst code base.</br></br>\r
72     [root@proj trunk] pwd</br>\r
73     /root/scst/trunk</br>\r
74     [root@proj trunk] mv /usr/src/linux/drivers/scsi/qla2xxx /usr/src/linux/drivers/scsi/qla2xxx_orig</br>\r
75     [root@proj trunk] ln -s /root/scst/trunk/qla2x00t /usr/src/linux/drivers/scsi/qla2xxx</br></br></br>\r
76    \r
77 9: Now build the kernel.</br></br>\r
78    \r
79     Make sure you disable kernel hacking feature, and enable\r
80     "Device Drivers->SCSI device support->SCSI low level drivers->Qlogic 2xxx target mode support"</br>\r
81     (i.e. CONFIG_SCSI_QLA2XXX_TARGET=y)</br>\r
82     Also turn OFF HIGHMEM4G|HIGHMEM64G,</br>\r
83     i.e.</br>\r
84     [root@proj ] grep -i highmem /usr/src/linux/.config</br>\r
85     CONFIG_NOHIGHMEM=y</br>\r
86     # CONFIG_HIGHMEM4G is not set</br>\r
87     # CONFIG_HIGHMEM64G is not set</br></br>\r
88    \r
89    If you have system with more than 1GB of memory, consider to change CONFIG_VMSPLIT option to the correspinding value.
90    </br></br>\r
91     [root@proj linux ] pwd</br>\r
92     /usr/src/linux</br>\r
93     [root@proj linux ] make menuconfig</br>\r
94     [root@proj linux ] make bzImage</br>\r
95     [root@proj linux ] make modules</br>\r
96     [root@proj linux ] make modules_install</br>\r
97     [root@proj linux ] make install</br></br></br>\r
98    \r
99 10: Reboot the machine and during boot select the modified kernel to boot from.</br></br></br>\r
100 \r
101 11:Depending on your requirement (performance/debugging) apply the appropiate\r
102     patches that comes with choose the appropriate SCST build mode. By default SCST has debug build mode.
103     Here is how to switch to the release mode:</br></br>\r
104     [root@proj trunk ] pwd</br>\r
105     /root/scst/trunk</br>\r
106     [root@proj trunk ] make debug2release</br></br></br>\r
107 \r
108 12:OPTIONAL step: do the cleanup before building scst module</br>\r
109     (Follow step 11 only if you get error "scst: disagrees about version of\r
110     symbol struct_module")</br></br>\r
111    \r
112     This error indicates that the kernel module the script was trying to\r
113     load was compiled against kernel headers that do not match the running\r
114     kernel. Doing a clean rebuild of the kernel and SCST should make the\r
115     above error go away. To make sure nothing of the old kernel is left,\r
116     Do clean rebuild of kernel and SCST :</br>\r
117     Follow the step below:</br></br>\r
118    \r
119     [root@proj linux ] pwd</br>\r
120     /usr/src/linux</br>\r
121     [root@proj linux ] make oldconfig</br>\r
122     [root@proj linux ] make clean</br>\r
123     [root@proj linux ] rm -rf /lib/modules/`uname -r`</br>\r
124     [root@proj linux ] make modules</br>\r
125     [root@proj linux ] make modules_install</br>\r
126     [root@proj linux ] make install</br>\r
127     [root@proj linux ] reboot</br></br></br>\r
128 \r
129 13:Now build the modules.</br>\r
130     But first make sure that the link "/lib/modules/`uname -r`/build"</br>\r
131     points to the current running kernel sources.</br></br>\r
132    \r
133     a) Build scst.</br>\r
134         [root@proj ] cd /root/scst/trunk/scst/src</br>\r
135         [root@proj ] make all (here I am building everything)</br>\r
136         [root@proj ] make install</br>\r
137        \r
138 \r
139     b) Build QLogic driver.</br>\r
140         [root@proj ] cd /root/scst/trunk/qla2x00t</br>\r
141         [root@proj ] make</br>\r
142         [root@proj ] make install</br></br>\r
143    \r
144     c) Build QLogic target driver</br>\r
145         [root@proj ] cd /root/scst/trunk/qla2x00t/qla2x00-target/</br>\r
146         root@proj ] make</br>\r
147         [root@proj ] make install</br></br></br>\r
148                 \r
149        \r
150 14:Insert the modules.</br>\r
151     The driver modules will be installed in '/lib/modules/`you_kernel_version`/extra'.</br>\r
152     In addition, scst.h, scst_debug.h as well as Module.symvers or\r
153     Modules.symvers will be copied to '/usr/local/include/scst'.</br> The first\r
154     file contains all SCST's public data definition, which are used by\r
155     target drivers. The other ones support debug messages logging and build process.</br></br>\r
156    \r
157     [root@proj scst]# ls -l /lib/modules/`uname -r`/extra</br>\r
158     total 232</br>\r
159     drwxr-xr-x  2 root root   4096 Jun 20 18:43 dev_handlers</br>\r
160     -rw-r--r--  1 root root  36756 Jun 20 18:46 qla2x00tgt.ko</br>\r
161     -rw-r--r--  1 root root 160192 Jun 20 18:46    qla2xxx.ko </br>  \r
162     -rw-r--r--  1 root root 190848 Jun 20 18:43 scst.ko</br></br>\r
163    \r
164     [root@proj scst]# ls -l /lib/modules/`uname -r`/extra/dev_handlers</br>\r
165     total 192</br>\r
166     -rw-r--r--  1 root root 11757 Jun 20 18:43 scst_cdrom.ko</br>\r
167     -rw-r--r--  1 root root 10111 Jun 20 18:43 scst_changer.ko</br>\r
168     -rw-r--r--  1 root root 12420 Jun 20 18:43 scst_disk.ko</br>\r
169     -rw-r--r--  1 root root 12449 Jun 20 18:43 scst_modisk.ko</br>\r
170     -rw-r--r--  1 root root 10131 Jun 20 18:43 scst_processor.ko</br>\r
171     -rw-r--r--  1 root root 10081 Jun 20 18:43 scst_raid.ko</br>\r
172     -rw-r--r--  1 root root 12563 Jun 20 18:43 scst_tape.ko</br>\r
173     -rw-r--r--  1 root root 37937 Jun 20 18:43 scst_user.ko</br>\r
174     -rw-r--r--  1 root root 50194 Jun 20 18:43 scst_vdisk.ko</br></br>\r
175    \r
176     where:</br>\r
177     - scst - SCST itself</br>\r
178      - scst_disk - device handler for disks (type 0)</br>\r
179      - scst_tape - device handler for tapes (type 1)</br>\r
180      - scst_processor - device handler for processors (type 3)</br>\r
181      - scst_cdrom - device handler for CDROMs (type 5)</br>\r
182      - scst_modisk - device handler for MO disks (type 7)</br>\r
183      - scst_changer - device handler for medium changers (type 8)</br>\r
184      - scst_raid - device handler for storage array controller (e.g. raid) (type C)</br>\r
185      - scst_vdisk - device handler for virtual disks (file, device or ISO CD image).</br>\r
186      - scst_user - user space device handler</br></br>\r
187 \r
188     You can insert any of these modules by 'modprobe' program, I've inserted all\r
189     the modules !!!</br>\r
190     [root@proj ] for _mod in scst qla2xxx qla2x00tgt scst_vdisk scst_user \r
191         scst_disk....; do modprobe $_mod; done</br></br>\r
192 \r
193     &lt snip from dmesg &gt</br></br>\r
194 \r
195     scst: SCST version 1.0.0-rc1 loaded successfully (max mem for commands 16251MB, per device 6500MB)</br>\r
196     scst: Enabled features: TRACING</br>\r
197     scst: Target template qla2x00tgt registered successfully</br>\r
198     scst: Virtual device handler vdisk for type 0 registered successfully</br>\r
199     scst: Virtual device handler "scst_user" registered successfully</br>\r
200     --------</br>\r
201     --------</br>\r
202     &lt snip from dmesg &gt</br></br></br>\r
203 \r
204 15:To see the devices remotely, we have to add them to atleast "Default" security group.</br>\r
205     Where each security group will have LUN 0(LUs numeration must not start from, e.g., 1)</br></br>\r
206 \r
207    \r
208     [root@proj ] dd if=/dev/zero of=/mnt/disk1 bs=1024k count=512</br>\r
209     512+0 records in</br>\r
210     512+0 records out</br></br>\r
211    \r
212     [root@proj ] ls -l /mnt/disk1</br>\r
213     -rw-r--r--  1 root root 536870912 Jun 23 13:27 /mnt/disk1</br></br>\r
214    \r
215     [root@proj ] file /mnt/disk1</br>\r
216     /mnt/disk1: data</br></br>\r
217 \r
218    \r
219     [root@proj ] echo "open vm_disk /mnt/disk1" > /proc/scsi_tgt/vdisk/vdisk</br>\r
220    \r
221     [root@proj ] echo "add vm_disk 0" >/proc/scsi_tgt/groups/Default/devices</br></br>\r
222 \r
223     &lt snip from dmesg &gt</br>\r
224     dev_vdisk: Attached SCSI target virtual disk vm_disk (file="/mnt/disk1", fs=512MB, bs=512, nblocks=1048576, cyln=512)</br>\r
225     scst: Attached SCSI target mid-level to virtual device vm_disk (id 1)</br>\r
226     scst: Added device vm_disk to group Default (LUN 0, rd_only 0)</br>\r
227     &lt snip from dmesg &gt</br></br>\r
228    \r
229     [root@proj ] cat /proc/scsi_tgt/groups/Default/devices</br>\r
230     Device (host:ch:id:lun or name)                             Virtual lun  Options</br>\r
231     vm_disk                                                        0           </br></br>\r
232 \r
233     [root@proj ] cat /proc/scsi_tgt/vdisk/vdisk</br>\r
234     Name              Size(MB)    Block size  Options         File name</br>\r
235     vm_disk           512         512                         /mnt/disk1</br></br></br>\r
236    \r
237    \r
238 16:After the drivers are loaded, the target mode should be enabled via a</br>\r
239 \r
240     sysfs interface on a per card basis. Under the appropriate scsi_host\r
241     there is an entry target_mode_enabled, where you should write "1", like:</br>\r
242 \r
243     [root@proj ] echo "1" >/sys/class/scsi_host/host11/target_mode_enabled</br></br>\r
244 \r
245 \r
246   <div style="text-align: center;"><strong>ON INITIATOR</strong></div></br>\r
247 \r
248 17:&lt snip from README &gt</br>\r
249     Without loading appropriate device handler, corresponding device\r
250     will be invisible for remote initiators, hence we have to\r
251     add them manully.</br> \r
252    &lt snip from README &gt</br></br>\r
253 \r
254     But as I've already loaded the device handler(scst_vdisk) on the target, \r
255     hence I don't need to perform step 17. </br></br>\r
256    \r
257 \r
258 18:After enabling the target mode on the target (see step 16),\r
259    to see new targets and devices you need either to rescan \r
260    initiator(s) manually, for example, by rmmod/modprobe the\r
261    corresponding FC device module on the initiator, or reboot the initiator itself.
262    Automatic discovery isn't supported by all known initiators,\r
263    so you need a way to make SCSI subsystem on the initiator to do the new devices discovery and hence be able to see\r
264    the new devices attached.</br></br>\r
265
266    Alternatively, if your initiator already connected to the target and you simply added new devices to it, you can try to run
267    a manual rescan by:</br>
268
269    [root@initiator ] echo "- - -" >/sys/class/scsi_host/hostX/scan</br>\r
270     where X: host number</br></br></br>\r
271  \r
272 </body>\r
273 </html>                 \r
274