Commit | Line | Data |
---|---|---|
5a5e045b | 1 | ========================================= |
554f200e | 2 | Kernel CAPI Interface to Hardware Drivers |
5a5e045b | 3 | ========================================= |
554f200e TS |
4 | |
5 | 1. Overview | |
5a5e045b | 6 | =========== |
554f200e | 7 | |
2296e5a0 KK |
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 | ||
554f200e TS |
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 | ||
2296e5a0 | 22 | Format and semantics of CAPI messages are specified in the CAPI 2.0 standard. |
16e693c5 | 23 | This standard is freely available from https://www.capi.org. |
2296e5a0 | 24 | |
554f200e TS |
25 | |
26 | 2. Driver and Device Registration | |
5a5e045b | 27 | ================================= |
554f200e | 28 | |
554f200e TS |
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 | |
4e329972 | 44 | driver has to call capi_ctr_down(). This will prevent further calls to the |
554f200e TS |
45 | callback functions by Kernel CAPI. |
46 | ||
47 | ||
48 | 3. Application Registration and Communication | |
5a5e045b | 49 | ============================================= |
554f200e TS |
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 | |
f1af9f58 TS |
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. | |
554f200e | 63 | |
554f200e TS |
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 | |
5a5e045b | 71 | ================== |
554f200e TS |
72 | |
73 | 4.1 struct capi_driver | |
5a5e045b | 74 | ---------------------- |
554f200e TS |
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 | ||
5a5e045b | 81 | ``char name[32]`` |
2296e5a0 | 82 | the name of the driver, as a zero-terminated ASCII string |
5a5e045b | 83 | ``char revision[32]`` |
2296e5a0 | 84 | the revision number of the driver, as a zero-terminated ASCII string |
554f200e TS |
85 | |
86 | 4.2 struct capi_ctr | |
5a5e045b | 87 | ------------------- |
554f200e TS |
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 | ||
5a5e045b MCC |
96 | to be set by the driver before calling attach_capi_ctr(): |
97 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
554f200e | 98 | |
5a5e045b | 99 | ``struct module *owner`` |
554f200e TS |
100 | pointer to the driver module owning the device |
101 | ||
5a5e045b | 102 | ``void *driverdata`` |
554f200e TS |
103 | an opaque pointer to driver specific data, not touched by Kernel CAPI |
104 | ||
5a5e045b | 105 | ``char name[32]`` |
2296e5a0 | 106 | the name of the controller, as a zero-terminated ASCII string |
554f200e | 107 | |
5a5e045b | 108 | ``char *driver_name`` |
2296e5a0 | 109 | the name of the driver, as a zero-terminated ASCII string |
554f200e | 110 | |
5a5e045b | 111 | ``int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata)`` |
554f200e TS |
112 | (optional) pointer to a callback function for sending firmware and |
113 | configuration data to the device | |
5a5e045b | 114 | |
831334cb | 115 | The function may return before the operation has completed. |
5a5e045b | 116 | |
831334cb | 117 | Completion must be signalled by a call to capi_ctr_ready(). |
5a5e045b | 118 | |
fe93299a TS |
119 | Return value: 0 on success, error code on error |
120 | Called in process context. | |
554f200e | 121 | |
5a5e045b | 122 | ``void (*reset_ctr)(struct capi_ctr *ctrlr)`` |
831334cb TS |
123 | (optional) pointer to a callback function for stopping the device, |
124 | releasing all registered applications | |
5a5e045b | 125 | |
831334cb | 126 | The function may return before the operation has completed. |
5a5e045b | 127 | |
831334cb | 128 | Completion must be signalled by a call to capi_ctr_down(). |
5a5e045b | 129 | |
fe93299a | 130 | Called in process context. |
554f200e | 131 | |
5a5e045b MCC |
132 | ``void (*register_appl)(struct capi_ctr *ctrlr, u16 applid, capi_register_params *rparam)`` |
133 | pointers to callback function for registration of | |
554f200e | 134 | applications with the device |
5a5e045b | 135 | |
fe93299a TS |
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. | |
554f200e | 138 | |
5a5e045b MCC |
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)`` | |
554f200e TS |
147 | pointer to a callback function for sending a CAPI message to the |
148 | device | |
5a5e045b | 149 | |
fe93299a | 150 | Return value: CAPI error code |
5a5e045b | 151 | |
fe93299a TS |
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. | |
5a5e045b | 156 | |
fe93299a TS |
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. | |
5a5e045b | 161 | |
f1af9f58 | 162 | May be called in process or interrupt context. |
5a5e045b | 163 | |
fe93299a TS |
164 | Calls to this function are not serialized by Kernel CAPI, ie. it must |
165 | be prepared to be re-entered. | |
554f200e | 166 | |
5a5e045b | 167 | ``char *(*procinfo)(struct capi_ctr *ctrlr)`` |
554f200e TS |
168 | pointer to a callback function returning the entry for the device in |
169 | the CAPI controller info table, /proc/capi/controller | |
170 | ||
5a5e045b MCC |
171 | Note: |
172 | Callback functions except send_message() are never called in interrupt | |
173 | context. | |
fe93299a | 174 | |
5a5e045b MCC |
175 | to be filled in before calling capi_ctr_ready(): |
176 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
554f200e | 177 | |
5a5e045b | 178 | ``u8 manu[CAPI_MANUFACTURER_LEN]`` |
554f200e TS |
179 | value to return for CAPI_GET_MANUFACTURER |
180 | ||
5a5e045b | 181 | ``capi_version version`` |
554f200e TS |
182 | value to return for CAPI_GET_VERSION |
183 | ||
5a5e045b | 184 | ``capi_profile profile`` |
554f200e TS |
185 | value to return for CAPI_GET_PROFILE |
186 | ||
5a5e045b | 187 | ``u8 serial[CAPI_SERIAL_LEN]`` |
554f200e TS |
188 | value to return for CAPI_GET_SERIAL |
189 | ||
190 | ||
f1af9f58 | 191 | 4.3 SKBs |
5a5e045b | 192 | -------- |
f1af9f58 TS |
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 | |
5a5e045b | 207 | ----------------------- |
fe93299a TS |
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 | |
f1af9f58 TS |
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. | |
fe93299a TS |
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 | ||
5a5e045b | 232 | =========== ================================================================= |
fe93299a TS |
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 | ||
f1af9f58 | 239 | _cstruct for CAPI parameters of type 'struct' |
fe93299a TS |
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. | |
f1af9f58 | 243 | Subparameters are stored in encoded form within the content part. |
fe93299a | 244 | |
f1af9f58 TS |
245 | _cmstruct alternative representation for CAPI parameters of type 'struct' |
246 | (used only for the 'Additional Info' and 'B Protocol' parameters) | |
fe93299a | 247 | The representation is a single byte containing one of the values: |
f1af9f58 TS |
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. | |
5a5e045b | 252 | =========== ================================================================= |
fe93299a | 253 | |
fe93299a | 254 | |
554f200e | 255 | 5. Lower Layer Interface Functions |
5a5e045b | 256 | ================================== |
554f200e | 257 | |
5a5e045b MCC |
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 | |
554f200e | 264 | |
5a5e045b | 265 | :: |
554f200e | 266 | |
5a5e045b MCC |
267 | void capi_ctr_ready(struct capi_ctr *ctrlr) |
268 | void capi_ctr_down(struct capi_ctr *ctrlr) | |
554f200e | 269 | |
5a5e045b | 270 | signal controller ready/not ready |
554f200e | 271 | |
5a5e045b MCC |
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 | |
554f200e TS |
279 | |
280 | ||
281 | 6. Helper Functions and Macros | |
5a5e045b | 282 | ============================== |
554f200e | 283 | |
554f200e TS |
284 | Macros to extract/set element values from/in a CAPI message header |
285 | (from <linux/isdn/capiutil.h>): | |
286 | ||
5a5e045b | 287 | ====================== ============================= ==================== |
554f200e | 288 | Get Macro Set Macro Element (Type) |
5a5e045b | 289 | ====================== ============================= ==================== |
554f200e TS |
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) | |
5a5e045b | 301 | ====================== ============================= ==================== |
554f200e | 302 | |
fe93299a TS |
303 | |
304 | Library functions for working with _cmsg structures | |
305 | (from <linux/isdn/capiutil.h>): | |
306 | ||
5a5e045b | 307 | ``char *capi_cmd2str(u8 Command, u8 Subcommand)`` |
fe93299a TS |
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 | ||
f1af9f58 TS |
313 | |
314 | 7. Debugging | |
5a5e045b | 315 | ============ |
f1af9f58 TS |
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 | |
d12f9ad0 | 326 | parameter controlling how CAPI messages sent from and to the controller are |
f1af9f58 TS |
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. |