linux/Documentation/scsi/aic7xxx_old.txt
<<
>>
Prefs
   1                            AIC7xxx Driver for Linux
   2
   3Introduction
   4----------------------------
   5The AIC7xxx SCSI driver adds support for Adaptec (http://www.adaptec.com)
   6SCSI controllers and chipsets. Major portions of the driver and driver
   7development are shared between both Linux and FreeBSD. Support for the
   8AIC-7xxx chipsets have been in the default Linux kernel since approximately
   9linux-1.1.x and fairly stable since linux-1.2.x, and are also in FreeBSD
  102.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
 505Dean W. Gehnert
 506deang@teleport.com
 507
 508$Revision: 3.0 $
 509
 510Modified by Doug Ledford 1998-2000
 511
 512
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.