- Docs updates
[mirror/scst/.git] / qla_isp / README.scst
1 WARNING
2
3 This driver is in beta stages, you may want to use it in production, but you
4 need test it for your hardware configuration.
5
6 INTRODUCTION
7
8 This is an SCST driver for ISP Qlogic chipsets commonly used in many SCSI and
9 FC host bus adapters. Supported chipsets are listed in the README file; an
10 incomplete list of supported HBAs can be found in doc/Hardware.txt .
11
12 It is based on Matthew Jacob's multiplatform driver for ISP chipsets,
13 which has its own page at http://www.feral.com/isp.html . The update for SCST
14 was made by Stanislaw Gruszka <stf_xl@wp.pl> for Open-E Inc.
15
16 Driver operates on the same hardware as qla2x00t, but has one notable
17 adventage over it: support of 24xx series of Qlogic adapters.
18
19 INSTALLATION: QUICK START
20
21 Build driver with the following command
22 $ make
23
24 Copy the firmware image appropriate for your HBA from the Qlogic FTP server
25 ftp://ftp.qlogic.com/outgoing/linux/firmware/ to one of the Linux firmware
26 loader directories (e.g. /lib/firmware, see the udev/hotplug documentation
27 for your distribution).
28
29 The next step depends on whether you have other QLA modules installed. Note
30 that you can't load an ISP driver when you build other Qlogic drivers in the
31 kernel (kerel oops may occur). Other QLA modules are acceptable, but extra
32 care is needed, first copy modules to a directory, e.g.:
33
34 $ mkdir /root/qla_isp
35 $ cp linux-2.6/build/*.ko /root/qla_isp
36
37 Each time you want to run qla_isp, unload all other qla modules
38
39 $ rmmod qla2x00tgt
40 $ rmmod qla2400
41 $ rmmod qla2300
42 $ rmmod qla2200
43 $ rmmod qla2xxx
44
45 and load ISP modules directly from the created directory, e.g.:
46
47 $ insmod /root/qla_isp/isp_scst.ko
48 $ insmod /root/qla_isp/isp_mod.ko
49
50 If you have neither other QLA drivers from SCST (qla2x00tgt) nor kernel
51 (qla2xxx and friends) you can install in the standard /lib/modules directory:
52
53 $ make install
54 $ depmod -ea
55
56 Then load the drivers manually the first time :
57
58 $ modprobe isp_scst
59 $ modprobe isp_mod
60
61 Now whenever the system is booted and a QLA card is plugged, modules will load
62 automatically.
63
64 When the driver is loaded, enable all channels for each HBA to work in target
65 mode. For Fibre Channel adapters you need to write the "enable all" string
66 into the procfs configuration file, e.g.:
67
68 $ echo "enable all" > /proc/scsi_tgt/qla_isp/3
69
70 To unload the isp_mod.ko module you must disable target mode for all cards,
71 e.g.:
72
73 $ echo "disable all" > /proc/scsi_tgt/qla_isp/3
74 $ echo "disable all" > /proc/scsi_tgt/qla_isp/4
75
76 To attach logical units continue with normal SCST setup.
77
78 SELECTING FIRMWARE
79
80 The firmware loading interface allows for choosing the appropriate firmware.
81 However, some firmware images are not available from the Qlogic site, e.g.
82 firmware with multichannel support. That is why you can build a firmware
83 image into  the isp_mod module. At the beginning of the isp_linux.h file you
84 need to comment out the following line:
85
86 #define DISABLE_FW_LOADER 1
87
88 Firmware from sources for 24xx supports multichannel (NPIV)
89
90 SUPPORTED DEVICES
91
92 You can disable support for selected chipsets by editing the isp_linux.h file.
93 In the following example, only the 2400 chipset is enabled:
94
95 #define ISP_DISABLE_1080_SUPPORT 1
96 #define ISP_DISABLE_12160_SUPPORT 1
97 #define ISP_DISABLE_2100_SUPPORT 1
98 #define ISP_DISABLE_2200_SUPPORT 1
99 #define ISP_DISABLE_2300_SUPPORT 1
100 #define ISP_DISABLE_2322_SUPPORT 1
101 //#define ISP_DISABLE_2400_SUPPORT 1
102
103 TARGET/INITIATOR ROLES
104
105 The driver can work as either a target or an initiator. Prior to performing
106 the compilation you can establish the default mode the driver will work in
107 by editing the file linux-2.6/build/Makefile - you need to set one of the
108 following values instead of ISP_ROLE_NONE
109 in -DISP_DEFAULT_ROLES=ISP_ROLE_NONE
110
111 ISP_ROLE_TARGET
112 ISP_ROLE_INITIATOR
113 ISP_ROLE_BOTH
114
115 You can also establish the driver role during module initialization using the
116 isp_roles option, e.g:
117
118 $ modprobe isp_mod isp_roles="b0300=initiator"
119
120 Number "b0300" is a DEVID value based on an address on the PCI bus, which you
121 can find in /proc/scsi/isp/N. Target role will be enabled automatically when
122 activating channels/LUNs in /proc/scsi_tgt/qla_isp/N .
123
124 The driver can also work as both a target and an initiator simultaneously, but
125 this will probably only function for P2P connections. To make the driver work
126 as a target/initator on one port with a FC switch, you can use N_PORT ID
127 virtualization, as seen below.
128
129 N_PORT ID VIRTUALIZATION
130
131 You can add an isp_vports option to the ISP module. It denotes the number of
132 ports(channels) and cannot be greater than 127. Each vport has its own WWN.
133 From the driver point of view each vport is a separate channel. You can define
134 separate role for each of the channels.
135
136 PROCFS INTERFACE
137
138 Target configuration interface is located in the following file:
139 /proc/scsi_tgt/qla_isp/N ; where N is the Linux SCSI host number and
140 is the same as for proc/scsi/isp/N and /sys/class/scsi_host/hostN files.
141
142 The process for enabling options for this file is different for FC and SPI
143 devices. For FC it is enabling/disabling channels, while SPI it is
144 enabling/disabling channels and logical units. For example:
145 FC:
146 $ echo "enable 5"  >  /proc/scsi_tgt/qla_isp/4
147
148 SPI:
149 $ echo "enable 0 1" > /proc/scsi_tgt/qla_isp/5
150
151 You may use the string "all" instead of a number e.g.:
152
153 $echo "disable all all"  > /proc/scsi_tgt/qla_isp/5
154
155 When all LUNs and channels are disabled, the target role will also become
156 inactive. For N_PORT ID virtualization, when enabling channels, you need to
157 first enable channel 0; when disabling channels, you need to disable channel
158 0 last.
159
160 Send question about this driver to scst-devel@lists.sourceforge.net, CC
161 Matthew Jacob <lydianconcepts@gmail.com> and Stanislaw Gruszka <stf_xl@wp.pl>.