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