0001 =========================================
0002 Kernel CAPI Interface to Hardware Drivers
0003 =========================================
0004
0005 1. Overview
0006 ===========
0007
0008 From the CAPI 2.0 specification:
0009 COMMON-ISDN-API (CAPI) is an application programming interface standard used
0010 to access ISDN equipment connected to basic rate interfaces (BRI) and primary
0011 rate interfaces (PRI).
0012
0013 Kernel CAPI operates as a dispatching layer between CAPI applications and CAPI
0014 hardware drivers. Hardware drivers register ISDN devices (controllers, in CAPI
0015 lingo) with Kernel CAPI to indicate their readiness to provide their service
0016 to CAPI applications. CAPI applications also register with Kernel CAPI,
0017 requesting association with a CAPI device. Kernel CAPI then dispatches the
0018 application registration to an available device, forwarding it to the
0019 corresponding hardware driver. Kernel CAPI then forwards CAPI messages in both
0020 directions between the application and the hardware driver.
0021
0022 Format and semantics of CAPI messages are specified in the CAPI 2.0 standard.
0023 This standard is freely available from https://www.capi.org.
0024
0025
0026 2. Driver and Device Registration
0027 =================================
0028
0029 CAPI drivers must register each of the ISDN devices they control with Kernel
0030 CAPI by calling the Kernel CAPI function attach_capi_ctr() with a pointer to a
0031 struct capi_ctr before they can be used. This structure must be filled with
0032 the names of the driver and controller, and a number of callback function
0033 pointers which are subsequently used by Kernel CAPI for communicating with the
0034 driver. The registration can be revoked by calling the function
0035 detach_capi_ctr() with a pointer to the same struct capi_ctr.
0036
0037 Before the device can be actually used, the driver must fill in the device
0038 information fields 'manu', 'version', 'profile' and 'serial' in the capi_ctr
0039 structure of the device, and signal its readiness by calling capi_ctr_ready().
0040 From then on, Kernel CAPI may call the registered callback functions for the
0041 device.
0042
0043 If the device becomes unusable for any reason (shutdown, disconnect ...), the
0044 driver has to call capi_ctr_down(). This will prevent further calls to the
0045 callback functions by Kernel CAPI.
0046
0047
0048 3. Application Registration and Communication
0049 =============================================
0050
0051 Kernel CAPI forwards registration requests from applications (calls to CAPI
0052 operation CAPI_REGISTER) to an appropriate hardware driver by calling its
0053 register_appl() callback function. A unique Application ID (ApplID, u16) is
0054 allocated by Kernel CAPI and passed to register_appl() along with the
0055 parameter structure provided by the application. This is analogous to the
0056 open() operation on regular files or character devices.
0057
0058 After a successful return from register_appl(), CAPI messages from the
0059 application may be passed to the driver for the device via calls to the
0060 send_message() callback function. Conversely, the driver may call Kernel
0061 CAPI's capi_ctr_handle_message() function to pass a received CAPI message to
0062 Kernel CAPI for forwarding to an application, specifying its ApplID.
0063
0064 Deregistration requests (CAPI operation CAPI_RELEASE) from applications are
0065 forwarded as calls to the release_appl() callback function, passing the same
0066 ApplID as with register_appl(). After return from release_appl(), no CAPI
0067 messages for that application may be passed to or from the device anymore.
0068
0069
0070 4. Data Structures
0071 ==================
0072
0073 4.1 struct capi_driver
0074 ----------------------
0075
0076 This structure describes a Kernel CAPI driver itself. It is used in the
0077 register_capi_driver() and unregister_capi_driver() functions, and contains
0078 the following non-private fields, all to be set by the driver before calling
0079 register_capi_driver():
0080
0081 ``char name[32]``
0082 the name of the driver, as a zero-terminated ASCII string
0083 ``char revision[32]``
0084 the revision number of the driver, as a zero-terminated ASCII string
0085
0086 4.2 struct capi_ctr
0087 -------------------
0088
0089 This structure describes an ISDN device (controller) handled by a Kernel CAPI
0090 driver. After registration via the attach_capi_ctr() function it is passed to
0091 all controller specific lower layer interface and callback functions to
0092 identify the controller to operate on.
0093
0094 It contains the following non-private fields:
0095
0096 to be set by the driver before calling attach_capi_ctr():
0097 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
0098
0099 ``struct module *owner``
0100 pointer to the driver module owning the device
0101
0102 ``void *driverdata``
0103 an opaque pointer to driver specific data, not touched by Kernel CAPI
0104
0105 ``char name[32]``
0106 the name of the controller, as a zero-terminated ASCII string
0107
0108 ``char *driver_name``
0109 the name of the driver, as a zero-terminated ASCII string
0110
0111 ``int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata)``
0112 (optional) pointer to a callback function for sending firmware and
0113 configuration data to the device
0114
0115 The function may return before the operation has completed.
0116
0117 Completion must be signalled by a call to capi_ctr_ready().
0118
0119 Return value: 0 on success, error code on error
0120 Called in process context.
0121
0122 ``void (*reset_ctr)(struct capi_ctr *ctrlr)``
0123 (optional) pointer to a callback function for stopping the device,
0124 releasing all registered applications
0125
0126 The function may return before the operation has completed.
0127
0128 Completion must be signalled by a call to capi_ctr_down().
0129
0130 Called in process context.
0131
0132 ``void (*register_appl)(struct capi_ctr *ctrlr, u16 applid, capi_register_params *rparam)``
0133 pointers to callback function for registration of
0134 applications with the device
0135
0136 Calls to these functions are serialized by Kernel CAPI so that only
0137 one call to any of them is active at any time.
0138
0139 ``void (*release_appl)(struct capi_ctr *ctrlr, u16 applid)``
0140 pointers to callback functions deregistration of
0141 applications with the device
0142
0143 Calls to these functions are serialized by Kernel CAPI so that only
0144 one call to any of them is active at any time.
0145
0146 ``u16 (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb)``
0147 pointer to a callback function for sending a CAPI message to the
0148 device
0149
0150 Return value: CAPI error code
0151
0152 If the method returns 0 (CAPI_NOERROR) the driver has taken ownership
0153 of the skb and the caller may no longer access it. If it returns a
0154 non-zero (error) value then ownership of the skb returns to the caller
0155 who may reuse or free it.
0156
0157 The return value should only be used to signal problems with respect
0158 to accepting or queueing the message. Errors occurring during the
0159 actual processing of the message should be signaled with an
0160 appropriate reply message.
0161
0162 May be called in process or interrupt context.
0163
0164 Calls to this function are not serialized by Kernel CAPI, ie. it must
0165 be prepared to be re-entered.
0166
0167 ``char *(*procinfo)(struct capi_ctr *ctrlr)``
0168 pointer to a callback function returning the entry for the device in
0169 the CAPI controller info table, /proc/capi/controller
0170
0171 Note:
0172 Callback functions except send_message() are never called in interrupt
0173 context.
0174
0175 to be filled in before calling capi_ctr_ready():
0176 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
0177
0178 ``u8 manu[CAPI_MANUFACTURER_LEN]``
0179 value to return for CAPI_GET_MANUFACTURER
0180
0181 ``capi_version version``
0182 value to return for CAPI_GET_VERSION
0183
0184 ``capi_profile profile``
0185 value to return for CAPI_GET_PROFILE
0186
0187 ``u8 serial[CAPI_SERIAL_LEN]``
0188 value to return for CAPI_GET_SERIAL
0189
0190
0191 4.3 SKBs
0192 --------
0193
0194 CAPI messages are passed between Kernel CAPI and the driver via send_message()
0195 and capi_ctr_handle_message(), stored in the data portion of a socket buffer
0196 (skb). Each skb contains a single CAPI message coded according to the CAPI 2.0
0197 standard.
0198
0199 For the data transfer messages, DATA_B3_REQ and DATA_B3_IND, the actual
0200 payload data immediately follows the CAPI message itself within the same skb.
0201 The Data and Data64 parameters are not used for processing. The Data64
0202 parameter may be omitted by setting the length field of the CAPI message to 22
0203 instead of 30.
0204
0205
0206 4.4 The _cmsg Structure
0207 -----------------------
0208
0209 (declared in <linux/isdn/capiutil.h>)
0210
0211 The _cmsg structure stores the contents of a CAPI 2.0 message in an easily
0212 accessible form. It contains members for all possible CAPI 2.0 parameters,
0213 including subparameters of the Additional Info and B Protocol structured
0214 parameters, with the following exceptions:
0215
0216 * second Calling party number (CONNECT_IND)
0217
0218 * Data64 (DATA_B3_REQ and DATA_B3_IND)
0219
0220 * Sending complete (subparameter of Additional Info, CONNECT_REQ and INFO_REQ)
0221
0222 * Global Configuration (subparameter of B Protocol, CONNECT_REQ, CONNECT_RESP
0223 and SELECT_B_PROTOCOL_REQ)
0224
0225 Only those parameters appearing in the message type currently being processed
0226 are actually used. Unused members should be set to zero.
0227
0228 Members are named after the CAPI 2.0 standard names of the parameters they
0229 represent. See <linux/isdn/capiutil.h> for the exact spelling. Member data
0230 types are:
0231
0232 =========== =================================================================
0233 u8 for CAPI parameters of type 'byte'
0234
0235 u16 for CAPI parameters of type 'word'
0236
0237 u32 for CAPI parameters of type 'dword'
0238
0239 _cstruct for CAPI parameters of type 'struct'
0240 The member is a pointer to a buffer containing the parameter in
0241 CAPI encoding (length + content). It may also be NULL, which will
0242 be taken to represent an empty (zero length) parameter.
0243 Subparameters are stored in encoded form within the content part.
0244
0245 _cmstruct alternative representation for CAPI parameters of type 'struct'
0246 (used only for the 'Additional Info' and 'B Protocol' parameters)
0247 The representation is a single byte containing one of the values:
0248 CAPI_DEFAULT: The parameter is empty/absent.
0249 CAPI_COMPOSE: The parameter is present.
0250 Subparameter values are stored individually in the corresponding
0251 _cmsg structure members.
0252 =========== =================================================================
0253
0254
0255 5. Lower Layer Interface Functions
0256 ==================================
0257
0258 ::
0259
0260 int attach_capi_ctr(struct capi_ctr *ctrlr)
0261 int detach_capi_ctr(struct capi_ctr *ctrlr)
0262
0263 register/unregister a device (controller) with Kernel CAPI
0264
0265 ::
0266
0267 void capi_ctr_ready(struct capi_ctr *ctrlr)
0268 void capi_ctr_down(struct capi_ctr *ctrlr)
0269
0270 signal controller ready/not ready
0271
0272 ::
0273
0274 void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid,
0275 struct sk_buff *skb)
0276
0277 pass a received CAPI message to Kernel CAPI
0278 for forwarding to the specified application
0279
0280
0281 6. Helper Functions and Macros
0282 ==============================
0283
0284 Macros to extract/set element values from/in a CAPI message header
0285 (from <linux/isdn/capiutil.h>):
0286
0287 ====================== ============================= ====================
0288 Get Macro Set Macro Element (Type)
0289 ====================== ============================= ====================
0290 CAPIMSG_LEN(m) CAPIMSG_SETLEN(m, len) Total Length (u16)
0291 CAPIMSG_APPID(m) CAPIMSG_SETAPPID(m, applid) ApplID (u16)
0292 CAPIMSG_COMMAND(m) CAPIMSG_SETCOMMAND(m,cmd) Command (u8)
0293 CAPIMSG_SUBCOMMAND(m) CAPIMSG_SETSUBCOMMAND(m, cmd) Subcommand (u8)
0294 CAPIMSG_CMD(m) - Command*256
0295 + Subcommand (u16)
0296 CAPIMSG_MSGID(m) CAPIMSG_SETMSGID(m, msgid) Message Number (u16)
0297
0298 CAPIMSG_CONTROL(m) CAPIMSG_SETCONTROL(m, contr) Controller/PLCI/NCCI
0299 (u32)
0300 CAPIMSG_DATALEN(m) CAPIMSG_SETDATALEN(m, len) Data Length (u16)
0301 ====================== ============================= ====================
0302
0303
0304 Library functions for working with _cmsg structures
0305 (from <linux/isdn/capiutil.h>):
0306
0307 ``char *capi_cmd2str(u8 Command, u8 Subcommand)``
0308 Returns the CAPI 2.0 message name corresponding to the given command
0309 and subcommand values, as a static ASCII string. The return value may
0310 be NULL if the command/subcommand is not one of those defined in the
0311 CAPI 2.0 standard.
0312
0313
0314 7. Debugging
0315 ============
0316
0317 The module kernelcapi has a module parameter showcapimsgs controlling some
0318 debugging output produced by the module. It can only be set when the module is
0319 loaded, via a parameter "showcapimsgs=<n>" to the modprobe command, either on
0320 the command line or in the configuration file.
0321
0322 If the lowest bit of showcapimsgs is set, kernelcapi logs controller and
0323 application up and down events.
0324
0325 In addition, every registered CAPI controller has an associated traceflag
0326 parameter controlling how CAPI messages sent from and to tha controller are
0327 logged. The traceflag parameter is initialized with the value of the
0328 showcapimsgs parameter when the controller is registered, but can later be
0329 changed via the MANUFACTURER_REQ command KCAPI_CMD_TRACE.
0330
0331 If the value of traceflag is non-zero, CAPI messages are logged.
0332 DATA_B3 messages are only logged if the value of traceflag is > 2.
0333
0334 If the lowest bit of traceflag is set, only the command/subcommand and message
0335 length are logged. Otherwise, kernelcapi logs a readable representation of
0336 the entire message.
