About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / networking / lapb-module.txt




Custom Search

Based on kernel version 3.9. Page generated on 2013-05-02 23:11 EST.

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.
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog
Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.