@@ -45,7 +45,7 @@ From then on, Kernel CAPI may call the registered callback functions for the
4545device.
4646
4747If 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
48+ driver has to call capi_ctr_down (). This will prevent further calls to the
4949callback functions by Kernel CAPI.
5050
5151
@@ -114,20 +114,36 @@ char *driver_name
114114int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata)
115115 (optional) pointer to a callback function for sending firmware and
116116 configuration data to the device
117+ Return value: 0 on success, error code on error
118+ Called in process context.
117119
118120void (*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+ (optional) pointer to a callback function for performing a reset on
122+ the device, releasing all registered applications
123+ Called in process context.
121124
122125void (*register_appl)(struct capi_ctr *ctrlr, u16 applid,
123126 capi_register_params *rparam)
124127void (*release_appl)(struct capi_ctr *ctrlr, u16 applid)
125128 pointers to callback functions for registration and deregistration of
126129 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.
127132
128133u16 (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb)
129134 pointer to a callback function for sending a CAPI message to the
130135 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.
131147
132148char *(*procinfo)(struct capi_ctr *ctrlr)
133149 pointer to a callback function returning the entry for the device in
@@ -138,6 +154,8 @@ read_proc_t *ctr_read_proc
138154 system entry, /proc/capi/controllers/<n>; will be called with a
139155 pointer to the device's capi_ctr structure as the last (data) argument
140156
157+ Note: Callback functions are never called in interrupt context.
158+
141159- to be filled in before calling capi_ctr_ready():
142160
143161u8 manu[CAPI_MANUFACTURER_LEN]
@@ -153,6 +171,45 @@ u8 serial[CAPI_SERIAL_LEN]
153171 value to return for CAPI_GET_SERIAL
154172
155173
174+ 4.3 The _cmsg Structure
175+
176+ (declared in <linux/isdn/capiutil.h>)
177+
178+ The _cmsg structure stores the contents of a CAPI 2.0 message in an easily
179+ accessible form. It contains members for all possible CAPI 2.0 parameters, of
180+ which only those appearing in the message type currently being processed are
181+ actually used. Unused members should be set to zero.
182+
183+ Members are named after the CAPI 2.0 standard names of the parameters they
184+ represent. See <linux/isdn/capiutil.h> for the exact spelling. Member data
185+ types are:
186+
187+ u8 for CAPI parameters of type 'byte'
188+
189+ u16 for CAPI parameters of type 'word'
190+
191+ u32 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+
206+ Functions capi_cmsg2message() and capi_message2cmsg() are provided to convert
207+ messages between their transport encoding described in the CAPI 2.0 standard
208+ and their _cmsg structure representation. Note that capi_cmsg2message() does
209+ not know or check the size of its destination buffer. The caller must make
210+ sure it is big enough to accomodate the resulting CAPI message.
211+
212+
1562135. Lower Layer Interface Functions
157214
158215(declared in <linux/isdn/capilli.h>)
@@ -166,7 +223,7 @@ int detach_capi_ctr(struct capi_ctr *ctrlr)
166223 register/unregister a device (controller) with Kernel CAPI
167224
168225void capi_ctr_ready(struct capi_ctr *ctrlr)
169- void capi_ctr_reseted (struct capi_ctr *ctrlr)
226+ void capi_ctr_down (struct capi_ctr *ctrlr)
170227 signal controller ready/not ready
171228
172229void capi_ctr_suspend_output(struct capi_ctr *ctrlr)
@@ -211,3 +268,32 @@ CAPIMSG_CONTROL(m) CAPIMSG_SETCONTROL(m, contr) Controller/PLCI/NCCI
211268 (u32)
212269CAPIMSG_DATALEN(m) CAPIMSG_SETDATALEN(m, len) Data Length (u16)
213270
271+
272+ Library functions for working with _cmsg structures
273+ (from <linux/isdn/capiutil.h>):
274+
275+ unsigned 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+
279+ unsigned capi_message2cmsg(_cmsg *cmsg, u8 *msg)
280+ Disassembles the CAPI 2.0 message in *msg, storing the parameters in
281+ *cmsg.
282+
283+ unsigned 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+
290+ void 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+
294+ char *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+
0 commit comments