Kernel CAPI Interface to Hardware Drivers¶
1. Overview¶
From the CAPI 2.0 specification:COMMON-ISDN-API (CAPI) is an application programming interface standard usedto access ISDN equipment connected to basic rate interfaces (BRI) and primaryrate interfaces (PRI).
Kernel CAPI operates as a dispatching layer between CAPI applications and CAPIhardware drivers. Hardware drivers register ISDN devices (controllers, in CAPIlingo) with Kernel CAPI to indicate their readiness to provide their serviceto CAPI applications. CAPI applications also register with Kernel CAPI,requesting association with a CAPI device. Kernel CAPI then dispatches theapplication registration to an available device, forwarding it to thecorresponding hardware driver. Kernel CAPI then forwards CAPI messages in bothdirections 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 fromhttps://www.capi.org.
2. Driver and Device Registration¶
CAPI drivers must register each of the ISDN devices they control with KernelCAPI by calling the Kernel CAPI function attach_capi_ctr() with a pointer to astruct capi_ctr before they can be used. This structure must be filled withthe names of the driver and controller, and a number of callback functionpointers which are subsequently used by Kernel CAPI for communicating with thedriver. The registration can be revoked by calling the functiondetach_capi_ctr() with a pointer to the same struct capi_ctr.
Before the device can be actually used, the driver must fill in the deviceinformation fields ‘manu’, ‘version’, ‘profile’ and ‘serial’ in the capi_ctrstructure of the device, and signal its readiness by calling capi_ctr_ready().From then on, Kernel CAPI may call the registered callback functions for thedevice.
If the device becomes unusable for any reason (shutdown, disconnect …), thedriver has to call capi_ctr_down(). This will prevent further calls to thecallback functions by Kernel CAPI.
3. Application Registration and Communication¶
Kernel CAPI forwards registration requests from applications (calls to CAPIoperation CAPI_REGISTER) to an appropriate hardware driver by calling itsregister_appl() callback function. A unique Application ID (ApplID, u16) isallocated by Kernel CAPI and passed to register_appl() along with theparameter structure provided by the application. This is analogous to theopen() operation on regular files or character devices.
After a successful return from register_appl(), CAPI messages from theapplication may be passed to the driver for the device via calls to thesend_message() callback function. Conversely, the driver may call KernelCAPI’s capi_ctr_handle_message() function to pass a received CAPI message toKernel CAPI for forwarding to an application, specifying its ApplID.
Deregistration requests (CAPI operation CAPI_RELEASE) from applications areforwarded as calls to the release_appl() callback function, passing the sameApplID as with register_appl(). After return from release_appl(), no CAPImessages 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 theregister_capi_driver() and unregister_capi_driver() functions, and containsthe following non-private fields, all to be set by the driver before callingregister_capi_driver():
charname[32]- the name of the driver, as a zero-terminated ASCII string
charrevision[32]- the revision number of the driver, as a zero-terminated ASCII string
4.2 struct capi_ctr¶
This structure describes an ISDN device (controller) handled by a Kernel CAPIdriver. After registration via the attach_capi_ctr() function it is passed toall controller specific lower layer interface and callback functions toidentify the controller to operate on.
It contains the following non-private fields:
to be set by the driver before calling attach_capi_ctr():¶
structmodule*owner- pointer to the driver module owning the device
void*driverdata- an opaque pointer to driver specific data, not touched by Kernel CAPI
charname[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)(structcapi_ctr*ctrlr,capiloaddata*ldata)(optional) pointer to a callback function for sending firmware andconfiguration data to the device
The function may return before the operation has completed.
Completion must be signalled by a call to capi_ctr_ready().
Return value: 0 on success, error code on errorCalled in process context.
void(*reset_ctr)(structcapi_ctr*ctrlr)(optional) pointer to a callback function for stopping the device,releasing all registered applications
The function may return before the operation has completed.
Completion must be signalled by a call to capi_ctr_down().
Called in process context.
void(*register_appl)(structcapi_ctr*ctrlr,u16applid,capi_register_params*rparam)pointers to callback function for registration ofapplications with the device
Calls to these functions are serialized by Kernel CAPI so that onlyone call to any of them is active at any time.
void(*release_appl)(structcapi_ctr*ctrlr,u16applid)pointers to callback functions deregistration ofapplications with the device
Calls to these functions are serialized by Kernel CAPI so that onlyone call to any of them is active at any time.
u16 (*send_message)(structcapi_ctr*ctrlr,structsk_buff*skb)pointer to a callback function for sending a CAPI message to thedevice
Return value: CAPI error code
If the method returns 0 (CAPI_NOERROR) the driver has taken ownershipof the skb and the caller may no longer access it. If it returns anon-zero (error) value then ownership of the skb returns to the callerwho may reuse or free it.
The return value should only be used to signal problems with respectto accepting or queueing the message. Errors occurring during theactual processing of the message should be signaled with anappropriate reply message.
May be called in process or interrupt context.
Calls to this function are not serialized by Kernel CAPI, ie. it mustbe prepared to be re-entered.
char*(*procinfo)(structcapi_ctr*ctrlr)- pointer to a callback function returning the entry for the device inthe CAPI controller info table, /proc/capi/controller
- Note:
- Callback functions except send_message() are never called in interruptcontext.
to be filled in before calling capi_ctr_ready():¶
u8manu[CAPI_MANUFACTURER_LEN]- value to return for CAPI_GET_MANUFACTURER
capi_versionversion- value to return for CAPI_GET_VERSION
capi_profileprofile- value to return for CAPI_GET_PROFILE
u8serial[CAPI_SERIAL_LEN]- value to return for CAPI_GET_SERIAL
4.3 SKBs¶
CAPI messages are passed between Kernel CAPI and the driver via send_message()and capi_ctr_handle_message(), stored in the data portion of a socket buffer(skb). Each skb contains a single CAPI message coded according to the CAPI 2.0standard.
For the data transfer messages, DATA_B3_REQ and DATA_B3_IND, the actualpayload data immediately follows the CAPI message itself within the same skb.The Data and Data64 parameters are not used for processing. The Data64parameter may be omitted by setting the length field of the CAPI message to 22instead of 30.
4.4 The _cmsg Structure¶
(declared in <linux/isdn/capiutil.h>)
The _cmsg structure stores the contents of a CAPI 2.0 message in an easilyaccessible form. It contains members for all possible CAPI 2.0 parameters,including subparameters of the Additional Info and B Protocol structuredparameters, with the following exceptions:
- second Calling party number (CONNECT_IND)
- Data64 (DATA_B3_REQ and DATA_B3_IND)
- Sending complete (subparameter of Additional Info, CONNECT_REQ and INFO_REQ)
- Global Configuration (subparameter of B Protocol, CONNECT_REQ, CONNECT_RESPand SELECT_B_PROTOCOL_REQ)
Only those parameters appearing in the message type currently being processedare actually used. Unused members should be set to zero.
Members are named after the CAPI 2.0 standard names of the parameters theyrepresent. See <linux/isdn/capiutil.h> for the exact spelling. Member datatypes are:
| u8 | for CAPI parameters of type ‘byte’ |
| u16 | for CAPI parameters of type ‘word’ |
| u32 | for CAPI parameters of type ‘dword’ |
| _cstruct | for CAPI parameters of type ‘struct’The member is a pointer to a buffer containing the parameter inCAPI encoding (length + content). It may also be NULL, which willbe taken to represent an empty (zero length) parameter.Subparameters are stored in encoded form within the content part. |
| _cmstruct | alternative representation for CAPI parameters of type ‘struct’(used only for the ‘Additional Info’ and ‘B Protocol’ parameters)The representation is a single byte containing one of the values:CAPI_DEFAULT: The parameter is empty/absent.CAPI_COMPOSE: The parameter is present.Subparameter values are stored individually in the corresponding_cmsg structure members. |
5. Lower Layer Interface Functions¶
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_down(struct capi_ctr *ctrlr)
signal controller ready/not ready
void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid, struct sk_buff *skb)
pass a received CAPI message to Kernel CAPIfor forwarding to the specified application
6. Helper Functions and Macros¶
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) |
Library functions for working with _cmsg structures(from <linux/isdn/capiutil.h>):
char*capi_cmd2str(u8Command,u8Subcommand)- Returns the CAPI 2.0 message name corresponding to the given commandand subcommand values, as a static ASCII string. The return value maybe NULL if the command/subcommand is not one of those defined in theCAPI 2.0 standard.
7. Debugging¶
The module kernelcapi has a module parameter showcapimsgs controlling somedebugging output produced by the module. It can only be set when the module isloaded, via a parameter “showcapimsgs=<n>” to the modprobe command, either onthe command line or in the configuration file.
If the lowest bit of showcapimsgs is set, kernelcapi logs controller andapplication up and down events.
In addition, every registered CAPI controller has an associated traceflagparameter controlling how CAPI messages sent from and to tha controller arelogged. The traceflag parameter is initialized with the value of theshowcapimsgs parameter when the controller is registered, but can later bechanged via the MANUFACTURER_REQ command KCAPI_CMD_TRACE.
If the value of traceflag is non-zero, CAPI messages are logged.DATA_B3 messages are only logged if the value of traceflag is > 2.
If the lowest bit of traceflag is set, only the command/subcommand and messagelength are logged. Otherwise, kernelcapi logs a readable representation ofthe entire message.