About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / scsi / tmscsim.txt




Custom Search

Based on kernel version 4.1. Page generated on 2015-06-28 12:14 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 $
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.