i386/linux/linux-2.3.21/Documentation/networking/lapb-module.txt

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