Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame^] | 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 | |