documentation.txt

内核linux2.4.20,可跟rtlinux3.2打补丁 组成实时linux系统,编译内核

    target:    target number
    The driver will try to send a BUS DEVICE RESET message to the target.

8.8 Abort all tasks of all logical units of a target

    cleardev <target>

    target:    target number
    The driver will try to send a ABORT message to all the logical units 
    of the target.


9. Configuration parameters

Under kernel configuration tools (make menuconfig, for example), it is 
possible to change some default driver configuration parameters.
If the firmware of all your devices is perfect enough, all the
features supported by the driver can be enabled at start-up. However,
if only one has a flaw for some SCSI feature, you can disable the
support by the driver of this feature at linux start-up and enable
this feature after boot-up only for devices that support it safely.

Configuration parameters:

Use normal IO                         (default answer: n)
    Answer "y" if you suspect your mother board to not allow memory mapped I/O.
    May slow down performance a little.

Default tagged command queue depth    (default answer: 16)
    Entering 0 defaults to tagged commands not being used.
    This parameter can be specified from the boot command line.

Maximum number of queued commands     (default answer: 32)
    This option allows you to specify the maximum number of tagged commands 
    that can be queued to a device. The maximum supported value is 255.

Synchronous transfers frequency       (default answer: 80)
    This option allows you to specify the frequency in MHz the driver 
    will use at boot time for synchronous data transfer negotiations.
    0 means "asynchronous data transfers".

10. Boot setup commands

10.1 Syntax

Setup commands can be passed to the driver either at boot time or as a 
string variable using 'insmod'.

A boot setup command for this driver begins with the driver name "sym53c8xx=".
The kernel syntax parser then expects an optionnal list of integers separated 
with comma followed by an optional list of  comma-separated strings.

Example of boot setup command under lilo prompt:

lilo: linux root=/dev/sda2 sym53c8xx=tags:4,sync:10,debug:0x200

- enable tagged commands, up to 4 tagged commands queued.
- set synchronous negotiation speed to 10 Mega-transfers / second.
- set DEBUG_NEGO flag.

Since comma seems not to be allowed when defining a string variable using  
'insmod', the driver also accepts <space> as option separator. 
The following command will install driver module with the same options as 
above.

    insmod sym53c8xx.o sym53c8xx="tags:4 sync:10 debug:0x200"

The integer list of arguments is discarded by the driver. 

Each string argument must be specified as "keyword:value". Only lower-case 
characters and digits are allowed.

10.2 Available arguments

10.2.1  Master parity checking
        mpar:y     enabled
        mpar:n     disabled

10.2.2  Scsi parity checking
        spar:y     enabled
        spar:n     disabled

10.2.3  Default number of tagged commands
        tags:0     (or tags:1 ) tagged command queuing disabled
        tags:#tags (#tags  > 1) tagged command queuing enabled
  #tags will be truncated to the max queued commands configuration parameter.
  This option also allows to specify a command queue depth for each device 
  that support tagged command queueing.
  Example:
      sym53c8xx=tags:10/t2t3q16-t5q24/t1u2q32
               will set devices queue depth as follow:
      - controller #0 target #2 and target #3                  -> 16 commands,
      - controller #0 target #5                                -> 24 commands,
      - controller #1 target #1 logical unit #2                -> 32 commands,
      - all other logical units (all targets, all controllers) -> 10 commands.

10.2.4  Default synchronous period factor
        sync:255     disabled (asynchronous transfer mode)
        sync:#factor
  #factor =  9     Ultra-3 SCSI 80 Mega-transfers / second (Wide only)
  #factor = 10     Ultra-2 SCSI 40 Mega-transfers / second
  #factor = 11     Ultra-2 SCSI 33 Mega-transfers / second
  #factor < 25     Ultra   SCSI 20 Mega-transfers / second
  #factor < 50     Fast    SCSI-2

  In all cases, the driver will use the minimum transfer period supported by 
  controllers according to SYM53C8XX chip type.

10.2.5  Verbosity level
        verb:0     minimal
        verb:1     normal
        verb:2     too much

10.2.6 Debug mode
        debug:0	 clear debug flags
        debug:#x   set debug flags
  #x is an integer value combining the following power-of-2 values:
  DEBUG_ALLOC       0x1
  DEBUG_PHASE       0x2
  DEBUG_POLL        0x4
  DEBUG_QUEUE       0x8
  DEBUG_RESULT     0x10
  DEBUG_SCATTER    0x20
  DEBUG_SCRIPT     0x40
  DEBUG_TINY       0x80
  DEBUG_TIMING    0x100
  DEBUG_NEGO      0x200
  DEBUG_TAGS      0x400
  DEBUG_FREEZE    0x800
  DEBUG_RESTART  0x1000

  You can play safely with DEBUG_NEGO. However, some of these flags may 
  generate bunches of syslog messages. 

10.2.7 Burst max
        burst:0    burst disabled
        burst:255  get burst length from initial IO register settings.
        burst:#x   burst enabled (1<<#x burst transfers max)
  #x is an integer value which is log base 2 of the burst transfers max.
  By default the driver uses the maximum value supported by the chip.

10.2.8 LED support
        led:1      enable  LED support
        led:0      disable LED support
  Donnot enable LED support if your scsi board does not use SDMS BIOS.
  (See 'Configuration parameters')

10.2.9 Max wide
        wide:1      wide scsi enabled
        wide:0      wide scsi disabled
  Some scsi boards use a 875 (ultra wide) and only supply narrow connectors.
  If you have connected a wide device with a 50 pins to 68 pins cable 
  converter, any accepted wide negotiation will break further data transfers.
  In such a case, using "wide:0" in the bootup command will be helpfull. 

10.2.10 Differential mode
        diff:0	never set up diff mode
        diff:1	set up diff mode if BIOS set it
        diff:2	always set up diff mode
        diff:3	set diff mode if GPIO3 is not set

10.2.11 IRQ mode
        irqm:0     always open drain
        irqm:1     same as initial settings (assumed BIOS settings)
        irqm:2     always totem pole

10.2.12 Reverse probe
        revprob:n   probe chip ids from the PCI configuration in this order:
                    810, 815, 825, 860, 875, 885, 875A, 895, 896, 895A,
                    1510D, 1010-33, 1010-66.
        revprob:y   probe chip ids in the reverse order.

10.2.13 Fix up PCI configuration space
        pcifix:<option bits>

    Available option bits:
        0x0:   No attempt to fix PCI configuration space registers values.
        0x1:   Set PCI cache-line size register if not set.
        0x2:   Set write and invalidate bit in PCI command register.

10.2.14 Serial NVRAM
        nvram:n     do not look for serial NVRAM
        nvram:y     test controllers for onboard serial NVRAM
        (alternate binary form)
        mvram=<bits options>
        0x01   look for NVRAM  (equivalent to nvram=y)
        0x02   ignore NVRAM "Synchronous negotiation" parameters for all devices
        0x04   ignore NVRAM "Wide negotiation"  parameter for all devices
        0x08   ignore NVRAM "Scan at boot time" parameter for all devices
        0x80   also attach controllers set to OFF in the NVRAM (sym53c8xx only)

10.2.15 Check SCSI BUS 
        buschk:<option bits>

    Available option bits:
        0x0:   No check.
        0x1:   Check and donnot attach the controller on error.  
        0x2:   Check and just warn on error.

10.2.16 Exclude a host from being attached
        excl=<io_address>

    Prevent host at a given io address from being attached.
    For example 'sym53c8xx=excl:0xb400,excl:0xc000' indicate to the 
    driver not to attach hosts at address 0xb400 and 0xc000.

10.2.17 Suggest a default SCSI id for hosts
        hostid:255	no id suggested.
        hostid:#x   (0 < x < 7) x suggested for hosts SCSI id.

    If a host SCSI id is available from the NVRAM, the driver will ignore 
    any value suggested as boot option. Otherwise, if a suggested value 
    different from 255 has been supplied, it will use it. Otherwise, it will 
    try to deduce the value previously set in the hardware and use value 
    7 if the hardware value is zero.

10.3 PCI configuration fix-up boot option

pcifix:<option bits>

Available option bits:
    0x1:     Set PCI cache-line size register if not set.
    0x2:     Set write and invalidate bit in PCI command register.

Use 'pcifix:3' in order to allow the driver to fix both PCI features.

Recent SYMBIOS 53C8XX scsi processors are able to use PCI read multiple 
and PCI write and invalidate commands. These features require the 
cache line size register to be properly set in the PCI configuration 
space of the chips. On the other hand, chips will use PCI write and 
invalidate commands only if the corresponding bit is set to 1 in the 
PCI command register.

Not all PCI bioses set the PCI cache line register and the PCI write and 
invalidate bit in the PCI configuration space of 53C8XX chips.
Optimized PCI accesses may be broken for some PCI/memory controllers or 
make problems with some PCI boards.

10.4 Serial NVRAM support boot option

nvram:n     do not look for serial NVRAM
nvram:y     test controllers for onboard serial NVRAM

This option can also been entered as an hexadecimal value that allows 
to control what information the driver will get from the NVRAM and what 
information it will ignore.
For details see '17. Serial NVRAM support'.

When this option is enabled, the driver tries to detect all boards using 
a Serial NVRAM. This memory is used to hold user set up parameters.

The parameters the driver is able to get from the NVRAM depend on the 
data format used, as follow:

                                 Tekram format      Symbios format
General and host parameters
    Boot order                         N                   Y
    Host SCSI ID                       Y                   Y
    SCSI parity checking               Y                   Y
    Verbose boot messages              N                   Y
SCSI devices parameters
    Synchronous transfer speed         Y                   Y
    Wide 16 / Narrow                   Y                   Y
    Tagged Command Queuing enabled     Y                   Y
    Disconnections enabled             Y                   Y
    Scan at boot time                  N                   Y

In order to speed up the system boot, for each device configured without 
the "scan at boot time" option, the driver forces an error on the 
first TEST UNIT READY command received for this device.

Some SDMS BIOS revisions seem to be unable to boot cleanly with very fast 
hard disks. In such a situation you cannot configure the NVRAM with 
optimized parameters value.

The 'nvram' boot option can be entered in hexadecimal form in order 
to ignore some options configured in the NVRAM, as follow:

mvram=<bits options>
      0x01   look for NVRAM  (equivalent to nvram=y)
      0x02   ignore NVRAM "Synchronous negotiation" parameters for all devices
      0x04   ignore NVRAM "Wide negotiation"  parameter for all devices
      0x08   ignore NVRAM "Scan at boot time" parameter for all devices
      0x80   also attach controllers set to OFF in the NVRAM (sym53c8xx only)

Option 0x80 is disabled by default.
Result is that, by default (option not set), the sym53c8xx driver will not 
attach controllers set to OFF in the NVRAM.

10.5 SCSI BUS checking boot option.

When this option is set to a non-zero value, the driver checks SCSI lines 
logic state, 100 micro-seconds after having asserted the SCSI RESET line.
The driver just reads SCSI lines and checks all lines read FALSE except RESET.
Since SCSI devices shall release the BUS at most 800 nano-seconds after SCSI 
RESET has been asserted, any signal to TRUE may indicate a SCSI BUS problem.
Unfortunately, the following common SCSI BUS problems are not detected:
- Only 1 terminator installed.
- Misplaced terminators.
- Bad quality terminators.
On the other hand, either bad cabling, broken devices, not conformant 
devices, ... may cause a SCSI signal to be wrong when te driver reads it.

15. SCSI problem troubleshooting

15.1 Problem tracking

Most SCSI problems are due to a non conformant SCSI bus or too buggy
devices.  If infortunately you have SCSI problems, you can check the
following things:

- SCSI bus cables
- terminations at both end of the SCSI chain
- linux syslog messages (some of them may help you)

If you donnot find the source of problems, you can configure the
driver or devices in the NVRAM with minimal features.

- only asynchronous data transfers
- tagged commands disabled
- disconnections not allowed

Now, if your SCSI bus is ok, your system has every chance to work
with this safe configuration but performances will not be optimal.

If it still fails, then you can send your problem description to
appropriate mailing lists or news-groups.  Send me a copy in order to
be sure I will receive it.  Obviously, a bug in the driver code is
possible.

  My cyrrent email address: Gerard Roudier <[e-mail]>

Allowing disconnections is important if you use several devices on
your SCSI bus but often causes problems with buggy devices.
Synchronous data transfers increases throughput of fast devices like
hard disks.  Good SCSI hard disks with a large cache gain advantage of
tagged commands queuing.

15.2 Understanding hardware error reports

When the driver detects an unexpected error condition, it may display a 
message of the following pattern.

sym0:1: ERROR (0:48) (1-21-65) (f/95/0) @ (script 7c0:19000000).
sym0: script cmd = 19000000
sym0: regdump: da 10 80 95 47 0f 01 07 75 01 81 21 80 01 09 00.

Some fields in such a message may help you understand the cause of the 
problem, as follows:

sym0:1: ERROR (0:48) (1-21-65) (f/95/0) @ (script 7c0:19000000).
.....A.........B.C....D.E..F....G.H..I.......J.....K...L.......

Field A : target number.
  SCSI ID of the device the controller was talking with at the moment the 
  error occurs.

Field B : DSTAT io register (DMA STATUS)
  Bit 0x40 : MDPE Master Data Parity Error
             Data parity error detected on the PCI BUS.
  Bit 0x20 : BF   Bus Fault
             PCI bus fault condition detected
  Bit 0x01 : IID  Illegal Instruction Detected
             Set by the chip when it detects an Illegal Instruction format 
             on some condition that makes an instruction illegal.
  Bit 0x80 : DFE Dma Fifo Empty
             Pure status bit that does not indicate an error.
  If the reported DSTAT value contains a combination of MDPE (0x40), 
  BF (0x20), then the cause may be likely due to a PCI BUS problem.

Field C : SIST io register (SCSI Interrupt Status)
  Bit 0x08 : SGE  SCSI GROSS ERROR
             Indicates that the chip detected a severe error condition 
             on the SCSI BUS that prevents the SCSI protocol from functionning
             properly.
  Bit 0x04 : UDC  Undexpected Disconnection
             Indicates that the device released the SCSI BUS when the chip 
             was not expecting this to happen. A device may behave so to 
             indicate the SCSI initiator that an error condition not reportable              using the SCSI protocol has occured.
  Bit 0x02 : RST  SCSI BUS Reset
             Generally SCSI targets donnot reset the SCSI BUS, although any 
             device on the BUS can reset it at any time.
  Bit 0x01 : PAR  Parity