Commit | Line | Data |
---|---|---|
554f200e TS |
1 | Kernel CAPI Interface to Hardware Drivers |
2 | ----------------------------------------- | |
3 | ||
4 | 1. Overview | |
5 | ||
2296e5a0 KK |
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 | ||
554f200e TS |
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 | ||
2296e5a0 KK |
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 | ||
554f200e TS |
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 | |
4e329972 | 48 | driver has to call capi_ctr_down(). This will prevent further calls to the |
554f200e TS |
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. The CAPI message to send is stored in the | |
2296e5a0 | 64 | data portion of an skb. Conversely, the driver may call Kernel CAPI's |
554f200e TS |
65 | capi_ctr_handle_message() function to pass a received CAPI message to Kernel |
66 | CAPI for forwarding to an application, specifying its ApplID. | |
67 | ||
554f200e TS |
68 | Deregistration requests (CAPI operation CAPI_RELEASE) from applications are |
69 | forwarded as calls to the release_appl() callback function, passing the same | |
70 | ApplID as with register_appl(). After return from release_appl(), no CAPI | |
71 | messages for that application may be passed to or from the device anymore. | |
72 | ||
73 | ||
74 | 4. Data Structures | |
75 | ||
76 | 4.1 struct capi_driver | |
77 | ||
78 | This structure describes a Kernel CAPI driver itself. It is used in the | |
79 | register_capi_driver() and unregister_capi_driver() functions, and contains | |
80 | the following non-private fields, all to be set by the driver before calling | |
81 | register_capi_driver(): | |
82 | ||
83 | char name[32] | |
2296e5a0 | 84 | the name of the driver, as a zero-terminated ASCII string |
554f200e | 85 | char revision[32] |
2296e5a0 | 86 | the revision number of the driver, as a zero-terminated ASCII string |
554f200e TS |
87 | int (*add_card)(struct capi_driver *driver, capicardparams *data) |
88 | a callback function pointer (may be NULL) | |
89 | ||
90 | ||
91 | 4.2 struct capi_ctr | |
92 | ||
93 | This structure describes an ISDN device (controller) handled by a Kernel CAPI | |
94 | driver. After registration via the attach_capi_ctr() function it is passed to | |
95 | all controller specific lower layer interface and callback functions to | |
96 | identify the controller to operate on. | |
97 | ||
98 | It contains the following non-private fields: | |
99 | ||
100 | - to be set by the driver before calling attach_capi_ctr(): | |
101 | ||
102 | struct module *owner | |
103 | pointer to the driver module owning the device | |
104 | ||
105 | void *driverdata | |
106 | an opaque pointer to driver specific data, not touched by Kernel CAPI | |
107 | ||
108 | char name[32] | |
2296e5a0 | 109 | the name of the controller, as a zero-terminated ASCII string |
554f200e TS |
110 | |
111 | char *driver_name | |
2296e5a0 | 112 | the name of the driver, as a zero-terminated ASCII string |
554f200e TS |
113 | |
114 | int (*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 | |
117 | ||
118 | void (*reset_ctr)(struct capi_ctr *ctrlr) | |
119 | pointer to a callback function for performing a reset on the device, | |
120 | releasing all registered applications | |
121 | ||
122 | void (*register_appl)(struct capi_ctr *ctrlr, u16 applid, | |
123 | capi_register_params *rparam) | |
124 | void (*release_appl)(struct capi_ctr *ctrlr, u16 applid) | |
125 | pointers to callback functions for registration and deregistration of | |
126 | applications with the device | |
127 | ||
128 | u16 (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb) | |
129 | pointer to a callback function for sending a CAPI message to the | |
130 | device | |
131 | ||
132 | char *(*procinfo)(struct capi_ctr *ctrlr) | |
133 | pointer to a callback function returning the entry for the device in | |
134 | the CAPI controller info table, /proc/capi/controller | |
135 | ||
136 | read_proc_t *ctr_read_proc | |
137 | pointer to the read_proc callback function for the device's proc file | |
138 | system entry, /proc/capi/controllers/<n>; will be called with a | |
139 | pointer to the device's capi_ctr structure as the last (data) argument | |
140 | ||
141 | - to be filled in before calling capi_ctr_ready(): | |
142 | ||
143 | u8 manu[CAPI_MANUFACTURER_LEN] | |
144 | value to return for CAPI_GET_MANUFACTURER | |
145 | ||
146 | capi_version version | |
147 | value to return for CAPI_GET_VERSION | |
148 | ||
149 | capi_profile profile | |
150 | value to return for CAPI_GET_PROFILE | |
151 | ||
152 | u8 serial[CAPI_SERIAL_LEN] | |
153 | value to return for CAPI_GET_SERIAL | |
154 | ||
155 | ||
156 | 5. Lower Layer Interface Functions | |
157 | ||
158 | (declared in <linux/isdn/capilli.h>) | |
159 | ||
160 | void register_capi_driver(struct capi_driver *drvr) | |
161 | void unregister_capi_driver(struct capi_driver *drvr) | |
162 | register/unregister a driver with Kernel CAPI | |
163 | ||
164 | int attach_capi_ctr(struct capi_ctr *ctrlr) | |
165 | int detach_capi_ctr(struct capi_ctr *ctrlr) | |
166 | register/unregister a device (controller) with Kernel CAPI | |
167 | ||
168 | void capi_ctr_ready(struct capi_ctr *ctrlr) | |
4e329972 | 169 | void capi_ctr_down(struct capi_ctr *ctrlr) |
554f200e TS |
170 | signal controller ready/not ready |
171 | ||
172 | void capi_ctr_suspend_output(struct capi_ctr *ctrlr) | |
173 | void capi_ctr_resume_output(struct capi_ctr *ctrlr) | |
174 | signal suspend/resume | |
175 | ||
176 | void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid, | |
177 | struct sk_buff *skb) | |
178 | pass a received CAPI message to Kernel CAPI | |
179 | for forwarding to the specified application | |
180 | ||
181 | ||
182 | 6. Helper Functions and Macros | |
183 | ||
184 | Library functions (from <linux/isdn/capilli.h>): | |
185 | ||
186 | void capilib_new_ncci(struct list_head *head, u16 applid, | |
187 | u32 ncci, u32 winsize) | |
188 | void capilib_free_ncci(struct list_head *head, u16 applid, u32 ncci) | |
189 | void capilib_release_appl(struct list_head *head, u16 applid) | |
190 | void capilib_release(struct list_head *head) | |
191 | void capilib_data_b3_conf(struct list_head *head, u16 applid, | |
192 | u32 ncci, u16 msgid) | |
193 | u16 capilib_data_b3_req(struct list_head *head, u16 applid, | |
194 | u32 ncci, u16 msgid) | |
195 | ||
196 | ||
197 | Macros to extract/set element values from/in a CAPI message header | |
198 | (from <linux/isdn/capiutil.h>): | |
199 | ||
200 | Get Macro Set Macro Element (Type) | |
201 | ||
202 | CAPIMSG_LEN(m) CAPIMSG_SETLEN(m, len) Total Length (u16) | |
203 | CAPIMSG_APPID(m) CAPIMSG_SETAPPID(m, applid) ApplID (u16) | |
204 | CAPIMSG_COMMAND(m) CAPIMSG_SETCOMMAND(m,cmd) Command (u8) | |
205 | CAPIMSG_SUBCOMMAND(m) CAPIMSG_SETSUBCOMMAND(m, cmd) Subcommand (u8) | |
206 | CAPIMSG_CMD(m) - Command*256 | |
207 | + Subcommand (u16) | |
208 | CAPIMSG_MSGID(m) CAPIMSG_SETMSGID(m, msgid) Message Number (u16) | |
209 | ||
210 | CAPIMSG_CONTROL(m) CAPIMSG_SETCONTROL(m, contr) Controller/PLCI/NCCI | |
211 | (u32) | |
212 | CAPIMSG_DATALEN(m) CAPIMSG_SETDATALEN(m, len) Data Length (u16) | |
213 |