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. Conversely, the driver may call Kernel
  64 CAPI's capi_ctr_handle_message() function to pass a received CAPI message to
  65 Kernel CAPI for forwarding to an application, specifying its ApplID.
  66
  67 Deregistration requests (CAPI operation CAPI_RELEASE) from applications are
  68 forwarded as calls to the release_appl() callback function, passing the same
  69 ApplID as with register_appl(). After return from release_appl(), no CAPI
  70 messages for that application may be passed to or from the device anymore.
  71
  72
  73 4. Data Structures
  74
  75 4.1 struct capi_driver
  76
  77 This structure describes a Kernel CAPI driver itself. It is used in the
  78 register_capi_driver() and unregister_capi_driver() functions, and contains
  79 the following non-private fields, all to be set by the driver before calling
  80 register_capi_driver():
  81
  82 char name[32]
  83         the name of the driver, as a zero-terminated ASCII string
  84 char revision[32]
  85         the revision number of the driver, as a zero-terminated ASCII string
  86 int (*add_card)(struct capi_driver *driver, capicardparams *data)
  87         a callback function pointer (may be NULL)
  88
  89
  90 4.2 struct capi_ctr
  91
  92 This structure describes an ISDN device (controller) handled by a Kernel CAPI
  93 driver. After registration via the attach_capi_ctr() function it is passed to
  94 all controller specific lower layer interface and callback functions to
  95 identify the controller to operate on.
  96
  97 It contains the following non-private fields:
  98
  99 - to be set by the driver before calling attach_capi_ctr():
 100
 101 struct module *owner
 102         pointer to the driver module owning the device
 103
 104 void *driverdata
 105         an opaque pointer to driver specific data, not touched by Kernel CAPI
 106
 107 char name[32]
 108         the name of the controller, as a zero-terminated ASCII string
 109
 110 char *driver_name
 111         the name of the driver, as a zero-terminated ASCII string
 112
 113 int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata)
 114         (optional) pointer to a callback function for sending firmware and
 115         configuration data to the device
 116         Return value: 0 on success, error code on error
 117         Called in process context.
 118
 119 void (*reset_ctr)(struct capi_ctr *ctrlr)
 120         (optional) pointer to a callback function for performing a reset on
 121         the device, releasing all registered applications
 122         Called in process context.
 123
 124 void (*register_appl)(struct capi_ctr *ctrlr, u16 applid,
 125                         capi_register_params *rparam)
 126 void (*release_appl)(struct capi_ctr *ctrlr, u16 applid)
 127         pointers to callback functions for registration and deregistration of
 128         applications with the device
 129         Calls to these functions are serialized by Kernel CAPI so that only
 130         one call to any of them is active at any time.
 131
 132 u16  (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb)
 133         pointer to a callback function for sending a CAPI message to the
 134         device
 135         Return value: CAPI error code
 136         If the method returns 0 (CAPI_NOERROR) the driver has taken ownership
 137         of the skb and the caller may no longer access it. If it returns a
 138         non-zero (error) value then ownership of the skb returns to the caller
 139         who may reuse or free it.
 140         The return value should only be used to signal problems with respect
 141         to accepting or queueing the message. Errors occurring during the
 142         actual processing of the message should be signaled with an
 143         appropriate reply message.
 144         May be called in process or interrupt context.
 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 const struct file_operations *proc_fops
 153         pointers to callback functions for the device's proc file
 154         system entry, /proc/capi/controllers/<n>; pointer to the device's
 155         capi_ctr structure is available from struct proc_dir_entry::data
 156         which is available from struct inode.
 157
 158 Note: Callback functions except send_message() are never called in interrupt
 159 context.
 160
 161 - to be filled in before calling capi_ctr_ready():
 162
 163 u8 manu[CAPI_MANUFACTURER_LEN]
 164         value to return for CAPI_GET_MANUFACTURER
 165
 166 capi_version version
 167         value to return for CAPI_GET_VERSION
 168
 169 capi_profile profile
 170         value to return for CAPI_GET_PROFILE
 171
 172 u8 serial[CAPI_SERIAL_LEN]
 173         value to return for CAPI_GET_SERIAL
 174
 175
 176 4.3 SKBs
 177
 178 CAPI messages are passed between Kernel CAPI and the driver via send_message()
 179 and capi_ctr_handle_message(), stored in the data portion of a socket buffer
 180 (skb).  Each skb contains a single CAPI message coded according to the CAPI 2.0
 181 standard.
 182
 183 For the data transfer messages, DATA_B3_REQ and DATA_B3_IND, the actual
 184 payload data immediately follows the CAPI message itself within the same skb.
 185 The Data and Data64 parameters are not used for processing. The Data64
 186 parameter may be omitted by setting the length field of the CAPI message to 22
 187 instead of 30.
 188
 189
 190 4.4 The _cmsg Structure
 191
 192 (declared in <linux/isdn/capiutil.h>)
 193
 194 The _cmsg structure stores the contents of a CAPI 2.0 message in an easily
 195 accessible form. It contains members for all possible CAPI 2.0 parameters,
 196 including subparameters of the Additional Info and B Protocol structured
 197 parameters, with the following exceptions:
 198
 199 * second Calling party number (CONNECT_IND)
 200
 201 * Data64 (DATA_B3_REQ and DATA_B3_IND)
 202
 203 * Sending complete (subparameter of Additional Info, CONNECT_REQ and INFO_REQ)
 204
 205 * Global Configuration (subparameter of B Protocol, CONNECT_REQ, CONNECT_RESP
 206   and SELECT_B_PROTOCOL_REQ)
 207
 208 Only those parameters appearing in the message type currently being processed
 209 are actually used. Unused members should be set to zero.
 210
 211 Members are named after the CAPI 2.0 standard names of the parameters they
 212 represent. See <linux/isdn/capiutil.h> for the exact spelling. Member data
 213 types are:
 214
 215 u8          for CAPI parameters of type 'byte'
 216
 217 u16         for CAPI parameters of type 'word'
 218
 219 u32         for CAPI parameters of type 'dword'
 220
 221 _cstruct    for CAPI parameters of type 'struct'
 222             The member is a pointer to a buffer containing the parameter in
 223             CAPI encoding (length + content). It may also be NULL, which will
 224             be taken to represent an empty (zero length) parameter.
 225             Subparameters are stored in encoded form within the content part.
 226
 227 _cmstruct   alternative representation for CAPI parameters of type 'struct'
 228             (used only for the 'Additional Info' and 'B Protocol' parameters)
 229             The representation is a single byte containing one of the values:
 230             CAPI_DEFAULT: The parameter is empty/absent.
 231             CAPI_COMPOSE: The parameter is present.
 232             Subparameter values are stored individually in the corresponding
 233             _cmsg structure members.
 234
 235 Functions capi_cmsg2message() and capi_message2cmsg() are provided to convert
 236 messages between their transport encoding described in the CAPI 2.0 standard
 237 and their _cmsg structure representation. Note that capi_cmsg2message() does
 238 not know or check the size of its destination buffer. The caller must make
 239 sure it is big enough to accomodate the resulting CAPI message.
 240
 241
 242 5. Lower Layer Interface Functions
 243
 244 (declared in <linux/isdn/capilli.h>)
 245
 246 void register_capi_driver(struct capi_driver *drvr)
 247 void unregister_capi_driver(struct capi_driver *drvr)
 248         register/unregister a driver with Kernel CAPI
 249
 250 int attach_capi_ctr(struct capi_ctr *ctrlr)
 251 int detach_capi_ctr(struct capi_ctr *ctrlr)
 252         register/unregister a device (controller) with Kernel CAPI
 253
 254 void capi_ctr_ready(struct capi_ctr *ctrlr)
 255 void capi_ctr_down(struct capi_ctr *ctrlr)
 256         signal controller ready/not ready
 257
 258 void capi_ctr_suspend_output(struct capi_ctr *ctrlr)
 259 void capi_ctr_resume_output(struct capi_ctr *ctrlr)
 260         signal suspend/resume
 261
 262 void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid,
 263                                 struct sk_buff *skb)
 264         pass a received CAPI message to Kernel CAPI
 265         for forwarding to the specified application
 266
 267
 268 6. Helper Functions and Macros
 269
 270 Library functions (from <linux/isdn/capilli.h>):
 271
 272 void capilib_new_ncci(struct list_head *head, u16 applid,
 273                         u32 ncci, u32 winsize)
 274 void capilib_free_ncci(struct list_head *head, u16 applid, u32 ncci)
 275 void capilib_release_appl(struct list_head *head, u16 applid)
 276 void capilib_release(struct list_head *head)
 277 void capilib_data_b3_conf(struct list_head *head, u16 applid,
 278                         u32 ncci, u16 msgid)
 279 u16  capilib_data_b3_req(struct list_head *head, u16 applid,
 280                         u32 ncci, u16 msgid)
 281
 282
 283 Macros to extract/set element values from/in a CAPI message header
 284 (from <linux/isdn/capiutil.h>):
 285
 286 Get Macro               Set Macro                       Element (Type)
 287
 288 CAPIMSG_LEN(m)          CAPIMSG_SETLEN(m, len)          Total Length (u16)
 289 CAPIMSG_APPID(m)        CAPIMSG_SETAPPID(m, applid)     ApplID (u16)
 290 CAPIMSG_COMMAND(m)      CAPIMSG_SETCOMMAND(m,cmd)       Command (u8)
 291 CAPIMSG_SUBCOMMAND(m)   CAPIMSG_SETSUBCOMMAND(m, cmd)   Subcommand (u8)
 292 CAPIMSG_CMD(m)          -                               Command*256
 293                                                         + Subcommand (u16)
 294 CAPIMSG_MSGID(m)        CAPIMSG_SETMSGID(m, msgid)      Message Number (u16)
 295
 296 CAPIMSG_CONTROL(m)      CAPIMSG_SETCONTROL(m, contr)    Controller/PLCI/NCCI
 297                                                         (u32)
 298 CAPIMSG_DATALEN(m)      CAPIMSG_SETDATALEN(m, len)      Data Length (u16)
 299
 300
 301 Library functions for working with _cmsg structures
 302 (from <linux/isdn/capiutil.h>):
 303
 304 unsigned capi_cmsg2message(_cmsg *cmsg, u8 *msg)
 305         Assembles a CAPI 2.0 message from the parameters in *cmsg, storing the
 306         result in *msg.
 307
 308 unsigned capi_message2cmsg(_cmsg *cmsg, u8 *msg)
 309         Disassembles the CAPI 2.0 message in *msg, storing the parameters in
 310         *cmsg.
 311
 312 unsigned capi_cmsg_header(_cmsg *cmsg, u16 ApplId, u8 Command, u8 Subcommand,
 313                           u16 Messagenumber, u32 Controller)
 314         Fills the header part and address field of the _cmsg structure *cmsg
 315         with the given values, zeroing the remainder of the structure so only
 316         parameters with non-default values need to be changed before sending
 317         the message.
 318
 319 void capi_cmsg_answer(_cmsg *cmsg)
 320         Sets the low bit of the Subcommand field in *cmsg, thereby converting
 321         _REQ to _CONF and _IND to _RESP.
 322
 323 char *capi_cmd2str(u8 Command, u8 Subcommand)
 324         Returns the CAPI 2.0 message name corresponding to the given command
 325         and subcommand values, as a static ASCII string. The return value may
 326         be NULL if the command/subcommand is not one of those defined in the
 327         CAPI 2.0 standard.
 328
 329
 330 7. Debugging
 331
 332 The module kernelcapi has a module parameter showcapimsgs controlling some
 333 debugging output produced by the module. It can only be set when the module is
 334 loaded, via a parameter "showcapimsgs=<n>" to the modprobe command, either on
 335 the command line or in the configuration file.
 336
 337 If the lowest bit of showcapimsgs is set, kernelcapi logs controller and
 338 application up and down events.
 339
 340 In addition, every registered CAPI controller has an associated traceflag
 341 parameter controlling how CAPI messages sent from and to tha controller are
 342 logged. The traceflag parameter is initialized with the value of the
 343 showcapimsgs parameter when the controller is registered, but can later be
 344 changed via the MANUFACTURER_REQ command KCAPI_CMD_TRACE.
 345
 346 If the value of traceflag is non-zero, CAPI messages are logged.
 347 DATA_B3 messages are only logged if the value of traceflag is > 2.
 348
 349 If the lowest bit of traceflag is set, only the command/subcommand and message
 350 length are logged. Otherwise, kernelcapi logs a readable representation of
 351 the entire message.