DIY PBX Chapter 3: Come to DAHDI

So, I physically installed the TDM410P telephony card, and now I needed to install some device drivers to run it. And, here I got into the fun stuff: software. This TDM410P clone card came with little documentation, and no software of any kind, so I had to find the driver source code, compile it, install it, configure it, load it and use it. That took a bit of research with books and the internet, and a lot of sitting at the keyboard, entering commands and checking results. But, both necessity and curiosity keep me involved, and I could do this. So, let me tell you all about it, OK?

Open-source Telephony, Digium, ZapTel and DAHDI

Last century, some very smart people wrote some open-source software for Linux that would manage a telephone system; they formed a company, Digium, and named the software Asterisk. But, at the time, you couldn't have a telephony application that stood alone; it needed to work with specific hardware that, at the time, cost a lot of money. Another bright person designed and built a simplified telephony adaptor card (the "Tormenta"), wrote an open-source driver (called "Zapata Telephony", or "ZapTel") for it and released them both to the world. Well, the cheap(er) devices won out, as more manufacturers built their own versions, and we got ZapTel as a telephony device driver framework. Digium adopted ZapTel and (eventually, because of trademark issues) renamed it to Digium Asterisk Hardware Device Interface (aka DAHDI).

So, to use the TDM410P card, I needed a DAHDI driver, which I retrieved from the Asterisk Project. The DAHDI project considers the TDM410P card as "obsolete", so I had to do a bit of research¹ to locate the latest driver set that supports it.

A digression on the generics of locally-compiled applications on Slackware

Here, I have to take a detour, to tell you about Slackware and my systems. I have selected Slackware Linux as my Linux distribution. I've run Slackware for about twenty years now, and feel comfortable with it. It is "old school" Linux, modelled after BSD Unix. Most Linux users wouldn't appreciate the level of detail you need to know to manage a Slackware system, but I dont count myself as one of "most users".

Traditionally, on such systems, software compiled from source (as opposed to software supplied by the vendor) goes in the /usr/local filesystem tree; /usr/local/src for the source code, /usr/local/bin and /usr/local/sbin for the binaries, /usr/local/lib and /usr/local/lib64 for the libraries, etc. I try to maintain that structure, with some minor modifications.

So, for any one application that I compile onsite, I create /usr/local/src/application_name as a directory to hold the compilation products for that application, and within it

• /usr/local/src/application_name/tarballs to hold the downloaded source tarballs,
• /usr/local/src/application_name/packages to hold installation packages that I create from the compilation process,
• /usr/local/src/application_name/application-source to hold the source code from the tarball, and
• /usr/local/src/application_name/install to hold a fake-root installation of the application.

With this structure, I can keep record of the versions of any application I build, from source tarball all the way to installation package.

Downloading and Extracting the DAHDI source

With the dahdi-linux-complete-2.11.1+2.11.1 package, I kept to this pattern. Here, I created the source code directory structure that I worked in, downloaded the DAHDI package to the proper subdirectory, and unpacked the source:

  # mkdir -p /usr/local/src/dahdi/tarballs
  # cd /usr/local/src/dahdi/tarballs
  # wget "http://downloads.asterisk.org/pub/telephony/dahdi-linux-complete/dahdi-linux-complete-2.11.1+2.11.1.tar.gz"
  # cd ..
  # tar -xzf tarballs/dahdi-linux-complete-2.11.1+2.11.1.tar.gz

That gave me a /usr/local/src/dahdi/dahdi-linux-complete-2.11.1+2.11.1 source code directory, containing the source of both the DAHDI device drivers, and the DAHDI administration tools.

  # cd dahdi-linux-complete-2.11.1+2.11.1
  # ls -l
  total 24
  -rw-r--r--  1 root root 6673 Mar  1  2016 ChangeLog
  -rw-r--r--  1 root root  533 Mar  1  2016 Makefile
  -rw-r--r--  1 root root 1127 Mar  1  2016 README
  drwxr-xr-x  5 root root 4096 Mar  1  2016 linux
  drwxr-xr-x 12 root root 4096 Nov 24 17:29 tools

The source code directory seems simple enough, a Changelog, README, and Makefile, and seperate drivers and tools subdirectories. The README tells us that we can make all && make install && make config from this top-level directory to build and install both the DAHDI kernel modules and the DAHDI userland tools. I, on the other hand, intend to build and install the kernel modules independantly of the userland tools, and so I descend into the linux subdirectory, where I will start with the kernel modules.

 # cd linux
 # ls
 LICENSE       Makefile  UPGRADE.txt  dahdi-modules  include
 LICENSE.LGPL  README    build_tools  drivers

Now, this is more like it. The README tells me that I need to have installed the kernel source tree (which I have, as part of the Slackware install), and tells me that (given that), I only need make && make install to compile and install the kernel modules. There are two sections in the README that I pay particular attention to: the section on "installing to a subtree" (which I will follow, as I intend to build and install a custom Slackware installation package rather than installing these modules directly), and a section on "OSLEC", which handles echo cancellation.

Another digression, to discuss Echo Cancellation

Many telephony adaptor cards have "echo cancellation" built into the hardware, as some sort of in-line DSP. Mine does not. So, in order to manage line echo (it's a thing), I have to use software. Asterisk (the PBX software) comes with a number of software echo cancellation modules that I could chose from. But the most recommended echo cancellation module doesn't come with Asterisk; the OSLEC echo cancellation module comes from the Linux kernel.

The Linux kernel provides OSLEC echo cancellation as a kernel module source (in /usr/src/linux/drivers/misc/echo), but most distributions do not compile this module into /lib/modules/. As my TDM410P card does not support hardware echo cancellation, I intend to use the software OSLEC echo cancellation instead. So, I had to decide on how to install the OSLEC echo kernel module.

I had two obvious choices: I could either

1. recompile the existing kernel and modules, including the OSLEC module, install these new components, rebuild by boot loader, and reboot, or
2. I seed the dahdi linux driver module source tree with the OSLEC module source (as per the OSLEC section of the README), then build and install the DAHDI modules, including the "borrowed" OSLEC module

The process to enable OSLEC and recompile the kernel is fairly straight-forward, but suffers from two drawbacks:

1. the process to install and activate the newly-compiled kernel and modules is relatively complex and can lead to an unbootable system, and
2. when Slackware releases the next kernel, I have to do it all over again.

The process to compile OSLEC as part of the DAHDI driver modules is initially less straightforward than a kernel compile, requiring some customization to the DAHDI driver source tree and compile script. However, once set up, I can perform later recompiles (for upgraded kernels) in a straight-forward manner.

For my DADHI and OSLEC installation, I chose to seed the dahdi driver source tree with the OSLEC source, and compile the resulting combined driver package as per the instructions at http://forums.asterisk.org/viewtopic.php?t=67164 (Note that these instructions describe the process for a very back level of the Linux kernel and DAHDI, and I made some adjustments to accomodate the source tree for kernel 4.4.240 and DAHDI 2.11.1).

How I built and installed OSLEC and DAHDI

The DAHDI Kbuild looks for the OSLEC echo module in drivers/staging/echo, where it resided during the v2.x kernels. However, the kernel maintainers have since promoted the OSLEC module drivers/misc/echo. Following this plan to compile OSLEC in the DAHDI compile, I either have the driver kernel module incorrectly living in /lib/modules/4.4.240/staging/echo (as the DAHDI Kbuild would normally place it), or modify the Kbuild, and correctly place the module in /lib/modules/4.4.240/misc/echo. I chose to modify the Kbuild to properly place the module.

So, I

 # cd drivers
 # mkdir misc
 # cp -R /usr/src/linux/drivers/misc/echo ./misc/echo

to build the "proper" directory for the OSLEC echo cancellation module source, and populate it with the sourcecode from the kernel source tree.

In linux/drivers/dahdi, I edit the Kbuild file to change some paths:

 # If you want to build OSLEC, include the code in the standard location:
 # drivers/staging/echo . The DAHDI OSLEC echo canceller will be built as
 # well:
 # DIY PBX - echo moved from staging/echo to misc/echo
 #ifneq (,$(wildcard $(src)/../staging/echo/echo.c))
 #obj-m += dahdi_echocan_oslec.o
 #obj-m += ../staging/echo/echo.o
 #endif
 # BEGIN DIY PBX change
 ifneq (,$(wildcard $(src)/../misc/echo/echo.c))
 obj-m += dahdi_echocan_oslec.o
 obj-m += ../misc/echo/echo.o
 endif
 # END DIY PBX change

which will cause the Kbuild to look for the OSLEC echo cancellation module in drivers/misc/echo instead of drivers/staging/echo.

Finally, in drivers/dahdi/dahdi_echocan_oslec.c, I modified the code to pull the OSLEC headers from misc/echo rather than staging/echo

 /* Fix this if OSLEC is elsewhere */
 //#include "../staging/echo/oslec.h"
 /* DIY PBX: OSLEC moved from /staging/ to /misc/ */
 #include "../misc/echo/oslec.h"
 //#include <linux/oslec.h>

Now I can "make && make install"

 # # create a fake-root install directory in /usr/local/src/dahdi/install.modules
 # mkdir ../../install.modules
 # make
 # # the next step "installs" everything, into the fake-root directory
 # make DESTDIR=/usr/local/src/dahdi/install.modules install
 # # had I wanted to install directly to my root filesystem, I would have run
 # #   make install
 # # instead

which builds all the modules and "installs" them to a directory structure in /usr/local/src/dahdi/install.modules instead in /.
From this install.modules directory, I built my Slackware installation package, saved that package in /usr/local/src/dahdi/packages, and used the standard package installation tools to install the package. Instead of going this route, I could have just installed directly into the system root directory, which takes more effort to reverse, should some component not have compiled or installed correctly.

How I built and installed the DAHDI userland tools

With the kernel modules safely installed, I now look to building and installing the DAHDI userland tools. These tools test, configure, and diagnose the DAHDI devices, and the telephony devices driven by DAHDI. So, I went back up the directory tree a bit, to the /usr/local/src/dahdi/dahdi-linux-complete-2.11.1+2.11.1 directory, and descended into the tools directory. Here, I found, along with all the tool source files, the standard README file that provided the configuration, compilation and installation instructions. I noted that this package, like many others, used the GNU Autoconf system, so I would first have to run the configure script before I performed the usual make && make install incantation.

The DADHI tools Makefile defaults it's configuration to place all libraries in ${libpath}/lib. However, for 64bit Linux, libraries should go into ${libpath}/lib64. By policy and convention, locally-compiled components should install in the /usr/local directory tree, but some of these tools have hardcoded paths directing to the /usr tree. I made the call to forego policy and let the install use /usr instead of /usr/local. However, to ensure proper placement of installation-compiled libraries in a 64bit system, I used a modified configure statement.

 # ./configure --sysconfdir=/etc --localstatedir=/var --libdir=/usr/lib64 --with-dahdi=../linux

With that done, I could now

 # # create the fake-root installation directory, same as before
 # mkdir /usr/local/src/dahdi/install.tools
 # make
 # # install the tools to the fake-root installation directory
 # make DESTDIR=/usr/local/src/dahdi/install.tools install
 # # install some additional config files to the fake-root installation directory
 # make DESTDIR=/usr/local/src/dahdi/install.tools install-config

and, like the DAHDI modules, I ended up with all the DAHDI tools "installed" to my fake root /usr/local/src/dahdi/install.tools directory. And, like the DAHDI modules, I built my Slackware installation package, saved that package in /usr/local/src/dahdi/packages, and used the standard package installation tools to install the package.

Now, I had DAHDI installed, but not configured or loaded.

How I activated and configured my telephony card

With all the modules and utilities in place, I could now configure my TDM410P telephony card. First off, I loaded the driver for the card; in this case, the wctdm24xxp driver, as documented in the "Supported Hardware" section of the DAHDI linux/README file.

  # # (re)build kernel module dependencies list
  # depmod -a
  # /sbin/modprobe wctdm24xxp

Surprisingly, this worked exactly as expected; no system crash, no "module not found", no nothing. Well, not precisely nothing:

 # dmesg | grep wctdm24xxp
 [342038.266176] wctdm24xxp 0000:03:06.0: Port 1: Installed -- AUTO FXO (FCC mode)
 [342038.266190] wctdm24xxp 0000:03:06.0: Port 2: Installed -- AUTO FXS/DPO
 [342038.266197] wctdm24xxp 0000:03:06.0: Port 3: Installed -- AUTO FXS/DPO
 [342038.266203] wctdm24xxp 0000:03:06.0: Port 4: Installed -- AUTO FXS/DPO
 [342038.267065] wctdm24xxp 0000:03:06.0: Found a Wildcard TDM: Wildcard TDM410P (0 BRI spans, 4 analog channels)

The module just loaded, and with that, I could start configuring DAHDI.

DAHDI needs to load some support modules that manipulate the telephony card, and to initialise all those modules (both dahdi, and telephony card) into an operational state. The dahdi_genconf(8) script interacts with the hardware driver and builds a configuration file in /etc/dahdi/system.conf, which a later DAHDI startup command (dahdi_cfg(8)) will use to initialize the DAHDI interface.

DAHDI installs two udev rules sets: /etc/udev/rules.d/dahdi.rules and /etc/udev/rules.d/xpp.rules. These udev rules prepare some device symlinks, and invoke some DAHDI tools to further initialize detected devices. The dahdi.rules expects to set ownership of the DAHDI udev subsystem to user asterisk, group asterisk, so I added such a user and group to my system. I will run Asterisk as user asterisk, group asterisk (to ensure privilege seperation between it and root), so it makes sense to give ownership of the telephony devices to that user as well.

With all those in place (the asterisk user, the udev rules and their support programs, and /etc/dahdi/system.conf), I ran dahdi_cfg(8). Silence... crickets... nothing. But /proc/modules showed that my driver and the DAHDI drivers had all loaded. The lsdahdi(8) command provided me with definite proof that my card was alive:

 # lsdahdi
 ### Span  1: WCTDM/0 "Wildcard TDM410P" (MASTER) 
   1 FXO        FXSKS       (EC: OSLEC - INACTIVE)  RED
   2 FXS        FXOKS       (EC: OSLEC - INACTIVE)  
   3 FXS        FXOKS       (EC: OSLEC - INACTIVE)  
   4 FXS        FXOKS       (EC: OSLEC - INACTIVE)  

Success!

Of course, I still have to configure my initsystem (init(1), not one of the fancier init systems) to initialize the card on system startup. DAHDI supplies an example startup script meant for pre-systemd Debian and Red Hat, which I will sculpt (not hack, I never "hack"). But, for now, I've got the card up and running. Now onwards to Asterisk, and a dial-tone.

Research

https://asterisk.org/

The home of Asterisk and DAHDI

http://downloads.asterisk.org/pub/telephony/dahdi-linux-complete/

Source code for DAHDI modules and tools, packaged in release-numbered tarballs

http://www.asteriskdocs.org/en/3rd_Edition/asterisk-book-html-chunk/Inte...

The chapter(s) on DAHDI in the book em>Asterisk^™: The Definitive Guide

http://www.asteriskdocs.org/en/3rd_Edition/asterisk-book-html-chunk/inde...

The whole book: Asterisk^™: The Definitive Guide

https://www.voip-info.org/dahdi/

A summary of DAHDI, with reference to it's predecessor, Zapata

https://support.digium.com/s/article/Installing-DAHDI

This document describes requirements and procedures of DAHDI's installation.

http://docs.tzafrir.org.il/dahdi-tools/README.html

The dahdi-tools installation instructions, htmlified

https://wiki.asterisk.org/wiki/display/DAHDI/Quick+Start+From+Source

DAHDI "Quick Start From Source" instructions