Root/Documentation/isdn/INTERFACE.CAPI

1Kernel CAPI Interface to Hardware Drivers
2-----------------------------------------
3
41. Overview
5
6From 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
11Kernel 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
20Format and semantics of CAPI messages are specified in the CAPI 2.0 standard.
21This standard is freely available from http://www.capi.org.
22
23
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
48driver has to call capi_ctr_down(). This will prevent further calls to the
49callback 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
63send_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.
66
67Deregistration 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]
83    the name of the driver, as a zero-terminated ASCII string
84char revision[32]
85    the revision number of the driver, as a zero-terminated ASCII string
86int (*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]
108    the name of the controller, as a zero-terminated ASCII string
109
110char *driver_name
111    the name of the driver, as a zero-terminated ASCII string
112
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
116    Return value: 0 on success, error code on error
117    Called in process context.
118
119void (*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
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
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
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
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
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
152const 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
158Note: Callback functions except send_message() are never called in interrupt
159context.
160
161- 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
1764.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
191
192(declared in <linux/isdn/capiutil.h>)
193
194The _cmsg structure stores the contents of a CAPI 2.0 message in an easily
195accessible 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.
210
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
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
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
2425. 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)
255void capi_ctr_down(struct capi_ctr *ctrlr)
256    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
300
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
329
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.
352

Archive Download this file



interactive