[SCSI] osd: Documentation for OSD library
[linux-2.6.git] / Documentation / scsi / tmscsim.txt
1 The tmscsim driver
2 ==================
3
4 1. Purpose and history
5 2. Installation
6 3. Features
7 4. Configuration via /proc/scsi/tmscsim/?
8 5. Configuration via boot/module params
9 6. Potential improvements
10 7. Bug reports, debugging and updates
11 8. Acknowledgements
12 9. Copyright
13
14
15 1. Purpose and history
16 ----------------------
17 The tmscsim driver supports PCI SCSI Host Adapters based on the AM53C974
18 chip. AM53C974 based SCSI adapters include: 
19  Tekram DC390, DC390T
20  Dawicontrol 2974
21  QLogic Fast! PCI Basic
22  some on-board adapters
23 (This is most probably not a complete list)
24
25 It has originally written by C.L. Huang from the Tekram corp. to support the
26 Tekram DC390(T) adapter. This is where the name comes from: tm = Tekram
27 scsi = SCSI driver, m = AMD (?) as opposed to w for the DC390W/U/F
28 (NCR53c8X5, X=2/7) driver. Yes, there was also a driver for the latter,
29 tmscsiw, which supported DC390W/U/F adapters. It's not maintained any more,
30 as the ncr53c8xx is perfectly supporting these adapters since some time.
31
32 The driver first appeared in April 1996, exclusively supported the DC390 
33 and has been enhanced since then in various steps. In May 1998 support for 
34 general AM53C974 based adapters and some possibilities to configure it were
35 added. The non-DC390 support works by assuming some values for the data
36 normally taken from the DC390 EEPROM. See below (chapter 5) for details.
37
38 When using the DC390, the configuration is still be done using the DC390
39 BIOS setup. The DC390 EEPROM is read and used by the driver, any boot or
40 module parameters (chapter 5) are ignored! However, you can change settings
41 dynamically, as described in chapter 4. 
42
43 For a more detailed description of the driver's history, see the first lines
44 of tmscsim.c.
45 The numbering scheme isn't consistent. The first versions went from 1.00 to
46 1.12, then 1.20a to 1.20t. Finally I decided to use the ncr53c8xx scheme. So
47 the next revisions will be 2.0a to 2.0X (stable), 2.1a to 2.1X (experimental),
48 2.2a to 2.2X (stable, again) etc. (X = anything between a and z.) If I send
49 fixes to people for testing, I create intermediate versions with a digit 
50 appended, e.g. 2.0c3.
51
52
53 2. Installation
54 ---------------
55 If you got any recent kernel with this driver and document included in
56 linux/drivers/scsi, you basically have to do nothing special to use this
57 driver. Of course you have to choose to compile SCSI support and DC390(T)
58 support into your kernel or as module when configuring your kernel for
59 compiling.
60 NEW: You may as well compile this module outside your kernel, using the
61 supplied Makefile.
62
63  If you got an old kernel (pre 2.1.127, pre 2.0.37p1) with an old version of
64  this driver: Get dc390-21125-20b.diff.gz or dc390-2036p21-20b1.diff.gz from
65  my web page and apply the patch. Apply further patches to upgrade to the 
66  latest version of the driver.
67
68  If you want to do it manually, you should copy the files (dc390.h,
69  tmscsim.h, tmscsim.c, scsiiom.c and README.tmscsim) from this directory to
70  linux/drivers/scsi. You have to recompile your kernel/module of course.
71
72  You should apply the three patches included in dc390-120-kernel.diff
73  (Applying them: cd /usr/src; patch -p0 <~/dc390-120-kernel.diff)
74  The patches are against 2.1.125, so you might have to manually resolve
75  rejections when applying to another kernel version.
76
77  The patches will update the kernel startup code to allow boot parameters to
78  be passed to the driver, update the Documentation and finally offer you the
79  possibility to omit the non-DC390 parts of the driver.
80  (By selecting "Omit support for non DC390" you basically disable the
81  emulation of a DC390 EEPROM for non DC390 adapters. This saves a few bytes
82  of memory.)
83
84 If you got a very old kernel without the tmscsim driver (pre 2.0.31)
85 I recommend upgrading your kernel. However, if you don't want to, please
86 contact me to get the appropriate patches.
87
88
89 Upgrading a SCSI driver is always a delicate thing to do. The 2.0 driver has
90 proven stable on many systems, but it's still a good idea to take some
91 precautions. In an ideal world you would have a full backup of your disks.
92 The world isn't ideal and most people don't have full backups (me neither).
93 So take at least the following measures:
94 * make your kernel remount the FS read-only on detecting an error:
95   tune2fs -e remount-ro /dev/sd??
96 * have copies of your SCSI disk's partition tables on some safe location:
97   dd if=/dev/sda of=/mnt/floppy/sda bs=512 count=1
98   or just print it with:
99   fdisk -l | lpr
100 * make sure you are able to boot Linux (e.g. from floppy disk using InitRD)
101   if your SCSI disk gets corrupted. You can use 
102   ftp://student.physik.uni-dortmund.de/pub/linux/kernel/bootdisk.gz
103
104 One more warning: I used to overclock my PCI bus to 41.67 MHz. My Tekram
105 DC390F (Sym53c875) accepted this as well as my Millenium. But the Am53C974
106 produced errors and started to corrupt my disks. So don't do that! A 37.50
107 MHz PCI bus works for me, though, but I don't recommend using higher clocks
108 than the 33.33 MHz being in the PCI spec.
109
110 If you want to share the IRQ with another device and the driver refuses to
111 do so, you might succeed with changing the DC390_IRQ type in tmscsim.c to 
112 IRQF_SHARED | IRQF_DISABLED.
113
114
115 3.Features
116 ----------
117 - SCSI
118  * Tagged command queueing
119  * Sync speed up to 10 MHz
120  * Disconnection
121  * Multiple LUNs
122
123 - General / Linux interface
124  * Support for up to 4 AM53C974 adapters.
125  * DC390 EEPROM usage or boot/module params
126  * Information via cat /proc/scsi/tmscsim/?
127  * Dynamically configurable by writing to /proc/scsi/tmscsim/?
128  * Dynamic allocation of resources
129  * SMP support: Locking on io_request lock (Linux 2.1/2.2) or adapter 
130     specific locks (Linux 2.5?)
131  * Uniform source code for Linux-2.x.y
132  * Support for dyn. addition/removal of devices via add/remove-single-device
133    (Try: echo "scsi add-single-device C B T U" >/proc/scsi/scsi 
134     C = Controller, B = Bus, T = Target SCSI ID, U = Unit SCSI LUN.) 
135     Use with care!
136  * Try to use the partition table for the determination of the mapping
137
138
139 4. Configuration via /proc/scsi/tmscsim/?
140 -----------------------------------------
141 First of all look at the output of /proc/scsi/tmscsim/? by typing
142  cat /proc/scsi/tmscsim/?
143 The "?" should be replaced by the SCSI host number. (The shell might do this
144 for you.)
145 You will see some info regarding the adapter and, at the end, a listing of
146 the attached devices and their settings.
147
148 Here's an example:
149 garloff@kurt:/home/garloff > cat /proc/scsi/tmscsim/0
150 Tekram DC390/AM53C974 PCI SCSI Host Adapter, Driver Version 2.0e7 2000-11-28
151 SCSI Host Nr 1, AM53C974 Adapter Nr 0
152 IOPortBase 0xb000, IRQ 10
153 MaxID 8, MaxLUN 8, AdapterID 6, SelTimeout 250 ms, DelayReset 1 s
154 TagMaxNum 16, Status 0x00, ACBFlag 0x00, GlitchEater 24 ns
155 Statistics: Cmnds 1470165, Cmnds not sent directly 0, Out of SRB conds 0
156             Lost arbitrations 587,  Sel. connected 0, Connected: No
157 Nr of attached devices: 4, Nr of DCBs: 4
158 Map of attached LUNs: 01 00 00 03 01 00 00 00
159 Idx ID LUN Prty Sync DsCn SndS TagQ NegoPeriod SyncSpeed SyncOffs MaxCmd
160 00  00  00  Yes  Yes  Yes  Yes  Yes   100 ns    10.0 M      15      16
161 01  03  00  Yes  Yes  Yes  Yes  No    100 ns    10.0 M      15      01
162 02  03  01  Yes  Yes  Yes  Yes  No    100 ns    10.0 M      15      01
163 03  04  00  Yes  Yes  Yes  Yes  No    100 ns    10.0 M      15      01
164
165 Note that the settings MaxID and MaxLUN are not zero- but one-based, which
166 means that a setting MaxLUN=4, will result in the support of LUNs 0..3. This
167 is somehow inconvenient, but the way the mid-level SCSI code expects it to be.
168
169 ACB and DCB are acronyms for Adapter Control Block and Device Control Block.
170 These are data structures of the driver containing information about the
171 adapter and the connected SCSI devices respectively.
172
173 Idx is the device index (just a consecutive number for the driver), ID and
174 LUN are the SCSI ID and LUN, Prty means Parity checking, Sync synchronous
175 negotiation, DsCn Disconnection, SndS Send Start command on startup (not
176 used by the driver) and TagQ Tagged Command Queueing. NegoPeriod and
177 SyncSpeed are somehow redundant, because they are reciprocal values 
178 (1 / 112 ns = 8.9 MHz). At least in theory. The driver is able to adjust the
179 NegoPeriod more accurate (4ns) than the SyncSpeed (1 / 25ns). I don't know
180 if certain devices will have problems with this discrepancy. Max. speed is
181 10 MHz corresp. to a min. NegoPeriod of 100 ns. 
182 (The driver allows slightly higher speeds if the devices (Ultra SCSI) accept
183 it, but that's out of adapter spec, on your own risk and unlikely to improve
184 performance. You're likely to crash your disks.) 
185 SyncOffs is the offset used for synchronous negotiations; max. is 15. 
186 The last values are only shown, if Sync is enabled. (NegoPeriod is still
187 displayed in brackets to show the values which will be used after enabling
188 Sync.)
189 MaxCmd ist the number of commands (=tags) which can be processed at the same
190 time by the device.
191
192 If you want to change a setting, you can do that by writing to
193 /proc/scsi/tmscsim/?. Basically you have to imitate the output of driver.
194 (Don't use the brackets for NegoPeriod on Sync disabled devices.)
195 You don't have to care about capitalisation. The driver will accept space,
196 tab, comma, = and : as separators.
197
198 There are three kinds of changes: 
199
200 (1) Change driver settings: 
201     You type the names of the parameters and the params following it.
202     Example:
203      echo "MaxLUN=8 seltimeout 200" >/proc/scsi/tmscsim/0
204
205     Note that you can only change MaxID, MaxLUN, AdapterID, SelTimeOut,
206     TagMaxNum, ACBFlag, GlitchEater and DelayReset. Don't change ACBFlag
207     unless you want to see what happens, if the driver hangs.
208
209 (2) Change device settings: You write a config line to the driver. The Nr
210     must match the ID and LUN given. If you give "-" as parameter, it is
211     ignored and the corresponding setting won't be changed. 
212     You can use "y" or "n" instead of "Yes" and "No" if you want to.
213     You don't need to specify a full line. The driver automatically performs
214     an INQUIRY on the device if necessary to check if it is capable to operate
215     with the given settings (Sync, TagQ).
216     Examples:
217      echo "0 0 0 y y y - y - 10 " >/proc/scsi/tmscsim/0
218      echo "3 5 0 y n y " >/proc/scsi/tmscsim/0
219
220     To give a short explanation of the first example: 
221     The first three numbers, "0 0 0" (Device index 0, SCSI ID 0, SCSI LUN 0),
222     select the device to which the following parameters apply. Note that it
223     would be sufficient to use the index or both SCSI ID and LUN, but I chose
224     to require all three to have a syntax similar to the output.
225     The following "y y y - y" enables Parity checking, enables Synchronous
226     transfers, Disconnection, leaves Send Start (not used) untouched and
227     enables Tagged Command Queueing for the selected device. The "-" skips
228     the Negotiation Period setting but the "10" sets the max sync. speed to
229     10 MHz. It's useless to specify both NegoPeriod and SyncSpeed as
230     discussed above. The values used in this example will result in maximum
231     performance.
232
233 (3) Special commands: You can force a SCSI bus reset, an INQUIRY command, the
234     removal or the addition of a device's DCB and a SCSI register dump.
235     This is only used for debugging when you meet problems. The parameter of
236     the INQUIRY and REMOVE commands is the device index as shown by the
237     output of /proc/scsi/tmscsim/? in the device listing in the first column
238     (Idx). ADD takes the SCSI ID and LUN.
239     Examples:
240      echo "reset" >/proc/scsi/tmscsim/0
241      echo "inquiry 1" >/proc/scsi/tmscsim/0
242      echo "remove 2" >/proc/scsi/tmscsim/1
243      echo "add 2 3" >/proc/scsi/tmscsim/?
244      echo "dump" >/proc/scsi/tmscsim/0
245
246     Note that you will meet problems when you REMOVE a device's DCB with the
247     remove command if it contains partitions which are mounted. Only use it
248     after unmounting its partitions, telling the SCSI mid-level code to
249     remove it (scsi remove-single-device) and you really need a few bytes of
250     memory.
251     The ADD command allows you to configure a device before you tell the
252     mid-level code to try detection.
253
254
255 I'd suggest reviewing the output of /proc/scsi/tmscsim/? after changing
256 settings to see if everything changed as requested.
257
258
259 5. Configuration via boot/module parameters
260 -------------------------------------------
261 With the DC390, the driver reads its EEPROM settings and tries to use them.
262 But you may want to override the settings prior to being able to change the
263 driver configuration via /proc/scsi/tmscsim/?.
264 If you do have another AM53C974 based adapter, that's even the only
265 possibility to adjust settings before you are able to write to the
266 /proc/scsi/tmscsim/? pseudo-file, e.g. if you want to use another 
267 adapter ID than 7.  
268 (BTW, the log message "DC390: No EEPROM found!" is normal without a DC390.)
269 For this purpose, you can pass options to the driver before it is initialised
270 by using kernel or module parameters. See lilo(8) or modprobe(1) manual
271 pages on how to pass params to the kernel or a module.
272 [NOTE: Formerly, it was not possible to override the EEPROM supplied
273  settings of the DC390 with cmd line parameters. This has changed since
274  2.0e7]
275
276 The syntax of the params is much shorter than the syntax of the /proc/...
277 interface. This makes it a little bit more difficult to use. However, long
278 parameter lines have the risk to be misinterpreted and the length of kernel
279 parameters is limited.
280
281 As the support for non-DC390 adapters works by simulating the values of the
282 DC390 EEPROM, the settings are given in a DC390 BIOS' way.
283
284 Here's the syntax:
285 tmscsim=AdaptID,SpdIdx,DevMode,AdaptMode,TaggedCmnds,DelayReset
286
287 Each of the parameters is a number, containing the described information:
288
289 * AdaptID: The SCSI ID of the host adapter. Must be in the range 0..7
290   Default is 7.
291
292 * SpdIdx: The index of the maximum speed as in the DC390 BIOS. The values
293   0..7 mean 10, 8.0, 6.7, 5.7, 5.0, 4.0, 3.1 and 2 MHz resp. Default is
294   0 (10.0 MHz).
295
296 * DevMode is a bit mapped value describing the per-device features. It
297   applies to all devices. (Sync, Disc and TagQ will only apply, if the
298   device supports it.) The meaning of the bits (* = default):
299
300    Bit Val(hex) Val(dec)  Meaning
301    *0    0x01       1     Parity check
302    *1    0x02       2     Synchronous Negotiation
303    *2    0x04       4     Disconnection
304    *3    0x08       8     Send Start command on startup. (Not used)
305    *4    0x10      16     Tagged Command Queueing
306
307   As usual, the desired value is obtained by adding the wanted values. If
308   you want to enable all values, e.g., you would use 31(0x1f). Default is 31.
309
310 * AdaptMode is a bit mapped value describing the enabled adapter features.
311
312    Bit Val(hex) Val(dec)  Meaning
313    *0    0x01       1     Support more than two drives. (Not used)
314    *1    0x02       2     Use DOS compatible mapping for HDs greater than 1GB.
315    *2    0x04       4     Reset SCSI Bus on startup.
316    *3    0x08       8     Active Negation: Improves SCSI Bus noise immunity.
317     4    0x10      16     Immediate return on BIOS seek command. (Not used)
318  (*)5    0x20      32     Check for LUNs >= 1.
319   
320   The default for LUN Check depends on CONFIG_SCSI_MULTI_LUN.
321
322 * TaggedCmnds is a number indicating the maximum number of Tagged Commands.
323   It is the binary logarithm - 1 of the actual number. Max is 4 (32).
324    Value  Number of Tagged Commands
325      0           2
326      1           4
327      2           8
328     *3          16
329      4          32
330
331 * DelayReset is the time in seconds (minus 0.5s), the adapter waits, after a
332   bus reset. Default is 1 (corresp. to 1.5s).
333
334 Example:
335  modprobe tmscsim tmscsim=6,2,31
336 would set the adapter ID to 6, max. speed to 6.7 MHz, enable all device
337 features and leave the adapter features, the number of Tagged Commands
338 and the Delay after a reset to the defaults.
339
340 As you can see, you don't need to specify all of the six params.
341 If you want values to be ignored (i.e. the EEprom settings or the defaults
342 will be used), you may pass -2 (not 0!) at the corresponding position.
343
344 The defaults (7,0,31,15,3,1) are aggressive to allow good performance. You
345 can use tmscsim=7,0,31,63,4,0 for maximum performance, if your SCSI chain
346 allows it. If you meet problems, you can use tmscsim=-1 which is a shortcut
347 for tmscsim=7,4,9,15,2,10.
348
349
350 6. Potential improvements
351 -------------------------
352 Most of the intended work on the driver has been done. Here are a few ideas
353 to further improve its usability:
354
355 * Cleanly separate per-Target and per-LUN properties (DCB)
356 * More intelligent abort() routine
357 * Use new_eh code (Linux-2.1+)
358 * Have the mid-level (ML) code (and not the driver) handle more of the
359   various conditions.
360 * Command queueing in the driver: Eliminate Query list and use ML instead.
361 * More user friendly boot/module param syntax
362
363 Further investigation on these problems:
364
365 * Driver hangs with sync readcdda (xcdroast) (most probably VIA PCI error)
366
367 Known problems: 
368 Please see http://www.garloff.de/kurt/linux/dc390/problems.html
369
370 * Changing the parameters of multi-lun by the tmscsim/? interface will
371   cause problems, cause these settings are mostly per Target and not per LUN
372   and should be updated accordingly. To be fixed for 2.0d24.
373 * CDRs (eg Yam CRW4416) not recognized, because some buggy devices don't 
374   recover from a SCSI reset in time. Use a higher delay or don't issue
375   a SCSI bus reset on driver initialization. See problems page.
376   For the CRW4416S, this seems to be solved with firmware 1.0g (reported by 
377   Jean-Yves Barbier).
378 * TEAC CD-532S not being recognized. (Works with 1.11).
379 * Scanners (eg. Astra UMAX 1220S) don't work: Disable Sync Negotiation.
380   If this does not help, try echo "INQUIRY t" >/proc/scsi/tmscsim/? (t
381   replaced by the dev index of your scanner). You may try to reset your SCSI
382   bus afterwards (echo "RESET" >/proc/scsi/tmscsim/?).
383   The problem seems to be solved as of 2.0d18, thanks to Andreas Rick.
384 * If there is a valid partition table, the driver will use it for determining
385   the mapping. If there's none, a reasonable mapping (Symbios-like) will be
386   assumed. Other operating systems may not like this mapping, though
387   it's consistent with the BIOS' behaviour. Old DC390 drivers ignored the
388   partition table and used a H/S = 64/32 or 255/63 translation. So if you
389   want to be compatible to those, use this old mapping when creating
390   partition tables. Even worse, on bootup the DC390 might complain if other
391   mappings are found, so auto rebooting may fail.
392 * In some situations, the driver will get stuck in an abort loop. This is a
393   bad interaction between the Mid-Layer of Linux' SCSI code and the driver.
394   Try to disable DsCn, if you meet this problem. Please contact me for
395   further debugging.
396
397
398 7. Bug reports, debugging and updates
399 -------------------------------------
400 Whenever you have problems with the driver, you are invited to ask the
401 author for help. However, I'd suggest reading the docs and trying to solve
402 the problem yourself, first. 
403 If you find something, which you believe to be a bug, please report it to me. 
404 Please append the output of /proc/scsi/scsi, /proc/scsi/tmscsim/? and
405 maybe the DC390 log messages to the report. 
406
407 Bug reports should be send to me (Kurt Garloff <dc390@garloff.de>) as well
408 as to the linux-scsi list (<linux-scsi@vger.kernel.org>), as sometimes bugs
409 are caused by the SCSI mid-level code.
410
411 I will ask you for some more details and probably I will also ask you to
412 enable some of the DEBUG options in the driver (tmscsim.c:DC390_DEBUGXXX
413 defines). The driver will produce some data for the syslog facility then.
414 Beware: If your syslog gets written to a SCSI disk connected to your
415 AM53C974, the logging might produce log output again, and you might end
416 having your box spending most of its time doing the logging.
417
418 The latest version of the driver can be found at:
419  http://www.garloff.de/kurt/linux/dc390/
420  ftp://ftp.suse.com/pub/people/garloff/linux/dc390/
421
422
423 8. Acknowledgements
424 -------------------
425 Thanks to Linus Torvalds, Alan Cox, the FSF people, the XFree86 team and 
426 all the others for the wonderful OS and software.
427 Thanks to C.L. Huang and Philip Giang (Tekram) for the initial driver
428 release and support.
429 Thanks to Doug Ledford, GĂ©rard Roudier for support with SCSI coding.
430 Thanks to a lot of people (espec. Chiaki Ishikawa, Andreas Haumer, Hubert 
431 Tonneau) for intensively testing the driver (and even risking data loss
432 doing this during early revisions).
433 Recently, SuSE GmbH, Nuernberg, FRG, has been paying me for the driver
434 development and maintenance. Special thanks!
435
436
437 9. Copyright
438 ------------
439  This driver is free software; you can redistribute it and/or modify
440  it under the terms of the GNU General Public License as published by   
441  the Free Software Foundation; version 2 of the License.
442  If you want to use any later version of the GNU GPL, you will probably
443  be allowed to, but you have to ask me and Tekram <erich@tekram.com.tw>
444  before.
445
446 -------------------------------------------------------------------------
447 Written by Kurt Garloff <kurt@garloff.de> 1998/06/11
448 Last updated 2000/11/28, driver revision 2.0e7
449 $Id: README.tmscsim,v 2.25.2.7 2000/12/20 01:07:12 garloff Exp $