Zaptel driver for HFC PCI A

This is my attempt at writing a Zaptel driver for the Cologne Chip's HFC-S PCI A based ISDN boards. While this is still a Zaptel-only driver this could become the beginning of a generic driver which supports both voice and data. I'm also thinking about designing a generic voice layer for Linux but this is pure vaporware and I don't sell vaporware (tought I package it).

This driver began as a fork of the driver made by Klaus-Peter Junghanns and went thorugh several refarmings and the addition of various features.

Main features

• Full support for 2.6.x kernel, tested on i386 and x86-64 architectures but probably supported on other archs (tought untested).
• L1 activation management. The driver automatically requests L1 activation when data needs to be transmitted.
• Sniffing capability. You can use Ethereal to dissect ISDN protocols either spoken by the card itself or by other TEs on the S/T bus.
• /proc and klog support for detailed debugging.

Module parameters

• debug_level

  0	No debug
  1	Interesting but not invasive messages
  2	More verbose messages
  3	Frames dump
  4	F/Z pointers and frames dump

  NOTE: requires make debug compilation

• nt_modes

  comma separated list of card IDs to configure in NT mode. NOTE: Kernel 2.6.x only

• force_l1_up

  When set to 1 tries to keep the L1 always up

• sniff_zaptel_d_channel

  Make frames transmitted from zaptel appear as transmitted from netdev for sniffing purposes.

Sniffing

The card sniffing capabilities are generally used in two different ways:

• Sniffing local TE traffic
• Sniffing traffic from/to other TEs

You cannot do both local and remote sniffing at the same time since Zaptel opens all the B channels while B2 is needed to sniff what other TEs transmit. If you attempt to put the card in promiscuous mode while B2 is open, it will complain and remains non-promiscuous. If you attempt to start Asterisk after the card has been put in promiscuous mode, Zaptel will fail opening the channel and Asterisk will not be able to boot.

You can always sniff what any TE (including the local) receive from the network, the limitation applies only to frames transmitted by the local and other TEs.

Compiling

Compilation is pretty easy but you have to be careful about a couple of details.

Firstly you need to specify your zaptel headers directory in the makefile. Be sure to specify the header files of the modules actually running on the system. If you specify headers not matching the inserted modules you may cause (very) bad behaviour.

Then, you probably need to build your kernel tree (on SuSE, I install kernel-sources, make cloneconfig and make).

Finally you need to compile the driver with make or make debug depending on what debugging features you want to be compiled in.

TODO

• Make locking more granular.
• Make FIFO access function even more generic (manage fifo full conditions).
• Investigate if there is some race condition between updating stats in IRQ handler and reading them in the other code.
• Undestand why the first transmitted frame after insmod is never transmitted.
• Better handle error conditions when the are cabling problems/disconnected cable.
• Rewrite zaptel :)

Detailed changes

• Implements L1 activation management; the driver automatically requests L1 activation when data is to be transmitted and delays transmission until the L1 is in active state. The FIFOs are disabled when the L1 is down to avoid useless PCI transfers.
• Implements channel opening/closing. Disables the (heavy) 8 KHz processing/nonprocessing interrupt when no channel is open in voice mode.
• Used kernel build infrastructure to select correct compiler options for x86-64 and other architectures. Without those options bad crashes (stack corruption inside IRQ handler) whould happen.

• ISDN4Linux driver and (not anymore) kapejod's driver used direct pointer deferencing to access memory mapped register. This is ok on most platforms, but, at least, you need the volatile qualifier to avoid harmful compiler optimizations.

  ISDN4Linux still (as of 2.6.9 kernel) uses direct deferencing without the volatile qualifier, in facts, it needs to use horrible hack like this:

  if (Read_hfc(cs, HFCPCI_INT_S1));

  The code above uses a null if statement in order to force the compiler to read from the register. Of course this wholly depends on the compiler, in facts, on my machine it didn't work and the pending interrupts register was not cleared, resulting in an IRQ flood.

  My driver uses readb/writeb functions provided by the Linux's kernel for enhanced portability and correct compiler behaviour.

• Used the new hotplug-compatible interface to enumerate/initialize/remove cards.
• Uses the new Linux's PCI API to allocate memory mapped I/O area and to allocate DMA (FIFO) area.
• Uses more meaningful/correct data types to map hardware data types (u8, u16, ...).
• Adds various error checking.
• Clears some compilation warnings.
• Adds a /proc interface to peek the card internal structures. The directory structure appears as follows:
  

  /proc/driver/zaphfc/:
  total 0
  dr-xr-xr-x  4 root root 0 2004-11-29 02:48 .
  dr-xr-xr-x  5 root root 0 2004-11-29 02:48 ..
  dr-xr-xr-x  2 root root 0 2004-11-29 02:48 0
  dr-xr-xr-x  2 root root 0 2004-11-29 02:48 1
  
  /proc/driver/zaphfc/0:
  total 0
  dr-xr-xr-x  2 root root 0 2004-11-29 02:48 .
  dr-xr-xr-x  4 root root 0 2004-11-29 02:48 ..
  -r--------  1 root root 0 2004-11-29 02:48 bufs
  -r--------  1 root root 0 2004-11-29 02:48 fifos
  -r--r--r--  1 root root 0 2004-11-29 02:48 info
  
  /proc/driver/zaphfc/1:
  total 0
  dr-xr-xr-x  2 root root 0 2004-11-29 02:48 .
  dr-xr-xr-x  4 root root 0 2004-11-29 02:48 ..
  -r--------  1 root root 0 2004-11-29 02:48 bufs
  -r--------  1 root root 0 2004-11-29 02:48 fifos
  -r--r--r--  1 root root 0 2004-11-29 02:48 info
  

• Adds 2.6.x IRQ handler compatibilty
• FIFO handling has been completely rewritten with more meaningful access functions that work either in transparent/framed mode.

• Added check for PCI Sync Loss. When the HFC isn't able to access the PCI bus to write to the FIFOs in time it generates an interrupt and sets a flag. The driver reports this event.

  NOTE: AMD PowerNOW! CPU clock frequency throttling makes the PCI bus inaccessible for too much time, so, you'll probably see the error being reported some time after initialization. Unfortunately the flag remains set until the chip is reset and you will not be able to estimate how much frequently the sync loss happens.

  Don't be scared, tought; only one sample/frame is corrupted every time the synchronization loss happens, it shouldn't be too harmful.

• Better card initialization
• More consistent delays to sync with the hardware
• Adds nt_modes, debug_level and force_l1_up, sniff_zaptel_d_channel
• Avoids progressive growth of TX FIFOs if IRQs are delyed too much
• Synchronizes zaptel with RX FIFO instead of ProcessingIRQ/8. Instead of generating the 1 KHz clock by counting processing/nonprocessing IRQ divided by 8, triggers the reception when there are at least 8 bytes in the RX FIFO. This improves tolerance to IRQ latency translating late IRQ servicin to jitter instead of slips.
• Creates a netdevice interface (isdnXd) to allow (patched) libpcap+ethereal to sniff D channel and dissect frames. When in promiscuous mode, sniffs E channel in order to see frames transmitted from other TEs.