Documentation/networking/comx.txt

   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