IX1A(4)

NAME
ix1a - CAPI manager driver for IX1 active ISDN controllers

SYNOPSIS
device kcapimgr
device ix1a

hint.ix1a.0.at="isa"
hint.ix1a.0.port="0x380"
hint.ix1a.0.irq="5"
hint.ix1a.0.flags="0x000x"
hint.ix1a.0.flags="0x001x"
hint.ix1a.0.flags="0x002x"

DESCRIPTION
The ix1a kernel module implements a CAPI manager hardware driver for the following active ISDN boards from ITK, now part of Digi International:

IX1 / Datafire Basic ISA
IX1 / Datafire Basic PCI
IX1 / Datafire Octo ISA
IX1 / Datafire Multimodem
IX1 / Datafire Primary PCI

ITK named their boards IX1, when Digi took over ITK the boards changed their base name to Datafire. All boards except the Multimodem are well tested. See the subsection for the Multimodem boards for further information.

  Notes regarding 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 (available through the user space CAPI library function capi20_reset_ctlr()) for downloading any number of firmware and / or configuration data blocks to a controller. A controller driven by ix1a needs either two or three such data blocks. The first is the boot code, needed to expand and start the real (compressed) firmware expected as the second data block. The third is a configuration data structure, needed to set non-default board settings.

To perform the task of downloading the firmware and configuration to an active IX1 / Datafire ISDN controller there is the tool ix1actl. It must be used with a configuration file name. This file must contain all necessary settings and the path names to the boot code and firmware files to use. The parameters are collected and sent to the controller as the third data block as mentioned in the paragraph before.

The boot code and firmware files themselves are strictly speaking not part of the ix1a driver or ix1actl tool distribution, although they are absolutely necessary for running the board. But with permission from Digi a version of the firmware files for each of the supported boards is installed with the ix1a driver into the directory /usr/share/capi/ix1a. These files are the last versions available as known to the author. So it will not be necessary to get newer versions. But if needed they can be extracted from the Microsoft Windows drivers for the specific board.

  IX1 / Datafire Basic
The IX1 Basic boards were manufactured in several variants. Some of these are:

Basic ISA v1.1 with 1MB memory
Basic ISA v1.2 with 1MB memory
Basic ISA with 4MB memory
Basic ISA for Up0 instead of S0 line access
Basic ISA with / without a serial debug port
Basic ISA with 4MB memory and Octo extension socket
Basic PCI with 4MB memory

Basic ISA boards can use one of the four i/o base addresses 0x380, 0x388, 0x390 and 0x398 and one of the four interrupts 5, 9, 10 and 11. Boards of revision 1.2 can use the two additional i/o addresses 0x3A0 or 0x3A8. The interrupt as well as the i/o base address are sent to the board when attaching it. I.e. the board does not ‘know’ its i/o base address on startup. To distinguish multiple boards in a single machine every Basic ISA board has two jumpers defining a card number. Older boards may not have real jumpers but are soldered to a fixed card number. Both jumpers set reflect card number 1, both unset mean card number 4. The driver identifies the board through its card number and tells it the i/o base address and the interrupt to use.

As usual for ISA boards they need some entries in /boot/device.hints to specify the i/o address base and the interrupt to use. The flags must be used to give the board type as ‘Basic ISA’ to distinguish it from ‘Octo ISA’ and ‘Multimodem ISA’. This distinction is specified as the second nibble of the flags value. Additionally the card number (minus 1) must be set in the lowest nibble of the flags. So card number 1 needs the flags set to 0x0000, card number 4 needs flags 0x0003.

Note that boards with hardware version 1.1 cannot share an interrupt. If interrupt sharing works for the other ISA boards must be checked for every specific case.

Basic PCI boards do not need any further hardware configuration. Their i/o base addresses and the interrupt to use are automatically assigned by the system.

Basic boards have a socket for an extension module. There are several variants of these modules. They basically provide support for fax group 3 and maybe other analog modem protocols, one or two channels and different transfer speeds from 9600 up to 33600 bit/s. Extension boards before hardware revision 2.1 are limited to a speed of 9600 bit/s (with the current firmware), even if they have a 14400 bit/s chip on them.

Boards with only 1MB memory do not provide all functionality. E.g. they only support either fax group 3 or modem protocols, not both, even if the extension board provides both capabilities. The memory chips for 1MB boards have the number ‘256’ in their memory chip description, 4MB boards normally have chips labled with a number containing ‘4400’. There are two different firmware files ixb-1m-fax.bin and ixb-1m-modem.bin for either fax or modem operation. Boards with 4MB memory automatically support fax group 3 and modem protocols if they can be used with the specific extension board.

Note that it is possible to load 1MB firmware onto boards with 4MB memory, but not the other way around. So be sure to load the boards with the correct firmware files. The firmware file ixb-4m.bin can only loaded onto boards with 4MB memory. The boot code file ixboot.scr is needed for all Basic variants.

  IX1 / Datafire Octo
The Octo board is in fact two boards connected by a flat ribbon cable. The main board is simply a 4MB memory Basic ISA board with a connector for the Octo cable. The Octo extension board needs no additional i/o ports or interrupts. The only distinction to a normal Basic board is to use the firmware file ixo.bin instead. It contains the code to address the three additional ISDN ports on the Octo extension board over the extension cable.

The ix1a driver needs to know if a specific board shall be used as a Basic board or as part of an Octo combination. This is done by setting the flags value in /boot/device.hints to the value 0x0010 for card number 1, 0x0013 for card number 4, etc. So the second nibble of the flags value set to 1 determines the board type to be ‘Octo’.

To support fax group 3 on all ISDN ports the Octo extension board has three extension connectors for fax or modem extension boards. You need four dual channel fax or modem extension boards to support fax group 3 on all ISDN ports. But the Octo combination has some restrictions. The following statements are taken from the readme file of the last Microsoft Windows driver software and the board's manual:

Line access restrictions
    Octo systems do not support S0-interfaces with mixed line access. All ISDN ports must be configured to use either all point-to-point or all multipoint access.

DTMF
    With this version of the download software only three connections with DTMF handling (recognise DTMF, build DTMF) could be established.

Fax / modem operation in general
    Modem mode is only activated with Fax/Modem modules version 2.1 with a 33.6 kbit datapump. In this case V.42 and V.42bis protocols will be supported.

    If not all four Fax/Modem extension sockets are used, start completing them from the port for the last ISDN port on. I.e. for only one fax extension board stick it onto the extension board for port three, the next on the one for port 2. Use the socket for the main board as the last one.

Fax / modem operation with 14400 bit/s datapump
    While four 14400 bit/s-Fax-connections are established, the NEXT RECEIVING fax connections can be established only with a speed of 9600 bit/s.

    While four 14400 bit/s-Fax-connections are established, only ONE further SENDING fax connection with a speed of 14400 bit/s can be established.

    By fax data reception with Fax/Modem modules version 1.4 (DPL) modes with transfer rates till 9600 bit/s are supported.

    Modem connections can be established only with a 33.6 kbit datapump.

    By mixed completion of Fax/Modem modules, the Basic card has to be completed with a 14400 bit/s kbit datapump.

Fax / modem operation with 33600 bit/s datapump
    With Fax/Modem modules version 2.1 with a 33600 bit/s datapump it is possible to have eight 14400 bit/s-fax-connections simultaneously.

    If four modem connections with 33600 bit/s are established, the next modem connection could have less than 33600 bit/s data transfer rate.

    A maximum of two modem connections can use the V.42bis protocol simultaneously.

  IX1 / Datafire Multimodem
Multimodem boards have eight 33600 bit/s modem chips, but do not have a line interface. Instead of a direct connection to the ISDN they must be connected through the MVIP bus to an Octo or Primary board (or even a completely different board with an MVIP bus). To drive a modem connection one first has to establish a B-channel connection on an Octo or Primary board, direct the B-channel path over the MVIP bus to the Multimodem board and let it handle the fax or modem protocol.

A CAPI application therefore must handle two PLCIs on different controllers for a single connection. And it must select special, proprietary B-channel protocols and settings to use the MVIP bus.

This is the reason why the Multimodem board is currently not tested. One has to implement an application specifically designed for this purpose. This task is left to the one that really needs to use a Multimodem board. Currently only the download operation seems to work correctly.

Like Basic ISA boards Multimodem boards need an i/o base address and an interrupt to use. They can use the same list of i/o base addresses as Basic ISA boards v1.2, extended by i/o base address 0x368. A Multimodem board can use the interrupts 5, 7, 9, 10, 11, 12 and 15. Every Multimodem board has a jumper field with three jumpers to define the card number from 1 to 8. All jumpers set denote card number 1, all open mean card number 8. This card number (minus 1) must be set in the flags value in the /boot/device.hints entry. The second nibble of the flags must be set to 2 for Multimodem boards. So the Multimodem card number 1 needs the flags value 0x0020, card number 8 is reflected by the flags value 0x0027.

Multimodem boards seem to have been manufactured with 1MB or 4MB memory. There are two variants of firmware to support both board types, ixm-1mb.bin and ixm-4mb.bin, respectively. The boot code file ixmboot.scr is needed for both variants.

  IX1 / Datafire Primary
ITK manufactured several types of Primary boards. This includes ISA and pure EISA variants, as well as a PCI version. The ix1a driver only supports the Primary PCI.

There are no hardware settings to configure. All i/o resources and the interrupt to use are automatically assigned by the system.

The Primary PCI board does not need a boot code file. The firmware file ixpp.bin is the only code to be downloaded to the board.

  Controller naming and addressing
When the ix1a driver is loaded, it attaches every ISDN board it is able to drive. Each board found gets a device name. The first is termed ix1a0, the second ix1a1 and so on. For each board all available ISDN ports are registered at the CAPI manager as a separate controller (Note: The Octo board combination has four ports, the Multimodem is registered as one controller even though it has no line interface). 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 IX1 Octo and IX1 Basic installed, the following devices are created (in this example the IX1 Octo will be identified first by the kernel):

ix1a0 (the IX1 Octo)
ix1a1 (the IX1 Basic)

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

CAPI controller 1: IX1-Octo-1/1
CAPI controller 2: IX1-Octo-1/2
CAPI controller 3: IX1-Octo-1/3
CAPI controller 4: IX1-Octo-1/4
CAPI controller 5: IX1-Basic-2

It does not matter if the Basic in the example is an ISA or a PCI board.

  Enabling logging messages
Sometimes it is useful to have the ix1a driver produce logging output to find the cause of some problem. The driver does not need to be compiled with special directives for this purpose. You can simply set the sysctl(1) variable capi.ix1a.loglevel or the kernel environment variable ((kenv) 1) with the same name. The sysctl variable can be set any time after loading the driver. If the startup phase of the driver including the probe / attach operations itself must be monitored, the kernel environment variable should be set in /boot/loader.conf to initialise the logging level to the value needed.

Both ways modify the same internal variable of the driver. Whenever a string is to be printed in the driver code, there is also a logging level associated with the output string. If the current logging level is higher or equal to the one corresponding to the output string, the output is executed. If it is lower, the output is suppressed. Output goes to the kernel syslog facility. 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.

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

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

capi.ix1a.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 ix1a driver supports the following kernel environment variables. Such variables are only accessible in kernel space. The command kenv(1) 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.ix1a.loglevel="1"
    This variable initializes the logging level of the ix1a driver on startup. The possible values are already mentioned in the paragraph Enabling logging messages.

SEE ALSO
c4b(4), kcapimgr(4), ix1actl(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 ix1a driver first appeared as an add-on for FreeBSD 5.3.

AUTHORS
This manual page and the ix1a 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 source code for a Linux driver from ITK / Digi Europe. This driver source was generously put at the authors disposal by Digi. Thanks to Digi for also donating hardware for testing the driver.

BUGS
The driver is currently tested with all boards except for the Multimodem type. These boards require special messages for controlling the MVIP bus. And they need an application designed specially to handle two boards for a single connection. There is currently no such program that can make use of the Multimodem boards.

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.