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,