DRAFT 1

Introduction
------------

Bayonne differs signficently from ACS in the way platform specific
telephony API's are integrated.  In ACS, a platform specific server must
be compiled and installed.  In Bayonne, a single (unified) server image
is used, and all telephony API's appear as loadable modules.  Furthermore,
Bayonne differs in that the server can be ran under "user" privilege, at
least for most telephony API's, while ACS actually required root
permission to execute.

These differences are substantial enough that the very concept of
configuration and deployment of Bayonne differs signficently from ACS.
This document is not meant to highlight those differences, but to identify
issues and configuration options relevant to each driver and telephony
vendor that is supported in Bayonne.

Drivers
-------

A "supported" Bayonne telephony device is managed through a plugin
"driver".  This "driver" is defined as a shared object module with an
extension of ".ivr".  Drivers (and other Bayonne "plugin" resources) are
found in /usr/lib/bayonne/version/, such as /usr/lib/bayonne/0.4.4/.

In addition to telephony device "drivers", there are plugins for
"integration" services.  These typically are used for switch integration,
such as the Bayonne "SMDI" module.  Other modules offer extended
call logging capabilities, network integration, VoIP stacks modified to
operate as runtime loadable modules, and script language extensions.  

While all other forms of drivers and plugins are optional, Bayonne
requires at minimum a telephony device and API "driver" (.ivr) to be
selected for Bayonne to execute.  Furthermore, at present only one such
driver can be selected and made active in any running instance of the
Bayonne server.

The primary telephony driver API is selected in the [paths] section of the
/etc/bayonne.conf file.  The name of the driver to load is specified
directly, in the form "driver=drivername", such as "driver=phonedev".  A
matching "phonedev.ivr" plugin is then loaded when the bayonne server is
started.

When Bayonne is "configured" (by running ./configure) it will detect what
telephony API's have been installed on the host system.  If it fails to
find the files associated with a given telephony API, then that API will
be excluded from Bayonne.  If you later add a telephony API, you will need
to remove config.cache and then re-run "./configure" before Bayonne will
recognize and build drivers for it.

The remaining sections of this document will cover the various driver and
plugin modules currently supported by Bayonne, as well as vendor specific
issues.

PHONEDEV.IVR
------------

The phonedev.ivr driver is used to support operating systems such as
GNU/Linux which make use of kernel mode "native" telephony drivers
commonly found under "/dev/phone".  This driver supports interaction with
kernel telephony "phone" devices through the application of a known set of
ioctl calls and the use of "event" notification through the exception bit
of the select() call.

The phonedev module does try to treat phone devices in a fully vendor
neutral manner.  "/dev/phone" device drivers from different vendors can be
loaded and mixed in kernel memory under separate device nodes, and the
phonedev.ivr module will accept such a mixed vendor environment as well as
query /dev/phone devices for specific features and capabilities that will
be supported on each instance in Bayonne.

Furthermore, in that Bayonne executes in "user" mode, the bayonne server
will only open and access "phone" devices that are actually made available
to the current user id that bayonne is running under.  This means that if
one wants to use, for example, three QuickNet "linejack" cards with
Bayonne for servicing incoming calls (say /dev/phone1-4), and yet preserve
a QuickNet "phonejack" card for "private" use (say with gnomephone or
speakfreely), then one can simply set the ownership of the linejack cards
to match the user id Bayonne will run under, and preserve the phonejack
(/dev/phone0) as owned under a different user id (say the userid of the
workstation user who wishes to use speakfreely).

Finally, the phonedev.ivr can be used in multiple instances of the Bayonne
server.  Hence, one can run different "application servers" by starting
multiple instances of Bayonne under different user id's.  Different sets
of "/dev/phone" devices can be marked as owned by each of the expected
server user id's, and each server will then operate only with the
"/dev/phone" devices that user id has been granted access to.

One should never start more than one instance of Bayonne under the same
effective user id.  Also, when using user permissions to partition
"/dev/phone" devices between multiple instances of Bayonne, these device
nodes must never be marked with shared group "write" permission, otherwise
the device may be accessed under multiple images.

When starting the server under the "root" user, one may find additional
problems.  Bayonne will change itself from root to a new effective user
id once started.  Due to a bug in the Quicknet cards, the /dev/phone
device must be closed and re-opened between each telephone call.  Hence
while root, /dev/phone will initially open, but once the server is
running /dev/phone devices may no longer work unless they are given
r/w access permissions under the effective user id the server is now
running under.  By default this will be the effective user id of the
"mail" account, although it can be changed in [server].

The "phonedev.ivr" uses service threads to service event queues for
driving the call processor of each of the open "/dev/phone" devices.
The total number of such devices that will be supported is indicated in
the [phone] section of /etc/bayonne using the "devices =" keyword.  The
default value is currently "16".  The maximum value that may be specified
is "240".  As each device represents an individual telephone line, it is
possible some cards may support multiple "/dev/phone" nodes from a single
card.  This value thus represents the total "port" capacity that will be
tested for rather than the total number of cards that may be supported in
a single chassis.

Normally only one or at most two service threads are needed, and these can
be selected using the [thread] service = keyword option as described in
the bayonne.conf man page.  Generally the service threads should run
either at or a higher priority than Bayonne itself.  The phonedev.ivr can
support a maximum of 240 device nodes (sufficient for 10 T-1 spans or 8
E-1 spans), hence, in a very high capacity "/dev/phone" based SMP server
one might wish to select 4 or even 8 service threads.

At the time of this writing, only the QuickNet cards are known to be using
"/dev/phone" drivers under Linux.  However, the Voicetronix multi-port
analog telephony cards will likely soon also use "/dev/phone" based Linux 
kernel modules.  It has been assumed a maximum of 16 QuickNet cards can be
installed in a single cabinet.  It is possible to also have up to 16
Voicetronix cards in a single cabinet, with each card servicing 4 analog
telephone lines, for a total capacity of 64 ports.

VPB.IVR
-------

The vpb.ivr driver supports Voicetronix's 4 port analog DSP card.  These
cards use a "user mode" library, libvpb2, which must be installed before
Bayonne is configured.  This driver will work for both GNU/Linux and
FreeBSD systems.  It will work for any target platform that the libvpb2
library supports in the future.

The vpb.ivr module requires that Bayonne is started under "root".  This is
nessisary for Bayonne to access io ports under both the Linux kernel and
FreeBSD.  Once started, Bayonne will reduce itself to the effective user
privilege specified in the [server] section of bayonne.conf.

The [vpb] section of Bayonne must be configured properly before you
attempt to start it.  This includes the base address of the "first" card
(in 0x3x0 range) and the total number of cards in the system.  Bayonne
assumes all Voicetronix cards will be in sequenctial addresses, and hence,
if you define the first card as 0x340, and specify two cards, the second
card must be set for 0x350.  Multiple instances of Bayonne can be started
so long as each instance uses a different set of cards.

A seperate service thread is started in Bayonne for each Voicetronix
card.  This service thread performs all event dispatch and may be tuned
for process priority scheduling and by scheduling policy for optimal
performance.

It is possible to have up to 16 Voicetronix cards in a single PC, for a
total capacity of 64 analog telephony ports.

PIKA.IVR
--------

The pika.ivr driver is used inconjunction with the Pika MonteCarlo SDK to
support Pika analog telephone cards under GNU/Linux.  This SDK has been
made available for RedHat 6.x based systems as a RPM package which must be
installed before Bayonne is "configured".

The pika.ivr module can be ran from "user mode" and does not require the
user to be "root".  This is accomplished by making /usr/pika readable to a
given user, and by setting permissions on /dev/pikadsp and /dev/pikacti
device nodes to permit user level access.

The ivr module supports all Pika trunk cards currently supported under
GNU/Linux with the MonteCarlo SDK.  These include the 4 port
"InLine" series of hardware, as well as the 12 and 24 port analog DSP
Daytona cards, as well as the non-DSP versions of these cards.  No station
side cards are currently supported, however.  

In addition to "DSP" cards, the pika.ivr implimentation on Bayonne
supports fully "dynamic" resource assignment and can work with non-DSP
cards that are mixed with DSP cards, or with systems designed with
blocking factors due to less DSP resources of a given type being available
than physical ports.  The pika.ivr takes full advantage of MonteCarlo MVIP
bus support to locate and connect DSP resources to ports on a as needed
demand basis anywhere on a given host.

Only one instance of Bayonne may be executed with the Pika DSP module
running.  The API uses a single global configuration and cannot dole out
partial access to Pika cards to different processes.  If more than one
instance is started, it may lock up the whole system.


DIALOGIC.IVR
------------

The Dialogic IVR module is not yet complete, however, enough is known to
say more about it here.

First, before you can use Dialogic support, you must install the Dialogic
UNIX SDK for your platform.  Bayonne is designed "generically" for the
standard UNIX SDK, and will work with it under both Solaris and UnixWare,
as well as under GNU/Linux.

When using GNU/Linux, you must also install the LiS streams package.  This
is required by the Dialogic Unix SDK since it really is a clone/port of
the standard Unix system release and is streams based.

The dialogic.ivr module has been developed to autodetect Dialogic
resources at startup.  It should detect both analog and digital telephony
devices, and will support both with the same ivr driver module, even if
both types of devices are mixed on the same system.

The ability to run Bayonne as an "ordinary" user depends on what
permissions and ownership are assigned to the various Dialogic /dev/xxxx
device nodes.  I believe it will be possible to use ordinary user
privilege but this has not been proven yet.

The dialogic.ivr analyses and assigns ALL dialogic devices that it finds
at startup.  Hence, only one instance of Bayonne may be executed on any
given server.

The current implimentation does "static" assignment of DSP resources at
startup, and requires that sufficient vox ports exist for all digital
telephony interfaces found in the system.  This means one cannot use plain
DTI cards unless one has sufficient sc bus voice resource cards also
available.  This may change in future releases.

ACULAB.IVR
----------

The aculab driver is also in early development.  It is based on the Aculab
PRI and BRI span cards with Prosody support.  You must install the Aculab
call, voice, and switch modules and libraries before building Bayonne
Aculab support.

At the moment I assume that root permission is required to access the
Aculab, though this may be incorrect.

The aculab module does automatic card timeslot assignment and will detect
and allocate aculab timeslot and card resources during startup.  In that
all devices are allocated at startup, only one instance of Bayonne can be
executed on a single server.

A single service thread is maintained for event dispatch, and a service
thread is available for each telephone port.  This may change later on.

There is an active workgroup working on aculab support, and the mailing
list for this can be found at bayonne-aculab@lists.sourceforge.net.
