^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) =========================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) Kernel CAPI Interface to Hardware Drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) =========================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) 1. Overview
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) ===========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) From the CAPI 2.0 specification:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) COMMON-ISDN-API (CAPI) is an application programming interface standard used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) to access ISDN equipment connected to basic rate interfaces (BRI) and primary
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) rate interfaces (PRI).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) Kernel CAPI operates as a dispatching layer between CAPI applications and CAPI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) hardware drivers. Hardware drivers register ISDN devices (controllers, in CAPI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) lingo) with Kernel CAPI to indicate their readiness to provide their service
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) to CAPI applications. CAPI applications also register with Kernel CAPI,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) requesting association with a CAPI device. Kernel CAPI then dispatches the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) application registration to an available device, forwarding it to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) corresponding hardware driver. Kernel CAPI then forwards CAPI messages in both
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) directions between the application and the hardware driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) Format and semantics of CAPI messages are specified in the CAPI 2.0 standard.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) This standard is freely available from https://www.capi.org.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) 2. Driver and Device Registration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) =================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) CAPI drivers must register each of the ISDN devices they control with Kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) CAPI by calling the Kernel CAPI function attach_capi_ctr() with a pointer to a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) struct capi_ctr before they can be used. This structure must be filled with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) the names of the driver and controller, and a number of callback function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) pointers which are subsequently used by Kernel CAPI for communicating with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) driver. The registration can be revoked by calling the function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) detach_capi_ctr() with a pointer to the same struct capi_ctr.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) Before the device can be actually used, the driver must fill in the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) information fields 'manu', 'version', 'profile' and 'serial' in the capi_ctr
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) structure of the device, and signal its readiness by calling capi_ctr_ready().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) From then on, Kernel CAPI may call the registered callback functions for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) If the device becomes unusable for any reason (shutdown, disconnect ...), the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) driver has to call capi_ctr_down(). This will prevent further calls to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) callback functions by Kernel CAPI.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) 3. Application Registration and Communication
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) =============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) Kernel CAPI forwards registration requests from applications (calls to CAPI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) operation CAPI_REGISTER) to an appropriate hardware driver by calling its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) register_appl() callback function. A unique Application ID (ApplID, u16) is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) allocated by Kernel CAPI and passed to register_appl() along with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) parameter structure provided by the application. This is analogous to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) open() operation on regular files or character devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) After a successful return from register_appl(), CAPI messages from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) application may be passed to the driver for the device via calls to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) send_message() callback function. Conversely, the driver may call Kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) CAPI's capi_ctr_handle_message() function to pass a received CAPI message to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) Kernel CAPI for forwarding to an application, specifying its ApplID.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) Deregistration requests (CAPI operation CAPI_RELEASE) from applications are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) forwarded as calls to the release_appl() callback function, passing the same
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) ApplID as with register_appl(). After return from release_appl(), no CAPI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) messages for that application may be passed to or from the device anymore.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) 4. Data Structures
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) ==================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) 4.1 struct capi_driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) ----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) This structure describes a Kernel CAPI driver itself. It is used in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) register_capi_driver() and unregister_capi_driver() functions, and contains
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) the following non-private fields, all to be set by the driver before calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) register_capi_driver():
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) ``char name[32]``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) the name of the driver, as a zero-terminated ASCII string
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) ``char revision[32]``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) the revision number of the driver, as a zero-terminated ASCII string
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) 4.2 struct capi_ctr
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) -------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) This structure describes an ISDN device (controller) handled by a Kernel CAPI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) driver. After registration via the attach_capi_ctr() function it is passed to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) all controller specific lower layer interface and callback functions to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) identify the controller to operate on.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) It contains the following non-private fields:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) to be set by the driver before calling attach_capi_ctr():
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) ``struct module *owner``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) pointer to the driver module owning the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) ``void *driverdata``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) an opaque pointer to driver specific data, not touched by Kernel CAPI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) ``char name[32]``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) the name of the controller, as a zero-terminated ASCII string
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) ``char *driver_name``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) the name of the driver, as a zero-terminated ASCII string
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) ``int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) (optional) pointer to a callback function for sending firmware and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) configuration data to the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) The function may return before the operation has completed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) Completion must be signalled by a call to capi_ctr_ready().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) Return value: 0 on success, error code on error
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) Called in process context.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) ``void (*reset_ctr)(struct capi_ctr *ctrlr)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) (optional) pointer to a callback function for stopping the device,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) releasing all registered applications
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) The function may return before the operation has completed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) Completion must be signalled by a call to capi_ctr_down().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) Called in process context.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) ``void (*register_appl)(struct capi_ctr *ctrlr, u16 applid, capi_register_params *rparam)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) pointers to callback function for registration of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) applications with the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) Calls to these functions are serialized by Kernel CAPI so that only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) one call to any of them is active at any time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) ``void (*release_appl)(struct capi_ctr *ctrlr, u16 applid)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) pointers to callback functions deregistration of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) applications with the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) Calls to these functions are serialized by Kernel CAPI so that only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) one call to any of them is active at any time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) ``u16 (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) pointer to a callback function for sending a CAPI message to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) Return value: CAPI error code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) If the method returns 0 (CAPI_NOERROR) the driver has taken ownership
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) of the skb and the caller may no longer access it. If it returns a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) non-zero (error) value then ownership of the skb returns to the caller
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) who may reuse or free it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) The return value should only be used to signal problems with respect
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) to accepting or queueing the message. Errors occurring during the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) actual processing of the message should be signaled with an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) appropriate reply message.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) May be called in process or interrupt context.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) Calls to this function are not serialized by Kernel CAPI, ie. it must
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) be prepared to be re-entered.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) ``char *(*procinfo)(struct capi_ctr *ctrlr)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) pointer to a callback function returning the entry for the device in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) the CAPI controller info table, /proc/capi/controller
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) Note:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) Callback functions except send_message() are never called in interrupt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) context.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) to be filled in before calling capi_ctr_ready():
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) ``u8 manu[CAPI_MANUFACTURER_LEN]``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) value to return for CAPI_GET_MANUFACTURER
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) ``capi_version version``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) value to return for CAPI_GET_VERSION
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) ``capi_profile profile``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) value to return for CAPI_GET_PROFILE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) ``u8 serial[CAPI_SERIAL_LEN]``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) value to return for CAPI_GET_SERIAL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) 4.3 SKBs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) --------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) CAPI messages are passed between Kernel CAPI and the driver via send_message()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) and capi_ctr_handle_message(), stored in the data portion of a socket buffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) (skb). Each skb contains a single CAPI message coded according to the CAPI 2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) standard.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) For the data transfer messages, DATA_B3_REQ and DATA_B3_IND, the actual
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) payload data immediately follows the CAPI message itself within the same skb.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) The Data and Data64 parameters are not used for processing. The Data64
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) parameter may be omitted by setting the length field of the CAPI message to 22
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) instead of 30.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) 4.4 The _cmsg Structure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) -----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) (declared in <linux/isdn/capiutil.h>)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) The _cmsg structure stores the contents of a CAPI 2.0 message in an easily
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) accessible form. It contains members for all possible CAPI 2.0 parameters,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) including subparameters of the Additional Info and B Protocol structured
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) parameters, with the following exceptions:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) * second Calling party number (CONNECT_IND)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) * Data64 (DATA_B3_REQ and DATA_B3_IND)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) * Sending complete (subparameter of Additional Info, CONNECT_REQ and INFO_REQ)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) * Global Configuration (subparameter of B Protocol, CONNECT_REQ, CONNECT_RESP
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) and SELECT_B_PROTOCOL_REQ)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) Only those parameters appearing in the message type currently being processed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) are actually used. Unused members should be set to zero.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) Members are named after the CAPI 2.0 standard names of the parameters they
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) represent. See <linux/isdn/capiutil.h> for the exact spelling. Member data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) types are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) =========== =================================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) u8 for CAPI parameters of type 'byte'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) u16 for CAPI parameters of type 'word'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) u32 for CAPI parameters of type 'dword'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) _cstruct for CAPI parameters of type 'struct'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) The member is a pointer to a buffer containing the parameter in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) CAPI encoding (length + content). It may also be NULL, which will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) be taken to represent an empty (zero length) parameter.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) Subparameters are stored in encoded form within the content part.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) _cmstruct alternative representation for CAPI parameters of type 'struct'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) (used only for the 'Additional Info' and 'B Protocol' parameters)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) The representation is a single byte containing one of the values:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) CAPI_DEFAULT: The parameter is empty/absent.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) CAPI_COMPOSE: The parameter is present.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) Subparameter values are stored individually in the corresponding
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) _cmsg structure members.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) =========== =================================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) 5. Lower Layer Interface Functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) ==================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) int attach_capi_ctr(struct capi_ctr *ctrlr)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) int detach_capi_ctr(struct capi_ctr *ctrlr)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) register/unregister a device (controller) with Kernel CAPI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) void capi_ctr_ready(struct capi_ctr *ctrlr)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) void capi_ctr_down(struct capi_ctr *ctrlr)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) signal controller ready/not ready
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) struct sk_buff *skb)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) pass a received CAPI message to Kernel CAPI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) for forwarding to the specified application
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) 6. Helper Functions and Macros
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) ==============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) Macros to extract/set element values from/in a CAPI message header
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) (from <linux/isdn/capiutil.h>):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) ====================== ============================= ====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) Get Macro Set Macro Element (Type)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) ====================== ============================= ====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) CAPIMSG_LEN(m) CAPIMSG_SETLEN(m, len) Total Length (u16)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) CAPIMSG_APPID(m) CAPIMSG_SETAPPID(m, applid) ApplID (u16)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) CAPIMSG_COMMAND(m) CAPIMSG_SETCOMMAND(m,cmd) Command (u8)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) CAPIMSG_SUBCOMMAND(m) CAPIMSG_SETSUBCOMMAND(m, cmd) Subcommand (u8)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) CAPIMSG_CMD(m) - Command*256
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) + Subcommand (u16)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) CAPIMSG_MSGID(m) CAPIMSG_SETMSGID(m, msgid) Message Number (u16)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) CAPIMSG_CONTROL(m) CAPIMSG_SETCONTROL(m, contr) Controller/PLCI/NCCI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) (u32)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) CAPIMSG_DATALEN(m) CAPIMSG_SETDATALEN(m, len) Data Length (u16)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) ====================== ============================= ====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) Library functions for working with _cmsg structures
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) (from <linux/isdn/capiutil.h>):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) ``char *capi_cmd2str(u8 Command, u8 Subcommand)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) Returns the CAPI 2.0 message name corresponding to the given command
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) and subcommand values, as a static ASCII string. The return value may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) be NULL if the command/subcommand is not one of those defined in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) CAPI 2.0 standard.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) 7. Debugging
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) The module kernelcapi has a module parameter showcapimsgs controlling some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) debugging output produced by the module. It can only be set when the module is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) loaded, via a parameter "showcapimsgs=<n>" to the modprobe command, either on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) the command line or in the configuration file.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) If the lowest bit of showcapimsgs is set, kernelcapi logs controller and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) application up and down events.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) In addition, every registered CAPI controller has an associated traceflag
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) parameter controlling how CAPI messages sent from and to tha controller are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) logged. The traceflag parameter is initialized with the value of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) showcapimsgs parameter when the controller is registered, but can later be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) changed via the MANUFACTURER_REQ command KCAPI_CMD_TRACE.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) If the value of traceflag is non-zero, CAPI messages are logged.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) DATA_B3 messages are only logged if the value of traceflag is > 2.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) If the lowest bit of traceflag is set, only the command/subcommand and message
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) length are logged. Otherwise, kernelcapi logs a readable representation of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) the entire message.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags