blob: f172091fb7cd4c592980a36272b2a61a4db71b7e [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 Schmidtf1af9f52009-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 Schmidtfe932992009-06-07 09:09:24 +0000116 Return value: 0 on success, error code on error
117 Called in process context.
Tilman Schmidt554f2002009-04-23 02:24:21 +0000118
119void (*reset_ctr)(struct capi_ctr *ctrlr)
Tilman Schmidtfe932992009-06-07 09:09:24 +0000120 (optional) pointer to a callback function for performing a reset on
121 the device, releasing all registered applications
122 Called in process context.
Tilman Schmidt554f2002009-04-23 02:24:21 +0000123
124void (*register_appl)(struct capi_ctr *ctrlr, u16 applid,
125 capi_register_params *rparam)
126void (*release_appl)(struct capi_ctr *ctrlr, u16 applid)
127 pointers to callback functions for registration and deregistration of
128 applications with the device
Tilman Schmidtfe932992009-06-07 09:09:24 +0000129 Calls to these functions are serialized by Kernel CAPI so that only
130 one call to any of them is active at any time.
Tilman Schmidt554f2002009-04-23 02:24:21 +0000131
132u16 (*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
Tilman Schmidtfe932992009-06-07 09:09:24 +0000135 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.
Tilman Schmidtf1af9f52009-10-06 12:18:00 +0000144 May be called in process or interrupt context.
Tilman Schmidtfe932992009-06-07 09:09:24 +0000145 Calls to this function are not serialized by Kernel CAPI, ie. it must
146 be prepared to be re-entered.
Tilman Schmidt554f2002009-04-23 02:24:21 +0000147
148char *(*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
Alexey Dobriyan9a58a802010-01-14 03:10:54 -0800152const 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.
Tilman Schmidt554f2002009-04-23 02:24:21 +0000157
Tilman Schmidtf1af9f52009-10-06 12:18:00 +0000158Note: Callback functions except send_message() are never called in interrupt
159context.
Tilman Schmidtfe932992009-06-07 09:09:24 +0000160
Tilman Schmidt554f2002009-04-23 02:24:21 +0000161- to be filled in before calling capi_ctr_ready():
162
163u8 manu[CAPI_MANUFACTURER_LEN]
164 value to return for CAPI_GET_MANUFACTURER
165
166capi_version version
167 value to return for CAPI_GET_VERSION
168
169capi_profile profile
170 value to return for CAPI_GET_PROFILE
171
172u8 serial[CAPI_SERIAL_LEN]
173 value to return for CAPI_GET_SERIAL
174
175
Tilman Schmidtf1af9f52009-10-06 12:18:00 +00001764.3 SKBs
177
178CAPI messages are passed between Kernel CAPI and the driver via send_message()
179and 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
181standard.
182
183For the data transfer messages, DATA_B3_REQ and DATA_B3_IND, the actual
184payload data immediately follows the CAPI message itself within the same skb.
185The Data and Data64 parameters are not used for processing. The Data64
186parameter may be omitted by setting the length field of the CAPI message to 22
187instead of 30.
188
189
1904.4 The _cmsg Structure
Tilman Schmidtfe932992009-06-07 09:09:24 +0000191
192(declared in <linux/isdn/capiutil.h>)
193
194The _cmsg structure stores the contents of a CAPI 2.0 message in an easily
Tilman Schmidtf1af9f52009-10-06 12:18:00 +0000195accessible form. It contains members for all possible CAPI 2.0 parameters,
196including subparameters of the Additional Info and B Protocol structured
197parameters, 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
208Only those parameters appearing in the message type currently being processed
209are actually used. Unused members should be set to zero.
Tilman Schmidtfe932992009-06-07 09:09:24 +0000210
211Members are named after the CAPI 2.0 standard names of the parameters they
212represent. See <linux/isdn/capiutil.h> for the exact spelling. Member data
213types are:
214
215u8 for CAPI parameters of type 'byte'
216
217u16 for CAPI parameters of type 'word'
218
219u32 for CAPI parameters of type 'dword'
220
Tilman Schmidtf1af9f52009-10-06 12:18:00 +0000221_cstruct for CAPI parameters of type 'struct'
Tilman Schmidtfe932992009-06-07 09:09:24 +0000222 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.
Tilman Schmidtf1af9f52009-10-06 12:18:00 +0000225 Subparameters are stored in encoded form within the content part.
Tilman Schmidtfe932992009-06-07 09:09:24 +0000226
Tilman Schmidtf1af9f52009-10-06 12:18:00 +0000227_cmstruct alternative representation for CAPI parameters of type 'struct'
228 (used only for the 'Additional Info' and 'B Protocol' parameters)
Tilman Schmidtfe932992009-06-07 09:09:24 +0000229 The representation is a single byte containing one of the values:
Tilman Schmidtf1af9f52009-10-06 12:18:00 +0000230 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.
Tilman Schmidtfe932992009-06-07 09:09:24 +0000234
235Functions capi_cmsg2message() and capi_message2cmsg() are provided to convert
236messages between their transport encoding described in the CAPI 2.0 standard
237and their _cmsg structure representation. Note that capi_cmsg2message() does
238not know or check the size of its destination buffer. The caller must make
239sure it is big enough to accomodate the resulting CAPI message.
240
241
Tilman Schmidt554f2002009-04-23 02:24:21 +00002425. Lower Layer Interface Functions
243
244(declared in <linux/isdn/capilli.h>)
245
246void register_capi_driver(struct capi_driver *drvr)
247void unregister_capi_driver(struct capi_driver *drvr)
248 register/unregister a driver with Kernel CAPI
249
250int attach_capi_ctr(struct capi_ctr *ctrlr)
251int detach_capi_ctr(struct capi_ctr *ctrlr)
252 register/unregister a device (controller) with Kernel CAPI
253
254void capi_ctr_ready(struct capi_ctr *ctrlr)
Tilman Schmidt4e329972009-06-07 09:09:23 +0000255void capi_ctr_down(struct capi_ctr *ctrlr)
Tilman Schmidt554f2002009-04-23 02:24:21 +0000256 signal controller ready/not ready
257
258void capi_ctr_suspend_output(struct capi_ctr *ctrlr)
259void capi_ctr_resume_output(struct capi_ctr *ctrlr)
260 signal suspend/resume
261
262void 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
2686. Helper Functions and Macros
269
270Library functions (from <linux/isdn/capilli.h>):
271
272void capilib_new_ncci(struct list_head *head, u16 applid,
273 u32 ncci, u32 winsize)
274void capilib_free_ncci(struct list_head *head, u16 applid, u32 ncci)
275void capilib_release_appl(struct list_head *head, u16 applid)
276void capilib_release(struct list_head *head)
277void capilib_data_b3_conf(struct list_head *head, u16 applid,
278 u32 ncci, u16 msgid)
279u16 capilib_data_b3_req(struct list_head *head, u16 applid,
280 u32 ncci, u16 msgid)
281
282
283Macros to extract/set element values from/in a CAPI message header
284(from <linux/isdn/capiutil.h>):
285
286Get Macro Set Macro Element (Type)
287
288CAPIMSG_LEN(m) CAPIMSG_SETLEN(m, len) Total Length (u16)
289CAPIMSG_APPID(m) CAPIMSG_SETAPPID(m, applid) ApplID (u16)
290CAPIMSG_COMMAND(m) CAPIMSG_SETCOMMAND(m,cmd) Command (u8)
291CAPIMSG_SUBCOMMAND(m) CAPIMSG_SETSUBCOMMAND(m, cmd) Subcommand (u8)
292CAPIMSG_CMD(m) - Command*256
293 + Subcommand (u16)
294CAPIMSG_MSGID(m) CAPIMSG_SETMSGID(m, msgid) Message Number (u16)
295
296CAPIMSG_CONTROL(m) CAPIMSG_SETCONTROL(m, contr) Controller/PLCI/NCCI
297 (u32)
298CAPIMSG_DATALEN(m) CAPIMSG_SETDATALEN(m, len) Data Length (u16)
299
Tilman Schmidtfe932992009-06-07 09:09:24 +0000300
301Library functions for working with _cmsg structures
302(from <linux/isdn/capiutil.h>):
303
304unsigned 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
308unsigned capi_message2cmsg(_cmsg *cmsg, u8 *msg)
309 Disassembles the CAPI 2.0 message in *msg, storing the parameters in
310 *cmsg.
311
312unsigned 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
319void 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
323char *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
Tilman Schmidtf1af9f52009-10-06 12:18:00 +0000329
3307. Debugging
331
332The module kernelcapi has a module parameter showcapimsgs controlling some
333debugging output produced by the module. It can only be set when the module is
334loaded, via a parameter "showcapimsgs=<n>" to the modprobe command, either on
335the command line or in the configuration file.
336
337If the lowest bit of showcapimsgs is set, kernelcapi logs controller and
338application up and down events.
339
340In addition, every registered CAPI controller has an associated traceflag
341parameter controlling how CAPI messages sent from and to tha controller are
342logged. The traceflag parameter is initialized with the value of the
343showcapimsgs parameter when the controller is registered, but can later be
344changed via the MANUFACTURER_REQ command KCAPI_CMD_TRACE.
345
346If the value of traceflag is non-zero, CAPI messages are logged.
347DATA_B3 messages are only logged if the value of traceflag is > 2.
348
349If the lowest bit of traceflag is set, only the command/subcommand and message
350length are logged. Otherwise, kernelcapi logs a readable representation of
351the entire message.