blob: 686e107923ec16f36a4f6a32fd49b791e36b30b9 [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
63send_message() callback function. The CAPI message to send is stored in the
Karsten Keil2296e5a2009-04-23 02:24:21 +000064data portion of an skb. Conversely, the driver may call Kernel CAPI's
Tilman Schmidt554f2002009-04-23 02:24:21 +000065capi_ctr_handle_message() function to pass a received CAPI message to Kernel
66CAPI for forwarding to an application, specifying its ApplID.
67
Tilman Schmidt554f2002009-04-23 02:24:21 +000068Deregistration requests (CAPI operation CAPI_RELEASE) from applications are
69forwarded as calls to the release_appl() callback function, passing the same
70ApplID as with register_appl(). After return from release_appl(), no CAPI
71messages for that application may be passed to or from the device anymore.
72
73
744. Data Structures
75
764.1 struct capi_driver
77
78This structure describes a Kernel CAPI driver itself. It is used in the
79register_capi_driver() and unregister_capi_driver() functions, and contains
80the following non-private fields, all to be set by the driver before calling
81register_capi_driver():
82
83char name[32]
Karsten Keil2296e5a2009-04-23 02:24:21 +000084 the name of the driver, as a zero-terminated ASCII string
Tilman Schmidt554f2002009-04-23 02:24:21 +000085char revision[32]
Karsten Keil2296e5a2009-04-23 02:24:21 +000086 the revision number of the driver, as a zero-terminated ASCII string
Tilman Schmidt554f2002009-04-23 02:24:21 +000087int (*add_card)(struct capi_driver *driver, capicardparams *data)
88 a callback function pointer (may be NULL)
89
90
914.2 struct capi_ctr
92
93This structure describes an ISDN device (controller) handled by a Kernel CAPI
94driver. After registration via the attach_capi_ctr() function it is passed to
95all controller specific lower layer interface and callback functions to
96identify the controller to operate on.
97
98It contains the following non-private fields:
99
100- to be set by the driver before calling attach_capi_ctr():
101
102struct module *owner
103 pointer to the driver module owning the device
104
105void *driverdata
106 an opaque pointer to driver specific data, not touched by Kernel CAPI
107
108char name[32]
Karsten Keil2296e5a2009-04-23 02:24:21 +0000109 the name of the controller, as a zero-terminated ASCII string
Tilman Schmidt554f2002009-04-23 02:24:21 +0000110
111char *driver_name
Karsten Keil2296e5a2009-04-23 02:24:21 +0000112 the name of the driver, as a zero-terminated ASCII string
Tilman Schmidt554f2002009-04-23 02:24:21 +0000113
114int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata)
115 (optional) pointer to a callback function for sending firmware and
116 configuration data to the device
Tilman Schmidtfe932992009-06-07 09:09:24 +0000117 Return value: 0 on success, error code on error
118 Called in process context.
Tilman Schmidt554f2002009-04-23 02:24:21 +0000119
120void (*reset_ctr)(struct capi_ctr *ctrlr)
Tilman Schmidtfe932992009-06-07 09:09:24 +0000121 (optional) pointer to a callback function for performing a reset on
122 the device, releasing all registered applications
123 Called in process context.
Tilman Schmidt554f2002009-04-23 02:24:21 +0000124
125void (*register_appl)(struct capi_ctr *ctrlr, u16 applid,
126 capi_register_params *rparam)
127void (*release_appl)(struct capi_ctr *ctrlr, u16 applid)
128 pointers to callback functions for registration and deregistration of
129 applications with the device
Tilman Schmidtfe932992009-06-07 09:09:24 +0000130 Calls to these functions are serialized by Kernel CAPI so that only
131 one call to any of them is active at any time.
Tilman Schmidt554f2002009-04-23 02:24:21 +0000132
133u16 (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb)
134 pointer to a callback function for sending a CAPI message to the
135 device
Tilman Schmidtfe932992009-06-07 09:09:24 +0000136 Return value: CAPI error code
137 If the method returns 0 (CAPI_NOERROR) the driver has taken ownership
138 of the skb and the caller may no longer access it. If it returns a
139 non-zero (error) value then ownership of the skb returns to the caller
140 who may reuse or free it.
141 The return value should only be used to signal problems with respect
142 to accepting or queueing the message. Errors occurring during the
143 actual processing of the message should be signaled with an
144 appropriate reply message.
145 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 Schmidtfe932992009-06-07 09:09:24 +0000157Note: Callback functions are never called in interrupt context.
158
Tilman Schmidt554f2002009-04-23 02:24:21 +0000159- to be filled in before calling capi_ctr_ready():
160
161u8 manu[CAPI_MANUFACTURER_LEN]
162 value to return for CAPI_GET_MANUFACTURER
163
164capi_version version
165 value to return for CAPI_GET_VERSION
166
167capi_profile profile
168 value to return for CAPI_GET_PROFILE
169
170u8 serial[CAPI_SERIAL_LEN]
171 value to return for CAPI_GET_SERIAL
172
173
Tilman Schmidtfe932992009-06-07 09:09:24 +00001744.3 The _cmsg Structure
175
176(declared in <linux/isdn/capiutil.h>)
177
178The _cmsg structure stores the contents of a CAPI 2.0 message in an easily
179accessible form. It contains members for all possible CAPI 2.0 parameters, of
180which only those appearing in the message type currently being processed are
181actually used. Unused members should be set to zero.
182
183Members are named after the CAPI 2.0 standard names of the parameters they
184represent. See <linux/isdn/capiutil.h> for the exact spelling. Member data
185types are:
186
187u8 for CAPI parameters of type 'byte'
188
189u16 for CAPI parameters of type 'word'
190
191u32 for CAPI parameters of type 'dword'
192
193_cstruct for CAPI parameters of type 'struct' not containing any
194 variably-sized (struct) subparameters (eg. 'Called Party Number')
195 The member is a pointer to a buffer containing the parameter in
196 CAPI encoding (length + content). It may also be NULL, which will
197 be taken to represent an empty (zero length) parameter.
198
199_cmstruct for CAPI parameters of type 'struct' containing 'struct'
200 subparameters ('Additional Info' and 'B Protocol')
201 The representation is a single byte containing one of the values:
202 CAPI_DEFAULT: the parameter is empty
203 CAPI_COMPOSE: the values of the subparameters are stored
204 individually in the corresponding _cmsg structure members
205
206Functions capi_cmsg2message() and capi_message2cmsg() are provided to convert
207messages between their transport encoding described in the CAPI 2.0 standard
208and their _cmsg structure representation. Note that capi_cmsg2message() does
209not know or check the size of its destination buffer. The caller must make
210sure it is big enough to accomodate the resulting CAPI message.
211
212
Tilman Schmidt554f2002009-04-23 02:24:21 +00002135. Lower Layer Interface Functions
214
215(declared in <linux/isdn/capilli.h>)
216
217void register_capi_driver(struct capi_driver *drvr)
218void unregister_capi_driver(struct capi_driver *drvr)
219 register/unregister a driver with Kernel CAPI
220
221int attach_capi_ctr(struct capi_ctr *ctrlr)
222int detach_capi_ctr(struct capi_ctr *ctrlr)
223 register/unregister a device (controller) with Kernel CAPI
224
225void capi_ctr_ready(struct capi_ctr *ctrlr)
Tilman Schmidt4e329972009-06-07 09:09:23 +0000226void capi_ctr_down(struct capi_ctr *ctrlr)
Tilman Schmidt554f2002009-04-23 02:24:21 +0000227 signal controller ready/not ready
228
229void capi_ctr_suspend_output(struct capi_ctr *ctrlr)
230void capi_ctr_resume_output(struct capi_ctr *ctrlr)
231 signal suspend/resume
232
233void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid,
234 struct sk_buff *skb)
235 pass a received CAPI message to Kernel CAPI
236 for forwarding to the specified application
237
238
2396. Helper Functions and Macros
240
241Library functions (from <linux/isdn/capilli.h>):
242
243void capilib_new_ncci(struct list_head *head, u16 applid,
244 u32 ncci, u32 winsize)
245void capilib_free_ncci(struct list_head *head, u16 applid, u32 ncci)
246void capilib_release_appl(struct list_head *head, u16 applid)
247void capilib_release(struct list_head *head)
248void capilib_data_b3_conf(struct list_head *head, u16 applid,
249 u32 ncci, u16 msgid)
250u16 capilib_data_b3_req(struct list_head *head, u16 applid,
251 u32 ncci, u16 msgid)
252
253
254Macros to extract/set element values from/in a CAPI message header
255(from <linux/isdn/capiutil.h>):
256
257Get Macro Set Macro Element (Type)
258
259CAPIMSG_LEN(m) CAPIMSG_SETLEN(m, len) Total Length (u16)
260CAPIMSG_APPID(m) CAPIMSG_SETAPPID(m, applid) ApplID (u16)
261CAPIMSG_COMMAND(m) CAPIMSG_SETCOMMAND(m,cmd) Command (u8)
262CAPIMSG_SUBCOMMAND(m) CAPIMSG_SETSUBCOMMAND(m, cmd) Subcommand (u8)
263CAPIMSG_CMD(m) - Command*256
264 + Subcommand (u16)
265CAPIMSG_MSGID(m) CAPIMSG_SETMSGID(m, msgid) Message Number (u16)
266
267CAPIMSG_CONTROL(m) CAPIMSG_SETCONTROL(m, contr) Controller/PLCI/NCCI
268 (u32)
269CAPIMSG_DATALEN(m) CAPIMSG_SETDATALEN(m, len) Data Length (u16)
270
Tilman Schmidtfe932992009-06-07 09:09:24 +0000271
272Library functions for working with _cmsg structures
273(from <linux/isdn/capiutil.h>):
274
275unsigned capi_cmsg2message(_cmsg *cmsg, u8 *msg)
276 Assembles a CAPI 2.0 message from the parameters in *cmsg, storing the
277 result in *msg.
278
279unsigned capi_message2cmsg(_cmsg *cmsg, u8 *msg)
280 Disassembles the CAPI 2.0 message in *msg, storing the parameters in
281 *cmsg.
282
283unsigned capi_cmsg_header(_cmsg *cmsg, u16 ApplId, u8 Command, u8 Subcommand,
284 u16 Messagenumber, u32 Controller)
285 Fills the header part and address field of the _cmsg structure *cmsg
286 with the given values, zeroing the remainder of the structure so only
287 parameters with non-default values need to be changed before sending
288 the message.
289
290void capi_cmsg_answer(_cmsg *cmsg)
291 Sets the low bit of the Subcommand field in *cmsg, thereby converting
292 _REQ to _CONF and _IND to _RESP.
293
294char *capi_cmd2str(u8 Command, u8 Subcommand)
295 Returns the CAPI 2.0 message name corresponding to the given command
296 and subcommand values, as a static ASCII string. The return value may
297 be NULL if the command/subcommand is not one of those defined in the
298 CAPI 2.0 standard.
299