1The Linux SYM-2 driver documentation file
2
3Written by Gerard Roudier <groudier@free.fr>
421 Rue Carnot
595170 DEUIL LA BARRE - FRANCE
6
7Decembre 28 2000
8===============================================================================
9
101.  Introduction
112.  Supported chips and SCSI features
123.  Advantages of this driver for newer chips.
13      3.1 Optimized SCSI SCRIPTS
14      3.2 New features appeared with the SYM53C896
154.  Memory mapped I/O versus normal I/O
165.  Tagged command queueing
176.  Parity checking
187.  Profiling information
198.  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
289.  Configuration parameters
2910. 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
5211. SCSI problem troubleshooting
53      15.1 Problem tracking
54      15.2 Understanding hardware error reports
5512. 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
621. Introduction
63
64This driver supports the whole SYM53C8XX family of PCI-SCSI controllers.
65It also support the subset of LSI53C10XX PCI-SCSI controllers that are based
66on the SYM53C8XX SCRIPTS language.
67
68It replaces the sym53c8xx+ncr53c8xx driver bundle and shares its core code
69with the FreeBSD SYM-2 driver. The `glue' that allows this driver to work
70under Linux is contained in 2 files named sym_glue.h and sym_glue.c.
71Other drivers files are intended not to depend on the Operating System
72on which the driver is used.
73
74The history of this driver can be summerized as follows:
75
761993: ncr driver written for 386bsd and FreeBSD by:
77          Wolfgang Stanglmeier        <wolf@cologne.de>
78          Stefan Esser                <se@mi.Uni-Koeln.de>
79
801996: port of the ncr driver to Linux-1.2.13 and rename it ncr53c8xx.
81          Gerard Roudier
82
831998: 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
871999: 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
912000: 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
97This README file addresses the Linux version of the driver. Under FreeBSD,
98the driver documentation is the sym.8 man page.
99
100Information about new chips is available at LSILOGIC web server:
101
102          http://www.lsilogic.com/
103
104SCSI standard documentations are available at T10 site:
105
106          http://www.t10.org/
107
108Useful SCSI tools written by Eric Youngdale are part of most Linux
109distributions:
110   scsiinfo:    command line tool
111   scsi-config: TCL/Tk tool using scsiinfo
112
1132. Supported chips and SCSI features
114
115The 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
123Other features depends on chip capabilities.
124The driver notably uses optimized SCRIPTS for devices that support
125LOAD/STORE and handles PHASE MISMATCH from SCRIPTS for devices that
126support the corresponding feature.
127
128The following table shows some characteristics of the chip family.
129
130       On board                                   LOAD/STORE   HARDWARE
131Chip   SDMS BIOS   Wide   SCSI std.   Max. sync   SCRIPTS      PHASE MISMATCH
132----   ---------   ----   ---------   ----------  ----------   --------------
133810        N         N      FAST10    10 MB/s        N             N
134810A       N         N      FAST10    10 MB/s        Y             N
135815        Y         N      FAST10    10 MB/s        N             N
136825        Y         Y      FAST10    20 MB/s        N             N
137825A       Y         Y      FAST10    20 MB/s        Y             N
138860        N         N      FAST20    20 MB/s        Y             N
139875        Y         Y      FAST20    40 MB/s        Y             N
140875A       Y         Y      FAST20    40 MB/s        Y             Y
141876        Y         Y      FAST20    40 MB/s        Y             N
142895        Y         Y      FAST40    80 MB/s        Y             N
143895A       Y         Y      FAST40    80 MB/s        Y             Y
144896        Y         Y      FAST40    80 MB/s        Y             Y
145897        Y         Y      FAST40    80 MB/s        Y             Y
1461510D      Y         Y      FAST40    80 MB/s        Y             Y
1471010       Y         Y      FAST80   160 MB/s        Y             Y
1481010_66*   Y         Y      FAST80   160 MB/s        Y             Y
149
150* Chip supports 33MHz and 66MHz PCI bus clock.
151
152
153Summary of other supported features:
154
155Module:                allow to load the driver
156Memory mapped I/O:     increases performance
157Control commands:      write operations to the proc SCSI file system
158Debugging information: written to syslog (expert only)
159Scatter / gather
160Shared interrupt
161Boot setup commands
162Serial NVRAM:          Symbios and Tekram formats
163
164
1653. Advantages of this driver for newer chips.
166
1673.1 Optimized SCSI SCRIPTS.
168
169All chips except the 810, 815 and 825, support new SCSI SCRIPTS instructions
170named LOAD and STORE that allow to move up to 1 DWORD from/to an IO register
171to/from memory much faster that the MOVE MEMORY instruction that is supported
172by the 53c7xx and 53c8xx family.
173
174The LOAD/STORE instructions support absolute and DSA relative addressing
175modes. The SCSI SCRIPTS had been entirely rewritten using LOAD/STORE instead
176of MOVE MEMORY instructions.
177
178Due to the lack of LOAD/STORE SCRIPTS instructions by earlier chips, this
179driver also incorporates a different SCRIPTS set based on MEMORY MOVE, in
180order to provide support for the entire SYM53C8XX chips family.
181
1823.2 New features appeared with the SYM53C896
183
184Newer chips (see above) allows handling of the phase mismatch context from
185SCRIPTS (avoids the phase mismatch interrupt that stops the SCSI processor
186until the C code has saved the context of the transfer).
187
188The 896 and 1010 chips support 64 bit PCI transactions and addressing,
189while the 895A supports 32 bit PCI transactions and 64 bit addressing.
190The SCRIPTS processor of these chips is not true 64 bit, but uses segment
191registers for bit 32-63. Another interesting feature is that LOAD/STORE
192instructions that address the on-chip RAM (8k) remain internal to the chip.
193
1944. Memory mapped I/O versus normal I/O
195
196Memory mapped I/O has less latency than normal I/O and is the recommended
197way for doing IO with PCI devices. Memory mapped I/O seems to work fine on
198most hardware configurations, but some poorly designed chipsets may break
199this feature. A configuration option is provided for normal I/O to be
200used but the driver defaults to MMIO.
201
2025. Tagged command queueing
203
204Queuing more than 1 command at a time to a device allows it to perform
205optimizations based on actual head positions and its mechanical
206characteristics. This feature may also reduce average command latency.
207In order to really gain advantage of this feature, devices must have
208a reasonnable cache size (No miracle is to be expected for a low-end
209hard disk with 128 KB or less).
210Some kown old SCSI devices do not properly support tagged command queuing.
211Generally, firmware revisions that fix this kind of problems are available
212at respective vendor web/ftp sites.
213All I can say is that I never have had problem with tagged queuing using
214this driver and its predecessors. Hard disks that behaved correctly for
215me 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
227If your controller has NVRAM, you can configure this feature per target
228from the user setup tool. The Tekram Setup program allows to tune the
229maximum number of queued commands up to 32. The Symbios Setup only allows
230to enable or disable this feature.
231
232The maximum number of simultaneous tagged commands queued to a device
233is currently set to 16 by default.  This value is suitable for most SCSI
234disks.  With large SCSI disks (>= 2GB, cache >= 512KB, average seek time
235<= 10 ms), using a larger value may give better performances.
236
237This driver supports up to 255 commands per device, and but using more than
23864 is generally not worth-while, unless you are using a very large disk or
239disk arrays. It is noticeable that most of recent hard disks seem not to
240accept more than 64 simultaneous commands. So, using more than 64 queued
241commands is probably just resource wasting.
242
243If your controller does not have NVRAM or if it is managed by the SDMS
244BIOS/SETUP, you can configure tagged queueing feature and device queue
245depths from the boot command-line. For example:
246
247  sym53c8xx=tags:4/t2t3q15-t4q7/t1u0q32
248
249will 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
257In some special conditions, some SCSI disk firmwares may return a
258QUEUE FULL status for a SCSI command. This behaviour is managed by the
259driver 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
267Since QUEUE FULL status reception and handling is resource wasting, the
268driver notifies by default this problem to user by indicating the actual
269number of commands used and their status, as well as its decision on the
270device queue depth change.
271The heuristic used by the driver in handling QUEUE FULL ensures that the
272impact on performances is not too bad. You can get rid of the messages by
273setting verbose level to zero, as follow:
274
2751st method: boot your system using 'sym53c8xx=verb:0' option.
2762nd method: apply "setverbose 0" control command to the proc fs entry
277            corresponding to your controller after boot-up.
278
2796. Parity checking
280
281The driver supports SCSI parity checking and PCI bus master parity
282checking. These features must be enabled in order to ensure safe data
283transfers. However, some flawed devices or mother boards will have
284problems with parity. You can disable either PCI parity or SCSI parity
285checking by entering appropriate options from the boot command line.
286(See 10: Boot setup commands).
287
2887. Profiling information
289
290This driver does not provide profiling informations as did its predecessors.
291This feature was not this useful and added complexity to the code.
292As the driver code got more complex, I have decided to remove everything
293that didn't seem actually useful.
294
2958. Control commands
296
297Control commands can be sent to the driver with write operations to
298the proc SCSI file system. The generic command syntax is the
299following:
300
301      echo "<verb> <parameters>" >/proc/scsi/sym53c8xx/0
302      (assumes controller number is 0)
303
304Using "all" for "<target>" parameter with the commands below will
305apply to all targets of the SCSI chain (except the controller).
306
307Available commands:
308
3098.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
3258.2 Set wide size
326
327    setwide <target> <size>
328
329    target:    target number
330    size:      0=8 bits, 1=16bits
331
3328.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
3408.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
3588.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
3758.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
3828.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
3898.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
3989. Configuration parameters
399
400Under kernel configuration tools (make menuconfig, for example), it is
401possible to change some default driver configuration parameters.
402If the firmware of all your devices is perfect enough, all the
403features supported by the driver can be enabled at start-up. However,
404if only one has a flaw for some SCSI feature, you can disable the
405support by the driver of this feature at linux start-up and enable
406this feature after boot-up only for devices that support it safely.
407
408Configuration parameters:
409
410Use 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
414Default 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
418Maximum 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
422Synchronous 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
42710. Boot setup commands
428
42910.1 Syntax
430
431Setup commands can be passed to the driver either at boot time or as a
432string variable using 'insmod'.
433
434A boot setup command for this driver begins with the driver name "sym53c8xx=".
435The kernel syntax parser then expects an optionnal list of integers separated
436with comma followed by an optional list of  comma-separated strings.
437
438Example of boot setup command under lilo prompt:
439
440lilo: 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
446Since comma seems not to be allowed when defining a string variable using
447'insmod', the driver also accepts <space> as option separator.
448The following command will install driver module with the same options as
449above.
450
451    insmod sym53c8xx.o sym53c8xx="tags:4 sync:10 debug:0x200"
452
453The integer list of arguments is discarded by the driver.
454
455Each string argument must be specified as "keyword:value". Only lower-case
456characters and digits are allowed.
457
45810.2 Available arguments
459
46010.2.1  Master parity checking
461        mpar:y     enabled
462        mpar:n     disabled
463
46410.2.2  Scsi parity checking
465        spar:y     enabled
466        spar:n     disabled
467
46810.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
48210.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
49410.2.5  Verbosity level
495        verb:0     minimal
496        verb:1     normal
497        verb:2     too much
498
49910.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
52010.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
52710.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
53310.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
54110.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
54710.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
55210.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
55810.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
56610.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        mvram=<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
57710.2.15 Check SCSI BUS
578        buschk:<option bits>
579
580    Available option bits:
581        0x0:   No check.
582        0x1:   Check and donnot attach the controller on error.
583        0x2:   Check and just warn on error.
584
58510.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
59210.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
60210.3 PCI configuration fix-up boot option
603
604pcifix:<option bits>
605
606Available 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
610Use 'pcifix:3' in order to allow the driver to fix both PCI features.
611
612Recent SYMBIOS 53C8XX scsi processors are able to use PCI read multiple
613and PCI write and invalidate commands. These features require the
614cache line size register to be properly set in the PCI configuration
615space of the chips. On the other hand, chips will use PCI write and
616invalidate commands only if the corresponding bit is set to 1 in the
617PCI command register.
618
619Not all PCI bioses set the PCI cache line register and the PCI write and
620invalidate bit in the PCI configuration space of 53C8XX chips.
621Optimized PCI accesses may be broken for some PCI/memory controllers or
622make problems with some PCI boards.
623
62410.4 Serial NVRAM support boot option
625
626nvram:n     do not look for serial NVRAM
627nvram:y     test controllers for onboard serial NVRAM
628
629This option can also been entered as an hexadecimal value that allows
630to control what information the driver will get from the NVRAM and what
631information it will ignore.
632For details see '17. Serial NVRAM support'.
633
634When this option is enabled, the driver tries to detect all boards using
635a Serial NVRAM. This memory is used to hold user set up parameters.
636
637The parameters the driver is able to get from the NVRAM depend on the
638data format used, as follow:
639
640                                 Tekram format      Symbios format
641General 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
646SCSI 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
653In order to speed up the system boot, for each device configured without
654the "scan at boot time" option, the driver forces an error on the
655first TEST UNIT READY command received for this device.
656
657Some SDMS BIOS revisions seem to be unable to boot cleanly with very fast
658hard disks. In such a situation you cannot configure the NVRAM with
659optimized parameters value.
660
661The 'nvram' boot option can be entered in hexadecimal form in order
662to ignore some options configured in the NVRAM, as follow:
663
664mvram=<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
671Option 0x80 is disabled by default.
672Result is that, by default (option not set), the sym53c8xx driver will not
673attach controllers set to OFF in the NVRAM.
674
67510.5 SCSI BUS checking boot option.
676
677When this option is set to a non-zero value, the driver checks SCSI lines
678logic state, 100 micro-seconds after having asserted the SCSI RESET line.
679The driver just reads SCSI lines and checks all lines read FALSE except RESET.
680Since SCSI devices shall release the BUS at most 800 nano-seconds after SCSI
681RESET has been asserted, any signal to TRUE may indicate a SCSI BUS problem.
682Unfortunately, the following common SCSI BUS problems are not detected:
683- Only 1 terminator installed.
684- Misplaced terminators.
685- Bad quality terminators.
686On the other hand, either bad cabling, broken devices, not conformant
687devices, ... may cause a SCSI signal to be wrong when te driver reads it.
688
68915. SCSI problem troubleshooting
690
69115.1 Problem tracking
692
693Most SCSI problems are due to a non conformant SCSI bus or too buggy
694devices.  If infortunately you have SCSI problems, you can check the
695following 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
701If you donnot find the source of problems, you can configure the
702driver or devices in the NVRAM with minimal features.
703
704- only asynchronous data transfers
705- tagged commands disabled
706- disconnections not allowed
707
708Now, if your SCSI bus is ok, your system has every chance to work
709with this safe configuration but performances will not be optimal.
710
711If it still fails, then you can send your problem description to
712appropriate mailing lists or news-groups.  Send me a copy in order to
713be sure I will receive it.  Obviously, a bug in the driver code is
714possible.
715
716  My cyrrent email address: Gerard Roudier <groudier@free.fr>
717
718Allowing disconnections is important if you use several devices on
719your SCSI bus but often causes problems with buggy devices.
720Synchronous data transfers increases throughput of fast devices like
721hard disks.  Good SCSI hard disks with a large cache gain advantage of
722tagged commands queuing.
723
72415.2 Understanding hardware error reports
725
726When the driver detects an unexpected error condition, it may display a
727message of the following pattern.
728
729sym0:1: ERROR (0:48) (1-21-65) (f/95/0) @ (script 7c0:19000000).
730sym0: script cmd = 19000000
731sym0: regdump: da 10 80 95 47 0f 01 07 75 01 81 21 80 01 09 00.
732
733Some fields in such a message may help you understand the cause of the
734problem, as follows:
735
736sym0: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
739Field A : target number.
740  SCSI ID of the device the controller was talking with at the moment the
741  error occurs.
742
743Field 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
756Field 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 functionning
760             properly.
761  Bit 0x04 : UDC  Undexpected 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 occured.
765  Bit 0x02 : RST  SCSI BUS Reset
766             Generally SCSI targets donnot 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
775For fields D,E,F,G and H, you may look into the sym53c8xx_defs.h file
776that contains some minimal comments on IO register bits.
777Field 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.
780Field E : SBCL  Scsi Bus Control Lines
781          Actual value of control lines on the SCSI BUS.
782Field F : SBDL  Scsi Bus Data Lines
783          Actual value of data lines on the SCSI BUS.
784Field G : SXFER  SCSI Transfer
785          Contains the setting of the Synchronous Period for output and
786          the current Synchronous offset (offset 0 means asynchronous).
787Field H : SCNTL3 Scsi Control Register 3
788          Contains the setting of timing values for both asynchronous and
789          synchronous data transfers.
790Field I : SCNTL4 Scsi Control Register 4
791          Only meaninful for 53C1010 Ultra3 controllers.
792
793Understanding Fields J, K, L and dumps requires to have good knowledge of
794SCSI standards, chip cores functionnals and internal driver data structures.
795You are not required to decode and understand them, unless you want to help
796maintain the driver code.
797
79817. Serial NVRAM (added by Richard Waltham: dormouse@farsrobt.demon.co.uk)
799
80017.1 Features
801
802Enabling serial NVRAM support enables detection of the serial NVRAM included
803on Symbios and some Symbios compatible host adaptors, and Tekram boards. The
804serial NVRAM is used by Symbios and Tekram to hold set up parameters for the
805host adaptor and it's attached drives.
806
807The Symbios NVRAM also holds data on the boot order of host adaptors in a
808system with more than one host adaptor. This enables the order of scanning
809the cards for drives to be changed from the default used during host adaptor
810detection.
811
812This can be done to a limited extent at the moment using "reverse probe" but
813this only changes the order of detection of different types of cards. The
814NVRAM boot order settings can do this as well as change the order the same
815types of cards are scanned in, something "reverse probe" cannot do.
816
817Tekram boards using Symbios chips, DC390W/F/U, which have NVRAM are detected
818and this is used to distinguish between Symbios compatible and Tekram host
819adaptors. This is used to disable the Symbios compatible "diff" setting
820incorrectly set on Tekram boards if the CONFIG_SCSI_53C8XX_SYMBIOS_COMPAT
821configuration parameter is set enabling both Symbios and Tekram boards to be
822used together with the Symbios cards using all their features, including
823"diff" support. ("led pin" support for Symbios compatible cards can remain
824enabled when using Tekram cards. It does nothing useful for Tekram host
825adaptors but does not cause problems either.)
826
827
82817.2 Symbios NVRAM layout
829
830typical data at NVRAM address 0x100 (53c810a NVRAM)
831-----------------------------------------------------------
83200 00
83364 01
8348e 0b
835
83600 30 00 00 00 00 07 00 00 00 00 00 00 00 07 04 10 04 00 00
837
83804 00 0f 00 00 10 00 50 00 00 01 00 00 62
83904 00 03 00 00 10 00 58 00 00 01 00 00 63
84004 00 01 00 00 10 00 48 00 00 01 00 00 61
84100 00 00 00 00 00 00 00 00 00 00 00 00 00
842
8430f 00 08 08 64 00 0a 00
8440f 00 08 08 64 00 0a 00
8450f 00 08 08 64 00 0a 00
8460f 00 08 08 64 00 0a 00
8470f 00 08 08 64 00 0a 00
8480f 00 08 08 64 00 0a 00
8490f 00 08 08 64 00 0a 00
8500f 00 08 08 64 00 0a 00
851
8520f 00 08 08 64 00 0a 00
8530f 00 08 08 64 00 0a 00
8540f 00 08 08 64 00 0a 00
8550f 00 08 08 64 00 0a 00
8560f 00 08 08 64 00 0a 00
8570f 00 08 08 64 00 0a 00
8580f 00 08 08 64 00 0a 00
8590f 00 08 08 64 00 0a 00
860
86100 00 00 00 00 00 00 00
86200 00 00 00 00 00 00 00
86300 00 00 00 00 00 00 00
86400 00 00 00 00 00 00 00
86500 00 00 00 00 00 00 00
86600 00 00 00 00 00 00 00
86700 00 00 00 00 00 00 00
86800 00 00 00 00 00 00 00
869
87000 00 00 00 00 00 00 00
87100 00 00 00 00 00 00 00
87200 00 00 00 00 00 00 00
87300 00 00 00 00 00 00 00
87400 00 00 00 00 00 00 00
87500 00 00 00 00 00 00 00
87600 00 00 00 00 00 00 00
87700 00 00 00 00 00 00 00
878
87900 00 00 00 00 00 00 00
88000 00 00 00 00 00 00 00
88100 00 00 00 00 00 00 00
882
883fe fe
88400 00
88500 00
886-----------------------------------------------------------
887NVRAM layout details
888
889NVRAM Address 0x000-0x0ff not used
890              0x100-0x26f initialised data
891              0x270-0x7ff not used
892
893general 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
901data 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-----------------------------------------------------------
911header
912
91300 00   - ?? start marker
91464 01   - byte count (lsb/msb excludes header/trailer)
9158e 0b   - checksum (lsb/msb excludes header/trailer)
916-----------------------------------------------------------
917controller set up
918
91900 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
936remaining bytes unknown - they do not appear to change in my
937current set up for any of the controllers.
938
939default set up is identical for 53c810a and 53c875 NVRAM
940(Removable Media added Symbios BIOS version 4.09)
941-----------------------------------------------------------
942boot configuration
943
944boot order set by order of the devices in this table
945
94604 00 0f 00 00 10 00 50 00 00 01 00 00 62 -- 1st controller
94704 00 03 00 00 10 00 58 00 00 01 00 00 63    2nd controller
94804 00 01 00 00 10 00 48 00 00 01 00 00 61    3rd controller
94900 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
959remaining bytes unknown - they do not appear to change in my
960current set up
961
962default set up is identical for 53c810a and 53c875 NVRAM
963-----------------------------------------------------------
964device set up (up to 16 devices - includes controller)
965
9660f 00 08 08 64 00 0a 00 - id 0
9670f 00 08 08 64 00 0a 00
9680f 00 08 08 64 00 0a 00
9690f 00 08 08 64 00 0a 00
9700f 00 08 08 64 00 0a 00
9710f 00 08 08 64 00 0a 00
9720f 00 08 08 64 00 0a 00
9730f 00 08 08 64 00 0a 00
974
9750f 00 08 08 64 00 0a 00
9760f 00 08 08 64 00 0a 00
9770f 00 08 08 64 00 0a 00
9780f 00 08 08 64 00 0a 00
9790f 00 08 08 64 00 0a 00
9800f 00 08 08 64 00 0a 00
9810f 00 08 08 64 00 0a 00
9820f 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
1000remaining bytes unknown - they do not appear to change in my
1001current set up
1002
1003?? use of this data is a guess but seems reasonable
1004(but it could be max bus width)
1005
1006default set up for 53c810a NVRAM
1007default 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
101300 00 00 00 00 00 00 00  (19x8bytes)
1014.
1015.
101600 00 00 00 00 00 00 00
1017
1018default set up is identical for 53c810a and 53c875 NVRAM
1019-----------------------------------------------------------
1020trailer
1021
1022fe fe   - ? end marker ?
102300 00
102400 00
1025
1026default set up is identical for 53c810a and 53c875 NVRAM
1027-----------------------------------------------------------
1028
1029
1030
103117.3 Tekram NVRAM layout
1032
1033nvram 64x16 (1024 bit)
1034
1035Drive settings
1036
1037Drive 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
1074Global settings
1075
1076Host 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
1104Host 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
1122Host 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
1129checksum (addr 0x111111)
1130
1131checksum = 0x1234 - (sum addr 0-63)
1132
1133----------------------------------------------------------------------------
1134
1135default nvram data:
1136
11370x0037 0x0000 0x0037 0x0000 0x0037 0x0000 0x0037 0x0000
11380x0037 0x0000 0x0037 0x0000 0x0037 0x0000 0x0037 0x0000
11390x0037 0x0000 0x0037 0x0000 0x0037 0x0000 0x0037 0x0000
11400x0037 0x0000 0x0037 0x0000 0x0037 0x0000 0x0037 0x0000
1141
11420x0f07 0x0400 0x0001 0x0000 0x0000 0x0000 0x0000 0x0000
11430x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000
11440x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000
11450x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0xfbbc
1146
1147
1148===============================================================================
1149End of Linux SYM-2 driver documentation file
1150