Guide to install CAPI for BSD on FreeBSD
========================================

CAPI for BSD (in short C4B) is the implementation of CAPI for the *BSD
operating systems. Currently only FreeBSD is supported, the other BSD flavours
may follow if someone will provide the necessary modifications (the author only
works with FreeBSD).

For a complete documentation see the included manual files, starting with
c4b(4) maintained under the directory "./c4b/tools/man".

The C4B package comes with two CAPI applications called "capitest" and
"capitrace" as support tools and the module "i4bcapimgr" as the link between
C4B and I4B (so CAPI controllers can be used by I4B and applications based on
it). Capi4HylaFax and Asterisk can also be used, in the future more
applications may follow.

Currently there are two hardware families that are really supported by C4B:

   The active board familiy from AVM:
      AVM B1 ISA
      AVM B1 PCI v3 and v4
      AVM B1 PCMCIA
      AVM C2
      AVM C4
      AVM T1 ISA
      AVM T1 PCI

   The active board family from ITK, now Digi International (the boards were
   originally called IX1, after ITK became part of Digi they were called
   Datafire):
      IX1 Basic ISA (1MB or 4MB memory)
      IX1 Basic PCI
      IX1 Octo ISA
      IX1 Primary PCI

All boards except the AVM T1 variants are successfully tested to work. Any
voluntaries for the AVM T1?

There is an additional driver in development state for the legacy Diehl (now
Eicon Networks Corporation) active ISDN boards S, SX, SXn, SCOM and Quadro (ISA
boards). But it still needs a lot of testing (and it lacks fax-g3 support
because of missing hardware features).

Earlier versions of C4B tried to completely integrate into the FreeBSD source
tree. The patchsets and shell scripts modified many parts of the source tree
and so were highly version dependent.

Now C4B is intended to be compiled and installed outside the FreeBSD source
tree. Only I4B must be modified to support CAPI-manager based controllers over
C4B. This makes updating FreeBSD and C4B much easier. The only drawback is that
C4B cannot be compiled directly into the kernel. Installation as separate
kernel modules is required. It is still required to have the system sources
installed.

Note: For 4.6-RELEASE and 4.7-RELEASE there is a separate package. Because of
the many differences between 4.x and 5.x it is not possible to provide a single
source code base supporting both operating system families. The package for 4.x
will get bugs fixed if necessary. But new features and controller drivers will
be implemented for 5.x and later. The 4.x-RELEASES after 4.7 are not tested.
The package may only be adapted on demand and if this request is reasonable.

Note: Versions before 5.3-RELEASE are not officially supported any more. The
patchsets for the 5.3-RELEASE should also be applyable to earlier 5.x-RELEASEs.
But the PC-CARD subsystem for earlier systems does not know about the file
"pccarddevs.h". You may need to modify the Makefile under
"./c4b/kernel/modules/avmaic" to not include this file name.



Board firmware
--------------

This package contains board firmware files for the supported board types . They
are installed into subdirectories under the directory "/usr/share/capi". For
AVM boards this is "/usr/share/capi/avmaic". The most recent versions are
provided by AVM (see http://www.avm.de).  You may extract them from the
MS-Windows Setup package or the Linux driver. But the most convenient way would
be 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).

For the legacy Diehl boards the directory "/usr/share/capi/daic" contains the
last firmware files that can be downloaded from the Eicon support pages (see
http://www.eicon.com, search for "legacy" boards). So there is normally no need
to get new firmware files, if the DSS1 (Euro-ISDN) D-channel protocol is
sufficient for using the boards.

For ITK IX1 (Digi Datafire) boards the directory "/usr/share/capi/ix1a"
contains the last firmware files that could be downloaded from the Digi web
site. Unfortunately this site does not provide any driver packages any more for
the boards supported by the ix1a device driver. So the firmware files delivered
with this package will not need to be substituted by other versions.



Installation instructions
-------------------------

1. Unpack the compressed tar file into a directory of Your choice.

2. Read the file README. ;-) Check if Your operating system is one of the
   releases supported. Currently C4B should work on all 5.x versions starting
   at 5.3-RELEASE (older versions may work, too) and on 6.0-STABLE (tested for
   6.0-STABLE from 2006-01-16).

3. Check your kernel configuration. If you are using the GENERIC kernel, you
   are already done. If you are using a custom kernel, you must remove or
   comment out any reference to "iavc" and "i4bcapi" in your kernel
   configuration file. These two drivers will also try to drive the AVM boards
   found in your machine. But only one driver can do this. If a second driver
   tries to access a board, your kernel may crash on the next boot. Be sure to
   rebuild and install a new kernel if you must make changes to your kenel
   configuration. See also the next step before you start rebuilding a new
   kernel.

4. If you plan to use I4B together with C4B, i.e. to use CAPI-manager based
   controllers with I4B interfaces like "/dev/i4brbch0" or "/dev/i4btel0", you
   have to patch the kernel sources and the I4B user space tools. To do this
   follow the steps below. If this is not the case proceed with step 5.

   a) Go to the directory with the name of your system release under "patches",
      e.g. "patches/FreeBSD-5.3-RELEASE". In this directory run the shell
      script "./do-patches.sh". The script supports an optional parameter
      defining the base directory of the source tree to patch. This is by
      default "/usr/src", but some people might have their source tree arranged
      differently.

      If you operating system version does not exactly match one of the patches
      directories, choose the best match. E.g. for 6.0-RELEASE go to the
      directory "FreeBSD-6.0-STABLE-060116". The patchset in this directory is
      created on 2006-01-16 for 6.0-STABLE, but should work for all 6.x
      versions since 6.0-RELEASE.

      Note that you may remove any C4B changes from your source tree by calling
      "./undo-patches.sh".

   b) Rebuild and install the kernel. There are no additional settings to make
      for C4B. It is only necessary to build the kernel with the patches
      applied. See the FreeBSD handbook for information about how to build and
      install a new kernel. You will need to reboot the system after installing
      the new kernel.

   c) Install the patched header files to "/usr/include". This is done by
      executing "make obj && make depend && make && make install" in the
      directory "/usr/src/include".

   d) Rebuild and install the I4B user space tools. This is done by executing
      "make obj && make depend && make && make install" in the directory
      "/usr/src/usr.sbin/i4b". The command should execute without problems.

5. After installing a new kernel and rebooting the system, if necessary because
   of steps 3 or 4, execute the commands "make obj && make depend && make &&
   make install" in the C4B base directory. This will build and install all
   parts of C4B, including kernel modules, the CAPI shared library and the
   tools. If this completes successfully, you now have C4B installed.

   Note that the "make depend" step is really necessary. It creates the header
   files needed to interface to the currently installed kernel. If this stop is
   left out, the "make" step will fail because of missing header files.

6. Configuring the CAPI subsystem. In "/etc/rc.conf" you have to add some
   variable assignments to enable CAPI support. The main CAPI subsystem is
   enabled through adding:

      capi_enable="YES"

   Additionally you have to enable the driver for the ISDN board you want to
   run. To enable all supported board families enter the following lines:

      avmaic_enable="YES"
      daic_enable="YES"
      ix1a_enable="YES"

   You should only enable the drivers you really need.

    It may also be necessary to modify "/boot/device.hints" if you plan to use
    any ISA based ISDN board. See the manual files for the board drivers
    (avmaic(4), daic(4), ix1a(4)).

7. Reboot the machine.

8. Modify the board configuration file(s) that is(are) automatically created
   when loading the CAPI driver(s) for the first time. Follow the instructions
   in the respective driver and control tool manuals (e.g. avmaic(4) and
   avmaicctl(8) for AVM boards). The startup scripts will automatically
   create an initial default configuration file if the corresponding driver is
   enabled but there is still no configuration file. The created file contains
   records for every board found in the system.

   You should modify the file for your ISDN board and restart the driver. For
   AVM boards this is done by calling "/etc/rc.d/avmaic restart". This will
   re-load the boards with their firmware and the current configuration. For
   other CAPI drivers and boards the same procedure works, substituting
   "avmaic" by "daic" or "ix1a".

   PC-CARD or PCMCIA ISDN adapters like the AVM B1 PCMCIA will need some
   special configuration settings. See the manual file for the respective
   board driver (e.g. avmaic(4) for the AVM B1 PCMCIA).

9. Test Your CAPI subsystem through "capitest" (see its manual page). If this
   step is successful, You have a working CAPI subsystem for ISDN access in
   Your FreeBSD machine. Congratulations!

Now You will want to read the manual pages, starting with c4b(4).

Be sure to recompile and reinstall C4B after a system update. It is necessary
to clean out the formerly created compilation targets by executing "make
cleandir" from the C4B base source directory. Otherwise the kernel modules may
still be compiled to match the interface of the older kernel.

Thomas Wintergerst,
<twinterg@gmx.de>
