Documentation/networking/generic-hdlc.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ==================
   4 Generic HDLC layer
   5 ==================
   6
   7 Krzysztof Halasa <khc@pm.waw.pl>
   8
   9
  10 Generic HDLC layer currently supports:
  11
  12 1. 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
  20 2. raw HDLC - either IP (IPv4) interface or Ethernet device emulation
  21 3. Cisco HDLC
  22 4. PPP
  23 5. X.25 (uses X.25 routines).
  24
  25 Generic HDLC is a protocol driver only - it needs a low-level driver
  26 for your particular hardware.
  27
  28 Ethernet device emulation (using HDLC or Frame-Relay PVC) is compatible
  29 with IEEE 802.1Q (VLANs) and 802.1D (Ethernet bridging).
  30
  31
  32 Make sure the hdlc.o and the hardware driver are loaded. It should
  33 create a number of "hdlc" (hdlc0 etc) network devices, one for each
  34 WAN port. You'll need the "sethdlc" utility, get it from:
  35
  36         http://www.kernel.org/pub/linux/utils/net/hdlc/
  37
  38 Compile sethdlc.c utility::
  39
  40         gcc -O2 -Wall -o sethdlc sethdlc.c
  41
  42 Make sure you're using a correct version of sethdlc for your kernel.
  43
  44 Use sethdlc to set physical interface, clock rate, HDLC mode used,
  45 and add any required PVCs if using Frame Relay.
  46 Usually you want something like::
  47
  48         sethdlc hdlc0 clock int rate 128000
  49         sethdlc hdlc0 cisco interval 10 timeout 25
  50
  51 or::
  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
  59 In Frame Relay mode, ifconfig master hdlc device up (without assigning
  60 any IP address to it) before using pvc devices.
  61
  62
  63 Setting 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
  82 Setting 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
 120 Frame-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
 131 Board-specific issues
 132 ---------------------
 133
 134 n2.o and c101.o need parameters to work::
 135
 136         insmod n2 hw=io,irq,ram,ports[:io,irq,...]
 137
 138 example::
 139
 140         insmod n2 hw=0x300,10,0xD0000,01
 141
 142 or::
 143
 144         insmod c101 hw=irq,ram[:irq,...]
 145
 146 example::
 147
 148         insmod c101 hw=9,0xdc000
 149
 150 If built into the kernel, these drivers need kernel (command line) parameters::
 151
 152         n2.hw=io,irq,ram,ports:...
 153
 154 or::
 155
 156         c101.hw=irq,ram:...
 157
 158
 159
 160 If 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
 165 The hardware driver has to be build with #define DEBUG_RINGS.
 166 Attaching this info to bug reports would be helpful. Anyway, let me know
 167 if you have problems using this.
 168
 169 For patches and other info look at:
 170 <http://www.kernel.org/pub/linux/utils/net/hdlc/>.