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