Kernel CAPI Interface to Hardware Drivers

개요와 driver·application 등록

CAPI 2.0 specification에서 COMMON-ISDN-API(CAPI)는 BRI(Basic Rate Interface)와 PRI(Primary Rate Interface)에 연결된 ISDN 장비에 접근하는 application programming interface 표준입니다.

Kernel CAPI는 CAPI application과 CAPI hardware driver 사이의 dispatch layer로 동작합니다. Hardware driver는 서비스를 제공할 준비가 되었음을 알리기 위해 제어하는 ISDN 장치, 즉 CAPI 용어의 controller를 Kernel CAPI에 등록합니다. Application도 Kernel CAPI에 등록하면서 CAPI 장치와의 연결을 요청합니다. Kernel CAPI는 사용 가능한 장치에 application 등록을 배정해 해당 hardware driver로 넘기고, 이후 양방향 CAPI message를 중계합니다.

CAPI message 형식과 의미는 CAPI 2.0 standard가 정의하며 표준은 `https://www.capi.org`에서 무료로 제공됩니다.

CAPI driver는 사용할 각 ISDN 장치마다 `struct capi_ctr` pointer를 `attach_capi_ctr()`에 넘겨 등록해야 합니다. 이 구조체에는 driver와 controller 이름 및 Kernel CAPI가 driver와 통신할 때 사용할 callback function pointer를 미리 채웁니다. 같은 구조체 pointer로 `detach_capi_ctr()`를 호출하면 등록을 철회합니다.

장치를 실제로 쓰기 전에는 `capi_ctr`의 `manu`, `version`, `profile`, `serial` 정보를 채우고 `capi_ctr_ready()`를 호출해 준비 완료를 알려야 합니다. 이 시점부터 Kernel CAPI가 등록된 callback을 호출할 수 있습니다. shutdown이나 disconnect 등으로 장치를 쓸 수 없게 되면 `capi_ctr_down()`을 호출해야 하며, 이후 Kernel CAPI는 callback을 더 호출하지 않습니다.

Application의 `CAPI_REGISTER` 요청은 적절한 hardware driver의 `register_appl()` callback으로 전달됩니다. Kernel CAPI가 고유한 `u16` Application ID, 즉 ApplID를 할당하고 application이 제공한 parameter 구조체와 함께 넘깁니다. 이는 일반 file이나 character device의 `open()`과 비슷합니다.

`register_appl()`이 성공하면 application message는 `send_message()` callback으로 driver에 전달될 수 있습니다. 반대 방향에서는 driver가 ApplID와 함께 `capi_ctr_handle_message()`를 호출하여 받은 CAPI message를 Kernel CAPI에 넘기고, Kernel CAPI가 해당 application으로 전달합니다.

Application의 `CAPI_RELEASE` 요청은 등록 때와 같은 ApplID를 가진 `release_appl()` callback으로 전달됩니다. `release_appl()`이 반환된 뒤에는 그 application의 CAPI message가 장치와 어느 방향으로도 오가면 안 됩니다.

=========================================
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 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.

`capi_driver`와 `capi_ctr` 자료 구조

`struct capi_driver`는 Kernel CAPI driver 자체를 설명합니다. `register_capi_driver()`와 `unregister_capi_driver()`에서 사용하며, 등록 전에 driver가 비공개가 아닌 field를 모두 설정합니다. `char name[32]`는 NUL로 끝나는 ASCII driver 이름이고 `char revision[32]`는 NUL로 끝나는 ASCII revision 번호입니다.

`struct capi_ctr`는 Kernel CAPI driver가 다루는 ISDN controller를 설명합니다. `attach_capi_ctr()`로 등록된 뒤 controller별 lower-layer interface와 callback에 전달되어 작업 대상을 식별합니다.

선택적 `load_firmware(ctrlr, ldata)` callback은 firmware와 configuration data를 장치에 보냅니다. 작업 완료 전에 반환할 수 있지만 완료 시 `capi_ctr_ready()`를 호출해야 합니다. 성공 시 0, 실패 시 error code를 반환하며 process context에서 호출됩니다.

선택적 `reset_ctr(ctrlr)` callback은 장치를 정지하고 등록된 모든 application을 해제합니다. 이 함수도 작업 완료 전에 반환할 수 있으며 완료는 `capi_ctr_down()` 호출로 알려야 합니다. process context에서 호출됩니다.

`register_appl(ctrlr, applid, rparam)`은 application을 장치에 등록하고 `release_appl(ctrlr, applid)`은 등록을 해제합니다. Kernel CAPI는 두 callback 호출을 직렬화하므로 이들 중 어느 하나만 한 시점에 실행됩니다.

`send_message(ctrlr, skb)`는 CAPI message를 장치로 보내고 CAPI error code를 반환합니다. 0인 `CAPI_NOERROR`를 반환하면 driver가 skb 소유권을 인수하므로 caller는 더 접근할 수 없습니다. 0이 아닌 error를 반환하면 소유권이 caller에게 돌아가며 caller가 skb를 재사용하거나 해제할 수 있습니다.

`send_message()` 반환값은 message 수락이나 queue 문제만 나타내야 합니다. 실제 message 처리 중 생긴 error는 적절한 reply message로 알려야 합니다. 이 callback은 process context 또는 interrupt context에서 호출될 수 있고 Kernel CAPI가 호출을 직렬화하지 않으므로 재진입에 대비해야 합니다.

`procinfo(ctrlr)` callback은 `/proc/capi/controller`의 CAPI controller 정보 table에 넣을 장치 entry를 반환합니다. `send_message()`를 제외한 callback은 interrupt context에서 호출되지 않습니다.

`capi_ctr_ready()` 호출 전에는 조회 응답용 field를 채웁니다. `manu[CAPI_MANUFACTURER_LEN]`은 `CAPI_GET_MANUFACTURER`, `capi_version version`은 `CAPI_GET_VERSION`, `capi_profile profile`은 `CAPI_GET_PROFILE`, `serial[CAPI_SERIAL_LEN]`은 `CAPI_GET_SERIAL`의 반환값입니다.

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

4.2 struct capi_ctr
-------------------

This structure describes an ISDN device (controller) handled by a Kernel CAPI
driver. After registration via the attach_capi_ctr() function it is passed to
all controller specific lower layer interface and callback functions to
identify the controller to operate on.

It contains the following non-private fields:

to be set by the driver before calling attach_capi_ctr():
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``struct module *owner``
        pointer to the driver module owning the device

``void *driverdata``
        an opaque pointer to driver specific data, not touched by Kernel CAPI

``char name[32]``
        the name of the controller, as a zero-terminated ASCII string

``char *driver_name``
        the name of the driver, as a zero-terminated ASCII string

``int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata)``
        (optional) pointer to a callback function for sending firmware and
        configuration data to the device

        The function may return before the operation has completed.

        Completion must be signalled by a call to capi_ctr_ready().

        Return value: 0 on success, error code on error
        Called in process context.

``void (*reset_ctr)(struct capi_ctr *ctrlr)``
        (optional) pointer to a callback function for stopping the device,
        releasing all registered applications

        The function may return before the operation has completed.

        Completion must be signalled by a call to capi_ctr_down().

        Called in process context.

``void (*register_appl)(struct capi_ctr *ctrlr, u16 applid, capi_register_params *rparam)``
        pointers to callback function for registration of
        applications with the device

        Calls to these functions are serialized by Kernel CAPI so that only
        one call to any of them is active at any time.

``void (*release_appl)(struct capi_ctr *ctrlr, u16 applid)``
        pointers to callback functions deregistration of
        applications with the device

        Calls to these functions are serialized by Kernel CAPI so that only
        one call to any of them is active at any time.

``u16  (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb)``
        pointer to a callback function for sending a CAPI message to the
        device

        Return value: CAPI error code

        If the method returns 0 (CAPI_NOERROR) the driver has taken ownership
        of the skb and the caller may no longer access it. If it returns a
        non-zero (error) value then ownership of the skb returns to the caller
        who may reuse or free it.

        The return value should only be used to signal problems with respect
        to accepting or queueing the message. Errors occurring during the
        actual processing of the message should be signaled with an
        appropriate reply message.

        May be called in process or interrupt context.

        Calls to this function are not serialized by Kernel CAPI, ie. it must
        be prepared to be re-entered.

``char *(*procinfo)(struct capi_ctr *ctrlr)``
        pointer to a callback function returning the entry for the device in
        the CAPI controller info table, /proc/capi/controller

Note:
  Callback functions except send_message() are never called in interrupt
  context.

to be filled in before calling capi_ctr_ready():
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``u8 manu[CAPI_MANUFACTURER_LEN]``
        value to return for CAPI_GET_MANUFACTURER

``capi_version version``
        value to return for CAPI_GET_VERSION

``capi_profile profile``
        value to return for CAPI_GET_PROFILE

``u8 serial[CAPI_SERIAL_LEN]``
        value to return for CAPI_GET_SERIAL

SKB message와 `_cmsg` 표현

Kernel CAPI와 driver 사이의 CAPI message는 `send_message()`와 `capi_ctr_handle_message()`를 통해 socket buffer, 즉 skb의 data 영역에 저장되어 전달됩니다. 각 skb에는 CAPI 2.0 standard에 따라 인코딩된 CAPI message 하나만 들어 있습니다.

Data transfer message인 `DATA_B3_REQ`와 `DATA_B3_IND`에서는 실제 payload가 같은 skb 안에서 CAPI message 바로 뒤에 옵니다. `Data`와 `Data64` parameter는 처리에 사용하지 않습니다. CAPI message length field를 30 대신 22로 설정하면 `Data64` parameter를 생략할 수 있습니다.

`<linux/isdn/capiutil.h>`의 `_cmsg` 구조체는 CAPI 2.0 message 내용을 접근하기 쉬운 형태로 저장합니다. Additional Info와 B Protocol의 하위 parameter까지 가능한 모든 CAPI 2.0 parameter member를 포함하지만 네 가지 예외가 있습니다.

현재 처리 중인 message type에 실제로 나타나는 parameter만 사용하며 쓰지 않는 member는 0으로 설정해야 합니다. Member 이름은 CAPI 2.0 standard의 parameter 이름을 따르고 정확한 철자는 `<linux/isdn/capiutil.h>`에서 확인합니다.

`_cstruct`의 하위 parameter는 content 부분 안에 인코딩된 형태로 저장됩니다. `_cmstruct`는 한 byte이며 `CAPI_DEFAULT`이면 parameter가 비어 있거나 없고, `CAPI_COMPOSE`이면 parameter가 존재합니다. 이 경우 하위 parameter 값은 대응하는 `_cmsg` member에 각각 저장됩니다.

4.3 SKBs
--------

CAPI messages are passed between Kernel CAPI and the driver via send_message()
and capi_ctr_handle_message(), stored in the data portion of a socket buffer
(skb).  Each skb contains a single CAPI message coded according to the CAPI 2.0
standard.

For the data transfer messages, DATA_B3_REQ and DATA_B3_IND, the actual
payload data immediately follows the CAPI message itself within the same skb.
The Data and Data64 parameters are not used for processing. The Data64
parameter may be omitted by setting the length field of the CAPI message to 22
instead of 30.


4.4 The _cmsg Structure
-----------------------

(declared in <linux/isdn/capiutil.h>)

The _cmsg structure stores the contents of a CAPI 2.0 message in an easily
accessible form. It contains members for all possible CAPI 2.0 parameters,
including subparameters of the Additional Info and B Protocol structured
parameters, with the following exceptions:

* second Calling party number (CONNECT_IND)

* Data64 (DATA_B3_REQ and DATA_B3_IND)

* Sending complete (subparameter of Additional Info, CONNECT_REQ and INFO_REQ)

* Global Configuration (subparameter of B Protocol, CONNECT_REQ, CONNECT_RESP
  and SELECT_B_PROTOCOL_REQ)

Only those parameters appearing in the message type currently being processed
are actually used. Unused members should be set to zero.

Members are named after the CAPI 2.0 standard names of the parameters they
represent. See <linux/isdn/capiutil.h> for the exact spelling. Member data
types are:

=========== =================================================================
u8          for CAPI parameters of type 'byte'

u16         for CAPI parameters of type 'word'

u32         for CAPI parameters of type 'dword'

_cstruct    for CAPI parameters of type 'struct'
            The member is a pointer to a buffer containing the parameter in
            CAPI encoding (length + content). It may also be NULL, which will
            be taken to represent an empty (zero length) parameter.
            Subparameters are stored in encoded form within the content part.

_cmstruct   alternative representation for CAPI parameters of type 'struct'
            (used only for the 'Additional Info' and 'B Protocol' parameters)
            The representation is a single byte containing one of the values:
            CAPI_DEFAULT: The parameter is empty/absent.
            CAPI_COMPOSE: The parameter is present.
            Subparameter values are stored individually in the corresponding
            _cmsg structure members.
=========== =================================================================

Lower-layer interface 함수

Lower-layer interface는 controller 등록 상태와 driver에서 받은 message를 Kernel CAPI에 전달하는 세 쌍의 operation으로 구성됩니다.

5. Lower Layer Interface Functions
==================================

::

  int attach_capi_ctr(struct capi_ctr *ctrlr)
  int detach_capi_ctr(struct capi_ctr *ctrlr)

register/unregister a device (controller) with Kernel CAPI

::

  void capi_ctr_ready(struct capi_ctr *ctrlr)
  void capi_ctr_down(struct capi_ctr *ctrlr)

signal controller ready/not ready

::

  void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid,
                               struct sk_buff *skb)

pass a received CAPI message to Kernel CAPI
for forwarding to the specified application

CAPI header macro와 helper 함수

`<linux/isdn/capiutil.h>`는 CAPI message header element를 읽거나 설정하는 macro를 제공합니다.

`capi_cmd2str(u8 Command, u8 Subcommand)`은 command와 subcommand에 해당하는 CAPI 2.0 message 이름을 static ASCII string으로 반환합니다. 조합이 CAPI 2.0 standard에 정의되지 않았으면 `NULL`을 반환할 수 있습니다.

6. Helper Functions and Macros
==============================

Macros to extract/set element values from/in a CAPI message header
(from <linux/isdn/capiutil.h>):

======================  =============================   ====================
Get Macro                Set Macro                        Element (Type)
======================  =============================   ====================
CAPIMSG_LEN(m)                CAPIMSG_SETLEN(m, len)                Total Length (u16)
CAPIMSG_APPID(m)        CAPIMSG_SETAPPID(m, applid)        ApplID (u16)
CAPIMSG_COMMAND(m)        CAPIMSG_SETCOMMAND(m,cmd)        Command (u8)
CAPIMSG_SUBCOMMAND(m)        CAPIMSG_SETSUBCOMMAND(m, cmd)        Subcommand (u8)
CAPIMSG_CMD(m)                -                                Command*256
                                                        + Subcommand (u16)
CAPIMSG_MSGID(m)        CAPIMSG_SETMSGID(m, msgid)        Message Number (u16)

CAPIMSG_CONTROL(m)        CAPIMSG_SETCONTROL(m, contr)        Controller/PLCI/NCCI
                                                        (u32)
CAPIMSG_DATALEN(m)        CAPIMSG_SETDATALEN(m, len)        Data Length (u16)
======================  =============================   ====================


Library functions for working with _cmsg structures
(from <linux/isdn/capiutil.h>):

``char *capi_cmd2str(u8 Command, u8 Subcommand)``
        Returns the CAPI 2.0 message name corresponding to the given command
        and subcommand values, as a static ASCII string. The return value may
        be NULL if the command/subcommand is not one of those defined in the
        CAPI 2.0 standard.

kernelcapi debugging과 traceflag

`kernelcapi` module의 `showcapimsgs` parameter는 일부 debugging 출력을 제어합니다. Module을 load할 때만 설정할 수 있으며 command line 또는 configuration file의 modprobe에 `showcapimsgs=<n>` 형식으로 전달합니다.

`showcapimsgs`의 최하위 bit가 설정되면 kernelcapi는 controller와 application의 up/down event를 기록합니다.

등록된 각 CAPI controller에는 controller를 오가는 CAPI message 기록 방식을 정하는 `traceflag` parameter가 있습니다. Controller 등록 시 `showcapimsgs` 값으로 초기화되며 나중에 `MANUFACTURER_REQ` command `KCAPI_CMD_TRACE`로 바꿀 수 있습니다.

7. Debugging
============

The module kernelcapi has a module parameter showcapimsgs controlling some
debugging output produced by the module. It can only be set when the module is
loaded, via a parameter "showcapimsgs=<n>" to the modprobe command, either on
the command line or in the configuration file.

If the lowest bit of showcapimsgs is set, kernelcapi logs controller and
application up and down events.

In addition, every registered CAPI controller has an associated traceflag
parameter controlling how CAPI messages sent from and to the controller are
logged. The traceflag parameter is initialized with the value of the
showcapimsgs parameter when the controller is registered, but can later be
changed via the MANUFACTURER_REQ command KCAPI_CMD_TRACE.

If the value of traceflag is non-zero, CAPI messages are logged.
DATA_B3 messages are only logged if the value of traceflag is > 2.

If the lowest bit of traceflag is set, only the command/subcommand and message
length are logged. Otherwise, kernelcapi logs a readable representation of
the entire message.