Documentation/networking/comx.txt - arm/linux - Git at Google



            		COMX drivers for the 2.2 kernel


            Originally written by: Tivadar Szemethy, <tiv@itc.hu>

            
            Currently maintained by: Gergely Madarasz <gorgo@itc.hu>


            Last change: 21/06/1999.


            INTRODUCTION


            This document describes the software drivers and their use for the

            
            COMX line of synchronous serial adapters for Linux version 2.2.0 and

            
            above.

            
            The cards are produced and sold by ITC-Pro Ltd. Budapest, Hungary

            
            For 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.hu


            Currently, 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))

            
            SliceCOM	(1x2Mbps channelized E1 board)

            
            PciCOM	(X21)


            At the moment of writing this document, the (Cisco)-HDLC, LAPB, SyncPPP and

            
            Frame Relay (DTE, rfc1294 IP encapsulation with partially implemented Q933a

            
            LMI) protocols are available as link-level protocol.

            
            X.25 support is being worked on.


            USAGE


            Load 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 INTRO


            The 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 can

            
            dynamically create a new interface by saying 'mkdir /proc/comx/comx0' (or you

            
            can 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 can

            
            be viewed by 'cat filename' and you can write a string to such a file by

            
            saying '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 automagically

            
            in it: 'boardtype' and 'protocol'. You have to fill in these files correctly

            
            for 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 example

            
            irq 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 can

            
            configure the corresponding network interface with the standard network

            
            configuration utilities. If you're unable to bring the interfaces up, look up

            
            the various kernel log files on your system, and consult the messages for

            
            a probable reason.


            EXAMPLE


            To create the interface 'comx0' which is the first channel of a COMX card:


            insmod comx

            
            # insmod comx-hw-comx ; insmod comx-proto-ppp  (these are usually

            
            autoloaded if you use the kernel module loader)


            mkdir /proc/comx/comx0

            
            echo comx >/proc/comx/comx0/boardtype

            
            echo 0x360 >/proc/comx/comx0/io		<- jumper-selectable I/O port

            
            echo 0x0a >/proc/comx/comx0/irq		<- jumper-selectable IRQ line

            
            echo 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 card

            
            echo HDLC >/proc/comx/comx0/protocol	<- the data-link protocol

            
            echo 10 >/proc/comx/comx0/keepalive	<- the keepalive for the protocol

            
            ifconfig comx0 1.2.3.4 pointopoint 5.6.7.8 netmask 255.255.255.255 <-

            
            					   finally configure it with ifconfig

            
            Check its status:

            
            cat /proc/comx/comx0/status


            If you want to use the second channel of this board:


            mkdir /proc/comx/comx1

            
            echo comx >/proc/comx/comx1/boardtype

            
            echo 0x360 >/proc/comx/comx1/io

            
            echo 10 >/proc/comx/comx1/irq

            
            echo 0xd000 >/proc/comx/comx1/memaddr

            
            echo 1 >/proc/comx/comx1/channel	<- channels are numbered

            
            					   as 0 (default) and 1


            Now, check if the driver recognized that you're going to use the other

            
            channel of the same adapter:


            cat /proc/comx/comx0/twin

            
            comx1

            
            cat /proc/comx/comx1/twin

            
            comx0


            You don't have to load the firmware twice, if you use both channels of

            
            an adapter, just write it into the channel 0's /proc firmware file.


            Default values: io 0x360 for COMX, 0x320 (HICOMX), irq 10, memaddr 0xd0000


            THE LOCOMX HARDWARE DRIVER


            The 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 by

            
            jumpers 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 DRIVERS


            On the HICOMX, COMX and CMX, you have to load the firmware (it is different for

            
            the three cards!). All these adapters can share the same memory

            
            address (we usually use 0xd0000). On the CMX you can set the internal

            
            clock rate (if enabled by jumpers on the small adapter boards) by writing

            
            the kbps value into the 'clock' file. You have to do this before initializing

            
            the card. If you use both HICOMX and CMX/COMX cards, initialize the HICOMX

            
            first. The I/O address of the HICOMX board is not configurable by any

            
            method available to the user: it is hardwired to 0x320, and if you have to

            
            change it, consult ITC-Pro Ltd.


            THE MIXCOM DRIVER


            The MixCOM board doesn't require firmware, the driver communicates with

            
            it through I/O ports. You can have three of these cards in one machine.


            THE SLICECOM DRIVER


            The SliceCOM board doesn't require firmware. You can have 4 of these cards

            
            in one machine. The driver doesn't (yet) support shared interrupts, so

            
            you will need a separate IRQ line for every board.

            
            Read Documentation/networking/slicecom.txt for help on configuring

            
            this adapter.


            THE HDLC/PPP LINE PROTOCOL DRIVER


            The HDLC/SyncPPP line protocol driver uses the kernel's built-in syncppp

            
            driver (syncppp.o). You don't have to manually select syncppp.o when building

            
            the kernel, the dependencies compile it in automatically.


            EXAMPLE

            
            (setting up hw parameters, see above)


            # using HDLC:

            
            echo hdlc >/proc/comx/comx0/protocol

            
            echo 10 >/proc/comx/comx0/keepalive	<- not necessary, 10 is the default

            
            ifconfig comx0 1.2.3.4 pointopoint 5.6.7.8 netmask 255.255.255.255


            (setting up hw parameters, see above)


            # using PPP:

            
            echo ppp >/proc/comx/comx0/protocol

            
            ifconfig comx0 up

            
            ifconfig comx0 1.2.3.4 pointopoint 5.6.7.8 netmask 255.255.255.255


            THE LAPB LINE PROTOCOL DRIVER


            For 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).

            
            comx-proto-lapb.o provides the following files in the appropriate directory

            
            (the default values in parens): t1 (5), t2 (1), n2 (20), mode (DTE, STD) and

            
            window (7). Agree with the administrator of your peer router on these

            
            settings (most people use defaults, but you have to know if you are DTE or

            
            DCE).


            EXAMPLE


            (setting up hw parameters, see above)

            
            echo lapb >/proc/comx/comx0/protocol

            
            echo dce >/proc/comx/comx0/mode		<- DCE interface in this example

            
            ifconfig comx0 1.2.3.4 pointopoint 5.6.7.8 netmask 255.255.255.255


            THE FRAME RELAY PROTOCOL DRIVER


            You DON'T need any other frame relay related modules from the kernel to use

            
            COMX-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 whatever

            
            you've named the interface). Do not assign any IP address to this interface

            
            and do not set any routes through it.

            
            Then, set up your DLCIs the following way: create a comx interface for each

            
            DLCI 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 physical

            
            COMX 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 implemented

            
            Q933a LMI.

            
            You can find an extensively commented example in the 'etc' directory.


            FURTHER /proc FILES


            boardtype:

            
            Type of the hardware. Valid values are:

            
             'comx', 'hicomx', 'locomx', 'cmx', 'slicecom'.


            protocol:

            
            Data-link protocol on this channel. Can be: HDLC, LAPB, PPP, FRAD


            status:

            
            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 system

            
            will consider the line status 'UP' only if it is up for at least this number

            
            of 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 '+' into

            
            the 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

	COMX drivers for the 2.2 kernel

	Originally written by: Tivadar Szemethy, <tiv@itc.hu>
	Currently maintained by: Gergely Madarasz <gorgo@itc.hu>

	Last change: 21/06/1999.

	INTRODUCTION

	This document describes the software drivers and their use for the
	COMX line of synchronous serial adapters for Linux version 2.2.0 and
	above.
	The cards are produced and sold by ITC-Pro Ltd. Budapest, Hungary
	For 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.hu

	Currently, 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))
	SliceCOM (1x2Mbps channelized E1 board)
	PciCOM (X21)

	At the moment of writing this document, the (Cisco)-HDLC, LAPB, SyncPPP and
	Frame Relay (DTE, rfc1294 IP encapsulation with partially implemented Q933a
	LMI) protocols are available as link-level protocol.
	X.25 support is being worked on.

	USAGE

	Load 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 INTRO

	The 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 can
	dynamically create a new interface by saying 'mkdir /proc/comx/comx0' (or you
	can 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 can
	be viewed by 'cat filename' and you can write a string to such a file by
	saying '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 automagically
	in it: 'boardtype' and 'protocol'. You have to fill in these files correctly
	for 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 example
	irq 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 can
	configure the corresponding network interface with the standard network
	configuration utilities. If you're unable to bring the interfaces up, look up
	the various kernel log files on your system, and consult the messages for
	a probable reason.

	EXAMPLE

	To create the interface 'comx0' which is the first channel of a COMX card:

	insmod comx
	# insmod comx-hw-comx ; insmod comx-proto-ppp (these are usually
	autoloaded if you use the kernel module loader)

	mkdir /proc/comx/comx0
	echo comx >/proc/comx/comx0/boardtype
	echo 0x360 >/proc/comx/comx0/io <- jumper-selectable I/O port
	echo 0x0a >/proc/comx/comx0/irq <- jumper-selectable IRQ line
	echo 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 card
	echo HDLC >/proc/comx/comx0/protocol <- the data-link protocol
	echo 10 >/proc/comx/comx0/keepalive <- the keepalive for the protocol
	ifconfig comx0 1.2.3.4 pointopoint 5.6.7.8 netmask 255.255.255.255 <-
	finally configure it with ifconfig
	Check its status:
	cat /proc/comx/comx0/status

	If you want to use the second channel of this board:

	mkdir /proc/comx/comx1
	echo comx >/proc/comx/comx1/boardtype
	echo 0x360 >/proc/comx/comx1/io
	echo 10 >/proc/comx/comx1/irq
	echo 0xd000 >/proc/comx/comx1/memaddr
	echo 1 >/proc/comx/comx1/channel <- channels are numbered
	as 0 (default) and 1

	Now, check if the driver recognized that you're going to use the other
	channel of the same adapter:

	cat /proc/comx/comx0/twin
	comx1
	cat /proc/comx/comx1/twin
	comx0

	You don't have to load the firmware twice, if you use both channels of
	an adapter, just write it into the channel 0's /proc firmware file.

	Default values: io 0x360 for COMX, 0x320 (HICOMX), irq 10, memaddr 0xd0000

	THE LOCOMX HARDWARE DRIVER

	The 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 by
	jumpers 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 DRIVERS

	On the HICOMX, COMX and CMX, you have to load the firmware (it is different for
	the three cards!). All these adapters can share the same memory
	address (we usually use 0xd0000). On the CMX you can set the internal
	clock rate (if enabled by jumpers on the small adapter boards) by writing
	the kbps value into the 'clock' file. You have to do this before initializing
	the card. If you use both HICOMX and CMX/COMX cards, initialize the HICOMX
	first. The I/O address of the HICOMX board is not configurable by any
	method available to the user: it is hardwired to 0x320, and if you have to
	change it, consult ITC-Pro Ltd.

	THE MIXCOM DRIVER

	The MixCOM board doesn't require firmware, the driver communicates with
	it through I/O ports. You can have three of these cards in one machine.

	THE SLICECOM DRIVER

	The SliceCOM board doesn't require firmware. You can have 4 of these cards
	in one machine. The driver doesn't (yet) support shared interrupts, so
	you will need a separate IRQ line for every board.
	Read Documentation/networking/slicecom.txt for help on configuring
	this adapter.

	THE HDLC/PPP LINE PROTOCOL DRIVER

	The HDLC/SyncPPP line protocol driver uses the kernel's built-in syncppp
	driver (syncppp.o). You don't have to manually select syncppp.o when building
	the kernel, the dependencies compile it in automatically.




	EXAMPLE
	(setting up hw parameters, see above)

	# using HDLC:
	echo hdlc >/proc/comx/comx0/protocol
	echo 10 >/proc/comx/comx0/keepalive <- not necessary, 10 is the default
	ifconfig comx0 1.2.3.4 pointopoint 5.6.7.8 netmask 255.255.255.255

	(setting up hw parameters, see above)

	# using PPP:
	echo ppp >/proc/comx/comx0/protocol
	ifconfig comx0 up
	ifconfig comx0 1.2.3.4 pointopoint 5.6.7.8 netmask 255.255.255.255


	THE LAPB LINE PROTOCOL DRIVER

	For 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).
	comx-proto-lapb.o provides the following files in the appropriate directory
	(the default values in parens): t1 (5), t2 (1), n2 (20), mode (DTE, STD) and
	window (7). Agree with the administrator of your peer router on these
	settings (most people use defaults, but you have to know if you are DTE or
	DCE).

	EXAMPLE

	(setting up hw parameters, see above)
	echo lapb >/proc/comx/comx0/protocol
	echo dce >/proc/comx/comx0/mode <- DCE interface in this example
	ifconfig comx0 1.2.3.4 pointopoint 5.6.7.8 netmask 255.255.255.255


	THE FRAME RELAY PROTOCOL DRIVER

	You DON'T need any other frame relay related modules from the kernel to use
	COMX-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 whatever
	you've named the interface). Do not assign any IP address to this interface
	and do not set any routes through it.
	Then, set up your DLCIs the following way: create a comx interface for each
	DLCI 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 physical
	COMX 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 implemented
	Q933a LMI.
	You can find an extensively commented example in the 'etc' directory.

	FURTHER /proc FILES

	boardtype:
	Type of the hardware. Valid values are:
	'comx', 'hicomx', 'locomx', 'cmx', 'slicecom'.

	protocol:
	Data-link protocol on this channel. Can be: HDLC, LAPB, PPP, FRAD

	status:
	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 system
	will consider the line status 'UP' only if it is up for at least this number
	of 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 '+' into
	the 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