summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorDavid S. Miller <davem@davemloft.net>2009-04-29 20:30:35 -0700
committerDavid S. Miller <davem@davemloft.net>2009-04-29 20:30:35 -0700
commitaba7453037c3a90714caae77a622dceaf1173786 (patch)
treebf07f9f432b0d8e9db9486f1f32ad065c0aa7c5c /Documentation
parenta4fe91ee711f4e955ea85ab05b092cfe384b073e (diff)
parent93af7aca44f0e82e67bda10a0fb73d383edcc8bd (diff)
Merge branch 'master' of master.kernel.org:/pub/scm/linux/kernel/git/davem/net-2.6
Conflicts: Documentation/isdn/00-INDEX drivers/net/wireless/iwlwifi/iwl-scan.c drivers/net/wireless/rndis_wlan.c net/mac80211/main.c
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/isdn/00-INDEX17
-rw-r--r--Documentation/isdn/INTERFACE.CAPI213
2 files changed, 229 insertions, 1 deletions
diff --git a/Documentation/isdn/00-INDEX b/Documentation/isdn/00-INDEX
index 33543ac7d81f..f6010a536590 100644
--- a/Documentation/isdn/00-INDEX
+++ b/Documentation/isdn/00-INDEX
@@ -8,10 +8,21 @@ INTERFACE
- description of isdn4linux Link Level and Hardware Level interfaces.
INTERFACE.fax
- description of the fax subinterface of isdn4linux.
+INTERFACE.CAPI
+ - description of kernel CAPI Link Level to Hardware Level interface.
README
- general info on what you need and what to do for Linux ISDN.
README.FAQ
- general info for FAQ.
+README.audio
+ - info for running audio over ISDN.
+README.fax
+ - info for using Fax over ISDN.
+README.gigaset
+ - info on the drivers for Siemens Gigaset ISDN adapters.
+README.icn
+ - info on the ICN-ISDN-card and its driver.
+>>>>>>> 93af7aca44f0e82e67bda10a0fb73d383edcc8bd:Documentation/isdn/00-INDEX
README.HiSax
- info on the HiSax driver which replaces the old teles.
README.audio
@@ -45,6 +56,10 @@ README.sc
README.syncppp
- info on running Sync PPP over ISDN.
README.x25
- - info on running X.25 over ISDN.
+ - info for running X.25 over ISDN.
syncPPP.FAQ
- frequently asked questions about running PPP over ISDN.
+README.hysdn
+ - info on driver for Hypercope active HYSDN cards
+README.mISDN
+ - info on the Modular ISDN subsystem (mISDN).
diff --git a/Documentation/isdn/INTERFACE.CAPI b/Documentation/isdn/INTERFACE.CAPI
new file mode 100644
index 000000000000..786d619b36e5
--- /dev/null
+++ b/Documentation/isdn/INTERFACE.CAPI
@@ -0,0 +1,213 @@
+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 http://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_reseted(). 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. 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.
+
+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
+
+void (*reset_ctr)(struct capi_ctr *ctrlr)
+ pointer to a callback function for performing a reset on the device,
+ releasing all registered applications
+
+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
+
+u16 (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb)
+ pointer to a callback function for sending a CAPI message to the
+ device
+
+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
+
+- 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
+
+
+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_reseted(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)
+