[GitHub/mt8127/android_kernel_alcatel_ttab.git] / Documentation / networking / generic-hdlc.txt

Generic HDLC layer
Krzysztof Halasa <khc@pm.waw.pl>


Generic HDLC layer currently supports:
1. Frame Relay (ANSI, CCITT, Cisco and no LMI)
   - Normal (routed) and Ethernet-bridged (Ethernet device emulation)
     interfaces can share a single PVC.
   - ARP support (no InARP support in the kernel - there is an
     experimental InARP user-space daemon available on:
     http://www.kernel.org/pub/linux/utils/net/hdlc/).
2. raw HDLC - either IP (IPv4) interface or Ethernet device emulation
3. Cisco HDLC
4. PPP
5. X.25 (uses X.25 routines).

Generic HDLC is a protocol driver only - it needs a low-level driver
for your particular hardware.

Ethernet device emulation (using HDLC or Frame-Relay PVC) is compatible
with IEEE 802.1Q (VLANs) and 802.1D (Ethernet bridging).


Make sure the hdlc.o and the hardware driver are loaded. It should
create a number of "hdlc" (hdlc0 etc) network devices, one for each
WAN port. You'll need the "sethdlc" utility, get it from:
	http://www.kernel.org/pub/linux/utils/net/hdlc/

Compile sethdlc.c utility:
	gcc -O2 -Wall -o sethdlc sethdlc.c
Make sure you're using a correct version of sethdlc for your kernel.

Use sethdlc to set physical interface, clock rate, HDLC mode used,
and add any required PVCs if using Frame Relay.
Usually you want something like:

	sethdlc hdlc0 clock int rate 128000
	sethdlc hdlc0 cisco interval 10 timeout 25
or
	sethdlc hdlc0 rs232 clock ext
	sethdlc hdlc0 fr lmi ansi
	sethdlc hdlc0 create 99
	ifconfig hdlc0 up
	ifconfig pvc0 localIP pointopoint remoteIP

In Frame Relay mode, ifconfig master hdlc device up (without assigning
any IP address to it) before using pvc devices.


Setting interface:

* v35 | rs232 | x21 | t1 | e1 - sets physical interface for a given port
                                if the card has software-selectable interfaces
  loopback - activate hardware loopback (for testing only)
* clock ext - both RX clock and TX clock external
* clock int - both RX clock and TX clock internal
* clock txint - RX clock external, TX clock internal
* clock txfromrx - RX clock external, TX clock derived from RX clock
* rate - sets clock rate in bps (for "int" or "txint" clock only)


Setting protocol:

* hdlc - sets raw HDLC (IP-only) mode
  nrz / nrzi / fm-mark / fm-space / manchester - sets transmission code
  no-parity / crc16 / crc16-pr0 (CRC16 with preset zeros) / crc32-itu
  crc16-itu (CRC16 with ITU-T polynomial) / crc16-itu-pr0 - sets parity

* hdlc-eth - Ethernet device emulation using HDLC. Parity and encoding
  as above.

* cisco - sets Cisco HDLC mode (IP, IPv6 and IPX supported)
  interval - time in seconds between keepalive packets
  timeout - time in seconds after last received keepalive packet before
            we assume the link is down

* ppp - sets synchronous PPP mode

* x25 - sets X.25 mode

* fr - Frame Relay mode
  lmi ansi / ccitt / cisco / none - LMI (link management) type
  dce - Frame Relay DCE (network) side LMI instead of default DTE (user).
  It has nothing to do with clocks!
  t391 - link integrity verification polling timer (in seconds) - user
  t392 - polling verification timer (in seconds) - network
  n391 - full status polling counter - user
  n392 - error threshold - both user and network
  n393 - monitored events count - both user and network

Frame-Relay only:
* create n | delete n - adds / deletes PVC interface with DLCI #n.
  Newly created interface will be named pvc0, pvc1 etc.

* create ether n | delete ether n - adds a device for Ethernet-bridged
  frames. The device will be named pvceth0, pvceth1 etc.


Board-specific issues
---------------------

n2.o and c101.o need parameters to work:

	insmod n2 hw=io,irq,ram,ports[:io,irq,...]
example:
	insmod n2 hw=0x300,10,0xD0000,01

or
	insmod c101 hw=irq,ram[:irq,...]
example:
	insmod c101 hw=9,0xdc000

If built into the kernel, these drivers need kernel (command line) parameters:
	n2.hw=io,irq,ram,ports:...
or
	c101.hw=irq,ram:...


If you have a problem with N2, C101 or PLX200SYN card, you can issue the
"private" command to see port's packet descriptor rings (in kernel logs):

	sethdlc hdlc0 private

The hardware driver has to be build with #define DEBUG_RINGS.
Attaching this info to bug reports would be helpful. Anyway, let me know
if you have problems using this.

For patches and other info look at:
<http://www.kernel.org/pub/linux/utils/net/hdlc/>.
Commit	Line	Data
1da177e4 LT	1	Generic HDLC layer
1da177e4 LT	2	Krzysztof Halasa <khc@pm.waw.pl>
1da177e4 LT	3
	4
	5	Generic HDLC layer currently supports:
e022c2f0	6	1. Frame Relay (ANSI, CCITT, Cisco and no LMI)
b3dd65f9 KH	7	- Normal (routed) and Ethernet-bridged (Ethernet device emulation)
	8	interfaces can share a single PVC.
	9	- ARP support (no InARP support in the kernel - there is an
	10	experimental InARP user-space daemon available on:
	11	http://www.kernel.org/pub/linux/utils/net/hdlc/).
e022c2f0 KH	12	2. raw HDLC - either IP (IPv4) interface or Ethernet device emulation
	13	3. Cisco HDLC
	14	4. PPP
b3dd65f9 KH	15	5. X.25 (uses X.25 routines).
	16
	17	Generic HDLC is a protocol driver only - it needs a low-level driver
	18	for your particular hardware.
1da177e4 LT	19
	20	Ethernet device emulation (using HDLC or Frame-Relay PVC) is compatible
	21	with IEEE 802.1Q (VLANs) and 802.1D (Ethernet bridging).
	22
	23
	24	Make sure the hdlc.o and the hardware driver are loaded. It should
	25	create a number of "hdlc" (hdlc0 etc) network devices, one for each
	26	WAN port. You'll need the "sethdlc" utility, get it from:
b3dd65f9	27	http://www.kernel.org/pub/linux/utils/net/hdlc/
1da177e4 LT	28
	29	Compile sethdlc.c utility:
	30	gcc -O2 -Wall -o sethdlc sethdlc.c
	31	Make sure you're using a correct version of sethdlc for your kernel.
	32
	33	Use sethdlc to set physical interface, clock rate, HDLC mode used,
	34	and add any required PVCs if using Frame Relay.
	35	Usually you want something like:
	36
	37	sethdlc hdlc0 clock int rate 128000
	38	sethdlc hdlc0 cisco interval 10 timeout 25
	39	or
	40	sethdlc hdlc0 rs232 clock ext
	41	sethdlc hdlc0 fr lmi ansi
	42	sethdlc hdlc0 create 99
	43	ifconfig hdlc0 up
	44	ifconfig pvc0 localIP pointopoint remoteIP
	45
	46	In Frame Relay mode, ifconfig master hdlc device up (without assigning
	47	any IP address to it) before using pvc devices.
	48
	49
	50	Setting interface:
	51
	52	* v35 \| rs232 \| x21 \| t1 \| e1 - sets physical interface for a given port
	53	if the card has software-selectable interfaces
	54	loopback - activate hardware loopback (for testing only)
b3dd65f9 KH	55	* clock ext - both RX clock and TX clock external
	56	* clock int - both RX clock and TX clock internal
	57	* clock txint - RX clock external, TX clock internal
	58	* clock txfromrx - RX clock external, TX clock derived from RX clock
	59	* rate - sets clock rate in bps (for "int" or "txint" clock only)
	60
1da177e4 LT	61
	62	Setting protocol:
	63
	64	* hdlc - sets raw HDLC (IP-only) mode
	65	nrz / nrzi / fm-mark / fm-space / manchester - sets transmission code
	66	no-parity / crc16 / crc16-pr0 (CRC16 with preset zeros) / crc32-itu
	67	crc16-itu (CRC16 with ITU-T polynomial) / crc16-itu-pr0 - sets parity
	68
	69	* hdlc-eth - Ethernet device emulation using HDLC. Parity and encoding
	70	as above.
	71
	72	* cisco - sets Cisco HDLC mode (IP, IPv6 and IPX supported)
	73	interval - time in seconds between keepalive packets
	74	timeout - time in seconds after last received keepalive packet before
	75	we assume the link is down
	76
	77	* ppp - sets synchronous PPP mode
	78
	79	* x25 - sets X.25 mode
	80
	81	* fr - Frame Relay mode
b3dd65f9	82	lmi ansi / ccitt / cisco / none - LMI (link management) type
1da177e4 LT	83	dce - Frame Relay DCE (network) side LMI instead of default DTE (user).
	84	It has nothing to do with clocks!
	85	t391 - link integrity verification polling timer (in seconds) - user
	86	t392 - polling verification timer (in seconds) - network
	87	n391 - full status polling counter - user
	88	n392 - error threshold - both user and network
	89	n393 - monitored events count - both user and network
	90
	91	Frame-Relay only:
	92	* create n \| delete n - adds / deletes PVC interface with DLCI #n.
	93	Newly created interface will be named pvc0, pvc1 etc.
	94
	95	* create ether n \| delete ether n - adds a device for Ethernet-bridged
	96	frames. The device will be named pvceth0, pvceth1 etc.
	97
	98
	99
	100
	101	Board-specific issues
	102	---------------------
	103
	104	n2.o and c101.o need parameters to work:
	105
	106	insmod n2 hw=io,irq,ram,ports[:io,irq,...]
	107	example:
	108	insmod n2 hw=0x300,10,0xD0000,01
	109
	110	or
	111	insmod c101 hw=irq,ram[:irq,...]
	112	example:
	113	insmod c101 hw=9,0xdc000
	114
	115	If built into the kernel, these drivers need kernel (command line) parameters:
	116	n2.hw=io,irq,ram,ports:...
	117	or
	118	c101.hw=irq,ram:...
	119
	120
	121
b3dd65f9 KH	122	If you have a problem with N2, C101 or PLX200SYN card, you can issue the
b3dd65f9 KH	123	"private" command to see port's packet descriptor rings (in kernel logs):
1da177e4 LT	124
	125	sethdlc hdlc0 private
	126
b3dd65f9	127	The hardware driver has to be build with #define DEBUG_RINGS.
1da177e4 LT	128	Attaching this info to bug reports would be helpful. Anyway, let me know
	129	if you have problems using this.
	130
b3dd65f9 KH	131	For patches and other info look at:
b3dd65f9 KH	132	<http://www.kernel.org/pub/linux/utils/net/hdlc/>.