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/kcapimgr".

Until now the only existing CAPI applications are "capitest" and "capitrace" as
support tools in this package and the module "i4bcapimgr" as the link between
C4B and I4B (so CAPI controllers can be used by I4B and applications based on
it). A nice thing would be to include FreeBSD-CAPI support into HylaFax.
Voluntaries are sill wanted.

Currently the only hardware supported is the active board family from AVM,
namely:

   AVM-B1 ISA
   AVM-B1 PCI v3 and v4
   AVM-C2
   AVM-C4
   AVM-T1 ISA
   AVM-T1 PCI

Until now only the B1 variants and the C4 are tested to work. The C2 should
also work, because it is nearly identical to the C4 with only two ports. The T1
variants are completely untested. Any voluntaries?

To link C4B into an existing FreeBSD 4.6-RELEASE or 4.7-RELEASE 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.

1. Get the firmware files for the active AVM board(s) You want to run in Your
   FreeBSD machine. These files are only proviced by AVM (see
   http://www.avm.de). You may extract them from the MS-Windows Setup package
   or the Linux driver. As a suggestion put the firmware file(s) into the
   directory "/usr/share/capi/avmaic" (does not exist yet).

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

3. Read the file README. ;-)
   Check if Your operating system is one of FreeBSD 4.6-REALEASE or
   4.7-RELEASE. If it is not, abort here.

4. Call the shell script "getall.sh" as user root (or equivalent). This will
   patch some files in the system source tree under "/usr/src/sys",
   "/usr/src/usr.sbin", "/usr/src/include" and "/usr/src/lib". Check that all
   patch operations were successful. You can undo the patch operations by
   finding the files called "*.org.c4b" and restoring them to their original
   file names (i.e. the names without the suffix ".org.c4b").

5. Configure, compile and install a new system kernel. Look into
   "/usr/src/sys/i386/conf/LINT" for a description of the new components for
   CAPI support. There are four new kernel modules: kcapimgr, capidev, avmaic
   and i4bcapimgr. All of them may be compiled directly into the kernel, but
   also as separate kernel modules. There are options for "rc.conf" to
   automatically load the separate kernel modules at system startup, see point
   10.

6. Perform "make obj; make depend; make; make install" in the directory
   "/usr/src/include". This will install the CAPI header files into
   "/usr/include".

7. Perform "make obj; make depend; make; make install" in the directory
   "usr/src/lib/libcapi20". This will create and install the CAPI shared
   library for user space CAPI applications.

8. Perform "make obj; make depend; make; make install" in the directory
   "/usr/src/usr.sbin/i4b". This will re-compile the userland code for I4B with
   the modifications necessary for supporting the CAPI manager.

9. Perform "make obj; make depend; make; make install" in the directory
   "/usr/src/usr.sbin/c4b". This will create the CAPI support tools capitest
   and capitrace and the firmware downloading tool avmaicctl for the avmaic
   hardware driver.

10. Check "/etc/defaults/rc.conf" for the available CAPI options (search for
    "capi" in this file). You have to enable CAPI support and provide a command
    line to automatically download Your board(s) through "avmaicctl".

11. Reboot the machine.

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