1=========================================
2Kernel CAPI Interface to Hardware Drivers
3=========================================
4
51. Overview
6===========
7
8From the CAPI 2.0 specification:
9COMMON-ISDN-API (CAPI) is an application programming interface standard used
10to access ISDN equipment connected to basic rate interfaces (BRI) and primary
11rate interfaces (PRI).
12
13Kernel CAPI operates as a dispatching layer between CAPI applications and CAPI
14hardware drivers. Hardware drivers register ISDN devices (controllers, in CAPI
15lingo) with Kernel CAPI to indicate their readiness to provide their service
16to CAPI applications. CAPI applications also register with Kernel CAPI,
17requesting association with a CAPI device. Kernel CAPI then dispatches the
18application registration to an available device, forwarding it to the
19corresponding hardware driver. Kernel CAPI then forwards CAPI messages in both
20directions between the application and the hardware driver.
21
22Format and semantics of CAPI messages are specified in the CAPI 2.0 standard.
23This standard is freely available from https://www.capi.org.
24
25
262. Driver and Device Registration
27=================================
28
29CAPI drivers must register each of the ISDN devices they control with Kernel
30CAPI by calling the Kernel CAPI function attach_capi_ctr() with a pointer to a
31struct capi_ctr before they can be used. This structure must be filled with
32the names of the driver and controller, and a number of callback function
33pointers which are subsequently used by Kernel CAPI for communicating with the
34driver. The registration can be revoked by calling the function
35detach_capi_ctr() with a pointer to the same struct capi_ctr.
36
37Before the device can be actually used, the driver must fill in the device
38information fields 'manu', 'version', 'profile' and 'serial' in the capi_ctr
39structure of the device, and signal its readiness by calling capi_ctr_ready().
40From then on, Kernel CAPI may call the registered callback functions for the
41device.
42
43If the device becomes unusable for any reason (shutdown, disconnect ...), the
44driver has to call capi_ctr_down(). This will prevent further calls to the
45callback functions by Kernel CAPI.
46
47
483. Application Registration and Communication
49=============================================
50
51Kernel CAPI forwards registration requests from applications (calls to CAPI
52operation CAPI_REGISTER) to an appropriate hardware driver by calling its
53register_appl() callback function. A unique Application ID (ApplID, u16) is
54allocated by Kernel CAPI and passed to register_appl() along with the
55parameter structure provided by the application. This is analogous to the
56open() operation on regular files or character devices.
57
58After a successful return from register_appl(), CAPI messages from the
59application may be passed to the driver for the device via calls to the
60send_message() callback function. Conversely, the driver may call Kernel
61CAPI's capi_ctr_handle_message() function to pass a received CAPI message to
62Kernel CAPI for forwarding to an application, specifying its ApplID.
63
64Deregistration requests (CAPI operation CAPI_RELEASE) from applications are
65forwarded as calls to the release_appl() callback function, passing the same
66ApplID as with register_appl(). After return from release_appl(), no CAPI
67messages for that application may be passed to or from the device anymore.
68
69
704. Data Structures
71==================
72
734.1 struct capi_driver
74----------------------
75
76This structure describes a Kernel CAPI driver itself. It is used in the
77register_capi_driver() and unregister_capi_driver() functions, and contains
78the following non-private fields, all to be set by the driver before calling
79register_capi_driver():
80
81``char name[32]``
82	the name of the driver, as a zero-terminated ASCII string
83``char revision[32]``
84	the revision number of the driver, as a zero-terminated ASCII string
85
864.2 struct capi_ctr
87-------------------
88
89This structure describes an ISDN device (controller) handled by a Kernel CAPI
90driver. After registration via the attach_capi_ctr() function it is passed to
91all controller specific lower layer interface and callback functions to
92identify the controller to operate on.
93
94It contains the following non-private fields:
95
96to be set by the driver before calling attach_capi_ctr():
97^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
98
99``struct module *owner``
100	pointer to the driver module owning the device
101
102``void *driverdata``
103	an opaque pointer to driver specific data, not touched by Kernel CAPI
104
105``char name[32]``
106	the name of the controller, as a zero-terminated ASCII string
107
108``char *driver_name``
109	the name of the driver, as a zero-terminated ASCII string
110
111``int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata)``
112	(optional) pointer to a callback function for sending firmware and
113	configuration data to the device
114
115	The function may return before the operation has completed.
116
117	Completion must be signalled by a call to capi_ctr_ready().
118
119	Return value: 0 on success, error code on error
120	Called in process context.
121
122``void (*reset_ctr)(struct capi_ctr *ctrlr)``
123	(optional) pointer to a callback function for stopping the device,
124	releasing all registered applications
125
126	The function may return before the operation has completed.
127
128	Completion must be signalled by a call to capi_ctr_down().
129
130	Called in process context.
131
132``void (*register_appl)(struct capi_ctr *ctrlr, u16 applid, capi_register_params *rparam)``
133	pointers to callback function for registration of
134	applications with the device
135
136	Calls to these functions are serialized by Kernel CAPI so that only
137	one call to any of them is active at any time.
138
139``void (*release_appl)(struct capi_ctr *ctrlr, u16 applid)``
140	pointers to callback functions deregistration of
141	applications with the device
142
143	Calls to these functions are serialized by Kernel CAPI so that only
144	one call to any of them is active at any time.
145
146``u16  (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb)``
147	pointer to a callback function for sending a CAPI message to the
148	device
149
150	Return value: CAPI error code
151
152	If the method returns 0 (CAPI_NOERROR) the driver has taken ownership
153	of the skb and the caller may no longer access it. If it returns a
154	non-zero (error) value then ownership of the skb returns to the caller
155	who may reuse or free it.
156
157	The return value should only be used to signal problems with respect
158	to accepting or queueing the message. Errors occurring during the
159	actual processing of the message should be signaled with an
160	appropriate reply message.
161
162	May be called in process or interrupt context.
163
164	Calls to this function are not serialized by Kernel CAPI, ie. it must
165	be prepared to be re-entered.
166
167``char *(*procinfo)(struct capi_ctr *ctrlr)``
168	pointer to a callback function returning the entry for the device in
169	the CAPI controller info table, /proc/capi/controller
170
171Note:
172  Callback functions except send_message() are never called in interrupt
173  context.
174
175to be filled in before calling capi_ctr_ready():
176^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
177
178``u8 manu[CAPI_MANUFACTURER_LEN]``
179	value to return for CAPI_GET_MANUFACTURER
180
181``capi_version version``
182	value to return for CAPI_GET_VERSION
183
184``capi_profile profile``
185	value to return for CAPI_GET_PROFILE
186
187``u8 serial[CAPI_SERIAL_LEN]``
188	value to return for CAPI_GET_SERIAL
189
190
1914.3 SKBs
192--------
193
194CAPI messages are passed between Kernel CAPI and the driver via send_message()
195and capi_ctr_handle_message(), stored in the data portion of a socket buffer
196(skb).  Each skb contains a single CAPI message coded according to the CAPI 2.0
197standard.
198
199For the data transfer messages, DATA_B3_REQ and DATA_B3_IND, the actual
200payload data immediately follows the CAPI message itself within the same skb.
201The Data and Data64 parameters are not used for processing. The Data64
202parameter may be omitted by setting the length field of the CAPI message to 22
203instead of 30.
204
205
2064.4 The _cmsg Structure
207-----------------------
208
209(declared in <linux/isdn/capiutil.h>)
210
211The _cmsg structure stores the contents of a CAPI 2.0 message in an easily
212accessible form. It contains members for all possible CAPI 2.0 parameters,
213including subparameters of the Additional Info and B Protocol structured
214parameters, with the following exceptions:
215
216* second Calling party number (CONNECT_IND)
217
218* Data64 (DATA_B3_REQ and DATA_B3_IND)
219
220* Sending complete (subparameter of Additional Info, CONNECT_REQ and INFO_REQ)
221
222* Global Configuration (subparameter of B Protocol, CONNECT_REQ, CONNECT_RESP
223  and SELECT_B_PROTOCOL_REQ)
224
225Only those parameters appearing in the message type currently being processed
226are actually used. Unused members should be set to zero.
227
228Members are named after the CAPI 2.0 standard names of the parameters they
229represent. See <linux/isdn/capiutil.h> for the exact spelling. Member data
230types are:
231
232=========== =================================================================
233u8          for CAPI parameters of type 'byte'
234
235u16         for CAPI parameters of type 'word'
236
237u32         for CAPI parameters of type 'dword'
238
239_cstruct    for CAPI parameters of type 'struct'
240	    The member is a pointer to a buffer containing the parameter in
241	    CAPI encoding (length + content). It may also be NULL, which will
242	    be taken to represent an empty (zero length) parameter.
243	    Subparameters are stored in encoded form within the content part.
244
245_cmstruct   alternative representation for CAPI parameters of type 'struct'
246	    (used only for the 'Additional Info' and 'B Protocol' parameters)
247	    The representation is a single byte containing one of the values:
248	    CAPI_DEFAULT: The parameter is empty/absent.
249	    CAPI_COMPOSE: The parameter is present.
250	    Subparameter values are stored individually in the corresponding
251	    _cmsg structure members.
252=========== =================================================================
253
254
2555. Lower Layer Interface Functions
256==================================
257
258::
259
260  int attach_capi_ctr(struct capi_ctr *ctrlr)
261  int detach_capi_ctr(struct capi_ctr *ctrlr)
262
263register/unregister a device (controller) with Kernel CAPI
264
265::
266
267  void capi_ctr_ready(struct capi_ctr *ctrlr)
268  void capi_ctr_down(struct capi_ctr *ctrlr)
269
270signal controller ready/not ready
271
272::
273
274  void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid,
275			       struct sk_buff *skb)
276
277pass a received CAPI message to Kernel CAPI
278for forwarding to the specified application
279
280
2816. Helper Functions and Macros
282==============================
283
284Macros to extract/set element values from/in a CAPI message header
285(from <linux/isdn/capiutil.h>):
286
287======================  =============================   ====================
288Get Macro		Set Macro			Element (Type)
289======================  =============================   ====================
290CAPIMSG_LEN(m)		CAPIMSG_SETLEN(m, len)		Total Length (u16)
291CAPIMSG_APPID(m)	CAPIMSG_SETAPPID(m, applid)	ApplID (u16)
292CAPIMSG_COMMAND(m)	CAPIMSG_SETCOMMAND(m,cmd)	Command (u8)
293CAPIMSG_SUBCOMMAND(m)	CAPIMSG_SETSUBCOMMAND(m, cmd)	Subcommand (u8)
294CAPIMSG_CMD(m)		-				Command*256
295							+ Subcommand (u16)
296CAPIMSG_MSGID(m)	CAPIMSG_SETMSGID(m, msgid)	Message Number (u16)
297
298CAPIMSG_CONTROL(m)	CAPIMSG_SETCONTROL(m, contr)	Controller/PLCI/NCCI
299							(u32)
300CAPIMSG_DATALEN(m)	CAPIMSG_SETDATALEN(m, len)	Data Length (u16)
301======================  =============================   ====================
302
303
304Library functions for working with _cmsg structures
305(from <linux/isdn/capiutil.h>):
306
307``char *capi_cmd2str(u8 Command, u8 Subcommand)``
308	Returns the CAPI 2.0 message name corresponding to the given command
309	and subcommand values, as a static ASCII string. The return value may
310	be NULL if the command/subcommand is not one of those defined in the
311	CAPI 2.0 standard.
312
313
3147. Debugging
315============
316
317The module kernelcapi has a module parameter showcapimsgs controlling some
318debugging output produced by the module. It can only be set when the module is
319loaded, via a parameter "showcapimsgs=<n>" to the modprobe command, either on
320the command line or in the configuration file.
321
322If the lowest bit of showcapimsgs is set, kernelcapi logs controller and
323application up and down events.
324
325In addition, every registered CAPI controller has an associated traceflag
326parameter controlling how CAPI messages sent from and to tha controller are
327logged. The traceflag parameter is initialized with the value of the
328showcapimsgs parameter when the controller is registered, but can later be
329changed via the MANUFACTURER_REQ command KCAPI_CMD_TRACE.
330
331If the value of traceflag is non-zero, CAPI messages are logged.
332DATA_B3 messages are only logged if the value of traceflag is > 2.
333
334If the lowest bit of traceflag is set, only the command/subcommand and message
335length are logged. Otherwise, kernelcapi logs a readable representation of
336the entire message.
337