0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ===============================
0004 The Linux LAPB Module Interface
0005 ===============================
0006
0007 Version 1.3
0008
0009 Jonathan Naylor 29.12.96
0010
0011 Changed (Henner Eisen, 2000-10-29): int return value for data_indication()
0012
0013 The LAPB module will be a separately compiled module for use by any parts of
0014 the Linux operating system that require a LAPB service. This document
0015 defines the interfaces to, and the services provided by this module. The
0016 term module in this context does not imply that the LAPB module is a
0017 separately loadable module, although it may be. The term module is used in
0018 its more standard meaning.
0019
0020 The interface to the LAPB module consists of functions to the module,
0021 callbacks from the module to indicate important state changes, and
0022 structures for getting and setting information about the module.
0023
0024 Structures
0025 ----------
0026
0027 Probably the most important structure is the skbuff structure for holding
0028 received and transmitted data, however it is beyond the scope of this
0029 document.
0030
0031 The two LAPB specific structures are the LAPB initialisation structure and
0032 the LAPB parameter structure. These will be defined in a standard header
0033 file, <linux/lapb.h>. The header file <net/lapb.h> is internal to the LAPB
0034 module and is not for use.
0035
0036 LAPB Initialisation Structure
0037 -----------------------------
0038
0039 This structure is used only once, in the call to lapb_register (see below).
0040 It contains information about the device driver that requires the services
0041 of the LAPB module::
0042
0043 struct lapb_register_struct {
0044 void (*connect_confirmation)(int token, int reason);
0045 void (*connect_indication)(int token, int reason);
0046 void (*disconnect_confirmation)(int token, int reason);
0047 void (*disconnect_indication)(int token, int reason);
0048 int (*data_indication)(int token, struct sk_buff *skb);
0049 void (*data_transmit)(int token, struct sk_buff *skb);
0050 };
0051
0052 Each member of this structure corresponds to a function in the device driver
0053 that is called when a particular event in the LAPB module occurs. These will
0054 be described in detail below. If a callback is not required (!!) then a NULL
0055 may be substituted.
0056
0057
0058 LAPB Parameter Structure
0059 ------------------------
0060
0061 This structure is used with the lapb_getparms and lapb_setparms functions
0062 (see below). They are used to allow the device driver to get and set the
0063 operational parameters of the LAPB implementation for a given connection::
0064
0065 struct lapb_parms_struct {
0066 unsigned int t1;
0067 unsigned int t1timer;
0068 unsigned int t2;
0069 unsigned int t2timer;
0070 unsigned int n2;
0071 unsigned int n2count;
0072 unsigned int window;
0073 unsigned int state;
0074 unsigned int mode;
0075 };
0076
0077 T1 and T2 are protocol timing parameters and are given in units of 100ms. N2
0078 is the maximum number of tries on the link before it is declared a failure.
0079 The window size is the maximum number of outstanding data packets allowed to
0080 be unacknowledged by the remote end, the value of the window is between 1
0081 and 7 for a standard LAPB link, and between 1 and 127 for an extended LAPB
0082 link.
0083
0084 The mode variable is a bit field used for setting (at present) three values.
0085 The bit fields have the following meanings:
0086
0087 ====== =================================================
0088 Bit Meaning
0089 ====== =================================================
0090 0 LAPB operation (0=LAPB_STANDARD 1=LAPB_EXTENDED).
0091 1 [SM]LP operation (0=LAPB_SLP 1=LAPB=MLP).
0092 2 DTE/DCE operation (0=LAPB_DTE 1=LAPB_DCE)
0093 3-31 Reserved, must be 0.
0094 ====== =================================================
0095
0096 Extended LAPB operation indicates the use of extended sequence numbers and
0097 consequently larger window sizes, the default is standard LAPB operation.
0098 MLP operation is the same as SLP operation except that the addresses used by
0099 LAPB are different to indicate the mode of operation, the default is Single
0100 Link Procedure. The difference between DCE and DTE operation is (i) the
0101 addresses used for commands and responses, and (ii) when the DCE is not
0102 connected, it sends DM without polls set, every T1. The upper case constant
0103 names will be defined in the public LAPB header file.
0104
0105
0106 Functions
0107 ---------
0108
0109 The LAPB module provides a number of function entry points.
0110
0111 ::
0112
0113 int lapb_register(void *token, struct lapb_register_struct);
0114
0115 This must be called before the LAPB module may be used. If the call is
0116 successful then LAPB_OK is returned. The token must be a unique identifier
0117 generated by the device driver to allow for the unique identification of the
0118 instance of the LAPB link. It is returned by the LAPB module in all of the
0119 callbacks, and is used by the device driver in all calls to the LAPB module.
0120 For multiple LAPB links in a single device driver, multiple calls to
0121 lapb_register must be made. The format of the lapb_register_struct is given
0122 above. The return values are:
0123
0124 ============= =============================
0125 LAPB_OK LAPB registered successfully.
0126 LAPB_BADTOKEN Token is already registered.
0127 LAPB_NOMEM Out of memory
0128 ============= =============================
0129
0130 ::
0131
0132 int lapb_unregister(void *token);
0133
0134 This releases all the resources associated with a LAPB link. Any current
0135 LAPB link will be abandoned without further messages being passed. After
0136 this call, the value of token is no longer valid for any calls to the LAPB
0137 function. The valid return values are:
0138
0139 ============= ===============================
0140 LAPB_OK LAPB unregistered successfully.
0141 LAPB_BADTOKEN Invalid/unknown LAPB token.
0142 ============= ===============================
0143
0144 ::
0145
0146 int lapb_getparms(void *token, struct lapb_parms_struct *parms);
0147
0148 This allows the device driver to get the values of the current LAPB
0149 variables, the lapb_parms_struct is described above. The valid return values
0150 are:
0151
0152 ============= =============================
0153 LAPB_OK LAPB getparms was successful.
0154 LAPB_BADTOKEN Invalid/unknown LAPB token.
0155 ============= =============================
0156
0157 ::
0158
0159 int lapb_setparms(void *token, struct lapb_parms_struct *parms);
0160
0161 This allows the device driver to set the values of the current LAPB
0162 variables, the lapb_parms_struct is described above. The values of t1timer,
0163 t2timer and n2count are ignored, likewise changing the mode bits when
0164 connected will be ignored. An error implies that none of the values have
0165 been changed. The valid return values are:
0166
0167 ============= =================================================
0168 LAPB_OK LAPB getparms was successful.
0169 LAPB_BADTOKEN Invalid/unknown LAPB token.
0170 LAPB_INVALUE One of the values was out of its allowable range.
0171 ============= =================================================
0172
0173 ::
0174
0175 int lapb_connect_request(void *token);
0176
0177 Initiate a connect using the current parameter settings. The valid return
0178 values are:
0179
0180 ============== =================================
0181 LAPB_OK LAPB is starting to connect.
0182 LAPB_BADTOKEN Invalid/unknown LAPB token.
0183 LAPB_CONNECTED LAPB module is already connected.
0184 ============== =================================
0185
0186 ::
0187
0188 int lapb_disconnect_request(void *token);
0189
0190 Initiate a disconnect. The valid return values are:
0191
0192 ================= ===============================
0193 LAPB_OK LAPB is starting to disconnect.
0194 LAPB_BADTOKEN Invalid/unknown LAPB token.
0195 LAPB_NOTCONNECTED LAPB module is not connected.
0196 ================= ===============================
0197
0198 ::
0199
0200 int lapb_data_request(void *token, struct sk_buff *skb);
0201
0202 Queue data with the LAPB module for transmitting over the link. If the call
0203 is successful then the skbuff is owned by the LAPB module and may not be
0204 used by the device driver again. The valid return values are:
0205
0206 ================= =============================
0207 LAPB_OK LAPB has accepted the data.
0208 LAPB_BADTOKEN Invalid/unknown LAPB token.
0209 LAPB_NOTCONNECTED LAPB module is not connected.
0210 ================= =============================
0211
0212 ::
0213
0214 int lapb_data_received(void *token, struct sk_buff *skb);
0215
0216 Queue data with the LAPB module which has been received from the device. It
0217 is expected that the data passed to the LAPB module has skb->data pointing
0218 to the beginning of the LAPB data. If the call is successful then the skbuff
0219 is owned by the LAPB module and may not be used by the device driver again.
0220 The valid return values are:
0221
0222 ============= ===========================
0223 LAPB_OK LAPB has accepted the data.
0224 LAPB_BADTOKEN Invalid/unknown LAPB token.
0225 ============= ===========================
0226
0227 Callbacks
0228 ---------
0229
0230 These callbacks are functions provided by the device driver for the LAPB
0231 module to call when an event occurs. They are registered with the LAPB
0232 module with lapb_register (see above) in the structure lapb_register_struct
0233 (see above).
0234
0235 ::
0236
0237 void (*connect_confirmation)(void *token, int reason);
0238
0239 This is called by the LAPB module when a connection is established after
0240 being requested by a call to lapb_connect_request (see above). The reason is
0241 always LAPB_OK.
0242
0243 ::
0244
0245 void (*connect_indication)(void *token, int reason);
0246
0247 This is called by the LAPB module when the link is established by the remote
0248 system. The value of reason is always LAPB_OK.
0249
0250 ::
0251
0252 void (*disconnect_confirmation)(void *token, int reason);
0253
0254 This is called by the LAPB module when an event occurs after the device
0255 driver has called lapb_disconnect_request (see above). The reason indicates
0256 what has happened. In all cases the LAPB link can be regarded as being
0257 terminated. The values for reason are:
0258
0259 ================= ====================================================
0260 LAPB_OK The LAPB link was terminated normally.
0261 LAPB_NOTCONNECTED The remote system was not connected.
0262 LAPB_TIMEDOUT No response was received in N2 tries from the remote
0263 system.
0264 ================= ====================================================
0265
0266 ::
0267
0268 void (*disconnect_indication)(void *token, int reason);
0269
0270 This is called by the LAPB module when the link is terminated by the remote
0271 system or another event has occurred to terminate the link. This may be
0272 returned in response to a lapb_connect_request (see above) if the remote
0273 system refused the request. The values for reason are:
0274
0275 ================= ====================================================
0276 LAPB_OK The LAPB link was terminated normally by the remote
0277 system.
0278 LAPB_REFUSED The remote system refused the connect request.
0279 LAPB_NOTCONNECTED The remote system was not connected.
0280 LAPB_TIMEDOUT No response was received in N2 tries from the remote
0281 system.
0282 ================= ====================================================
0283
0284 ::
0285
0286 int (*data_indication)(void *token, struct sk_buff *skb);
0287
0288 This is called by the LAPB module when data has been received from the
0289 remote system that should be passed onto the next layer in the protocol
0290 stack. The skbuff becomes the property of the device driver and the LAPB
0291 module will not perform any more actions on it. The skb->data pointer will
0292 be pointing to the first byte of data after the LAPB header.
0293
0294 This method should return NET_RX_DROP (as defined in the header
0295 file include/linux/netdevice.h) if and only if the frame was dropped
0296 before it could be delivered to the upper layer.
0297
0298 ::
0299
0300 void (*data_transmit)(void *token, struct sk_buff *skb);
0301
0302 This is called by the LAPB module when data is to be transmitted to the
0303 remote system by the device driver. The skbuff becomes the property of the
0304 device driver and the LAPB module will not perform any more actions on it.
0305 The skb->data pointer will be pointing to the first byte of the LAPB header.
