Messages in this thread Patch in this message | | | Date | Tue, 14 Apr 2009 21:53:46 +0200 | From | Tilman Schmidt <> | Subject | [PATCH RFC] Documentation/isdn/INTERFACE.CAPI |
| |
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)
[unhandled content-type:application/pgp-signature] | |