Merge branch 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/bart/ide-2.6
[linux-2.6] / Documentation / isdn / INTERFACE.CAPI
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_reseted(). 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. The CAPI message to send is stored in the
64 data portion of an skb. Conversely, the driver may call Kernel CAPI's
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
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]
84         the name of the driver, as a zero-terminated ASCII string
85 char revision[32]
86         the revision number of the driver, as a zero-terminated ASCII string
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]
109         the name of the controller, as a zero-terminated ASCII string
110
111 char *driver_name
112         the name of the driver, as a zero-terminated ASCII string
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)
169 void capi_ctr_reseted(struct capi_ctr *ctrlr)
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