KCAPIMGR(4)

NAME
kcapimgr - Kernel CAPI manager of C4B

SYNOPSIS
device kcapimgr

options KCAPIMGR_LOG_LEVEL="1"

DESCRIPTION
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 are dispatched to the respective controller by the CAPI manager and vice versa.

If an ISDN controller shall be used with c4b, a driver kernel module must register it at kcapimgr. This way it is possible to support several ISDN controllers from multiple vendors in the same machine concurrently. On other operating systems it is mostly only possible to install multiple ISDN controllers of a single manufacturer into the same machine. This limitation does not exist in c4b.

The CAPI manager performs application id and controller number mapping if it is necessary for a specific controller. Active ISDN controllers (and even passive ones) may introduce a limitation on the usable controller numbers and / or application ids. This is declared by the driver module when registering the controller at the CAPI manager. The CAPI applications do not recognize this mapping, the CAPI manager handles it transparently.

The kernel CAPI manager only provides kernel modules with CAPI. To support user space CAPI applications an additional kernel module named capidev must be loaded. This module uses the kernel application interface of the CAPI manager and links user space CAPI applications to it.

  Options supported by the driver
The CAPI manager supports the following compile time option.

Note: It is recognized if the module is compiled directly into the kernel binary and if it is compiled as a separate loadable kernel module.

KCAPIMGR_LOG_LEVEL="1"
    If there is a problem with the CAPI manager, an application or an ISDN controller driver, it may be required to let the driver produce debugging output. There are currently five levels defined for the logging level of the kcapimgr driver. When a string is to be printed within the driver code and the corresponding level of the print command is less than or equal to the currently active logging level, the output goes to the console (or wherever kernel output is configured to go to). Every line of output contains an isolated letter that resembles the logging level of the message. The following values may be set as the logging level. The default value is 1, so errors are always printed. The letter after the logging level is the letter that is inserted within log messages of the respective level.

    LOG_ALWAYS (0, A)
        Print out only messages that cannot be suppressed. But beware that this level suppresses regular error messages. So it is normally not useful to set the logging level to 0.

    LOG_ERROR (1, E)
        Print out messages about errors. These errors are not related to e.g. CAPI error result values. Instead misbehaviour of drivers or applications is normally signaled as an error. The logging level should always be 1 or higher.

    LOG_INFO (2, M)
        Print out informational messages (and also messages for lower levels). This level produces a little bit more output than setting only the LOG_ERROR level. It triggers the output of some informational messages.

    LOG_TRACE (3, T)
        Print out messages for the tracing level. This triggers some messages when a CAPI message is handled (or not) or an application is registered or released.

    LOG_DEBUG (4, D)
        Print out messages for the debugging level. If this level is set, all logging messages the driver can produce are enabled. This is normally used for debugging the driver, to see if it works correctly or where some error occurs. ‘related’ modules like capidev or controller drivers, to see if they work correctly or where some error occurs.

    The logging level may also be set by the sysctl() system call and through kernel environment variables. kcapimgr registers a sysctl variable named capi.kcapimgr.loglevel. This variable may be modified at any time after loading the driver. This is normally the best way to change the logging level.

    If it is necessary to enable logging messages for the startup phase of the kcapimgr driver, one can set the kernel environment variable capi.kcapimgr.loglevel in the file /boot/loader.conf the same way as the sysctl variable.

    So it is normally never needed to directly compile in a special default logging level into the kcapimgr driver module.

  Application side interface
The kernel CAPI manager provides a function interface for kernel CAPI applications. This interface is modelled after other CAPI implementations, notably the Novell NetWare CAPI manager and the Linux kernel CAPI implementation. As the NetWare CAPI manager is most similar to the functionality of the c4b CAPI manager, the interface definitions of these two are very similar. Only the UNIX specific kernel properties lead to some differences.

As usual all kernel mode CAPI applications must first register to send or receive some CAPI message. Other functions like kcapi_get_profile(), kcapi_get_manufacturer() and the like may be called without prior registration.

All CAPI messages are exchanged through ‘mbufs’. If You do not know this term, You probably do not want to write a kernel space CAPI application. The CAPI message makes up the data part of an mbuf. The mbufs are allocated with a packet header, so it is possible to forward data blocks to network modules and vice versa. An attached data block for Data-B3-Requests or -Indications is stored in a second mbuf. The address of this mbuf is stored in the member m_next of the mbuf for the corresponding CAPI message. This way both mbufs of such CAPI messages are released automatically if the main CAPI message mbuf is released.

A complete definition of the application interface of the kernel CAPI manager is described in kcapi(9).

  Controller driver side interface
The second interface provided by the CAPI manager is used to communicate with ISDN controller drivers. For every controller to be used with the CAPI manager a driver module must be loaded. This driver module must register all controllers it drives at the CAPI manager. This registration must be done even if the controller needs its firmware downloaded before it can be used. For downloading firmware and configuration data to active ISDN controllers there is an extension function to the regular CAPI specification. A controller driver can (and must) enable or disable each of ‘his’ controllers at the CAPI manager when a firmware download is complete or the board is reset.

Because of the general registration mechanism it is possible to install ISDN controllers of different manufacturers into the same machine. It is only necessary to load all drivers necessary to use each board.

It is possible to let each driver (or the controller itself if it is an active one) define its own controller numbering scheme and to create its own application ids when registering CAPI applications. The CAPI manager performs a mapping for these identifiers on every CAPI message exchanged with such controllers. So beware that in CAPI traces at the application level and at the controller level the application id and the controller numbers may differ because of the mapping function of the CAPI manager. Of course the mapping, especially the controller number mapping, needs some CPU time and so it is advisable for driver writers not to use this feature. Instead the driver shall rely on the numbering scheme provided by the CAPI manager.

A complete definition of the controller driver interface of the kernel CAPI manager is described in kcapi-drv(9).

  Tracing of CAPI function calls and messages
A CAPI implementation without the possibility to create a CAPI trace is not of much use for application (or controller driver) developement. kcapimgr implements this feature through manufacturer specific CAPI messages described in capi-trc(7).

A normal user can only create traces at the application level and only for his own applications or processes running under one of the groups he is a member of. Root can trace all applications and additionally can create traces at the controller level. These later traces may differ from the application level because of the possible application id and / or controller number mapping for the respective controller.

The content of a CAPI trace can be configured in many ways through settings in the manufacturer specific CAPI messages when starting a trace. Function calls can be included or excluded, the same is true for general CAPI messages. If CAPI messages are included in general, another option is to include Data-B3 messages (or not), too. Additionally the data blocks of traced Data-B3 messages can also be included in the trace. The data blocks may be included completely or only their first few bytes.

One does not have to write his own tracing application, allthough this is possible. There is already the tool capitrace that performs this task.

  Sysctl variables registered by the driver
Besides the logging level already mentioned before the kcapimgr module registers some other sysctl variables. All but the logging level are read-only, just the loging level may be modified.

capi.kcapimgr.version
    The version number of the kcapimgr driver module.

capi.kcapimgr.loglevel
    The logging level variable was already mentioned before. It shows the current setting of the logging level and may be changed to produce more or less diagnostic output.

capi.kcapimgr.apps_registered
    This variable shows the current number of CAPI applications registered at the CAPI manager. Its value is always updated when a new application calls kcapi_register() or another performs a kcapi_release().

capi.kcapimgr.ctlrs_registered
    Similar to the number of registered applications this variable counts the number of controllers registered at the CAPI manager.

capi.kcapimgr.tracers_registered
    Similar to the number of registered applications this variable counts the number of tracers activated by any CAPI application. Its value is always updated when a new CAPI trace is started or stopped.

  Supported kernel environment variables
The kcapimgr module supports the following kernel environment variables. Such variables are only accessible in kernel space, not by regular processes. The command kenv provides a method to print and modify the current content of the kernel environment. The best way to persistently set a kernel environment variable to a specific value is to place variable assignments into the file /boot/loader.conf.

capi.kcapimgr.loglevel="4"
    This variable initializes the logging level of the kcapimgr module on startup. The possible values are already mentioned in the paragraph Options supported by the driver.

SEE ALSO
capi20(3), c4b(4), capidev(4), capi-trc(7), 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
kcapimgr first appeared as an add-on for FreeBSD 4.6.

AUTHORS
This manual page and the kernel CAPI manager were written by Thomas Wintergerst <twinterg@gmx.de>.

BUGS
The CAPI manager is currently only tested under FreeBSD 4.6, 4.7, 5.0 and 5.1. This list should be extended to the other BSD flavours like NetBSD and OpenBSD.