About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / stallion.txt


Based on kernel version 2.6.27. Page generated on 2008-10-13 09:54 EST.

1	* NOTE - This is an unmaintained driver.  Lantronix, which bought Stallion
2	technologies, is not active in driver maintenance, and they have no information
3	on when or if they will have a 2.6 driver.
4	
5	James Nelson <james4765[AT]gmail[DOT]com> - 12-12-2004
6	
7	Stallion Multiport Serial Driver Readme
8	---------------------------------------
9	
10	Copyright (C) 1994-1999,  Stallion Technologies.
11	
12	Version:   5.5.1
13	Date:      28MAR99
14	
15	
16	
17	1. INTRODUCTION
18	
19	There are two drivers that work with the different families of Stallion
20	multiport serial boards. One is for the Stallion smart boards - that is
21	EasyIO, EasyConnection 8/32 and EasyConnection 8/64-PCI, the other for
22	the true Stallion intelligent multiport boards - EasyConnection 8/64
23	(ISA, EISA, MCA), EasyConnection/RA-PCI, ONboard and Brumby.
24	
25	If you are using any of the Stallion intelligent multiport boards (Brumby,
26	ONboard, EasyConnection 8/64 (ISA, EISA, MCA), EasyConnection/RA-PCI) with
27	Linux you will need to get the driver utility package.  This contains a
28	firmware loader and the firmware images necessary to make the devices operate.
29	
30	The Stallion Technologies ftp site, ftp.stallion.com, will always have
31	the latest version of the driver utility package.
32	
33	ftp://ftp.stallion.com/drivers/ata5/Linux/ata-linux-550.tar.gz
34	
35	As of the printing of this document the latest version of the driver
36	utility package is 5.5.0. If a later version is now available then you
37	should use the latest version.
38	
39	If you are using the EasyIO, EasyConnection 8/32 or EasyConnection 8/64-PCI
40	boards then you don't need this package, although it does have a serial stats
41	display program.
42	
43	If you require DIP switch settings, EISA or MCA configuration files, or any
44	other information related to Stallion boards then have a look at Stallion's
45	web pages at http://www.stallion.com.
46	
47	
48	
49	2. INSTALLATION
50	
51	The drivers can be used as loadable modules or compiled into the kernel.
52	You can choose which when doing a "config" on the kernel.
53	
54	All ISA, EISA and MCA boards that you want to use need to be configured into
55	the driver(s). All PCI boards will be automatically detected when you load
56	the driver - so they do not need to be entered into the driver(s)
57	configuration structure. Note that kernel PCI support is required to use PCI
58	boards.
59	
60	There are two methods of configuring ISA, EISA and MCA boards into the drivers.
61	If using the driver as a loadable module then the simplest method is to pass
62	the driver configuration as module arguments. The other method is to modify
63	the driver source to add configuration lines for each board in use.
64	
65	If you have pre-built Stallion driver modules then the module argument
66	configuration method should be used. A lot of Linux distributions come with
67	pre-built driver modules in /lib/modules/X.Y.Z/misc for the kernel in use.
68	That makes things pretty simple to get going.
69	
70	
71	2.1 MODULE DRIVER CONFIGURATION:
72	
73	The simplest configuration for modules is to use the module load arguments
74	to configure any ISA, EISA or MCA boards. PCI boards are automatically
75	detected, so do not need any additional configuration at all.
76	
77	If using EasyIO, EasyConnection 8/32 ISA or MCA, or EasyConnection 8/63-PCI
78	boards then use the "stallion" driver module, Otherwise if you are using
79	an EasyConnection 8/64 ISA, EISA or MCA, EasyConnection/RA-PCI, ONboard,
80	Brumby or original Stallion board then use the "istallion" driver module.
81	
82	Typically to load up the smart board driver use:
83	
84	    modprobe stallion
85	
86	This will load the EasyIO and EasyConnection 8/32 driver. It will output a
87	message to say that it loaded and print the driver version number. It will
88	also print out whether it found the configured boards or not. These messages
89	may not appear on the console, but typically are always logged to
90	/var/adm/messages or /var/log/syslog files - depending on how the klogd and
91	syslogd daemons are setup on your system.
92	
93	To load the intelligent board driver use:
94	
95	    modprobe istallion
96	
97	It will output similar messages to the smart board driver.
98	
99	If not using an auto-detectable board type (that is a PCI board) then you
100	will also need to supply command line arguments to the modprobe command
101	when loading the driver. The general form of the configuration argument is
102	
103	    board?=<name>[,<ioaddr>[,<addr>][,<irq>]]
104	
105	where:
106	
107	    board?  -- specifies the arbitrary board number of this board,
108	               can be in the range 0 to 3.
109	
110	    name    -- textual name of this board. The board name is the common
111	               board name, or any "shortened" version of that. The board
112	               type number may also be used here.
113	
114	    ioaddr  -- specifies the I/O address of this board. This argument is
115	               optional, but should generally be specified.
116	
117	    addr    -- optional second address argument. Some board types require
118	               a second I/O address, some require a memory address. The
119	               exact meaning of this argument depends on the board type.
120	
121	    irq     -- optional IRQ line used by this board.
122	
123	Up to 4 board configuration arguments can be specified on the load line.
124	Here is some examples:
125	
126	    modprobe stallion board0=easyio,0x2a0,5
127	
128	This configures an EasyIO board as board 0 at I/O address 0x2a0 and IRQ 5.
129	
130	    modprobe istallion board3=ec8/64,0x2c0,0xcc000
131	
132	This configures an EasyConnection 8/64 ISA as board 3 at I/O address 0x2c0 at
133	memory address 0xcc000.
134	
135	    modprobe stallion board1=ec8/32-at,0x2a0,0x280,10
136	
137	This configures an EasyConnection 8/32 ISA board at primary I/O address 0x2a0,
138	secondary address 0x280 and IRQ 10.
139	
140	You will probably want to enter this module load and configuration information
141	into your system startup scripts so that the drivers are loaded and configured
142	on each system boot. Typically the start up script would be something like
143	/etc/modprobe.conf.
144	
145	
146	2.2 STATIC DRIVER CONFIGURATION:
147	
148	For static driver configuration you need to modify the driver source code.
149	Entering ISA, EISA and MCA boards into the driver(s) configuration structure
150	involves editing the driver(s) source file. It's pretty easy if you follow
151	the instructions below. Both drivers can support up to 4 boards. The smart
152	card driver (the stallion.c driver) supports any combination of EasyIO and
153	EasyConnection 8/32 boards (up to a total of 4). The intelligent driver
154	supports any combination of ONboards, Brumbys, Stallions and EasyConnection
155	8/64 (ISA and EISA) boards (up to a total of 4).
156	
157	To set up the driver(s) for the boards that you want to use you need to
158	edit the appropriate driver file and add configuration entries.
159	
160	If using EasyIO or EasyConnection 8/32 ISA or MCA boards,
161	   In drivers/char/stallion.c:
162	      - find the definition of the stl_brdconf array (of structures)
163	        near the top of the file
164	      - modify this to match the boards you are going to install
165		(the comments before this structure should help)
166	      - save and exit
167	
168	If using ONboard, Brumby, Stallion or EasyConnection 8/64 (ISA or EISA)
169	boards,
170	   In drivers/char/istallion.c:
171	      - find the definition of the stli_brdconf array (of structures)
172	        near the top of the file
173	      - modify this to match the boards you are going to install
174		(the comments before this structure should help)
175	      - save and exit
176	
177	Once you have set up the board configurations then you are ready to build
178	the kernel or modules.
179	
180	When the new kernel is booted, or the loadable module loaded then the
181	driver will emit some kernel trace messages about whether the configured
182	boards were detected or not. Depending on how your system logger is set
183	up these may come out on the console, or just be logged to
184	/var/adm/messages or /var/log/syslog. You should check the messages to
185	confirm that all is well.
186	
187	
188	2.3 SHARING INTERRUPTS
189	
190	It is possible to share interrupts between multiple EasyIO and
191	EasyConnection 8/32 boards in an EISA system. To do this you must be using
192	static driver configuration, modifying the driver source code to add driver
193	configuration. Then a couple of extra things are required:
194	
195	1. When entering the board resources into the stallion.c file you need to
196	   mark the boards as using level triggered interrupts. Do this by replacing
197	   the "0" entry at field position 6 (the last field) in the board
198	   configuration structure with a "1". (This is the structure that defines
199	   the board type, I/O locations, etc. for each board). All boards that are
200	   sharing an interrupt must be set this way, and each board should have the
201	   same interrupt number specified here as well. Now build the module or
202	   kernel as you would normally.
203	
204	2. When physically installing the boards into the system you must enter
205	   the system EISA configuration utility. You will need to install the EISA
206	   configuration files for *all* the EasyIO and EasyConnection 8/32 boards
207	   that are sharing interrupts. The Stallion EasyIO and EasyConnection 8/32
208	   EISA configuration files required are supplied by Stallion Technologies
209	   on the EASY Utilities floppy diskette (usually supplied in the box with
210	   the board when purchased. If not, you can pick it up from Stallion's FTP
211	   site, ftp.stallion.com). You will need to edit the board resources to
212	   choose level triggered interrupts, and make sure to set each board's
213	   interrupt to the same IRQ number.
214	
215	You must complete both the above steps for this to work. When you reboot
216	or load the driver your EasyIO and EasyConnection 8/32 boards will be
217	sharing interrupts.
218	
219	
220	2.4 USING HIGH SHARED MEMORY
221	
222	The EasyConnection 8/64-EI, ONboard and Stallion boards are capable of
223	using shared memory addresses above the usual 640K - 1Mb range. The ONboard
224	ISA and the Stallion boards can be programmed to use memory addresses up to
225	16Mb (the ISA bus addressing limit), and the EasyConnection 8/64-EI and
226	ONboard/E can be programmed for memory addresses up to 4Gb (the EISA bus
227	addressing limit).
228	
229	The higher than 1Mb memory addresses are fully supported by this driver.
230	Just enter the address as you normally would for a lower than 1Mb address
231	(in the driver's board configuration structure).
232	
233	
234	
235	2.5 TROUBLE SHOOTING
236	
237	If a board is not found by the driver but is actually in the system then the
238	most likely problem is that the I/O address is wrong. Change the module load
239	argument for the loadable module form. Or change it in the driver stallion.c
240	or istallion.c configuration structure and rebuild the kernel or modules, or
241	change it on the board.
242	
243	On EasyIO and EasyConnection 8/32 boards the IRQ is software programmable, so
244	if there is a conflict you may need to change the IRQ used for a board. There
245	are no interrupts to worry about for ONboard, Brumby or EasyConnection 8/64
246	(ISA, EISA and MCA) boards. The memory region on EasyConnection 8/64 and
247	ONboard boards is software programmable, but not on the Brumby boards.
248	
249	
250	
251	3. USING THE DRIVERS
252	
253	3.1 INTELLIGENT DRIVER OPERATION
254	
255	The intelligent boards also need to have their "firmware" code downloaded
256	to them. This is done via a user level application supplied in the driver
257	utility package called "stlload". Compile this program wherever you dropped
258	the package files, by typing "make". In its simplest form you can then type
259	
260	    ./stlload -i cdk.sys
261	
262	in this directory and that will download board 0 (assuming board 0 is an
263	EasyConnection 8/64 or EasyConnection/RA board). To download to an
264	ONboard, Brumby or Stallion do:
265	
266	    ./stlload -i 2681.sys
267	
268	Normally you would want all boards to be downloaded as part of the standard
269	system startup. To achieve this, add one of the lines above into the
270	/etc/rc.d/rc.S or /etc/rc.d/rc.serial file. To download each board just add
271	the "-b <brd-number>" option to the line. You will need to download code for
272	every board. You should probably move the stlload program into a system
273	directory, such as /usr/sbin. Also, the default location of the cdk.sys image
274	file in the stlload down-loader is /usr/lib/stallion. Create that directory
275	and put the cdk.sys and 2681.sys files in it. (It's a convenient place to put
276	them anyway). As an example your /etc/rc.d/rc.S file might have the
277	following lines added to it (if you had 3 boards):
278	
279	    /usr/sbin/stlload -b 0 -i /usr/lib/stallion/cdk.sys
280	    /usr/sbin/stlload -b 1 -i /usr/lib/stallion/2681.sys
281	    /usr/sbin/stlload -b 2 -i /usr/lib/stallion/2681.sys
282	
283	The image files cdk.sys and 2681.sys are specific to the board types. The
284	cdk.sys will only function correctly on an EasyConnection 8/64 board. Similarly
285	the 2681.sys image fill only operate on ONboard, Brumby and Stallion boards.
286	If you load the wrong image file into a board it will fail to start up, and
287	of course the ports will not be operational!
288	
289	If you are using the modularized version of the driver you might want to put
290	the modprobe calls in the startup script as well (before the download lines
291	obviously).
292	
293	
294	3.2 USING THE SERIAL PORTS
295	
296	Once the driver is installed you will need to setup some device nodes to
297	access the serial ports. The simplest method is to use the /dev/MAKEDEV program.
298	It will automatically create device entries for Stallion boards. This will
299	create the normal serial port devices as /dev/ttyE# where# is the port number
300	starting from 0. A bank of 64 minor device numbers is allocated to each board,
301	so the first port on the second board is port 64,etc. A set of callout type
302	devices may also be created. They are created as the devices /dev/cue# where #
303	is the same as for the ttyE devices.
304	
305	For the most part the Stallion driver tries to emulate the standard PC system
306	COM ports and the standard Linux serial driver. The idea is that you should
307	be able to use Stallion board ports and COM ports interchangeably without
308	modifying anything but the device name. Anything that doesn't work like that
309	should be considered a bug in this driver!
310	
311	If you look at the driver code you will notice that it is fairly closely
312	based on the Linux serial driver (linux/drivers/char/serial.c). This is
313	intentional, obviously this is the easiest way to emulate its behavior!
314	
315	Since this driver tries to emulate the standard serial ports as much as
316	possible, most system utilities should work as they do for the standard
317	COM ports. Most importantly "stty" works as expected and "setserial" can
318	also be used (excepting the ability to auto-configure the I/O and IRQ
319	addresses of boards). Higher baud rates are supported in the usual fashion
320	through setserial or using the CBAUDEX extensions. Note that the EasyIO and
321	EasyConnection (all types) support at least 57600 and 115200 baud. The newer
322	EasyConnection XP modules and new EasyIO boards support 230400 and 460800
323	baud as well. The older boards including ONboard and Brumby support a
324	maximum baud rate of 38400.
325	
326	If you are unfamiliar with how to use serial ports, then get the Serial-HOWTO
327	by Greg Hankins. It will explain everything you need to know!
328	
329	
330	
331	4. NOTES
332	
333	You can use both drivers at once if you have a mix of board types installed
334	in a system. However to do this you will need to change the major numbers
335	used by one of the drivers. Currently both drivers use major numbers 24, 25
336	and 28 for their devices. Change one driver to use some other major numbers,
337	and then modify the mkdevnods script to make device nodes based on those new
338	major numbers. For example, you could change the istallion.c driver to use
339	major numbers 60, 61 and 62. You will also need to create device nodes with
340	different names for the ports, for example ttyF# and cuf#.
341	
342	The original Stallion board is no longer supported by Stallion Technologies.
343	Although it is known to work with the istallion driver.
344	
345	Finding a free physical memory address range can be a problem. The older
346	boards like the Stallion and ONboard need large areas (64K or even 128K), so
347	they can be very difficult to get into a system. If you have 16 Mb of RAM
348	then you have no choice but to put them somewhere in the 640K -> 1Mb range.
349	ONboards require 64K, so typically 0xd0000 is good, or 0xe0000 on some
350	systems. If you have an original Stallion board, "V4.0" or Rev.O, then you
351	need a 64K memory address space, so again 0xd0000 and 0xe0000 are good.
352	Older Stallion boards are a much bigger problem. They need 128K of address
353	space and must be on a 128K boundary. If you don't have a VGA card then
354	0xc0000 might be usable - there is really no other place you can put them
355	below 1Mb.
356	
357	Both the ONboard and old Stallion boards can use higher memory addresses as
358	well, but you must have less than 16Mb of RAM to be able to use them. Usual
359	high memory addresses used include 0xec0000 and 0xf00000.
360	
361	The Brumby boards only require 16Kb of address space, so you can usually
362	squeeze them in somewhere. Common addresses are 0xc8000, 0xcc000, or in
363	the 0xd0000 range. EasyConnection 8/64 boards are even better, they only
364	require 4Kb of address space, again usually 0xc8000, 0xcc000 or 0xd0000
365	are good.
366	
367	If you are using an EasyConnection 8/64-EI or ONboard/E then usually the
368	0xd0000 or 0xe0000 ranges are the best options below 1Mb. If neither of
369	them can be used then the high memory support to use the really high address
370	ranges is the best option. Typically the 2Gb range is convenient for them,
371	and gets them well out of the way.
372	
373	The ports of the EasyIO-8M board do not have DCD or DTR signals. So these
374	ports cannot be used as real modem devices. Generally, when using these
375	ports you should only use the cueX devices.
376	
377	The driver utility package contains a couple of very useful programs. One 
378	is a serial port statistics collection and display program - very handy
379	for solving serial port problems. The other is an extended option setting
380	program that works with the intelligent boards.
381	
382	
383	
384	5. DISCLAIMER
385	
386	The information contained in this document is believed to be accurate and
387	reliable. However, no responsibility is assumed by Stallion Technologies
388	Pty. Ltd. for its use, nor any infringements of patents or other rights
389	of third parties resulting from its use. Stallion Technologies reserves
390	the right to modify the design of its products and will endeavour to change
391	the information in manuals and accompanying documentation accordingly.
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog