GNU Linux-libre 4.19.211-gnu1
[releases.git] / Documentation / isdn / INTERFACE.CAPI
1 Kernel CAPI Interface to Hardware Drivers
2 -----------------------------------------
3
4 1. Overview
5
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
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
20 Format and semantics of CAPI messages are specified in the CAPI 2.0 standard.
21 This standard is freely available from https://www.capi.org.
22
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
48 driver has to call capi_ctr_down(). This will prevent further calls to the
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. Conversely, the driver may call Kernel
64 CAPI's capi_ctr_handle_message() function to pass a received CAPI message to
65 Kernel CAPI for forwarding to an application, specifying its ApplID.
66
67 Deregistration requests (CAPI operation CAPI_RELEASE) from applications are
68 forwarded as calls to the release_appl() callback function, passing the same
69 ApplID as with register_appl(). After return from release_appl(), no CAPI
70 messages for that application may be passed to or from the device anymore.
71
72
73 4. Data Structures
74
75 4.1 struct capi_driver
76
77 This structure describes a Kernel CAPI driver itself. It is used in the
78 register_capi_driver() and unregister_capi_driver() functions, and contains
79 the following non-private fields, all to be set by the driver before calling
80 register_capi_driver():
81
82 char name[32]
83         the name of the driver, as a zero-terminated ASCII string
84 char revision[32]
85         the revision number of the driver, as a zero-terminated ASCII string
86 int (*add_card)(struct capi_driver *driver, capicardparams *data)
87         a callback function pointer (may be NULL)
88
89
90 4.2 struct capi_ctr
91
92 This structure describes an ISDN device (controller) handled by a Kernel CAPI
93 driver. After registration via the attach_capi_ctr() function it is passed to
94 all controller specific lower layer interface and callback functions to
95 identify the controller to operate on.
96
97 It contains the following non-private fields:
98
99 - to be set by the driver before calling attach_capi_ctr():
100
101 struct module *owner
102         pointer to the driver module owning the device
103
104 void *driverdata
105         an opaque pointer to driver specific data, not touched by Kernel CAPI
106
107 char name[32]
108         the name of the controller, as a zero-terminated ASCII string
109
110 char *driver_name
111         the name of the driver, as a zero-terminated ASCII string
112
113 int (*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         The function may return before the operation has completed.
117         Completion must be signalled by a call to capi_ctr_ready().
118         Return value: 0 on success, error code on error
119         Called in process context.
120
121 void (*reset_ctr)(struct capi_ctr *ctrlr)
122         (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().
126         Called in process context.
127
128 void (*register_appl)(struct capi_ctr *ctrlr, u16 applid,
129                         capi_register_params *rparam)
130 void (*release_appl)(struct capi_ctr *ctrlr, u16 applid)
131         pointers to callback functions for registration and deregistration of
132         applications with the device
133         Calls to these functions are serialized by Kernel CAPI so that only
134         one call to any of them is active at any time.
135
136 u16  (*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
139         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.
148         May be called in process or interrupt context.
149         Calls to this function are not serialized by Kernel CAPI, ie. it must
150         be prepared to be re-entered.
151
152 char *(*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
156 const 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.
161
162 Note: Callback functions except send_message() are never called in interrupt
163 context.
164
165 - to be filled in before calling capi_ctr_ready():
166
167 u8 manu[CAPI_MANUFACTURER_LEN]
168         value to return for CAPI_GET_MANUFACTURER
169
170 capi_version version
171         value to return for CAPI_GET_VERSION
172
173 capi_profile profile
174         value to return for CAPI_GET_PROFILE
175
176 u8 serial[CAPI_SERIAL_LEN]
177         value to return for CAPI_GET_SERIAL
178
179
180 4.3 SKBs
181
182 CAPI messages are passed between Kernel CAPI and the driver via send_message()
183 and 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
185 standard.
186
187 For the data transfer messages, DATA_B3_REQ and DATA_B3_IND, the actual
188 payload data immediately follows the CAPI message itself within the same skb.
189 The Data and Data64 parameters are not used for processing. The Data64
190 parameter may be omitted by setting the length field of the CAPI message to 22
191 instead of 30.
192
193
194 4.4 The _cmsg Structure
195
196 (declared in <linux/isdn/capiutil.h>)
197
198 The _cmsg structure stores the contents of a CAPI 2.0 message in an easily
199 accessible form. It contains members for all possible CAPI 2.0 parameters,
200 including subparameters of the Additional Info and B Protocol structured
201 parameters, 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
212 Only those parameters appearing in the message type currently being processed
213 are actually used. Unused members should be set to zero.
214
215 Members are named after the CAPI 2.0 standard names of the parameters they
216 represent. See <linux/isdn/capiutil.h> for the exact spelling. Member data
217 types are:
218
219 u8          for CAPI parameters of type 'byte'
220
221 u16         for CAPI parameters of type 'word'
222
223 u32         for CAPI parameters of type 'dword'
224
225 _cstruct    for CAPI parameters of type 'struct'
226             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.
229             Subparameters are stored in encoded form within the content part.
230
231 _cmstruct   alternative representation for CAPI parameters of type 'struct'
232             (used only for the 'Additional Info' and 'B Protocol' parameters)
233             The representation is a single byte containing one of the values:
234             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.
238
239 Functions capi_cmsg2message() and capi_message2cmsg() are provided to convert
240 messages between their transport encoding described in the CAPI 2.0 standard
241 and their _cmsg structure representation. Note that capi_cmsg2message() does
242 not know or check the size of its destination buffer. The caller must make
243 sure it is big enough to accommodate the resulting CAPI message.
244
245
246 5. Lower Layer Interface Functions
247
248 (declared in <linux/isdn/capilli.h>)
249
250 void register_capi_driver(struct capi_driver *drvr)
251 void unregister_capi_driver(struct capi_driver *drvr)
252         register/unregister a driver with Kernel CAPI
253
254 int attach_capi_ctr(struct capi_ctr *ctrlr)
255 int detach_capi_ctr(struct capi_ctr *ctrlr)
256         register/unregister a device (controller) with Kernel CAPI
257
258 void capi_ctr_ready(struct capi_ctr *ctrlr)
259 void capi_ctr_down(struct capi_ctr *ctrlr)
260         signal controller ready/not ready
261
262 void capi_ctr_suspend_output(struct capi_ctr *ctrlr)
263 void capi_ctr_resume_output(struct capi_ctr *ctrlr)
264         signal suspend/resume
265
266 void 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
272 6. Helper Functions and Macros
273
274 Library functions (from <linux/isdn/capilli.h>):
275
276 void capilib_new_ncci(struct list_head *head, u16 applid,
277                         u32 ncci, u32 winsize)
278 void capilib_free_ncci(struct list_head *head, u16 applid, u32 ncci)
279 void capilib_release_appl(struct list_head *head, u16 applid)
280 void capilib_release(struct list_head *head)
281 void capilib_data_b3_conf(struct list_head *head, u16 applid,
282                         u32 ncci, u16 msgid)
283 u16  capilib_data_b3_req(struct list_head *head, u16 applid,
284                         u32 ncci, u16 msgid)
285
286
287 Macros to extract/set element values from/in a CAPI message header
288 (from <linux/isdn/capiutil.h>):
289
290 Get Macro               Set Macro                       Element (Type)
291
292 CAPIMSG_LEN(m)          CAPIMSG_SETLEN(m, len)          Total Length (u16)
293 CAPIMSG_APPID(m)        CAPIMSG_SETAPPID(m, applid)     ApplID (u16)
294 CAPIMSG_COMMAND(m)      CAPIMSG_SETCOMMAND(m,cmd)       Command (u8)
295 CAPIMSG_SUBCOMMAND(m)   CAPIMSG_SETSUBCOMMAND(m, cmd)   Subcommand (u8)
296 CAPIMSG_CMD(m)          -                               Command*256
297                                                         + Subcommand (u16)
298 CAPIMSG_MSGID(m)        CAPIMSG_SETMSGID(m, msgid)      Message Number (u16)
299
300 CAPIMSG_CONTROL(m)      CAPIMSG_SETCONTROL(m, contr)    Controller/PLCI/NCCI
301                                                         (u32)
302 CAPIMSG_DATALEN(m)      CAPIMSG_SETDATALEN(m, len)      Data Length (u16)
303
304
305 Library functions for working with _cmsg structures
306 (from <linux/isdn/capiutil.h>):
307
308 unsigned 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
312 unsigned capi_message2cmsg(_cmsg *cmsg, u8 *msg)
313         Disassembles the CAPI 2.0 message in *msg, storing the parameters in
314         *cmsg.
315
316 unsigned 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
323 void 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
327 char *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
333
334 7. Debugging
335
336 The module kernelcapi has a module parameter showcapimsgs controlling some
337 debugging output produced by the module. It can only be set when the module is
338 loaded, via a parameter "showcapimsgs=<n>" to the modprobe command, either on
339 the command line or in the configuration file.
340
341 If the lowest bit of showcapimsgs is set, kernelcapi logs controller and
342 application up and down events.
343
344 In addition, every registered CAPI controller has an associated traceflag
345 parameter controlling how CAPI messages sent from and to tha controller are
346 logged. The traceflag parameter is initialized with the value of the
347 showcapimsgs parameter when the controller is registered, but can later be
348 changed via the MANUFACTURER_REQ command KCAPI_CMD_TRACE.
349
350 If the value of traceflag is non-zero, CAPI messages are logged.
351 DATA_B3 messages are only logged if the value of traceflag is > 2.
352
353 If the lowest bit of traceflag is set, only the command/subcommand and message
354 length are logged. Otherwise, kernelcapi logs a readable representation of
355 the entire message.