fe93299a00
Clarify calling context and return codes of callback methods, and add a description of the _cmsg structure and helper functions. Impact: documentation Signed-off-by: Tilman Schmidt <tilman@imap.cc> Signed-off-by: David S. Miller <davem@davemloft.net>
300 lines
12 KiB
Plaintext
300 lines
12 KiB
Plaintext
Kernel CAPI Interface to Hardware Drivers
|
|
-----------------------------------------
|
|
|
|
1. Overview
|
|
|
|
From the CAPI 2.0 specification:
|
|
COMMON-ISDN-API (CAPI) is an application programming interface standard used
|
|
to access ISDN equipment connected to basic rate interfaces (BRI) and primary
|
|
rate interfaces (PRI).
|
|
|
|
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.
|
|
|
|
Format and semantics of CAPI messages are specified in the CAPI 2.0 standard.
|
|
This standard is freely available from http://www.capi.org.
|
|
|
|
|
|
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_down(). 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
|
|
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 an skb. Conversely, the driver may call Kernel CAPI's
|
|
capi_ctr_handle_message() function to pass a received CAPI message to Kernel
|
|
CAPI for forwarding to an application, specifying its ApplID.
|
|
|
|
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
|
|
|
|
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
|
|
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)
|
|
|
|
|
|
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:
|
|
|
|
- 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 *ctrlr, capiloaddata *ldata)
|
|
(optional) pointer to a callback function for sending firmware and
|
|
configuration data to the device
|
|
Return value: 0 on success, error code on error
|
|
Called in process context.
|
|
|
|
void (*reset_ctr)(struct capi_ctr *ctrlr)
|
|
(optional) pointer to a callback function for performing a reset on
|
|
the device, releasing all registered applications
|
|
Called in process context.
|
|
|
|
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
|
|
Calls to these functions are serialized by Kernel CAPI so that only
|
|
one call to any of them is active at any time.
|
|
|
|
u16 (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb)
|
|
pointer to a callback function for sending a CAPI message to the
|
|
device
|
|
Return value: CAPI error code
|
|
If the method returns 0 (CAPI_NOERROR) the driver has taken ownership
|
|
of the skb and the caller may no longer access it. If it returns a
|
|
non-zero (error) value then ownership of the skb returns to the caller
|
|
who may reuse or free it.
|
|
The return value should only be used to signal problems with respect
|
|
to accepting or queueing the message. Errors occurring during the
|
|
actual processing of the message should be signaled with an
|
|
appropriate reply message.
|
|
Calls to this function are not serialized by Kernel CAPI, ie. it must
|
|
be prepared to be re-entered.
|
|
|
|
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
|
|
|
|
Note: Callback functions are never called in interrupt context.
|
|
|
|
- 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
|
|
|
|
|
|
4.3 The _cmsg Structure
|
|
|
|
(declared in <linux/isdn/capiutil.h>)
|
|
|
|
The _cmsg structure stores the contents of a CAPI 2.0 message in an easily
|
|
accessible form. It contains members for all possible CAPI 2.0 parameters, of
|
|
which only those appearing in the message type currently being processed are
|
|
actually used. Unused members should be set to zero.
|
|
|
|
Members are named after the CAPI 2.0 standard names of the parameters they
|
|
represent. See <linux/isdn/capiutil.h> for the exact spelling. Member data
|
|
types 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' not containing any
|
|
variably-sized (struct) subparameters (eg. 'Called Party Number')
|
|
The member is a pointer to a buffer containing the parameter in
|
|
CAPI encoding (length + content). It may also be NULL, which will
|
|
be taken to represent an empty (zero length) parameter.
|
|
|
|
_cmstruct for CAPI parameters of type 'struct' containing 'struct'
|
|
subparameters ('Additional Info' and 'B Protocol')
|
|
The representation is a single byte containing one of the values:
|
|
CAPI_DEFAULT: the parameter is empty
|
|
CAPI_COMPOSE: the values of the subparameters are stored
|
|
individually in the corresponding _cmsg structure members
|
|
|
|
Functions capi_cmsg2message() and capi_message2cmsg() are provided to convert
|
|
messages between their transport encoding described in the CAPI 2.0 standard
|
|
and their _cmsg structure representation. Note that capi_cmsg2message() does
|
|
not know or check the size of its destination buffer. The caller must make
|
|
sure it is big enough to accomodate the resulting CAPI message.
|
|
|
|
|
|
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_down(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)
|
|
|
|
|
|
Library functions for working with _cmsg structures
|
|
(from <linux/isdn/capiutil.h>):
|
|
|
|
unsigned capi_cmsg2message(_cmsg *cmsg, u8 *msg)
|
|
Assembles a CAPI 2.0 message from the parameters in *cmsg, storing the
|
|
result in *msg.
|
|
|
|
unsigned capi_message2cmsg(_cmsg *cmsg, u8 *msg)
|
|
Disassembles the CAPI 2.0 message in *msg, storing the parameters in
|
|
*cmsg.
|
|
|
|
unsigned capi_cmsg_header(_cmsg *cmsg, u16 ApplId, u8 Command, u8 Subcommand,
|
|
u16 Messagenumber, u32 Controller)
|
|
Fills the header part and address field of the _cmsg structure *cmsg
|
|
with the given values, zeroing the remainder of the structure so only
|
|
parameters with non-default values need to be changed before sending
|
|
the message.
|
|
|
|
void capi_cmsg_answer(_cmsg *cmsg)
|
|
Sets the low bit of the Subcommand field in *cmsg, thereby converting
|
|
_REQ to _CONF and _IND to _RESP.
|
|
|
|
char *capi_cmd2str(u8 Command, u8 Subcommand)
|
|
Returns the CAPI 2.0 message name corresponding to the given command
|
|
and subcommand values, as a static ASCII string. The return value may
|
|
be NULL if the command/subcommand is not one of those defined in the
|
|
CAPI 2.0 standard.
|
|
|