@@ -8,6 +8,8 @@ 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
new file mode 100644
@@ -0,0 +1,111 @@
+Kernel CAPI Interface to Hardware Drivers
+-----------------------------------------
+
+1. Overview
+
+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.
+
+
+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.
+
+
+3. Data Structures
+
+3.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)
+
+
+3.2 struct capi_ctr
+
+This structure describes an ISDN device (controller) handled by a Kernel CAPI
+driver. It is used in the attach_capi_ctr() and detach_capi_ctr() functions,
+and 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 *card, capiloaddata *ldata)
+ (optional) pointer to a callback function for loading firmware into
+ the device
+
+void (*reset_ctr)(struct capi_ctr *card)
+ pointer to a callback function for performing a reset on the device,
+ releasing all registered applications
+
+void (*register_appl)(struct capi_ctr *card, u16 applid,
+ capi_register_params *rparam)
+void (*release_appl)(struct capi_ctr *card, u16 applid)
+u16 (*send_message)(struct capi_ctr *card, struct sk_buff *skb)
+ callback function pointers for driver operation
+
+char *(*procinfo)(struct capi_ctr *card)
+ 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 the ready callback (whatever that means):
+
+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. Functions
+
+tbc
+