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