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