README file for the dc395x_trm SCSI driver ========================================== Preliminary. 2000-02-14 Kurt Garloff $Id: README.dc395x,v 1.16 2002/02/13 10:23:58 garloff Exp $ This driver is similar to the DC390/AM53c974 driver (tmscsim), so you might want to have a look into the README.tmscsim. The tmscsim has undergone a lot of development since the 1.10 version, most notably the configuration via parameters and /proc/scsi/tmscsim/?. These features are now almost completely implemented for the dc395x_trm driver, too. Status ------ The dc395x_trm is BETA. This means that it might crash your hard disk or fail to read your CD-Rom. It seems to basically work for a lot of cases and success reports have been sent to me. On the other hand, I have a few failure reports, which I was not yet able to resolve. So, don't rely on this driver. Not yet. It is a good idea, to have a BACKUP, if you have valuable data on your disk. If you can't do it, print at least your partition table or save it to a safe place and have a boot floppy ready. Status (2) ---------- The driver works perfectly for my Fireball harddisk but fails sometimes on my IBM DORS and on my IBM DCAS drive and on my Plextor UltraPlex. I have no clue at all, why it happens. I spent a couple of days investigating, creating a driver with extensive sanity checks and debugging possibilities. To no avail! I will look into this again, when I get good docu from Tekram. The one I have currently is lousy. The driver now at least works partially. The following things seem to help: Disallowing disconnection, Sync transfers for the device in question or lowering the Sync speed. Sync speeds of 10MHz or lower seem to work all the time for me. It seems to be related to Sync transfers done via the S/G DMA. The tests being done lead to no conclusion, though. If you find some pattern, please let me know. More hints: The data integrity checks within the driver all succeed. The transfers normally succeed until after some reselections, the device does not finish the DataIn phase. The SCSI Counter says that a certain number of bytes have been transfered (and this number seems to be equal to 0x1000 or at least a multiple of 0x200) successfully and the SCSI FIFO is empty. The DMA engine seems also to approach a block boundary: A Current TransferCtr of 0x208 with a FIFO counter of 0x08 is a typical value. (That happens with reading from the DORS.) The bus is locked up (probably the dev. is waiting for some more ACKs). If the S/G support is limited to one segment, preventing the above to happen, the bus seems to be locked up after a Disconnection, so the next command being sent (TagQ is enabled) fails. Status (3) ---------- It seems to be a matter of the quality of your SCSI bus and the quality of the lnie drivers of the DC395. While the NCR53C8xx drives a bus with 2.5m length and 7 devices without problems at 20MHz, the DC395UW locks up the bus, if driven with more than 10MHz. Using 10MHz max. Sync Frequency, I could not produce problems. Reducing the bus to 1.2m and 3 devices, the DC395UW happily does 13.3MHz. The 20MHz are still not perfect, and I could watch a problem once. (Whereas the bus now should really be perfect for doing high speed transfers.) It's also completely unclear to me, why this problem does not occur, if disconnection is turned off for the fast devices. Then, I can do 20MHz with the DC395UW on the long bus setup. Maybe the chip is extremely sensitive to timing issues, maybe the line drivers are not very good, maybe its input filters are not very good. I did play a little bit with the filter cfg. of the Tekram, but without too much success. Disabling the Active Negation _Enhance_ feature gave a little bit better results, so I did disable it for the driver. You may want to play with the FilterCfg setting yourself, the /proc interface allows to change it. (Bits: 0: Always 1, 1: Active Negation, 2: Fast Filter enable, 3: Data Filter disable, 4: Active Negation enhance) Status (4) ---------- Part of the above said has to be taken back. The driver did still have one serious bug which -- for timing reasons -- only showed on fast transfers and a busy SCSI bus. A FIFO was cleared at the wrong place. Now, the driver seems to work with 20MHz on my system reliably. The hardware is not quite well supporting more than one initiator controller on the bus: If the bus is busy and the TRM_S1040 tries to arbitrate and select a device, it does not always generate an interrupt (which would indicate Disconnection, Selection Timeout, Reselection or -- in the best case -- a phase change). The driver takes this into account now and does not even try. Instead the waiting queue will be woken up by a timer a 50 ms later to try again. Exception handling and automatic downgrading -------------------------------------------- For the positive side: The exception handling procedure (invoked from mid-level SCSI code) does its job pretty well in most of the cases, so your transfers proceed after the SCSI bus has been reset. (No, this won't make you happy, if you are writing to tapes or CDRs, but otherwise, you may be lucky.) In spite of the bus lock ups, I did not loose any data on my harddisks. The driver is clever enough to reduce the settings for the device which caused the bus lockup, so after a few resets the driver will have found the maximum possible speed of your drive. So even with a bad bus, you will be able to use this driver in slow mode. (Use the /proc/scsi interface to try to change the settings again. You may choose to disable disconnections instead of lowering the speed of sync transfers.) Usage ----- I would currently not suggest to use this driver, if you are dealing with important data, which you don't have a backup of! YOU RISK DATA LOSS! OK, you want to use it anyway? Start with read-only access of your data. catting or dding it to /dev/null is a good start. Proceed with read-only filesystem checks (e2fsck -nfF). Produce concurrent load on your SCSI bus. Still no trouble? What does the badblocks program say? (Take care: With -w it will overwrite your data!) Go on, mount rw an unused partition and run bonnie a couple of times. Run it twice concurrently. If you have not seen any problems by now, you might want to take the risk and use it on your normal filesystems. If you find any trouble, you can reduce the Sync Speed and try again. That way, you may find the best safe settings for your bus. Please note that the driver spits out some debug messages from time to time. Those start with "DC395x: Debug:" and are certainly no reason to worry. If you find trouble, you can contact me, of course. Please, don't bother sending useless bug reports saying: It does not work. You should at least be able to provide some details about your SCSI setup, the messages written to the syslog and the outputs of /proc/scsi/scsi and /proc/scsi/dc395x_trm/?. If your driver crashes badly, log via network or a serial console. (The latter is what I do during driver development.) If you can provide me with exact observations and logs of failures, I would be very pleased! Parameters ---------- The driver uses the settings from the EEPROM set in the SCSI BIOS setup. If there is no EEPROM, the driver uses default values. Both can be overriden by command line parameters (module or kernel parameters). [This is new; formerly the EEprom could not be overriden.] The syntax is as follows: dc395x_trm = AdapterID, SpeedIdx, DevMode, AdaptMode, Tags, DelayReset AdapterID : Host Adapter SCSI ID SpeedIdx : 0,1,...7 = 20,13.3,10,8,6.7,5.8,5,4 MHz [ 7] DevMode : Bitmap for Dev Cfg [63] AdaptMode : Bitmap for Adapter Cfg [47] Tags : The number of tags is 1<= 1. If you set AdapterID to -1, the adapter will use conservative ("safe") default settings instead; more precisely, dc395x_trm=-1 is a shortcut for dc395x_trm=7,4,9,15,2,10 If you specify -2 for a value, it will be ignored. You don't need to specify all six parameters. Note, that you can also influence the behaviour of the host adapter at runtime by echoing values to /proc/scsi/dc395x_trm/?. Have a look at README.tmscsim for explanation and examples. The syntax is the same, except for the added "Wide" setting. Installation ------------ As long as this driver is not yet integrated into the mainstream kernel, you have to do some handwork to install the driver. IF YOU NEVER COMPILED A KERNEL YOURSELF BEFORE, YOU SHOULD NOW BETTER GO AND READ SOME DOCUMENTATION ABOUT IT. YOU ARE LIKELY TO SCREW YOURSELF, OTHERWISE. FIRST COMPILE A KERNEL WITHOUT THIS DRIVER AND GET IT TO WORK. Maybe you Linux distributor will be nice enough to include the driver in its distribution, so you don't have to do it yourself. OK, if you want to do it: Get the driver distribution dc395-1??.tar.gz. Unpack it: > tar xvzf dc395-1??.tar.gz Copy the driver files to the linux source tree: > cp -p dc395/dc395x_trm.? /usr/src/linux/drivers/scsi/ > cp -p dc395/README.dc395x /usr/src/linux/drivers/scsi/ and apply the appropriate patch to your kernel source tree. Depending on your kernel version, this is dc395-integ20.diff, dc395-integ22.diff or dc395-integ24.diff. (Replace XX by 20, 22, 23 or 24) > patch -p1 -d /usr/src/linux cd /usr/src/linux > make oldconfig (enable CONFIG_SCSI_DC395x_TRMS1040) > make bzlilo > make modules > make modules_install > depmod -ae NEW: You may be able to skip compilation of the kernel by just using the Makefile. For 2.4 kernels, if you compile outside the kernel source tree, you don't even need to apply a patch to your kernel any more. I will provide a complete patch which makes kernel integration easier and will ask to apply it to the main tree, as soon as I got enough reports about the stability of the driver. Currently, there are still too many problems left :-( Copyright --------- The driver is free software. It is protected by the GNU General Public License (GPL). Please read it, before using this driver. It should be included in your kernel sources and with your distribution. It carries the filename COPYING. If you don't have it, please ask me to send you one by email. Note: The GNU GPL says also something about warranty and liability. Please be aware the following: While I do my best to provide a working and reliable driver, there is a chance, that it will kill your valuable data. I refuse to take any responsibility for that. The driver is provided as-is and YOU USE IT AT YOUR OWN RESPONSIBILITY. Updates ------- Resources for this driver can be found on http://www.garloff.de/kurt/linux/dc395/ ftp://ftp.suse.com/pub/people/garloff/linux/dc395/ (and mirrors, of course) Announcements will be sent to the linux-scsi@vger.kernel.org list. Acknowledgements ---------------- I'd like to thank SuSE GmbH, Nuremberg, to allow me working on this driver during my working hours for them. Thanks to all the people that took the risk to install the driver in its alpha stage and sent detailed bug reports to me, sometimes. Without them, the driver would now not approach stability. They are the reason why free software rules.