documentation.txt

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

The Linux SYM-2 driver documentation file

Written by Gerard Roudier <[e-mail]>
21 Rue Carnot
95170 DEUIL LA BARRE - FRANCE

Decembre 28 2000
===============================================================================

1.  Introduction
2.  Supported chips and SCSI features
3.  Advantages of this driver for newer chips.
      3.1 Optimized SCSI SCRIPTS
      3.2 New features appeared with the SYM53C896
4.  Memory mapped I/O versus normal I/O
5.  Tagged command queueing
6.  Parity checking
7.  Profiling information
8.  Control commands
      8.1  Set minimum synchronous period
      8.2  Set wide size
      8.3  Set maximum number of concurrent tagged commands
      8.4  Set debug mode
      8.5  Set flag (no_disc)
      8.6  Set verbose level
      8.7  Reset all logical units of a target
      8.8  Abort all tasks of all logical units of a target
9.  Configuration parameters
10. Boot setup commands
      10.1 Syntax
      10.2 Available arguments
             10.2.1  Master parity checking
             10.2.2  Scsi parity checking
             10.2.3  Default number of tagged commands
             10.2.4  Default synchronous period factor
             10.2.5  Verbosity level
             10.2.6  Debug mode
             10.2.7  Burst max
             10.2.8  LED support
             10.2.9  Max wide
             10.2.10 Differential mode
             10.2.11 IRQ mode
             10.2.12 Reverse probe
             10.2.13 Fix up PCI configuration space
             10.2.14 Serial NVRAM
             10.2.15 Check SCSI BUS 
             10.2.16 Exclude a host from being attached
             10.2.17 Suggest a default SCSI id for hosts
      10.3 PCI configuration fix-up boot option
      10.4 Serial NVRAM support boot option
      10.5 SCSI BUS checking boot option
11. SCSI problem troubleshooting
      15.1 Problem tracking
      15.2 Understanding hardware error reports
12. Serial NVRAM support (by Richard Waltham)
      17.1 Features
      17.2 Symbios NVRAM layout
      17.3 Tekram  NVRAM layout

===============================================================================

1. Introduction

This driver supports the whole SYM53C8XX family of PCI-SCSI controllers.
It also support the subset of LSI53C10XX PCI-SCSI controllers that are based 
on the SYM53C8XX SCRIPTS language.

It replaces the sym53c8xx+ncr53c8xx driver bundle and shares its core code 
with the FreeBSD SYM-2 driver. The `glue' that allows this driver to work 
under Linux is contained in 2 files named sym_glue.h and sym_glue.c.
Other drivers files are intended not to depend on the Operating System 
on which the driver is used.

The history of this driver can be summerized as follows:

1993: ncr driver written for 386bsd and FreeBSD by:
          Wolfgang Stanglmeier        <[e-mail]>
          Stefan Esser                <[e-mail]>

1996: port of the ncr driver to Linux-1.2.13 and rename it ncr53c8xx.
          Gerard Roudier

1998: new sym53c8xx driver for Linux based on LOAD/STORE instruction and that 
      adds full support for the 896 but drops support for early NCR devices.
          Gerard Roudier

1999: port of the sym53c8xx driver to FreeBSD and support for the LSI53C1010 
      33 MHz and 66MHz Ultra-3 controllers. The new driver is named `sym'.
          Gerard Roudier

2000: Add support for early NCR devices to FreeBSD `sym' driver.
      Break the driver into several sources and separate the OS glue 
      code from the core code that can be shared among different O/Ses.
      Write a glue code for Linux.
          Gerard Roudier

This README file addresses the Linux version of the driver. Under FreeBSD, 
the driver documentation is the sym.8 man page.

Information about new chips is available at LSILOGIC web server:

          http://www.lsilogic.com/

SCSI standard documentations are available at T10 site:

          http://www.t10.org/

Useful SCSI tools written by Eric Youngdale are part of most Linux 
distributions:
   scsiinfo:    command line tool
   scsi-config: TCL/Tk tool using scsiinfo

2. Supported chips and SCSI features

The following features are supported for all chips:

	Synchronous negotiation
	Disconnection
	Tagged command queuing
	SCSI parity checking
	PCI Master parity checking

Other features depends on chip capabilities.
The driver notably uses optimized SCRIPTS for devices that support 
LOAD/STORE and handles PHASE MISMATCH from SCRIPTS for devices that 
support the corresponding feature.

The following table shows some characteristics of the chip family.

       On board                                   LOAD/STORE   HARDWARE
Chip   SDMS BIOS   Wide   SCSI std.   Max. sync   SCRIPTS      PHASE MISMATCH
----   ---------   ----   ---------   ----------  ----------   --------------
810        N         N      FAST10    10 MB/s        N             N
810A       N         N      FAST10    10 MB/s        Y             N
815        Y         N      FAST10    10 MB/s        N             N
825        Y         Y      FAST10    20 MB/s        N             N
825A       Y         Y      FAST10    20 MB/s        Y             N
860        N         N      FAST20    20 MB/s        Y             N
875        Y         Y      FAST20    40 MB/s        Y             N
875A       Y         Y      FAST20    40 MB/s        Y             Y
876        Y         Y      FAST20    40 MB/s        Y             N
895        Y         Y      FAST40    80 MB/s        Y             N
895A       Y         Y      FAST40    80 MB/s        Y             Y
896        Y         Y      FAST40    80 MB/s        Y             Y
897        Y         Y      FAST40    80 MB/s        Y             Y
1510D      Y         Y      FAST40    80 MB/s        Y             Y
1010       Y         Y      FAST80   160 MB/s        Y             Y
1010_66*   Y         Y      FAST80   160 MB/s        Y             Y

* Chip supports 33MHz and 66MHz PCI bus clock.


Summary of other supported features:

Module:                allow to load the driver
Memory mapped I/O:     increases performance
Control commands:      write operations to the proc SCSI file system
Debugging information: written to syslog (expert only)
Scatter / gather
Shared interrupt
Boot setup commands
Serial NVRAM:          Symbios and Tekram formats


3. Advantages of this driver for newer chips.

3.1 Optimized SCSI SCRIPTS.

All chips except the 810, 815 and 825, support new SCSI SCRIPTS instructions 
named LOAD and STORE that allow to move up to 1 DWORD from/to an IO register 
to/from memory much faster that the MOVE MEMORY instruction that is supported 
by the 53c7xx and 53c8xx family.

The LOAD/STORE instructions support absolute and DSA relative addressing 
modes. The SCSI SCRIPTS had been entirely rewritten using LOAD/STORE instead 
of MOVE MEMORY instructions.

Due to the lack of LOAD/STORE SCRIPTS instructions by earlier chips, this 
driver also incorporates a different SCRIPTS set based on MEMORY MOVE, in 
order to provide support for the entire SYM53C8XX chips family.

3.2 New features appeared with the SYM53C896

Newer chips (see above) allows handling of the phase mismatch context from 
SCRIPTS (avoids the phase mismatch interrupt that stops the SCSI processor 
until the C code has saved the context of the transfer).

The 896 and 1010 chips support 64 bit PCI transactions and addressing, 
while the 895A supports 32 bit PCI transactions and 64 bit addressing.
The SCRIPTS processor of these chips is not true 64 bit, but uses segment 
registers for bit 32-63. Another interesting feature is that LOAD/STORE 
instructions that address the on-chip RAM (8k) remain internal to the chip.

4. Memory mapped I/O versus normal I/O

Memory mapped I/O has less latency than normal I/O and is the recommended 
way for doing IO with PCI devices. Memory mapped I/O seems to work fine on 
most hardware configurations, but some poorly designed chipsets may break 
this feature. A configuration option is provided for normal I/O to be 
used but the driver defaults to MMIO.

5. Tagged command queueing

Queuing more than 1 command at a time to a device allows it to perform 
optimizations based on actual head positions and its mechanical 
characteristics. This feature may also reduce average command latency.
In order to really gain advantage of this feature, devices must have 
a reasonnable cache size (No miracle is to be expected for a low-end 
hard disk with 128 KB or less).
Some kown old SCSI devices do not properly support tagged command queuing.
Generally, firmware revisions that fix this kind of problems are available 
at respective vendor web/ftp sites.
All I can say is that I never have had problem with tagged queuing using 
this driver and its predecessors. Hard disks that behaved correctly for 
me using tagged commands are the following:

- IBM S12 0662
- Conner 1080S
- Quantum Atlas I
- Quantum Atlas II
- Seagate Cheetah I
- Quantum Viking II
- IBM DRVS
- Quantum Atlas IV
- Seagate Cheetah II

If your controller has NVRAM, you can configure this feature per target 
from the user setup tool. The Tekram Setup program allows to tune the 
maximum number of queued commands up to 32. The Symbios Setup only allows 
to enable or disable this feature.

The maximum number of simultaneous tagged commands queued to a device
is currently set to 16 by default.  This value is suitable for most SCSI
disks.  With large SCSI disks (>= 2GB, cache >= 512KB, average seek time
<= 10 ms), using a larger value may give better performances.

This driver supports up to 255 commands per device, and but using more than 
64 is generally not worth-while, unless you are using a very large disk or 
disk arrays. It is noticeable that most of recent hard disks seem not to 
accept more than 64 simultaneous commands. So, using more than 64 queued 
commands is probably just resource wasting.

If your controller does not have NVRAM or if it is managed by the SDMS 
BIOS/SETUP, you can configure tagged queueing feature and device queue 
depths from the boot command-line. For example:

  sym53c8xx=tags:4/t2t3q15-t4q7/t1u0q32

will set tagged commands queue depths as follow:

- target 2  all luns  on controller 0 --> 15
- target 3  all luns  on controller 0 --> 15
- target 4  all luns  on controller 0 -->  7
- target 1  lun 0     on controller 1 --> 32
- all other target/lun                -->  4

In some special conditions, some SCSI disk firmwares may return a
QUEUE FULL status for a SCSI command. This behaviour is managed by the
driver using the following heuristic:

- Each time a QUEUE FULL status is returned, tagged queue depth is reduced 
  to the actual number of disconnected commands. 

- Every 200 successfully completed SCSI commands, if allowed by the
  current limit, the maximum number of queueable commands is incremented.

Since QUEUE FULL status reception and handling is resource wasting, the 
driver notifies by default this problem to user by indicating the actual 
number of commands used and their status, as well as its decision on the 
device queue depth change.
The heuristic used by the driver in handling QUEUE FULL ensures that the 
impact on performances is not too bad. You can get rid of the messages by 
setting verbose level to zero, as follow:

1st method: boot your system using 'sym53c8xx=verb:0' option.
2nd method: apply "setverbose 0" control command to the proc fs entry 
            corresponding to your controller after boot-up.

6. Parity checking

The driver supports SCSI parity checking and PCI bus master parity
checking. These features must be enabled in order to ensure safe data
transfers. However, some flawed devices or mother boards will have
problems with parity. You can disable either PCI parity or SCSI parity 
checking by entering appropriate options from the boot command line.
(See 10: Boot setup commands).

7. Profiling information

This driver does not provide profiling informations as did its predecessors.
This feature was not this useful and added complexity to the code. 
As the driver code got more complex, I have decided to remove everything 
that didn't seem actually useful.

8. Control commands

Control commands can be sent to the driver with write operations to
the proc SCSI file system. The generic command syntax is the
following:

      echo "<verb> <parameters>" >/proc/scsi/sym53c8xx/0
      (assumes controller number is 0)

Using "all" for "<target>" parameter with the commands below will
apply to all targets of the SCSI chain (except the controller).

Available commands:

8.1 Set minimum synchronous period factor

    setsync <target> <period factor>

    target:    target number
    period:    minimum synchronous period.
               Maximum speed = 1000/(4*period factor) except for special
               cases below.

    Specify a period of 0, to force asynchronous transfer mode.

       9 means 12.5 nano-seconds synchronous period
      10 means 25 nano-seconds synchronous period
      11 means 30 nano-seconds synchronous period
      12 means 50 nano-seconds synchronous period

8.2 Set wide size

    setwide <target> <size>

    target:    target number
    size:      0=8 bits, 1=16bits

8.3 Set maximum number of concurrent tagged commands
 
    settags <target> <tags>

    target:    target number
    tags:      number of concurrent tagged commands
               must not be greater than configured (default: 16)

8.4 Set debug mode

    setdebug <list of debug flags>

    Available debug flags:
        alloc:   print info about memory allocations (ccb, lcb)
        queue:   print info about insertions into the command start queue
        result:  print sense data on CHECK CONDITION status
        scatter: print info about the scatter process
        scripts: print info about the script binding process
	tiny:    print minimal debugging information
	timing:  print timing information of the NCR chip
	nego:    print information about SCSI negotiations
	phase:   print information on script interruptions

    Use "setdebug" with no argument to reset debug flags.


8.5 Set flag (no_disc)
 
    setflag <target> <flag>

    target:    target number

    For the moment, only one flag is available:

        no_disc:   not allow target to disconnect.

    Do not specify any flag in order to reset the flag. For example:
    - setflag 4
      will reset no_disc flag for target 4, so will allow it disconnections.
    - setflag all
      will allow disconnection for all devices on the SCSI bus.


8.6 Set verbose level

    setverbose #level

    The driver default verbose level is 1. This command allows to change 
    th driver verbose level after boot-up.

8.7 Reset all logical units of a target

    resetdev <target>