[PATCH RFC] Documentation/isdn/INTERFACE.CAPI

[Tilman Schmidt <tilman@imap.cc>]

[-- Attachment #1: Type: text/plain, Size: 6264 bytes --]

In the course of my efforts to deduce the kernel CAPI hardware driver
interface from the existing driver sources in drivers/isdn/hardware,
I started to collect what I found out into a document INTERFACE.CAPI
analogous to the existing INTERFACE documents for the old isdn4linux
subsystem. I include the current state below and would welcome any
comments and corrections.

Open questions so far:

- Is there any rule or convention for the contents and format of the
  entries in /proc/capi/controller and /proc/capi/controllers/*?

- What is the benefit of registering/unregistering the driver itself
  with register_capi_driver()/unregister_capi_driver()? In particular,
  when and to what purpose is the add_card() callback used?

More questions are sure to follow once I get on with figuring out the
workings of the callback functions register_appl()/release_appl(). :-)

Thanks,
Tilman

diff --git a/Documentation/isdn/00-INDEX b/Documentation/isdn/00-INDEX
index 33543ac..f33110a 100644
--- a/Documentation/isdn/00-INDEX
+++ b/Documentation/isdn/00-INDEX
@@ -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
diff --git a/Documentation/isdn/INTERFACE.CAPI b/Documentation/isdn/INTERFACE.CAPI
new file mode 100644
index 0000000..d7112ac
--- /dev/null
+++ b/Documentation/isdn/INTERFACE.CAPI
@@ -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
+

-- 
Tilman Schmidt                    E-Mail: tilman@imap.cc
Bonn, Germany
Diese Nachricht besteht zu 100% aus wiederverwerteten Bits.
Ungeöffnet mindestens haltbar bis: (siehe Rückseite)


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 254 bytes --]