1. Overview
+From the CAPI 2.0 specification:
+COMMON-ISDN-API (CAPI) is an application programming interface standard used
+to access ISDN equipment connected to basic rate interfaces (BRI) and primary
+rate interfaces (PRI).
+
Kernel CAPI operates as a dispatching layer between CAPI applications and CAPI
hardware drivers. Hardware drivers register ISDN devices (controllers, in CAPI
lingo) with Kernel CAPI to indicate their readiness to provide their service
corresponding hardware driver. Kernel CAPI then forwards CAPI messages in both
directions between the application and the hardware driver.
+Format and semantics of CAPI messages are specified in the CAPI 2.0 standard.
+This standard is freely available from http://www.capi.org.
+
2. Driver and Device Registration
device.
If the device becomes unusable for any reason (shutdown, disconnect ...), the
-driver has to call capi_ctr_reseted(). This will prevent further calls to the
+driver has to call capi_ctr_down(). This will prevent further calls to the
callback functions by Kernel CAPI.
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 a 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.
-
-Format and semantics of CAPI messages are specified in the CAPI 2.0 standard.
+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
register_capi_driver():
char name[32]
- the name of the driver, as a zero terminated ASCII string
+ the name of the driver, as a zero-terminated ASCII string
char revision[32]
- the revision number of the driver, as a zero terminated ASCII string
+ the revision number of the driver, as a zero-terminated ASCII string
int (*add_card)(struct capi_driver *driver, capicardparams *data)
a callback function pointer (may be NULL)
an opaque pointer to driver specific data, not touched by Kernel CAPI
char name[32]
- the name of the controller, as a zero terminated ASCII string
+ the name of the controller, as a zero-terminated ASCII string
char *driver_name
- the name of the driver, as a zero terminated ASCII string
+ the name of the driver, as a zero-terminated ASCII string
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.
+ 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.
char *(*procinfo)(struct capi_ctr *ctrlr)
pointer to a callback function returning the entry for the device in
the CAPI controller info table, /proc/capi/controller
-read_proc_t *ctr_read_proc
- pointer to the read_proc callback function for the device's proc file
- system entry, /proc/capi/controllers/<n>; will be called with a
- pointer to the device's capi_ctr structure as the last (data) argument
+const struct file_operations *proc_fops
+ pointers to callback functions for the device's proc file
+ system entry, /proc/capi/controllers/<n>; pointer to the device's
+ capi_ctr structure is available from struct proc_dir_entry::data
+ which is available from struct inode.
+
+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 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,
+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
+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'
+ 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 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/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
+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>)
register/unregister a device (controller) with Kernel CAPI
void capi_ctr_ready(struct capi_ctr *ctrlr)
-void capi_ctr_reseted(struct capi_ctr *ctrlr)
+void capi_ctr_down(struct capi_ctr *ctrlr)
signal controller ready/not ready
void capi_ctr_suspend_output(struct capi_ctr *ctrlr)
(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.
+
+
+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.
git://ftp.safe.ca / safe / jmp / linux-2.6 / blobdiff