Documentation/isdn/INTERFACE.CAPI

   1 Kernel CAPI Interface to Hardware Drivers
   2 -----------------------------------------
   3
   4 1. Overview
   5
   6 From the CAPI 2.0 specification:
   7 COMMON-ISDN-API (CAPI) is an application programming interface standard used
   8 to access ISDN equipment connected to basic rate interfaces (BRI) and primary
   9 rate interfaces (PRI).
  10
  11 Kernel CAPI operates as a dispatching layer between CAPI applications and CAPI
  12 hardware drivers. Hardware drivers register ISDN devices (controllers, in CAPI
  13 lingo) with Kernel CAPI to indicate their readiness to provide their service
  14 to CAPI applications. CAPI applications also register with Kernel CAPI,
  15 requesting association with a CAPI device. Kernel CAPI then dispatches the
  16 application registration to an available device, forwarding it to the
  17 corresponding hardware driver. Kernel CAPI then forwards CAPI messages in both
  18 directions between the application and the hardware driver.
  19
  20 Format and semantics of CAPI messages are specified in the CAPI 2.0 standard.
  21 This standard is freely available from http://www.capi.org.
  22
  23
  24 2. Driver and Device Registration
  25
  26 CAPI drivers optionally register themselves with Kernel CAPI by calling the
  27 Kernel CAPI function register_capi_driver() with a pointer to a struct
  28 capi_driver. This structure must be filled with the name and revision of the
  29 driver, and optionally a pointer to a callback function, add_card(). The
  30 registration can be revoked by calling the function unregister_capi_driver()
  31 with a pointer to the same struct capi_driver.
  32
  33 CAPI drivers must register each of the ISDN devices they control with Kernel
  34 CAPI by calling the Kernel CAPI function attach_capi_ctr() with a pointer to a
  35 struct capi_ctr before they can be used. This structure must be filled with
  36 the names of the driver and controller, and a number of callback function
  37 pointers which are subsequently used by Kernel CAPI for communicating with the
  38 driver. The registration can be revoked by calling the function
  39 detach_capi_ctr() with a pointer to the same struct capi_ctr.
  40
  41 Before the device can be actually used, the driver must fill in the device
  42 information fields 'manu', 'version', 'profile' and 'serial' in the capi_ctr
  43 structure of the device, and signal its readiness by calling capi_ctr_ready().
  44 From then on, Kernel CAPI may call the registered callback functions for the
  45 device.
  46
  47 If the device becomes unusable for any reason (shutdown, disconnect ...), the
  48 driver has to call capi_ctr_down(). This will prevent further calls to the
  49 callback functions by Kernel CAPI.
  50
  51
  52 3. Application Registration and Communication
  53
  54 Kernel CAPI forwards registration requests from applications (calls to CAPI
  55 operation CAPI_REGISTER) to an appropriate hardware driver by calling its
  56 register_appl() callback function. A unique Application ID (ApplID, u16) is
  57 allocated by Kernel CAPI and passed to register_appl() along with the
  58 parameter structure provided by the application. This is analogous to the
  59 open() operation on regular files or character devices.
  60
  61 After a successful return from register_appl(), CAPI messages from the
  62 application may be passed to the driver for the device via calls to the
  63 send_message() callback function. The CAPI message to send is stored in the
  64 data portion of an skb. Conversely, the driver may call Kernel CAPI's
  65 capi_ctr_handle_message() function to pass a received CAPI message to Kernel
  66 CAPI for forwarding to an application, specifying its ApplID.
  67
  68 Deregistration requests (CAPI operation CAPI_RELEASE) from applications are
  69 forwarded as calls to the release_appl() callback function, passing the same
  70 ApplID as with register_appl(). After return from release_appl(), no CAPI
  71 messages for that application may be passed to or from the device anymore.
  72
  73
  74 4. Data Structures
  75
  76 4.1 struct capi_driver
  77
  78 This structure describes a Kernel CAPI driver itself. It is used in the
  79 register_capi_driver() and unregister_capi_driver() functions, and contains
  80 the following non-private fields, all to be set by the driver before calling
  81 register_capi_driver():
  82
  83 char name[32]
  84         the name of the driver, as a zero-terminated ASCII string
  85 char revision[32]
  86         the revision number of the driver, as a zero-terminated ASCII string
  87 int (*add_card)(struct capi_driver *driver, capicardparams *data)
  88         a callback function pointer (may be NULL)
  89
  90
  91 4.2 struct capi_ctr
  92
  93 This structure describes an ISDN device (controller) handled by a Kernel CAPI
  94 driver. After registration via the attach_capi_ctr() function it is passed to
  95 all controller specific lower layer interface and callback functions to
  96 identify the controller to operate on.
  97
  98 It contains the following non-private fields:
  99
 100 - to be set by the driver before calling attach_capi_ctr():
 101
 102 struct module *owner
 103         pointer to the driver module owning the device
 104
 105 void *driverdata
 106         an opaque pointer to driver specific data, not touched by Kernel CAPI
 107
 108 char name[32]
 109         the name of the controller, as a zero-terminated ASCII string
 110
 111 char *driver_name
 112         the name of the driver, as a zero-terminated ASCII string
 113
 114 int (*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         Return value: 0 on success, error code on error
 118         Called in process context.
 119
 120 void (*reset_ctr)(struct capi_ctr *ctrlr)
 121         (optional) pointer to a callback function for performing a reset on
 122         the device, releasing all registered applications
 123         Called in process context.
 124
 125 void (*register_appl)(struct capi_ctr *ctrlr, u16 applid,
 126                         capi_register_params *rparam)
 127 void (*release_appl)(struct capi_ctr *ctrlr, u16 applid)
 128         pointers to callback functions for registration and deregistration of
 129         applications with the device
 130         Calls to these functions are serialized by Kernel CAPI so that only
 131         one call to any of them is active at any time.
 132
 133 u16  (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb)
 134         pointer to a callback function for sending a CAPI message to the
 135         device
 136         Return value: CAPI error code
 137         If the method returns 0 (CAPI_NOERROR) the driver has taken ownership
 138         of the skb and the caller may no longer access it. If it returns a
 139         non-zero (error) value then ownership of the skb returns to the caller
 140         who may reuse or free it.
 141         The return value should only be used to signal problems with respect
 142         to accepting or queueing the message. Errors occurring during the
 143         actual processing of the message should be signaled with an
 144         appropriate reply message.
 145         Calls to this function are not serialized by Kernel CAPI, ie. it must
 146         be prepared to be re-entered.
 147
 148 char *(*procinfo)(struct capi_ctr *ctrlr)
 149         pointer to a callback function returning the entry for the device in
 150         the CAPI controller info table, /proc/capi/controller
 151
 152 read_proc_t *ctr_read_proc
 153         pointer to the read_proc callback function for the device's proc file
 154         system entry, /proc/capi/controllers/<n>; will be called with a
 155         pointer to the device's capi_ctr structure as the last (data) argument
 156
 157 Note: Callback functions are never called in interrupt context.
 158
 159 - to be filled in before calling capi_ctr_ready():
 160
 161 u8 manu[CAPI_MANUFACTURER_LEN]
 162         value to return for CAPI_GET_MANUFACTURER
 163
 164 capi_version version
 165         value to return for CAPI_GET_VERSION
 166
 167 capi_profile profile
 168         value to return for CAPI_GET_PROFILE
 169
 170 u8 serial[CAPI_SERIAL_LEN]
 171         value to return for CAPI_GET_SERIAL
 172
 173
 174 4.3 The _cmsg Structure
 175
 176 (declared in <linux/isdn/capiutil.h>)
 177
 178 The _cmsg structure stores the contents of a CAPI 2.0 message in an easily
 179 accessible form. It contains members for all possible CAPI 2.0 parameters, of
 180 which only those appearing in the message type currently being processed are
 181 actually used. Unused members should be set to zero.
 182
 183 Members are named after the CAPI 2.0 standard names of the parameters they
 184 represent. See <linux/isdn/capiutil.h> for the exact spelling. Member data
 185 types are:
 186
 187 u8          for CAPI parameters of type 'byte'
 188
 189 u16         for CAPI parameters of type 'word'
 190
 191 u32         for CAPI parameters of type 'dword'
 192
 193 _cstruct    for CAPI parameters of type 'struct' not containing any
 194             variably-sized (struct) subparameters (eg. 'Called Party Number')
 195             The member is a pointer to a buffer containing the parameter in
 196             CAPI encoding (length + content). It may also be NULL, which will
 197             be taken to represent an empty (zero length) parameter.
 198
 199 _cmstruct   for CAPI parameters of type 'struct' containing 'struct'
 200             subparameters ('Additional Info' and 'B Protocol')
 201             The representation is a single byte containing one of the values:
 202             CAPI_DEFAULT: the parameter is empty
 203             CAPI_COMPOSE: the values of the subparameters are stored
 204             individually in the corresponding _cmsg structure members
 205
 206 Functions capi_cmsg2message() and capi_message2cmsg() are provided to convert
 207 messages between their transport encoding described in the CAPI 2.0 standard
 208 and their _cmsg structure representation. Note that capi_cmsg2message() does
 209 not know or check the size of its destination buffer. The caller must make
 210 sure it is big enough to accomodate the resulting CAPI message.
 211
 212
 213 5. Lower Layer Interface Functions
 214
 215 (declared in <linux/isdn/capilli.h>)
 216
 217 void register_capi_driver(struct capi_driver *drvr)
 218 void unregister_capi_driver(struct capi_driver *drvr)
 219         register/unregister a driver with Kernel CAPI
 220
 221 int attach_capi_ctr(struct capi_ctr *ctrlr)
 222 int detach_capi_ctr(struct capi_ctr *ctrlr)
 223         register/unregister a device (controller) with Kernel CAPI
 224
 225 void capi_ctr_ready(struct capi_ctr *ctrlr)
 226 void capi_ctr_down(struct capi_ctr *ctrlr)
 227         signal controller ready/not ready
 228
 229 void capi_ctr_suspend_output(struct capi_ctr *ctrlr)
 230 void capi_ctr_resume_output(struct capi_ctr *ctrlr)
 231         signal suspend/resume
 232
 233 void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid,
 234                                 struct sk_buff *skb)
 235         pass a received CAPI message to Kernel CAPI
 236         for forwarding to the specified application
 237
 238
 239 6. Helper Functions and Macros
 240
 241 Library functions (from <linux/isdn/capilli.h>):
 242
 243 void capilib_new_ncci(struct list_head *head, u16 applid,
 244                         u32 ncci, u32 winsize)
 245 void capilib_free_ncci(struct list_head *head, u16 applid, u32 ncci)
 246 void capilib_release_appl(struct list_head *head, u16 applid)
 247 void capilib_release(struct list_head *head)
 248 void capilib_data_b3_conf(struct list_head *head, u16 applid,
 249                         u32 ncci, u16 msgid)
 250 u16  capilib_data_b3_req(struct list_head *head, u16 applid,
 251                         u32 ncci, u16 msgid)
 252
 253
 254 Macros to extract/set element values from/in a CAPI message header
 255 (from <linux/isdn/capiutil.h>):
 256
 257 Get Macro               Set Macro                       Element (Type)
 258
 259 CAPIMSG_LEN(m)          CAPIMSG_SETLEN(m, len)          Total Length (u16)
 260 CAPIMSG_APPID(m)        CAPIMSG_SETAPPID(m, applid)     ApplID (u16)
 261 CAPIMSG_COMMAND(m)      CAPIMSG_SETCOMMAND(m,cmd)       Command (u8)
 262 CAPIMSG_SUBCOMMAND(m)   CAPIMSG_SETSUBCOMMAND(m, cmd)   Subcommand (u8)
 263 CAPIMSG_CMD(m)          -                               Command*256
 264                                                         + Subcommand (u16)
 265 CAPIMSG_MSGID(m)        CAPIMSG_SETMSGID(m, msgid)      Message Number (u16)
 266
 267 CAPIMSG_CONTROL(m)      CAPIMSG_SETCONTROL(m, contr)    Controller/PLCI/NCCI
 268                                                         (u32)
 269 CAPIMSG_DATALEN(m)      CAPIMSG_SETDATALEN(m, len)      Data Length (u16)
 270
 271
 272 Library functions for working with _cmsg structures
 273 (from <linux/isdn/capiutil.h>):
 274
 275 unsigned capi_cmsg2message(_cmsg *cmsg, u8 *msg)
 276         Assembles a CAPI 2.0 message from the parameters in *cmsg, storing the
 277         result in *msg.
 278
 279 unsigned capi_message2cmsg(_cmsg *cmsg, u8 *msg)
 280         Disassembles the CAPI 2.0 message in *msg, storing the parameters in
 281         *cmsg.
 282
 283 unsigned capi_cmsg_header(_cmsg *cmsg, u16 ApplId, u8 Command, u8 Subcommand,
 284                           u16 Messagenumber, u32 Controller)
 285         Fills the header part and address field of the _cmsg structure *cmsg
 286         with the given values, zeroing the remainder of the structure so only
 287         parameters with non-default values need to be changed before sending
 288         the message.
 289
 290 void capi_cmsg_answer(_cmsg *cmsg)
 291         Sets the low bit of the Subcommand field in *cmsg, thereby converting
 292         _REQ to _CONF and _IND to _RESP.
 293
 294 char *capi_cmd2str(u8 Command, u8 Subcommand)
 295         Returns the CAPI 2.0 message name corresponding to the given command
 296         and subcommand values, as a static ASCII string. The return value may
 297         be NULL if the command/subcommand is not one of those defined in the
 298         CAPI 2.0 standard.
 299