Commit | Line | Data |
---|---|---|
554f200e TS |
1 | Kernel CAPI Interface to Hardware Drivers |
2 | ----------------------------------------- | |
3 | ||
4 | 1. Overview | |
5 | ||
2296e5a0 KK |
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 | ||
554f200e TS |
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 | ||
2296e5a0 KK |
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 | ||
554f200e TS |
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 | |
4e329972 | 48 | driver has to call capi_ctr_down(). This will prevent further calls to the |
554f200e TS |
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. The CAPI message to send is stored in the | |
2296e5a0 | 64 | data portion of an skb. Conversely, the driver may call Kernel CAPI's |
554f200e TS |
65 | capi_ctr_handle_message() function to pass a received CAPI message to Kernel |
66 | CAPI for forwarding to an application, specifying its ApplID. | |
67 | ||
554f200e TS |
68 | Deregistration requests (CAPI operation CAPI_RELEASE) from applications are |
69 | forwarded as calls to the release_appl() callback function, passing the same | |
70 | ApplID as with register_appl(). After return from release_appl(), no CAPI | |
71 | messages for that application may be passed to or from the device anymore. | |
72 | ||
73 | ||
74 | 4. Data Structures | |
75 | ||
76 | 4.1 struct capi_driver | |
77 | ||
78 | This structure describes a Kernel CAPI driver itself. It is used in the | |
79 | register_capi_driver() and unregister_capi_driver() functions, and contains | |
80 | the following non-private fields, all to be set by the driver before calling | |
81 | register_capi_driver(): | |
82 | ||
83 | char name[32] | |
2296e5a0 | 84 | the name of the driver, as a zero-terminated ASCII string |
554f200e | 85 | char revision[32] |
2296e5a0 | 86 | the revision number of the driver, as a zero-terminated ASCII string |
554f200e TS |
87 | int (*add_card)(struct capi_driver *driver, capicardparams *data) |
88 | a callback function pointer (may be NULL) | |
89 | ||
90 | ||
91 | 4.2 struct capi_ctr | |
92 | ||
93 | This structure describes an ISDN device (controller) handled by a Kernel CAPI | |
94 | driver. After registration via the attach_capi_ctr() function it is passed to | |
95 | all controller specific lower layer interface and callback functions to | |
96 | identify the controller to operate on. | |
97 | ||
98 | It contains the following non-private fields: | |
99 | ||
100 | - to be set by the driver before calling attach_capi_ctr(): | |
101 | ||
102 | struct module *owner | |
103 | pointer to the driver module owning the device | |
104 | ||
105 | void *driverdata | |
106 | an opaque pointer to driver specific data, not touched by Kernel CAPI | |
107 | ||
108 | char name[32] | |
2296e5a0 | 109 | the name of the controller, as a zero-terminated ASCII string |
554f200e TS |
110 | |
111 | char *driver_name | |
2296e5a0 | 112 | the name of the driver, as a zero-terminated ASCII string |
554f200e TS |
113 | |
114 | int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata) | |
115 | (optional) pointer to a callback function for sending firmware and | |
116 | configuration data to the device | |
fe93299a TS |
117 | Return value: 0 on success, error code on error |
118 | Called in process context. | |
554f200e TS |
119 | |
120 | void (*reset_ctr)(struct capi_ctr *ctrlr) | |
fe93299a TS |
121 | (optional) pointer to a callback function for performing a reset on |
122 | the device, releasing all registered applications | |
123 | Called in process context. | |
554f200e TS |
124 | |
125 | void (*register_appl)(struct capi_ctr *ctrlr, u16 applid, | |
126 | capi_register_params *rparam) | |
127 | void (*release_appl)(struct capi_ctr *ctrlr, u16 applid) | |
128 | pointers to callback functions for registration and deregistration of | |
129 | applications with the device | |
fe93299a TS |
130 | Calls to these functions are serialized by Kernel CAPI so that only |
131 | one call to any of them is active at any time. | |
554f200e TS |
132 | |
133 | u16 (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb) | |
134 | pointer to a callback function for sending a CAPI message to the | |
135 | device | |
fe93299a TS |
136 | Return value: CAPI error code |
137 | If the method returns 0 (CAPI_NOERROR) the driver has taken ownership | |
138 | of the skb and the caller may no longer access it. If it returns a | |
139 | non-zero (error) value then ownership of the skb returns to the caller | |
140 | who may reuse or free it. | |
141 | The return value should only be used to signal problems with respect | |
142 | to accepting or queueing the message. Errors occurring during the | |
143 | actual processing of the message should be signaled with an | |
144 | appropriate reply message. | |
145 | Calls to this function are not serialized by Kernel CAPI, ie. it must | |
146 | be prepared to be re-entered. | |
554f200e TS |
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 | read_proc_t *ctr_read_proc | |
153 | pointer to the read_proc callback function for the device's proc file | |
154 | system entry, /proc/capi/controllers/<n>; will be called with a | |
155 | pointer to the device's capi_ctr structure as the last (data) argument | |
156 | ||
fe93299a TS |
157 | Note: Callback functions are never called in interrupt context. |
158 | ||
554f200e TS |
159 | - to be filled in before calling capi_ctr_ready(): |
160 | ||
161 | u8 manu[CAPI_MANUFACTURER_LEN] | |
162 | value to return for CAPI_GET_MANUFACTURER | |
163 | ||
164 | capi_version version | |
165 | value to return for CAPI_GET_VERSION | |
166 | ||
167 | capi_profile profile | |
168 | value to return for CAPI_GET_PROFILE | |
169 | ||
170 | u8 serial[CAPI_SERIAL_LEN] | |
171 | value to return for CAPI_GET_SERIAL | |
172 | ||
173 | ||
fe93299a TS |
174 | 4.3 The _cmsg Structure |
175 | ||
176 | (declared in <linux/isdn/capiutil.h>) | |
177 | ||
178 | The _cmsg structure stores the contents of a CAPI 2.0 message in an easily | |
179 | accessible form. It contains members for all possible CAPI 2.0 parameters, of | |
180 | which only those appearing in the message type currently being processed are | |
181 | actually used. Unused members should be set to zero. | |
182 | ||
183 | Members are named after the CAPI 2.0 standard names of the parameters they | |
184 | represent. See <linux/isdn/capiutil.h> for the exact spelling. Member data | |
185 | types are: | |
186 | ||
187 | u8 for CAPI parameters of type 'byte' | |
188 | ||
189 | u16 for CAPI parameters of type 'word' | |
190 | ||
191 | u32 for CAPI parameters of type 'dword' | |
192 | ||
193 | _cstruct for CAPI parameters of type 'struct' not containing any | |
194 | variably-sized (struct) subparameters (eg. 'Called Party Number') | |
195 | The member is a pointer to a buffer containing the parameter in | |
196 | CAPI encoding (length + content). It may also be NULL, which will | |
197 | be taken to represent an empty (zero length) parameter. | |
198 | ||
199 | _cmstruct for CAPI parameters of type 'struct' containing 'struct' | |
200 | subparameters ('Additional Info' and 'B Protocol') | |
201 | The representation is a single byte containing one of the values: | |
202 | CAPI_DEFAULT: the parameter is empty | |
203 | CAPI_COMPOSE: the values of the subparameters are stored | |
204 | individually in the corresponding _cmsg structure members | |
205 | ||
206 | Functions capi_cmsg2message() and capi_message2cmsg() are provided to convert | |
207 | messages between their transport encoding described in the CAPI 2.0 standard | |
208 | and their _cmsg structure representation. Note that capi_cmsg2message() does | |
209 | not know or check the size of its destination buffer. The caller must make | |
210 | sure it is big enough to accomodate the resulting CAPI message. | |
211 | ||
212 | ||
554f200e TS |
213 | 5. Lower Layer Interface Functions |
214 | ||
215 | (declared in <linux/isdn/capilli.h>) | |
216 | ||
217 | void register_capi_driver(struct capi_driver *drvr) | |
218 | void unregister_capi_driver(struct capi_driver *drvr) | |
219 | register/unregister a driver with Kernel CAPI | |
220 | ||
221 | int attach_capi_ctr(struct capi_ctr *ctrlr) | |
222 | int detach_capi_ctr(struct capi_ctr *ctrlr) | |
223 | register/unregister a device (controller) with Kernel CAPI | |
224 | ||
225 | void capi_ctr_ready(struct capi_ctr *ctrlr) | |
4e329972 | 226 | void capi_ctr_down(struct capi_ctr *ctrlr) |
554f200e TS |
227 | signal controller ready/not ready |
228 | ||
229 | void capi_ctr_suspend_output(struct capi_ctr *ctrlr) | |
230 | void capi_ctr_resume_output(struct capi_ctr *ctrlr) | |
231 | signal suspend/resume | |
232 | ||
233 | void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid, | |
234 | struct sk_buff *skb) | |
235 | pass a received CAPI message to Kernel CAPI | |
236 | for forwarding to the specified application | |
237 | ||
238 | ||
239 | 6. Helper Functions and Macros | |
240 | ||
241 | Library functions (from <linux/isdn/capilli.h>): | |
242 | ||
243 | void capilib_new_ncci(struct list_head *head, u16 applid, | |
244 | u32 ncci, u32 winsize) | |
245 | void capilib_free_ncci(struct list_head *head, u16 applid, u32 ncci) | |
246 | void capilib_release_appl(struct list_head *head, u16 applid) | |
247 | void capilib_release(struct list_head *head) | |
248 | void capilib_data_b3_conf(struct list_head *head, u16 applid, | |
249 | u32 ncci, u16 msgid) | |
250 | u16 capilib_data_b3_req(struct list_head *head, u16 applid, | |
251 | u32 ncci, u16 msgid) | |
252 | ||
253 | ||
254 | Macros to extract/set element values from/in a CAPI message header | |
255 | (from <linux/isdn/capiutil.h>): | |
256 | ||
257 | Get Macro Set Macro Element (Type) | |
258 | ||
259 | CAPIMSG_LEN(m) CAPIMSG_SETLEN(m, len) Total Length (u16) | |
260 | CAPIMSG_APPID(m) CAPIMSG_SETAPPID(m, applid) ApplID (u16) | |
261 | CAPIMSG_COMMAND(m) CAPIMSG_SETCOMMAND(m,cmd) Command (u8) | |
262 | CAPIMSG_SUBCOMMAND(m) CAPIMSG_SETSUBCOMMAND(m, cmd) Subcommand (u8) | |
263 | CAPIMSG_CMD(m) - Command*256 | |
264 | + Subcommand (u16) | |
265 | CAPIMSG_MSGID(m) CAPIMSG_SETMSGID(m, msgid) Message Number (u16) | |
266 | ||
267 | CAPIMSG_CONTROL(m) CAPIMSG_SETCONTROL(m, contr) Controller/PLCI/NCCI | |
268 | (u32) | |
269 | CAPIMSG_DATALEN(m) CAPIMSG_SETDATALEN(m, len) Data Length (u16) | |
270 | ||
fe93299a TS |
271 | |
272 | Library functions for working with _cmsg structures | |
273 | (from <linux/isdn/capiutil.h>): | |
274 | ||
275 | unsigned capi_cmsg2message(_cmsg *cmsg, u8 *msg) | |
276 | Assembles a CAPI 2.0 message from the parameters in *cmsg, storing the | |
277 | result in *msg. | |
278 | ||
279 | unsigned capi_message2cmsg(_cmsg *cmsg, u8 *msg) | |
280 | Disassembles the CAPI 2.0 message in *msg, storing the parameters in | |
281 | *cmsg. | |
282 | ||
283 | unsigned capi_cmsg_header(_cmsg *cmsg, u16 ApplId, u8 Command, u8 Subcommand, | |
284 | u16 Messagenumber, u32 Controller) | |
285 | Fills the header part and address field of the _cmsg structure *cmsg | |
286 | with the given values, zeroing the remainder of the structure so only | |
287 | parameters with non-default values need to be changed before sending | |
288 | the message. | |
289 | ||
290 | void capi_cmsg_answer(_cmsg *cmsg) | |
291 | Sets the low bit of the Subcommand field in *cmsg, thereby converting | |
292 | _REQ to _CONF and _IND to _RESP. | |
293 | ||
294 | char *capi_cmd2str(u8 Command, u8 Subcommand) | |
295 | Returns the CAPI 2.0 message name corresponding to the given command | |
296 | and subcommand values, as a static ASCII string. The return value may | |
297 | be NULL if the command/subcommand is not one of those defined in the | |
298 | CAPI 2.0 standard. | |
299 |