blob: d1526eba264571589dd3b5f06e0e5fa002daebeb [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001
2 COMX drivers for the 2.2 kernel
3
4Originally written by: Tivadar Szemethy, <tiv@itc.hu>
5Currently maintained by: Gergely Madarasz <gorgo@itc.hu>
6
7Last change: 21/06/1999.
8
9INTRODUCTION
10
11This document describes the software drivers and their use for the
12COMX line of synchronous serial adapters for Linux version 2.2.0 and
13above.
14The cards are produced and sold by ITC-Pro Ltd. Budapest, Hungary
15For further info contact <info@itc.hu>
16or http://www.itc.hu (mostly in Hungarian).
17The firmware files and software are available from ftp://ftp.itc.hu
18
19Currently, the drivers support the following cards and protocols:
20
21COMX (2x64 kbps intelligent board)
22CMX (1x256 + 1x128 kbps intelligent board)
23HiCOMX (2x2Mbps intelligent board)
24LoCOMX (1x512 kbps passive board)
25MixCOM (1x512 or 2x512kbps passive board with a hardware watchdog an
26 optional BRI interface and optional flashROM (1-32M))
27SliceCOM (1x2Mbps channelized E1 board)
28PciCOM (X21)
29
30At the moment of writing this document, the (Cisco)-HDLC, LAPB, SyncPPP and
31Frame Relay (DTE, rfc1294 IP encapsulation with partially implemented Q933a
32LMI) protocols are available as link-level protocol.
33X.25 support is being worked on.
34
35USAGE
36
37Load the comx.o module and the hardware-specific and protocol-specific
38modules you'll need into the running kernel using the insmod utility.
39This creates the /proc/comx directory.
40See the example scripts in the 'etc' directory.
41
42/proc INTERFACE INTRO
43
44The COMX driver set has a new type of user interface based on the /proc
45filesystem which eliminates the need for external user-land software doing
46IOCTL calls.
47Each network interface or device (i.e. those ones you configure with 'ifconfig'
48and 'route' etc.) has a corresponding directory under /proc/comx. You can
49dynamically create a new interface by saying 'mkdir /proc/comx/comx0' (or you
50can name it whatever you want up to 8 characters long, comx[n] is just a
51convention).
52Generally the files contained in these directories are text files, which can
53be viewed by 'cat filename' and you can write a string to such a file by
54saying 'echo _string_ >filename'. This is very similar to the sysctl interface.
55Don't use a text editor to edit these files, always use 'echo' (or 'cat'
56where appropriate).
57When you've created the comx[n] directory, two files are created automagically
58in it: 'boardtype' and 'protocol'. You have to fill in these files correctly
59for your board and protocol you intend to use (see the board and protocol
60descriptions in this file below or the example scripts in the 'etc' directory).
61After filling in these files, other files will appear in the directory for
62setting the various hardware- and protocol-related informations (for example
63irq and io addresses, keepalive values etc.) These files are set to default
64values upon creation, so you don't necessarily have to change all of them.
65
66When you're ready with filling in the files in the comx[n] directory, you can
67configure the corresponding network interface with the standard network
68configuration utilities. If you're unable to bring the interfaces up, look up
69the various kernel log files on your system, and consult the messages for
70a probable reason.
71
72EXAMPLE
73
74To create the interface 'comx0' which is the first channel of a COMX card:
75
76insmod comx
77# insmod comx-hw-comx ; insmod comx-proto-ppp (these are usually
78autoloaded if you use the kernel module loader)
79
80mkdir /proc/comx/comx0
81echo comx >/proc/comx/comx0/boardtype
82echo 0x360 >/proc/comx/comx0/io <- jumper-selectable I/O port
83echo 0x0a >/proc/comx/comx0/irq <- jumper-selectable IRQ line
84echo 0xd000 >/proc/comx/comx0/memaddr <- software-configurable memory
85 address. COMX uses 64 KB, and this
86 can be: 0xa000, 0xb000, 0xc000,
87 0xd000, 0xe000. Avoid conflicts
88 with other hardware.
89cat </etc/siol1.rom >/proc/comx/comx0/firmware <- the firmware for the card
90echo HDLC >/proc/comx/comx0/protocol <- the data-link protocol
91echo 10 >/proc/comx/comx0/keepalive <- the keepalive for the protocol
92ifconfig comx0 1.2.3.4 pointopoint 5.6.7.8 netmask 255.255.255.255 <-
93 finally configure it with ifconfig
94Check its status:
95cat /proc/comx/comx0/status
96
97If you want to use the second channel of this board:
98
99mkdir /proc/comx/comx1
100echo comx >/proc/comx/comx1/boardtype
101echo 0x360 >/proc/comx/comx1/io
102echo 10 >/proc/comx/comx1/irq
103echo 0xd000 >/proc/comx/comx1/memaddr
104echo 1 >/proc/comx/comx1/channel <- channels are numbered
105 as 0 (default) and 1
106
107Now, check if the driver recognized that you're going to use the other
108channel of the same adapter:
109
110cat /proc/comx/comx0/twin
111comx1
112cat /proc/comx/comx1/twin
113comx0
114
115You don't have to load the firmware twice, if you use both channels of
116an adapter, just write it into the channel 0's /proc firmware file.
117
118Default values: io 0x360 for COMX, 0x320 (HICOMX), irq 10, memaddr 0xd0000
119
120THE LOCOMX HARDWARE DRIVER
121
122The LoCOMX driver doesn't require firmware, and it doesn't use memory either,
123but it uses DMA channels 1 and 3. You can set the clock rate (if enabled by
124jumpers on the board) by writing the kbps value into the file named 'clock'.
125Set it to 'external' (it is the default) if you have external clock source.
126
127(Note: currently the LoCOMX driver does not support the internal clock)
128
129THE COMX, CMX AND HICOMX DRIVERS
130
131On the HICOMX, COMX and CMX, you have to load the firmware (it is different for
132the three cards!). All these adapters can share the same memory
133address (we usually use 0xd0000). On the CMX you can set the internal
134clock rate (if enabled by jumpers on the small adapter boards) by writing
135the kbps value into the 'clock' file. You have to do this before initializing
136the card. If you use both HICOMX and CMX/COMX cards, initialize the HICOMX
137first. The I/O address of the HICOMX board is not configurable by any
138method available to the user: it is hardwired to 0x320, and if you have to
139change it, consult ITC-Pro Ltd.
140
141THE MIXCOM DRIVER
142
143The MixCOM board doesn't require firmware, the driver communicates with
144it through I/O ports. You can have three of these cards in one machine.
145
146THE SLICECOM DRIVER
147
148The SliceCOM board doesn't require firmware. You can have 4 of these cards
149in one machine. The driver doesn't (yet) support shared interrupts, so
150you will need a separate IRQ line for every board.
151Read Documentation/networking/slicecom.txt for help on configuring
152this adapter.
153
154THE HDLC/PPP LINE PROTOCOL DRIVER
155
156The HDLC/SyncPPP line protocol driver uses the kernel's built-in syncppp
157driver (syncppp.o). You don't have to manually select syncppp.o when building
158the kernel, the dependencies compile it in automatically.
159
160
161
162
163EXAMPLE
164(setting up hw parameters, see above)
165
166# using HDLC:
167echo hdlc >/proc/comx/comx0/protocol
168echo 10 >/proc/comx/comx0/keepalive <- not necessary, 10 is the default
169ifconfig comx0 1.2.3.4 pointopoint 5.6.7.8 netmask 255.255.255.255
170
171(setting up hw parameters, see above)
172
173# using PPP:
174echo ppp >/proc/comx/comx0/protocol
175ifconfig comx0 up
176ifconfig comx0 1.2.3.4 pointopoint 5.6.7.8 netmask 255.255.255.255
177
178
179THE LAPB LINE PROTOCOL DRIVER
180
181For this, you'll need to configure LAPB support (See 'LAPB Data Link Driver' in
182'Network options' section) into your kernel (thanks to Jonathan Naylor for his
183excellent implementation).
184comx-proto-lapb.o provides the following files in the appropriate directory
185(the default values in parens): t1 (5), t2 (1), n2 (20), mode (DTE, STD) and
186window (7). Agree with the administrator of your peer router on these
187settings (most people use defaults, but you have to know if you are DTE or
188DCE).
189
190EXAMPLE
191
192(setting up hw parameters, see above)
193echo lapb >/proc/comx/comx0/protocol
194echo dce >/proc/comx/comx0/mode <- DCE interface in this example
195ifconfig comx0 1.2.3.4 pointopoint 5.6.7.8 netmask 255.255.255.255
196
197
198THE FRAME RELAY PROTOCOL DRIVER
199
200You DON'T need any other frame relay related modules from the kernel to use
201COMX-Frame Relay. This protocol is a bit more complicated than the others,
202because it allows to use 'subinterfaces' or DLCIs within one physical device.
203First you have to create the 'master' device (the actual physical interface)
204as you would do for other protocols. Specify 'frad' as protocol type.
205Now you can bring this interface up by saying 'ifconfig comx0 up' (or whatever
206you've named the interface). Do not assign any IP address to this interface
207and do not set any routes through it.
208Then, set up your DLCIs the following way: create a comx interface for each
209DLCI you intend to use (with mkdir), and write 'dlci' to the 'boardtype' file,
210and 'ietf-ip' to the 'protocol' file. Currently, the only supported
211encapsulation type is this (also called as RFC1294/1490 IP encapsulation).
212Write the DLCI number to the 'dlci' file, and write the name of the physical
213COMX device to the file called 'master'.
214Now you can assign an IP address to this interface and set routes using it.
215See the example file for further info and example config script.
216Notes: this driver implements a DTE interface with partially implemented
217Q933a LMI.
218You can find an extensively commented example in the 'etc' directory.
219
220FURTHER /proc FILES
221
222boardtype:
223Type of the hardware. Valid values are:
224 'comx', 'hicomx', 'locomx', 'cmx', 'slicecom'.
225
226protocol:
227Data-link protocol on this channel. Can be: HDLC, LAPB, PPP, FRAD
228
229status:
230You can read the channel's actual status from the 'status' file, for example
231'cat /proc/comx/comx3/status'.
232
233lineup_delay:
234Interpreted in seconds (default is 1). Used to avoid line jitter: the system
235will consider the line status 'UP' only if it is up for at least this number
236of seconds.
237
238debug:
239You can set various debug options through this file. Valid options are:
240'comx_events', 'comx_tx', 'comx_rx', 'hw_events', 'hw_tx', 'hw_rx'.
241You can enable a debug options by writing its name prepended by a '+' into
242the debug file, for example 'echo +comx_rx >comx0/debug'.
243Disabling an option happens similarly, use the '-' prefix
244(e.g. 'echo -hw_rx >debug').
245Debug results can be read from the debug file, for example:
246tail -f /proc/comx/comx2/debug
247
248