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/>.