Documentation/isdn/interface_capi.rst

   1 =========================================
   2 Kernel CAPI Interface to Hardware Drivers
   3 =========================================
   4
   5 1. Overview
   6 ===========
   7
   8 From the CAPI 2.0 specification:
   9 COMMON-ISDN-API (CAPI) is an application programming interface standard used
  10 to access ISDN equipment connected to basic rate interfaces (BRI) and primary
  11 rate interfaces (PRI).
  12
  13 Kernel CAPI operates as a dispatching layer between CAPI applications and CAPI
  14 hardware drivers. Hardware drivers register ISDN devices (controllers, in CAPI
  15 lingo) with Kernel CAPI to indicate their readiness to provide their service
  16 to CAPI applications. CAPI applications also register with Kernel CAPI,
  17 requesting association with a CAPI device. Kernel CAPI then dispatches the
  18 application registration to an available device, forwarding it to the
  19 corresponding hardware driver. Kernel CAPI then forwards CAPI messages in both
  20 directions between the application and the hardware driver.
  21
  22 Format and semantics of CAPI messages are specified in the CAPI 2.0 standard.
  23 This standard is freely available from https://www.capi.org.
  24
  25
  26 2. Driver and Device Registration
  27 =================================
  28
  29 CAPI drivers optionally register themselves with Kernel CAPI by calling the
  30 Kernel CAPI function register_capi_driver() with a pointer to a struct
  31 capi_driver. This structure must be filled with the name and revision of the
  32 driver, and optionally a pointer to a callback function, add_card(). The
  33 registration can be revoked by calling the function unregister_capi_driver()
  34 with a pointer to the same struct capi_driver.
  35
  36 CAPI drivers must register each of the ISDN devices they control with Kernel
  37 CAPI by calling the Kernel CAPI function attach_capi_ctr() with a pointer to a
  38 struct capi_ctr before they can be used. This structure must be filled with
  39 the names of the driver and controller, and a number of callback function
  40 pointers which are subsequently used by Kernel CAPI for communicating with the
  41 driver. The registration can be revoked by calling the function
  42 detach_capi_ctr() with a pointer to the same struct capi_ctr.
  43
  44 Before the device can be actually used, the driver must fill in the device
  45 information fields 'manu', 'version', 'profile' and 'serial' in the capi_ctr
  46 structure of the device, and signal its readiness by calling capi_ctr_ready().
  47 From then on, Kernel CAPI may call the registered callback functions for the
  48 device.
  49
  50 If the device becomes unusable for any reason (shutdown, disconnect ...), the
  51 driver has to call capi_ctr_down(). This will prevent further calls to the
  52 callback functions by Kernel CAPI.
  53
  54
  55 3. Application Registration and Communication
  56 =============================================
  57
  58 Kernel CAPI forwards registration requests from applications (calls to CAPI
  59 operation CAPI_REGISTER) to an appropriate hardware driver by calling its
  60 register_appl() callback function. A unique Application ID (ApplID, u16) is
  61 allocated by Kernel CAPI and passed to register_appl() along with the
  62 parameter structure provided by the application. This is analogous to the
  63 open() operation on regular files or character devices.
  64
  65 After a successful return from register_appl(), CAPI messages from the
  66 application may be passed to the driver for the device via calls to the
  67 send_message() callback function. Conversely, the driver may call Kernel
  68 CAPI's capi_ctr_handle_message() function to pass a received CAPI message to
  69 Kernel CAPI for forwarding to an application, specifying its ApplID.
  70
  71 Deregistration requests (CAPI operation CAPI_RELEASE) from applications are
  72 forwarded as calls to the release_appl() callback function, passing the same
  73 ApplID as with register_appl(). After return from release_appl(), no CAPI
  74 messages for that application may be passed to or from the device anymore.
  75
  76
  77 4. Data Structures
  78 ==================
  79
  80 4.1 struct capi_driver
  81 ----------------------
  82
  83 This structure describes a Kernel CAPI driver itself. It is used in the
  84 register_capi_driver() and unregister_capi_driver() functions, and contains
  85 the following non-private fields, all to be set by the driver before calling
  86 register_capi_driver():
  87
  88 ``char name[32]``
  89         the name of the driver, as a zero-terminated ASCII string
  90 ``char revision[32]``
  91         the revision number of the driver, as a zero-terminated ASCII string
  92 ``int (*add_card)(struct capi_driver *driver, capicardparams *data)``
  93         a callback function pointer (may be NULL)
  94
  95
  96 4.2 struct capi_ctr
  97 -------------------
  98
  99 This structure describes an ISDN device (controller) handled by a Kernel CAPI
 100 driver. After registration via the attach_capi_ctr() function it is passed to
 101 all controller specific lower layer interface and callback functions to
 102 identify the controller to operate on.
 103
 104 It contains the following non-private fields:
 105
 106 to be set by the driver before calling attach_capi_ctr():
 107 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 108
 109 ``struct module *owner``
 110         pointer to the driver module owning the device
 111
 112 ``void *driverdata``
 113         an opaque pointer to driver specific data, not touched by Kernel CAPI
 114
 115 ``char name[32]``
 116         the name of the controller, as a zero-terminated ASCII string
 117
 118 ``char *driver_name``
 119         the name of the driver, as a zero-terminated ASCII string
 120
 121 ``int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata)``
 122         (optional) pointer to a callback function for sending firmware and
 123         configuration data to the device
 124
 125         The function may return before the operation has completed.
 126
 127         Completion must be signalled by a call to capi_ctr_ready().
 128
 129         Return value: 0 on success, error code on error
 130         Called in process context.
 131
 132 ``void (*reset_ctr)(struct capi_ctr *ctrlr)``
 133         (optional) pointer to a callback function for stopping the device,
 134         releasing all registered applications
 135
 136         The function may return before the operation has completed.
 137
 138         Completion must be signalled by a call to capi_ctr_down().
 139
 140         Called in process context.
 141
 142 ``void (*register_appl)(struct capi_ctr *ctrlr, u16 applid, capi_register_params *rparam)``
 143         pointers to callback function for registration of
 144         applications with the device
 145
 146         Calls to these functions are serialized by Kernel CAPI so that only
 147         one call to any of them is active at any time.
 148
 149 ``void (*release_appl)(struct capi_ctr *ctrlr, u16 applid)``
 150         pointers to callback functions deregistration of
 151         applications with the device
 152
 153         Calls to these functions are serialized by Kernel CAPI so that only
 154         one call to any of them is active at any time.
 155
 156 ``u16  (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb)``
 157         pointer to a callback function for sending a CAPI message to the
 158         device
 159
 160         Return value: CAPI error code
 161
 162         If the method returns 0 (CAPI_NOERROR) the driver has taken ownership
 163         of the skb and the caller may no longer access it. If it returns a
 164         non-zero (error) value then ownership of the skb returns to the caller
 165         who may reuse or free it.
 166
 167         The return value should only be used to signal problems with respect
 168         to accepting or queueing the message. Errors occurring during the
 169         actual processing of the message should be signaled with an
 170         appropriate reply message.
 171
 172         May be called in process or interrupt context.
 173
 174         Calls to this function are not serialized by Kernel CAPI, ie. it must
 175         be prepared to be re-entered.
 176
 177 ``char *(*procinfo)(struct capi_ctr *ctrlr)``
 178         pointer to a callback function returning the entry for the device in
 179         the CAPI controller info table, /proc/capi/controller
 180
 181 ``const struct file_operations *proc_fops``
 182         pointers to callback functions for the device's proc file
 183         system entry, /proc/capi/controllers/<n>; pointer to the device's
 184         capi_ctr structure is available from struct proc_dir_entry::data
 185         which is available from struct inode.
 186
 187 Note:
 188   Callback functions except send_message() are never called in interrupt
 189   context.
 190
 191 to be filled in before calling capi_ctr_ready():
 192 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 193
 194 ``u8 manu[CAPI_MANUFACTURER_LEN]``
 195         value to return for CAPI_GET_MANUFACTURER
 196
 197 ``capi_version version``
 198         value to return for CAPI_GET_VERSION
 199
 200 ``capi_profile profile``
 201         value to return for CAPI_GET_PROFILE
 202
 203 ``u8 serial[CAPI_SERIAL_LEN]``
 204         value to return for CAPI_GET_SERIAL
 205
 206
 207 4.3 SKBs
 208 --------
 209
 210 CAPI messages are passed between Kernel CAPI and the driver via send_message()
 211 and capi_ctr_handle_message(), stored in the data portion of a socket buffer
 212 (skb).  Each skb contains a single CAPI message coded according to the CAPI 2.0
 213 standard.
 214
 215 For the data transfer messages, DATA_B3_REQ and DATA_B3_IND, the actual
 216 payload data immediately follows the CAPI message itself within the same skb.
 217 The Data and Data64 parameters are not used for processing. The Data64
 218 parameter may be omitted by setting the length field of the CAPI message to 22
 219 instead of 30.
 220
 221
 222 4.4 The _cmsg Structure
 223 -----------------------
 224
 225 (declared in <linux/isdn/capiutil.h>)
 226
 227 The _cmsg structure stores the contents of a CAPI 2.0 message in an easily
 228 accessible form. It contains members for all possible CAPI 2.0 parameters,
 229 including subparameters of the Additional Info and B Protocol structured
 230 parameters, with the following exceptions:
 231
 232 * second Calling party number (CONNECT_IND)
 233
 234 * Data64 (DATA_B3_REQ and DATA_B3_IND)
 235
 236 * Sending complete (subparameter of Additional Info, CONNECT_REQ and INFO_REQ)
 237
 238 * Global Configuration (subparameter of B Protocol, CONNECT_REQ, CONNECT_RESP
 239   and SELECT_B_PROTOCOL_REQ)
 240
 241 Only those parameters appearing in the message type currently being processed
 242 are actually used. Unused members should be set to zero.
 243
 244 Members are named after the CAPI 2.0 standard names of the parameters they
 245 represent. See <linux/isdn/capiutil.h> for the exact spelling. Member data
 246 types are:
 247
 248 =========== =================================================================
 249 u8          for CAPI parameters of type 'byte'
 250
 251 u16         for CAPI parameters of type 'word'
 252
 253 u32         for CAPI parameters of type 'dword'
 254
 255 _cstruct    for CAPI parameters of type 'struct'
 256             The member is a pointer to a buffer containing the parameter in
 257             CAPI encoding (length + content). It may also be NULL, which will
 258             be taken to represent an empty (zero length) parameter.
 259             Subparameters are stored in encoded form within the content part.
 260
 261 _cmstruct   alternative representation for CAPI parameters of type 'struct'
 262             (used only for the 'Additional Info' and 'B Protocol' parameters)
 263             The representation is a single byte containing one of the values:
 264             CAPI_DEFAULT: The parameter is empty/absent.
 265             CAPI_COMPOSE: The parameter is present.
 266             Subparameter values are stored individually in the corresponding
 267             _cmsg structure members.
 268 =========== =================================================================
 269
 270 Functions capi_cmsg2message() and capi_message2cmsg() are provided to convert
 271 messages between their transport encoding described in the CAPI 2.0 standard
 272 and their _cmsg structure representation. Note that capi_cmsg2message() does
 273 not know or check the size of its destination buffer. The caller must make
 274 sure it is big enough to accommodate the resulting CAPI message.
 275
 276
 277 5. Lower Layer Interface Functions
 278 ==================================
 279
 280 (declared in <linux/isdn/capilli.h>)
 281
 282 ::
 283
 284   void register_capi_driver(struct capi_driver *drvr)
 285   void unregister_capi_driver(struct capi_driver *drvr)
 286
 287 register/unregister a driver with Kernel CAPI
 288
 289 ::
 290
 291   int attach_capi_ctr(struct capi_ctr *ctrlr)
 292   int detach_capi_ctr(struct capi_ctr *ctrlr)
 293
 294 register/unregister a device (controller) with Kernel CAPI
 295
 296 ::
 297
 298   void capi_ctr_ready(struct capi_ctr *ctrlr)
 299   void capi_ctr_down(struct capi_ctr *ctrlr)
 300
 301 signal controller ready/not ready
 302
 303 ::
 304
 305   void capi_ctr_suspend_output(struct capi_ctr *ctrlr)
 306   void capi_ctr_resume_output(struct capi_ctr *ctrlr)
 307
 308 signal suspend/resume
 309
 310 ::
 311
 312   void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid,
 313                                struct sk_buff *skb)
 314
 315 pass a received CAPI message to Kernel CAPI
 316 for forwarding to the specified application
 317
 318
 319 6. Helper Functions and Macros
 320 ==============================
 321
 322 Library functions (from <linux/isdn/capilli.h>):
 323
 324 ::
 325
 326   void capilib_new_ncci(struct list_head *head, u16 applid,
 327                         u32 ncci, u32 winsize)
 328   void capilib_free_ncci(struct list_head *head, u16 applid, u32 ncci)
 329   void capilib_release_appl(struct list_head *head, u16 applid)
 330   void capilib_release(struct list_head *head)
 331   void capilib_data_b3_conf(struct list_head *head, u16 applid,
 332                         u32 ncci, u16 msgid)
 333   u16  capilib_data_b3_req(struct list_head *head, u16 applid,
 334                         u32 ncci, u16 msgid)
 335
 336
 337 Macros to extract/set element values from/in a CAPI message header
 338 (from <linux/isdn/capiutil.h>):
 339
 340 ======================  =============================   ====================
 341 Get Macro               Set Macro                       Element (Type)
 342 ======================  =============================   ====================
 343 CAPIMSG_LEN(m)          CAPIMSG_SETLEN(m, len)          Total Length (u16)
 344 CAPIMSG_APPID(m)        CAPIMSG_SETAPPID(m, applid)     ApplID (u16)
 345 CAPIMSG_COMMAND(m)      CAPIMSG_SETCOMMAND(m,cmd)       Command (u8)
 346 CAPIMSG_SUBCOMMAND(m)   CAPIMSG_SETSUBCOMMAND(m, cmd)   Subcommand (u8)
 347 CAPIMSG_CMD(m)          -                               Command*256
 348                                                         + Subcommand (u16)
 349 CAPIMSG_MSGID(m)        CAPIMSG_SETMSGID(m, msgid)      Message Number (u16)
 350
 351 CAPIMSG_CONTROL(m)      CAPIMSG_SETCONTROL(m, contr)    Controller/PLCI/NCCI
 352                                                         (u32)
 353 CAPIMSG_DATALEN(m)      CAPIMSG_SETDATALEN(m, len)      Data Length (u16)
 354 ======================  =============================   ====================
 355
 356
 357 Library functions for working with _cmsg structures
 358 (from <linux/isdn/capiutil.h>):
 359
 360 ``unsigned capi_cmsg2message(_cmsg *cmsg, u8 *msg)``
 361         Assembles a CAPI 2.0 message from the parameters in ``*cmsg``,
 362         storing the result in ``*msg``.
 363
 364 ``unsigned capi_message2cmsg(_cmsg *cmsg, u8 *msg)``
 365         Disassembles the CAPI 2.0 message in ``*msg``, storing the parameters
 366         in ``*cmsg``.
 367
 368 ``unsigned capi_cmsg_header(_cmsg *cmsg, u16 ApplId, u8 Command, u8 Subcommand, u16 Messagenumber, u32 Controller)``
 369         Fills the header part and address field of the _cmsg structure ``*cmsg``
 370         with the given values, zeroing the remainder of the structure so only
 371         parameters with non-default values need to be changed before sending
 372         the message.
 373
 374 ``void capi_cmsg_answer(_cmsg *cmsg)``
 375         Sets the low bit of the Subcommand field in ``*cmsg``, thereby
 376         converting ``_REQ`` to ``_CONF`` and ``_IND`` to ``_RESP``.
 377
 378 ``char *capi_cmd2str(u8 Command, u8 Subcommand)``
 379         Returns the CAPI 2.0 message name corresponding to the given command
 380         and subcommand values, as a static ASCII string. The return value may
 381         be NULL if the command/subcommand is not one of those defined in the
 382         CAPI 2.0 standard.
 383
 384
 385 7. Debugging
 386 ============
 387
 388 The module kernelcapi has a module parameter showcapimsgs controlling some
 389 debugging output produced by the module. It can only be set when the module is
 390 loaded, via a parameter "showcapimsgs=<n>" to the modprobe command, either on
 391 the command line or in the configuration file.
 392
 393 If the lowest bit of showcapimsgs is set, kernelcapi logs controller and
 394 application up and down events.
 395
 396 In addition, every registered CAPI controller has an associated traceflag
 397 parameter controlling how CAPI messages sent from and to tha controller are
 398 logged. The traceflag parameter is initialized with the value of the
 399 showcapimsgs parameter when the controller is registered, but can later be
 400 changed via the MANUFACTURER_REQ command KCAPI_CMD_TRACE.
 401
 402 If the value of traceflag is non-zero, CAPI messages are logged.
 403 DATA_B3 messages are only logged if the value of traceflag is > 2.
 404
 405 If the lowest bit of traceflag is set, only the command/subcommand and message
 406 length are logged. Otherwise, kernelcapi logs a readable representation of
 407 the entire message.