~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

TOMOYO Linux Cross Reference
Linux/Documentation/isdn/interface_capi.rst

Version: ~ [ linux-6.12-rc7 ] ~ [ linux-6.11.7 ] ~ [ linux-6.10.14 ] ~ [ linux-6.9.12 ] ~ [ linux-6.8.12 ] ~ [ linux-6.7.12 ] ~ [ linux-6.6.60 ] ~ [ linux-6.5.13 ] ~ [ linux-6.4.16 ] ~ [ linux-6.3.13 ] ~ [ linux-6.2.16 ] ~ [ linux-6.1.116 ] ~ [ linux-6.0.19 ] ~ [ linux-5.19.17 ] ~ [ linux-5.18.19 ] ~ [ linux-5.17.15 ] ~ [ linux-5.16.20 ] ~ [ linux-5.15.171 ] ~ [ linux-5.14.21 ] ~ [ linux-5.13.19 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.229 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.285 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.323 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.336 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.337 ] ~ [ linux-4.4.302 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.12 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

Diff markup

Differences between /Documentation/isdn/interface_capi.rst (Version linux-6.12-rc7) and /Documentation/isdn/interface_capi.rst (Version linux-4.14.336)


  1 =========================================         
  2 Kernel CAPI Interface to Hardware Drivers         
  3 =========================================         
  4                                                   
  5 1. Overview                                       
  6 ===========                                       
  7                                                   
  8 From the CAPI 2.0 specification:                  
  9 COMMON-ISDN-API (CAPI) is an application progr    
 10 to access ISDN equipment connected to basic ra    
 11 rate interfaces (PRI).                            
 12                                                   
 13 Kernel CAPI operates as a dispatching layer be    
 14 hardware drivers. Hardware drivers register IS    
 15 lingo) with Kernel CAPI to indicate their read    
 16 to CAPI applications. CAPI applications also r    
 17 requesting association with a CAPI device. Ker    
 18 application registration to an available devic    
 19 corresponding hardware driver. Kernel CAPI the    
 20 directions between the application and the har    
 21                                                   
 22 Format and semantics of CAPI messages are spec    
 23 This standard is freely available from https:/    
 24                                                   
 25                                                   
 26 2. Driver and Device Registration                 
 27 =================================                 
 28                                                   
 29 CAPI drivers must register each of the ISDN de    
 30 CAPI by calling the Kernel CAPI function attac    
 31 struct capi_ctr before they can be used. This     
 32 the names of the driver and controller, and a     
 33 pointers which are subsequently used by Kernel    
 34 driver. The registration can be revoked by cal    
 35 detach_capi_ctr() with a pointer to the same s    
 36                                                   
 37 Before the device can be actually used, the dr    
 38 information fields 'manu', 'version', 'profile    
 39 structure of the device, and signal its readin    
 40 From then on, Kernel CAPI may call the registe    
 41 device.                                           
 42                                                   
 43 If the device becomes unusable for any reason     
 44 driver has to call capi_ctr_down(). This will     
 45 callback functions by Kernel CAPI.                
 46                                                   
 47                                                   
 48 3. Application Registration and Communication     
 49 =============================================     
 50                                                   
 51 Kernel CAPI forwards registration requests fro    
 52 operation CAPI_REGISTER) to an appropriate har    
 53 register_appl() callback function. A unique Ap    
 54 allocated by Kernel CAPI and passed to registe    
 55 parameter structure provided by the applicatio    
 56 open() operation on regular files or character    
 57                                                   
 58 After a successful return from register_appl()    
 59 application may be passed to the driver for th    
 60 send_message() callback function. Conversely,     
 61 CAPI's capi_ctr_handle_message() function to p    
 62 Kernel CAPI for forwarding to an application,     
 63                                                   
 64 Deregistration requests (CAPI operation CAPI_R    
 65 forwarded as calls to the release_appl() callb    
 66 ApplID as with register_appl(). After return f    
 67 messages for that application may be passed to    
 68                                                   
 69                                                   
 70 4. Data Structures                                
 71 ==================                                
 72                                                   
 73 4.1 struct capi_driver                            
 74 ----------------------                            
 75                                                   
 76 This structure describes a Kernel CAPI driver     
 77 register_capi_driver() and unregister_capi_dri    
 78 the following non-private fields, all to be se    
 79 register_capi_driver():                           
 80                                                   
 81 ``char name[32]``                                 
 82         the name of the driver, as a zero-term    
 83 ``char revision[32]``                             
 84         the revision number of the driver, as     
 85                                                   
 86 4.2 struct capi_ctr                               
 87 -------------------                               
 88                                                   
 89 This structure describes an ISDN device (contr    
 90 driver. After registration via the attach_capi    
 91 all controller specific lower layer interface     
 92 identify the controller to operate on.            
 93                                                   
 94 It contains the following non-private fields:     
 95                                                   
 96 to be set by the driver before calling attach_    
 97 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^    
 98                                                   
 99 ``struct module *owner``                          
100         pointer to the driver module owning th    
101                                                   
102 ``void *driverdata``                              
103         an opaque pointer to driver specific d    
104                                                   
105 ``char name[32]``                                 
106         the name of the controller, as a zero-    
107                                                   
108 ``char *driver_name``                             
109         the name of the driver, as a zero-term    
110                                                   
111 ``int (*load_firmware)(struct capi_ctr *ctrlr,    
112         (optional) pointer to a callback funct    
113         configuration data to the device          
114                                                   
115         The function may return before the ope    
116                                                   
117         Completion must be signalled by a call    
118                                                   
119         Return value: 0 on success, error code    
120         Called in process context.                
121                                                   
122 ``void (*reset_ctr)(struct capi_ctr *ctrlr)``     
123         (optional) pointer to a callback funct    
124         releasing all registered applications     
125                                                   
126         The function may return before the ope    
127                                                   
128         Completion must be signalled by a call    
129                                                   
130         Called in process context.                
131                                                   
132 ``void (*register_appl)(struct capi_ctr *ctrlr    
133         pointers to callback function for regi    
134         applications with the device              
135                                                   
136         Calls to these functions are serialize    
137         one call to any of them is active at a    
138                                                   
139 ``void (*release_appl)(struct capi_ctr *ctrlr,    
140         pointers to callback functions deregis    
141         applications with the device              
142                                                   
143         Calls to these functions are serialize    
144         one call to any of them is active at a    
145                                                   
146 ``u16  (*send_message)(struct capi_ctr *ctrlr,    
147         pointer to a callback function for sen    
148         device                                    
149                                                   
150         Return value: CAPI error code             
151                                                   
152         If the method returns 0 (CAPI_NOERROR)    
153         of the skb and the caller may no longe    
154         non-zero (error) value then ownership     
155         who may reuse or free it.                 
156                                                   
157         The return value should only be used t    
158         to accepting or queueing the message.     
159         actual processing of the message shoul    
160         appropriate reply message.                
161                                                   
162         May be called in process or interrupt     
163                                                   
164         Calls to this function are not seriali    
165         be prepared to be re-entered.             
166                                                   
167 ``char *(*procinfo)(struct capi_ctr *ctrlr)``     
168         pointer to a callback function returni    
169         the CAPI controller info table, /proc/    
170                                                   
171 Note:                                             
172   Callback functions except send_message() are    
173   context.                                        
174                                                   
175 to be filled in before calling capi_ctr_ready(    
176 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^    
177                                                   
178 ``u8 manu[CAPI_MANUFACTURER_LEN]``                
179         value to return for CAPI_GET_MANUFACTU    
180                                                   
181 ``capi_version version``                          
182         value to return for CAPI_GET_VERSION      
183                                                   
184 ``capi_profile profile``                          
185         value to return for CAPI_GET_PROFILE      
186                                                   
187 ``u8 serial[CAPI_SERIAL_LEN]``                    
188         value to return for CAPI_GET_SERIAL       
189                                                   
190                                                   
191 4.3 SKBs                                          
192 --------                                          
193                                                   
194 CAPI messages are passed between Kernel CAPI a    
195 and capi_ctr_handle_message(), stored in the d    
196 (skb).  Each skb contains a single CAPI messag    
197 standard.                                         
198                                                   
199 For the data transfer messages, DATA_B3_REQ an    
200 payload data immediately follows the CAPI mess    
201 The Data and Data64 parameters are not used fo    
202 parameter may be omitted by setting the length    
203 instead of 30.                                    
204                                                   
205                                                   
206 4.4 The _cmsg Structure                           
207 -----------------------                           
208                                                   
209 (declared in <linux/isdn/capiutil.h>)             
210                                                   
211 The _cmsg structure stores the contents of a C    
212 accessible form. It contains members for all p    
213 including subparameters of the Additional Info    
214 parameters, with the following exceptions:        
215                                                   
216 * second Calling party number (CONNECT_IND)       
217                                                   
218 * Data64 (DATA_B3_REQ and DATA_B3_IND)            
219                                                   
220 * Sending complete (subparameter of Additional    
221                                                   
222 * Global Configuration (subparameter of B Prot    
223   and SELECT_B_PROTOCOL_REQ)                      
224                                                   
225 Only those parameters appearing in the message    
226 are actually used. Unused members should be se    
227                                                   
228 Members are named after the CAPI 2.0 standard     
229 represent. See <linux/isdn/capiutil.h> for the    
230 types are:                                        
231                                                   
232 =========== ==================================    
233 u8          for CAPI parameters of type 'byte'    
234                                                   
235 u16         for CAPI parameters of type 'word'    
236                                                   
237 u32         for CAPI parameters of type 'dword    
238                                                   
239 _cstruct    for CAPI parameters of type 'struc    
240             The member is a pointer to a buffe    
241             CAPI encoding (length + content).     
242             be taken to represent an empty (ze    
243             Subparameters are stored in encode    
244                                                   
245 _cmstruct   alternative representation for CAP    
246             (used only for the 'Additional Inf    
247             The representation is a single byt    
248             CAPI_DEFAULT: The parameter is emp    
249             CAPI_COMPOSE: The parameter is pre    
250             Subparameter values are stored ind    
251             _cmsg structure members.              
252 =========== ==================================    
253                                                   
254                                                   
255 5. Lower Layer Interface Functions                
256 ==================================                
257                                                   
258 ::                                                
259                                                   
260   int attach_capi_ctr(struct capi_ctr *ctrlr)     
261   int detach_capi_ctr(struct capi_ctr *ctrlr)     
262                                                   
263 register/unregister a device (controller) with    
264                                                   
265 ::                                                
266                                                   
267   void capi_ctr_ready(struct capi_ctr *ctrlr)     
268   void capi_ctr_down(struct capi_ctr *ctrlr)      
269                                                   
270 signal controller ready/not ready                 
271                                                   
272 ::                                                
273                                                   
274   void capi_ctr_handle_message(struct capi_ctr    
275                                struct sk_buff     
276                                                   
277 pass a received CAPI message to Kernel CAPI       
278 for forwarding to the specified application       
279                                                   
280                                                   
281 6. Helper Functions and Macros                    
282 ==============================                    
283                                                   
284 Macros to extract/set element values from/in a    
285 (from <linux/isdn/capiutil.h>):                   
286                                                   
287 ======================  ======================    
288 Get Macro               Set Macro                 
289 ======================  ======================    
290 CAPIMSG_LEN(m)          CAPIMSG_SETLEN(m, len)    
291 CAPIMSG_APPID(m)        CAPIMSG_SETAPPID(m, ap    
292 CAPIMSG_COMMAND(m)      CAPIMSG_SETCOMMAND(m,c    
293 CAPIMSG_SUBCOMMAND(m)   CAPIMSG_SETSUBCOMMAND(    
294 CAPIMSG_CMD(m)          -                         
295                                                   
296 CAPIMSG_MSGID(m)        CAPIMSG_SETMSGID(m, ms    
297                                                   
298 CAPIMSG_CONTROL(m)      CAPIMSG_SETCONTROL(m,     
299                                                   
300 CAPIMSG_DATALEN(m)      CAPIMSG_SETDATALEN(m,     
301 ======================  ======================    
302                                                   
303                                                   
304 Library functions for working with _cmsg struc    
305 (from <linux/isdn/capiutil.h>):                   
306                                                   
307 ``char *capi_cmd2str(u8 Command, u8 Subcommand    
308         Returns the CAPI 2.0 message name corr    
309         and subcommand values, as a static ASC    
310         be NULL if the command/subcommand is n    
311         CAPI 2.0 standard.                        
312                                                   
313                                                   
314 7. Debugging                                      
315 ============                                      
316                                                   
317 The module kernelcapi has a module parameter s    
318 debugging output produced by the module. It ca    
319 loaded, via a parameter "showcapimsgs=<n>" to     
320 the command line or in the configuration file.    
321                                                   
322 If the lowest bit of showcapimsgs is set, kern    
323 application up and down events.                   
324                                                   
325 In addition, every registered CAPI controller     
326 parameter controlling how CAPI messages sent f    
327 logged. The traceflag parameter is initialized    
328 showcapimsgs parameter when the controller is     
329 changed via the MANUFACTURER_REQ command KCAPI    
330                                                   
331 If the value of traceflag is non-zero, CAPI me    
332 DATA_B3 messages are only logged if the value     
333                                                   
334 If the lowest bit of traceflag is set, only th    
335 length are logged. Otherwise, kernelcapi logs     
336 the entire message.                               
                                                      

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

kernel.org | git.kernel.org | LWN.net | Project Home | SVN repository | Mail admin

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

sflogo.php