Root/
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 | Return value: 0 on success, error code on error |
117 | Called in process context. |
118 | |
119 | void (*reset_ctr)(struct capi_ctr *ctrlr) |
120 | (optional) pointer to a callback function for performing a reset on |
121 | the device, releasing all registered applications |
122 | Called in process context. |
123 | |
124 | void (*register_appl)(struct capi_ctr *ctrlr, u16 applid, |
125 | capi_register_params *rparam) |
126 | void (*release_appl)(struct capi_ctr *ctrlr, u16 applid) |
127 | pointers to callback functions for registration and deregistration of |
128 | applications with the device |
129 | Calls to these functions are serialized by Kernel CAPI so that only |
130 | one call to any of them is active at any time. |
131 | |
132 | u16 (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb) |
133 | pointer to a callback function for sending a CAPI message to the |
134 | device |
135 | Return value: CAPI error code |
136 | If the method returns 0 (CAPI_NOERROR) the driver has taken ownership |
137 | of the skb and the caller may no longer access it. If it returns a |
138 | non-zero (error) value then ownership of the skb returns to the caller |
139 | who may reuse or free it. |
140 | The return value should only be used to signal problems with respect |
141 | to accepting or queueing the message. Errors occurring during the |
142 | actual processing of the message should be signaled with an |
143 | appropriate reply message. |
144 | May be called in process or interrupt context. |
145 | Calls to this function are not serialized by Kernel CAPI, ie. it must |
146 | be prepared to be re-entered. |
147 | |
148 | char *(*procinfo)(struct capi_ctr *ctrlr) |
149 | pointer to a callback function returning the entry for the device in |
150 | the CAPI controller info table, /proc/capi/controller |
151 | |
152 | const struct file_operations *proc_fops |
153 | pointers to callback functions for the device's proc file |
154 | system entry, /proc/capi/controllers/<n>; pointer to the device's |
155 | capi_ctr structure is available from struct proc_dir_entry::data |
156 | which is available from struct inode. |
157 | |
158 | Note: Callback functions except send_message() are never called in interrupt |
159 | context. |
160 | |
161 | - to be filled in before calling capi_ctr_ready(): |
162 | |
163 | u8 manu[CAPI_MANUFACTURER_LEN] |
164 | value to return for CAPI_GET_MANUFACTURER |
165 | |
166 | capi_version version |
167 | value to return for CAPI_GET_VERSION |
168 | |
169 | capi_profile profile |
170 | value to return for CAPI_GET_PROFILE |
171 | |
172 | u8 serial[CAPI_SERIAL_LEN] |
173 | value to return for CAPI_GET_SERIAL |
174 | |
175 | |
176 | 4.3 SKBs |
177 | |
178 | CAPI messages are passed between Kernel CAPI and the driver via send_message() |
179 | and capi_ctr_handle_message(), stored in the data portion of a socket buffer |
180 | (skb). Each skb contains a single CAPI message coded according to the CAPI 2.0 |
181 | standard. |
182 | |
183 | For the data transfer messages, DATA_B3_REQ and DATA_B3_IND, the actual |
184 | payload data immediately follows the CAPI message itself within the same skb. |
185 | The Data and Data64 parameters are not used for processing. The Data64 |
186 | parameter may be omitted by setting the length field of the CAPI message to 22 |
187 | instead of 30. |
188 | |
189 | |
190 | 4.4 The _cmsg Structure |
191 | |
192 | (declared in <linux/isdn/capiutil.h>) |
193 | |
194 | The _cmsg structure stores the contents of a CAPI 2.0 message in an easily |
195 | accessible form. It contains members for all possible CAPI 2.0 parameters, |
196 | including subparameters of the Additional Info and B Protocol structured |
197 | parameters, with the following exceptions: |
198 | |
199 | * second Calling party number (CONNECT_IND) |
200 | |
201 | * Data64 (DATA_B3_REQ and DATA_B3_IND) |
202 | |
203 | * Sending complete (subparameter of Additional Info, CONNECT_REQ and INFO_REQ) |
204 | |
205 | * Global Configuration (subparameter of B Protocol, CONNECT_REQ, CONNECT_RESP |
206 | and SELECT_B_PROTOCOL_REQ) |
207 | |
208 | Only those parameters appearing in the message type currently being processed |
209 | are actually used. Unused members should be set to zero. |
210 | |
211 | Members are named after the CAPI 2.0 standard names of the parameters they |
212 | represent. See <linux/isdn/capiutil.h> for the exact spelling. Member data |
213 | types are: |
214 | |
215 | u8 for CAPI parameters of type 'byte' |
216 | |
217 | u16 for CAPI parameters of type 'word' |
218 | |
219 | u32 for CAPI parameters of type 'dword' |
220 | |
221 | _cstruct for CAPI parameters of type 'struct' |
222 | The member is a pointer to a buffer containing the parameter in |
223 | CAPI encoding (length + content). It may also be NULL, which will |
224 | be taken to represent an empty (zero length) parameter. |
225 | Subparameters are stored in encoded form within the content part. |
226 | |
227 | _cmstruct alternative representation for CAPI parameters of type 'struct' |
228 | (used only for the 'Additional Info' and 'B Protocol' parameters) |
229 | The representation is a single byte containing one of the values: |
230 | CAPI_DEFAULT: The parameter is empty/absent. |
231 | CAPI_COMPOSE: The parameter is present. |
232 | Subparameter values are stored individually in the corresponding |
233 | _cmsg structure members. |
234 | |
235 | Functions capi_cmsg2message() and capi_message2cmsg() are provided to convert |
236 | messages between their transport encoding described in the CAPI 2.0 standard |
237 | and their _cmsg structure representation. Note that capi_cmsg2message() does |
238 | not know or check the size of its destination buffer. The caller must make |
239 | sure it is big enough to accomodate the resulting CAPI message. |
240 | |
241 | |
242 | 5. Lower Layer Interface Functions |
243 | |
244 | (declared in <linux/isdn/capilli.h>) |
245 | |
246 | void register_capi_driver(struct capi_driver *drvr) |
247 | void unregister_capi_driver(struct capi_driver *drvr) |
248 | register/unregister a driver with Kernel CAPI |
249 | |
250 | int attach_capi_ctr(struct capi_ctr *ctrlr) |
251 | int detach_capi_ctr(struct capi_ctr *ctrlr) |
252 | register/unregister a device (controller) with Kernel CAPI |
253 | |
254 | void capi_ctr_ready(struct capi_ctr *ctrlr) |
255 | void capi_ctr_down(struct capi_ctr *ctrlr) |
256 | signal controller ready/not ready |
257 | |
258 | void capi_ctr_suspend_output(struct capi_ctr *ctrlr) |
259 | void capi_ctr_resume_output(struct capi_ctr *ctrlr) |
260 | signal suspend/resume |
261 | |
262 | void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid, |
263 | struct sk_buff *skb) |
264 | pass a received CAPI message to Kernel CAPI |
265 | for forwarding to the specified application |
266 | |
267 | |
268 | 6. Helper Functions and Macros |
269 | |
270 | Library functions (from <linux/isdn/capilli.h>): |
271 | |
272 | void capilib_new_ncci(struct list_head *head, u16 applid, |
273 | u32 ncci, u32 winsize) |
274 | void capilib_free_ncci(struct list_head *head, u16 applid, u32 ncci) |
275 | void capilib_release_appl(struct list_head *head, u16 applid) |
276 | void capilib_release(struct list_head *head) |
277 | void capilib_data_b3_conf(struct list_head *head, u16 applid, |
278 | u32 ncci, u16 msgid) |
279 | u16 capilib_data_b3_req(struct list_head *head, u16 applid, |
280 | u32 ncci, u16 msgid) |
281 | |
282 | |
283 | Macros to extract/set element values from/in a CAPI message header |
284 | (from <linux/isdn/capiutil.h>): |
285 | |
286 | Get Macro Set Macro Element (Type) |
287 | |
288 | CAPIMSG_LEN(m) CAPIMSG_SETLEN(m, len) Total Length (u16) |
289 | CAPIMSG_APPID(m) CAPIMSG_SETAPPID(m, applid) ApplID (u16) |
290 | CAPIMSG_COMMAND(m) CAPIMSG_SETCOMMAND(m,cmd) Command (u8) |
291 | CAPIMSG_SUBCOMMAND(m) CAPIMSG_SETSUBCOMMAND(m, cmd) Subcommand (u8) |
292 | CAPIMSG_CMD(m) - Command*256 |
293 | + Subcommand (u16) |
294 | CAPIMSG_MSGID(m) CAPIMSG_SETMSGID(m, msgid) Message Number (u16) |
295 | |
296 | CAPIMSG_CONTROL(m) CAPIMSG_SETCONTROL(m, contr) Controller/PLCI/NCCI |
297 | (u32) |
298 | CAPIMSG_DATALEN(m) CAPIMSG_SETDATALEN(m, len) Data Length (u16) |
299 | |
300 | |
301 | Library functions for working with _cmsg structures |
302 | (from <linux/isdn/capiutil.h>): |
303 | |
304 | unsigned capi_cmsg2message(_cmsg *cmsg, u8 *msg) |
305 | Assembles a CAPI 2.0 message from the parameters in *cmsg, storing the |
306 | result in *msg. |
307 | |
308 | unsigned capi_message2cmsg(_cmsg *cmsg, u8 *msg) |
309 | Disassembles the CAPI 2.0 message in *msg, storing the parameters in |
310 | *cmsg. |
311 | |
312 | unsigned capi_cmsg_header(_cmsg *cmsg, u16 ApplId, u8 Command, u8 Subcommand, |
313 | u16 Messagenumber, u32 Controller) |
314 | Fills the header part and address field of the _cmsg structure *cmsg |
315 | with the given values, zeroing the remainder of the structure so only |
316 | parameters with non-default values need to be changed before sending |
317 | the message. |
318 | |
319 | void capi_cmsg_answer(_cmsg *cmsg) |
320 | Sets the low bit of the Subcommand field in *cmsg, thereby converting |
321 | _REQ to _CONF and _IND to _RESP. |
322 | |
323 | char *capi_cmd2str(u8 Command, u8 Subcommand) |
324 | Returns the CAPI 2.0 message name corresponding to the given command |
325 | and subcommand values, as a static ASCII string. The return value may |
326 | be NULL if the command/subcommand is not one of those defined in the |
327 | CAPI 2.0 standard. |
328 | |
329 | |
330 | 7. Debugging |
331 | |
332 | The module kernelcapi has a module parameter showcapimsgs controlling some |
333 | debugging output produced by the module. It can only be set when the module is |
334 | loaded, via a parameter "showcapimsgs=<n>" to the modprobe command, either on |
335 | the command line or in the configuration file. |
336 | |
337 | If the lowest bit of showcapimsgs is set, kernelcapi logs controller and |
338 | application up and down events. |
339 | |
340 | In addition, every registered CAPI controller has an associated traceflag |
341 | parameter controlling how CAPI messages sent from and to tha controller are |
342 | logged. The traceflag parameter is initialized with the value of the |
343 | showcapimsgs parameter when the controller is registered, but can later be |
344 | changed via the MANUFACTURER_REQ command KCAPI_CMD_TRACE. |
345 | |
346 | If the value of traceflag is non-zero, CAPI messages are logged. |
347 | DATA_B3 messages are only logged if the value of traceflag is > 2. |
348 | |
349 | If the lowest bit of traceflag is set, only the command/subcommand and message |
350 | length are logged. Otherwise, kernelcapi logs a readable representation of |
351 | the entire message. |
352 |
Branches:
ben-wpan
ben-wpan-stefan
javiroman/ks7010
jz-2.6.34
jz-2.6.34-rc5
jz-2.6.34-rc6
jz-2.6.34-rc7
jz-2.6.35
jz-2.6.36
jz-2.6.37
jz-2.6.38
jz-2.6.39
jz-3.0
jz-3.1
jz-3.11
jz-3.12
jz-3.13
jz-3.15
jz-3.16
jz-3.18-dt
jz-3.2
jz-3.3
jz-3.4
jz-3.5
jz-3.6
jz-3.6-rc2-pwm
jz-3.9
jz-3.9-clk
jz-3.9-rc8
jz47xx
jz47xx-2.6.38
master
Tags:
od-2011-09-04
od-2011-09-18
v2.6.34-rc5
v2.6.34-rc6
v2.6.34-rc7
v3.9