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