COMX drivers for the 2.2 kernelOriginally written by: Tivadar Szemethy, <tiv@itc.hu>Currently maintained by: Gergely Madarasz <gorgo@itc.hu>Last change: 21/06/1999.INTRODUCTIONThis document describes the software drivers and their use for the COMX line of synchronous serial adapters for Linux version 2.2.0 andabove.The cards are produced and sold by ITC-Pro Ltd. Budapest, HungaryFor further info contact <info@itc.hu> or http://www.itc.hu (mostly in Hungarian).The firmware files and software are available from ftp://ftp.itc.huCurrently, the drivers support the following cards and protocols:COMX (2x64 kbps intelligent board)CMX (1x256 + 1x128 kbps intelligent board)HiCOMX (2x2Mbps intelligent board)LoCOMX (1x512 kbps passive board)MixCOM (1x512 or 2x512kbps passive board with a hardware watchdog an	optional BRI interface and optional flashROM (1-32M))At the moment of writing this document, the (Cisco)-HDLC, LAPB, SyncPPP andFrame Relay (DTE, rfc1294 IP encapsulation with partially implemented Q933a LMI) protocols are available as link-level protocol. X.25 support is being worked on.USAGELoad the comx.o module and the hardware-specific and protocol-specific modules you'll need into the running kernel using the insmod utility.This creates the /proc/comx directory.See the example scripts in the 'etc' directory./proc INTERFACE INTROThe COMX driver set has a new type of user interface based on the /proc filesystem which eliminates the need for external user-land software doing IOCTL calls. Each network interface or device (i.e. those ones you configure with 'ifconfig'and 'route' etc.) has a corresponding directory under /proc/comx. You candynamically create a new interface by saying 'mkdir /proc/comx/comx0' (or youcan name it whatever you want up to 8 characters long, comx[n] is just a convention).Generally the files contained in these directories are text files, which canbe viewed by 'cat filename' and you can write a string to such a file bysaying 'echo _string_ >filename'. This is very similar to the sysctl interface.Don't use a text editor to edit these files, always use 'echo' (or 'cat'where appropriate).When you've created the comx[n] directory, two files are created automagicallyin it: 'boardtype' and 'protocol'. You have to fill in these files correctlyfor your board and protocol you intend to use (see the board and protocol descriptions in this file below or the example scripts in the 'etc' directory).After filling in these files, other files will appear in the directory for setting the various hardware- and protocol-related informations (for exampleirq and io addresses, keepalive values etc.) These files are set to default values upon creation, so you don't necessarily have to change all of them.When you're ready with filling in the files in the comx[n] directory, you canconfigure the corresponding network interface with the standard network configuration utilities. If you're unable to bring the interfaces up, look upthe various kernel log files on your system, and consult the messages fora probable reason.EXAMPLETo create the interface 'comx0' which is the first channel of a COMX card:insmod comx # insmod comx-hw-comx ; insmod comx-proto-hdlc  (these are usuallyautoloaded if you use the kernel module loader)mkdir /proc/comx/comx0echo comx >/proc/comx/comx0/boardtypeecho 0x360 >/proc/comx/comx0/io		<- jumper-selectable I/O port echo 0x0a >/proc/comx/comx0/irq		<- jumper-selectable IRQ lineecho 0xd000 >/proc/comx/comx0/memaddr	<- software-configurable memory					   address. COMX uses 64 KB, and this					   can be: 0xa000, 0xb000, 0xc000, 					   0xd000, 0xe000. Avoid conflicts					   with other hardware.cat </etc/siol1.rom >/proc/comx/comx0/firmware <- the firmware for the cardecho HDLC >/proc/comx/comx0/protocol	<- the data-link protocolecho 10 >/proc/comx/comx0/keepalive	<- the keepalive for the protocolifconfig comx0 1.2.3.4 pointopoint 5.6.7.8 netmask 255.255.255.255 <-					   finally configure it with ifconfigCheck its status:cat /proc/comx/comx0/statusIf you want to use the second channel of this board:mkdir /proc/comx/comx1echo comx >/proc/comx/comx1/boardtypeecho 0x360 >/proc/comx/comx1/io	echo 10 >/proc/comx/comx1/irq		echo 0xd000 >/proc/comx/comx1/memaddrecho 1 >/proc/comx/comx1/channel	<- channels are numbered 					   as 0 (default) and 1Now, check if the driver recognized that you're going to use the otherchannel of the same adapter:cat /proc/comx/comx0/twincomx1cat /proc/comx/comx1/twincomx0You don't have to load the firmware twice, if you use both channels ofan adapter, just write it into the channel 0's /proc firmware file.Default values: io 0x360 for COMX, 0x320 (HICOMX), irq 10, memaddr 0xd0000THE LOCOMX HARDWARE DRIVERThe LoCOMX driver doesn't require firmware, and it doesn't use memory either,but it uses DMA channels 1 and 3. You can set the clock rate (if enabled byjumpers on the board) by writing the kbps value into the file named 'clock'.Set it to 'external' (it is the default) if you have external clock source.(Note: currently the LoCOMX driver does not support the internal clock)THE COMX, CMX AND HICOMX DRIVERSOn the HICOMX, COMX and CMX, you have to load the firmware (it is different forthe three cards!). All these adapters can share the same memoryaddress (we usually use 0xd0000). On the CMX you can set the internalclock rate (if enabled by jumpers on the small adapter boards) by writingthe kbps value into the 'clock' file. You have to do this before initializingthe card. If you use both HICOMX and CMX/COMX cards, initialize the HICOMXfirst. The I/O address of the HICOMX board is not configurable by anymethod available to the user: it is hardwired to 0x320, and if you have to change it, consult ITC-Pro Ltd.THE MIXCOM DRIVERThe MixCOM board doesn't require firmware, the driver communicates withit through I/O ports. You can have three of these cards in one machine.THE HDLC LINE PROTOCOL DRIVERThere's only one configurable parameter with this protocol: the 'keepalive'value. You can set this in seconds or set to 'off'. Agree with the administratorof your peer router on this setting. The default is 10 (seconds).EXAMPLE(setting up hw parameters, see above)echo hdlc >/proc/comx/comx0/protocolecho 10 >/proc/comx/comx0/keepalive	<- not necessary, 10 is the defaultifconfig comx0 1.2.3.4 pointopoint 5.6.7.8 netmask 255.255.255.255THE PPP LINE PROTOCOL DRIVERTo use this driver, you have to have ppp-2.3.4, and have a modified version ofpppd (this pppd will work as async pppd to, the modifiactions merely relax some restricions in order to be able to use non-async lines too.If configured, this driver can use Van Jacobson TCP header compression (you'llneed the slhc.o module for this).Additionally to use this protocol, enable async ppp in your kernel config, andcreate the comx device special files in /dev. They're character special fileswith major 88, and their names must be the same as their network interfacecounterparts (i.e /dev/comx0 with minor 0 corresponds interface comx0 and soon).EXAMPLE(setting up hw parameters, see above)echo ppp >/proc/comx/comx0/protocolifconfig comx0 uppppd comx0 1.2.3.4:5.6.7.8 persist	<- with this option pppd won't exit					   when the line goes downTHE LAPB LINE PROTOCOL DRIVERFor this, you'll need to configure LAPB support (See 'LAPB Data Link Driver' in'Network options' section) into your kernel (thanks to Jonathan Naylor for his excellent implementation). comxlapb.o provides the following files in the appropriate directory(the default values in parens): t1 (5), t2 (1), n2 (20), mode (DTE, STD) andwindow (7). Agree with the administrator of your peer router on thesesettings (most people use defaults, but you have to know if you are DTE orDCE).EXAMPLE(setting up hw parameters, see above)echo lapb >/proc/comx/comx0/protocolecho dce >/proc/comx/comx0/mode		<- DCE interface in this exampleifconfig comx0 1.2.3.4 pointopoint 5.6.7.8 netmask 255.255.255.255THE FRAME RELAY PROTOCOL DRIVERYou DON'T need any other frame relay related modules from the kernel to useCOMX-Frame Relay. This protocol is a bit more complicated than the others, because it allows to use 'subinterfaces' or DLCIs within one physical device.First you have to create the 'master' device (the actual physical interface)as you would do for other protocols. Specify 'frad' as protocol type.Now you can bring this interface up by saying 'ifconfig comx0 up' (or whateveryou've named the interface). Do not assign any IP address to this interfaceand do not set any routes through it.Then, set up your DLCIs the following way: create a comx interface for eachDLCI you intend to use (with mkdir), and write 'dlci' to the 'boardtype' file, and 'ietf-ip' to the 'protocol' file. Currently, the only supported encapsulation type is this (also called as RFC1294/1490 IP encapsulation).Write the DLCI number to the 'dlci' file, and write the name of the physicalCOMX device to the file called 'master'. Now you can assign an IP address to this interface and set routes using it.See the example file for further info and example config script.Notes: this driver implements a DTE interface with partially implementedQ933a LMI.You can find an extensively commented example in the 'etc' directory.FURTHER /proc FILESboardtype:Type of the hardware. Valid values are: 'comx', 'hicomx', 'locomx', 'cmx'.protocol:Data-link protocol on this channel. Can be: HDLC, LAPB, PPP, FRADstatus:You can read the channel's actual status from the 'status' file, for example'cat /proc/comx/comx3/status'.lineup_delay:Interpreted in seconds (default is 1). Used to avoid line jitter: the systemwill consider the line status 'UP' only if it is up for at least this numberof seconds.debug: You can set various debug options through this file. Valid options are:'comx_events', 'comx_tx', 'comx_rx', 'hw_events', 'hw_tx', 'hw_rx'.You can enable a debug options by writing its name prepended by a '+' intothe debug file, for example 'echo +comx_rx >comx0/debug'. Disabling an option happens similarly, use the '-' prefix (e.g. 'echo -hw_rx >debug').Debug results can be read from the debug file, for example: tail -f /proc/comx/comx2/debug