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