blob: fe24ecc6372e6b3482c3f39972ab9f70077d7b70 [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001=============================================================================
2
3 MOXA Smartio Family Device Driver Ver 1.1 Installation Guide
4 for Linux Kernel 2.2.x and 2.0.3x
5 Copyright (C) 1999, Moxa Technologies Co, Ltd.
6=============================================================================
7Content
8
91. Introduction
102. System Requirement
113. Installation
124. Utilities
135. Setserial
146. Troubleshooting
15
16-----------------------------------------------------------------------------
171. Introduction
18
19 The Smartio family Linux driver, Ver. 1.1, supports following multiport
20 boards.
21
22 -C104P/H/HS, C104H/PCI, C104HS/PCI, CI-104J 4 port multiport board.
23 -C168P/H/HS, C168H/PCI 8 port multiport board.
24
25 This driver has been modified a little and cleaned up from the Moxa
26 contributed driver code and merged into Linux 2.2.14pre. In particular
27 official major/minor numbers have been assigned which are different to
28 those the original Moxa supplied driver used.
29
30 This driver and installation procedure have been developed upon Linux Kernel
31 2.2.5 and backward compatible to 2.0.3x. This driver supports Intel x86 and
32 Alpha hardware platform. In order to maintain compatibility, this version
33 has also been properly tested with RedHat, OpenLinux, TurboLinux and
34 S.u.S.E Linux. However, if compatibility problem occurs, please contact
35 Moxa at support@moxa.com.tw.
36
37 In addition to device driver, useful utilities are also provided in this
38 version. They are
39 - msdiag Diagnostic program for detecting installed Moxa Smartio boards.
40 - msmon Monitor program to observe data count and line status signals.
41 - msterm A simple terminal program which is useful in testing serial
42 ports.
43 - io-irq.exe Configuration program to setup ISA boards. Please note that
44 this program can only be executed under DOS.
45
46 All the drivers and utilities are published in form of source code under
47 GNU General Public License in this version. Please refer to GNU General
48 Public License announcement in each source code file for more detail.
49
50 In Moxa's ftp sites, you may always find latest driver at
51 ftp://ftp.moxa.com or ftp://ftp.moxa.com.tw.
52
53 This version of driver can be installed as Loadable Module (Module driver)
54 or built-in into kernel (Static driver). You may refer to following
55 installation procedure for suitable one. Before you install the driver,
56 please refer to hardware installation procedure in the User's Manual.
57
58 We assume the user should be familiar with following documents.
59 - Serial-HOWTO
60 - Kernel-HOWTO
61
62-----------------------------------------------------------------------------
632. System Requirement
64 - Hardware platform: Intel x86 or Alpha machine
65 - Kernel version: 2.0.3x or 2.2.x
66 - gcc version 2.72 or later
67 - Maximum 4 boards can be installed in combination
68
69-----------------------------------------------------------------------------
703. Installation
71
72 3.1 Hardware installation
73
74 There are two types of buses, ISA and PCI, for Smartio family multiport
75 board.
76
77 ISA board
78 ---------
79 You'll have to configure CAP address, I/O address, Interrupt Vector
80 as well as IRQ before installing this driver. Please refer to hardware
81 installation procedure in User's Manual before proceed any further.
82 Please make sure the JP1 is open after the ISA board is set properly.
83
84 PCI board
85 ---------
86 You may need to adjust IRQ usage in BIOS to avoid from IRQ conflict
87 with other ISA devices. Please refer to hardware installation
88 procedure in User's Manual in advance.
89
90 IRQ Sharing
91 -----------
92 Each port within the same multiport board shares the same IRQ. Up to
93 4 Moxa Smartio Family multiport boards can be installed together on
94 one system and they can share the same IRQ.
95
96 3.2 Driver files and device naming convention
97
98 The driver file may be obtained from ftp, CD-ROM or floppy disk. The
99 first step, anyway, is to copy driver file "mxser.tgz" into specified
100 directory. e.g. /moxa. The execute commands as below.
101
102 # cd /moxa
103 # tar xvf /dev/fd0
104 or
105 # cd /moxa
106 # cp /mnt/cdrom/<driver directory>/mxser.tgz .
107 # tar xvfz mxser.tgz
108
109 You may find all the driver and utilities files in /moxa/mxser.
110 Following installation procedure depends on the model you'd like to
111 run the driver. If you prefer module driver, please refer to 3.3.
112 If static driver is required, please refer to 3.4.
113
114 Dialin and callout port
115 -----------------------
116 This driver remains traditional serial device properties. There're
117 two special file name for each serial port. One is dial-in port
118 which is named "ttyMxx". For callout port, the naming convention
119 is "cumxx".
120
121 Device naming when more than 2 boards installed
122 -----------------------------------------------
123 Naming convention for each Smartio multiport board is pre-defined
124 as below.
125
126 Board Num. Dial-in Port Callout port
127 1st board ttyM0 - ttyM7 cum0 - cum7
128 2nd board ttyM8 - ttyM15 cum8 - cum15
129 3rd board ttyM16 - ttyM23 cum16 - cum23
130 4th board ttyM24 - ttym31 cum24 - cum31
131
132 Board sequence
133 --------------
134 This driver will activate ISA boards according to the parameter set
135 in the driver. After all specified ISA board activated, PCI board
136 will be installed in the system automatically driven.
137 Therefore the board number is sorted by the CAP address of ISA boards.
138 For PCI boards, their sequence will be after ISA boards and C168H/PCI
139 has higher priority than C104H/PCI boards.
140
141 3.3 Module driver configuration
142 Module driver is easiest way to install. If you prefer static driver
143 installation, please skip this paragraph.
144 1. Find "Makefile" in /moxa/mxser, then run
145
146 # make install
147
148 The driver files "mxser.o" and utilities will be properly compiled
149 and copied to system directories respectively.Then run
150
151 # insmod mxser
152
153 to activate the modular driver. You may run "lsmod" to check
154 if "mxser.o" is activated.
155
156 2. Create special files by executing "msmknod".
157 # cd /moxa/mxser/driver
158 # ./msmknod
159
160 Default major numbers for dial-in device and callout device are
161 174, 175. Msmknod will delete any special files occupying the same
162 device naming.
163
164 3. Up to now, you may manually execute "insmod mxser" to activate
165 this driver and run "rmmod mxser" to remove it. However, it's
166 better to have a boot time configuration to eliminate manual
167 operation.
168 Boot time configuration can be achieved by rc file. Run following
169 command for setting rc files.
170
171 # cd /moxa/mxser/driver
172 # cp ./rc.mxser /etc/rc.d
173 # cd /etc/rc.d
174
175 You may have to modify part of the content in rc.mxser to specify
176 parameters for ISA board. Please refer to rc.mxser for more detail.
177 Find "rc.serial". If "rc.serial" doesn't exist, create it by vi.
178 Add "rc.mxser" in last line. Next, open rc.local by vi
179 and append following content.
180
181 if [ -f /etc/rc.d/rc.serial ]; then
182 sh /etc/rc.d/rc.serial
183 fi
184
185 4. Reboot and check if mxser.o activated by "lsmod" command.
186 5. If you'd like to drive Smartio ISA boards in the system, you'll
187 have to add parameter to specify CAP address of given board while
188 activating "mxser.o". The format for parameters are as follows.
189
190 insmod mxser ioaddr=0x???,0x???,0x???,0x???
191 | | | |
192 | | | +- 4th ISA board
193 | | +------ 3rd ISA board
194 | +------------ 2nd ISA board
195 +------------------- 1st ISA board
196
197 3.4 Static driver configuration
198
199 1. Create link
200 # cd /usr/src/linux/drivers/char
201 # ln -s /moxa/mxser/driver/mxser.c mxser.c
202
203 2. Add CAP address list for ISA boards
204 In module mode, the CAP address for ISA board is given by
205 parameter. In static driver configuration, you'll have to
206 assign it within driver's source code. If you will not
207 install any ISA boards, you may skip to next portion.
208 The instructions to modify driver source code are as
209 below.
210 a. # cd /moxa/mxser/driver
211 # vi mxser.c
212 b. Find the array mxserBoardCAP[] as below.
213
214 static int mxserBoardCAP[]
215 = {0x00, 0x00, 0x00, 0x00};
216
217 c. Change the address within this array using vi. For
218 example, to driver 2 ISA boards with CAP address
219 0x280 and 0x180 as 1st and 2nd board. Just to change
220 the source code as follows.
221
222 static int mxserBoardCAP[]
223 = {0x280, 0x180, 0x00, 0x00};
224
225 3. Modify tty_io.c
226 # cd /usr/src/linux/drivers/char/
227 # vi tty_io.c
228 Find pty_init(), insert "mxser_init()" as
229
230 pty_init();
231 mxser_init();
232
233 4. Modify tty.h
234 # cd /usr/src/linux/include/linux
235 # vi tty.h
236 Find extern int tty_init(void), insert "mxser_init()" as
237
238 extern int tty_init(void);
239 extern int mxser_init(void);
240
241 5. Modify Makefile
242 # cd /usr/src/linux/drivers/char
243 # vi Makefile
244 Find L_OBJS := tty_io.o ...... random.o, add
245 "mxser.o" at last of this line as
246 L_OBJS := tty_io.o ....... mxser.o
247
248 6. Rebuild kernel
249 The following are for Linux kernel rebuilding,for your reference only.
250 For appropriate details, please refer to the Linux document.
251
252 If 'lilo' utility is installed, please use 'make zlilo' to rebuild
253 kernel. If 'lilo' is not installed, please follow the following steps.
254
255 a. cd /usr/src/linux
256 b. make clean /* take a few minutes */
257 c. make bzImage /* take probably 10-20 minutes */
258 d. Backup original boot kernel. /* optional step */
259 e. cp /usr/src/linux/arch/i386/boot/bzImage /boot/vmlinuz
260 f. Please make sure the boot kernel (vmlinuz) is in the
261 correct position. If you use 'lilo' utility, you should
262 check /etc/lilo.conf 'image' item specified the path
263 which is the 'vmlinuz' path, or you will load wrong
264 (or old) boot kernel image (vmlinuz).
265 g. chmod 400 /vmlinuz
266 h. lilo
267 i. rdev -R /vmlinuz 1
268 j. sync
269
270 Note that if the result of "make zImage" is ERROR, then you have to
271 go back to Linux configuration Setup. Type "make config" in directory
272 /usr/src/linux or "setup".
273
274 Since system include file, /usr/src/linux/include/linux/interrupt.h,
275 is modified each time the MOXA driver is installed, kernel rebuilding
276 is inevitable. And it takes about 10 to 20 minutes depends on the
277 machine.
278
279 7. Make utility
280 # cd /moxa/mxser/utility
281 # make install
282
283 8. Make special file
284 # cd /moxa/mxser/driver
285 # ./msmknod
286
287 9. Reboot
288
289 3.5 Custom configuration
290 Although this driver already provides you default configuration, you
291 still can change the device name and major number.The instruction to
292 change these parameters are shown as below.
293
294 Change Device name
295 ------------------
296 If you'd like to use other device names instead of default naming
297 convention, all you have to do is to modify the internal code
298 within the shell script "msmknod". First, you have to open "msmknod"
299 by vi. Locate each line contains "ttyM" and "cum" and change them
300 to the device name you desired. "msmknod" creates the device names
301 you need next time executed.
302
303 Change Major number
304 -------------------
305 If major number 30 and 35 had been occupied, you may have to select
306 2 free major numbers for this driver. There are 3 steps to change
307 major numbers.
308
309 1. Find free major numbers
310 In /proc/devices, you may find all the major numbers occupied
311 in the system. Please select 2 major numbers that are available.
312 e.g. 40, 45.
313 2. Create special files
314 Run /moxa/mxser/driver/msmknod to create special files with
315 specified major numbers.
316 3. Modify driver with new major number
317 Run vi to open /moxa/mxser/driver/mxser.c. Locate the line
318 contains "MXSERMAJOR". Change the content as below.
319 #define MXSERMAJOR 40
320 #define MXSERCUMAJOR 45
321 4. Run # make install in /moxa/mxser/driver.
322
323 3.6 Verify driver installation
324 You may refer to /var/log/messages to check the latest status
325 log reported by this driver whenever it's activated.
326-----------------------------------------------------------------------------
3274. Utilities
328 There are 3 utilities contained in this driver. They are msdiag, msmon and
329 msterm. These 3 utilities are released in form of source code. They should
330 be compiled into executable file and copied into /usr/bin.
331
332 msdiag - Diagnostic
333 --------------------
334 This utility provides the function to detect what Moxa Smartio multiport
335 board exists in the system.
336
337 msmon - Port Monitoring
338 -----------------------
339 This utility gives the user a quick view about all the MOXA ports'
340 activities. One can easily learn each port's total received/transmitted
341 (Rx/Tx) character count since the time when the monitoring is started.
342 Rx/Tx throughputs per second are also reported in interval basis (e.g.
343 the last 5 seconds) and in average basis (since the time the monitoring
344 is started). You can reset all ports' count by <HOME> key. <+> <->
345 (plus/minus) keys to change the displaying time interval. Press <ENTER>
346 on the port, that cursor stay, to view the port's communication
347 parameters, signal status, and input/output queue.
348
349 msterm - Terminal Emulation
350 ---------------------------
351 This utility provides data sending and receiving ability of all tty ports,
352 especially for MOXA ports. It is quite useful for testing simple
353 application, for example, sending AT command to a modem connected to the
354 port or used as a terminal for login purpose. Note that this is only a
355 dumb terminal emulation without handling full screen operation.
356-----------------------------------------------------------------------------
3575. Setserial
358
359 Supported Setserial parameters are listed as below.
360
361 uart set UART type(16450-->disable FIFO, 16550A-->enable FIFO)
362 close_delay set the amount of time(in 1/100 of a second) that DTR
363 should be kept low while being closed.
364 closing_wait set the amount of time(in 1/100 of a second) that the
365 serial port should wait for data to be drained while
366 being closed, before the receiver is disable.
367 spd_hi Use 57.6kb when the application requests 38.4kb.
368 spd_vhi Use 115.2kb when the application requests 38.4kb.
369 spd_normal Use 38.4kb when the application requests 38.4kb.
370
371-----------------------------------------------------------------------------
3726. Troubleshooting
373
374 The boot time error messages and solutions are stated as clearly as
375 possible. If all the possible solutions fail, please contact our technical
376 support team to get more help.
377
378 Error msg: More than 4 Moxa Smartio family boards found. Fifth board and
379 after are ignored.
380 Solution:
381 To avoid this problem, please unplug fifth and after board, because Moxa
382 driver supports up to 4 boards.
383
384 Error msg: Request_irq fail, IRQ(?) may be conflict with another device.
385 Solution:
386 Other PCI or ISA devices occupy the assigned IRQ. If you are not sure
387 which device causes the situation,please check /proc/interrupts to find
388 free IRQ and simply change another free IRQ for Moxa board.
389
390 Error msg: Board #: C1xx Series(CAP=xxx) interrupt number invalid.
391 Solution:
392 Each port within the same multiport board shares the same IRQ. Please set
393 one IRQ (IRQ doesn't equal to zero) for one Moxa board.
394
395 Error msg: No interrupt vector be set for Moxa ISA board(CAP=xxx).
396 Solution:
397 Moxa ISA board needs an interrupt vector.Please refer to user's manual
398 "Hardware Installation" chapter to set interrupt vector.
399
400 Error msg: Couldn't install MOXA Smartio family driver!
401 Solution:
402 Load Moxa driver fail, the major number may conflict with other devices.
403 Please refer to previous section 3.5 to change a free major number for
404 Moxa driver.
405
406 Error msg: Couldn't install MOXA Smartio family callout driver!
407 Solution:
408 Load Moxa callout driver fail, the callout device major number may
409 conflict with other devices. Please refer to previous section 3.5 to
410 change a free callout device major number for Moxa driver.
411-----------------------------------------------------------------------------