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.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.