I4BCAPIMGR(4)

NAME
i4bcapimgr - I4B controller driver for CAPI manager driven controllers

SYNOPSIS
device kcapimgr
device i4bcapimgr

options I4BCAPIMGR_LOG_LEVEL="1"
options I4BCAPIMGR_ALLOC_MAX_BDATA_SIZE

DESCRIPTION
i4bcapimgr is the link between i4b and c4b. It if is loaded, all ISDN controllers available through the CAPI manager can be used for i4b purposes, too. All connection types provided by i4b are supported.

The driver may be directly compiled into the kernel binary, requiring this mode for the CAPI manager, too. Or it can be used as a separate kernel module and loaded on demand. This way the configuration lines mentioned in section SYNOPSIS are not needed in the kernel configuration file.

Note: The options are also recognized when compiling i4bcapimgr as a separate kernel loadable module.

  Driver operation
At the time beeing loaded i4bcapimgr asks the CAPI manager for all available ISDN controllers and their properties. Each controller is registered at the i4b device driver. This is true even for controllers currently beeing disabled, maybe because they are still not loaded with their firmware and configuration. But this is only a problem if the ISDN daemon isdnd is loaded before all controllers to use are downloaded with their firmware. And even if the ISDN daemon is loaded before the ISDN controllers are ready for use, the only thing happening is that no connection can be established.

As soon as the ISDN daemon is started, i4bcapimgr sends out a CAPI Listen-Request message to every controller configured to be used by i4b. Every incoming call for the services speech, telephony and unrestricted digital data are forwarded to layer 4 of the i4b driver.

Unfortunately i4b currently does not support point-to-point line configurations very well. Extension digits can not be collected if signalled in multiple information elements. So only the digits available in the D-channel SETUP message (or the Connect-Indication CAPI message) are forwarded to i4b. The collection of additional extension digits would require at least the configuration of the expected number of dial-in digits. As each controller may be connected to a different line, this data would need to be configured for every controller separately. As soon as i4b supports this feature, there is only little work to do in i4bcapimgr to support this feature. The internal CAPI state machines are already prepared for this operation as far as possible.

If i4bcapimgr is used as a separate kernel module, it may be unloaded from the active kernel. i4b generally is not prepared for this operation. But if i4bcapimgr is the last i4b controller driver loaded, it can safely be unloaded. Every CAPI controller is unregistered at i4b in this case and the number of available controllers is updated accordingly. Only if other i4b controller drivers are loaded after i4bcapimgr this may lead to unpredictable behaviour of i4b because there will be ‘holes’ in the i4b controller array.

  Options supported by the driver
i4bcapimgr supports some compile time options. They are recognized if compiled directly into the kernel and if compiled as a separate kernel module.

I4BCAPIMGR_LOG_LEVEL="1"
    If there is a problem with the driver, it may be required to let the driver produce debugging output. There are currently six levels defined for the logging level of the i4bcapimgr 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 for transitions of the internal state machines.

    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.

    LOG_DATAMSG (5, D)
        In addition to the other logging levels this enables messages for the data transfer. In normal operation this would lead to very much logging output filling up disk space if the kernel output is directed into a file (which is usually the case). So use this flag with care.

    The logging level may also be set by the sysctl() system call. The i4bcapimgr driver registers a sysctl variable named capi.i4bcapimgr.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 i4bcapimgr driver, one can set the kernel environment variable capi.i4bcapimgr.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 i4bcapimgr driver module.

    Note that besides debug output of the driver itself the tracing facility of the CAPI manager and the tool capitrace are also a good help for locating errors. However since i4bcapimgr is a kernel module only root is allowed to create CAPI traces for it.

I4BCAPIMGR_ALLOC_MAX_BDATA_SIZE
    Normally incoming data blocks are forwarded to the layer 4 drivers just as they are delivered by the CAPI manager. But there are cases (activated VJ compression in sppp and uncompression is performed in the received mbuf) where it is assumed in i4b that the received mbuf (special data structure in the kernel to carry data and messages for network drivers and the like) is allocated with the maximum size of 2KB (at least this was true when writing this driver).

    The CAPI manager does not enforce its drivers to allocate data containers of this size. Namely the avmaic driver for active AVM ISDN controllers allocates mbufs only with the size required to hold the data received.

    If this option is set, all incoming data blocks are copied into new mbufs of maximum size, thus wasting memory and computing time if copying is not needed.

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

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

capi.i4bcapimgr.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.i4bcapimgr.appl_id
    After the i4bcapimgr module is loaded, it registers all available CAPI controllers at the i4b driver. As soon as the ISDN daemon is started, it opens all configured controllers. This operation triggers the registration at the CAPI manager, resulting in an assigned CAPI application id. This id will remain valid until the ISDN daemon is terminated. This sysctl variable provides read access to the assigned CAPI application id for the i4bcapimgr module. It is usefull when evaluating CAPI traces to ignore all function calls and messages not related to the i4bcapimgr module.

capi.i4bcapimgr.max_connections
    This variable shows the maximum number of connections that may be established through the i4bcapimgr module. It is the summed number of B-channels of all available CAPI controllers. Not all controllers may be configured to be used by the ISDN daemon. So this is the theoretical maximum number of possible connections.

  Supported kernel environment variables
The i4bcapimgr driver supports the following kernel environment variables. Such variables are only accessible in kernel space. 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.i4bcapimgr.loglevel="1"
    This variable initializes the logging level of the i4bcapimgr driver on startup. The possible values are already mentioned in the paragraph Options supported by the driver.

SEE ALSO
c4b(4), i4b(4), kcapimgr(4), capitrace(8). CAPI Association e.V., Common ISDN API v2.0 4th Edition, June 2001, see http://www.capi.org.

HISTORY
The i4bcapimgr driver first appeared as an add-on for FreeBSD 4.6.

AUTHORS
This manual page and the i4bcapimgr driver were written by Thomas Wintergerst <twinterg@gmx.de>.

BUGS
Point-to-point line configurations are currently not supported very well. Only the digits signalled in the SETUP D-channel message (or the CAPI Connect-Indication message) are signalled to layer 4 of i4b. As soon as i4b supports the collection of additional extension digits after the D-channel SETUP message or there is a configuration setting for the expected number of dial-in digits, i4bcapimgr can be modified to support this feature with little efford.

It should be possible to perform a firmware download through the ISDN daemon (see isdnd.rc(5)). But currently this is not possible and the controller section in /etc/isdn/isdnd.rc must be left empty for CAPI manager driven controllers. The reason is that CAPI registration and the initial Listen-Request message are sent when the ISDN daemon attaches to the isdn4bsd devices. Only thereafter the download operation is started, leading into unregistering all applications. The application registration is restored on the first message sent, but the Listen-Request is not. So outgoing connections will work, but incoming connections will not.

This will be resolved when the CAPI manager is able to restore Listen-Requests automatically after a download operation.