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