Merge branch 'next' of git://git.kernel.org/pub/scm/linux/kernel/git/benh/powerpc
[pandora-kernel.git] / Documentation / scsi / aic7xxx_old.txt
1                             AIC7xxx Driver for Linux
2
3 Introduction
4 ----------------------------
5 The AIC7xxx SCSI driver adds support for Adaptec (http://www.adaptec.com)
6 SCSI controllers and chipsets. Major portions of the driver and driver
7 development are shared between both Linux and FreeBSD. Support for the
8 AIC-7xxx chipsets have been in the default Linux kernel since approximately
9 linux-1.1.x and fairly stable since linux-1.2.x, and are also in FreeBSD
10 2.1.0 or later.
11
12   Supported cards/chipsets
13   ----------------------------
14     Adaptec Cards
15     ----------------------------
16     AHA-274x
17     AHA-274xT               
18     AHA-2842
19     AHA-2910B               
20     AHA-2920C
21     AHA-2930
22     AHA-2930U
23     AHA-2930CU
24     AHA-2930U2
25     AHA-2940               
26     AHA-2940W              
27     AHA-2940U              
28     AHA-2940UW
29     AHA-2940UW-PRO
30     AHA-2940AU 
31     AHA-2940U2W
32     AHA-2940U2
33     AHA-2940U2B
34     AHA-2940U2BOEM
35     AHA-2944D              
36     AHA-2944WD
37     AHA-2944UD
38     AHA-2944UWD
39     AHA-2950U2
40     AHA-2950U2W
41     AHA-2950U2B
42     AHA-29160M
43     AHA-3940
44     AHA-3940U
45     AHA-3940W
46     AHA-3940UW
47     AHA-3940AUW
48     AHA-3940U2W
49     AHA-3950U2B
50     AHA-3950U2D
51     AHA-3960D
52     AHA-39160M
53     AHA-3985
54     AHA-3985U
55     AHA-3985W
56     AHA-3985UW
57
58     Motherboard Chipsets
59     ----------------------------
60     AIC-777x   
61     AIC-785x
62     AIC-786x
63     AIC-787x
64     AIC-788x
65     AIC-789x
66     AIC-3860
67
68     Bus Types
69     ----------------------------
70     W - Wide SCSI, SCSI-3, 16bit bus, 68pin connector, will also support
71         SCSI-1/SCSI-2 50pin devices, transfer rates up to 20MB/s.
72     U - Ultra SCSI, transfer rates up to 40MB/s.
73     U2- Ultra 2 SCSI, transfer rates up to 80MB/s.
74     D - Differential SCSI.
75     T - Twin Channel SCSI. Up to 14 SCSI devices.
76
77     AHA-274x - EISA SCSI controller
78     AHA-284x - VLB SCSI controller
79     AHA-29xx - PCI SCSI controller
80     AHA-394x - PCI controllers with two separate SCSI controllers on-board.
81     AHA-398x - PCI RAID controllers with three separate SCSI controllers
82                on-board.
83
84   Not Supported Devices
85   ------------------------------
86     Adaptec Cards
87     ----------------------------
88     AHA-2920 (Only the cards that use the Future Domain chipset are not
89               supported, any 2920 cards based on Adaptec AIC chipsets,
90               such as the 2920C, are supported)
91     AAA-13x Raid Adapters
92     AAA-113x Raid Port Card
93
94     Motherboard Chipsets
95     ----------------------------
96     AIC-7810
97
98     Bus Types
99     ----------------------------
100     R - Raid Port busses are not supported.
101
102     The hardware RAID devices sold by Adaptec are *NOT* supported by this
103     driver (and will people please stop emailing me about them, they are
104     a totally separate beast from the bare SCSI controllers and this driver
105     cannot be retrofitted in any sane manner to support the hardware RAID
106     features on those cards - Doug Ledford).
107     
108
109   People
110   ------------------------------
111     Justin T Gibbs  gibbs@plutotech.com
112       (BSD Driver Author)
113     Dan Eischen     deischen@iworks.InterWorks.org
114       (Original Linux Driver Co-maintainer)
115     Dean Gehnert    deang@teleport.com
116       (Original Linux FTP/patch maintainer)
117     Jess Johnson    jester@frenzy.com
118       (AIC7xxx FAQ author)
119     Doug Ledford    dledford@redhat.com
120       (Current Linux aic7xxx-5.x.x Driver/Patch/FTP maintainer)
121     
122     Special thanks go to John Aycock (aycock@cpsc.ucalgary.ca), the original
123     author of the driver. John has since retired from the project. Thanks
124     again for all his work!
125     
126   Mailing list
127   ------------------------------
128     There is a mailing list available for users who want to track development
129     and converse with other users and developers. This list is for both
130     FreeBSD and Linux support of the AIC7xxx chipsets.
131
132     To subscribe to the AIC7xxx mailing list send mail to the list server,
133     with "subscribe AIC7xxx" in the body (no Subject: required):
134         To: majordomo@FreeBSD.ORG
135         ---
136         subscribe AIC7xxx
137
138     To unsubscribe from the list, send mail to the list server with:
139         To: majordomo@FreeBSD.ORG
140         ---
141         unsubscribe AIC7xxx
142
143     Send regular messages and replies to: AIC7xxx@FreeBSD.ORG
144     
145   Boot Command line options
146   ------------------------------
147     "aic7xxx=no_reset" -  Eliminate the SCSI bus reset during startup.
148         Some SCSI devices need the initial reset that this option disables
149         in order to work.  If you have problems at bootup, please make sure
150         you aren't using this option.
151         
152     "aic7xxx=reverse_scan" - Certain PCI motherboards scan for devices at
153         bootup by scanning from the highest numbered PCI device to the
154         lowest numbered PCI device, others do just the opposite and scan
155         from lowest to highest numbered PCI device.  There is no reliable
156         way to autodetect this ordering.  So, we default to the most common
157         order, which is lowest to highest.  Then, in case your motherboard
158         scans from highest to lowest, we have this option.  If your BIOS
159         finds the drives on controller A before controller B but the linux
160         kernel finds your drives on controller B before A, then you should
161         use this option.
162         
163     "aic7xxx=extended" - Force the driver to detect extended drive translation
164         on your controller.  This helps those people who have cards without
165         a SEEPROM make sure that linux and all other operating systems think
166         the same way about your hard drives.
167
168     "aic7xxx=scbram" - Some cards have external SCB RAM that can be used to
169         give the card more hardware SCB slots.  This allows the driver to use
170         that SCB RAM.  Without this option, the driver won't touch the SCB
171         RAM because it is known to cause problems on a few cards out there
172         (such as 3985 class cards).
173         
174     "aic7xxx=irq_trigger:x" - Replace x with either 0 or 1 to force the kernel
175         to use the correct IRQ type for your card.  This only applies to EISA
176         based controllers.  On these controllers, 0 is for Edge triggered
177         interrupts, and 1 is for Level triggered interrupts.  If you aren't
178         sure or don't know which IRQ trigger type your EISA card uses, then
179         let the kernel autodetect the trigger type.
180         
181     "aic7xxx=verbose" - This option can be used in one of two ways.  If you
182         simply specify aic7xxx=verbose, then the kernel will automatically
183         pick the default set of verbose messages for you to see.
184         Alternatively, you can specify the command as 
185         "aic7xxx=verbose:0xXXXX" where the X entries are replaced with
186         hexadecimal digits.  This option is a bit field type option.  For
187         a full listing of the available options, search for the 
188         #define VERBOSE_xxxxxx lines in the aic7xxx.c file.  If you want
189         verbose messages, then it is recommended that you simply use the
190         aic7xxx=verbose variant of this command.
191         
192     "aic7xxx=pci_parity:x" - This option controls whether or not the driver
193         enables PCI parity error checking on the PCI bus.  By default, this
194         checking is disabled.  To enable the checks, simply specify pci_parity
195         with no value afterwords.  To reverse the parity from even to odd,
196         supply any number other than 0 or 255.  In short:
197           pci_parity     - Even parity checking (even is the normal PCI parity)
198           pci_parity:x   - Where x > 0, Odd parity checking
199           pci_parity:0   - No check (default)
200         NOTE: In order to get Even PCI parity checking, you must use the
201         version of the option that does not include the : and a number at
202         the end (unless you want to enter exactly 2^32 - 1 as the number).
203         
204     "aic7xxx=no_probe" - This option will disable the probing for any VLB
205         based 2842 controllers and any EISA based controllers.  This is
206         needed on certain newer motherboards where the normal EISA I/O ranges
207         have been claimed by other PCI devices.  Probing on those machines
208         will often result in the machine crashing or spontaneously rebooting
209         during startup.  Examples of machines that need this are the
210         Dell PowerEdge 6300 machines.
211
212     "aic7xxx=seltime:2" - This option controls how long the card waits
213         during a device selection sequence for the device to respond.
214         The original SCSI spec says that this "should be" 256ms.  This
215         is generally not required with modern devices.  However, some
216         very old SCSI I devices need the full 256ms.  Most modern devices
217         can run fine with only 64ms.  The default for this option is
218         64ms.  If you need to change this option, then use the following
219         table to set the proper value in the example above:
220           0  -  256ms
221           1  -  128ms
222           2  -   64ms
223           3  -   32ms
224         
225     "aic7xxx=panic_on_abort" - This option is for debugging and will cause
226         the driver to panic the linux kernel and freeze the system the first
227         time the drivers abort or reset routines are called.  This is most
228         helpful when some problem causes infinite reset loops that scroll too
229         fast to see.  By using this option, you can write down what the errors
230         actually are and send that information to me so it can be fixed.
231         
232     "aic7xxx=dump_card" - This option will print out the *entire* set of
233         configuration registers on the card during the init sequence.  This
234         is a debugging aid used to see exactly what state the card is in
235         when we finally finish our initialization routines.  If you don't
236         have documentation on the chipsets, this will do you absolutely
237         no good unless you are simply trying to write all the information
238         down in order to send it to me.
239         
240     "aic7xxx=dump_sequencer" - This is the same as the above options except
241         that instead of dumping the register contents on the card, this
242         option dumps the contents of the sequencer program RAM.  This gives
243         the ability to verify that the instructions downloaded to the
244         card's sequencer are indeed what they are supposed to be.  Again,
245         unless you have documentation to tell you how to interpret these
246         numbers, then it is totally useless.
247         
248     "aic7xxx=override_term:0xffffffff" - This option is used to force the
249         termination on your SCSI controllers to a particular setting.  This
250         is a bit mask variable that applies for up to 8 aic7xxx SCSI channels.
251         Each channel gets 4 bits, divided as follows:
252         bit   3   2   1   0
253               |   |   |   Enable/Disable Single Ended Low Byte Termination
254               |   |   En/Disable Single Ended High Byte Termination
255               |   En/Disable Low Byte LVD Termination
256               En/Disable High Byte LVD Termination
257
258         The upper 2 bits that deal with LVD termination only apply to Ultra2
259         controllers.  Furthermore, due to the current Ultra2 controller
260         designs, these bits are tied together such that setting either bit
261         enables both low and high byte LVD termination.  It is not possible
262         to only set high or low byte LVD termination in this manner.  This is
263         an artifact of the BIOS definition on Ultra2 controllers.  For other
264         controllers, the only important bits are the two lowest bits.  Setting
265         the higher bits on non-Ultra2 controllers has no effect.  A few
266         examples of how to use this option:
267
268         Enable low and high byte termination on a non-ultra2 controller that
269         is the first aic7xxx controller (the correct bits are 0011), 
270         aic7xxx=override_term:0x3
271
272         Enable all termination on the third aic7xxx controller, high byte
273         termination on the second aic7xxx controller, and low and high byte
274         SE termination on the first aic7xxx controller 
275         (bits are 1111 0010 0011), 
276         aic7xxx=override_term:0xf23
277         
278         No attempt has been made to make this option non-cryptic.  It really
279         shouldn't be used except in dire circumstances, and if that happens,
280         I'm probably going to be telling you what to set this to anyway :)
281
282     "aic7xxx=stpwlev:0xffffffff" - This option is used to control the STPWLEV
283         bit in the DEVCONFIG PCI register.  Currently, this is one of the
284         very few registers that we have absolutely *no* way of detecting
285         what the variable should be.  It depends entirely on how the chipset
286         and external terminators were coupled by the card/motherboard maker.
287         Further, a chip reset (at power up) always sets this bit to 0.  If
288         there is no BIOS to run on the chipset/card (such as with a 2910C
289         or a motherboard controller with the BIOS totally disabled) then
290         the variable may not get set properly.  Of course, if the proper
291         setting was 0, then that's what it would be after the reset, but if
292         the proper setting is actually 1.....you get the picture.  Now, since
293         we can't detect this at all, I've added this option to force the
294         setting.  If you have a BIOS on your controller then you should never
295         need to use this option.  However, if you are having lots of SCSI
296         reset problems and can't seem to get them knocked out, this may help.
297
298         Here's a test to know for certain if you need this option.  Make
299         a boot floppy that you can use to boot your computer up and that
300         will detect the aic7xxx controller.  Next, power down your computer.
301         While it's down, unplug all SCSI cables from your Adaptec SCSI
302         controller.  Boot the system back up to the Adaptec EZ-SCSI BIOS
303         and then make sure that termination is enabled on your adapter (if
304         you have an Adaptec BIOS of course).  Next, boot up the floppy you
305         made and wait for it to detect the aic7xxx controller.  If the kernel
306         finds the controller fine, says scsi : x hosts and then tries to
307         detect your devices like normal, up to the point where it fails to
308         mount your root file system and panics, then you're fine.  If, on
309         the other hand, the system goes into an infinite reset loop, then
310         you need to use this option and/or the previous option to force the
311         proper termination settings on your controller.   If this happens,
312         then you next need to figure out what your settings should be.
313
314         To find the correct settings, power your machine back down, connect
315         back up the SCSI cables, and boot back into your machine like normal.
316         However, boot with the aic7xxx=verbose:0x39 option.  Record the
317         initial DEVCONFIG values for each of your aic7xxx controllers as
318         they are listed, and also record what the machine is detecting as
319         the proper termination on your controllers.  NOTE: the order in
320         which the initial DEVCONFIG values are printed out is not guaranteed
321         to be the same order as the SCSI controllers are registered.  The
322         above option and this option both work on the order of the SCSI
323         controllers as they are registered, so make sure you match the right
324         DEVCONFIG values with the right controllers if you have more than
325         one aic7xxx controller.
326
327         Once you have the detected termination settings and the initial
328         DEVCONFIG values for each controller, then figure out what the
329         termination on each of the controllers *should* be.  Hopefully, that
330         part is correct, but it could possibly be wrong if there is
331         bogus cable detection logic on your controller or something similar.
332         If all the controllers have the correct termination settings, then
333         don't set the aic7xxx=override_term variable at all, leave it alone.
334         Next, on any controllers that go into an infinite reset loop when
335         you unplug all the SCSI cables, get the starting DEVCONFIG value.
336         If the initial DEVCONFIG value is divisible by 2, then the correct
337         setting for that controller is 0.  If it's an odd number, then
338         the correct setting for that controller is 1.  For any other
339         controllers that didn't have an infinite reset problem, then reverse
340         the above options.  If DEVCONFIG was even, then the correct setting
341         is 1, if not then the correct setting is 0.
342
343         Now that you know what the correct setting was for each controller,
344         we need to encode that into the aic7xxx=stpwlev:0x... variable.
345         This variable is a bit field encoded variable.  Bit 0 is for the first
346         aic7xxx controller, bit 1 for the next, etc.  Put all these bits
347         together and you get a number.  For example, if the third aic7xxx
348         needed a 1, but the second and first both needed a 0, then the bits
349         would be 100 in binary.  This then translates to 0x04.  You would
350         therefore set aic7xxx=stpwlev:0x04.  This is fairly standard binary
351         to hexadecimal conversions here.  If you aren't up to speed on the
352         binary->hex conversion then send an email to the aic7xxx mailing
353         list and someone can help you out.
354
355     "aic7xxx=tag_info:{{8,8..},{8,8..},..}" - This option is used to disable
356         or enable Tagged Command Queueing (TCQ) on specific devices.  As of
357         driver version 5.1.11, TCQ is now either on or off by default
358         according to the setting you choose during the make config process.
359         In order to en/disable TCQ for certain devices at boot time, a user
360         may use this boot param.  The driver will then parse this message out
361         and en/disable the specific device entries that are present based upon
362         the value given.  The param line is parsed in the following manner:
363
364           { - first instance indicates the start of this parameter values
365               second instance is the start of entries for a particular
366               device entry
367           } - end the entries for a particular host adapter, or end the entire
368               set of parameter entries
369           , - move to next entry.  Inside of a set of device entries, this
370               moves us to the next device on the list.  Outside of device
371               entries, this moves us to the next host adapter
372           . - Same effect as , but is safe to use with insmod.
373           x - the number to enter into the array at this position.  
374               0 = Enable tagged queueing on this device and use the default
375                   queue depth
376               1-254 = Enable tagged queueing on this device and use this
377                       number as the queue depth
378               255 = Disable tagged queueing on this device.
379               Note: anything above 32 for an actual queue depth is wasteful
380                     and not recommended.
381
382         A few examples of how this can be used:
383
384         tag_info:{{8,12,,0,,255,4}}
385           This line will only effect the first aic7xxx card registered.  It
386           will set scsi id 0 to a queue depth of 8, id 1 to 12, leave id 2
387           at the default, set id 3 to tagged queueing enabled and use the
388           default queue depth, id 4 default, id 5 disabled, and id 6 to 4.
389           Any not specified entries stay at the default value, repeated
390           commas with no value specified will simply increment to the next id
391           without changing anything for the missing values.
392
393         tag_info:{,,,{,,,255}}
394           First, second, and third adapters at default values.  Fourth
395           adapter, id 3 is disabled.  Notice that leading commas simply
396           increment what the first number effects, and there are no need
397           for trailing commas.  When you close out an adapter, or the
398           entire entry, anything not explicitly set stays at the default
399           value.
400
401         A final note on this option.  The scanner I used for this isn't
402         perfect or highly robust.  If you mess the line up, the worst that
403         should happen is that the line will get ignored.  If you don't
404         close out the entire entry with the final bracket, then any other
405         aic7xxx options after this will get ignored.  So, in general, be
406         sure of what you are entering, and after you have it right, just
407         add it to the lilo.conf file so there won't be any mistakes.  As
408         a means of checking this parser, the entire tag_info array for
409         each card is now printed out in the /proc/scsi/aic7xxx/x file.  You
410         can use that to verify that your options were parsed correctly. 
411         
412     Boot command line options may be combined to form the proper set of options
413     a user might need.  For example, the following is valid:
414     
415     aic7xxx=verbose,extended,irq_trigger:1
416     
417     The only requirement is that individual options be separated by a comma or
418     a period on the command line.
419         
420   Module Loading command options
421   ------------------------------
422     When loading the aic7xxx driver as a module, the exact same options are
423     available to the user.  However, the syntax to specify the options changes
424     slightly.  For insmod, you need to wrap the aic7xxx= argument in quotes
425     and replace all ',' with '.'.  So, for example, a valid insmod line
426     would be:
427
428     insmod aic7xxx aic7xxx='verbose.irq_trigger:1.extended'
429
430     This line should result in the *exact* same behaviour as if you typed
431     it in at the lilo prompt and the driver was compiled into the kernel
432     instead of being a module.  The reason for the single quote is so that
433     the shell won't try to interpret anything in the line, such as {. 
434     Insmod assumes any options starting with a letter instead of a number
435     is a character string (which is what we want) and by switching all of
436     the commas to periods, insmod won't interpret this as more than one
437     string and write junk into our binary image.  I consider it a bug in
438     the insmod program that even if you wrap your string in quotes (quotes
439     that pass the shell mind you and that insmod sees) it still treats
440     a comma inside of those quotes as starting a new variable, resulting
441     in memory scribbles if you don't switch the commas to periods.
442
443
444   Kernel Compile options
445   ------------------------------
446     The various kernel compile time options for this driver are now fairly
447     well documented in the file drivers/scsi/Kconfig.  In order to
448     see this documentation, you need to use one of the advanced configuration
449     programs (menuconfig and xconfig).  If you are using the "make menuconfig"
450     method of configuring your kernel, then you would simply highlight the
451     option in question and hit the ? key.  If you are using the "make xconfig"
452     method of configuring your kernel, then simply click on the help button
453     next to the option you have questions about.  The help information from
454     the Configure.help file will then get automatically displayed.
455
456   /proc support
457   ------------------------------
458     The /proc support for the AIC7xxx can be found in the /proc/scsi/aic7xxx/
459     directory. That directory contains a file for each SCSI controller in
460     the system. Each file presents the current configuration and transfer
461     statistics (enabled with #define in aic7xxx.c) for each controller.
462
463     Thanks to Michael Neuffer for his upper-level SCSI help, and
464     Matthew Jacob for statistics support.
465
466   Debugging the driver
467   ------------------------------
468     Should you have problems with this driver, and would like some help in
469     getting them solved, there are a couple debugging items built into
470     the driver to facilitate getting the needed information from the system.
471     In general, I need a complete description of the problem, with as many
472     logs as possible concerning what happens.  To help with this, there is
473     a command option aic7xxx=panic_on_abort.  This option, when set, forces
474     the driver to panic the kernel on the first SCSI abort issued by the
475     mid level SCSI code.  If your system is going to reset loops and you
476     can't read the screen, then this is what you need.  Not only will it
477     stop the system, but it also prints out a large amount of state
478     information in the process.  Second, if you specify the option
479     "aic7xxx=verbose:0x1ffff", the system will print out *SOOOO* much
480     information as it runs that you won't be able to see anything.
481     However, this can actually be very useful if your machine simply
482     locks up when trying to boot, since it will pin-point what was last
483     happening (in regards to the aic7xxx driver) immediately prior to
484     the lockup.  This is really only useful if your machine simply can
485     not boot up successfully.  If you can get your machine to run, then
486     this will produce far too much information.
487
488   FTP sites
489   ------------------------------
490     ftp://ftp.redhat.com/pub/aic/
491       - Out of date.  I used to keep stuff here, but too many people
492         complained about having a hard time getting into Red Hat's ftp
493         server.  So use the web site below instead.
494     ftp://ftp.pcnet.com/users/eischen/Linux/
495       - Dan Eischen's driver distribution area
496     ftp://ekf2.vsb.cz/pub/linux/kernel/aic7xxx/ftp.teleport.com/
497       - European Linux mirror of Teleport site
498
499   Web sites
500   ------------------------------
501     http://people.redhat.com/dledford/
502       - My web site, also the primary aic7xxx site with several related
503         pages.
504
505 Dean W. Gehnert
506 deang@teleport.com
507
508 $Revision: 3.0 $
509
510 Modified by Doug Ledford 1998-2000
511