No more "invalid span", now it's either "'foo' not a libpri span" or
"'foo' span not found" which makes it a lot more useful.
Signed-off-by: Stefan Knoblich <stkn@openisdn.net>
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>
