About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / networking / ppp_generic.txt

Custom Search

Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

1			PPP Generic Driver and Channel Interface
2			----------------------------------------
4				    Paul Mackerras
5				   paulus@samba.org
6				      7 Feb 2002
8	The generic PPP driver in linux-2.4 provides an implementation of the
9	functionality which is of use in any PPP implementation, including:
11	* the network interface unit (ppp0 etc.)
12	* the interface to the networking code
13	* PPP multilink: splitting datagrams between multiple links, and
14	  ordering and combining received fragments
15	* the interface to pppd, via a /dev/ppp character device
16	* packet compression and decompression
17	* TCP/IP header compression and decompression
18	* detecting network traffic for demand dialling and for idle timeouts
19	* simple packet filtering
21	For sending and receiving PPP frames, the generic PPP driver calls on
22	the services of PPP `channels'.  A PPP channel encapsulates a
23	mechanism for transporting PPP frames from one machine to another.  A
24	PPP channel implementation can be arbitrarily complex internally but
25	has a very simple interface with the generic PPP code: it merely has
26	to be able to send PPP frames, receive PPP frames, and optionally
27	handle ioctl requests.  Currently there are PPP channel
28	implementations for asynchronous serial ports, synchronous serial
29	ports, and for PPP over ethernet.
31	This architecture makes it possible to implement PPP multilink in a
32	natural and straightforward way, by allowing more than one channel to
33	be linked to each ppp network interface unit.  The generic layer is
34	responsible for splitting datagrams on transmit and recombining them
35	on receive.
38	PPP channel API
39	---------------
41	See include/linux/ppp_channel.h for the declaration of the types and
42	functions used to communicate between the generic PPP layer and PPP
43	channels.
45	Each channel has to provide two functions to the generic PPP layer,
46	via the ppp_channel.ops pointer:
48	* start_xmit() is called by the generic layer when it has a frame to
49	  send.  The channel has the option of rejecting the frame for
50	  flow-control reasons.  In this case, start_xmit() should return 0
51	  and the channel should call the ppp_output_wakeup() function at a
52	  later time when it can accept frames again, and the generic layer
53	  will then attempt to retransmit the rejected frame(s).  If the frame
54	  is accepted, the start_xmit() function should return 1.
56	* ioctl() provides an interface which can be used by a user-space
57	  program to control aspects of the channel's behaviour.  This
58	  procedure will be called when a user-space program does an ioctl
59	  system call on an instance of /dev/ppp which is bound to the
60	  channel.  (Usually it would only be pppd which would do this.)
62	The generic PPP layer provides seven functions to channels:
64	* ppp_register_channel() is called when a channel has been created, to
65	  notify the PPP generic layer of its presence.  For example, setting
66	  a serial port to the PPPDISC line discipline causes the ppp_async
67	  channel code to call this function.
69	* ppp_unregister_channel() is called when a channel is to be
70	  destroyed.  For example, the ppp_async channel code calls this when
71	  a hangup is detected on the serial port.
73	* ppp_output_wakeup() is called by a channel when it has previously
74	  rejected a call to its start_xmit function, and can now accept more
75	  packets.
77	* ppp_input() is called by a channel when it has received a complete
78	  PPP frame.
80	* ppp_input_error() is called by a channel when it has detected that a
81	  frame has been lost or dropped (for example, because of a FCS (frame
82	  check sequence) error).
84	* ppp_channel_index() returns the channel index assigned by the PPP
85	  generic layer to this channel.  The channel should provide some way
86	  (e.g. an ioctl) to transmit this back to user-space, as user-space
87	  will need it to attach an instance of /dev/ppp to this channel.
89	* ppp_unit_number() returns the unit number of the ppp network
90	  interface to which this channel is connected, or -1 if the channel
91	  is not connected.
93	Connecting a channel to the ppp generic layer is initiated from the
94	channel code, rather than from the generic layer.  The channel is
95	expected to have some way for a user-level process to control it
96	independently of the ppp generic layer.  For example, with the
97	ppp_async channel, this is provided by the file descriptor to the
98	serial port.
100	Generally a user-level process will initialize the underlying
101	communications medium and prepare it to do PPP.  For example, with an
102	async tty, this can involve setting the tty speed and modes, issuing
103	modem commands, and then going through some sort of dialog with the
104	remote system to invoke PPP service there.  We refer to this process
105	as `discovery'.  Then the user-level process tells the medium to
106	become a PPP channel and register itself with the generic PPP layer.
107	The channel then has to report the channel number assigned to it back
108	to the user-level process.  From that point, the PPP negotiation code
109	in the PPP daemon (pppd) can take over and perform the PPP
110	negotiation, accessing the channel through the /dev/ppp interface.
112	At the interface to the PPP generic layer, PPP frames are stored in
113	skbuff structures and start with the two-byte PPP protocol number.
114	The frame does *not* include the 0xff `address' byte or the 0x03
115	`control' byte that are optionally used in async PPP.  Nor is there
116	any escaping of control characters, nor are there any FCS or framing
117	characters included.  That is all the responsibility of the channel
118	code, if it is needed for the particular medium.  That is, the skbuffs
119	presented to the start_xmit() function contain only the 2-byte
120	protocol number and the data, and the skbuffs presented to ppp_input()
121	must be in the same format.
123	The channel must provide an instance of a ppp_channel struct to
124	represent the channel.  The channel is free to use the `private' field
125	however it wishes.  The channel should initialize the `mtu' and
126	`hdrlen' fields before calling ppp_register_channel() and not change
127	them until after ppp_unregister_channel() returns.  The `mtu' field
128	represents the maximum size of the data part of the PPP frames, that
129	is, it does not include the 2-byte protocol number.
131	If the channel needs some headroom in the skbuffs presented to it for
132	transmission (i.e., some space free in the skbuff data area before the
133	start of the PPP frame), it should set the `hdrlen' field of the
134	ppp_channel struct to the amount of headroom required.  The generic
135	PPP layer will attempt to provide that much headroom but the channel
136	should still check if there is sufficient headroom and copy the skbuff
137	if there isn't.
139	On the input side, channels should ideally provide at least 2 bytes of
140	headroom in the skbuffs presented to ppp_input().  The generic PPP
141	code does not require this but will be more efficient if this is done.
144	Buffering and flow control
145	--------------------------
147	The generic PPP layer has been designed to minimize the amount of data
148	that it buffers in the transmit direction.  It maintains a queue of
149	transmit packets for the PPP unit (network interface device) plus a
150	queue of transmit packets for each attached channel.  Normally the
151	transmit queue for the unit will contain at most one packet; the
152	exceptions are when pppd sends packets by writing to /dev/ppp, and
153	when the core networking code calls the generic layer's start_xmit()
154	function with the queue stopped, i.e. when the generic layer has
155	called netif_stop_queue(), which only happens on a transmit timeout.
156	The start_xmit function always accepts and queues the packet which it
157	is asked to transmit.
159	Transmit packets are dequeued from the PPP unit transmit queue and
160	then subjected to TCP/IP header compression and packet compression
161	(Deflate or BSD-Compress compression), as appropriate.  After this
162	point the packets can no longer be reordered, as the decompression
163	algorithms rely on receiving compressed packets in the same order that
164	they were generated.
166	If multilink is not in use, this packet is then passed to the attached
167	channel's start_xmit() function.  If the channel refuses to take
168	the packet, the generic layer saves it for later transmission.  The
169	generic layer will call the channel's start_xmit() function again
170	when the channel calls  ppp_output_wakeup() or when the core
171	networking code calls the generic layer's start_xmit() function
172	again.  The generic layer contains no timeout and retransmission
173	logic; it relies on the core networking code for that.
175	If multilink is in use, the generic layer divides the packet into one
176	or more fragments and puts a multilink header on each fragment.  It
177	decides how many fragments to use based on the length of the packet
178	and the number of channels which are potentially able to accept a
179	fragment at the moment.  A channel is potentially able to accept a
180	fragment if it doesn't have any fragments currently queued up for it
181	to transmit.  The channel may still refuse a fragment; in this case
182	the fragment is queued up for the channel to transmit later.  This
183	scheme has the effect that more fragments are given to higher-
184	bandwidth channels.  It also means that under light load, the generic
185	layer will tend to fragment large packets across all the channels,
186	thus reducing latency, while under heavy load, packets will tend to be
187	transmitted as single fragments, thus reducing the overhead of
188	fragmentation.
191	SMP safety
192	----------
194	The PPP generic layer has been designed to be SMP-safe.  Locks are
195	used around accesses to the internal data structures where necessary
196	to ensure their integrity.  As part of this, the generic layer
197	requires that the channels adhere to certain requirements and in turn
198	provides certain guarantees to the channels.  Essentially the channels
199	are required to provide the appropriate locking on the ppp_channel
200	structures that form the basis of the communication between the
201	channel and the generic layer.  This is because the channel provides
202	the storage for the ppp_channel structure, and so the channel is
203	required to provide the guarantee that this storage exists and is
204	valid at the appropriate times.
206	The generic layer requires these guarantees from the channel:
208	* The ppp_channel object must exist from the time that
209	  ppp_register_channel() is called until after the call to
210	  ppp_unregister_channel() returns.
212	* No thread may be in a call to any of ppp_input(), ppp_input_error(),
213	  ppp_output_wakeup(), ppp_channel_index() or ppp_unit_number() for a
214	  channel at the time that ppp_unregister_channel() is called for that
215	  channel.
217	* ppp_register_channel() and ppp_unregister_channel() must be called
218	  from process context, not interrupt or softirq/BH context.
220	* The remaining generic layer functions may be called at softirq/BH
221	  level but must not be called from a hardware interrupt handler.
223	* The generic layer may call the channel start_xmit() function at
224	  softirq/BH level but will not call it at interrupt level.  Thus the
225	  start_xmit() function may not block.
227	* The generic layer will only call the channel ioctl() function in
228	  process context.
230	The generic layer provides these guarantees to the channels:
232	* The generic layer will not call the start_xmit() function for a
233	  channel while any thread is already executing in that function for
234	  that channel.
236	* The generic layer will not call the ioctl() function for a channel
237	  while any thread is already executing in that function for that
238	  channel.
240	* By the time a call to ppp_unregister_channel() returns, no thread
241	  will be executing in a call from the generic layer to that channel's
242	  start_xmit() or ioctl() function, and the generic layer will not
243	  call either of those functions subsequently.
246	Interface to pppd
247	-----------------
249	The PPP generic layer exports a character device interface called
250	/dev/ppp.  This is used by pppd to control PPP interface units and
251	channels.  Although there is only one /dev/ppp, each open instance of
252	/dev/ppp acts independently and can be attached either to a PPP unit
253	or a PPP channel.  This is achieved using the file->private_data field
254	to point to a separate object for each open instance of /dev/ppp.  In
255	this way an effect similar to Solaris' clone open is obtained,
256	allowing us to control an arbitrary number of PPP interfaces and
257	channels without having to fill up /dev with hundreds of device names.
259	When /dev/ppp is opened, a new instance is created which is initially
260	unattached.  Using an ioctl call, it can then be attached to an
261	existing unit, attached to a newly-created unit, or attached to an
262	existing channel.  An instance attached to a unit can be used to send
263	and receive PPP control frames, using the read() and write() system
264	calls, along with poll() if necessary.  Similarly, an instance
265	attached to a channel can be used to send and receive PPP frames on
266	that channel.
268	In multilink terms, the unit represents the bundle, while the channels
269	represent the individual physical links.  Thus, a PPP frame sent by a
270	write to the unit (i.e., to an instance of /dev/ppp attached to the
271	unit) will be subject to bundle-level compression and to fragmentation
272	across the individual links (if multilink is in use).  In contrast, a
273	PPP frame sent by a write to the channel will be sent as-is on that
274	channel, without any multilink header.
276	A channel is not initially attached to any unit.  In this state it can
277	be used for PPP negotiation but not for the transfer of data packets.
278	It can then be connected to a PPP unit with an ioctl call, which
279	makes it available to send and receive data packets for that unit.
281	The ioctl calls which are available on an instance of /dev/ppp depend
282	on whether it is unattached, attached to a PPP interface, or attached
283	to a PPP channel.  The ioctl calls which are available on an
284	unattached instance are:
286	* PPPIOCNEWUNIT creates a new PPP interface and makes this /dev/ppp
287	  instance the "owner" of the interface.  The argument should point to
288	  an int which is the desired unit number if >= 0, or -1 to assign the
289	  lowest unused unit number.  Being the owner of the interface means
290	  that the interface will be shut down if this instance of /dev/ppp is
291	  closed.
293	* PPPIOCATTACH attaches this instance to an existing PPP interface.
294	  The argument should point to an int containing the unit number.
295	  This does not make this instance the owner of the PPP interface.
297	* PPPIOCATTCHAN attaches this instance to an existing PPP channel.
298	  The argument should point to an int containing the channel number.
300	The ioctl calls available on an instance of /dev/ppp attached to a
301	channel are:
303	* PPPIOCDETACH detaches the instance from the channel.  This ioctl is
304	  deprecated since the same effect can be achieved by closing the
305	  instance.  In order to prevent possible races this ioctl will fail
306	  with an EINVAL error if more than one file descriptor refers to this
307	  instance (i.e. as a result of dup(), dup2() or fork()).
309	* PPPIOCCONNECT connects this channel to a PPP interface.  The
310	  argument should point to an int containing the interface unit
311	  number.  It will return an EINVAL error if the channel is already
312	  connected to an interface, or ENXIO if the requested interface does
313	  not exist.
315	* PPPIOCDISCONN disconnects this channel from the PPP interface that
316	  it is connected to.  It will return an EINVAL error if the channel
317	  is not connected to an interface.
319	* All other ioctl commands are passed to the channel ioctl() function.
321	The ioctl calls that are available on an instance that is attached to
322	an interface unit are:
324	* PPPIOCSMRU sets the MRU (maximum receive unit) for the interface.
325	  The argument should point to an int containing the new MRU value.
327	* PPPIOCSFLAGS sets flags which control the operation of the
328	  interface.  The argument should be a pointer to an int containing
329	  the new flags value.  The bits in the flags value that can be set
330	  are:
331		SC_COMP_TCP		enable transmit TCP header compression
332		SC_NO_TCP_CCID		disable connection-id compression for
333					TCP header compression
334		SC_REJ_COMP_TCP		disable receive TCP header decompression
335		SC_CCP_OPEN		Compression Control Protocol (CCP) is
336					open, so inspect CCP packets
337		SC_CCP_UP		CCP is up, may (de)compress packets
338		SC_LOOP_TRAFFIC		send IP traffic to pppd
339		SC_MULTILINK		enable PPP multilink fragmentation on
340					transmitted packets
341		SC_MP_SHORTSEQ		expect short multilink sequence
342					numbers on received multilink fragments
343		SC_MP_XSHORTSEQ		transmit short multilink sequence nos.
345	  The values of these flags are defined in <linux/ppp-ioctl.h>.  Note
346	  that the values of the SC_MULTILINK, SC_MP_SHORTSEQ and
347	  SC_MP_XSHORTSEQ bits are ignored if the CONFIG_PPP_MULTILINK option
348	  is not selected.
350	* PPPIOCGFLAGS returns the value of the status/control flags for the
351	  interface unit.  The argument should point to an int where the ioctl
352	  will store the flags value.  As well as the values listed above for
353	  PPPIOCSFLAGS, the following bits may be set in the returned value:
354		SC_COMP_RUN		CCP compressor is running
355		SC_DECOMP_RUN		CCP decompressor is running
356		SC_DC_ERROR		CCP decompressor detected non-fatal error
357		SC_DC_FERROR		CCP decompressor detected fatal error
359	* PPPIOCSCOMPRESS sets the parameters for packet compression or
360	  decompression.  The argument should point to a ppp_option_data
361	  structure (defined in <linux/ppp-ioctl.h>), which contains a
362	  pointer/length pair which should describe a block of memory
363	  containing a CCP option specifying a compression method and its
364	  parameters.  The ppp_option_data struct also contains a `transmit'
365	  field.  If this is 0, the ioctl will affect the receive path,
366	  otherwise the transmit path.
368	* PPPIOCGUNIT returns, in the int pointed to by the argument, the unit
369	  number of this interface unit.
371	* PPPIOCSDEBUG sets the debug flags for the interface to the value in
372	  the int pointed to by the argument.  Only the least significant bit
373	  is used; if this is 1 the generic layer will print some debug
374	  messages during its operation.  This is only intended for debugging
375	  the generic PPP layer code; it is generally not helpful for working
376	  out why a PPP connection is failing.
378	* PPPIOCGDEBUG returns the debug flags for the interface in the int
379	  pointed to by the argument.
381	* PPPIOCGIDLE returns the time, in seconds, since the last data
382	  packets were sent and received.  The argument should point to a
383	  ppp_idle structure (defined in <linux/ppp_defs.h>).  If the
384	  CONFIG_PPP_FILTER option is enabled, the set of packets which reset
385	  the transmit and receive idle timers is restricted to those which
386	  pass the `active' packet filter.
388	* PPPIOCSMAXCID sets the maximum connection-ID parameter (and thus the
389	  number of connection slots) for the TCP header compressor and
390	  decompressor.  The lower 16 bits of the int pointed to by the
391	  argument specify the maximum connection-ID for the compressor.  If
392	  the upper 16 bits of that int are non-zero, they specify the maximum
393	  connection-ID for the decompressor, otherwise the decompressor's
394	  maximum connection-ID is set to 15.
396	* PPPIOCSNPMODE sets the network-protocol mode for a given network
397	  protocol.  The argument should point to an npioctl struct (defined
398	  in <linux/ppp-ioctl.h>).  The `protocol' field gives the PPP protocol
399	  number for the protocol to be affected, and the `mode' field
400	  specifies what to do with packets for that protocol:
402		NPMODE_PASS	normal operation, transmit and receive packets
403		NPMODE_DROP	silently drop packets for this protocol
404		NPMODE_ERROR	drop packets and return an error on transmit
405		NPMODE_QUEUE	queue up packets for transmit, drop received
406				packets
408	  At present NPMODE_ERROR and NPMODE_QUEUE have the same effect as
411	* PPPIOCGNPMODE returns the network-protocol mode for a given
412	  protocol.  The argument should point to an npioctl struct with the
413	  `protocol' field set to the PPP protocol number for the protocol of
414	  interest.  On return the `mode' field will be set to the network-
415	  protocol mode for that protocol.
417	* PPPIOCSPASS and PPPIOCSACTIVE set the `pass' and `active' packet
418	  filters.  These ioctls are only available if the CONFIG_PPP_FILTER
419	  option is selected.  The argument should point to a sock_fprog
420	  structure (defined in <linux/filter.h>) containing the compiled BPF
421	  instructions for the filter.  Packets are dropped if they fail the
422	  `pass' filter; otherwise, if they fail the `active' filter they are
423	  passed but they do not reset the transmit or receive idle timer.
425	* PPPIOCSMRRU enables or disables multilink processing for received
426	  packets and sets the multilink MRRU (maximum reconstructed receive
427	  unit).  The argument should point to an int containing the new MRRU
428	  value.  If the MRRU value is 0, processing of received multilink
429	  fragments is disabled.  This ioctl is only available if the
430	  CONFIG_PPP_MULTILINK option is selected.
432	Last modified: 7-feb-2002
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.