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