AVMAIC(4)

NAME
avmaic - CAPI manager driver for AVM active ISDN controllers

SYNOPSIS
device kcapimgr
device avmaic

options AVMAIC_LOG_LEVEL="1"
options AVMAIC_MAX_APPLICATIONS="30"
options AVMAIC_MAX_NCCI_PER_CHANNEL="4"

hint.avmaic.0.at="isa"
hint.avmaic.0.port="0x150"
hint.avmaic.0.irq="5"
hint.avmaic.0.flags="0"
hint.avmaic.0.flags="0x10"

DESCRIPTION
The avmaic kernel module implements a CAPI manager hardware driver for the following active ISDN boards from AVM:

AVM B1 ISA
AVM B1 PCI v3 / v4
AVM B1 PCMCIA
AVM C2
AVM C4
AVM T1(B) ISA
AVM T1(B) PCI

The code for all boards is implemented, but currently only the S0 boards are tested. The code for the T1 boards can only be evaluated if someone would donate (or lend) additional hardware or perform the necessary tests himself.

This driver was inspired by the AVM DDK for the AVM B1 ISA ISDN controller available freely from AVM (see http://www.avm.de). The other boards in general support the same interface, i.e. they simply accept CAPI messages and deliver such messages through their i/o interface with a common and simple command set. The only difference between the various board types is the type of their hardware interface. Some support register based i/o, others use DMA based i/o. The information about these different interface types is mainly derived from the Linux driver from AVM, written by Carsten Paeth.

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. For PCI boards the only thing to do is to specify the ‘device’ line in the kernel configuration file or to load the driver. All hardware configuration data is determined automatically.

Only for ISA boards some additional information 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. Namely the AVM B1 ISA and the AVM T1 ISA need these device hints. The port number and the irq number must always be specified for these two ISA board types. Valid entries for the resources must be taken from the hardware manuals for the respective board. For the AVM T1 ISA a flags value must also be specified. This board must be configured (by jumpering) for board number 0, 1, 2 or 3. This jumper setting must be reflected in the flags value in the corresponding device hint. Board numbers 0 to 3 correspond to the flags values 0x10 to 0x13.

  Board firmware
Active controllers always need some firmware loaded to run. The CAPI manager provides the extension function kcapi_reset_ctlr() to the CAPI specification for downloading any number of firmware and / or configuration data blocks to a controller. A controller driven by avmaic needs either one or two such data blocks. The first is the real firmware. The second is a configuration data file, needed if the actual ISDN port configuration does not meet the default settings for the controller.

To perform the task of downloading the firmware and configuration to an active AVM ISDN controller there is the tool avmaicctl. It reads a configuration file and loads all boards with the firmware file and configuration settings found in this file.

The firmware file itself is strictly speaking not part of the avmaic driver or avmaicctl tool distribution. But with permission from AVM a version of a firmware file for each of the supported boards is installed with the avmaic driver into the directory /usr/share/capi/avmaic. The most current versions can be obtained from AVM themselves (see http://www.avm.de). One either has to extract the respective firmware file from the linux driver distribution or the Microsoft Windows version.

But the most convenient way is to check ftp://ftp.in-berlin.de/pub/capi4linux. This site among other things provides the latest firmware files for active AVM boards as plain files, not packaged into installation sets like on the AVM site.

The boards supported require the following firmware files for operation:

AVM B1 (all variants)
    Use the file b1.t4 for the DSS1 (Euro-ISDN) D-channel protocol. This is the D-channel protocol commonly used in Europe and most parts of the world. To run the North American protocols “NI1” or “5ESS” the firmware file b1-usa.t4 must be used, b1-1tr6.t4 is needed for the old German 1TR6 D-channel protocol.

AVM C2
    The firmware file c2.bin must be used. It supports only the DSS1 (Euro-ISDN) protocol.

AVM C4
    The firmware file c4.bin must be used. It supports only the DSS1 (Euro-ISDN) protocol.

AVM T1
    For DSS1 (Euro-ISDN) D-channel protocol the firmware file t1.t4 must be used, t1-1tr6.t4 is needed for the old German 1TR6 D-channel protocol.

AVM T1B
    The AVM T1B is an extended variant of the AVM T1 that supports DTMF detection. To enable this feature this board needs different firmware than the basic AVM T1. Use t1b.t4 for DSS1 (Euro-ISDN) and t1b-1tr6.t4 for the old German 1TR6 D-channel protocol.

  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 avamic0, the second avmaic1 and so on. For each board all available ISDN ports are registered at the CAPI manager as a separate controller (Note: The AVM C2 and AVM C4 have two and four ports respectively). 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 AVM B1 and AVM C4 installed, the following devices are created (in this example the AVM B1 will be identified first by the kernel):

avmaic0 (the AVM B1)
avmaic1 (the AVM C4)

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

CAPI controller 1: AVMB1-1
CAPI controller 2: AVMC4-2/1
CAPI controller 3: AVMC4-2/2
CAPI controller 4: AVMC4-2/3
CAPI controller 5: AVMC4-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.

AVMAIC_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 avmaic 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 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 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 avmaic driver registers a sysctl variable named capi.avmaic.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 avmaic driver, one can set the kernel environment variable capi.avmaic.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

AVMAIC_MAX_APPLICATIONS="30"
    The firmware of the active AVM boards must be provided with the maximum number of concurrently registered CAPI applications. 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.

    This value may also be set through the kernel environment variable capi.avmaic.max_applications on system startup.

    Note: Setting this value higher than the default may exhaust the onboard memory of the controller.

AVMAIC_MAX_NCCI_PER_CHANNEL="4"
    Regular ISDN connections only need one NCCI (logical connection identifier in CAPI) per physical connection. But there are B-channel protocol combinations where more than one logical connection can be performed over a single physical connection. ISO 8208 is such a B-channel protocol, but X.31 (X.25 over the D-channel) also may use several logical connections over a single physical connection. By default the maximum number of logical connections is set to 4. If more than this number of logical connections per physical connection is needed, this option must be specified in the kernel configuration file.

    This value may also be set through the kernel environment variable capi.avmaic.max_ncci_per_channel on system startup.

    Note: Setting this value higher than the default may exhaust the onboard memory of the controller.

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

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

capi.avmaic.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.avmaic.max_applications
    This variable shows the maximum number of registered applications used by the avmaic driver to initialize the board firmware.

capi.avmaic.max_ncci_per_channel
    This variable shows the maximum number of logical connections (NCCIs) supported over a single physical connection (PLCI). It is used to initialize the board firmware.

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

capi.avmaic.max_applications
    This variable is an alternative method to the compile time option AVMAIC_MAX_APPLICATIONS for initializing the maximum number of registered applications. If this kernel variable is set on loading the driver, its value is used to initialize the corresponding internal driver setting.

capi.avmaic.max_ncci_per_channel
    This variable is an alternative method to the compile time option AVMAIC_MAX_NCCI_PER_CHANNEL for initializing the maximum number of logical connections per physical channel. If this kernel variable is set on loading the driver, its value is used to initialize the corresponding internal driver setting.

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

AUTHORS
This manual page and the avmaic 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 DDK from AVM for the AVM B1 ISA and the Linux driver for the active AVM boards from AVM, written by Carsten Paeth <calle@calle.in-berlin.de>.

Thanks to AVM for donating hardware for testing the driver.

BUGS
The driver is currently untested for the AVM T1 board variants. The author currently has no access to one of these board types.

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

Besides other BSD flavours the driver should also run on other platforms than the Intel one, namely the Alpha platform. But currently the driver only supports the little endian byte order.

On FreeBSD 5.3-RELEASE the AVM B1 PCMCIA does not work directly after inserting it into the cardbus slot. It is necessary to unload and reload the avmaic driver to make the card work. A possible solution would be to patch the pccard driver so it does not reset each card by switching power off and on again when attaching it. In FreeBSD 5-STABLE this problem seems to be solved.