282 lines
11 KiB
Cheetah
282 lines
11 KiB
Cheetah
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[]>
|
|
|
|
<book id="NGC">
|
|
<bookinfo>
|
|
<title>Next Generation CAPI</title>
|
|
|
|
<copyright>
|
|
<year>2004</year>
|
|
<holder>Frank A. Uepping</holder>
|
|
</copyright>
|
|
|
|
<revhistory>
|
|
<revision>
|
|
<revnumber></revnumber>
|
|
<date>2005-01-27</date>
|
|
<revremark>Working Draft</revremark>
|
|
</revision>
|
|
</revhistory>
|
|
|
|
<legalnotice>
|
|
<para>
|
|
This documentation is free software; you can redistribute it and/or
|
|
modify it under the terms of the GNU General Public License as
|
|
published by the Free Software Foundation; either version 2 of the
|
|
License, or (at your option) any later version.
|
|
</para>
|
|
|
|
<para>
|
|
This program is distributed in the hope that it will be useful, but
|
|
WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
General Public License for more details.
|
|
</para>
|
|
|
|
<para>
|
|
You should have received a copy of the GNU General Public License along
|
|
with this program; if not, write to the Free Software Foundation, Inc.,
|
|
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
|
|
</para>
|
|
|
|
<para>
|
|
For more details see the file COPYING in the source distribution of
|
|
Linux.
|
|
</para>
|
|
</legalnotice>
|
|
</bookinfo>
|
|
|
|
<toc></toc>
|
|
|
|
<chapter id="intro">
|
|
<title>Introduction</title>
|
|
|
|
<para>
|
|
<acronym>CAPI</> (COMMON-ISDN-API) is a message oriented and event driven
|
|
programming interface, used by applications to access <acronym>ISDN</>
|
|
hardware equipment in a standardized and straightforward way. Publisher
|
|
of the <acronym>CAPI</> standard is the <ulink
|
|
url="http://www.capi.org">CAPI-Association</ulink>, a non-profit
|
|
international consortium of hardware and software manufactures and
|
|
telecommunications institutions; the <acronym>CAPI</> standard is freely
|
|
available for download on their website.
|
|
</para>
|
|
|
|
<para>
|
|
The <acronym>CAPI</> standard defines a set of messages, protocols, and
|
|
operations. While the messages and protocols are interoperable, the
|
|
interface to the operations is specific to each supported
|
|
operating system. For Linux, the standard defines <acronym>CAPI</>
|
|
interfaces for user and kernel space.
|
|
</para>
|
|
|
|
<para>
|
|
<ulink url="http://www.capi4linux.org/ngc"><emphasis>Next Generation
|
|
CAPI</emphasis></ulink> (<acronym>NGC</>) is an
|
|
<emphasis>experimental</emphasis> implementation of the <acronym>CAPI</>
|
|
2.0 standard and derived from <ulink
|
|
url="http://www.capi4linux.org">CAPI4Linux</ulink>.
|
|
</para>
|
|
|
|
<para>
|
|
The heart of the <acronym>NGC</> subsystem is the capicore and, as such,
|
|
it is crucial to the performance and the stability of the whole
|
|
subsystem. Basically, the capicore provides an infrastructure for the
|
|
communication between applications and device drivers. Applications are
|
|
interfaced with the capicore via <acronym>CAPI</>, and device drivers via
|
|
a custom made interface proprietary to Linux. This white paper is
|
|
concerned with these interfaces, and describes them from the viewpoint of
|
|
a device driver and an application developer, respectively. Further, it
|
|
is assumed that the reader is familiar with the basic concepts and terms
|
|
of the <acronym>CAPI</> standard and with Linux kernel programming in
|
|
general.
|
|
</para>
|
|
</chapter>
|
|
|
|
<chapter>
|
|
<title>Structures and Data Types</title>
|
|
|
|
<para>
|
|
The capicore provides a common set of structures and data types forming
|
|
the basis of communication between the various layers of the
|
|
<acronym>NGC</> subsystem.
|
|
</para>
|
|
|
|
!Iinclude/linux/isdn/capinfo.h
|
|
!Finclude/linux/capi.h capi_register_params capi_version capi_profile
|
|
!Finclude/linux/isdn/capiappl.h capi_stats capi_appl
|
|
!Finclude/linux/isdn/capidevice.h capi_driver capi_device
|
|
</chapter>
|
|
|
|
<chapter>
|
|
<title>Device Driver Interface</title>
|
|
|
|
<para>
|
|
Device drivers and applications communicate together, via the capicore,
|
|
in an asynchronous way by exchanging messages according to the
|
|
<acronym>CAPI</> standard. While the implementation of a device driver
|
|
might be rather complex internally, the interface with the capicore is
|
|
pretty simple. The declarations to this interface can be found in
|
|
<filename class="headerfile">linux/isdn/capidevice.h</filename>.
|
|
</para>
|
|
|
|
<sect1>
|
|
<title>Overview</title>
|
|
|
|
<para>
|
|
Devices are represented to the capicore by objects of the generic
|
|
<structname>capi_device</structname> structure. This structure forms
|
|
the basis of communication between the capicore and device drivers.
|
|
Devices are reference counted objects and need to be dynamically
|
|
allocated by the device driver via the function
|
|
<function>capi_device_alloc</function>. Destroying a device is
|
|
done by releasing all references to it via the function
|
|
<function>capi_device_put</function>.
|
|
</para>
|
|
|
|
<para>
|
|
Once a generic <structname>capi_device</structname> object is
|
|
initialized, the device driver can register it with the capicore via
|
|
the function <function>capi_device_register</function>. Removing the
|
|
device from the capicore is done via the function
|
|
<function>capi_device_unregister</function>; subsequently, the
|
|
device driver can release the device via the function
|
|
<function>capi_device_put</function>.
|
|
</para>
|
|
|
|
<para>
|
|
The device driver has to provide three functions for calling by the
|
|
capicore via the <structname>capi_driver</structname> structure,
|
|
enabling the registration and removal of applications with the device
|
|
driver's devices and the transfer of messages to them.
|
|
</para>
|
|
|
|
<para>
|
|
Each application owns a message queue by which devices are transferring
|
|
messages to the application. Adding messages to the application queue
|
|
is done via the function
|
|
<function>capi_appl_enqueue_message</function>. Upon that, the device
|
|
driver should <emphasis>wakeup</emphasis> the application via the
|
|
function <function>capi_appl_signal</function>. If the device driver
|
|
encounters an error related to a message (i.e., in the context of an
|
|
application), it should inform the concerned application about that
|
|
condition via the function <function>capi_appl_signal_error</function>,
|
|
causing the application to release.
|
|
</para>
|
|
|
|
<para>
|
|
Besides that, since <acronym>CAPI</> devices are <emphasis>class
|
|
devices</emphasis>, they can easily export own attributes to the sysfs,
|
|
enabling the device driver to offer device specific features to the
|
|
user. See <filename class="headerfile">linux/device.h</filename> for
|
|
more information.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1>
|
|
<title>Operations</title>
|
|
|
|
!Fdrivers/isdn/capi/core.c capi_device_alloc capi_device_register capi_device_unregister
|
|
!Finclude/linux/isdn/capidevice.h capi_device_get capi_device_put capi_device_set_devdata capi_device_get_devdata capi_device_set_dev capi_device_get_dev to_capi_device capi_appl_enqueue_message capi_appl_signal capi_appl_signal_error
|
|
</sect1>
|
|
</chapter>
|
|
|
|
<chapter>
|
|
<title>Application Interface</title>
|
|
|
|
<para>
|
|
Applications and device drivers communicate together, via the capicore,
|
|
in an asynchronous way by exchanging messages according to the
|
|
<acronym>CAPI</> standard. While the implementation of an application
|
|
might be rather complex internally, the interface with the capicore is
|
|
pretty simple.
|
|
</para>
|
|
|
|
<para>
|
|
For Linux, the <acronym>CAPI</> standard defines <acronym>CAPI</>
|
|
interfaces for user and kernel space applications. Unfortunately, the
|
|
specification to the kernel space <acronym>CAPI</> is too unspecific. To
|
|
give developers the required backing in writing safe kernel space
|
|
applications, the capicore introduces an alternative interface which
|
|
we're going to describe here in detail. The declarations to this
|
|
interface can be found in <filename
|
|
class="headerfile">linux/isdn/capiappl.h</filename>.
|
|
</para>
|
|
|
|
<sect1>
|
|
<title>Overview</title>
|
|
|
|
<para>
|
|
Applications are represented to the capicore by objects of the generic
|
|
<structname>capi_appl</structname> structure. This structure forms the
|
|
basis of communication between the capicore and applications.
|
|
</para>
|
|
|
|
<para>
|
|
Once a generic <structname>capi_appl</structname> object is
|
|
initialized, the application can register it with the capicore via the
|
|
function <function>capi_register</function>. Removing an application
|
|
from the capicore is done via the function
|
|
<function>capi_release</function>.
|
|
</para>
|
|
|
|
<para>
|
|
Applications need to install a signal handler via the function
|
|
<function>capi_set_signal</function>. The signal handler serves as a
|
|
notification mechanism for asynchronous events, such as:
|
|
|
|
<itemizedlist mark=opencircle>
|
|
<listitem>
|
|
<para>the arrival of new messages</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>the clearance of queue-full/busy conditions</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>errors</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
Note that a signal handler is not meant to be a
|
|
<emphasis>workhorse</emphasis>, but just a mechanism for waking up and
|
|
scheduling applications.
|
|
</para>
|
|
|
|
<para>
|
|
Applications transfer messages via the function
|
|
<function>capi_put_message</function>, and fetch them via the function
|
|
<function>capi_get_message</function>. They can put back messages via
|
|
the function <function>capi_unget_message</function>, and check for
|
|
pending messages via the function
|
|
<function>capi_peek_message</function>.
|
|
</para>
|
|
|
|
<para>
|
|
Applications can retrieve informations from <acronym>CAPI</> devices
|
|
via the functions: <function>capi_get_manufacturer</function>,
|
|
<function>capi_get_serial_number</function>,
|
|
<function>capi_get_version</function>,
|
|
<function>capi_get_profile</function>, and
|
|
<function>capi_get_product</function>.
|
|
</para>
|
|
|
|
<para>
|
|
Since <acronym>CAPI</> devices are <emphasis>class devices</emphasis>,
|
|
applications can install a <emphasis>class interface</emphasis> with
|
|
the Linux device driver core to get informed when <acronym>CAPI</>
|
|
devices are being registered and removed with the capicore. See
|
|
<filename class="headerfile">linux/device.h</filename> for more
|
|
information.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1>
|
|
<title>Operations</title>
|
|
|
|
!Finclude/linux/isdn/capiappl.h capi_set_signal
|
|
!Fdrivers/isdn/capi/core.c capi_register capi_release capi_put_message
|
|
!Finclude/linux/isdn/capiappl.h capi_get_message capi_unget_message capi_peek_message
|
|
!Fdrivers/isdn/capi/core.c capi_isinstalled capi_get_manufacturer capi_get_serial_number capi_get_version capi_get_profile capi_get_product
|
|
</sect1>
|
|
</chapter>
|
|
</book>
|