1========================================= 2Kernel CAPI Interface to Hardware Drivers 3========================================= 4 51. Overview 6=========== 7 8From the CAPI 2.0 specification: 9COMMON-ISDN-API (CAPI) is an application programming interface standard used 10to access ISDN equipment connected to basic rate interfaces (BRI) and primary 11rate interfaces (PRI). 12 13Kernel CAPI operates as a dispatching layer between CAPI applications and CAPI 14hardware drivers. Hardware drivers register ISDN devices (controllers, in CAPI 15lingo) with Kernel CAPI to indicate their readiness to provide their service 16to CAPI applications. CAPI applications also register with Kernel CAPI, 17requesting association with a CAPI device. Kernel CAPI then dispatches the 18application registration to an available device, forwarding it to the 19corresponding hardware driver. Kernel CAPI then forwards CAPI messages in both 20directions between the application and the hardware driver. 21 22Format and semantics of CAPI messages are specified in the CAPI 2.0 standard. 23This standard is freely available from https://www.capi.org. 24 25 262. Driver and Device Registration 27================================= 28 29CAPI drivers optionally register themselves with Kernel CAPI by calling the 30Kernel CAPI function register_capi_driver() with a pointer to a struct 31capi_driver. This structure must be filled with the name and revision of the 32driver, and optionally a pointer to a callback function, add_card(). The 33registration can be revoked by calling the function unregister_capi_driver() 34with a pointer to the same struct capi_driver. 35 36CAPI drivers must register each of the ISDN devices they control with Kernel 37CAPI by calling the Kernel CAPI function attach_capi_ctr() with a pointer to a 38struct capi_ctr before they can be used. This structure must be filled with 39the names of the driver and controller, and a number of callback function 40pointers which are subsequently used by Kernel CAPI for communicating with the 41driver. The registration can be revoked by calling the function 42detach_capi_ctr() with a pointer to the same struct capi_ctr. 43 44Before the device can be actually used, the driver must fill in the device 45information fields 'manu', 'version', 'profile' and 'serial' in the capi_ctr 46structure of the device, and signal its readiness by calling capi_ctr_ready(). 47From then on, Kernel CAPI may call the registered callback functions for the 48device. 49 50If the device becomes unusable for any reason (shutdown, disconnect ...), the 51driver has to call capi_ctr_down(). This will prevent further calls to the 52callback functions by Kernel CAPI. 53 54 553. Application Registration and Communication 56============================================= 57 58Kernel CAPI forwards registration requests from applications (calls to CAPI 59operation CAPI_REGISTER) to an appropriate hardware driver by calling its 60register_appl() callback function. A unique Application ID (ApplID, u16) is 61allocated by Kernel CAPI and passed to register_appl() along with the 62parameter structure provided by the application. This is analogous to the 63open() operation on regular files or character devices. 64 65After a successful return from register_appl(), CAPI messages from the 66application may be passed to the driver for the device via calls to the 67send_message() callback function. Conversely, the driver may call Kernel 68CAPI's capi_ctr_handle_message() function to pass a received CAPI message to 69Kernel CAPI for forwarding to an application, specifying its ApplID. 70 71Deregistration requests (CAPI operation CAPI_RELEASE) from applications are 72forwarded as calls to the release_appl() callback function, passing the same 73ApplID as with register_appl(). After return from release_appl(), no CAPI 74messages for that application may be passed to or from the device anymore. 75 76 774. Data Structures 78================== 79 804.1 struct capi_driver 81---------------------- 82 83This structure describes a Kernel CAPI driver itself. It is used in the 84register_capi_driver() and unregister_capi_driver() functions, and contains 85the following non-private fields, all to be set by the driver before calling 86register_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 964.2 struct capi_ctr 97------------------- 98 99This structure describes an ISDN device (controller) handled by a Kernel CAPI 100driver. After registration via the attach_capi_ctr() function it is passed to 101all controller specific lower layer interface and callback functions to 102identify the controller to operate on. 103 104It contains the following non-private fields: 105 106to 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 187Note: 188 Callback functions except send_message() are never called in interrupt 189 context. 190 191to 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 2074.3 SKBs 208-------- 209 210CAPI messages are passed between Kernel CAPI and the driver via send_message() 211and 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 213standard. 214 215For the data transfer messages, DATA_B3_REQ and DATA_B3_IND, the actual 216payload data immediately follows the CAPI message itself within the same skb. 217The Data and Data64 parameters are not used for processing. The Data64 218parameter may be omitted by setting the length field of the CAPI message to 22 219instead of 30. 220 221 2224.4 The _cmsg Structure 223----------------------- 224 225(declared in <linux/isdn/capiutil.h>) 226 227The _cmsg structure stores the contents of a CAPI 2.0 message in an easily 228accessible form. It contains members for all possible CAPI 2.0 parameters, 229including subparameters of the Additional Info and B Protocol structured 230parameters, 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 241Only those parameters appearing in the message type currently being processed 242are actually used. Unused members should be set to zero. 243 244Members are named after the CAPI 2.0 standard names of the parameters they 245represent. See <linux/isdn/capiutil.h> for the exact spelling. Member data 246types are: 247 248=========== ================================================================= 249u8 for CAPI parameters of type 'byte' 250 251u16 for CAPI parameters of type 'word' 252 253u32 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 270Functions capi_cmsg2message() and capi_message2cmsg() are provided to convert 271messages between their transport encoding described in the CAPI 2.0 standard 272and their _cmsg structure representation. Note that capi_cmsg2message() does 273not know or check the size of its destination buffer. The caller must make 274sure it is big enough to accommodate the resulting CAPI message. 275 276 2775. 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 287register/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 294register/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 301signal 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 308signal suspend/resume 309 310:: 311 312 void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid, 313 struct sk_buff *skb) 314 315pass a received CAPI message to Kernel CAPI 316for forwarding to the specified application 317 318 3196. Helper Functions and Macros 320============================== 321 322Library 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 337Macros to extract/set element values from/in a CAPI message header 338(from <linux/isdn/capiutil.h>): 339 340====================== ============================= ==================== 341Get Macro Set Macro Element (Type) 342====================== ============================= ==================== 343CAPIMSG_LEN(m) CAPIMSG_SETLEN(m, len) Total Length (u16) 344CAPIMSG_APPID(m) CAPIMSG_SETAPPID(m, applid) ApplID (u16) 345CAPIMSG_COMMAND(m) CAPIMSG_SETCOMMAND(m,cmd) Command (u8) 346CAPIMSG_SUBCOMMAND(m) CAPIMSG_SETSUBCOMMAND(m, cmd) Subcommand (u8) 347CAPIMSG_CMD(m) - Command*256 348 + Subcommand (u16) 349CAPIMSG_MSGID(m) CAPIMSG_SETMSGID(m, msgid) Message Number (u16) 350 351CAPIMSG_CONTROL(m) CAPIMSG_SETCONTROL(m, contr) Controller/PLCI/NCCI 352 (u32) 353CAPIMSG_DATALEN(m) CAPIMSG_SETDATALEN(m, len) Data Length (u16) 354====================== ============================= ==================== 355 356 357Library 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 3857. Debugging 386============ 387 388The module kernelcapi has a module parameter showcapimsgs controlling some 389debugging output produced by the module. It can only be set when the module is 390loaded, via a parameter "showcapimsgs=<n>" to the modprobe command, either on 391the command line or in the configuration file. 392 393If the lowest bit of showcapimsgs is set, kernelcapi logs controller and 394application up and down events. 395 396In addition, every registered CAPI controller has an associated traceflag 397parameter controlling how CAPI messages sent from and to tha controller are 398logged. The traceflag parameter is initialized with the value of the 399showcapimsgs parameter when the controller is registered, but can later be 400changed via the MANUFACTURER_REQ command KCAPI_CMD_TRACE. 401 402If the value of traceflag is non-zero, CAPI messages are logged. 403DATA_B3 messages are only logged if the value of traceflag is > 2. 404 405If the lowest bit of traceflag is set, only the command/subcommand and message 406length are logged. Otherwise, kernelcapi logs a readable representation of 407the entire message. 408