Subversion Repositories or1k

The tmscsim driver

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

1. Purpose and history

2. Installation

3. Features

4. Configuration via /proc/scsi/tmscsim/?

5. Configuration via boot/module params

6. Potential improvements

7. Bug reports, debugging and updates

8. Acknowledgements

1. Purpose and history

----------------------

The tmscsim driver supports PCI SCSI Host Adapters based on the AM53C974

chip. AM53C974 based SCSI adapters include:

 Tekram DC390, DC390T

 Dawicontrol 2974

 QLogic Fast! PCI Basic

 some on-board adapters

(This is most probably not a complete list)

It has originally written by C.L. Huang from the Tekram corp. to support the

Tekram DC390(T) adapter. This is where the name comes from: tm = Tekram

scsi = SCSI driver, m = AMD (?) as opposed to w for the DC390W/U/F

(NCR53c8X5, X=2/7) driver. Yes, there was also a driver for the latter,

tmscsimw, which supported DC390W/U/F adapters. It's not maintained any more,

as the ncr53c8xx is perfectly supporting these adpaters since some time.

The driver first appeared in April 1996, exclusively supported the DC390

and has been enhanced since then in various steps. In May 1998 support for

general AM53C974 based adapters and some possibilities to configure it were

added. The non-DC390 support works by assuming some values for the data

normally taken from the DC390 EEPROM. See below (chapter 5) for details.

When using the DC390, the configuration is still be done using the DC390

BIOS setup. The DC390 EEPROM is read and used by the driver, any boot or

module parameters (chapter 5) are ignored! However, you can change settings

dynamically, as described in chapter 4.

For a more detailed description of the driver's history, see the first lines

of tmscsim.c.

The numbering scheme isn't consistent. The first versions went from 1.00 to

1.12, then 1.20a to 1.20t. Finally I decided to use the ncr53c8xx scheme. So

the next revisions will be 2.0a to 2.0X (stable), 2.1a to 2.1X (experimental),

2.2a to 2.2X (stable, again) etc. (X = anything between a and z.) If I send

fixes to people for testing, I create intermediate versions with a digit

appended, e.g. 2.0c3.

2. Installation

---------------

If you got any recent kernel with this driver and document included in

linux/drivers/scsi, you basically have to do nothing special to use this

driver. Of course you have to choose to compile SCSI support and DC390(T)

support into your kernel or as module when configuring your kernel for

compiling.

 If you got an old kernel (pre 2.1.127, pre 2.0.37p1) with an old version of

 this driver: Get dc390-21125-20b.diff.gz or dc390-2036p21-20b1.diff.gz from

 my website and apply the patch.

 If you want to do it manually, you should copy the files (dc390.h,

 tmscsim.h, tmscsim.c, scsiiom.c and README.tmscsim) from this directory to

 linux/drivers/scsi. You have to recompile your kernel/module of course.

 You should apply the three patches included in dc390-120-kernel.diff

 (Applying them: cd /usr/src; patch -p0 <~/dc390-120-kernel.diff)

 The patches are against 2.1.125, so you might have to manually resolve

 rejections when applying to another kernel version.

 The patches will update the kernel startup code to allow boot parameters to

 be passed to the driver, update the Documentation and finally offer you the

 possibility to omit the non-DC390 parts of the driver.

 (By selecting "Omit support for non DC390" you basically disable the

 emulation of a DC390 EEPROM for non DC390 adapters. This saves a few bytes

 of memory.)

If you got a very old kernel without the tmscsim driver (pre 2.0.31)

I recommend upgrading your kernel. However, if you don't want to, please

contact me to get the appropriate patches.

Upgrading a SCSI driver is always a delicate thing to do. The 2.0 driver has

proven stable on many systems, but it's still a good idea to take some

precautions. In an ideal world you would have a full backup of your disks.

The world isn't ideal and most people don't have full backups (me neither).

So take at least the following measures:

* make your kernel remount the FS read-only on detecting an error:

  tune2fs -e remount-ro /dev/sd??

* have copies of your SCSI disk's partition tables on some safe location:

  dd if=/dev/sda of=/mnt/floppy/sda bs=512 count=1

* make sure you are able to boot Linux (e.g. from floppy disk using InitRD)

  if your SCSI disk gets corrupted. You can use

  ftp://student.physik.uni-dortmund.de/pub/linux/kernel/bootdisk.gz

One more warning: I used to overclock my PCI bus to 41.67 MHz. My Tekram

DC390F (Sym53c875) accepted this as well as my Millenium. But the Am53C974

produced errors and started to corrupt my disks. So don't do that! A 37.50

MHz PCI bus works for me, though, but I don't recommend using higher clocks

than the 33.33 MHz being in the PCI spec.

If you want to share the IRQ with another device and the driver refuses to

do, you might succeed with changing the DC390_IRQ type in tmscsim.c to

SA_SHIRQ | SA_INTERRUPT.

3.Features

----------

- SCSI

 * Tagged command queueing

 * Sync speed up to 10 MHz

 * Disconnection

 * Multiple LUNs

- General / Linux interface

 * Support for up to 4 AM53C974 adapters.

 * DC390 EEPROM usage or boot/module params

 * Information via cat /proc/scsi/tmscsim/?

 * Dynamically configurable by writing to /proc/scsi/tmscsim/?

 * Dynamic allocation of resources

 * SMP support: Locking on io_request lock (Linux 2.1/2.2) or adapter

    specific locks (Linux 2.3)

 * Uniform source code for Linux-2.x.y

 * Support for dyn. addition/removal of devices via add/remove-single-device

   (Try: echo "scsi add-single-device H C I L" >/proc/scsi/scsi

    H = Host, C = Channel, I = SCSI ID, L = SCSI LUN.) Use with care!

 * Try to use the partition table for the determination of the mapping

4. Configuration via /proc/scsi/tmscsim/?

-----------------------------------------

First of all look at the output of /proc/scsi/tmscsim/? by typing

 cat /proc/scsi/tmscsim/?

The "?" should be replaced by the SCSI host number. (The shell might do this

for you.)

You will see some info regarding the adapter and, at the end, a listing of

the attached devices and their settings.

Here's an example:

garloff@kg1:/home/garloff > cat /proc/scsi/tmscsim/0

Tekram DC390/AM53C974 PCI SCSI Host Adapter, Driver Version 1.20s, 1998/08/20

SCSI Host Nr 0, AM53C974 Adapter Nr 0

IOPortBase 0x6200, IRQLevel 0x09

MaxID 7, MaxLUN 8, AdapterID 7, SelTimeout 250 ms

TagMaxNum 16, Status 0, ACBFlag 0, GlitchEater 24 ns

Statistics: Nr of Cmnds 39563, Cmnds not sent directly 0, Out of SRB conds 0

            Nr of lost arbitrations 17

Nr of attached devices: 4, Nr of DCBs: 4

Idx ID LUN Prty Sync DsCn SndS TagQ STOP NegoPeriod SyncSpeed SyncOffs

00  00  00  Yes  Yes  Yes  Yes  Yes  No    100 ns    10.0 M      15

01  01  00  Yes  Yes  Yes  Yes  Yes  No    100 ns    10.0 M      15

02  03  00  Yes  Yes  Yes  Yes  No   No    100 ns    10.0 M      15

03  05  00  Yes  No   Yes  Yes  No   No   (200 ns)

Note that the settings MaxID and MaxLUN are not zero- but one-based, which

means that a setting MaxLUN=4, will result in the support of LUNs 0..3. This

is somehow inconvenient, but the way the mid-level SCSI code expects it to be.

ACB and DCB are acronyms for Adapter Control Block and Device Control Block.

These are data structures of the driver containing information about the

adapter and the connected SCSI devices respectively.

Idx is the device index (just a consecutive number for the driver), ID and

LUN are the SCSI ID and LUN, Prty means Parity checking, Sync synchronous

negotiation, DsCn Disconnection, SndS Send Start command on startup (not

used by the driver) and TagQ Tagged Command Queueing. NegoPeriod and

SyncSpeed are somehow redundant, because they are reciprocal values

(1 / 112 ns = 8.9 MHz). At least in theory. The driver is able to adjust the

NegoPeriod more accurate (4ns) than the SyncSpeed (1 / 25ns). I don't know

if certain devices will have problems with this discrepancy. Max. speed is

10 MHz corresp. to a min. NegoPeriod of 100 ns.

(The driver allows slightly higher speeds if the devices (Ultra SCSI) accept

it, but that's out of adapter spec, on your own risk and unlikely to improve

performance. You're likely to crash your disks.)

SyncOffs is the offset used for synchronous negotiations; max. is 15.

The last values are only shown, if Sync is enabled. (NegoPeriod is still

displayed in brackets to show the values which will be used after enabling

Sync.)

The STOP parameter is for testing/debugging purposes only and should bet set

to No. Please don't fiddle with it, unless you want to get rid of the

contents of your disk.

If you want to change a setting, you can do that by writing to

/proc/scsi/tmscsim/?. Basically you have to imitate the output of driver.

(Don't use the brackets for NegoPeriod on Sync disabled devices.)

You don't have to care about capitalisation. The driver will accept space,

tab, comma, = and : as separators.

There are three kinds of changes:

(1) Change driver settings:

    You type the names of the parameters and the params following it.

    Example:

     echo "MaxLUN=8 seltimeout 200" >/proc/scsi/tmscsim/0

    Note that you can only change MaxID, MaxLUN, AdapterID, SelTimeOut,

    TagMaxNum, ACBFlag and GlitchEater. Don't change ACBFlag unless you

    want to see what happens, if the driver hangs.

(2) Change device settings: You write a config line to the driver. The Nr

    must match the ID and LUN given. If you give "-" as parameter, it is

    ignored and the corresponding setting won't be changed.

    You can use "y" or "n" instead of "Yes" and "No" if you want to.

    You don't need to specify a full line. The driver automatically performs

    an INQUIRY on the device if necessary to check if it is capable to operate

    with the given settings (Sync, TagQ).

    Examples:

     echo "0 0 0 y y y - y - 10" >/proc/scsi/tmscsim/0

     echo "3 5 0 y n y" >/proc/scsi/tmscsim/0

    To give a short explanation of the first example:

    The first three numbers, "0 0 0" (Device index 0, SCSI ID 0, SCSI LUN 0),

    select the device to which the following parameters apply. Note that it

    would be sufficient to use the index or both SCSI ID and LUN, but I chose

    to require all three to have a syntax similar to the output.

    The following "y y y - y" enables Parity checking, enables Synchronous

    transfers, Disconnection, leaves Send Start (not used) untouched and

    enables Tagged Command Queueing for the selected device. The "-" skips

    the Negotiation Period setting but the "10" sets the max sync. speed to

    10 MHz. It's useless to specify both NegoPeriod and SyncSpeed as

    discussed above. The values used in this example will result in maximum

    performance.

(3) Special commands: You can force a SCSI bus reset, an INQUIRY command and

    the removal of a device's DCB.

    This is only used for debugging when you meet problems. The parameter of

    the INQUIRY and remove command is the device index as shown by the

    output of /proc/scsi/tmscsim/? in the device listing in the first column

    (Idx).

    Examples:

     echo "reset" >/proc/scsi/tmscsim/0

     echo "inquiry 1" >/proc/scsi/tmscsim/0

     echo "remove 2" >/proc/scsi/tmscsim/1

    Note that you will meet problems when you remove a device's DCB with the

    remove command if it contains partitions which are mounted. Only use it

    after unmounting its partitions, telling the SCSI mid-level code to

    remove it (scsi remove-single-device) and you really need a few bytes of

    memory.

I'd suggest reviewing the output of /proc/scsi/tmscsim/? after changing

settings to see if everything changed as requested.

5. Configuration via boot/module parameters

-------------------------------------------

With the DC390, the driver reads its EEPROM settings and IGNORES boot /

module parameters. If you want to override the EEPROM settings of a DC390,

you have to use the /proc/scsi/tmscsim/? interface described in the above

chapter.

However, if you do have another AM53C974 based adapter you might want to

adjust some settings before you are able to write to the /proc/scsi/tmscsim/?

pseudo-file, e.g. if you want to use another adapter ID than 7. (Note that

the log message "DC390: No EEPROM found!" is normal without a DC390.)

For this purpose, you can pass options to the driver before it is initialised

by using kernel or module parameters. See lilo(8) or modprobe(1) manual

pages on how to pass params to the kernel or a module.

The syntax of the params is much shorter than the syntax of the /proc/...

interface. This makes it a little bit more difficult to use. However, long

parameter lines have the risk to be misinterpreted and the length of kernel

parameters is limited.

As the support for non-DC390 adapters works by simulating the values of the

DC390 EEPROM, the settings are given in a DC390 BIOS' way.

Here's the syntax:

tmscsim=AdaptID,SpdIdx,DevMode,AdaptMode,TaggedCmnds

Each of the parameters is a number, containing the described information:

* AdaptID: The SCSI ID of the host adapter. Must be in the range 0..7

  Default is 7.

* SpdIdx: The index of the maximum speed as in the DC390 BIOS. The values

  0..7 mean 10, 8.0, 6.7, 5.7, 5.0, 4.0, 3.1 and 2 MHz resp. Default is

  1 (8.0 MHz).

* DevMode is a bit mapped value describing the per-device features. It

  applies to all devices. (Sync, Disc and TagQ will only apply, if the

  device supports it.) The meaning of the bits (* = default):

   Bit Val(hex) Val(dec)  Meaning

   *0    0x01       1     Parity check

   *1    0x02       2     Synchronous Negotiation

   *2    0x04       4     Disconnection

   *3    0x08       8     Send Start command on startup. (Not used)

   *4    0x10      16     Tagged Queueing

  As usual, the desired value is obtained by adding the wanted values. If

  you want to enable all values, e.g., you would use 31(0x1f). Default is 31.

* AdaptMode is a bit mapped value describing the enabled adapter features.

   Bit Val(hex) Val(dec)  Meaning

   *0    0x01       1     Support more than two drives. (Not used)

   *1    0x02       2     Use DOS compatible mapping for HDs greater than 1GB.

   *2    0x04       4     Reset SCSI Bus on startup.

   *3    0x08       8     Active Negation: Improves SCSI Bus noise immunity.

    4    0x10      16     Immediate return on BIOS seek command. (Not used)

 (*)5    0x20      32     Check for LUNs >= 1.

  The default for LUN Check depends on CONFIG_SCSI_MULTI_LUN.

* TaggedCmnds is a number indicating the maximum number of Tagged Commands.

  It is the binary logarithm - 1 of the actual number. Max is 4 (32).

   Value  Number of Tagged Commands

     1           4

     2           8

    *3          16

     4          32

Example:

 modprobe tmscsim tmscsim=6,2,31

would set the adapter ID to 6, max. speed to 6.7 MHz, enable all device

features and leave the adapter features and the number of Tagged Commands

to the defaults.

As you can see, you don't need to specify all of the five params.

The defaults (7,1,31,15,3) are aggressive to allow good performance. You can

use tmscsim=7,0,31,63,4 for maximum performance, if your SCSI chain is

perfect. If you meet problems, you can use tmscsim=-1 which is a shortcut

for tmscsim=7,4,9,15,2.

6. Potential improvements

-------------------------

Most of the intended work on the driver has been done. Here are a few ideas

to further improve its usability:

* More intelligent abort() routine

* Implement new_eh code (Linux-2.1+)

* Have the mid-level code (and not the driver) handle more of the various

  conditions.

* Rework command queueing in the driver

* More user friendly boot/module param syntax

Further investigation on these problems:

* Driver hangs with sync readcdda (xcdroast) (most probably VIA PCI error)

Known problems:

* There was a report that with a certain Scanner, the last SCSI command

  won't be finished correctly. This might be a command queueing bug or a bug

  in SCSI implementation of the scanner. Issueing another command to the

  scanner seems to help. (Try echo "INQUIRY x" >/proc/scsi/tmscsim/?, where

  x is the index (not the SCSI ID!) of the scanner. See 4.(3).)

* If there is a valid partition table, the driver will use it for determing

  the mapping. Other operating systems may not like this mapping, though

  it's consistent with the BIOS' behaviour. Old DC390 drivers ignored the

  partition table and used a H/S = 64/32 or 255/63 translation. So if you

  want to be compatible to those, use this old mapping when creating

  partition tables.

* In some situations, the driver will get stuck in an abort loop. Please

  disable DsCn, if you meet this problem. Please contact me for further

  debugging.

* 2.1.115+: Linux misses locks in sr_ioctl.c and scsi_ioctl.c

  There used to be a patch included here, which partially solved the

  problem. I suggest you contact Chiaki Ishikawa ,

  Richard Waltham  or Doug Ledford

  , if you want to help further debugging it.

* 2.0.35: CD changers (e.g. NAKAMICHI MBR-7.{0,2}) have problems because

  the mid-level code doesn't handle BLIST_SINGLELUN correctly. There used

  to be a patch included here to fix this, but I was told that it is fixed

  in 2.0.36.

7. Bug reports, debugging and updates

-------------------------------------

Whenever you have problems with the driver, you are invited to ask the

author for help. However, I'd suggest reading the docs and trying to solve

the problem yourself, first.

If you find something, which you believe to be a bug, please report it to me.

Please append the output of /proc/scsi/scsi, /proc/scsi/tmscsim/? and

maybe the DC390 log messages to the report.

Bug reports should be send to me (Kurt Garloff ) as well

as to the linux-scsi list (), as sometimes bugs

are caused by the SCSI mid-level code.

I will ask you for some more details and probably I will also ask you to

enable some of the DEBUG options in the driver (tmscsim.c:DC390_DEBUGXXX

defines). The driver will produce some data for the syslog facility then.

Beware: If your syslog gets written to a SCSI disk connected to your

AM53C974, the logging might produce log output again, and you might end

having your box spending most of its time doing the logging.

The latest version of the driver can be found at:

 http://www.garloff.de/kurt/linux/dc390/

and

 ftp://student.physik.uni-dortmund.de/pub/linux/kernel/dc390/

(The latter might shut down some day.)

8. Acknowledgements

-------------------

Thanks to Linus Torvalds, Alan Cox, David Miller, Rik v. Riel, the FSF

people, the XFree86 team and all the others for the wonderful OS and

software.

Thanks to C.L. Huang and Philip Giang (Tekram) for the initial driver

release and support.

Thanks to Doug Ledford, Gerard Roudier for support with SCSI coding.

Thanks to a lot of people (espec. Chiaki Ishikawa, Andreas Haumer, Hubert

Tonneau) for intensively testing the driver (and even risking data loss

doing this during early revisions).

-------------------------------------------------------------------------

Written by Kurt Garloff  1998/06/11

Last updated 1998/12/25, driver revision 2.0d

$Id: README.tmscsim,v 1.1 2005-12-20 10:17:45 jcastillo Exp $