CAPI FOR BSD(4)

NAME
C4B - CAPI for BSD

SYNOPSIS
device kcapimgr
device capidev

options KCAPIMGR_LOG_LEVEL="1"
options CAPIDEV_LOG_LEVEL="1"

DESCRIPTION
This manual page is the overview of CAPI for BSD, shortly termed c4b, and the various components that belong to this package.

c4b is the implementation of CAPI for the BSD operating systems. Although currently only FreeBSD is supported, the other flavours like NetBSD, OpenBSD and BSD/OS may follow if someone is willing to port and test it.

c4b mainly consists of two kernel modules named kcapimgr and capidev that can either be compiled directly into the kernel or loaded as separate kernel modules. The later possibility is the preferred method as it is most flexible, especially when developing new hardware drivers. Automatic loading the C4B modules on system startup can be enabled by adding the variable assignment ‘capi_enable="YES"’ to the file /etc/rc.conf (see the comments according to CAPI in file /etc/defaults/rc.conf).

  Kernel CAPI manager
kcapimgr is the central part of c4b. It makes up the CAPI manager kernel module that provides interfaces for kernel mode CAPI applications and ISDN board drivers. All CAPI calls and messages from any CAPI application is dispatched to the respective controller by the CAPI manager.

  The CAPI device
capidev serves as the link between user space and the kernel CAPI manager. It creates a character device named /dev/capi20 and handles all device related operations. These operations are translated into CAPI calls and messages and forwarded to the CAPI manager. The results are sent back to the user space application as the result of the device operations.

  Hardware drivers
Without any hardware driver the CAPI manager will be of no use. These drivers may be loaded as a kernel module or directly compiled into the kernel binary. If a CAPI driver needs to be compiled into the kernel, the CAPI manager needs to be, too.

There are currently three drivers for ISDN boards that work with the CAPI manager:

avmaic
    Driver for the active board family from AVM.

daic
    Driver for the old legacy Eicon boards S, Sx, SCOM and Quattro. But this driver has currently pre-alpha status and needs a lot of bugfixing.

ix1a
    Driver for ITK IX1 / Digi Datafire active ISDN boards.

This seems to be a rather short list of supported boards for the CAPI manager. But other drivers will follow, even for passive ISDN boards.

  CAPI support for user space applications
For user space applications there are two ways to address the kernel CAPI manager. The first and conveniest is the use of the (shared) library libcapi20.so. There are header files including all required definitions for CAPI function calls and messages. One only has to link to the library and call the CAPI functions in the application code to communicate over ISDN. Maybe this library will be extended with additional helper functions in the future (or there will be a second library for this task).

The other type of CAPI access for user space applications is to use the CAPI device named /dev/capi20 directly. For this no additional library is necessary. A CAPI application would need to open the device and perform several operations on the resulting file descriptor. Some CAPI operations are implemented as IOCTLs, others are read and write operations.

  Tools
There are some tools to help in programming CAPI applications and hardware drivers. The first named capitest is a simple test application, able to list the information about installed hardware and to perform simple ISDN connections.

It is very hard to create applications or drivers for a CAPI implementation without a facility to trace CAPI calls and messages. In c4b this task is accomplished by the kernel CAPI managers trace functionality and the tool capitrace. With this combination one can create and interpret CAPI traces at the (kernel) application level and at the controller driver level. The later is only possible for users with root access rights. Root can capture all events and data. Normal users can only trace applications running under their account or group.

  I4B support
It is not necessary to write a hardware driver for c4b and a second one for I4B for the same board or device. The kernel module i4bcapimgr provides I4B with support for ISDN controllers driven by the CAPI manager. So every hardware with a driver for the CAPI manager can also be used with I4B without the need for a special I4B driver.

Unfortunately the other way around is not possible. So to use an ISDN board with CAPI one has to write a driver for the CAPI manager. The existing I4B drivers cannot be used directly.

SEE ALSO
capi20(3), avmaic(4), capidev(4), daic(4), i4b(4), i4bcapimgr(4), ix1a(4), kcapimgr(4), capi-trc(7), capitest(8), capitrace(8), kcapi(9), kcapi-drv(9). CAPI Association e.V., Common ISDN API v2.0 4th Edition, June 2001, see http://www.capi.org.

HISTORY
c4b first appeared as an add-on for FreeBSD 4.6.

AUTHORS
This manual page and the above mentioned components were written by Thomas Wintergerst <twinterg@gmx.de>.

BUGS
All components mentioned above are currently only available for FreeBSD 4.6, 4.7, 5.x. A port to the other BSD flavours like NetBSD and OpenBSD must still be done.

The CAPI manager, the CAPI device module and the shared library including its header files should be ready for use on other platforms than Intel, e.g. the Alpha platform. These components should be ready to support big endian hardware, even though CAPI is defined with little endian byte order. But this is currently not tested.