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