linux/Documentation/scsi/tmscsim.txt
<<
>>
Prefs
   1The tmscsim driver
   2==================
   3
   41. Purpose and history
   52. Installation
   63. Features
   74. Configuration via /proc/scsi/tmscsim/?
   85. Configuration via boot/module params
   96. Potential improvements
  107. Bug reports, debugging and updates
  118. Acknowledgements
  129. Copyright
  13
  14
  151. Purpose and history
  16----------------------
  17The tmscsim driver supports PCI SCSI Host Adapters based on the AM53C974
  18chip. AM53C974 based SCSI adapters include: 
  19 Tekram DC390, DC390T
  20 Dawicontrol 2974
  21 QLogic Fast! PCI Basic
  22 some on-board adapters
  23(This is most probably not a complete list)
  24
  25It has originally written by C.L. Huang from the Tekram corp. to support the
  26Tekram DC390(T) adapter. This is where the name comes from: tm = Tekram
  27scsi = SCSI driver, m = AMD (?) as opposed to w for the DC390W/U/F
  28(NCR53c8X5, X=2/7) driver. Yes, there was also a driver for the latter,
  29tmscsiw, which supported DC390W/U/F adapters. It's not maintained any more,
  30as the ncr53c8xx is perfectly supporting these adapters since some time.
  31
  32The driver first appeared in April 1996, exclusively supported the DC390 
  33and has been enhanced since then in various steps. In May 1998 support for 
  34general AM53C974 based adapters and some possibilities to configure it were
  35added. The non-DC390 support works by assuming some values for the data
  36normally taken from the DC390 EEPROM. See below (chapter 5) for details.
  37
  38When using the DC390, the configuration is still be done using the DC390
  39BIOS setup. The DC390 EEPROM is read and used by the driver, any boot or
  40module parameters (chapter 5) are ignored! However, you can change settings
  41dynamically, as described in chapter 4. 
  42
  43For a more detailed description of the driver's history, see the first lines
  44of tmscsim.c.
  45The numbering scheme isn't consistent. The first versions went from 1.00 to
  461.12, then 1.20a to 1.20t. Finally I decided to use the ncr53c8xx scheme. So
  47the next revisions will be 2.0a to 2.0X (stable), 2.1a to 2.1X (experimental),
  482.2a to 2.2X (stable, again) etc. (X = anything between a and z.) If I send
  49fixes to people for testing, I create intermediate versions with a digit 
  50appended, e.g. 2.0c3.
  51
  52
  532. Installation
  54---------------
  55If you got any recent kernel with this driver and document included in
  56linux/drivers/scsi, you basically have to do nothing special to use this
  57driver. Of course you have to choose to compile SCSI support and DC390(T)
  58support into your kernel or as module when configuring your kernel for
  59compiling.
  60NEW: You may as well compile this module outside your kernel, using the
  61supplied Makefile.
  62
  63 If you got an old kernel (pre 2.1.127, pre 2.0.37p1) with an old version of
  64 this driver: Get dc390-21125-20b.diff.gz or dc390-2036p21-20b1.diff.gz from
  65 my web page and apply the patch. Apply further patches to upgrade to the 
  66 latest version of the driver.
  67
  68 If you want to do it manually, you should copy the files (dc390.h,
  69 tmscsim.h, tmscsim.c, scsiiom.c and README.tmscsim) from this directory to
  70 linux/drivers/scsi. You have to recompile your kernel/module of course.
  71
  72 You should apply the three patches included in dc390-120-kernel.diff
  73 (Applying them: cd /usr/src; patch -p0 <~/dc390-120-kernel.diff)
  74 The patches are against 2.1.125, so you might have to manually resolve
  75 rejections when applying to another kernel version.
  76
  77 The patches will update the kernel startup code to allow boot parameters to
  78 be passed to the driver, update the Documentation and finally offer you the
  79 possibility to omit the non-DC390 parts of the driver.
  80 (By selecting "Omit support for non DC390" you basically disable the
  81 emulation of a DC390 EEPROM for non DC390 adapters. This saves a few bytes
  82 of memory.)
  83
  84If you got a very old kernel without the tmscsim driver (pre 2.0.31)
  85I recommend upgrading your kernel. However, if you don't want to, please
  86contact me to get the appropriate patches.
  87
  88
  89Upgrading a SCSI driver is always a delicate thing to do. The 2.0 driver has
  90proven stable on many systems, but it's still a good idea to take some
  91precautions. In an ideal world you would have a full backup of your disks.
  92The world isn't ideal and most people don't have full backups (me neither).
  93So take at least the following measures:
  94* make your kernel remount the FS read-only on detecting an error:
  95  tune2fs -e remount-ro /dev/sd??
  96* have copies of your SCSI disk's partition tables on some safe location:
  97  dd if=/dev/sda of=/mnt/floppy/sda bs=512 count=1
  98  or just print it with:
  99  fdisk -l | lpr
 100* make sure you are able to boot Linux (e.g. from floppy disk using InitRD)
 101  if your SCSI disk gets corrupted. You can use 
 102  ftp://student.physik.uni-dortmund.de/pub/linux/kernel/bootdisk.gz
 103
 104One more warning: I used to overclock my PCI bus to 41.67 MHz. My Tekram
 105DC390F (Sym53c875) accepted this as well as my Millennium. But the Am53C974
 106produced errors and started to corrupt my disks. So don't do that! A 37.50
 107MHz PCI bus works for me, though, but I don't recommend using higher clocks
 108than the 33.33 MHz being in the PCI spec.
 109
 110If you want to share the IRQ with another device and the driver refuses to
 111do so, you might succeed with changing the DC390_IRQ type in tmscsim.c to 
 112IRQF_SHARED | IRQF_DISABLED.
 113
 114
 1153.Features
 116----------
 117- SCSI
 118 * Tagged command queueing
 119 * Sync speed up to 10 MHz
 120 * Disconnection
 121 * Multiple LUNs
 122
 123- General / Linux interface
 124 * Support for up to 4 AM53C974 adapters.
 125 * DC390 EEPROM usage or boot/module params
 126 * Information via cat /proc/scsi/tmscsim/?
 127 * Dynamically configurable by writing to /proc/scsi/tmscsim/?
 128 * Dynamic allocation of resources
 129 * SMP support: Locking on io_request lock (Linux 2.1/2.2) or adapter 
 130    specific locks (Linux 2.5?)
 131 * Uniform source code for Linux-2.x.y
 132 * Support for dyn. addition/removal of devices via add/remove-single-device
 133   (Try: echo "scsi add-single-device C B T U" >/proc/scsi/scsi 
 134    C = Controller, B = Bus, T = Target SCSI ID, U = Unit SCSI LUN.) 
 135    Use with care!
 136 * Try to use the partition table for the determination of the mapping
 137
 138
 1394. Configuration via /proc/scsi/tmscsim/?
 140-----------------------------------------
 141First of all look at the output of /proc/scsi/tmscsim/? by typing
 142 cat /proc/scsi/tmscsim/?
 143The "?" should be replaced by the SCSI host number. (The shell might do this
 144for you.)
 145You will see some info regarding the adapter and, at the end, a listing of
 146the attached devices and their settings.
 147
 148Here's an example:
 149garloff@kurt:/home/garloff > cat /proc/scsi/tmscsim/0
 150Tekram DC390/AM53C974 PCI SCSI Host Adapter, Driver Version 2.0e7 2000-11-28
 151SCSI Host Nr 1, AM53C974 Adapter Nr 0
 152IOPortBase 0xb000, IRQ 10
 153MaxID 8, MaxLUN 8, AdapterID 6, SelTimeout 250 ms, DelayReset 1 s
 154TagMaxNum 16, Status 0x00, ACBFlag 0x00, GlitchEater 24 ns
 155Statistics: Cmnds 1470165, Cmnds not sent directly 0, Out of SRB conds 0
 156            Lost arbitrations 587,  Sel. connected 0, Connected: No
 157Nr of attached devices: 4, Nr of DCBs: 4
 158Map of attached LUNs: 01 00 00 03 01 00 00 00
 159Idx ID LUN Prty Sync DsCn SndS TagQ NegoPeriod SyncSpeed SyncOffs MaxCmd
 16000  00  00  Yes  Yes  Yes  Yes  Yes   100 ns    10.0 M      15      16
 16101  03  00  Yes  Yes  Yes  Yes  No    100 ns    10.0 M      15      01
 16202  03  01  Yes  Yes  Yes  Yes  No    100 ns    10.0 M      15      01
 16303  04  00  Yes  Yes  Yes  Yes  No    100 ns    10.0 M      15      01
 164
 165Note that the settings MaxID and MaxLUN are not zero- but one-based, which
 166means that a setting MaxLUN=4, will result in the support of LUNs 0..3. This
 167is somehow inconvenient, but the way the mid-level SCSI code expects it to be.
 168
 169ACB and DCB are acronyms for Adapter Control Block and Device Control Block.
 170These are data structures of the driver containing information about the
 171adapter and the connected SCSI devices respectively.
 172
 173Idx is the device index (just a consecutive number for the driver), ID and
 174LUN are the SCSI ID and LUN, Prty means Parity checking, Sync synchronous
 175negotiation, DsCn Disconnection, SndS Send Start command on startup (not
 176used by the driver) and TagQ Tagged Command Queueing. NegoPeriod and
 177SyncSpeed are somehow redundant, because they are reciprocal values 
 178(1 / 112 ns = 8.9 MHz). At least in theory. The driver is able to adjust the
 179NegoPeriod more accurate (4ns) than the SyncSpeed (1 / 25ns). I don't know
 180if certain devices will have problems with this discrepancy. Max. speed is
 18110 MHz corresp. to a min. NegoPeriod of 100 ns. 
 182(The driver allows slightly higher speeds if the devices (Ultra SCSI) accept
 183it, but that's out of adapter spec, on your own risk and unlikely to improve
 184performance. You're likely to crash your disks.) 
 185SyncOffs is the offset used for synchronous negotiations; max. is 15. 
 186The last values are only shown, if Sync is enabled. (NegoPeriod is still
 187displayed in brackets to show the values which will be used after enabling
 188Sync.)
 189MaxCmd ist the number of commands (=tags) which can be processed at the same
 190time by the device.
 191
 192If you want to change a setting, you can do that by writing to
 193/proc/scsi/tmscsim/?. Basically you have to imitate the output of driver.
 194(Don't use the brackets for NegoPeriod on Sync disabled devices.)
 195You don't have to care about capitalisation. The driver will accept space,
 196tab, comma, = and : as separators.
 197
 198There are three kinds of changes: 
 199
 200(1) Change driver settings: 
 201    You type the names of the parameters and the params following it.
 202    Example:
 203     echo "MaxLUN=8 seltimeout 200" >/proc/scsi/tmscsim/0
 204
 205    Note that you can only change MaxID, MaxLUN, AdapterID, SelTimeOut,
 206    TagMaxNum, ACBFlag, GlitchEater and DelayReset. Don't change ACBFlag
 207    unless you want to see what happens, if the driver hangs.
 208
 209(2) Change device settings: You write a config line to the driver. The Nr
 210    must match the ID and LUN given. If you give "-" as parameter, it is
 211    ignored and the corresponding setting won't be changed. 
 212    You can use "y" or "n" instead of "Yes" and "No" if you want to.
 213    You don't need to specify a full line. The driver automatically performs
 214    an INQUIRY on the device if necessary to check if it is capable to operate
 215    with the given settings (Sync, TagQ).
 216    Examples:
 217     echo "0 0 0 y y y - y - 10 " >/proc/scsi/tmscsim/0
 218     echo "3 5 0 y n y " >/proc/scsi/tmscsim/0
 219
 220    To give a short explanation of the first example: 
 221    The first three numbers, "0 0 0" (Device index 0, SCSI ID 0, SCSI LUN 0),
 222    select the device to which the following parameters apply. Note that it
 223    would be sufficient to use the index or both SCSI ID and LUN, but I chose
 224    to require all three to have a syntax similar to the output.
 225    The following "y y y - y" enables Parity checking, enables Synchronous
 226    transfers, Disconnection, leaves Send Start (not used) untouched and
 227    enables Tagged Command Queueing for the selected device. The "-" skips
 228    the Negotiation Period setting but the "10" sets the max sync. speed to
 229    10 MHz. It's useless to specify both NegoPeriod and SyncSpeed as
 230    discussed above. The values used in this example will result in maximum
 231    performance.
 232
 233(3) Special commands: You can force a SCSI bus reset, an INQUIRY command, the
 234    removal or the addition of a device's DCB and a SCSI register dump.
 235    This is only used for debugging when you meet problems. The parameter of
 236    the INQUIRY and REMOVE commands is the device index as shown by the
 237    output of /proc/scsi/tmscsim/? in the device listing in the first column
 238    (Idx). ADD takes the SCSI ID and LUN.
 239    Examples:
 240     echo "reset" >/proc/scsi/tmscsim/0
 241     echo "inquiry 1" >/proc/scsi/tmscsim/0
 242     echo "remove 2" >/proc/scsi/tmscsim/1
 243     echo "add 2 3" >/proc/scsi/tmscsim/?
 244     echo "dump" >/proc/scsi/tmscsim/0
 245
 246    Note that you will meet problems when you REMOVE a device's DCB with the
 247    remove command if it contains partitions which are mounted. Only use it
 248    after unmounting its partitions, telling the SCSI mid-level code to
 249    remove it (scsi remove-single-device) and you really need a few bytes of
 250    memory.
 251    The ADD command allows you to configure a device before you tell the
 252    mid-level code to try detection.
 253
 254
 255I'd suggest reviewing the output of /proc/scsi/tmscsim/? after changing
 256settings to see if everything changed as requested.
 257
 258
 2595. Configuration via boot/module parameters
 260-------------------------------------------
 261With the DC390, the driver reads its EEPROM settings and tries to use them.
 262But you may want to override the settings prior to being able to change the
 263driver configuration via /proc/scsi/tmscsim/?.
 264If you do have another AM53C974 based adapter, that's even the only
 265possibility to adjust settings before you are able to write to the
 266/proc/scsi/tmscsim/? pseudo-file, e.g. if you want to use another 
 267adapter ID than 7.  
 268(BTW, the log message "DC390: No EEPROM found!" is normal without a DC390.)
 269For this purpose, you can pass options to the driver before it is initialised
 270by using kernel or module parameters. See lilo(8) or modprobe(1) manual
 271pages on how to pass params to the kernel or a module.
 272[NOTE: Formerly, it was not possible to override the EEPROM supplied
 273 settings of the DC390 with cmd line parameters. This has changed since
 274 2.0e7]
 275
 276The syntax of the params is much shorter than the syntax of the /proc/...
 277interface. This makes it a little bit more difficult to use. However, long
 278parameter lines have the risk to be misinterpreted and the length of kernel
 279parameters is limited.
 280
 281As the support for non-DC390 adapters works by simulating the values of the
 282DC390 EEPROM, the settings are given in a DC390 BIOS' way.
 283
 284Here's the syntax:
 285tmscsim=AdaptID,SpdIdx,DevMode,AdaptMode,TaggedCmnds,DelayReset
 286
 287Each of the parameters is a number, containing the described information:
 288
 289* AdaptID: The SCSI ID of the host adapter. Must be in the range 0..7
 290  Default is 7.
 291
 292* SpdIdx: The index of the maximum speed as in the DC390 BIOS. The values
 293  0..7 mean 10, 8.0, 6.7, 5.7, 5.0, 4.0, 3.1 and 2 MHz resp. Default is
 294  0 (10.0 MHz).
 295
 296* DevMode is a bit mapped value describing the per-device features. It
 297  applies to all devices. (Sync, Disc and TagQ will only apply, if the
 298  device supports it.) The meaning of the bits (* = default):
 299
 300   Bit Val(hex) Val(dec)  Meaning
 301   *0    0x01       1     Parity check
 302   *1    0x02       2     Synchronous Negotiation
 303   *2    0x04       4     Disconnection
 304   *3    0x08       8     Send Start command on startup. (Not used)
 305   *4    0x10      16     Tagged Command Queueing
 306
 307  As usual, the desired value is obtained by adding the wanted values. If
 308  you want to enable all values, e.g., you would use 31(0x1f). Default is 31.
 309
 310* AdaptMode is a bit mapped value describing the enabled adapter features.
 311
 312   Bit Val(hex) Val(dec)  Meaning
 313   *0    0x01       1     Support more than two drives. (Not used)
 314   *1    0x02       2     Use DOS compatible mapping for HDs greater than 1GB.
 315   *2    0x04       4     Reset SCSI Bus on startup.
 316   *3    0x08       8     Active Negation: Improves SCSI Bus noise immunity.
 317    4    0x10      16     Immediate return on BIOS seek command. (Not used)
 318 (*)5    0x20      32     Check for LUNs >= 1.
 319  
 320  The default for LUN Check depends on CONFIG_SCSI_MULTI_LUN.
 321
 322* TaggedCmnds is a number indicating the maximum number of Tagged Commands.
 323  It is the binary logarithm - 1 of the actual number. Max is 4 (32).
 324   Value  Number of Tagged Commands
 325     0           2
 326     1           4
 327     2           8
 328    *3          16
 329     4          32
 330
 331* DelayReset is the time in seconds (minus 0.5s), the adapter waits, after a
 332  bus reset. Default is 1 (corresp. to 1.5s).
 333
 334Example:
 335 modprobe tmscsim tmscsim=6,2,31
 336would set the adapter ID to 6, max. speed to 6.7 MHz, enable all device
 337features and leave the adapter features, the number of Tagged Commands
 338and the Delay after a reset to the defaults.
 339
 340As you can see, you don't need to specify all of the six params.
 341If you want values to be ignored (i.e. the EEprom settings or the defaults
 342will be used), you may pass -2 (not 0!) at the corresponding position.
 343
 344The defaults (7,0,31,15,3,1) are aggressive to allow good performance. You
 345can use tmscsim=7,0,31,63,4,0 for maximum performance, if your SCSI chain
 346allows it. If you meet problems, you can use tmscsim=-1 which is a shortcut
 347for tmscsim=7,4,9,15,2,10.
 348
 349
 3506. Potential improvements
 351-------------------------
 352Most of the intended work on the driver has been done. Here are a few ideas
 353to further improve its usability:
 354
 355* Cleanly separate per-Target and per-LUN properties (DCB)
 356* More intelligent abort() routine
 357* Use new_eh code (Linux-2.1+)
 358* Have the mid-level (ML) code (and not the driver) handle more of the
 359  various conditions.
 360* Command queueing in the driver: Eliminate Query list and use ML instead.
 361* More user friendly boot/module param syntax
 362
 363Further investigation on these problems:
 364
 365* Driver hangs with sync readcdda (xcdroast) (most probably VIA PCI error)
 366
 367Known problems: 
 368Please see http://www.garloff.de/kurt/linux/dc390/problems.html
 369
 370* Changing the parameters of multi-lun by the tmscsim/? interface will
 371  cause problems, cause these settings are mostly per Target and not per LUN
 372  and should be updated accordingly. To be fixed for 2.0d24.
 373* CDRs (eg Yam CRW4416) not recognized, because some buggy devices don't 
 374  recover from a SCSI reset in time. Use a higher delay or don't issue
 375  a SCSI bus reset on driver initialization. See problems page.
 376  For the CRW4416S, this seems to be solved with firmware 1.0g (reported by 
 377  Jean-Yves Barbier).
 378* TEAC CD-532S not being recognized. (Works with 1.11).
 379* Scanners (eg. Astra UMAX 1220S) don't work: Disable Sync Negotiation.
 380  If this does not help, try echo "INQUIRY t" >/proc/scsi/tmscsim/? (t
 381  replaced by the dev index of your scanner). You may try to reset your SCSI
 382  bus afterwards (echo "RESET" >/proc/scsi/tmscsim/?).
 383  The problem seems to be solved as of 2.0d18, thanks to Andreas Rick.
 384* If there is a valid partition table, the driver will use it for determining
 385  the mapping. If there's none, a reasonable mapping (Symbios-like) will be
 386  assumed. Other operating systems may not like this mapping, though
 387  it's consistent with the BIOS' behaviour. Old DC390 drivers ignored the
 388  partition table and used a H/S = 64/32 or 255/63 translation. So if you
 389  want to be compatible to those, use this old mapping when creating
 390  partition tables. Even worse, on bootup the DC390 might complain if other
 391  mappings are found, so auto rebooting may fail.
 392* In some situations, the driver will get stuck in an abort loop. This is a
 393  bad interaction between the Mid-Layer of Linux' SCSI code and the driver.
 394  Try to disable DsCn, if you meet this problem. Please contact me for
 395  further debugging.
 396
 397
 3987. Bug reports, debugging and updates
 399-------------------------------------
 400Whenever you have problems with the driver, you are invited to ask the
 401author for help. However, I'd suggest reading the docs and trying to solve
 402the problem yourself, first. 
 403If you find something, which you believe to be a bug, please report it to me. 
 404Please append the output of /proc/scsi/scsi, /proc/scsi/tmscsim/? and
 405maybe the DC390 log messages to the report. 
 406
 407Bug reports should be send to me (Kurt Garloff <dc390@garloff.de>) as well
 408as to the linux-scsi list (<linux-scsi@vger.kernel.org>), as sometimes bugs
 409are caused by the SCSI mid-level code.
 410
 411I will ask you for some more details and probably I will also ask you to
 412enable some of the DEBUG options in the driver (tmscsim.c:DC390_DEBUGXXX
 413defines). The driver will produce some data for the syslog facility then.
 414Beware: If your syslog gets written to a SCSI disk connected to your
 415AM53C974, the logging might produce log output again, and you might end
 416having your box spending most of its time doing the logging.
 417
 418The latest version of the driver can be found at:
 419 http://www.garloff.de/kurt/linux/dc390/
 420 ftp://ftp.suse.com/pub/people/garloff/linux/dc390/
 421
 422
 4238. Acknowledgements
 424-------------------
 425Thanks to Linus Torvalds, Alan Cox, the FSF people, the XFree86 team and 
 426all the others for the wonderful OS and software.
 427Thanks to C.L. Huang and Philip Giang (Tekram) for the initial driver
 428release and support.
 429Thanks to Doug Ledford, GĂ©rard Roudier for support with SCSI coding.
 430Thanks to a lot of people (espec. Chiaki Ishikawa, Andreas Haumer, Hubert 
 431Tonneau) for intensively testing the driver (and even risking data loss
 432doing this during early revisions).
 433Recently, SuSE GmbH, Nuernberg, FRG, has been paying me for the driver
 434development and maintenance. Special thanks!
 435
 436
 4379. Copyright
 438------------
 439 This driver is free software; you can redistribute it and/or modify
 440 it under the terms of the GNU General Public License as published by   
 441 the Free Software Foundation; version 2 of the License.
 442 If you want to use any later version of the GNU GPL, you will probably
 443 be allowed to, but you have to ask me and Tekram <erich@tekram.com.tw>
 444 before.
 445
 446-------------------------------------------------------------------------
 447Written by Kurt Garloff <kurt@garloff.de> 1998/06/11
 448Last updated 2000/11/28, driver revision 2.0e7
 449$Id: README.tmscsim,v 2.25.2.7 2000/12/20 01:07:12 garloff Exp $
 450
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.