Generic HDLC layer for Linux

General HDLC layer for Linux is an interface between low-level hardware drivers for synchronous serial (HDLC) cards and the rest of kernel networking. The following protocols are supported:

raw HDLC - IP protocol only and Ethernet device emulation
Cisco HDLC (HDLC encapsulation used by Cisco® routers) - IP, IPv6 and IPX protocols
Point-to-Point Protocol (PPP) - IP and probably IPX protocols (uses syncppp.c module)
X.25 (using standard X.25 stack)
Frame Relay (using ANSI, CCITT, Cisco (Linux-2.6 only) or no LMI) - IP, IPv6 and IPX protocols - both DTE (normal) and DCE (FR switch side) modes are supported. Ethernet-bridged interface mode is available as well.

Generic HDLC layer is included in the official Linux kernel, available via anonymous ftp from ftp.kernel.org and its mirrors.

Ethernet framing using HDLC or FR PVC is compatible with 802.1Q VLAN and 802.1D Ethernet bridging.

A list of supported cards is here.

Linux kernel support by version is here.

Short info about using the drivers and sethdlc utility is here.

An experimental Inverse ARP daemon program is here. You may need it if your Frame-Relay IP provider requires you to use InARP.

A small utility for testing synchronous serial cards is here.

Synchronous HDLC cards supported via generic HDLC layer

Currently, low-level drivers for the following cards use the generic HDLC layer:

C101 (ISA) cards manufactured by Moxa Technologies Co., Ltd.
PC300 cards manufactured by Cyclades Corp.
RISCom/N2 cards manufactured by SDL Communications, Inc. (now SBS Communications Group)
wanXL cards manufactured by SBE Inc. (limited Linux 2.2 support, experimental Linux 2.6 support)
FarSync T-Series cards manufactured by FarSite Communications Ltd. (driver written by R. J. Dunlop)
Etinc PCISYNC cards using DSCC4 controller (driver written by Francois Romieu)
PCI200SYN cards manufactured by Goramo s.j.

Other cards may be supported by drivers available from card manufacturers.

Card name	C101 (ISA)	PC300	RISCom/N2	wanXL	PCI200SYN
Manufacturer	Moxa Technologies Co., Ltd	Cyclades Corp.	SDL Communications, Inc.	SBE Inc.	Goramo s.j.
slot type	8-bit ISA (16-bit slot required)	32-bit PCI	16-bit ISA	32-bit PCI	32-bit PCI
chip used	Hitachi HD64570 SCA	Hitachi HD64572 SCA-II	Hitachi HD64570 SCA	Motorola 68EN360 QUICC	Hitachi HD64572 SCA-II
number of ports	1	1 or 2	1 or 2	1, 2 or 4	2
RAM buffer size	256 KB 8-bit DRAM	256 KB 32-bit SRAM	64-512 KB 16-bit SRAM	4 MB 32-bit DRAM for firmware	256 KB 32-bit SRAM
RAM buffer type	shared ISA memory (16 KB window size)	shared PCI memory	shared ISA memory (16, 32 or 64 KB window size)	uses main system memory for buffers in PCI bus-mastering DMA mode	shared PCI memory
max clock rate (V.35 interface)	7 Mbps (limited by SCA chip)	5 Mbps (limited by line drivers)	7 Mbps (limited by SCA chip)	2 Mbps	10 Mbps

Linux kernel support by version

Linux 2.6

All listed cards are supported.
SBE wanXL cards are supported with an experimental driver - currently tested with wanXL-400, it should work with wanXL-200 as well, and probably requires minor tweaking for wanXL-100.
For my version of PC300RSV/X21 driver you need to apply this patch.
For Cisco LMI support on Frame-Relay on kernels <2.6.13 apply this patch.

Sethdlc utility for 2.4/2.6 kernels can be found here.

Recent versions of Linux 2.6 introduced a change which breaks generic HDLC. You will need to revert git commit cacaddf57ed4d5ca994e9a7e2bd5558061f5d89d, or to apply this patch. This is a temporary fix only, a real fix will follow soon. While not yet finally fixed, this patch is not needed on Linux 2.6.14.4, 2.6.15 and newer kernels.

Linux 2.4

All listed cards are supported except wanXL (there is an experimental driver in 2.6 kernels). If you have a PC300RSV or PC300X21 card you can choose between a driver written by Cyclades Corp or a driver written by me.

If you wish to use C101, N2 and/or PCI200SYN card(s), and/or PC300RSV/X21 with my driver, consult the following list and patch your kernel to use 1.14a or later version of the generic HDLC layer. If you have other card(s) please check the documentation provided by the manufacturer or the driver's author.

Linux 2.4.20 and older 2.4 kernels contain version 1.02 of generic HDLC layer.
Apply this patch to your kernel tree first. For PCI200SYN and/or PC300RSV/X21 drivers apply this patch as well. Rebuild your kernel even if the HDLC layer and/or hardware drivers are configured as modules.
If you really have to use the old 1.02 code, grab the old sethdlc utility from here.
Linux 2.4.21 and 2.4.22 kernels contain version 1.11 of generic HDLC layer.
Apply this patch to your kernel tree first. For PCI200SYN and/or PC300RSV/X21 drivers apply this patch as well.
Linux 2.4.21-ac and 2.4.22-ac kernels (and some recent distributions, including Red Hat 9 Linux) contain version 1.12 of generic HDLC layer.
Apply this patch to your kernel tree first. For PCI200SYN and/or PC300RSV/X21 drivers apply this patch as well.
Linux 2.4.23 and 2.4.24 kernels contain version 1.14a of generic HDLC layer. For PCI200SYN and/or PC300RSV/X21 drivers apply this patch.
Linux 2.4.25 and later 2.4 kernels contain version 1.14b (a cosmetic update to version 1.14a) of the generic HDLC layer. PCI200SYN driver is now included in the official kernel tree.
For PC300RSV/X21 driver apply this patch - this experimental version of pc300too driver tries to address a bug in a PCI bridge used by PC300 cards which prevents them from working with certain motherboards and/or PCI settings (if your card's resource region 0 has an address with bit 7 set then you are affected by this bug - please check lspci -vv -d 120e:0301).

Sethdlc utility for 2.4/2.6 kernels can be found here.
Note that there is no active development on this code - if you need new features use Linux 2.6.

Linux 2.2

Later Linux 2.2 kernels contain hardware drivers for C101, N2 and wanXL cards. This is an old code which is no longer actively maintained by me.

Sethdlc utility for Linux 2.2 can be found here.

Click here to see file directory containing files related to generic HDLC.

Using the drivers and sethdlc utility

The exact procedure depends on the card type you want to use and on your kernel version.

First, apply the patches to the kernel tree if required, then configure your kernel and build the driver modules. Load the modules using either insmod/modprobe programs or through /etc/modules.conf file. At least the following modules should be loaded: hdlc and the hardware driver for your card. Once the driver is loaded, verify that the network device(s) are created (issue "ifconfig -a" or "ip link" command and look for devices named hdlc0, hdlc1 etc.)

Get, unpack and compile the sethdlc utility. Remember to get a correct version for your kernel. If your kernel source is not in /usr/src/linux, please change the kernel include path in Makefile or use -I option to gcc. If you get "Generic HDLC layer version mismatch" error while compiling sethdlc then either your compiler is using wrong kernel headers (probably from some glibc-kernheaders package) or you haven't patched your kernel tree correctly.

If you have wanXL card, you have to use Linux 2.2 kernel, or check to see if there is a driver from card manufacturer.
You will need a firmware file (available from SBE Inc.) for your card as well. After the wanxl.o driver module is loaded, verify that one hdlc0 device has been created, and then load the firmware using:

	sethdlc hdlc0 run /path/firmware.file.name

It should create hdlcX devices for the remaining ports (in case of 2- or 4-port card).

Update: Linux 2.6 kernels contain an experimental driver for wanXL cards. You need no external firmware for this driver.

If you have C101, RISCom/N2 or PCI200SYN card(s) (or you have PC300RSV and wish to use my alternative driver), it's recommended that you use the "current" patch for 2.4 Linux kernel. In that case you have to use the "current" sethdlc.c version (version 1.16 or later) as well.

As the drivers don't probe for ISA cards, you have to specify IRQ setting, RAM window address and (in case of RISCom/N2) hardware I/O port number used by the card. Use something like (note double quotes required by insmod/modprobe):

	insmod n2 hw='"io,irq,ram,ports[:io,irq,...]"'

example:

	insmod n2 hw='"0x300,10,0xD0000,01"'

("01" means that both ports 0 and 1 should be enabled - there is no way to detect the number of ports on RISCom/N2 card)

In case of C101 you need:

	insmod c101 hw='"irq,ram[:irq,ram...]"'

example:

	insmod c101 hw='"9,0xDC000"'

If you have a driver built into the kernel, pass the equivalent "n2=io,irq,ram,ports:..." or "c101=irq,ram:..." parameter while booting your kernel. Set the jumper on your C101 card in "IN" position if you're using external transmit (and receive) clock source (the most common case), and in "OUT" position otherwise.

With Linux kernel 2.6 you don't need double quotes anymore - use something like:

	insmod n2 hw=io,irq,ram,ports[:io,irq,...]

or, if the driver is built into the kernel, pass an equivalent "n2.hw=io,irq,ram:..." or similar parameter while booting.

Having verified that hdlcX network devices are created, you may now set the physical interface parameters and the requested protocol. Use sethdlc to set physical interface, clock rate, HDLC mode used, and add any required PVCs if using Frame Relay. Usually you need something like:

Cisco HDLC, V.35 interface and internal 128000 bps clock:

	sethdlc hdlc0 v35 clock int rate 128000
	sethdlc hdlc0 cisco interval 10 timeout 25
	ifconfig hdlc0 localIP pointopoint remoteIP

RS232/V.24 synchronous interface with external clock and Ethernet over HDLC framing:

	sethdlc hdlc0 rs232 clock ext
	sethdlc hdlc0 hdlc-eth
	ifconfig hdlc0 localIP netmask ... broadcast ...

Default physical interface with external clock and Frame-Relay with ANSI LMI:
```
	sethdlc hdlc0 clock ext
	sethdlc hdlc0 fr lmi ansi
	sethdlc hdlc0 create 99		# creates PVC with DLCI = 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 any pvc devices.

The following command displays current settings of a given device:

	sethdlc hdlc0

	sethdlc pvc0