About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / isdn / INTERFACE.CAPI




Custom Search

Based on kernel version 3.15.4. Page generated on 2014-07-07 09:03 EST.

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 http://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.
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.