[FreeTDM] Add (experimental) ftmod_misdn

Add I/O plugin for mISDN stack that is included in the linux kernel
since version 2.6.27.

The in-kernel mISDN stack uses a socket based interface (AF_ISDN),
data and control commands are exchanged via datagram messages.

This makes writing a driver that doesn't use a separate (per-span)
thread to handle all incoming events a bit tricky, because responses
to control messages and incoming data are mixed and interfacing
with the synchronous FreeTDM I/O API is problematic.

B(*)/D-channel handling:

The current version uses misdn_wait() to poll() for activity on
the non-blocking channel sockets and misdn_read() to receive and
handle all pending events up to the first PH_DATA_IND (data) message
(which is what the caller of the read method is actually after).

In case no data has been received, misdn_read() returns FTDM_SUCCESS
with *datalen = 0, which is OK for all the signalling modules tested
(ftmod_libpri and (out-of-tree) ftmod_isdn).

To send data, misdn_write() is called, which just sends a PH_DATA_REQ
message to the mISDN channel socket.

(*) B-channels use a per-channel timerfd as a timing reference for
'ready-for-write' poll()ing in misdn_wait().

This is a workaround for a limitation of mISDN sockets, which do not
support POLLOUT waiting on b-channel sockets (in a useful way).

Sending/receiving of data works the same way as on d-channels, otherwise.

The module has received some minimal testing using a beronet
single-port HFC E1 and a HFC4-S quad-port BRI card on linux-3.0.x.

--- Limitations ---

 - Only the most basic features have been implemented (alarms,
   sending/receiving data/audio).

 - Spans are limited to E1 and BRI/BRI_PTMP trunk types.

 - D-Channels only work on 16 for PRI and 3 for BRI.

 - NT/TE mode information is not available from freetdm.conf /
   at configure_span()-time so the module assumes TE mode,
   which should be only a problem for cards that can change
   the port configuration (pin-out) from software.

 - Current design (b-channel timerfd / misdn_wait()/_read()/_write())
   should be fine for most SoHo use-cases
   (scalability / cpu usage / timing precision).

--- Requirements ---

 - mISDNif.h header (/usr/include/mISDN/mISDNif.h), provided by mISDNuser
   (http://isdn.eversberg.eu/download/lcr-1.7/mISDNuser-20100525.tar.gz).

 - Linux kernel with mISDN and timerfd enabled (>= 2.6.27)
   and libc with timerfd support.

mISDN options can be found in the:

"Device Drivers" -> "ISDN support" -> "Modular ISDN driver"

section of make menuconfig. Timerfd is usually enabled by default.

The FreeTDM configure script will check for missing mISDNif.h
header and timerfd support and print a message.

You should see the following in the summary screen on success:

	ftmod_misdn........................ yes

NOTE: Forcing mISDN support using the "--with-misdn" configure option,
      will cause the configure script to fail on the first missing
      dependency.

--- Usage ---

To use the module, make sure you have mISDN support in the kernel
(kernel modules loaded or kernel with built-in mISDN running),
the "misdn_info" application shipped with mISDNuser will output
a list of available mISDN ports on your system, e.g.:

Found 5 ports
  Port  0 'hfc-4s.1-1':      TE/NT-mode BRI S/T (for phone lines & phones)
                              2 B-channels: 1-2
                                B-protocols: RAW HDLC X75slp
  ...

  Port  4 'hfc-e1.2':        TE/NT-mode PRI E1  (for phone lines & E1 devices)
                             30 B-channels: 1-15 17-31
                                B-protocols: RAW HDLC X75slp

NOTE: ftmod_misdn will print an error message if mISDN support is not available,
      or if there are no ports installed.

- Example freetdm.conf settings

[span misdn BRI_1]
trunk_type => BRI_PTMP
b-channel => 0:1,2
d-channel => 0:3

[span misdn PRI_1]
trunk_type => E1
b-channel => hfc-e1.2:1-15,17-31
d-channel => hfc-e1.2:16

Signed-off-by: Stefan Knoblich <stkn@openisdn.net>

libs/freetdm/Makefile.am

@@ -248,6 +248,14 @@ ftmod_r2_la_LDFLAGS = -shared -module -avoid-version -lopenr2
 ftmod_r2_la_LIBADD  = libfreetdm.la
 endif
 
+if HAVE_MISDN
+mod_LTLIBRARIES += ftmod_misdn.la
+ftmod_misdn_la_SOURCES  = $(SRC)/ftmod/ftmod_misdn/ftmod_misdn.c
+ftmod_misdn_la_CFLAGS   = $(FTDM_CFLAGS) $(AM_CFLAGS) $(MISDN_CFLAGS)
+ftmod_misdn_la_LDFLAGS  = -shared -module -avoid-version
+ftmod_misdn_la_LIBADD   = libfreetdm.la
+endif
+
 dox doxygen:
 	doxygen $(FT_SRCDIR)/docs/Doxygen.conf
 

libs/freetdm/configure.ac

@@ -364,6 +364,42 @@ then
 fi
 AM_CONDITIONAL([HAVE_LIBISDN], [test "${HAVE_LIBISDN}" = "yes"])
 
+
+##
+# mISDN dependencies
+#
+HAVE_MISDN="no"
+AC_ARG_WITH([misdn],
+	[AS_HELP_STRING([--with-misdn], [Install ftmod_misdn (mISDN I/O plugin)])],
+	[case "${withval}" in
+	 no|yes) with_misdn="${withval}" ;;
+	 *)      AC_MSG_ERROR([Invalid value \"${with_misdn}\" for --with-misdn option]) ;;
+	 esac],
+	[with_misdn="auto"]
+)
+AS_IF([test "${with_misdn}" != "no"],
+	[AC_MSG_RESULT([${as_nl}<<>> ftmod_misdn (Linux mISDN I/O plugin)])
+	 AC_CHECK_FUNCS([timerfd_create],,
+		[AS_IF([test "${with_misdn}" = "yes"],
+			[AC_MSG_ERROR([no timerfd support in libc])],
+			[AC_MSG_NOTICE([no timerfd support in libc])]
+		 )]
+	 )
+	 AC_CHECK_HEADER([mISDN/mISDNif.h],,
+		[AS_IF([test "${with_misdn}" = "yes"],
+			[AC_MSG_ERROR([mISDN/mISDNif.h not found])],
+			[AC_MSG_NOTICE([mISDN/mISDNif.h not found])]
+		)],
+		[#include <sys/socket.h>]
+	 )
+	 AS_IF([test "${ac_cv_func_timerfd_create}" = "yes" -a "${ac_cv_header_mISDN_mISDNif_h}" = "yes"],
+		[HAVE_MISDN="yes"],
+		[AC_MSG_NOTICE([Some required dependencies are missing, module disabled])]
+	 )]
+)
+AM_CONDITIONAL([HAVE_MISDN], [test "${HAVE_MISDN}" = "yes"])
+
+
 AC_MSG_RESULT([${as_nl}<<>> Creating output files])
 AC_CONFIG_FILES([
 	Makefile
@@ -389,6 +425,7 @@ AC_MSG_RESULT([
 	ftmod_pritap....................... ${HAVE_PRITAP}
   I/O:
 	ftmod_wanpipe...................... ${HAVE_LIBSANGOMA}
+	ftmod_misdn........................ ${HAVE_MISDN}
 
 ===============================================================================
 ])