Commit | Line | Data |
---|---|---|
40e79150 | 1 | .. SPDX-License-Identifier: GPL-2.0 |
1da177e4 | 2 | |
40e79150 MCC |
3 | =============================== |
4 | The Linux LAPB Module Interface | |
5 | =============================== | |
1da177e4 | 6 | |
40e79150 MCC |
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() | |
1da177e4 LT |
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 | |
40e79150 | 41 | of the LAPB module:: |
1da177e4 | 42 | |
40e79150 MCC |
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 | }; | |
1da177e4 LT |
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 | |
40e79150 MCC |
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 | }; | |
1da177e4 LT |
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 | ||
40e79150 | 87 | ====== ================================================= |
1da177e4 | 88 | Bit Meaning |
40e79150 | 89 | ====== ================================================= |
1da177e4 LT |
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. | |
40e79150 | 94 | ====== ================================================= |
1da177e4 LT |
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 | ||
40e79150 | 111 | :: |
1da177e4 | 112 | |
40e79150 | 113 | int lapb_register(void *token, struct lapb_register_struct); |
1da177e4 LT |
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 | ||
40e79150 | 124 | ============= ============================= |
1da177e4 LT |
125 | LAPB_OK LAPB registered successfully. |
126 | LAPB_BADTOKEN Token is already registered. | |
127 | LAPB_NOMEM Out of memory | |
40e79150 | 128 | ============= ============================= |
1da177e4 | 129 | |
40e79150 | 130 | :: |
1da177e4 | 131 | |
40e79150 | 132 | int lapb_unregister(void *token); |
1da177e4 LT |
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 | ||
40e79150 | 139 | ============= =============================== |
1da177e4 LT |
140 | LAPB_OK LAPB unregistered successfully. |
141 | LAPB_BADTOKEN Invalid/unknown LAPB token. | |
40e79150 | 142 | ============= =============================== |
1da177e4 | 143 | |
40e79150 | 144 | :: |
1da177e4 | 145 | |
40e79150 | 146 | int lapb_getparms(void *token, struct lapb_parms_struct *parms); |
1da177e4 LT |
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 | ||
40e79150 | 152 | ============= ============================= |
1da177e4 LT |
153 | LAPB_OK LAPB getparms was successful. |
154 | LAPB_BADTOKEN Invalid/unknown LAPB token. | |
40e79150 | 155 | ============= ============================= |
1da177e4 | 156 | |
40e79150 | 157 | :: |
1da177e4 | 158 | |
40e79150 | 159 | int lapb_setparms(void *token, struct lapb_parms_struct *parms); |
1da177e4 LT |
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 | ||
40e79150 | 167 | ============= ================================================= |
1da177e4 LT |
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. | |
40e79150 | 171 | ============= ================================================= |
1da177e4 | 172 | |
40e79150 | 173 | :: |
1da177e4 | 174 | |
40e79150 | 175 | int lapb_connect_request(void *token); |
1da177e4 LT |
176 | |
177 | Initiate a connect using the current parameter settings. The valid return | |
178 | values are: | |
179 | ||
40e79150 | 180 | ============== ================================= |
1da177e4 LT |
181 | LAPB_OK LAPB is starting to connect. |
182 | LAPB_BADTOKEN Invalid/unknown LAPB token. | |
183 | LAPB_CONNECTED LAPB module is already connected. | |
40e79150 | 184 | ============== ================================= |
1da177e4 | 185 | |
40e79150 | 186 | :: |
1da177e4 | 187 | |
40e79150 | 188 | int lapb_disconnect_request(void *token); |
1da177e4 LT |
189 | |
190 | Initiate a disconnect. The valid return values are: | |
191 | ||
40e79150 | 192 | ================= =============================== |
1da177e4 LT |
193 | LAPB_OK LAPB is starting to disconnect. |
194 | LAPB_BADTOKEN Invalid/unknown LAPB token. | |
195 | LAPB_NOTCONNECTED LAPB module is not connected. | |
40e79150 | 196 | ================= =============================== |
1da177e4 | 197 | |
40e79150 | 198 | :: |
1da177e4 | 199 | |
40e79150 | 200 | int lapb_data_request(void *token, struct sk_buff *skb); |
1da177e4 LT |
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 | ||
40e79150 | 206 | ================= ============================= |
1da177e4 LT |
207 | LAPB_OK LAPB has accepted the data. |
208 | LAPB_BADTOKEN Invalid/unknown LAPB token. | |
209 | LAPB_NOTCONNECTED LAPB module is not connected. | |
40e79150 | 210 | ================= ============================= |
1da177e4 | 211 | |
40e79150 | 212 | :: |
1da177e4 | 213 | |
40e79150 | 214 | int lapb_data_received(void *token, struct sk_buff *skb); |
1da177e4 LT |
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 | ||
40e79150 | 222 | ============= =========================== |
1da177e4 LT |
223 | LAPB_OK LAPB has accepted the data. |
224 | LAPB_BADTOKEN Invalid/unknown LAPB token. | |
40e79150 | 225 | ============= =========================== |
1da177e4 LT |
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 | ||
40e79150 | 235 | :: |
1da177e4 | 236 | |
40e79150 | 237 | void (*connect_confirmation)(void *token, int reason); |
1da177e4 LT |
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 | ||
40e79150 | 243 | :: |
1da177e4 | 244 | |
40e79150 | 245 | void (*connect_indication)(void *token, int reason); |
1da177e4 LT |
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 | ||
40e79150 | 250 | :: |
1da177e4 | 251 | |
40e79150 | 252 | void (*disconnect_confirmation)(void *token, int reason); |
1da177e4 LT |
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 | ||
40e79150 | 259 | ================= ==================================================== |
1da177e4 LT |
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. | |
40e79150 | 264 | ================= ==================================================== |
1da177e4 | 265 | |
40e79150 | 266 | :: |
1da177e4 | 267 | |
40e79150 | 268 | void (*disconnect_indication)(void *token, int reason); |
1da177e4 LT |
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 | ||
40e79150 | 275 | ================= ==================================================== |
1da177e4 LT |
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. | |
40e79150 | 282 | ================= ==================================================== |
1da177e4 | 283 | |
40e79150 | 284 | :: |
1da177e4 | 285 | |
40e79150 | 286 | int (*data_indication)(void *token, struct sk_buff *skb); |
1da177e4 LT |
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 | ||
40e79150 | 298 | :: |
1da177e4 | 299 | |
40e79150 | 300 | void (*data_transmit)(void *token, struct sk_buff *skb); |
1da177e4 LT |
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. |