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