arch/x86: Implement <asm/fb.h> with generic helpers
[linux-2.6-microblaze.git] / Documentation / isdn / interface_capi.rst
1 =========================================
2 Kernel CAPI Interface to Hardware Drivers
3 =========================================
4
5 1. Overview
6 ===========
7
8 From the CAPI 2.0 specification:
9 COMMON-ISDN-API (CAPI) is an application programming interface standard used
10 to access ISDN equipment connected to basic rate interfaces (BRI) and primary
11 rate interfaces (PRI).
12
13 Kernel CAPI operates as a dispatching layer between CAPI applications and CAPI
14 hardware drivers. Hardware drivers register ISDN devices (controllers, in CAPI
15 lingo) with Kernel CAPI to indicate their readiness to provide their service
16 to CAPI applications. CAPI applications also register with Kernel CAPI,
17 requesting association with a CAPI device. Kernel CAPI then dispatches the
18 application registration to an available device, forwarding it to the
19 corresponding hardware driver. Kernel CAPI then forwards CAPI messages in both
20 directions between the application and the hardware driver.
21
22 Format and semantics of CAPI messages are specified in the CAPI 2.0 standard.
23 This standard is freely available from https://www.capi.org.
24
25
26 2. Driver and Device Registration
27 =================================
28
29 CAPI drivers must register each of the ISDN devices they control with Kernel
30 CAPI by calling the Kernel CAPI function attach_capi_ctr() with a pointer to a
31 struct capi_ctr before they can be used. This structure must be filled with
32 the names of the driver and controller, and a number of callback function
33 pointers which are subsequently used by Kernel CAPI for communicating with the
34 driver. The registration can be revoked by calling the function
35 detach_capi_ctr() with a pointer to the same struct capi_ctr.
36
37 Before the device can be actually used, the driver must fill in the device
38 information fields 'manu', 'version', 'profile' and 'serial' in the capi_ctr
39 structure of the device, and signal its readiness by calling capi_ctr_ready().
40 From then on, Kernel CAPI may call the registered callback functions for the
41 device.
42
43 If the device becomes unusable for any reason (shutdown, disconnect ...), the
44 driver has to call capi_ctr_down(). This will prevent further calls to the
45 callback functions by Kernel CAPI.
46
47
48 3. Application Registration and Communication
49 =============================================
50
51 Kernel CAPI forwards registration requests from applications (calls to CAPI
52 operation CAPI_REGISTER) to an appropriate hardware driver by calling its
53 register_appl() callback function. A unique Application ID (ApplID, u16) is
54 allocated by Kernel CAPI and passed to register_appl() along with the
55 parameter structure provided by the application. This is analogous to the
56 open() operation on regular files or character devices.
57
58 After a successful return from register_appl(), CAPI messages from the
59 application may be passed to the driver for the device via calls to the
60 send_message() callback function. Conversely, the driver may call Kernel
61 CAPI's capi_ctr_handle_message() function to pass a received CAPI message to
62 Kernel CAPI for forwarding to an application, specifying its ApplID.
63
64 Deregistration requests (CAPI operation CAPI_RELEASE) from applications are
65 forwarded as calls to the release_appl() callback function, passing the same
66 ApplID as with register_appl(). After return from release_appl(), no CAPI
67 messages for that application may be passed to or from the device anymore.
68
69
70 4. Data Structures
71 ==================
72
73 4.1 struct capi_driver
74 ----------------------
75
76 This structure describes a Kernel CAPI driver itself. It is used in the
77 register_capi_driver() and unregister_capi_driver() functions, and contains
78 the following non-private fields, all to be set by the driver before calling
79 register_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
86 4.2 struct capi_ctr
87 -------------------
88
89 This structure describes an ISDN device (controller) handled by a Kernel CAPI
90 driver. After registration via the attach_capi_ctr() function it is passed to
91 all controller specific lower layer interface and callback functions to
92 identify the controller to operate on.
93
94 It contains the following non-private fields:
95
96 to 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
171 Note:
172   Callback functions except send_message() are never called in interrupt
173   context.
174
175 to 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
191 4.3 SKBs
192 --------
193
194 CAPI messages are passed between Kernel CAPI and the driver via send_message()
195 and 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
197 standard.
198
199 For the data transfer messages, DATA_B3_REQ and DATA_B3_IND, the actual
200 payload data immediately follows the CAPI message itself within the same skb.
201 The Data and Data64 parameters are not used for processing. The Data64
202 parameter may be omitted by setting the length field of the CAPI message to 22
203 instead of 30.
204
205
206 4.4 The _cmsg Structure
207 -----------------------
208
209 (declared in <linux/isdn/capiutil.h>)
210
211 The _cmsg structure stores the contents of a CAPI 2.0 message in an easily
212 accessible form. It contains members for all possible CAPI 2.0 parameters,
213 including subparameters of the Additional Info and B Protocol structured
214 parameters, 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
225 Only those parameters appearing in the message type currently being processed
226 are actually used. Unused members should be set to zero.
227
228 Members are named after the CAPI 2.0 standard names of the parameters they
229 represent. See <linux/isdn/capiutil.h> for the exact spelling. Member data
230 types are:
231
232 =========== =================================================================
233 u8          for CAPI parameters of type 'byte'
234
235 u16         for CAPI parameters of type 'word'
236
237 u32         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
255 5. 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
263 register/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
270 signal 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
277 pass a received CAPI message to Kernel CAPI
278 for forwarding to the specified application
279
280
281 6. Helper Functions and Macros
282 ==============================
283
284 Macros to extract/set element values from/in a CAPI message header
285 (from <linux/isdn/capiutil.h>):
286
287 ======================  =============================   ====================
288 Get Macro               Set Macro                       Element (Type)
289 ======================  =============================   ====================
290 CAPIMSG_LEN(m)          CAPIMSG_SETLEN(m, len)          Total Length (u16)
291 CAPIMSG_APPID(m)        CAPIMSG_SETAPPID(m, applid)     ApplID (u16)
292 CAPIMSG_COMMAND(m)      CAPIMSG_SETCOMMAND(m,cmd)       Command (u8)
293 CAPIMSG_SUBCOMMAND(m)   CAPIMSG_SETSUBCOMMAND(m, cmd)   Subcommand (u8)
294 CAPIMSG_CMD(m)          -                               Command*256
295                                                         + Subcommand (u16)
296 CAPIMSG_MSGID(m)        CAPIMSG_SETMSGID(m, msgid)      Message Number (u16)
297
298 CAPIMSG_CONTROL(m)      CAPIMSG_SETCONTROL(m, contr)    Controller/PLCI/NCCI
299                                                         (u32)
300 CAPIMSG_DATALEN(m)      CAPIMSG_SETDATALEN(m, len)      Data Length (u16)
301 ======================  =============================   ====================
302
303
304 Library 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
314 7. Debugging
315 ============
316
317 The module kernelcapi has a module parameter showcapimsgs controlling some
318 debugging output produced by the module. It can only be set when the module is
319 loaded, via a parameter "showcapimsgs=<n>" to the modprobe command, either on
320 the command line or in the configuration file.
321
322 If the lowest bit of showcapimsgs is set, kernelcapi logs controller and
323 application up and down events.
324
325 In addition, every registered CAPI controller has an associated traceflag
326 parameter controlling how CAPI messages sent from and to the controller are
327 logged. The traceflag parameter is initialized with the value of the
328 showcapimsgs parameter when the controller is registered, but can later be
329 changed via the MANUFACTURER_REQ command KCAPI_CMD_TRACE.
330
331 If the value of traceflag is non-zero, CAPI messages are logged.
332 DATA_B3 messages are only logged if the value of traceflag is > 2.
333
334 If the lowest bit of traceflag is set, only the command/subcommand and message
335 length are logged. Otherwise, kernelcapi logs a readable representation of
336 the entire message.