Documentation/isdn/INTERFACE.CAPI
Subsystems (3)
RFC PATCH 1/1 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
Documentation/isdn/00-INDEX +2 -0
@@ -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
Documentation/isdn/INTERFACE.CAPI new file +111 -0
111 lines not on this page · raw message
Signature · 4 lines
Tilman Schmidt E-Mail: [email protected] Bonn, Germany Diese Nachricht besteht zu 100% aus wiederverwerteten Bits. Ungeöffnet mindestens haltbar bis: (siehe Rückseite)
RFC PATCH v2 1/1 Documentation/isdn/INTERFACE.CAPI
isdn: document Kernel CAPI driver interface
Create a file Documentation/isdn/INTERFACE.CAPI describing the interface between the kernel CAPI subsystem and ISDN device drivers, analogous to the existing Documentation/isdn/INTERFACE for the old isdn4linux subsystem. Also add kerneldoc comments to the exported functions in drivers/isdn/capi/kcapi.c.
Impact: Documentation
---
Second, expanded draft. Hopefully better formatted mail. Expanded recipient list. Comments? Anything?
Documentation/isdn/00-INDEX | 2 Documentation/isdn/INTERFACE.CAPI | 207 ++++++++++++++++++++++++++++ drivers/isdn/capi/kcapi.c | 171 +++++++++++++++++++++++ 3 files changed, 380 insertions(+)
Documentation/isdn/00-INDEX +2 -0
@@ -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
Documentation/isdn/INTERFACE.CAPI new file +207 -0
207 lines not on this page · raw message
drivers/isdn/capi/kcapi.c +171 -0
285 lines not on this page · raw message
David Miller
maintainerFrom: Tilman Schmidt <[email protected]>
Date: Tue, 21 Apr 2009 11:18:52 +0200 (CEST)
Quoted 10 lines
isdn: document Kernel CAPI driver interface
Create a file
Documentation/isdn/INTERFACE.CAPIdescribing the interface between the kernel CAPI subsystem and ISDN device drivers, analogous to the existingDocumentation/isdn/INTERFACEfor the old isdn4linux subsystem. Also add kerneldoc comments to the exported functions indrivers/isdn/capi/kcapi.c.Impact: Documentation
Signed-off-by Tilman Schmidt <[email protected]>
If someone can give this a general review, I'll queue it up in net-2.6
Thanks!
David Miller
maintainerFrom: Tilman Schmidt <[email protected]>
Date: Tue, 21 Apr 2009 11:18:52 +0200 (CEST)
Documentation/isdn/00-INDEX INTERFACE · line 15
Quoted 9 lines
Documentation/isdn/00-INDEX +2
-0@@ -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
There is no INTERFACE.fax entry in this file in the current tree.
I wanted to apply this, but aparently your patch is against something other than Linus's tree or net-2.6
Quoted 15 lines · On Mittwoch, 22. April 2009 11:31:42 David Miller wrote:
From: Tilman Schmidt <[email protected]>
Date: Tue, 21 Apr 2009 11:18:52 +0200 (CEST)Documentation/isdn/00-INDEX INTERFACE · line 15
Quoted 9 lines
Documentation/isdn/00-INDEX +2
-0@@ -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.FAQThere is no INTERFACE.fax entry in this file in the current tree.
Seems the file was never updated from the old CVS version.
Quoted 3 lines
I wanted to apply this, but aparently your patch is against something other than Linus's tree or net-2.6
I will send a new signed patch after review in few hours.
Thanks to Tilman for this work.
Karsten
Quoted 17 lines · Karsten Keil
Quoted 15 lines · On Mittwoch, 22. April 2009 11:31:42 David Miller wrote:
From: Tilman Schmidt <[email protected]>
Date: Tue, 21 Apr 2009 11:18:52 +0200 (CEST)Documentation/isdn/00-INDEX INTERFACE · line 15
Quoted 9 lines
Documentation/isdn/00-INDEX +2
-0@@ -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.FAQThere is no INTERFACE.fax entry in this file in the current tree.
Quoted 8 lines
Seems the file was never updated from the old CVS version.
Quoted 3 lines
I wanted to apply this, but aparently your patch is against something other than Linus's tree or net-2.6
I will send a new signed patch after review in few hours.
Thanks to Tilman for this work.
Try copying Randy on the patch - he is good at reviewing documentation.
Sam
Quoted 16 lines · David Miller
From: Tilman Schmidt <[email protected]>
Date: Tue, 21 Apr 2009 11:18:52 +0200 (CEST)Documentation/isdn/00-INDEX INTERFACE · line 15
Quoted 9 lines
Documentation/isdn/00-INDEX +2
-0@@ -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.FAQThere is no INTERFACE.fax entry in this file in the current tree.
Quoted 2 lines
I wanted to apply this, but aparently your patch is against something other than Linus's tree or net-2.6
It applies on top of my mis-dated patch
Subject: [PATCH v2] update Documentation/isdn/00-INDEX
Date: Mon, 17 Nov 2008 14:01:32 +0100
which I sent in fact on 7 Apr 2009. Somehow I thought you had already applied that.
If it helps, I can re-send that one with the correct date, or alternatively merge both of these patches into one.
Regards,
Tilman
Signature · 4 lines
Tilman Schmidt E-Mail: [email protected] Bonn, Germany Diese Nachricht besteht zu 100% aus wiederverwerteten Bits. Ungeöffnet mindestens haltbar bis: (siehe Rückseite)
Quoted 38 lines · Tilman Schmidt
isdn: document Kernel CAPI driver interface
Create a file
Documentation/isdn/INTERFACE.CAPIdescribing the interface between the kernel CAPI subsystem and ISDN device drivers, analogous to the existingDocumentation/isdn/INTERFACEfor the old isdn4linux subsystem. Also add kerneldoc comments to the exported functions indrivers/isdn/capi/kcapi.c.Impact: Documentation
Signed-off-by Tilman Schmidt <[email protected]>---
Second, expanded draft. Hopefully better formatted mail. Expanded recipient list. Comments? Anything?Documentation/isdn/00-INDEX | 2 Documentation/isdn/INTERFACE.CAPI | 207 ++++++++++++++++++++++++++++ drivers/isdn/capi/kcapi.c | 171 +++++++++++++++++++++++ 3 files changed, 380 insertions(+)Documentation/isdn/00-INDEX +2
-0@@ -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.FAQDocumentation/isdn/INTERFACE.CAPI new file +0
-0
Documentation/isdn/INTERFACE.CAPI line 5
Quoted 5 lines
Documentation/isdn/INTERFACE.CAPI new file +5
-0@@ -0,0 +1,207 @@ +Kernel CAPI Interface to Hardware Drivers +----------------------------------------- + +1. Overview +
Should say what CAPI means, please.
Quoted 41 lines
Documentation/isdn/INTERFACE.CAPI new file +41
-0+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. + + +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
Documentation/isdn/INTERFACE.CAPI line 56
Quoted 10 lines
Documentation/isdn/INTERFACE.CAPI new file +10
-0+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 a skb. Conversely, the driver may call Kernel CAPI's
I would say/write "an skb."
Documentation/isdn/INTERFACE.CAPI line 60
Quoted 4 lines
Documentation/isdn/INTERFACE.CAPI new file +4
-0+capi_ctr_handle_message() function to pass a received CAPI message to Kernel +CAPI for forwarding to an application, specifying its ApplID. + +Format and semantics of CAPI messages are specified in the CAPI 2.0 standard.
(googles) which happens to be availble at www.capi.org.
Quoted 8 lines
Documentation/isdn/INTERFACE.CAPI new file +8
-0+ +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
Documentation/isdn/INTERFACE.CAPI line 78
Quoted 10 lines
Documentation/isdn/INTERFACE.CAPI new file +10
-0+ +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
zero-terminated
(or) null-terminated
Documentation/isdn/INTERFACE.CAPI line 80
Quoted 2 lines
Documentation/isdn/INTERFACE.CAPI new file +2
-0+char revision[32] + the revision number of the driver, as a zero terminated ASCII string
ditto
Quoted 13 lines
Documentation/isdn/INTERFACE.CAPI new file +13
-0+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: +
Documentation/isdn/INTERFACE.CAPI line 103
Quoted 10 lines
Documentation/isdn/INTERFACE.CAPI new file +10
-0+- 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
(ditto, above/below)
drivers/isdn/capi/kcapi.c
Quoted 108 lines
Documentation/isdn/INTERFACE.CAPI new file +104
-0+ +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) +drivers/isdn/capi/kcapi.c +0
-0
kernel-doc changes look good.
Nice job. Thanks.
~Randy