1.. SPDX-License-Identifier: GPL-2.0 2 3=============================== 4The Linux LAPB Module Interface 5=============================== 6 7Version 1.3 8 9Jonathan Naylor 29.12.96 10 11Changed (Henner Eisen, 2000-10-29): int return value for data_indication() 12 13The LAPB module will be a separately compiled module for use by any parts of 14the Linux operating system that require a LAPB service. This document 15defines the interfaces to, and the services provided by this module. The 16term module in this context does not imply that the LAPB module is a 17separately loadable module, although it may be. The term module is used in 18its more standard meaning. 19 20The interface to the LAPB module consists of functions to the module, 21callbacks from the module to indicate important state changes, and 22structures for getting and setting information about the module. 23 24Structures 25---------- 26 27Probably the most important structure is the skbuff structure for holding 28received and transmitted data, however it is beyond the scope of this 29document. 30 31The two LAPB specific structures are the LAPB initialisation structure and 32the LAPB parameter structure. These will be defined in a standard header 33file, <linux/lapb.h>. The header file <net/lapb.h> is internal to the LAPB 34module and is not for use. 35 36LAPB Initialisation Structure 37----------------------------- 38 39This structure is used only once, in the call to lapb_register (see below). 40It contains information about the device driver that requires the services 41of the LAPB module:: 42 43 struct lapb_register_struct { 44 void (*connect_confirmation)(int token, int reason); 45 void (*connect_indication)(int token, int reason); 46 void (*disconnect_confirmation)(int token, int reason); 47 void (*disconnect_indication)(int token, int reason); 48 int (*data_indication)(int token, struct sk_buff *skb); 49 void (*data_transmit)(int token, struct sk_buff *skb); 50 }; 51 52Each member of this structure corresponds to a function in the device driver 53that is called when a particular event in the LAPB module occurs. These will 54be described in detail below. If a callback is not required (!!) then a NULL 55may be substituted. 56 57 58LAPB Parameter Structure 59------------------------ 60 61This structure is used with the lapb_getparms and lapb_setparms functions 62(see below). They are used to allow the device driver to get and set the 63operational parameters of the LAPB implementation for a given connection:: 64 65 struct lapb_parms_struct { 66 unsigned int t1; 67 unsigned int t1timer; 68 unsigned int t2; 69 unsigned int t2timer; 70 unsigned int n2; 71 unsigned int n2count; 72 unsigned int window; 73 unsigned int state; 74 unsigned int mode; 75 }; 76 77T1 and T2 are protocol timing parameters and are given in units of 100ms. N2 78is the maximum number of tries on the link before it is declared a failure. 79The window size is the maximum number of outstanding data packets allowed to 80be unacknowledged by the remote end, the value of the window is between 1 81and 7 for a standard LAPB link, and between 1 and 127 for an extended LAPB 82link. 83 84The mode variable is a bit field used for setting (at present) three values. 85The bit fields have the following meanings: 86 87====== ================================================= 88Bit Meaning 89====== ================================================= 900 LAPB operation (0=LAPB_STANDARD 1=LAPB_EXTENDED). 911 [SM]LP operation (0=LAPB_SLP 1=LAPB=MLP). 922 DTE/DCE operation (0=LAPB_DTE 1=LAPB_DCE) 933-31 Reserved, must be 0. 94====== ================================================= 95 96Extended LAPB operation indicates the use of extended sequence numbers and 97consequently larger window sizes, the default is standard LAPB operation. 98MLP operation is the same as SLP operation except that the addresses used by 99LAPB are different to indicate the mode of operation, the default is Single 100Link Procedure. The difference between DCE and DTE operation is (i) the 101addresses used for commands and responses, and (ii) when the DCE is not 102connected, it sends DM without polls set, every T1. The upper case constant 103names will be defined in the public LAPB header file. 104 105 106Functions 107--------- 108 109The LAPB module provides a number of function entry points. 110 111:: 112 113 int lapb_register(void *token, struct lapb_register_struct); 114 115This must be called before the LAPB module may be used. If the call is 116successful then LAPB_OK is returned. The token must be a unique identifier 117generated by the device driver to allow for the unique identification of the 118instance of the LAPB link. It is returned by the LAPB module in all of the 119callbacks, and is used by the device driver in all calls to the LAPB module. 120For multiple LAPB links in a single device driver, multiple calls to 121lapb_register must be made. The format of the lapb_register_struct is given 122above. The return values are: 123 124============= ============================= 125LAPB_OK LAPB registered successfully. 126LAPB_BADTOKEN Token is already registered. 127LAPB_NOMEM Out of memory 128============= ============================= 129 130:: 131 132 int lapb_unregister(void *token); 133 134This releases all the resources associated with a LAPB link. Any current 135LAPB link will be abandoned without further messages being passed. After 136this call, the value of token is no longer valid for any calls to the LAPB 137function. The valid return values are: 138 139============= =============================== 140LAPB_OK LAPB unregistered successfully. 141LAPB_BADTOKEN Invalid/unknown LAPB token. 142============= =============================== 143 144:: 145 146 int lapb_getparms(void *token, struct lapb_parms_struct *parms); 147 148This allows the device driver to get the values of the current LAPB 149variables, the lapb_parms_struct is described above. The valid return values 150are: 151 152============= ============================= 153LAPB_OK LAPB getparms was successful. 154LAPB_BADTOKEN Invalid/unknown LAPB token. 155============= ============================= 156 157:: 158 159 int lapb_setparms(void *token, struct lapb_parms_struct *parms); 160 161This allows the device driver to set the values of the current LAPB 162variables, the lapb_parms_struct is described above. The values of t1timer, 163t2timer and n2count are ignored, likewise changing the mode bits when 164connected will be ignored. An error implies that none of the values have 165been changed. The valid return values are: 166 167============= ================================================= 168LAPB_OK LAPB getparms was successful. 169LAPB_BADTOKEN Invalid/unknown LAPB token. 170LAPB_INVALUE One of the values was out of its allowable range. 171============= ================================================= 172 173:: 174 175 int lapb_connect_request(void *token); 176 177Initiate a connect using the current parameter settings. The valid return 178values are: 179 180============== ================================= 181LAPB_OK LAPB is starting to connect. 182LAPB_BADTOKEN Invalid/unknown LAPB token. 183LAPB_CONNECTED LAPB module is already connected. 184============== ================================= 185 186:: 187 188 int lapb_disconnect_request(void *token); 189 190Initiate a disconnect. The valid return values are: 191 192================= =============================== 193LAPB_OK LAPB is starting to disconnect. 194LAPB_BADTOKEN Invalid/unknown LAPB token. 195LAPB_NOTCONNECTED LAPB module is not connected. 196================= =============================== 197 198:: 199 200 int lapb_data_request(void *token, struct sk_buff *skb); 201 202Queue data with the LAPB module for transmitting over the link. If the call 203is successful then the skbuff is owned by the LAPB module and may not be 204used by the device driver again. The valid return values are: 205 206================= ============================= 207LAPB_OK LAPB has accepted the data. 208LAPB_BADTOKEN Invalid/unknown LAPB token. 209LAPB_NOTCONNECTED LAPB module is not connected. 210================= ============================= 211 212:: 213 214 int lapb_data_received(void *token, struct sk_buff *skb); 215 216Queue data with the LAPB module which has been received from the device. It 217is expected that the data passed to the LAPB module has skb->data pointing 218to the beginning of the LAPB data. If the call is successful then the skbuff 219is owned by the LAPB module and may not be used by the device driver again. 220The valid return values are: 221 222============= =========================== 223LAPB_OK LAPB has accepted the data. 224LAPB_BADTOKEN Invalid/unknown LAPB token. 225============= =========================== 226 227Callbacks 228--------- 229 230These callbacks are functions provided by the device driver for the LAPB 231module to call when an event occurs. They are registered with the LAPB 232module with lapb_register (see above) in the structure lapb_register_struct 233(see above). 234 235:: 236 237 void (*connect_confirmation)(void *token, int reason); 238 239This is called by the LAPB module when a connection is established after 240being requested by a call to lapb_connect_request (see above). The reason is 241always LAPB_OK. 242 243:: 244 245 void (*connect_indication)(void *token, int reason); 246 247This is called by the LAPB module when the link is established by the remote 248system. The value of reason is always LAPB_OK. 249 250:: 251 252 void (*disconnect_confirmation)(void *token, int reason); 253 254This is called by the LAPB module when an event occurs after the device 255driver has called lapb_disconnect_request (see above). The reason indicates 256what has happened. In all cases the LAPB link can be regarded as being 257terminated. The values for reason are: 258 259================= ==================================================== 260LAPB_OK The LAPB link was terminated normally. 261LAPB_NOTCONNECTED The remote system was not connected. 262LAPB_TIMEDOUT No response was received in N2 tries from the remote 263 system. 264================= ==================================================== 265 266:: 267 268 void (*disconnect_indication)(void *token, int reason); 269 270This is called by the LAPB module when the link is terminated by the remote 271system or another event has occurred to terminate the link. This may be 272returned in response to a lapb_connect_request (see above) if the remote 273system refused the request. The values for reason are: 274 275================= ==================================================== 276LAPB_OK The LAPB link was terminated normally by the remote 277 system. 278LAPB_REFUSED The remote system refused the connect request. 279LAPB_NOTCONNECTED The remote system was not connected. 280LAPB_TIMEDOUT No response was received in N2 tries from the remote 281 system. 282================= ==================================================== 283 284:: 285 286 int (*data_indication)(void *token, struct sk_buff *skb); 287 288This is called by the LAPB module when data has been received from the 289remote system that should be passed onto the next layer in the protocol 290stack. The skbuff becomes the property of the device driver and the LAPB 291module will not perform any more actions on it. The skb->data pointer will 292be pointing to the first byte of data after the LAPB header. 293 294This method should return NET_RX_DROP (as defined in the header 295file include/linux/netdevice.h) if and only if the frame was dropped 296before it could be delivered to the upper layer. 297 298:: 299 300 void (*data_transmit)(void *token, struct sk_buff *skb); 301 302This is called by the LAPB module when data is to be transmitted to the 303remote system by the device driver. The skbuff becomes the property of the 304device driver and the LAPB module will not perform any more actions on it. 305The skb->data pointer will be pointing to the first byte of the LAPB header. 306