Guide to incorporate CAPI for BSD into FreeBSD
==============================================

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

For a complete documentation see the included manual files, starting with
c4b(4) under the directory "./c4b/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).

To link C4B into an existing FreeBSD 5.x-RELEASE (or a matching STABLE /
CURRENT) one should execute the following steps. For other versions there is
no official support. You are basically left on Your own, but the file
"SystemModifications.txt" and the content of the "patches" directory may help.
Be sure 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. The 4.x-RELEASES after 4.7 are not tested. The package
will only be adapted on demand and if this request is reasonable.

Note: The patch sets for 5.0-RELEASE to 5.2-RELEASE were not updated for the
current C4B version and so are not included in this release. This is because
the author's machines currently only run 5.3-RELEASE, 5.4-RELEASE or 5-STABLE.
For version 1.0 C4B will only directly support FreeBSD 5.3-RELEASE and earlier.
For older systems the package v0.93 remains available for some time. Installing
C4B v1.0 on FreeBSD earlier than 5.3-RELEASE may need some "handwork".



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. If it is not, abort here. For Current or some state in
   between releases You may perform the integration steps "by hand". The file
   "SystemModifications.txt" and the contents of the directory
   "patches/FreeBSD-Current" may help. But in this directory there is no
   ready-made patch set. It is equiped to create a patchset for new operating
   system releases. Please look at the shell scripts in this directory.

3. 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.

   After running "./do-patches.sh" without any errors CAPI for BSD is
   completely integrated into the source tree. The next "make world" will
   create a running system with CAPI support.
   
   Note that you may remove any C4B changes from your source tree by calling
   "./undo-patches.sh". With the command line parameter "-a" not only the
   system patches are undone, but also the new c4b directories and files are
   removed.

4. Either do...

   a) ...a complete system rebuild as described in "/usr/src/Makefile" ("make
      world" or follow the steps to upgrade a running system). This will
      install a complete new system with CAPI support. This will take some time
      and beware to not overwrite Your system configuration files in "/etc", if
      this is a matter (see the hints for performing an update in
      "/usr/src/Makefile").
      
      But beware that Your current kernel configuration file does not contain
      any reference to "iavc" or "i4bcapi". See step 10 for more information
      about this topic.
      
      If You ran the "mergemaster" calls, You should proceed with step 12. If
      you are upgrading from an earlier c4b version "mergemaster" may have
      reported the script "capi" under "/etc/rc.d" as only beein in your
      installation. Let "mergemaster" remove it, as it is now replaced by a
      new set of startup scripts.
      
      If You left the "mergemaster" calls out, You have to go to step 11.
      This is necessary, because a "make installworld" will not overwrite any
      files in "/etc", it will also not install the new or modified files
      thereunder. So You have to install them "by hand".

   ...or...
   
   b) ...perform the following steps from 5 to the end of this text. This will
      need some "handwork" but will be a little bit quicker and it will not
      overwrite Your system configuration in "/etc".

5. Perform "make obj && make depend && make && make install" in the directory
   "<source base>/include". This will install the CAPI header files into
   "/usr/include". The "source base" is normally "/usr/src", but if Your
   source tree is arranged differently this might be another directory.

6. Perform "make obj && make depend && make && make install" in the directory
   "<source base>/lib/libcapi20". This will create and install the CAPI shared
   library for user space CAPI applications.

7. Perform "make obj && make depend && make && make install" in the directory
   "<source base>/usr.sbin/i4b". This will re-compile the userland code for
   I4B with the modifications necessary for supporting the CAPI manager and
   ISDN controllers driven by it. If you leave this step out and later start
   "isdnd" your system may crash.

8. Perform "make obj && make depend && make && make install" in the directory
   "<source base>/usr.sbin/c4b". This will create the CAPI support tools
   capitest and capitrace and the firmware downloading tools for the hardware
   drivers. And last but not least this will install the manual files for the
   kernel modules and the kernel mode interface to the CAPI manager.

9. Perform "make obj && make depend && make && make install" in the directory
   "<source base>/share/capi". This will install the necessary board firmware
   files to "/usr/share/capi".

10. Build and install a new kernel. Before doing this You have to remove the
    old directory under "/sys/i386/compile" or "/sys/amd64/compile" and
    perform a new "configure" run. It is not necessary to change the kernel
    configuration file to include any line for CAPI support or a specific
    controller driver. All kernel parts belonging to c4b can (and should) be
    loaded as kernel modules (no need to include them into the kernel
    directly). The startup scripts in "/etc/rc.d" will do this according to the
    configuration in "/etc/rc.conf" (see the next points in this list).

    Important: If you are planning to use c4b to access your active AVM board,
               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.

11. Do a "make install" in the directory "<source base>/etc/rc.d". This will
    install the CAPI subsystem startup scripts. If you are upgrading from an
    earlier c4b version you must remove the old startup script "capi" in
    "/etc/rc.d" "by hand". "mergemaster" will detect it suggest to remove it.

    Do a "make install" in the directory "<source base>/etc/defaults". This
    will install the file "/etc/defaults/rc.conf" with the default settings for
    the CAPI subsystem.
   
12. Check "/etc/defaults/rc.conf" for the available CAPI options (search for
    "capi" in this file). In "/etc/rc.conf" you have to enable basic CAPI
    support (capi_enable="YES") and the hardware driver for Your ISDN board(s)
    (avmaic_enable="YES", ix1a_enable="YES", etc.).
    
    It may also be necessary to modify "/boot/device.hints" if you plan to use
    any ISA based ISDN board. See "/sys/i386/NOTES" or "/sys/amd64/NOTES" for
    further information about settings and hints for the CAPI hardware
    drivers.
    
13. Reboot the machine.

14. 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 start". 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).

15. 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).


Thomas Wintergerst,
<twinterg@gmx.de>
