blob: 1688b5a1fd77ac1de87ae4822713d02a9164b0bf [file] [log] [blame]
Tilman Schmidt554f2002009-04-23 02:24:21 +00001Kernel CAPI Interface to Hardware Drivers
2-----------------------------------------
3
41. Overview
5
Karsten Keil2296e5a2009-04-23 02:24:21 +00006From the CAPI 2.0 specification:
7COMMON-ISDN-API (CAPI) is an application programming interface standard used
8to access ISDN equipment connected to basic rate interfaces (BRI) and primary
9rate interfaces (PRI).
10
Tilman Schmidt554f2002009-04-23 02:24:21 +000011Kernel CAPI operates as a dispatching layer between CAPI applications and CAPI
12hardware drivers. Hardware drivers register ISDN devices (controllers, in CAPI
13lingo) with Kernel CAPI to indicate their readiness to provide their service
14to CAPI applications. CAPI applications also register with Kernel CAPI,
15requesting association with a CAPI device. Kernel CAPI then dispatches the
16application registration to an available device, forwarding it to the
17corresponding hardware driver. Kernel CAPI then forwards CAPI messages in both
18directions between the application and the hardware driver.
19
Karsten Keil2296e5a2009-04-23 02:24:21 +000020Format and semantics of CAPI messages are specified in the CAPI 2.0 standard.
21This standard is freely available from http://www.capi.org.
22
Tilman Schmidt554f2002009-04-23 02:24:21 +000023
242. Driver and Device Registration
25
26CAPI drivers optionally register themselves with Kernel CAPI by calling the
27Kernel CAPI function register_capi_driver() with a pointer to a struct
28capi_driver. This structure must be filled with the name and revision of the
29driver, and optionally a pointer to a callback function, add_card(). The
30registration can be revoked by calling the function unregister_capi_driver()
31with a pointer to the same struct capi_driver.
32
33CAPI drivers must register each of the ISDN devices they control with Kernel
34CAPI by calling the Kernel CAPI function attach_capi_ctr() with a pointer to a
35struct capi_ctr before they can be used. This structure must be filled with
36the names of the driver and controller, and a number of callback function
37pointers which are subsequently used by Kernel CAPI for communicating with the
38driver. The registration can be revoked by calling the function
39detach_capi_ctr() with a pointer to the same struct capi_ctr.
40
41Before the device can be actually used, the driver must fill in the device
42information fields 'manu', 'version', 'profile' and 'serial' in the capi_ctr
43structure of the device, and signal its readiness by calling capi_ctr_ready().
44From then on, Kernel CAPI may call the registered callback functions for the
45device.
46
47If the device becomes unusable for any reason (shutdown, disconnect ...), the
Tilman Schmidt4e329972009-06-07 09:09:23 +000048driver has to call capi_ctr_down(). This will prevent further calls to the
Tilman Schmidt554f2002009-04-23 02:24:21 +000049callback functions by Kernel CAPI.
50
51
523. Application Registration and Communication
53
54Kernel CAPI forwards registration requests from applications (calls to CAPI
55operation CAPI_REGISTER) to an appropriate hardware driver by calling its
56register_appl() callback function. A unique Application ID (ApplID, u16) is
57allocated by Kernel CAPI and passed to register_appl() along with the
58parameter structure provided by the application. This is analogous to the
59open() operation on regular files or character devices.
60
61After a successful return from register_appl(), CAPI messages from the
62application may be passed to the driver for the device via calls to the
Tilman Schmidtf1af9f582009-10-06 12:18:00 +000063send_message() callback function. Conversely, the driver may call Kernel
64CAPI's capi_ctr_handle_message() function to pass a received CAPI message to
65Kernel CAPI for forwarding to an application, specifying its ApplID.
Tilman Schmidt554f2002009-04-23 02:24:21 +000066
Tilman Schmidt554f2002009-04-23 02:24:21 +000067Deregistration requests (CAPI operation CAPI_RELEASE) from applications are
68forwarded as calls to the release_appl() callback function, passing the same
69ApplID as with register_appl(). After return from release_appl(), no CAPI
70messages for that application may be passed to or from the device anymore.
71
72
734. Data Structures
74
754.1 struct capi_driver
76
77This structure describes a Kernel CAPI driver itself. It is used in the
78register_capi_driver() and unregister_capi_driver() functions, and contains
79the following non-private fields, all to be set by the driver before calling
80register_capi_driver():
81
82char name[32]
Karsten Keil2296e5a2009-04-23 02:24:21 +000083 the name of the driver, as a zero-terminated ASCII string
Tilman Schmidt554f2002009-04-23 02:24:21 +000084char revision[32]
Karsten Keil2296e5a2009-04-23 02:24:21 +000085 the revision number of the driver, as a zero-terminated ASCII string
Tilman Schmidt554f2002009-04-23 02:24:21 +000086int (*add_card)(struct capi_driver *driver, capicardparams *data)
87 a callback function pointer (may be NULL)
88
89
904.2 struct capi_ctr
91
92This structure describes an ISDN device (controller) handled by a Kernel CAPI
93driver. After registration via the attach_capi_ctr() function it is passed to
94all controller specific lower layer interface and callback functions to
95identify the controller to operate on.
96
97It contains the following non-private fields:
98
99- to be set by the driver before calling attach_capi_ctr():
100
101struct module *owner
102 pointer to the driver module owning the device
103
104void *driverdata
105 an opaque pointer to driver specific data, not touched by Kernel CAPI
106
107char name[32]
Karsten Keil2296e5a2009-04-23 02:24:21 +0000108 the name of the controller, as a zero-terminated ASCII string
Tilman Schmidt554f2002009-04-23 02:24:21 +0000109
110char *driver_name
Karsten Keil2296e5a2009-04-23 02:24:21 +0000111 the name of the driver, as a zero-terminated ASCII string
Tilman Schmidt554f2002009-04-23 02:24:21 +0000112
113int (*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
Tilman Schmidt831334c2010-07-05 14:18:22 +0000116 The function may return before the operation has completed.
117 Completion must be signalled by a call to capi_ctr_ready().
Tilman Schmidtfe932992009-06-07 09:09:24 +0000118 Return value: 0 on success, error code on error
119 Called in process context.
Tilman Schmidt554f2002009-04-23 02:24:21 +0000120
121void (*reset_ctr)(struct capi_ctr *ctrlr)
Tilman Schmidt831334c2010-07-05 14:18:22 +0000122 (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().
Tilman Schmidtfe932992009-06-07 09:09:24 +0000126 Called in process context.
Tilman Schmidt554f2002009-04-23 02:24:21 +0000127
128void (*register_appl)(struct capi_ctr *ctrlr, u16 applid,
129 capi_register_params *rparam)
130void (*release_appl)(struct capi_ctr *ctrlr, u16 applid)
131 pointers to callback functions for registration and deregistration of
132 applications with the device
Tilman Schmidtfe932992009-06-07 09:09:24 +0000133 Calls to these functions are serialized by Kernel CAPI so that only
134 one call to any of them is active at any time.
Tilman Schmidt554f2002009-04-23 02:24:21 +0000135
136u16 (*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
Tilman Schmidtfe932992009-06-07 09:09:24 +0000139 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.
Tilman Schmidtf1af9f582009-10-06 12:18:00 +0000148 May be called in process or interrupt context.
Tilman Schmidtfe932992009-06-07 09:09:24 +0000149 Calls to this function are not serialized by Kernel CAPI, ie. it must
150 be prepared to be re-entered.
Tilman Schmidt554f2002009-04-23 02:24:21 +0000151
152char *(*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
Alexey Dobriyan9a58a802010-01-14 03:10:54 -0800156const 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.
Tilman Schmidt554f2002009-04-23 02:24:21 +0000161
Tilman Schmidtf1af9f582009-10-06 12:18:00 +0000162Note: Callback functions except send_message() are never called in interrupt
163context.
Tilman Schmidtfe932992009-06-07 09:09:24 +0000164
Tilman Schmidt554f2002009-04-23 02:24:21 +0000165- to be filled in before calling capi_ctr_ready():
166
167u8 manu[CAPI_MANUFACTURER_LEN]
168 value to return for CAPI_GET_MANUFACTURER
169
170capi_version version
171 value to return for CAPI_GET_VERSION
172
173capi_profile profile
174 value to return for CAPI_GET_PROFILE
175
176u8 serial[CAPI_SERIAL_LEN]
177 value to return for CAPI_GET_SERIAL
178
179
Tilman Schmidtf1af9f582009-10-06 12:18:00 +00001804.3 SKBs
181
182CAPI messages are passed between Kernel CAPI and the driver via send_message()
183and 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
185standard.
186
187For the data transfer messages, DATA_B3_REQ and DATA_B3_IND, the actual
188payload data immediately follows the CAPI message itself within the same skb.
189The Data and Data64 parameters are not used for processing. The Data64
190parameter may be omitted by setting the length field of the CAPI message to 22
191instead of 30.
192
193
1944.4 The _cmsg Structure
Tilman Schmidtfe932992009-06-07 09:09:24 +0000195
196(declared in <linux/isdn/capiutil.h>)
197
198The _cmsg structure stores the contents of a CAPI 2.0 message in an easily
Tilman Schmidtf1af9f582009-10-06 12:18:00 +0000199accessible form. It contains members for all possible CAPI 2.0 parameters,
200including subparameters of the Additional Info and B Protocol structured
201parameters, 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
212Only those parameters appearing in the message type currently being processed
213are actually used. Unused members should be set to zero.
Tilman Schmidtfe932992009-06-07 09:09:24 +0000214
215Members are named after the CAPI 2.0 standard names of the parameters they
216represent. See <linux/isdn/capiutil.h> for the exact spelling. Member data
217types are:
218
219u8 for CAPI parameters of type 'byte'
220
221u16 for CAPI parameters of type 'word'
222
223u32 for CAPI parameters of type 'dword'
224
Tilman Schmidtf1af9f582009-10-06 12:18:00 +0000225_cstruct for CAPI parameters of type 'struct'
Tilman Schmidtfe932992009-06-07 09:09:24 +0000226 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.
Tilman Schmidtf1af9f582009-10-06 12:18:00 +0000229 Subparameters are stored in encoded form within the content part.
Tilman Schmidtfe932992009-06-07 09:09:24 +0000230
Tilman Schmidtf1af9f582009-10-06 12:18:00 +0000231_cmstruct alternative representation for CAPI parameters of type 'struct'
232 (used only for the 'Additional Info' and 'B Protocol' parameters)
Tilman Schmidtfe932992009-06-07 09:09:24 +0000233 The representation is a single byte containing one of the values:
Tilman Schmidtf1af9f582009-10-06 12:18:00 +0000234 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.
Tilman Schmidtfe932992009-06-07 09:09:24 +0000238
239Functions capi_cmsg2message() and capi_message2cmsg() are provided to convert
240messages between their transport encoding described in the CAPI 2.0 standard
241and their _cmsg structure representation. Note that capi_cmsg2message() does
242not know or check the size of its destination buffer. The caller must make
Lucas De Marchi25985ed2011-03-30 22:57:33 -0300243sure it is big enough to accommodate the resulting CAPI message.
Tilman Schmidtfe932992009-06-07 09:09:24 +0000244
245
Tilman Schmidt554f2002009-04-23 02:24:21 +00002465. Lower Layer Interface Functions
247
248(declared in <linux/isdn/capilli.h>)
249
250void register_capi_driver(struct capi_driver *drvr)
251void unregister_capi_driver(struct capi_driver *drvr)
252 register/unregister a driver with Kernel CAPI
253
254int attach_capi_ctr(struct capi_ctr *ctrlr)
255int detach_capi_ctr(struct capi_ctr *ctrlr)
256 register/unregister a device (controller) with Kernel CAPI
257
258void capi_ctr_ready(struct capi_ctr *ctrlr)
Tilman Schmidt4e329972009-06-07 09:09:23 +0000259void capi_ctr_down(struct capi_ctr *ctrlr)
Tilman Schmidt554f2002009-04-23 02:24:21 +0000260 signal controller ready/not ready
261
262void capi_ctr_suspend_output(struct capi_ctr *ctrlr)
263void capi_ctr_resume_output(struct capi_ctr *ctrlr)
264 signal suspend/resume
265
266void 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
2726. Helper Functions and Macros
273
274Library functions (from <linux/isdn/capilli.h>):
275
276void capilib_new_ncci(struct list_head *head, u16 applid,
277 u32 ncci, u32 winsize)
278void capilib_free_ncci(struct list_head *head, u16 applid, u32 ncci)
279void capilib_release_appl(struct list_head *head, u16 applid)
280void capilib_release(struct list_head *head)
281void capilib_data_b3_conf(struct list_head *head, u16 applid,
282 u32 ncci, u16 msgid)
283u16 capilib_data_b3_req(struct list_head *head, u16 applid,
284 u32 ncci, u16 msgid)
285
286
287Macros to extract/set element values from/in a CAPI message header
288(from <linux/isdn/capiutil.h>):
289
290Get Macro Set Macro Element (Type)
291
292CAPIMSG_LEN(m) CAPIMSG_SETLEN(m, len) Total Length (u16)
293CAPIMSG_APPID(m) CAPIMSG_SETAPPID(m, applid) ApplID (u16)
294CAPIMSG_COMMAND(m) CAPIMSG_SETCOMMAND(m,cmd) Command (u8)
295CAPIMSG_SUBCOMMAND(m) CAPIMSG_SETSUBCOMMAND(m, cmd) Subcommand (u8)
296CAPIMSG_CMD(m) - Command*256
297 + Subcommand (u16)
298CAPIMSG_MSGID(m) CAPIMSG_SETMSGID(m, msgid) Message Number (u16)
299
300CAPIMSG_CONTROL(m) CAPIMSG_SETCONTROL(m, contr) Controller/PLCI/NCCI
301 (u32)
302CAPIMSG_DATALEN(m) CAPIMSG_SETDATALEN(m, len) Data Length (u16)
303
Tilman Schmidtfe932992009-06-07 09:09:24 +0000304
305Library functions for working with _cmsg structures
306(from <linux/isdn/capiutil.h>):
307
308unsigned 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
312unsigned capi_message2cmsg(_cmsg *cmsg, u8 *msg)
313 Disassembles the CAPI 2.0 message in *msg, storing the parameters in
314 *cmsg.
315
316unsigned 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
323void 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
327char *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
Tilman Schmidtf1af9f582009-10-06 12:18:00 +0000333
3347. Debugging
335
336The module kernelcapi has a module parameter showcapimsgs controlling some
337debugging output produced by the module. It can only be set when the module is
338loaded, via a parameter "showcapimsgs=<n>" to the modprobe command, either on
339the command line or in the configuration file.
340
341If the lowest bit of showcapimsgs is set, kernelcapi logs controller and
342application up and down events.
343
344In addition, every registered CAPI controller has an associated traceflag
345parameter controlling how CAPI messages sent from and to tha controller are
346logged. The traceflag parameter is initialized with the value of the
347showcapimsgs parameter when the controller is registered, but can later be
348changed via the MANUFACTURER_REQ command KCAPI_CMD_TRACE.
349
350If the value of traceflag is non-zero, CAPI messages are logged.
351DATA_B3 messages are only logged if the value of traceflag is > 2.
352
353If the lowest bit of traceflag is set, only the command/subcommand and message
354length are logged. Otherwise, kernelcapi logs a readable representation of
355the entire message.