Documentation: expand isdn/INTERFACE.CAPI document

After a successful return from register_appl(), CAPI messages from the

application may be passed to the driver for the device via calls to the

send_message() callback function. The CAPI message to send is stored in the

data portion of an skb. Conversely, the driver may call Kernel CAPI's

capi_ctr_handle_message() function to pass a received CAPI message to Kernel

CAPI for forwarding to an application, specifying its ApplID.

send_message() callback function. Conversely, the driver may call Kernel

CAPI's capi_ctr_handle_message() function to pass a received CAPI message to

Kernel CAPI for forwarding to an application, specifying its ApplID.

Deregistration requests (CAPI operation CAPI_RELEASE) from applications are

forwarded as calls to the release_appl() callback function, passing the same

	to accepting or queueing the message. Errors occurring during the

	actual processing of the message should be signaled with an

	appropriate reply message.

	May be called in process or interrupt context.

	Calls to this function are not serialized by Kernel CAPI, ie. it must

	be prepared to be re-entered.

	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.

Note: Callback functions except send_message() are never called in interrupt

context.

- to be filled in before calling capi_ctr_ready():

	value to return for CAPI_GET_SERIAL

4.3 The _cmsg Structure

4.3 SKBs

CAPI messages are passed between Kernel CAPI and the driver via send_message()

and capi_ctr_handle_message(), stored in the data portion of a socket buffer

(skb).  Each skb contains a single CAPI message coded according to the CAPI 2.0

standard.

For the data transfer messages, DATA_B3_REQ and DATA_B3_IND, the actual

payload data immediately follows the CAPI message itself within the same skb.

The Data and Data64 parameters are not used for processing. The Data64

parameter may be omitted by setting the length field of the CAPI message to 22

instead of 30.

4.4 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.

accessible form. It contains members for all possible CAPI 2.0 parameters,

including subparameters of the Additional Info and B Protocol structured

parameters, with the following exceptions:

* second Calling party number (CONNECT_IND)

* Data64 (DATA_B3_REQ and DATA_B3_IND)

* Sending complete (subparameter of Additional Info, CONNECT_REQ and INFO_REQ)

* Global Configuration (subparameter of B Protocol, CONNECT_REQ, CONNECT_RESP

  and SELECT_B_PROTOCOL_REQ)

Only those parameters 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

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')

_cstruct    for CAPI parameters of type 'struct'

	    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.

	    Subparameters are stored in encoded form within the content part.

_cmstruct   for CAPI parameters of type 'struct' containing 'struct'

	    subparameters ('Additional Info' and 'B Protocol')

_cmstruct   alternative representation for CAPI parameters of type 'struct'

	    (used only for the 'Additional Info' and 'B Protocol' parameters)

	    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

	    CAPI_DEFAULT: The parameter is empty/absent.

	    CAPI_COMPOSE: The parameter is present.

	    Subparameter values 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

	be NULL if the command/subcommand is not one of those defined in the

	CAPI 2.0 standard.

7. Debugging

The module kernelcapi has a module parameter showcapimsgs controlling some

debugging output produced by the module. It can only be set when the module is

loaded, via a parameter "showcapimsgs=<n>" to the modprobe command, either on

the command line or in the configuration file.

If the lowest bit of showcapimsgs is set, kernelcapi logs controller and

application up and down events.

In addition, every registered CAPI controller has an associated traceflag

parameter controlling how CAPI messages sent from and to tha controller are

logged. The traceflag parameter is initialized with the value of the

showcapimsgs parameter when the controller is registered, but can later be

changed via the MANUFACTURER_REQ command KCAPI_CMD_TRACE.

If the value of traceflag is non-zero, CAPI messages are logged.

DATA_B3 messages are only logged if the value of traceflag is > 2.

If the lowest bit of traceflag is set, only the command/subcommand and message

length are logged. Otherwise, kernelcapi logs a readable representation of

the entire message.