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