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>

diff --git a/Documentation/isdn/INTERFACE.CAPI b/Documentation/isdn/INTERFACE.CAPI
index 4631538..686e107 100644 (file)
--- a/Documentation/isdn/INTERFACE.CAPI
+++ b/Documentation/isdn/INTERFACE.CAPI
@@ -114,20 +114,36 @@ char *driver_name
 int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata)
        (optional) pointer to a callback function for sending firmware and
        configuration data to the device
+       Return value: 0 on success, error code on error
+       Called in process context.
 
 void (*reset_ctr)(struct capi_ctr *ctrlr)
-       pointer to a callback function for performing a reset on the device,
-       releasing all registered applications
+       (optional) pointer to a callback function for performing a reset on
+       the device, releasing all registered applications
+       Called in process context.
 
 void (*register_appl)(struct capi_ctr *ctrlr, u16 applid,
                        capi_register_params *rparam)
 void (*release_appl)(struct capi_ctr *ctrlr, u16 applid)
        pointers to callback functions for registration and 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)
        pointer to a callback function for sending a CAPI message to the
        device
+       Return value: CAPI error code
+       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.
+       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.
+       Calls to this function are not serialized by Kernel CAPI, ie. it must
+       be prepared to be re-entered.
 
 char *(*procinfo)(struct capi_ctr *ctrlr)
        pointer to a callback function returning the entry for the device in
@@ -138,6 +154,8 @@ read_proc_t *ctr_read_proc
        system entry, /proc/capi/controllers/<n>; will be called with a
        pointer to the device's capi_ctr structure as the last (data) argument
 
+Note: Callback functions are never called in interrupt context.
+
 - to be filled in before calling capi_ctr_ready():
 
 u8 manu[CAPI_MANUFACTURER_LEN]
@@ -153,6 +171,45 @@ u8 serial[CAPI_SERIAL_LEN]
        value to return for CAPI_GET_SERIAL
 
 
+4.3 The _cmsg Structure
+
+(declared in <linux/isdn/capiutil.h>)
+
+The _cmsg structure stores the contents of a CAPI 2.0 message in an easily
+accessible form. It contains members for all possible CAPI 2.0 parameters, of
+which only those appearing in the message type currently being processed are
+actually used. Unused members should be set to zero.
+
+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:
+
+u8          for CAPI parameters of type 'byte'
+
+u16         for CAPI parameters of type 'word'
+
+u32         for CAPI parameters of type 'dword'
+
+_cstruct    for CAPI parameters of type 'struct' not containing any
+           variably-sized (struct) subparameters (eg. 'Called Party Number')
+           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.
+
+_cmstruct   for CAPI parameters of type 'struct' containing 'struct'
+           subparameters ('Additional Info' and 'B Protocol')
+           The representation is a single byte containing one of the values:
+           CAPI_DEFAULT: the parameter is empty
+           CAPI_COMPOSE: the values of the subparameters are stored
+           individually in the corresponding _cmsg structure members
+
+Functions capi_cmsg2message() and capi_message2cmsg() are provided to convert
+messages between their transport encoding described in the CAPI 2.0 standard
+and their _cmsg structure representation. Note that capi_cmsg2message() does
+not know or check the size of its destination buffer. The caller must make
+sure it is big enough to accomodate the resulting CAPI message.
+
+
 5. Lower Layer Interface Functions
 
 (declared in <linux/isdn/capilli.h>)
@@ -211,3 +268,32 @@ CAPIMSG_CONTROL(m) CAPIMSG_SETCONTROL(m, contr)    Controller/PLCI/NCCI
                                                        (u32)
 CAPIMSG_DATALEN(m)     CAPIMSG_SETDATALEN(m, len)      Data Length (u16)
 
+
+Library functions for working with _cmsg structures
+(from <linux/isdn/capiutil.h>):
+
+unsigned capi_cmsg2message(_cmsg *cmsg, u8 *msg)
+       Assembles a CAPI 2.0 message from the parameters in *cmsg, storing the
+       result in *msg.
+
+unsigned capi_message2cmsg(_cmsg *cmsg, u8 *msg)
+       Disassembles the CAPI 2.0 message in *msg, storing the parameters in
+       *cmsg.
+
+unsigned capi_cmsg_header(_cmsg *cmsg, u16 ApplId, u8 Command, u8 Subcommand,
+                         u16 Messagenumber, u32 Controller)
+       Fills the header part and address field of the _cmsg structure *cmsg
+       with the given values, zeroing the remainder of the structure so only
+       parameters with non-default values need to be changed before sending
+       the message.
+
+void capi_cmsg_answer(_cmsg *cmsg)
+       Sets the low bit of the Subcommand field in *cmsg, thereby converting
+       _REQ to _CONF and _IND to _RESP.
+
+char *capi_cmd2str(u8 Command, u8 Subcommand)
+       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.
+