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