Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | |
2 | COMX drivers for the 2.2 kernel | |
3 | ||
4 | Originally written by: Tivadar Szemethy, <tiv@itc.hu> | |
5 | Currently maintained by: Gergely Madarasz <gorgo@itc.hu> | |
6 | ||
7 | Last change: 21/06/1999. | |
8 | ||
9 | INTRODUCTION | |
10 | ||
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 | |
18 | ||
19 | Currently, the drivers support the following cards and protocols: | |
20 | ||
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) | |
29 | ||
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. | |
34 | ||
35 | USAGE | |
36 | ||
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. | |
41 | ||
42 | /proc INTERFACE INTRO | |
43 | ||
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. | |
65 | ||
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. | |
71 | ||
72 | EXAMPLE | |
73 | ||
74 | To create the interface 'comx0' which is the first channel of a COMX card: | |
75 | ||
76 | insmod comx | |
77 | # insmod comx-hw-comx ; insmod comx-proto-ppp (these are usually | |
78 | autoloaded if you use the kernel module loader) | |
79 | ||
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 | |
96 | ||
97 | If you want to use the second channel of this board: | |
98 | ||
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 | |
106 | ||
107 | Now, check if the driver recognized that you're going to use the other | |
108 | channel of the same adapter: | |
109 | ||
110 | cat /proc/comx/comx0/twin | |
111 | comx1 | |
112 | cat /proc/comx/comx1/twin | |
113 | comx0 | |
114 | ||
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. | |
117 | ||
118 | Default values: io 0x360 for COMX, 0x320 (HICOMX), irq 10, memaddr 0xd0000 | |
119 | ||
120 | THE LOCOMX HARDWARE DRIVER | |
121 | ||
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. | |
126 | ||
127 | (Note: currently the LoCOMX driver does not support the internal clock) | |
128 | ||
129 | THE COMX, CMX AND HICOMX DRIVERS | |
130 | ||
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. | |
140 | ||
141 | THE MIXCOM DRIVER | |
142 | ||
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. | |
145 | ||
146 | THE SLICECOM DRIVER | |
147 | ||
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. | |
153 | ||
154 | THE HDLC/PPP LINE PROTOCOL DRIVER | |
155 | ||
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. | |
159 | ||
160 | ||
161 | ||
162 | ||
163 | EXAMPLE | |
164 | (setting up hw parameters, see above) | |
165 | ||
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 | |
170 | ||
171 | (setting up hw parameters, see above) | |
172 | ||
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 | |
177 | ||
178 | ||
179 | THE LAPB LINE PROTOCOL DRIVER | |
180 | ||
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). | |
189 | ||
190 | EXAMPLE | |
191 | ||
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 | |
196 | ||
197 | ||
198 | THE FRAME RELAY PROTOCOL DRIVER | |
199 | ||
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. | |
219 | ||
220 | FURTHER /proc FILES | |
221 | ||
222 | boardtype: | |
223 | Type of the hardware. Valid values are: | |
224 | 'comx', 'hicomx', 'locomx', 'cmx', 'slicecom'. | |
225 | ||
226 | protocol: | |
227 | Data-link protocol on this channel. Can be: HDLC, LAPB, PPP, FRAD | |
228 | ||
229 | status: | |
230 | You can read the channel's actual status from the 'status' file, for example | |
231 | 'cat /proc/comx/comx3/status'. | |
232 | ||
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. | |
237 | ||
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 | |
247 | ||
248 |