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