Documentation/scsi/sym53c8xx_2.txt

   1 The Linux SYM-2 driver documentation file
   2
   3 Written by Gerard Roudier <groudier@free.fr>
   4 21 Rue Carnot
   5 95170 DEUIL LA BARRE - FRANCE
   6
   7 Decembre 28 2000
   8 ===============================================================================
   9
  10 1.  Introduction
  11 2.  Supported chips and SCSI features
  12 3.  Advantages of this driver for newer chips.
  13       3.1 Optimized SCSI SCRIPTS
  14       3.2 New features appeared with the SYM53C896
  15 4.  Memory mapped I/O versus normal I/O
  16 5.  Tagged command queueing
  17 6.  Parity checking
  18 7.  Profiling information
  19 8.  Control commands
  20       8.1  Set minimum synchronous period
  21       8.2  Set wide size
  22       8.3  Set maximum number of concurrent tagged commands
  23       8.4  Set debug mode
  24       8.5  Set flag (no_disc)
  25       8.6  Set verbose level
  26       8.7  Reset all logical units of a target
  27       8.8  Abort all tasks of all logical units of a target
  28 9.  Configuration parameters
  29 10. Boot setup commands
  30       10.1 Syntax
  31       10.2 Available arguments
  32              10.2.1  Master parity checking
  33              10.2.2  Scsi parity checking
  34              10.2.3  Default number of tagged commands
  35              10.2.4  Default synchronous period factor
  36              10.2.5  Verbosity level
  37              10.2.6  Debug mode
  38              10.2.7  Burst max
  39              10.2.8  LED support
  40              10.2.9  Max wide
  41              10.2.10 Differential mode
  42              10.2.11 IRQ mode
  43              10.2.12 Reverse probe
  44              10.2.13 Fix up PCI configuration space
  45              10.2.14 Serial NVRAM
  46              10.2.15 Check SCSI BUS
  47              10.2.16 Exclude a host from being attached
  48              10.2.17 Suggest a default SCSI id for hosts
  49       10.3 PCI configuration fix-up boot option
  50       10.4 Serial NVRAM support boot option
  51       10.5 SCSI BUS checking boot option
  52 11. SCSI problem troubleshooting
  53       15.1 Problem tracking
  54       15.2 Understanding hardware error reports
  55 12. Serial NVRAM support (by Richard Waltham)
  56       17.1 Features
  57       17.2 Symbios NVRAM layout
  58       17.3 Tekram  NVRAM layout
  59
  60 ===============================================================================
  61
  62 1. Introduction
  63
  64 This driver supports the whole SYM53C8XX family of PCI-SCSI controllers.
  65 It also support the subset of LSI53C10XX PCI-SCSI controllers that are based
  66 on the SYM53C8XX SCRIPTS language.
  67
  68 It replaces the sym53c8xx+ncr53c8xx driver bundle and shares its core code
  69 with the FreeBSD SYM-2 driver. The `glue' that allows this driver to work
  70 under Linux is contained in 2 files named sym_glue.h and sym_glue.c.
  71 Other drivers files are intended not to depend on the Operating System
  72 on which the driver is used.
  73
  74 The history of this driver can be summerized as follows:
  75
  76 1993: ncr driver written for 386bsd and FreeBSD by:
  77           Wolfgang Stanglmeier        <wolf@cologne.de>
  78           Stefan Esser                <se@mi.Uni-Koeln.de>
  79
  80 1996: port of the ncr driver to Linux-1.2.13 and rename it ncr53c8xx.
  81           Gerard Roudier
  82
  83 1998: new sym53c8xx driver for Linux based on LOAD/STORE instruction and that
  84       adds full support for the 896 but drops support for early NCR devices.
  85           Gerard Roudier
  86
  87 1999: port of the sym53c8xx driver to FreeBSD and support for the LSI53C1010
  88       33 MHz and 66MHz Ultra-3 controllers. The new driver is named `sym'.
  89           Gerard Roudier
  90
  91 2000: Add support for early NCR devices to FreeBSD `sym' driver.
  92       Break the driver into several sources and separate the OS glue
  93       code from the core code that can be shared among different O/Ses.
  94       Write a glue code for Linux.
  95           Gerard Roudier
  96
  97 This README file addresses the Linux version of the driver. Under FreeBSD,
  98 the driver documentation is the sym.8 man page.
  99
 100 Information about new chips is available at LSILOGIC web server:
 101
 102           http://www.lsilogic.com/
 103
 104 SCSI standard documentations are available at T10 site:
 105
 106           http://www.t10.org/
 107
 108 Useful SCSI tools written by Eric Youngdale are part of most Linux
 109 distributions:
 110    scsiinfo:    command line tool
 111    scsi-config: TCL/Tk tool using scsiinfo
 112
 113 2. Supported chips and SCSI features
 114
 115 The following features are supported for all chips:
 116
 117         Synchronous negotiation
 118         Disconnection
 119         Tagged command queuing
 120         SCSI parity checking
 121         PCI Master parity checking
 122
 123 Other features depends on chip capabilities.
 124 The driver notably uses optimized SCRIPTS for devices that support
 125 LOAD/STORE and handles PHASE MISMATCH from SCRIPTS for devices that
 126 support the corresponding feature.
 127
 128 The following table shows some characteristics of the chip family.
 129
 130        On board                                   LOAD/STORE   HARDWARE
 131 Chip   SDMS BIOS   Wide   SCSI std.   Max. sync   SCRIPTS      PHASE MISMATCH
 132 ----   ---------   ----   ---------   ----------  ----------   --------------
 133 810        N         N      FAST10    10 MB/s        N             N
 134 810A       N         N      FAST10    10 MB/s        Y             N
 135 815        Y         N      FAST10    10 MB/s        N             N
 136 825        Y         Y      FAST10    20 MB/s        N             N
 137 825A       Y         Y      FAST10    20 MB/s        Y             N
 138 860        N         N      FAST20    20 MB/s        Y             N
 139 875        Y         Y      FAST20    40 MB/s        Y             N
 140 875A       Y         Y      FAST20    40 MB/s        Y             Y
 141 876        Y         Y      FAST20    40 MB/s        Y             N
 142 895        Y         Y      FAST40    80 MB/s        Y             N
 143 895A       Y         Y      FAST40    80 MB/s        Y             Y
 144 896        Y         Y      FAST40    80 MB/s        Y             Y
 145 897        Y         Y      FAST40    80 MB/s        Y             Y
 146 1510D      Y         Y      FAST40    80 MB/s        Y             Y
 147 1010       Y         Y      FAST80   160 MB/s        Y             Y
 148 1010_66*   Y         Y      FAST80   160 MB/s        Y             Y
 149
 150 * Chip supports 33MHz and 66MHz PCI bus clock.
 151
 152
 153 Summary of other supported features:
 154
 155 Module:                allow to load the driver
 156 Memory mapped I/O:     increases performance
 157 Control commands:      write operations to the proc SCSI file system
 158 Debugging information: written to syslog (expert only)
 159 Scatter / gather
 160 Shared interrupt
 161 Boot setup commands
 162 Serial NVRAM:          Symbios and Tekram formats
 163
 164
 165 3. Advantages of this driver for newer chips.
 166
 167 3.1 Optimized SCSI SCRIPTS.
 168
 169 All chips except the 810, 815 and 825, support new SCSI SCRIPTS instructions
 170 named LOAD and STORE that allow to move up to 1 DWORD from/to an IO register
 171 to/from memory much faster that the MOVE MEMORY instruction that is supported
 172 by the 53c7xx and 53c8xx family.
 173
 174 The LOAD/STORE instructions support absolute and DSA relative addressing
 175 modes. The SCSI SCRIPTS had been entirely rewritten using LOAD/STORE instead
 176 of MOVE MEMORY instructions.
 177
 178 Due to the lack of LOAD/STORE SCRIPTS instructions by earlier chips, this
 179 driver also incorporates a different SCRIPTS set based on MEMORY MOVE, in
 180 order to provide support for the entire SYM53C8XX chips family.
 181
 182 3.2 New features appeared with the SYM53C896
 183
 184 Newer chips (see above) allows handling of the phase mismatch context from
 185 SCRIPTS (avoids the phase mismatch interrupt that stops the SCSI processor
 186 until the C code has saved the context of the transfer).
 187
 188 The 896 and 1010 chips support 64 bit PCI transactions and addressing,
 189 while the 895A supports 32 bit PCI transactions and 64 bit addressing.
 190 The SCRIPTS processor of these chips is not true 64 bit, but uses segment
 191 registers for bit 32-63. Another interesting feature is that LOAD/STORE
 192 instructions that address the on-chip RAM (8k) remain internal to the chip.
 193
 194 4. Memory mapped I/O versus normal I/O
 195
 196 Memory mapped I/O has less latency than normal I/O and is the recommended
 197 way for doing IO with PCI devices. Memory mapped I/O seems to work fine on
 198 most hardware configurations, but some poorly designed chipsets may break
 199 this feature. A configuration option is provided for normal I/O to be
 200 used but the driver defaults to MMIO.
 201
 202 5. Tagged command queueing
 203
 204 Queuing more than 1 command at a time to a device allows it to perform
 205 optimizations based on actual head positions and its mechanical
 206 characteristics. This feature may also reduce average command latency.
 207 In order to really gain advantage of this feature, devices must have
 208 a reasonable cache size (No miracle is to be expected for a low-end
 209 hard disk with 128 KB or less).
 210 Some kown old SCSI devices do not properly support tagged command queuing.
 211 Generally, firmware revisions that fix this kind of problems are available
 212 at respective vendor web/ftp sites.
 213 All I can say is that I never have had problem with tagged queuing using
 214 this driver and its predecessors. Hard disks that behaved correctly for
 215 me using tagged commands are the following:
 216
 217 - IBM S12 0662
 218 - Conner 1080S
 219 - Quantum Atlas I
 220 - Quantum Atlas II
 221 - Seagate Cheetah I
 222 - Quantum Viking II
 223 - IBM DRVS
 224 - Quantum Atlas IV
 225 - Seagate Cheetah II
 226
 227 If your controller has NVRAM, you can configure this feature per target
 228 from the user setup tool. The Tekram Setup program allows to tune the
 229 maximum number of queued commands up to 32. The Symbios Setup only allows
 230 to enable or disable this feature.
 231
 232 The maximum number of simultaneous tagged commands queued to a device
 233 is currently set to 16 by default.  This value is suitable for most SCSI
 234 disks.  With large SCSI disks (>= 2GB, cache >= 512KB, average seek time
 235 <= 10 ms), using a larger value may give better performances.
 236
 237 This driver supports up to 255 commands per device, and but using more than
 238 64 is generally not worth-while, unless you are using a very large disk or
 239 disk arrays. It is noticeable that most of recent hard disks seem not to
 240 accept more than 64 simultaneous commands. So, using more than 64 queued
 241 commands is probably just resource wasting.
 242
 243 If your controller does not have NVRAM or if it is managed by the SDMS
 244 BIOS/SETUP, you can configure tagged queueing feature and device queue
 245 depths from the boot command-line. For example:
 246
 247   sym53c8xx=tags:4/t2t3q15-t4q7/t1u0q32
 248
 249 will set tagged commands queue depths as follow:
 250
 251 - target 2  all luns  on controller 0 --> 15
 252 - target 3  all luns  on controller 0 --> 15
 253 - target 4  all luns  on controller 0 -->  7
 254 - target 1  lun 0     on controller 1 --> 32
 255 - all other target/lun                -->  4
 256
 257 In some special conditions, some SCSI disk firmwares may return a
 258 QUEUE FULL status for a SCSI command. This behaviour is managed by the
 259 driver using the following heuristic:
 260
 261 - Each time a QUEUE FULL status is returned, tagged queue depth is reduced
 262   to the actual number of disconnected commands.
 263
 264 - Every 200 successfully completed SCSI commands, if allowed by the
 265   current limit, the maximum number of queueable commands is incremented.
 266
 267 Since QUEUE FULL status reception and handling is resource wasting, the
 268 driver notifies by default this problem to user by indicating the actual
 269 number of commands used and their status, as well as its decision on the
 270 device queue depth change.
 271 The heuristic used by the driver in handling QUEUE FULL ensures that the
 272 impact on performances is not too bad. You can get rid of the messages by
 273 setting verbose level to zero, as follow:
 274
 275 1st method: boot your system using 'sym53c8xx=verb:0' option.
 276 2nd method: apply "setverbose 0" control command to the proc fs entry
 277             corresponding to your controller after boot-up.
 278
 279 6. Parity checking
 280
 281 The driver supports SCSI parity checking and PCI bus master parity
 282 checking. These features must be enabled in order to ensure safe data
 283 transfers. However, some flawed devices or mother boards will have
 284 problems with parity. You can disable either PCI parity or SCSI parity
 285 checking by entering appropriate options from the boot command line.
 286 (See 10: Boot setup commands).
 287
 288 7. Profiling information
 289
 290 This driver does not provide profiling informations as did its predecessors.
 291 This feature was not this useful and added complexity to the code.
 292 As the driver code got more complex, I have decided to remove everything
 293 that didn't seem actually useful.
 294
 295 8. Control commands
 296
 297 Control commands can be sent to the driver with write operations to
 298 the proc SCSI file system. The generic command syntax is the
 299 following:
 300
 301       echo "<verb> <parameters>" >/proc/scsi/sym53c8xx/0
 302       (assumes controller number is 0)
 303
 304 Using "all" for "<target>" parameter with the commands below will
 305 apply to all targets of the SCSI chain (except the controller).
 306
 307 Available commands:
 308
 309 8.1 Set minimum synchronous period factor
 310
 311     setsync <target> <period factor>
 312
 313     target:    target number
 314     period:    minimum synchronous period.
 315                Maximum speed = 1000/(4*period factor) except for special
 316                cases below.
 317
 318     Specify a period of 0, to force asynchronous transfer mode.
 319
 320        9 means 12.5 nano-seconds synchronous period
 321       10 means 25 nano-seconds synchronous period
 322       11 means 30 nano-seconds synchronous period
 323       12 means 50 nano-seconds synchronous period
 324
 325 8.2 Set wide size
 326
 327     setwide <target> <size>
 328
 329     target:    target number
 330     size:      0=8 bits, 1=16bits
 331
 332 8.3 Set maximum number of concurrent tagged commands
 333
 334     settags <target> <tags>
 335
 336     target:    target number
 337     tags:      number of concurrent tagged commands
 338                must not be greater than configured (default: 16)
 339
 340 8.4 Set debug mode
 341
 342     setdebug <list of debug flags>
 343
 344     Available debug flags:
 345         alloc:   print info about memory allocations (ccb, lcb)
 346         queue:   print info about insertions into the command start queue
 347         result:  print sense data on CHECK CONDITION status
 348         scatter: print info about the scatter process
 349         scripts: print info about the script binding process
 350         tiny:    print minimal debugging information
 351         timing:  print timing information of the NCR chip
 352         nego:    print information about SCSI negotiations
 353         phase:   print information on script interruptions
 354
 355     Use "setdebug" with no argument to reset debug flags.
 356
 357
 358 8.5 Set flag (no_disc)
 359
 360     setflag <target> <flag>
 361
 362     target:    target number
 363
 364     For the moment, only one flag is available:
 365
 366         no_disc:   not allow target to disconnect.
 367
 368     Do not specify any flag in order to reset the flag. For example:
 369     - setflag 4
 370       will reset no_disc flag for target 4, so will allow it disconnections.
 371     - setflag all
 372       will allow disconnection for all devices on the SCSI bus.
 373
 374
 375 8.6 Set verbose level
 376
 377     setverbose #level
 378
 379     The driver default verbose level is 1. This command allows to change
 380     th driver verbose level after boot-up.
 381
 382 8.7 Reset all logical units of a target
 383
 384     resetdev <target>
 385
 386     target:    target number
 387     The driver will try to send a BUS DEVICE RESET message to the target.
 388
 389 8.8 Abort all tasks of all logical units of a target
 390
 391     cleardev <target>
 392
 393     target:    target number
 394     The driver will try to send a ABORT message to all the logical units
 395     of the target.
 396
 397
 398 9. Configuration parameters
 399
 400 Under kernel configuration tools (make menuconfig, for example), it is
 401 possible to change some default driver configuration parameters.
 402 If the firmware of all your devices is perfect enough, all the
 403 features supported by the driver can be enabled at start-up. However,
 404 if only one has a flaw for some SCSI feature, you can disable the
 405 support by the driver of this feature at linux start-up and enable
 406 this feature after boot-up only for devices that support it safely.
 407
 408 Configuration parameters:
 409
 410 Use normal IO                         (default answer: n)
 411     Answer "y" if you suspect your mother board to not allow memory mapped I/O.
 412     May slow down performance a little.
 413
 414 Default tagged command queue depth    (default answer: 16)
 415     Entering 0 defaults to tagged commands not being used.
 416     This parameter can be specified from the boot command line.
 417
 418 Maximum number of queued commands     (default answer: 32)
 419     This option allows you to specify the maximum number of tagged commands
 420     that can be queued to a device. The maximum supported value is 255.
 421
 422 Synchronous transfers frequency       (default answer: 80)
 423     This option allows you to specify the frequency in MHz the driver
 424     will use at boot time for synchronous data transfer negotiations.
 425     0 means "asynchronous data transfers".
 426
 427 10. Boot setup commands
 428
 429 10.1 Syntax
 430
 431 Setup commands can be passed to the driver either at boot time or as a
 432 string variable using 'insmod'.
 433
 434 A boot setup command for this driver begins with the driver name "sym53c8xx=".
 435 The kernel syntax parser then expects an optionnal list of integers separated
 436 with comma followed by an optional list of  comma-separated strings.
 437
 438 Example of boot setup command under lilo prompt:
 439
 440 lilo: linux root=/dev/sda2 sym53c8xx=tags:4,sync:10,debug:0x200
 441
 442 - enable tagged commands, up to 4 tagged commands queued.
 443 - set synchronous negotiation speed to 10 Mega-transfers / second.
 444 - set DEBUG_NEGO flag.
 445
 446 Since comma seems not to be allowed when defining a string variable using
 447 'insmod', the driver also accepts <space> as option separator.
 448 The following command will install driver module with the same options as
 449 above.
 450
 451     insmod sym53c8xx.o sym53c8xx="tags:4 sync:10 debug:0x200"
 452
 453 The integer list of arguments is discarded by the driver.
 454
 455 Each string argument must be specified as "keyword:value". Only lower-case
 456 characters and digits are allowed.
 457
 458 10.2 Available arguments
 459
 460 10.2.1  Master parity checking
 461         mpar:y     enabled
 462         mpar:n     disabled
 463
 464 10.2.2  Scsi parity checking
 465         spar:y     enabled
 466         spar:n     disabled
 467
 468 10.2.3  Default number of tagged commands
 469         tags:0     (or tags:1 ) tagged command queuing disabled
 470         tags:#tags (#tags  > 1) tagged command queuing enabled
 471   #tags will be truncated to the max queued commands configuration parameter.
 472   This option also allows to specify a command queue depth for each device
 473   that support tagged command queueing.
 474   Example:
 475       sym53c8xx=tags:10/t2t3q16-t5q24/t1u2q32
 476                will set devices queue depth as follow:
 477       - controller #0 target #2 and target #3                  -> 16 commands,
 478       - controller #0 target #5                                -> 24 commands,
 479       - controller #1 target #1 logical unit #2                -> 32 commands,
 480       - all other logical units (all targets, all controllers) -> 10 commands.
 481
 482 10.2.4  Default synchronous period factor
 483         sync:255     disabled (asynchronous transfer mode)
 484         sync:#factor
 485   #factor =  9     Ultra-3 SCSI 80 Mega-transfers / second (Wide only)
 486   #factor = 10     Ultra-2 SCSI 40 Mega-transfers / second
 487   #factor = 11     Ultra-2 SCSI 33 Mega-transfers / second
 488   #factor < 25     Ultra   SCSI 20 Mega-transfers / second
 489   #factor < 50     Fast    SCSI-2
 490
 491   In all cases, the driver will use the minimum transfer period supported by
 492   controllers according to SYM53C8XX chip type.
 493
 494 10.2.5  Verbosity level
 495         verb:0     minimal
 496         verb:1     normal
 497         verb:2     too much
 498
 499 10.2.6 Debug mode
 500         debug:0  clear debug flags
 501         debug:#x   set debug flags
 502   #x is an integer value combining the following power-of-2 values:
 503   DEBUG_ALLOC       0x1
 504   DEBUG_PHASE       0x2
 505   DEBUG_POLL        0x4
 506   DEBUG_QUEUE       0x8
 507   DEBUG_RESULT     0x10
 508   DEBUG_SCATTER    0x20
 509   DEBUG_SCRIPT     0x40
 510   DEBUG_TINY       0x80
 511   DEBUG_TIMING    0x100
 512   DEBUG_NEGO      0x200
 513   DEBUG_TAGS      0x400
 514   DEBUG_FREEZE    0x800
 515   DEBUG_RESTART  0x1000
 516
 517   You can play safely with DEBUG_NEGO. However, some of these flags may
 518   generate bunches of syslog messages.
 519
 520 10.2.7 Burst max
 521         burst:0    burst disabled
 522         burst:255  get burst length from initial IO register settings.
 523         burst:#x   burst enabled (1<<#x burst transfers max)
 524   #x is an integer value which is log base 2 of the burst transfers max.
 525   By default the driver uses the maximum value supported by the chip.
 526
 527 10.2.8 LED support
 528         led:1      enable  LED support
 529         led:0      disable LED support
 530   Donnot enable LED support if your scsi board does not use SDMS BIOS.
 531   (See 'Configuration parameters')
 532
 533 10.2.9 Max wide
 534         wide:1      wide scsi enabled
 535         wide:0      wide scsi disabled
 536   Some scsi boards use a 875 (ultra wide) and only supply narrow connectors.
 537   If you have connected a wide device with a 50 pins to 68 pins cable
 538   converter, any accepted wide negotiation will break further data transfers.
 539   In such a case, using "wide:0" in the bootup command will be helpfull.
 540
 541 10.2.10 Differential mode
 542         diff:0  never set up diff mode
 543         diff:1  set up diff mode if BIOS set it
 544         diff:2  always set up diff mode
 545         diff:3  set diff mode if GPIO3 is not set
 546
 547 10.2.11 IRQ mode
 548         irqm:0     always open drain
 549         irqm:1     same as initial settings (assumed BIOS settings)
 550         irqm:2     always totem pole
 551
 552 10.2.12 Reverse probe
 553         revprob:n   probe chip ids from the PCI configuration in this order:
 554                     810, 815, 825, 860, 875, 885, 875A, 895, 896, 895A,
 555                     1510D, 1010-33, 1010-66.
 556         revprob:y   probe chip ids in the reverse order.
 557
 558 10.2.13 Fix up PCI configuration space
 559         pcifix:<option bits>
 560
 561     Available option bits:
 562         0x0:   No attempt to fix PCI configuration space registers values.
 563         0x1:   Set PCI cache-line size register if not set.
 564         0x2:   Set write and invalidate bit in PCI command register.
 565
 566 10.2.14 Serial NVRAM
 567         nvram:n     do not look for serial NVRAM
 568         nvram:y     test controllers for onboard serial NVRAM
 569         (alternate binary form)
 570         nvram=<bits options>
 571         0x01   look for NVRAM  (equivalent to nvram=y)
 572         0x02   ignore NVRAM "Synchronous negotiation" parameters for all devices
 573         0x04   ignore NVRAM "Wide negotiation"  parameter for all devices
 574         0x08   ignore NVRAM "Scan at boot time" parameter for all devices
 575         0x80   also attach controllers set to OFF in the NVRAM (sym53c8xx only)
 576
 577 10.2.15 Check SCSI BUS
 578         buschk:<option bits>
 579
 580     Available option bits:
 581         0x0:   No check.
 582         0x1:   Check and do not attach the controller on error.
 583         0x2:   Check and just warn on error.
 584
 585 10.2.16 Exclude a host from being attached
 586         excl=<io_address>
 587
 588     Prevent host at a given io address from being attached.
 589     For example 'sym53c8xx=excl:0xb400,excl:0xc000' indicate to the
 590     driver not to attach hosts at address 0xb400 and 0xc000.
 591
 592 10.2.17 Suggest a default SCSI id for hosts
 593         hostid:255      no id suggested.
 594         hostid:#x   (0 < x < 7) x suggested for hosts SCSI id.
 595
 596     If a host SCSI id is available from the NVRAM, the driver will ignore
 597     any value suggested as boot option. Otherwise, if a suggested value
 598     different from 255 has been supplied, it will use it. Otherwise, it will
 599     try to deduce the value previously set in the hardware and use value
 600     7 if the hardware value is zero.
 601
 602 10.3 PCI configuration fix-up boot option
 603
 604 pcifix:<option bits>
 605
 606 Available option bits:
 607     0x1:     Set PCI cache-line size register if not set.
 608     0x2:     Set write and invalidate bit in PCI command register.
 609
 610 Use 'pcifix:3' in order to allow the driver to fix both PCI features.
 611
 612 Recent SYMBIOS 53C8XX scsi processors are able to use PCI read multiple
 613 and PCI write and invalidate commands. These features require the
 614 cache line size register to be properly set in the PCI configuration
 615 space of the chips. On the other hand, chips will use PCI write and
 616 invalidate commands only if the corresponding bit is set to 1 in the
 617 PCI command register.
 618
 619 Not all PCI bioses set the PCI cache line register and the PCI write and
 620 invalidate bit in the PCI configuration space of 53C8XX chips.
 621 Optimized PCI accesses may be broken for some PCI/memory controllers or
 622 make problems with some PCI boards.
 623
 624 10.4 Serial NVRAM support boot option
 625
 626 nvram:n     do not look for serial NVRAM
 627 nvram:y     test controllers for onboard serial NVRAM
 628
 629 This option can also been entered as an hexadecimal value that allows
 630 to control what information the driver will get from the NVRAM and what
 631 information it will ignore.
 632 For details see '17. Serial NVRAM support'.
 633
 634 When this option is enabled, the driver tries to detect all boards using
 635 a Serial NVRAM. This memory is used to hold user set up parameters.
 636
 637 The parameters the driver is able to get from the NVRAM depend on the
 638 data format used, as follow:
 639
 640                                  Tekram format      Symbios format
 641 General and host parameters
 642     Boot order                         N                   Y
 643     Host SCSI ID                       Y                   Y
 644     SCSI parity checking               Y                   Y
 645     Verbose boot messages              N                   Y
 646 SCSI devices parameters
 647     Synchronous transfer speed         Y                   Y
 648     Wide 16 / Narrow                   Y                   Y
 649     Tagged Command Queuing enabled     Y                   Y
 650     Disconnections enabled             Y                   Y
 651     Scan at boot time                  N                   Y
 652
 653 In order to speed up the system boot, for each device configured without
 654 the "scan at boot time" option, the driver forces an error on the
 655 first TEST UNIT READY command received for this device.
 656
 657 Some SDMS BIOS revisions seem to be unable to boot cleanly with very fast
 658 hard disks. In such a situation you cannot configure the NVRAM with
 659 optimized parameters value.
 660
 661 The 'nvram' boot option can be entered in hexadecimal form in order
 662 to ignore some options configured in the NVRAM, as follow:
 663
 664 nvram=<bits options>
 665       0x01   look for NVRAM  (equivalent to nvram=y)
 666       0x02   ignore NVRAM "Synchronous negotiation" parameters for all devices
 667       0x04   ignore NVRAM "Wide negotiation"  parameter for all devices
 668       0x08   ignore NVRAM "Scan at boot time" parameter for all devices
 669       0x80   also attach controllers set to OFF in the NVRAM (sym53c8xx only)
 670
 671 Option 0x80 is disabled by default.
 672 Result is that, by default (option not set), the sym53c8xx driver will not
 673 attach controllers set to OFF in the NVRAM.
 674
 675 10.5 SCSI BUS checking boot option.
 676
 677 When this option is set to a non-zero value, the driver checks SCSI lines
 678 logic state, 100 micro-seconds after having asserted the SCSI RESET line.
 679 The driver just reads SCSI lines and checks all lines read FALSE except RESET.
 680 Since SCSI devices shall release the BUS at most 800 nano-seconds after SCSI
 681 RESET has been asserted, any signal to TRUE may indicate a SCSI BUS problem.
 682 Unfortunately, the following common SCSI BUS problems are not detected:
 683 - Only 1 terminator installed.
 684 - Misplaced terminators.
 685 - Bad quality terminators.
 686 On the other hand, either bad cabling, broken devices, not conformant
 687 devices, ... may cause a SCSI signal to be wrong when te driver reads it.
 688
 689 15. SCSI problem troubleshooting
 690
 691 15.1 Problem tracking
 692
 693 Most SCSI problems are due to a non conformant SCSI bus or too buggy
 694 devices.  If infortunately you have SCSI problems, you can check the
 695 following things:
 696
 697 - SCSI bus cables
 698 - terminations at both end of the SCSI chain
 699 - linux syslog messages (some of them may help you)
 700
 701 If you do not find the source of problems, you can configure the
 702 driver or devices in the NVRAM with minimal features.
 703
 704 - only asynchronous data transfers
 705 - tagged commands disabled
 706 - disconnections not allowed
 707
 708 Now, if your SCSI bus is ok, your system has every chance to work
 709 with this safe configuration but performances will not be optimal.
 710
 711 If it still fails, then you can send your problem description to
 712 appropriate mailing lists or news-groups.  Send me a copy in order to
 713 be sure I will receive it.  Obviously, a bug in the driver code is
 714 possible.
 715
 716   My cyrrent email address: Gerard Roudier <groudier@free.fr>
 717
 718 Allowing disconnections is important if you use several devices on
 719 your SCSI bus but often causes problems with buggy devices.
 720 Synchronous data transfers increases throughput of fast devices like
 721 hard disks.  Good SCSI hard disks with a large cache gain advantage of
 722 tagged commands queuing.
 723
 724 15.2 Understanding hardware error reports
 725
 726 When the driver detects an unexpected error condition, it may display a
 727 message of the following pattern.
 728
 729 sym0:1: ERROR (0:48) (1-21-65) (f/95/0) @ (script 7c0:19000000).
 730 sym0: script cmd = 19000000
 731 sym0: regdump: da 10 80 95 47 0f 01 07 75 01 81 21 80 01 09 00.
 732
 733 Some fields in such a message may help you understand the cause of the
 734 problem, as follows:
 735
 736 sym0:1: ERROR (0:48) (1-21-65) (f/95/0) @ (script 7c0:19000000).
 737 .....A.........B.C....D.E..F....G.H..I.......J.....K...L.......
 738
 739 Field A : target number.
 740   SCSI ID of the device the controller was talking with at the moment the
 741   error occurs.
 742
 743 Field B : DSTAT io register (DMA STATUS)
 744   Bit 0x40 : MDPE Master Data Parity Error
 745              Data parity error detected on the PCI BUS.
 746   Bit 0x20 : BF   Bus Fault
 747              PCI bus fault condition detected
 748   Bit 0x01 : IID  Illegal Instruction Detected
 749              Set by the chip when it detects an Illegal Instruction format
 750              on some condition that makes an instruction illegal.
 751   Bit 0x80 : DFE Dma Fifo Empty
 752              Pure status bit that does not indicate an error.
 753   If the reported DSTAT value contains a combination of MDPE (0x40),
 754   BF (0x20), then the cause may be likely due to a PCI BUS problem.
 755
 756 Field C : SIST io register (SCSI Interrupt Status)
 757   Bit 0x08 : SGE  SCSI GROSS ERROR
 758              Indicates that the chip detected a severe error condition
 759              on the SCSI BUS that prevents the SCSI protocol from functioning
 760              properly.
 761   Bit 0x04 : UDC  Unexpected Disconnection
 762              Indicates that the device released the SCSI BUS when the chip
 763              was not expecting this to happen. A device may behave so to
 764              indicate the SCSI initiator that an error condition not reportable              using the SCSI protocol has occurred.
 765   Bit 0x02 : RST  SCSI BUS Reset
 766              Generally SCSI targets do not reset the SCSI BUS, although any
 767              device on the BUS can reset it at any time.
 768   Bit 0x01 : PAR  Parity
 769              SCSI parity error detected.
 770   On a faulty SCSI BUS, any error condition among SGE (0x08), UDC (0x04) and
 771   PAR (0x01) may be detected by the chip. If your SCSI system sometimes
 772   encounters such error conditions, especially SCSI GROSS ERROR, then a SCSI
 773   BUS problem is likely the cause of these errors.
 774
 775 For fields D,E,F,G and H, you may look into the sym53c8xx_defs.h file
 776 that contains some minimal comments on IO register bits.
 777 Field D : SOCL  Scsi Output Control Latch
 778           This register reflects the state of the SCSI control lines the
 779           chip want to drive or compare against.
 780 Field E : SBCL  Scsi Bus Control Lines
 781           Actual value of control lines on the SCSI BUS.
 782 Field F : SBDL  Scsi Bus Data Lines
 783           Actual value of data lines on the SCSI BUS.
 784 Field G : SXFER  SCSI Transfer
 785           Contains the setting of the Synchronous Period for output and
 786           the current Synchronous offset (offset 0 means asynchronous).
 787 Field H : SCNTL3 Scsi Control Register 3
 788           Contains the setting of timing values for both asynchronous and
 789           synchronous data transfers.
 790 Field I : SCNTL4 Scsi Control Register 4
 791           Only meaninful for 53C1010 Ultra3 controllers.
 792
 793 Understanding Fields J, K, L and dumps requires to have good knowledge of
 794 SCSI standards, chip cores functionnals and internal driver data structures.
 795 You are not required to decode and understand them, unless you want to help
 796 maintain the driver code.
 797
 798 17. Serial NVRAM (added by Richard Waltham: dormouse@farsrobt.demon.co.uk)
 799
 800 17.1 Features
 801
 802 Enabling serial NVRAM support enables detection of the serial NVRAM included
 803 on Symbios and some Symbios compatible host adaptors, and Tekram boards. The
 804 serial NVRAM is used by Symbios and Tekram to hold set up parameters for the
 805 host adaptor and it's attached drives.
 806
 807 The Symbios NVRAM also holds data on the boot order of host adaptors in a
 808 system with more than one host adaptor. This enables the order of scanning
 809 the cards for drives to be changed from the default used during host adaptor
 810 detection.
 811
 812 This can be done to a limited extent at the moment using "reverse probe" but
 813 this only changes the order of detection of different types of cards. The
 814 NVRAM boot order settings can do this as well as change the order the same
 815 types of cards are scanned in, something "reverse probe" cannot do.
 816
 817 Tekram boards using Symbios chips, DC390W/F/U, which have NVRAM are detected
 818 and this is used to distinguish between Symbios compatible and Tekram host
 819 adaptors. This is used to disable the Symbios compatible "diff" setting
 820 incorrectly set on Tekram boards if the CONFIG_SCSI_53C8XX_SYMBIOS_COMPAT
 821 configuration parameter is set enabling both Symbios and Tekram boards to be
 822 used together with the Symbios cards using all their features, including
 823 "diff" support. ("led pin" support for Symbios compatible cards can remain
 824 enabled when using Tekram cards. It does nothing useful for Tekram host
 825 adaptors but does not cause problems either.)
 826
 827
 828 17.2 Symbios NVRAM layout
 829
 830 typical data at NVRAM address 0x100 (53c810a NVRAM)
 831 -----------------------------------------------------------
 832 00 00
 833 64 01
 834 8e 0b
 835
 836 00 30 00 00 00 00 07 00 00 00 00 00 00 00 07 04 10 04 00 00
 837
 838 04 00 0f 00 00 10 00 50 00 00 01 00 00 62
 839 04 00 03 00 00 10 00 58 00 00 01 00 00 63
 840 04 00 01 00 00 10 00 48 00 00 01 00 00 61
 841 00 00 00 00 00 00 00 00 00 00 00 00 00 00
 842
 843 0f 00 08 08 64 00 0a 00
 844 0f 00 08 08 64 00 0a 00
 845 0f 00 08 08 64 00 0a 00
 846 0f 00 08 08 64 00 0a 00
 847 0f 00 08 08 64 00 0a 00
 848 0f 00 08 08 64 00 0a 00
 849 0f 00 08 08 64 00 0a 00
 850 0f 00 08 08 64 00 0a 00
 851
 852 0f 00 08 08 64 00 0a 00
 853 0f 00 08 08 64 00 0a 00
 854 0f 00 08 08 64 00 0a 00
 855 0f 00 08 08 64 00 0a 00
 856 0f 00 08 08 64 00 0a 00
 857 0f 00 08 08 64 00 0a 00
 858 0f 00 08 08 64 00 0a 00
 859 0f 00 08 08 64 00 0a 00
 860
 861 00 00 00 00 00 00 00 00
 862 00 00 00 00 00 00 00 00
 863 00 00 00 00 00 00 00 00
 864 00 00 00 00 00 00 00 00
 865 00 00 00 00 00 00 00 00
 866 00 00 00 00 00 00 00 00
 867 00 00 00 00 00 00 00 00
 868 00 00 00 00 00 00 00 00
 869
 870 00 00 00 00 00 00 00 00
 871 00 00 00 00 00 00 00 00
 872 00 00 00 00 00 00 00 00
 873 00 00 00 00 00 00 00 00
 874 00 00 00 00 00 00 00 00
 875 00 00 00 00 00 00 00 00
 876 00 00 00 00 00 00 00 00
 877 00 00 00 00 00 00 00 00
 878
 879 00 00 00 00 00 00 00 00
 880 00 00 00 00 00 00 00 00
 881 00 00 00 00 00 00 00 00
 882
 883 fe fe
 884 00 00
 885 00 00
 886 -----------------------------------------------------------
 887 NVRAM layout details
 888
 889 NVRAM Address 0x000-0x0ff not used
 890               0x100-0x26f initialised data
 891               0x270-0x7ff not used
 892
 893 general layout
 894
 895         header  -   6 bytes,
 896         data    - 356 bytes (checksum is byte sum of this data)
 897         trailer -   6 bytes
 898                   ---
 899         total     368 bytes
 900
 901 data area layout
 902
 903         controller set up  -  20 bytes
 904         boot configuration -  56 bytes (4x14 bytes)
 905         device set up      - 128 bytes (16x8 bytes)
 906         unused (spare?)    - 152 bytes (19x8 bytes)
 907                              ---
 908         total                356 bytes
 909
 910 -----------------------------------------------------------
 911 header
 912
 913 00 00   - ?? start marker
 914 64 01   - byte count (lsb/msb excludes header/trailer)
 915 8e 0b   - checksum (lsb/msb excludes header/trailer)
 916 -----------------------------------------------------------
 917 controller set up
 918
 919 00 30 00 00 00 00 07 00 00 00 00 00 00 00 07 04 10 04 00 00
 920                    |     |           |     |
 921                    |     |           |      -- host ID
 922                    |     |           |
 923                    |     |            --Removable Media Support
 924                    |     |               0x00 = none
 925                    |     |               0x01 = Bootable Device
 926                    |     |               0x02 = All with Media
 927                    |     |
 928                    |      --flag bits 2
 929                    |        0x00000001= scan order hi->low
 930                    |            (default 0x00 - scan low->hi)
 931                     --flag bits 1
 932                        0x00000001 scam enable
 933                        0x00000010 parity enable
 934                        0x00000100 verbose boot msgs
 935
 936 remaining bytes unknown - they do not appear to change in my
 937 current set up for any of the controllers.
 938
 939 default set up is identical for 53c810a and 53c875 NVRAM
 940 (Removable Media added Symbios BIOS version 4.09)
 941 -----------------------------------------------------------
 942 boot configuration
 943
 944 boot order set by order of the devices in this table
 945
 946 04 00 0f 00 00 10 00 50 00 00 01 00 00 62 -- 1st controller
 947 04 00 03 00 00 10 00 58 00 00 01 00 00 63    2nd controller
 948 04 00 01 00 00 10 00 48 00 00 01 00 00 61    3rd controller
 949 00 00 00 00 00 00 00 00 00 00 00 00 00 00    4th controller
 950        |  |  |  |     |        |     |  |
 951        |  |  |  |     |        |      ---- PCI io port adr
 952        |  |  |  |     |         --0x01 init/scan at boot time
 953        |  |  |  |      --PCI device/function number (0xdddddfff)
 954        |  |   ----- ?? PCI vendor ID (lsb/msb)
 955         ----PCI device ID (lsb/msb)
 956
 957 ?? use of this data is a guess but seems reasonable
 958
 959 remaining bytes unknown - they do not appear to change in my
 960 current set up
 961
 962 default set up is identical for 53c810a and 53c875 NVRAM
 963 -----------------------------------------------------------
 964 device set up (up to 16 devices - includes controller)
 965
 966 0f 00 08 08 64 00 0a 00 - id 0
 967 0f 00 08 08 64 00 0a 00
 968 0f 00 08 08 64 00 0a 00
 969 0f 00 08 08 64 00 0a 00
 970 0f 00 08 08 64 00 0a 00
 971 0f 00 08 08 64 00 0a 00
 972 0f 00 08 08 64 00 0a 00
 973 0f 00 08 08 64 00 0a 00
 974
 975 0f 00 08 08 64 00 0a 00
 976 0f 00 08 08 64 00 0a 00
 977 0f 00 08 08 64 00 0a 00
 978 0f 00 08 08 64 00 0a 00
 979 0f 00 08 08 64 00 0a 00
 980 0f 00 08 08 64 00 0a 00
 981 0f 00 08 08 64 00 0a 00
 982 0f 00 08 08 64 00 0a 00 - id 15
 983  |     |  |  |     |  |
 984  |     |  |  |      ----timeout (lsb/msb)
 985  |     |  |   --synch period (0x?? 40 Mtrans/sec- fast 40) (probably 0x28)
 986  |     |  |                  (0x30 20 Mtrans/sec- fast 20)
 987  |     |  |                  (0x64 10 Mtrans/sec- fast )
 988  |     |  |                  (0xc8  5 Mtrans/sec)
 989  |     |  |                  (0x00  asynchronous)
 990  |     |   -- ?? max sync offset (0x08 in NVRAM on 53c810a)
 991  |     |                         (0x10 in NVRAM on 53c875)
 992  |      --device bus width (0x08 narrow)
 993  |                         (0x10 16 bit wide)
 994   --flag bits
 995     0x00000001 - disconnect enabled
 996     0x00000010 - scan at boot time
 997     0x00000100 - scan luns
 998     0x00001000 - queue tags enabled
 999
1000 remaining bytes unknown - they do not appear to change in my
1001 current set up
1002
1003 ?? use of this data is a guess but seems reasonable
1004 (but it could be max bus width)
1005
1006 default set up for 53c810a NVRAM
1007 default set up for 53c875 NVRAM - bus width     - 0x10
1008                                 - sync offset ? - 0x10
1009                                 - sync period   - 0x30
1010 -----------------------------------------------------------
1011 ?? spare device space (32 bit bus ??)
1012
1013 00 00 00 00 00 00 00 00  (19x8bytes)
1014 .
1015 .
1016 00 00 00 00 00 00 00 00
1017
1018 default set up is identical for 53c810a and 53c875 NVRAM
1019 -----------------------------------------------------------
1020 trailer
1021
1022 fe fe   - ? end marker ?
1023 00 00
1024 00 00
1025
1026 default set up is identical for 53c810a and 53c875 NVRAM
1027 -----------------------------------------------------------
1028
1029
1030
1031 17.3 Tekram NVRAM layout
1032
1033 nvram 64x16 (1024 bit)
1034
1035 Drive settings
1036
1037 Drive ID 0-15 (addr 0x0yyyy0 = device setup, yyyy = ID)
1038               (addr 0x0yyyy1 = 0x0000)
1039
1040     x x x x  x x x x  x x x x  x x x x
1041                | | |      | |  | | | |
1042                | | |      | |  | | |  ----- parity check   0 - off
1043                | | |      | |  | | |                       1 - on
1044                | | |      | |  | | |
1045                | | |      | |  | |  ------- sync neg       0 - off
1046                | | |      | |  | |                         1 - on
1047                | | |      | |  | |
1048                | | |      | |  |  --------- disconnect     0 - off
1049                | | |      | |  |                           1 - on
1050                | | |      | |  |
1051                | | |      | |   ----------- start cmd      0 - off
1052                | | |      | |                              1 - on
1053                | | |      | |
1054                | | |      |  -------------- tagged cmds    0 - off
1055                | | |      |                                1 - on
1056                | | |      |
1057                | | |       ---------------- wide neg       0 - off
1058                | | |                                       1 - on
1059                | | |
1060                 --------------------------- sync rate      0 - 10.0 Mtrans/sec
1061                                                            1 -  8.0
1062                                                            2 -  6.6
1063                                                            3 -  5.7
1064                                                            4 -  5.0
1065                                                            5 -  4.0
1066                                                            6 -  3.0
1067                                                            7 -  2.0
1068                                                            7 -  2.0
1069                                                            8 - 20.0
1070                                                            9 - 16.7
1071                                                            a - 13.9
1072                                                            b - 11.9
1073
1074 Global settings
1075
1076 Host flags 0 (addr 0x100000, 32)
1077
1078     x x x x  x x x x  x x x x  x x x x
1079     | | | |  | | | |           | | | |
1080     | | | |  | | | |            ----------- host ID    0x00 - 0x0f
1081     | | | |  | | | |
1082     | | | |  | | |  ----------------------- support for    0 - off
1083     | | | |  | | |                          > 2 drives     1 - on
1084     | | | |  | | |
1085     | | | |  | |  ------------------------- support drives 0 - off
1086     | | | |  | |                            > 1Gbytes      1 - on
1087     | | | |  | |
1088     | | | |  |  --------------------------- bus reset on   0 - off
1089     | | | |  |                                power on     1 - on
1090     | | | |  |
1091     | | | |   ----------------------------- active neg     0 - off
1092     | | | |                                                1 - on
1093     | | | |
1094     | | |  -------------------------------- imm seek       0 - off
1095     | | |                                                  1 - on
1096     | | |
1097     | |  ---------------------------------- scan luns      0 - off
1098     | |                                                    1 - on
1099     | |
1100      -------------------------------------- removable      0 - disable
1101                                             as BIOS dev    1 - boot device
1102                                                            2 - all
1103
1104 Host flags 1 (addr 0x100001, 33)
1105
1106     x x x x  x x x x  x x x x  x x x x
1107                | | |             | | |
1108                | | |              --------- boot delay     0 -   3 sec
1109                | | |                                       1 -   5
1110                | | |                                       2 -  10
1111                | | |                                       3 -  20
1112                | | |                                       4 -  30
1113                | | |                                       5 -  60
1114                | | |                                       6 - 120
1115                | | |
1116                 --------------------------- max tag cmds   0 -  2
1117                                                            1 -  4
1118                                                            2 -  8
1119                                                            3 - 16
1120                                                            4 - 32
1121
1122 Host flags 2 (addr 0x100010, 34)
1123
1124     x x x x  x x x x  x x x x  x x x x
1125                                      |
1126                                       ----- F2/F6 enable   0 - off ???
1127                                                            1 - on  ???
1128
1129 checksum (addr 0x111111)
1130
1131 checksum = 0x1234 - (sum addr 0-63)
1132
1133 ----------------------------------------------------------------------------
1134
1135 default nvram data:
1136
1137 0x0037 0x0000 0x0037 0x0000 0x0037 0x0000 0x0037 0x0000
1138 0x0037 0x0000 0x0037 0x0000 0x0037 0x0000 0x0037 0x0000
1139 0x0037 0x0000 0x0037 0x0000 0x0037 0x0000 0x0037 0x0000
1140 0x0037 0x0000 0x0037 0x0000 0x0037 0x0000 0x0037 0x0000
1141
1142 0x0f07 0x0400 0x0001 0x0000 0x0000 0x0000 0x0000 0x0000
1143 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000
1144 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000
1145 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0xfbbc
1146
1147
1148 ===============================================================================
1149 End of Linux SYM-2 driver documentation file