linux-imx

Kernel CAPI Interface to Hardware Drivers

-----------------------------------------

​

1. Overview

​

From the CAPI 2.0 specification:

COMMON-ISDN-API (CAPI) is an application programming interface standard used

to access ISDN equipment connected to basic rate interfaces (BRI) and primary

rate interfaces (PRI).

​

Kernel CAPI operates as a dispatching layer between CAPI applications and CAPI

hardware drivers. Hardware drivers register ISDN devices (controllers, in CAPI

lingo) with Kernel CAPI to indicate their readiness to provide their service

to CAPI applications. CAPI applications also register with Kernel CAPI,

requesting association with a CAPI device. Kernel CAPI then dispatches the

application registration to an available device, forwarding it to the

corresponding hardware driver. Kernel CAPI then forwards CAPI messages in both

directions between the application and the hardware driver.

​

Format and semantics of CAPI messages are specified in the CAPI 2.0 standard.

This standard is freely available from https://www.capi.org.

​

​

2. Driver and Device Registration

​

CAPI drivers optionally register themselves with Kernel CAPI by calling the

Kernel CAPI function register_capi_driver() with a pointer to a struct

capi_driver. This structure must be filled with the name and revision of the

driver, and optionally a pointer to a callback function, add_card(). The

registration can be revoked by calling the function unregister_capi_driver()

with a pointer to the same struct capi_driver.

​

CAPI drivers must register each of the ISDN devices they control with Kernel

CAPI by calling the Kernel CAPI function attach_capi_ctr() with a pointer to a

struct capi_ctr before they can be used. This structure must be filled with

the names of the driver and controller, and a number of callback function

pointers which are subsequently used by Kernel CAPI for communicating with the

driver. The registration can be revoked by calling the function

detach_capi_ctr() with a pointer to the same struct capi_ctr.

​

Before the device can be actually used, the driver must fill in the device

information fields 'manu', 'version', 'profile' and 'serial' in the capi_ctr

structure of the device, and signal its readiness by calling capi_ctr_ready().

From then on, Kernel CAPI may call the registered callback functions for the

device.

​

If the device becomes unusable for any reason (shutdown, disconnect ...), the

driver has to call capi_ctr_down(). This will prevent further calls to the

callback functions by Kernel CAPI.

​

​

3. Application Registration and Communication

​

Kernel CAPI forwards registration requests from applications (calls to CAPI

operation CAPI_REGISTER) to an appropriate hardware driver by calling its

register_appl() callback function. A unique Application ID (ApplID, u16) is

allocated by Kernel CAPI and passed to register_appl() along with the

parameter structure provided by the application. This is analogous to the

open() operation on regular files or character devices.

​

After a successful return from register_appl(), CAPI messages from the

application may be passed to the driver for the device via calls to the

send_message() callback function. Conversely, the driver may call Kernel

CAPI's capi_ctr_handle_message() function to pass a received CAPI message to

Kernel CAPI for forwarding to an application, specifying its ApplID.

​

Deregistration requests (CAPI operation CAPI_RELEASE) from applications are

forwarded as calls to the release_appl() callback function, passing the same

ApplID as with register_appl(). After return from release_appl(), no CAPI

messages for that application may be passed to or from the device anymore.

​

​

4. Data Structures

​

4.1 struct capi_driver

​

This structure describes a Kernel CAPI driver itself. It is used in the

register_capi_driver() and unregister_capi_driver() functions, and contains

the following non-private fields, all to be set by the driver before calling

register_capi_driver():

​

char name[32]

    the name of the driver, as a zero-terminated ASCII string

char revision[32]

    the revision number of the driver, as a zero-terminated ASCII string

int (*add_card)(struct capi_driver *driver, capicardparams *data)

    a callback function pointer (may be NULL)

​

​

4.2 struct capi_ctr

​

This structure describes an ISDN device (controller) handled by a Kernel CAPI