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 progr
10 to access ISDN equipment connected to basic ra
11 rate interfaces (PRI).
12
13 Kernel CAPI operates as a dispatching layer be
14 hardware drivers. Hardware drivers register IS
15 lingo) with Kernel CAPI to indicate their read
16 to CAPI applications. CAPI applications also r
17 requesting association with a CAPI device. Ker
18 application registration to an available devic
19 corresponding hardware driver. Kernel CAPI the
20 directions between the application and the har
21
22 Format and semantics of CAPI messages are spec
23 This standard is freely available from https:/
24
25
26 2. Driver and Device Registration
27 =================================
28
29 CAPI drivers must register each of the ISDN de
30 CAPI by calling the Kernel CAPI function attac
31 struct capi_ctr before they can be used. This
32 the names of the driver and controller, and a
33 pointers which are subsequently used by Kernel
34 driver. The registration can be revoked by cal
35 detach_capi_ctr() with a pointer to the same s
36
37 Before the device can be actually used, the dr
38 information fields 'manu', 'version', 'profile
39 structure of the device, and signal its readin
40 From then on, Kernel CAPI may call the registe
41 device.
42
43 If the device becomes unusable for any reason
44 driver has to call capi_ctr_down(). This will
45 callback functions by Kernel CAPI.
46
47
48 3. Application Registration and Communication
49 =============================================
50
51 Kernel CAPI forwards registration requests fro
52 operation CAPI_REGISTER) to an appropriate har
53 register_appl() callback function. A unique Ap
54 allocated by Kernel CAPI and passed to registe
55 parameter structure provided by the applicatio
56 open() operation on regular files or character
57
58 After a successful return from register_appl()
59 application may be passed to the driver for th
60 send_message() callback function. Conversely,
61 CAPI's capi_ctr_handle_message() function to p
62 Kernel CAPI for forwarding to an application,
63
64 Deregistration requests (CAPI operation CAPI_R
65 forwarded as calls to the release_appl() callb
66 ApplID as with register_appl(). After return f
67 messages for that application may be passed to
68
69
70 4. Data Structures
71 ==================
72
73 4.1 struct capi_driver
74 ----------------------
75
76 This structure describes a Kernel CAPI driver
77 register_capi_driver() and unregister_capi_dri
78 the following non-private fields, all to be se
79 register_capi_driver():
80
81 ``char name[32]``
82 the name of the driver, as a zero-term
83 ``char revision[32]``
84 the revision number of the driver, as
85
86 4.2 struct capi_ctr
87 -------------------
88
89 This structure describes an ISDN device (contr
90 driver. After registration via the attach_capi
91 all controller specific lower layer interface
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_
97 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
98
99 ``struct module *owner``
100 pointer to the driver module owning th
101
102 ``void *driverdata``
103 an opaque pointer to driver specific d
104
105 ``char name[32]``
106 the name of the controller, as a zero-
107
108 ``char *driver_name``
109 the name of the driver, as a zero-term
110
111 ``int (*load_firmware)(struct capi_ctr *ctrlr,
112 (optional) pointer to a callback funct
113 configuration data to the device
114
115 The function may return before the ope
116
117 Completion must be signalled by a call
118
119 Return value: 0 on success, error code
120 Called in process context.
121
122 ``void (*reset_ctr)(struct capi_ctr *ctrlr)``
123 (optional) pointer to a callback funct
124 releasing all registered applications
125
126 The function may return before the ope
127
128 Completion must be signalled by a call
129
130 Called in process context.
131
132 ``void (*register_appl)(struct capi_ctr *ctrlr
133 pointers to callback function for regi
134 applications with the device
135
136 Calls to these functions are serialize
137 one call to any of them is active at a
138
139 ``void (*release_appl)(struct capi_ctr *ctrlr,
140 pointers to callback functions deregis
141 applications with the device
142
143 Calls to these functions are serialize
144 one call to any of them is active at a
145
146 ``u16 (*send_message)(struct capi_ctr *ctrlr,
147 pointer to a callback function for sen
148 device
149
150 Return value: CAPI error code
151
152 If the method returns 0 (CAPI_NOERROR)
153 of the skb and the caller may no longe
154 non-zero (error) value then ownership
155 who may reuse or free it.
156
157 The return value should only be used t
158 to accepting or queueing the message.
159 actual processing of the message shoul
160 appropriate reply message.
161
162 May be called in process or interrupt
163
164 Calls to this function are not seriali
165 be prepared to be re-entered.
166
167 ``char *(*procinfo)(struct capi_ctr *ctrlr)``
168 pointer to a callback function returni
169 the CAPI controller info table, /proc/
170
171 Note:
172 Callback functions except send_message() are
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_MANUFACTU
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 a
195 and capi_ctr_handle_message(), stored in the d
196 (skb). Each skb contains a single CAPI messag
197 standard.
198
199 For the data transfer messages, DATA_B3_REQ an
200 payload data immediately follows the CAPI mess
201 The Data and Data64 parameters are not used fo
202 parameter may be omitted by setting the length
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 C
212 accessible form. It contains members for all p
213 including subparameters of the Additional Info
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
221
222 * Global Configuration (subparameter of B Prot
223 and SELECT_B_PROTOCOL_REQ)
224
225 Only those parameters appearing in the message
226 are actually used. Unused members should be se
227
228 Members are named after the CAPI 2.0 standard
229 represent. See <linux/isdn/capiutil.h> for the
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 'struc
240 The member is a pointer to a buffe
241 CAPI encoding (length + content).
242 be taken to represent an empty (ze
243 Subparameters are stored in encode
244
245 _cmstruct alternative representation for CAP
246 (used only for the 'Additional Inf
247 The representation is a single byt
248 CAPI_DEFAULT: The parameter is emp
249 CAPI_COMPOSE: The parameter is pre
250 Subparameter values are stored ind
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
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
275 struct sk_buff
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
285 (from <linux/isdn/capiutil.h>):
286
287 ====================== ======================
288 Get Macro Set Macro
289 ====================== ======================
290 CAPIMSG_LEN(m) CAPIMSG_SETLEN(m, len)
291 CAPIMSG_APPID(m) CAPIMSG_SETAPPID(m, ap
292 CAPIMSG_COMMAND(m) CAPIMSG_SETCOMMAND(m,c
293 CAPIMSG_SUBCOMMAND(m) CAPIMSG_SETSUBCOMMAND(
294 CAPIMSG_CMD(m) -
295
296 CAPIMSG_MSGID(m) CAPIMSG_SETMSGID(m, ms
297
298 CAPIMSG_CONTROL(m) CAPIMSG_SETCONTROL(m,
299
300 CAPIMSG_DATALEN(m) CAPIMSG_SETDATALEN(m,
301 ====================== ======================
302
303
304 Library functions for working with _cmsg struc
305 (from <linux/isdn/capiutil.h>):
306
307 ``char *capi_cmd2str(u8 Command, u8 Subcommand
308 Returns the CAPI 2.0 message name corr
309 and subcommand values, as a static ASC
310 be NULL if the command/subcommand is n
311 CAPI 2.0 standard.
312
313
314 7. Debugging
315 ============
316
317 The module kernelcapi has a module parameter s
318 debugging output produced by the module. It ca
319 loaded, via a parameter "showcapimsgs=<n>" to
320 the command line or in the configuration file.
321
322 If the lowest bit of showcapimsgs is set, kern
323 application up and down events.
324
325 In addition, every registered CAPI controller
326 parameter controlling how CAPI messages sent f
327 logged. The traceflag parameter is initialized
328 showcapimsgs parameter when the controller is
329 changed via the MANUFACTURER_REQ command KCAPI
330
331 If the value of traceflag is non-zero, CAPI me
332 DATA_B3 messages are only logged if the value
333
334 If the lowest bit of traceflag is set, only th
335 length are logged. Otherwise, kernelcapi logs
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.