SAFE public projects git trees. - safe/jmp/linux-2.6/blob - Documentation/isdn/INTERFACE.CAPI

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