docs: isdn: convert to ReST and add to kAPI bookset
[linux-2.6-microblaze.git] / Documentation / isdn / INTERFACE.CAPI
diff --git a/Documentation/isdn/INTERFACE.CAPI b/Documentation/isdn/INTERFACE.CAPI
deleted file mode 100644 (file)
index 021aa9c..0000000
+++ /dev/null
@@ -1,355 +0,0 @@
-Kernel CAPI Interface to Hardware Drivers
------------------------------------------
-
-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
-to CAPI applications. CAPI applications also register with Kernel CAPI,
-requesting association with a CAPI device. Kernel CAPI then dispatches the
-application registration to an available device, forwarding it to the
-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 https://www.capi.org.
-
-
-2. Driver and Device Registration
-
-CAPI drivers optionally register themselves with Kernel CAPI by calling the
-Kernel CAPI function register_capi_driver() with a pointer to a struct
-capi_driver. This structure must be filled with the name and revision of the
-driver, and optionally a pointer to a callback function, add_card(). The
-registration can be revoked by calling the function unregister_capi_driver()
-with a pointer to the same struct capi_driver.
-
-CAPI drivers must register each of the ISDN devices they control with Kernel
-CAPI by calling the Kernel CAPI function attach_capi_ctr() with a pointer to a
-struct capi_ctr before they can be used. This structure must be filled with
-the names of the driver and controller, and a number of callback function
-pointers which are subsequently used by Kernel CAPI for communicating with the
-driver. The registration can be revoked by calling the function
-detach_capi_ctr() with a pointer to the same struct capi_ctr.
-
-Before the device can be actually used, the driver must fill in the device
-information fields 'manu', 'version', 'profile' and 'serial' in the capi_ctr
-structure of the device, and signal its readiness by calling capi_ctr_ready().
-From then on, Kernel CAPI may call the registered callback functions for the
-device.
-
-If the device becomes unusable for any reason (shutdown, disconnect ...), the
-driver has to call capi_ctr_down(). This will prevent further calls to the
-callback functions by Kernel CAPI.
-
-
-3. Application Registration and Communication
-
-Kernel CAPI forwards registration requests from applications (calls to CAPI
-operation CAPI_REGISTER) to an appropriate hardware driver by calling its
-register_appl() callback function. A unique Application ID (ApplID, u16) is
-allocated by Kernel CAPI and passed to register_appl() along with the
-parameter structure provided by the application. This is analogous to the
-open() operation on regular files or character devices.
-
-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. 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
-ApplID as with register_appl(). After return from release_appl(), no CAPI
-messages for that application may be passed to or from the device anymore.
-
-
-4. Data Structures
-
-4.1 struct capi_driver
-
-This structure describes a Kernel CAPI driver itself. It is used in the
-register_capi_driver() and unregister_capi_driver() functions, and contains
-the following non-private fields, all to be set by the driver before calling
-register_capi_driver():
-
-char name[32]
-       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
-int (*add_card)(struct capi_driver *driver, capicardparams *data)
-       a callback function pointer (may be NULL)
-
-
-4.2 struct capi_ctr
-
-This structure describes an ISDN device (controller) handled by a Kernel CAPI
-driver. After registration via the attach_capi_ctr() function it is passed to
-all controller specific lower layer interface and callback functions to
-identify the controller to operate on.
-
-It contains the following non-private fields:
-
-- to be set by the driver before calling attach_capi_ctr():
-
-struct module *owner
-       pointer to the driver module owning the device
-
-void *driverdata
-       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
-
-char *driver_name
-       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
-       The function may return before the operation has completed.
-       Completion must be signalled by a call to capi_ctr_ready().
-       Return value: 0 on success, error code on error
-       Called in process context.
-
-void (*reset_ctr)(struct capi_ctr *ctrlr)
-       (optional) pointer to a callback function for stopping the device,
-       releasing all registered applications
-       The function may return before the operation has completed.
-       Completion must be signalled by a call to capi_ctr_down().
-       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
-
-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():
-
-u8 manu[CAPI_MANUFACTURER_LEN]
-       value to return for CAPI_GET_MANUFACTURER
-
-capi_version version
-       value to return for CAPI_GET_VERSION
-
-capi_profile profile
-       value to return for CAPI_GET_PROFILE
-
-u8 serial[CAPI_SERIAL_LEN]
-       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 accommodate the resulting CAPI message.
-
-
-5. Lower Layer Interface Functions
-
-(declared in <linux/isdn/capilli.h>)
-
-void register_capi_driver(struct capi_driver *drvr)
-void unregister_capi_driver(struct capi_driver *drvr)
-       register/unregister a driver with Kernel CAPI
-
-int attach_capi_ctr(struct capi_ctr *ctrlr)
-int detach_capi_ctr(struct capi_ctr *ctrlr)
-       register/unregister a device (controller) with Kernel CAPI
-
-void capi_ctr_ready(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)
-void capi_ctr_resume_output(struct capi_ctr *ctrlr)
-       signal suspend/resume
-
-void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid,
-                               struct sk_buff *skb)
-       pass a received CAPI message to Kernel CAPI
-       for forwarding to the specified application
-
-
-6. Helper Functions and Macros
-
-Library functions (from <linux/isdn/capilli.h>):
-
-void capilib_new_ncci(struct list_head *head, u16 applid,
-                       u32 ncci, u32 winsize)
-void capilib_free_ncci(struct list_head *head, u16 applid, u32 ncci)
-void capilib_release_appl(struct list_head *head, u16 applid)
-void capilib_release(struct list_head *head)
-void capilib_data_b3_conf(struct list_head *head, u16 applid,
-                       u32 ncci, u16 msgid)
-u16  capilib_data_b3_req(struct list_head *head, u16 applid,
-                       u32 ncci, u16 msgid)
-
-
-Macros to extract/set element values from/in a CAPI message header
-(from <linux/isdn/capiutil.h>):
-
-Get Macro              Set Macro                       Element (Type)
-
-CAPIMSG_LEN(m)         CAPIMSG_SETLEN(m, len)          Total Length (u16)
-CAPIMSG_APPID(m)       CAPIMSG_SETAPPID(m, applid)     ApplID (u16)
-CAPIMSG_COMMAND(m)     CAPIMSG_SETCOMMAND(m,cmd)       Command (u8)
-CAPIMSG_SUBCOMMAND(m)  CAPIMSG_SETSUBCOMMAND(m, cmd)   Subcommand (u8)
-CAPIMSG_CMD(m)         -                               Command*256
-                                                       + Subcommand (u16)
-CAPIMSG_MSGID(m)       CAPIMSG_SETMSGID(m, msgid)      Message Number (u16)
-
-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.
-
-
-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.