blob: 5fe8de5cc7275f768b3c1106c5276f56ab35e256 [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
152read_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
Tilman Schmidtf1af9f52009-10-06 12:18:00 +0000157Note: Callback functions except send_message() are never called in interrupt
158context.
Tilman Schmidtfe932992009-06-07 09:09:24 +0000159
Tilman Schmidt554f2002009-04-23 02:24:21 +0000160- to be filled in before calling capi_ctr_ready():
161
162u8 manu[CAPI_MANUFACTURER_LEN]
163 value to return for CAPI_GET_MANUFACTURER
164
165capi_version version
166 value to return for CAPI_GET_VERSION
167
168capi_profile profile
169 value to return for CAPI_GET_PROFILE
170
171u8 serial[CAPI_SERIAL_LEN]
172 value to return for CAPI_GET_SERIAL
173
174
Tilman Schmidtf1af9f52009-10-06 12:18:00 +00001754.3 SKBs
176
177CAPI messages are passed between Kernel CAPI and the driver via send_message()
178and capi_ctr_handle_message(), stored in the data portion of a socket buffer
179(skb). Each skb contains a single CAPI message coded according to the CAPI 2.0
180standard.
181
182For the data transfer messages, DATA_B3_REQ and DATA_B3_IND, the actual
183payload data immediately follows the CAPI message itself within the same skb.
184The Data and Data64 parameters are not used for processing. The Data64
185parameter may be omitted by setting the length field of the CAPI message to 22
186instead of 30.
187
188
1894.4 The _cmsg Structure
Tilman Schmidtfe932992009-06-07 09:09:24 +0000190
191(declared in <linux/isdn/capiutil.h>)
192
193The _cmsg structure stores the contents of a CAPI 2.0 message in an easily
Tilman Schmidtf1af9f52009-10-06 12:18:00 +0000194accessible form. It contains members for all possible CAPI 2.0 parameters,
195including subparameters of the Additional Info and B Protocol structured
196parameters, with the following exceptions:
197
198* second Calling party number (CONNECT_IND)
199
200* Data64 (DATA_B3_REQ and DATA_B3_IND)
201
202* Sending complete (subparameter of Additional Info, CONNECT_REQ and INFO_REQ)
203
204* Global Configuration (subparameter of B Protocol, CONNECT_REQ, CONNECT_RESP
205 and SELECT_B_PROTOCOL_REQ)
206
207Only those parameters appearing in the message type currently being processed
208are actually used. Unused members should be set to zero.
Tilman Schmidtfe932992009-06-07 09:09:24 +0000209
210Members are named after the CAPI 2.0 standard names of the parameters they
211represent. See <linux/isdn/capiutil.h> for the exact spelling. Member data
212types are:
213
214u8 for CAPI parameters of type 'byte'
215
216u16 for CAPI parameters of type 'word'
217
218u32 for CAPI parameters of type 'dword'
219
Tilman Schmidtf1af9f52009-10-06 12:18:00 +0000220_cstruct for CAPI parameters of type 'struct'
Tilman Schmidtfe932992009-06-07 09:09:24 +0000221 The member is a pointer to a buffer containing the parameter in
222 CAPI encoding (length + content). It may also be NULL, which will
223 be taken to represent an empty (zero length) parameter.
Tilman Schmidtf1af9f52009-10-06 12:18:00 +0000224 Subparameters are stored in encoded form within the content part.
Tilman Schmidtfe932992009-06-07 09:09:24 +0000225
Tilman Schmidtf1af9f52009-10-06 12:18:00 +0000226_cmstruct alternative representation for CAPI parameters of type 'struct'
227 (used only for the 'Additional Info' and 'B Protocol' parameters)
Tilman Schmidtfe932992009-06-07 09:09:24 +0000228 The representation is a single byte containing one of the values:
Tilman Schmidtf1af9f52009-10-06 12:18:00 +0000229 CAPI_DEFAULT: The parameter is empty/absent.
230 CAPI_COMPOSE: The parameter is present.
231 Subparameter values are stored individually in the corresponding
232 _cmsg structure members.
Tilman Schmidtfe932992009-06-07 09:09:24 +0000233
234Functions capi_cmsg2message() and capi_message2cmsg() are provided to convert
235messages between their transport encoding described in the CAPI 2.0 standard
236and their _cmsg structure representation. Note that capi_cmsg2message() does
237not know or check the size of its destination buffer. The caller must make
238sure it is big enough to accomodate the resulting CAPI message.
239
240
Tilman Schmidt554f2002009-04-23 02:24:21 +00002415. Lower Layer Interface Functions
242
243(declared in <linux/isdn/capilli.h>)
244
245void register_capi_driver(struct capi_driver *drvr)
246void unregister_capi_driver(struct capi_driver *drvr)
247 register/unregister a driver with Kernel CAPI
248
249int attach_capi_ctr(struct capi_ctr *ctrlr)
250int detach_capi_ctr(struct capi_ctr *ctrlr)
251 register/unregister a device (controller) with Kernel CAPI
252
253void capi_ctr_ready(struct capi_ctr *ctrlr)
Tilman Schmidt4e329972009-06-07 09:09:23 +0000254void capi_ctr_down(struct capi_ctr *ctrlr)
Tilman Schmidt554f2002009-04-23 02:24:21 +0000255 signal controller ready/not ready
256
257void capi_ctr_suspend_output(struct capi_ctr *ctrlr)
258void capi_ctr_resume_output(struct capi_ctr *ctrlr)
259 signal suspend/resume
260
261void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid,
262 struct sk_buff *skb)
263 pass a received CAPI message to Kernel CAPI
264 for forwarding to the specified application
265
266
2676. Helper Functions and Macros
268
269Library functions (from <linux/isdn/capilli.h>):
270
271void capilib_new_ncci(struct list_head *head, u16 applid,
272 u32 ncci, u32 winsize)
273void capilib_free_ncci(struct list_head *head, u16 applid, u32 ncci)
274void capilib_release_appl(struct list_head *head, u16 applid)
275void capilib_release(struct list_head *head)
276void capilib_data_b3_conf(struct list_head *head, u16 applid,
277 u32 ncci, u16 msgid)
278u16 capilib_data_b3_req(struct list_head *head, u16 applid,
279 u32 ncci, u16 msgid)
280
281
282Macros to extract/set element values from/in a CAPI message header
283(from <linux/isdn/capiutil.h>):
284
285Get Macro Set Macro Element (Type)
286
287CAPIMSG_LEN(m) CAPIMSG_SETLEN(m, len) Total Length (u16)
288CAPIMSG_APPID(m) CAPIMSG_SETAPPID(m, applid) ApplID (u16)
289CAPIMSG_COMMAND(m) CAPIMSG_SETCOMMAND(m,cmd) Command (u8)
290CAPIMSG_SUBCOMMAND(m) CAPIMSG_SETSUBCOMMAND(m, cmd) Subcommand (u8)
291CAPIMSG_CMD(m) - Command*256
292 + Subcommand (u16)
293CAPIMSG_MSGID(m) CAPIMSG_SETMSGID(m, msgid) Message Number (u16)
294
295CAPIMSG_CONTROL(m) CAPIMSG_SETCONTROL(m, contr) Controller/PLCI/NCCI
296 (u32)
297CAPIMSG_DATALEN(m) CAPIMSG_SETDATALEN(m, len) Data Length (u16)
298
Tilman Schmidtfe932992009-06-07 09:09:24 +0000299
300Library functions for working with _cmsg structures
301(from <linux/isdn/capiutil.h>):
302
303unsigned capi_cmsg2message(_cmsg *cmsg, u8 *msg)
304 Assembles a CAPI 2.0 message from the parameters in *cmsg, storing the
305 result in *msg.
306
307unsigned capi_message2cmsg(_cmsg *cmsg, u8 *msg)
308 Disassembles the CAPI 2.0 message in *msg, storing the parameters in
309 *cmsg.
310
311unsigned capi_cmsg_header(_cmsg *cmsg, u16 ApplId, u8 Command, u8 Subcommand,
312 u16 Messagenumber, u32 Controller)
313 Fills the header part and address field of the _cmsg structure *cmsg
314 with the given values, zeroing the remainder of the structure so only
315 parameters with non-default values need to be changed before sending
316 the message.
317
318void capi_cmsg_answer(_cmsg *cmsg)
319 Sets the low bit of the Subcommand field in *cmsg, thereby converting
320 _REQ to _CONF and _IND to _RESP.
321
322char *capi_cmd2str(u8 Command, u8 Subcommand)
323 Returns the CAPI 2.0 message name corresponding to the given command
324 and subcommand values, as a static ASCII string. The return value may
325 be NULL if the command/subcommand is not one of those defined in the
326 CAPI 2.0 standard.
327
Tilman Schmidtf1af9f52009-10-06 12:18:00 +0000328
3297. Debugging
330
331The module kernelcapi has a module parameter showcapimsgs controlling some
332debugging output produced by the module. It can only be set when the module is
333loaded, via a parameter "showcapimsgs=<n>" to the modprobe command, either on
334the command line or in the configuration file.
335
336If the lowest bit of showcapimsgs is set, kernelcapi logs controller and
337application up and down events.
338
339In addition, every registered CAPI controller has an associated traceflag
340parameter controlling how CAPI messages sent from and to tha controller are
341logged. The traceflag parameter is initialized with the value of the
342showcapimsgs parameter when the controller is registered, but can later be
343changed via the MANUFACTURER_REQ command KCAPI_CMD_TRACE.
344
345If the value of traceflag is non-zero, CAPI messages are logged.
346DATA_B3 messages are only logged if the value of traceflag is > 2.
347
348If the lowest bit of traceflag is set, only the command/subcommand and message
349length are logged. Otherwise, kernelcapi logs a readable representation of
350the entire message.