CAPI-TRC(7)

NAME
capi-trc - using the CAPI tracing feature of c4b

SYNOPSIS
#include <capi20.h>
#include <capi_bsd.h>
#include <capi_bsdtrc.h>

DESCRIPTION
The ability of creating a trace of all CAPI function calls and messages an application exchanges with a CAPI implementation is a vital thing for CAPI application developement. For controller device driver developement it is at least just as important.

In c4b the tracing feature is built into the kernel CAPI manager kcapimgr. A CAPI application process with sufficient rights may start tracing function calls and exchanged messages between the CAPI manager and its applications. There several options to control the information to be traced.

In the usual case CAPI traces will be created with the tool called capitrace. This program can create all possible traces and supports all available options to control the amount of tracing data. It is even able to decode trace data into human readable format. So there is normally no need for an application developer to create his own tracing applications.

  Controlling the amount of trace information
CAPI traces are normally created with a particular purpose. One wants to see some very special information and all other data would be discarded.

In c4b it is possible to control the amount of tracing data created in several ways. First one can independently choose to include or not function calls and messages in the tracing data stream. If CAPI messages in general shall be traced, another choice is to include or not Data-B3 messages. And finally if Data-B3 messages are included, the attached data blocks may also be traced. It is possible to trace the complete data blocks or to only trace the first few bytes.

  Reference points for intercepting CAPI function calls and messages
c4b is made of several kernel modules and some parts in user space. So the controller and its driver is a good way apart from a CAPI application. On the way from an application to the controller and vice versa there are several points where it makes sense to intercept CAPI function calls and messages. The first one would be the shared library in user space that is directly linked to an application. The next point is the CAPI character special device driver, then comes the CAPI manager and finally the controller driver. Currently there are two reference points for which CAPI tracing can be enabled. These are the kernel application interface and the controller driver interface of the CAPI manager. This way messages and function calls can be observed when entering or leaving the CAPI manager ‘on both ends’. As the CAPI device simply takes its data from the character device, forwards it to the CAPI manager directly and vice versa, there is no need to implement an additional tracing point there. What is currently missing in c4b is the possibility to trace CAPI calls to the shared library in user space.

The CAPI manager performs some message conversion if a controller needs application id or controller number mapping. And some messages or function calls are suppressed or delayed if the CAPI state machines or an implementation detail requires it. So it makes sense to create traces near the application side and additionally at the controller side of the CAPI manager.

  Taking access rights into account
A normal user shall not be able to create traces for applications running with root privileges. E.g. if network connections are directed through the CAPI manager passwords may be transfered in CAPI messages. Because of this c4b implements some security within the tracing facility. Normal users can only create CAPI traces for application processes running under their own account or under a group they are a member of. Those processes do not receive any trace information about CAPI applications running under other accounts.

Controller traces are even reserved for root processes. A normal user cannot trace calls between the CAPI manager and a controller driver. Processes with a user or group id of 0 (root or wheel respectively) are allowed to trace everything. They receive trace information about all CAPI applications currently running.

  Creating CAPI traces in general
A CAPI tracing application must first register itself as usual by calling kcapi_register() or capi20_register(), depending on whether the application is running in kernel or user space. A pure tracing application will not establish any ISDN connection so this value may be set to zero on registration. This saves some memory in user and kernel space. But a single CAPI application may concurrently handle ISDN connections and create a CAPI trace.

After registration the application has to start a ‘tracer’. A tracer is a virtual object with some properties. The most important property is the reference point from where it receives tracing information. An application can create an ‘application tracer’ or a ‘controller tracer’ (assuming sufficient rights to do so). A controller tracer is always created with the controller number to trace events for. The other properties define if function calls, general CAPI messages, Data-B3 messages and data blocks are to be included in the trace. All this information is specified when creating a tracer. As a result the application receives a tracer id to identify the tracer object.

After a tracer is started the application will receive trace messages. They may be e.g. stored into a file for later evaluation. Every trace message contains among other data the tracer id it is created from. So the application can create multiple tracers and save tracing information for each of them into separate files.

Trace messages are delivered to the application until the tracer is stopped by the application.

  The method for exchanging trace messages
All trace messages are delivered to the application through the normal CAPI facilities. Thus an application can wait for trace messages by calling capi20_wait_for_message() if it is a user space application. A trace message is fetched by calling capi20_get_message().

To distinguish a trace message from normal CAPI messages, they are sent or received with the CAPI command C_MANUFACTURER. This applies to all messages according the tracing feature.

A tracer is started by sending a Manufacturer-Request with specific data to the CAPI manager. It responses with a matching Manufacturer-Confirmation. Trace messages are signalled as Manufacturer-Indications and must be acknowledged with Manufacturer-Responses. A tracer is stopped by sending another Manufacturer-Request. The corresponding confirmation reports success or failure for the stop operation.

All Manufacturer messages according the tracing feature are flagged with a specific manufacturer id. The identifier C4B_TRACE_MANU_ID is defined for this 32bit integer value.

All identifiers and the content for trace messages are defined in the header file capi_bsdtrc.h. It would only blow up this manual page if every data structure was described in detail here. Just take a look into the (commented) header file for reference.

SEE ALSO
capi20(3), c4b(4), capidev(4), kcapimgr(4), capitrace(8), kcapi(9), kcapi-drv(9). CAPI Association e.V., Common ISDN API v2.0 4th Edition, June 2001, see http://www.capi.org.

STANDARDS
There is currently no standard for CAPI tracing. Maybe this implementation could be incorporated into the CAPI specification for the BSD operating systems if such an official specification will ever be released.

HISTORY
This manual page and c4b first appeared as an add-on to FreeBSD 4.6.

AUTHORS
This manual page was written by Thomas Wintergerst <twinterg@gmx.de>.

BUGS
There should be a way to trace at the reference point in the shared library for user space application support.