aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorTilman Schmidt <tilman@imap.cc>2009-06-07 05:09:24 -0400
committerDavid S. Miller <davem@davemloft.net>2009-06-08 03:45:52 -0400
commitfe93299a008a7056fe1790744b3a425ddf79a16b (patch)
tree918460120177a3ab1a79f28f4409ead19f7a39dc
parent7d31acda9f8eaa27e2fd232712f7e1f3e9a79bdb (diff)
isdn: extend INTERFACE.CAPI document
Clarify calling context and return codes of callback methods, and add a description of the _cmsg structure and helper functions. Impact: documentation Signed-off-by: Tilman Schmidt <tilman@imap.cc> Signed-off-by: David S. Miller <davem@davemloft.net>
-rw-r--r--Documentation/isdn/INTERFACE.CAPI90
1 files changed, 88 insertions, 2 deletions
diff --git a/Documentation/isdn/INTERFACE.CAPI b/Documentation/isdn/INTERFACE.CAPI
index 463153816162..686e107923ec 100644
--- a/Documentation/isdn/INTERFACE.CAPI
+++ b/Documentation/isdn/INTERFACE.CAPI
@@ -114,20 +114,36 @@ char *driver_name
114int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata) 114int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata)
115 (optional) pointer to a callback function for sending firmware and 115 (optional) pointer to a callback function for sending firmware and
116 configuration data to the device 116 configuration data to the device
117 Return value: 0 on success, error code on error
118 Called in process context.
117 119
118void (*reset_ctr)(struct capi_ctr *ctrlr) 120void (*reset_ctr)(struct capi_ctr *ctrlr)
119 pointer to a callback function for performing a reset on the device, 121 (optional) pointer to a callback function for performing a reset on
120 releasing all registered applications 122 the device, releasing all registered applications
123 Called in process context.
121 124
122void (*register_appl)(struct capi_ctr *ctrlr, u16 applid, 125void (*register_appl)(struct capi_ctr *ctrlr, u16 applid,
123 capi_register_params *rparam) 126 capi_register_params *rparam)
124void (*release_appl)(struct capi_ctr *ctrlr, u16 applid) 127void (*release_appl)(struct capi_ctr *ctrlr, u16 applid)
125 pointers to callback functions for registration and deregistration of 128 pointers to callback functions for registration and deregistration of
126 applications with the device 129 applications with the device
130 Calls to these functions are serialized by Kernel CAPI so that only
131 one call to any of them is active at any time.
127 132
128u16 (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb) 133u16 (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb)
129 pointer to a callback function for sending a CAPI message to the 134 pointer to a callback function for sending a CAPI message to the
130 device 135 device
136 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.
131 147
132char *(*procinfo)(struct capi_ctr *ctrlr) 148char *(*procinfo)(struct capi_ctr *ctrlr)
133 pointer to a callback function returning the entry for the device in 149 pointer to a callback function returning the entry for the device in
@@ -138,6 +154,8 @@ read_proc_t *ctr_read_proc
138 system entry, /proc/capi/controllers/<n>; will be called with a 154 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 155 pointer to the device's capi_ctr structure as the last (data) argument
140 156
157Note: Callback functions are never called in interrupt context.
158
141- to be filled in before calling capi_ctr_ready(): 159- to be filled in before calling capi_ctr_ready():
142 160
143u8 manu[CAPI_MANUFACTURER_LEN] 161u8 manu[CAPI_MANUFACTURER_LEN]
@@ -153,6 +171,45 @@ u8 serial[CAPI_SERIAL_LEN]
153 value to return for CAPI_GET_SERIAL 171 value to return for CAPI_GET_SERIAL
154 172
155 173
1744.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
1565. Lower Layer Interface Functions 2135. Lower Layer Interface Functions
157 214
158(declared in <linux/isdn/capilli.h>) 215(declared in <linux/isdn/capilli.h>)
@@ -211,3 +268,32 @@ CAPIMSG_CONTROL(m) CAPIMSG_SETCONTROL(m, contr) Controller/PLCI/NCCI
211 (u32) 268 (u32)
212CAPIMSG_DATALEN(m) CAPIMSG_SETDATALEN(m, len) Data Length (u16) 269CAPIMSG_DATALEN(m) CAPIMSG_SETDATALEN(m, len) Data Length (u16)
213 270
271
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