linux/Documentation/isdn/INTERFACE.CAPI
<<
>>
Prefs
   1Kernel CAPI Interface to Hardware Drivers
   2-----------------------------------------
   3
   41. Overview
   5
   6From the CAPI 2.0 specification:
   7COMMON-ISDN-API (CAPI) is an application programming interface standard used
   8to access ISDN equipment connected to basic rate interfaces (BRI) and primary
   9rate interfaces (PRI).
  10
  11Kernel CAPI operates as a dispatching layer between CAPI applications and CAPI
  12hardware drivers. Hardware drivers register ISDN devices (controllers, in CAPI
  13lingo) with Kernel CAPI to indicate their readiness to provide their service
  14to CAPI applications. CAPI applications also register with Kernel CAPI,
  15requesting association with a CAPI device. Kernel CAPI then dispatches the
  16application registration to an available device, forwarding it to the
  17corresponding hardware driver. Kernel CAPI then forwards CAPI messages in both
  18directions between the application and the hardware driver.
  19
  20Format and semantics of CAPI messages are specified in the CAPI 2.0 standard.
  21This standard is freely available from http://www.capi.org.
  22
  23
  242. Driver and Device Registration
  25
  26CAPI drivers optionally register themselves with Kernel CAPI by calling the
  27Kernel CAPI function register_capi_driver() with a pointer to a struct
  28capi_driver. This structure must be filled with the name and revision of the
  29driver, and optionally a pointer to a callback function, add_card(). The
  30registration can be revoked by calling the function unregister_capi_driver()
  31with a pointer to the same struct capi_driver.
  32
  33CAPI drivers must register each of the ISDN devices they control with Kernel
  34CAPI by calling the Kernel CAPI function attach_capi_ctr() with a pointer to a
  35struct capi_ctr before they can be used. This structure must be filled with
  36the names of the driver and controller, and a number of callback function
  37pointers which are subsequently used by Kernel CAPI for communicating with the
  38driver. The registration can be revoked by calling the function
  39detach_capi_ctr() with a pointer to the same struct capi_ctr.
  40
  41Before the device can be actually used, the driver must fill in the device
  42information fields 'manu', 'version', 'profile' and 'serial' in the capi_ctr
  43structure of the device, and signal its readiness by calling capi_ctr_ready().
  44From then on, Kernel CAPI may call the registered callback functions for the
  45device.
  46
  47If the device becomes unusable for any reason (shutdown, disconnect ...), the
  48driver has to call capi_ctr_reseted(). This will prevent further calls to the
  49callback functions by Kernel CAPI.
  50
  51
  523. Application Registration and Communication
  53
  54Kernel CAPI forwards registration requests from applications (calls to CAPI
  55operation CAPI_REGISTER) to an appropriate hardware driver by calling its
  56register_appl() callback function. A unique Application ID (ApplID, u16) is
  57allocated by Kernel CAPI and passed to register_appl() along with the
  58parameter structure provided by the application. This is analogous to the
  59open() operation on regular files or character devices.
  60
  61After a successful return from register_appl(), CAPI messages from the
  62application may be passed to the driver for the device via calls to the
  63send_message() callback function. The CAPI message to send is stored in the
  64data portion of an skb. Conversely, the driver may call Kernel CAPI's
  65capi_ctr_handle_message() function to pass a received CAPI message to Kernel
  66CAPI for forwarding to an application, specifying its ApplID.
  67
  68Deregistration requests (CAPI operation CAPI_RELEASE) from applications are
  69forwarded as calls to the release_appl() callback function, passing the same
  70ApplID as with register_appl(). After return from release_appl(), no CAPI
  71messages for that application may be passed to or from the device anymore.
  72
  73
  744. Data Structures
  75
  764.1 struct capi_driver
  77
  78This structure describes a Kernel CAPI driver itself. It is used in the
  79register_capi_driver() and unregister_capi_driver() functions, and contains
  80the following non-private fields, all to be set by the driver before calling
  81register_capi_driver():
  82
  83char name[32]
  84        the name of the driver, as a zero-terminated ASCII string
  85char revision[32]
  86        the revision number of the driver, as a zero-terminated ASCII string
  87int (*add_card)(struct capi_driver *driver, capicardparams *data)
  88        a callback function pointer (may be NULL)
  89
  90
  914.2 struct capi_ctr
  92
  93This structure describes an ISDN device (controller) handled by a Kernel CAPI
  94driver. After registration via the attach_capi_ctr() function it is passed to
  95all controller specific lower layer interface and callback functions to
  96identify the controller to operate on.
  97
  98It contains the following non-private fields:
  99
 100- to be set by the driver before calling attach_capi_ctr():
 101
 102struct module *owner
 103        pointer to the driver module owning the device
 104
 105void *driverdata
 106        an opaque pointer to driver specific data, not touched by Kernel CAPI
 107
 108char name[32]
 109        the name of the controller, as a zero-terminated ASCII string
 110
 111char *driver_name
 112        the name of the driver, as a zero-terminated ASCII string
 113
 114int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata)
 115        (optional) pointer to a callback function for sending firmware and
 116        configuration data to the device
 117
 118void (*reset_ctr)(struct capi_ctr *ctrlr)
 119        pointer to a callback function for performing a reset on the device,
 120        releasing all registered applications
 121
 122void (*register_appl)(struct capi_ctr *ctrlr, u16 applid,
 123                        capi_register_params *rparam)
 124void (*release_appl)(struct capi_ctr *ctrlr, u16 applid)
 125        pointers to callback functions for registration and deregistration of
 126        applications with the device
 127
 128u16  (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb)
 129        pointer to a callback function for sending a CAPI message to the
 130        device
 131
 132char *(*procinfo)(struct capi_ctr *ctrlr)
 133        pointer to a callback function returning the entry for the device in
 134        the CAPI controller info table, /proc/capi/controller
 135
 136read_proc_t *ctr_read_proc
 137        pointer to the read_proc callback function for the device's proc file
 138        system entry, /proc/capi/controllers/<n>; will be called with a
 139        pointer to the device's capi_ctr structure as the last (data) argument
 140
 141- to be filled in before calling capi_ctr_ready():
 142
 143u8 manu[CAPI_MANUFACTURER_LEN]
 144        value to return for CAPI_GET_MANUFACTURER
 145
 146capi_version version
 147        value to return for CAPI_GET_VERSION
 148
 149capi_profile profile
 150        value to return for CAPI_GET_PROFILE
 151
 152u8 serial[CAPI_SERIAL_LEN]
 153        value to return for CAPI_GET_SERIAL
 154
 155
 1565. Lower Layer Interface Functions
 157
 158(declared in <linux/isdn/capilli.h>)
 159
 160void register_capi_driver(struct capi_driver *drvr)
 161void unregister_capi_driver(struct capi_driver *drvr)
 162        register/unregister a driver with Kernel CAPI
 163
 164int attach_capi_ctr(struct capi_ctr *ctrlr)
 165int detach_capi_ctr(struct capi_ctr *ctrlr)
 166        register/unregister a device (controller) with Kernel CAPI
 167
 168void capi_ctr_ready(struct capi_ctr *ctrlr)
 169void capi_ctr_reseted(struct capi_ctr *ctrlr)
 170        signal controller ready/not ready
 171
 172void capi_ctr_suspend_output(struct capi_ctr *ctrlr)
 173void capi_ctr_resume_output(struct capi_ctr *ctrlr)
 174        signal suspend/resume
 175
 176void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid,
 177                                struct sk_buff *skb)
 178        pass a received CAPI message to Kernel CAPI
 179        for forwarding to the specified application
 180
 181
 1826. Helper Functions and Macros
 183
 184Library functions (from <linux/isdn/capilli.h>):
 185
 186void capilib_new_ncci(struct list_head *head, u16 applid,
 187                        u32 ncci, u32 winsize)
 188void capilib_free_ncci(struct list_head *head, u16 applid, u32 ncci)
 189void capilib_release_appl(struct list_head *head, u16 applid)
 190void capilib_release(struct list_head *head)
 191void capilib_data_b3_conf(struct list_head *head, u16 applid,
 192                        u32 ncci, u16 msgid)
 193u16  capilib_data_b3_req(struct list_head *head, u16 applid,
 194                        u32 ncci, u16 msgid)
 195
 196
 197Macros to extract/set element values from/in a CAPI message header
 198(from <linux/isdn/capiutil.h>):
 199
 200Get Macro               Set Macro                       Element (Type)
 201
 202CAPIMSG_LEN(m)          CAPIMSG_SETLEN(m, len)          Total Length (u16)
 203CAPIMSG_APPID(m)        CAPIMSG_SETAPPID(m, applid)     ApplID (u16)
 204CAPIMSG_COMMAND(m)      CAPIMSG_SETCOMMAND(m,cmd)       Command (u8)
 205CAPIMSG_SUBCOMMAND(m)   CAPIMSG_SETSUBCOMMAND(m, cmd)   Subcommand (u8)
 206CAPIMSG_CMD(m)          -                               Command*256
 207                                                        + Subcommand (u16)
 208CAPIMSG_MSGID(m)        CAPIMSG_SETMSGID(m, msgid)      Message Number (u16)
 209
 210CAPIMSG_CONTROL(m)      CAPIMSG_SETCONTROL(m, contr)    Controller/PLCI/NCCI
 211                                                        (u32)
 212CAPIMSG_DATALEN(m)      CAPIMSG_SETDATALEN(m, len)      Data Length (u16)
 213
 214