(转)The Linux LAPB Module Interface

bilbo0214

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, . The header file  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.
               
               
               

本文来自ChinaUnix博客，如果查看原文请点：http://blog.chinaunix.net/u/29291/showart_1358672.html