Minor changes and docs updates
[mirror/scst/.git] / qla2x00t / qla2x00-target / README
1 Target driver for Qlogic 2200/2300 Fibre Channel cards
2 ======================================================
3
4 Version 1.0.1, X XXXX 2008
5 --------------------------
6
7 This driver has all required features and looks to be quite stable (for
8 beta) and useful. It consists from two parts: the target mode driver
9 itself and the changed initiator driver from Linux kernel, which is,
10 particularly, intended to perform all the initialization and shutdown
11 tasks. This driver was changed to provide the target mode support and
12 all necessary callbacks, but it's still capable to work as initiator
13 only. Mode, when a host acts as the initiator and the target
14 simultaneously, is supported as well.
15
16 This version is compatible with SCST core version 1.0.0 and higher and
17 Linux kernel 2.6.16 and higher.
18
19 The original initiator driver was taken from the kernel 2.6.17.8.
20
21 See also "ToDo" file for list of known issues and unimplemented 
22 features.
23
24 Installation
25 ------------
26
27 Only vanilla kernels from kernel.org are supported, but it should work
28 on vendors' kernels, if you manage to successfully compile on them. The
29 main problem with vendor's kernels is that they often contain patches,
30 which will appear only in the next version of the vanilla kernel,
31 therefore it's quite hard to track such changes. Thus, if during
32 compilation for some vendor kernel your compiler complains about
33 redefinition of some symbol, you should either switch to vanilla kernel,
34 or change as necessary the corresponding to that symbol "#if
35 LINUX_VERSION_CODE" statement.
36
37 At first, make sure that the link "/lib/modules/`you_kernel_version`/build" 
38 points to the source code for your currently running kernel.
39
40 Then you should replace (or link) by the initiator driver from this
41 package "qla2xxx" subdirectory in kernel_source/drivers/scsi/ of the
42 currently running kernel and using your favorite kernel configuration
43 tool enable in the QLogic QLA2XXX Fibre Channel driver target mode
44 support (CONFIG_SCSI_QLA2XXX_TARGET). Then rebuild the kernel and its
45 modules. During this step you will compile the initiator driver. To
46 install it, install the built kernel and its modules.
47
48 Then edit qla2x00-target/Makefile and set SCST_INC_DIR variable to point
49 to the directory, where SCST's public include files are located. If you
50 install QLA2x00 target driver's source code in the SCST's directory,
51 then SCST_INC_DIR will be set correctly for you.
52
53 Also you can set SCST_DIR variable to the directory, where SCST was
54 built, but this is optional. If you don't set it or set incorrectly,
55 during the compilation you will get a bunch of harmless warnings like
56 "WARNING: "scst_rx_data" [/XXX/qla2x00tgt.ko] undefined!"
57
58 To compile the target driver, type 'make' in qla2x00-target/
59 subdirectory. It will build qla2x00tgt.ko module.
60
61 To install the target driver, type 'make install' in qla2x00-target/
62 subdirectory. The target driver will be installed in
63 /lib/modules/`you_kernel_version`/extra. To uninstall it, type 'make
64 uninstall'.
65
66 After the drivers are loaded and adapters successfully initialized by
67 the initiator driver, including firmware image load, the target mode
68 should be enabled via a sysfs interface on a per card basis. Under the
69 appropriate scsi_host there is an entry target_mode_enabled, where you
70 should write "1", like:
71
72 echo "1" >/sys/class/scsi_host/host0/target_mode_enabled
73
74 Then you should configure exported devices using the corresponding
75 interface of SCST core. It is highly recommended to use scstadmin
76 utility for that purpose.
77
78 Compilation options
79 -------------------
80
81 There are the following compilation options, that could be commented
82 in/out in Makefile:
83
84  - DEBUG_TGT - turns on some debugging code, including some logging. Makes
85    the driver considerably bigger and slower, producing large amount of
86    log data.
87
88  - CONFIG_SCST_TRACING - turns on ability to log events. Makes the driver
89    considerably bigger and leads to some performance loss.
90
91  - DEBUG_WORK_IN_THREAD - makes SCST process incoming commands and
92    call the driver's callbacks in SCST thread context instead of tasklet
93    one. Useful for debugging and lead to some performance loss.
94    
95 Credits
96 -------
97
98 Thanks to 
99
100  * Nathaniel Clark <nate@misrule.us> for porting to new 2.6 kernel
101 initiator driver.
102
103  * Mark Buechler <mark.buechler@gmail.com> for the original
104 WWN-based authentification, a lot of useful suggestions, bug reports and
105 help in debugging.
106
107  * Ming Zhang <mingz@ele.uri.edu> for his fixes.
108
109 Vladislav Bolkhovitin <vst@vlnb.net>, http://scst.sourceforge.net