DAIC(4)

NAME
daic - CAPI manager driver for legacy Diehl active ISDN controllers

SYNOPSIS
device kcapimgr
device daic

options DAIC_LOG_LEVEL="1"
options DAIC_MAX_APPLICATIONS="30"
options DAIC_MAX_NCCI_PER_PLCI="4"
options DAIC_MAX_NCCI_PER_PORT="128"
options DAIC_MAX_PLCI_PER_PORT="64"

# Diehl S, SX, SXn, SCOM (specifying the memory size is optional)
hint.daic.0.at="isa"
hint.daic.0.maddr="0xD0000"
hint.daic.0.msize="0x800"
hint.daic.0.irq="10"

# Diehl Quadro (specifying the memory size is optional)
hint.daic.0.at="isa"
hint.daic.0.maddr="0xD0000"
hint.daic.0.msize="0x2000"
hint.daic.0.irq="10"

# Diehl S2m (specifying the memory size is optional)
hint.daic.0.at="isa"
hint.daic.0.maddr="0xD0000"
hint.daic.0.msize="0x4000"
hint.daic.0.irq="10"

DESCRIPTION
The daic kernel module implements a CAPI manager hardware driver for the following legacy active ISA ISDN boards from the Diehl Elektronik GmbH, now Eicon Networks Corporation:

S
SX
SXn
SCOM
Quadro
S2m

The code for all boards but the S2m is implemented, but currently only the SCOM board is (very little) tested. The S2m board uses the same logical interface as the S0 boards, but the physical communication is different. The code may be implemented if someone really requires the driver to support this board. The author does not have access to such board, so testing must be done completely by someone else.

This driver was inspired by the handbook for the boards S, SX and SCOM. This book also included some documentation about the hardware interface to the boards. The remaining boards Quadro and S2m use the same or a similar interface. The Quadro board duplicates the hardware interface three times, so it looks like four simple S0 boards. This fact and some other details were taken from an old attempt of Martin Husemann to create a driver for i4b and the Linux driver for Eicon boards.

The driver may be directly compiled into the kernel or installed as a separate kernel module. The later method is preferred because of its flexibility. As all boards are ISA boards, some additional information besides adding a device line to the kernel configuration file must be provided so the driver can address ‘his’ hardware. Since FreeBSD 5.0 this is done by adding hints to the file /boot/device.hints. The boards use memory mapped i/o, so no port but a memory address must be specified. This address is assigned to the board through switches on the board (see the board's hardware manual for further information). The same is true for the interrupt number.

The memory size need not be specified for the boards. It is possible to automatically detect, if a board has only the S0 or the S2m memory interface. As a result of this detection the board is loaded with the right primary bootstrap software. This board software is able to detect the detailed board type, even if it is a Quadro or not. And this delivers the size of the memory interface.

  Board firmware
Active controllers always need some firmware loaded to run. This firmware download is done using the tool daicctl. See daicctl(8) for a description of its usage.

The board needs two firmware files to run: the bootstrap code and the protocol firmware. The bootstrap file name for S0 boards is dnload.bin, for S2m boards it is called prload.bin. The protocol firmware files are named according to the D-channel protocol to be used, prepended by “te_”, and get an extension after the board type. For the DSS1 (Euro-ISDN) protocol the firmware file names for the supported board types are:

S   te_etsi.bin

    te_etsi.sx

SCOM
    te_etsi.sy

Quadro
    te_etsi.sq

S2m te_etsi.p

All these files for the boards supported can be found in the directory /usr/share/capi/daic. Currently the only D-channel protocol available is DSS1 (also called Euro-ISDN). For other D-channel protocols different protocol firmware files are needed. They may be extracted from the last software package for the Microsoft Windows operating systems available from Eicon (see http://www.eicon.com and search for “legacy” boards).

The driver and the boards also support some configuration settings that might be set through daicctl. This includes the line configuration and some rarely used controller options. See daicctl(8) for a description of all available controller configuration options.

  Controller naming and addressing
When the driver is loaded, it attaches every ISDN board it is able to drive. Each board found gets a device name. The first is termed daic0, the second daic1 and so on. For each board all available ISDN ports are registered at the CAPI manager as a separate controller (Note: The Quadro has four ports). With this registration every port gets an additional name that is available through the CAPI extension function kcapi_get_ctlr_driver_info(). This name consists of the board type name and a unique number (in fact this number is the device number incremented by 1). Boards with more than one ISDN port get the respective port number added to the name so every port gets a unique name.

If there are e.g. two boards of the types SCOM and Quadro installed, the following devices are created (in this example the SCOM will be identified first by the kernel):

daic0 (the SCOM)
daic1 (the Quadro)

The corresponding CAPI controllers are registered with their respective names as follows:

CAPI controller 1: SCOM-1
CAPI controller 2: Quadro-2/1
CAPI controller 3: Quadro-2/2
CAPI controller 4: Quadro-2/3
CAPI controller 5: Quadro-2/4

  Options supported by the driver
The driver may be compiled with any of the following options. They are normally not needed. But there may be cases where one or more have to be specified.

DAIC_LOG_LEVEL="1"
    If there is a problem with the driver, with a board or when evaluating the driver with currently untested hardware, it may be required to let the driver produce debugging output. There are currently seven levels defined for the logging level of the daic 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 a hardware communication failure with the board is normally signalled 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 messages when loading the firmware or the configuration.

    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, (nearly) 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. The only messages not covered are messages in the interrupt handler and messages for transfering data messages.

    LOG_DATAMSG (5, D)
        Print out messages regarding the exchange of data blocks with a controller. As data communication is the main thing when doing ISDN connections, this will produce a lot of output. So use this level with care and only if debugging the data exchange routines of the driver.

    LOG_IRQ (6, I)
        Print out messages in the interrupt context. This bit must be used with care. It is possible that indications or return codes from the board are lost because of the interrupt handler using up too much CPU processing time.

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

DAIC_MAX_APPLICATIONS="30"
    To reduce memory allocation of the driver there is a limit in the number of applications that may be registered at a controller concurrently. This value is set to 30 by default. If one needs to register more than this number of CAPI applications with one controller, this setting may be modified.

DAIC_MAX_NCCI_PER_PLCI="4"
    To reduce memory allocation of the driver but maintain performance there is a limit in the number of NCCIs that can be maintained per PLCI for a board. This value is set to 4 by default. If one needs to handle more than this number of NCCIs per physical connection, this setting may be modified. Note that this setting has an effect for both S0 and S2m boards.

DAIC_MAX_NCCI_PER_PORT="128"
    To reduce memory allocation of the driver but maintain performance there is a limit in the number of NCCIs that can be maintained per port of a board. Note that this setting has an effect for both S0 and S2m boards.

DAIC_MAX_PLCI_PER_PORT="64"
    To reduce memory allocation of the driver but maintain performance there is a limit in the number of PLCIs that can be maintained per port of a board. In most cases a PLCI is equivalent to a physical connection. But when supplementary services are used (currently not supported), there may be more than one PLCI for a single call. Note that this setting has an effect for both S0 and S2m boards.

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

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

capi.daic.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.

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

SEE ALSO
c4b(4), kcapimgr(4), daic.cfg(5), daicctl(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
The daic driver first appeared as an add-on for FreeBSD 5.0.

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

ACKNOWLEDGEMENTS
The information about the hardware interfaces of the various ISDN boards necessary to implement the driver, was derived from the board manual for S, SX, SXn and SCOM boards, an old attempt by Martin Husemann to create an i4b driver and the Linux driver for Eicon boards.

BUGS
Flow control is currently missing for HDLC and X.75 connections. A Disconnect-B3-Request (in fact the equivalent request on the controller level) bypasses all still buffered data blocks in the controller that are waiting to be sent.

The driver is currently very few tested. The only tests were done with an SCOM board.

The driver should be functional on other BSD operating systems than FreeBSD 5.x. But the other flavours like NetBSD or OpenBSD must be handled by other persons.

As the boards supported by the driver use only the ISA bus, there is no need to port the driver to other machine architectures than the Intel platform.