Documentation/networking/ppp_generic.rst

12 The generic PPP driver in linux-2.4 provides an implementation of the
15 * the network interface unit (ppp0 etc.)
16 * the interface to the networking code
19 * the interface to pppd, via a /dev/ppp character device
25 For sending and receiving PPP frames, the generic PPP driver calls on
26 the services of PPP ``channels``.  A PPP channel encapsulates a
29 has a very simple interface with the generic PPP code: it merely has
37 be linked to each ppp network interface unit.  The generic layer is
45 See include/linux/ppp_channel.h for the declaration of the types and
46 functions used to communicate between the generic PPP layer and PPP
49 Each channel has to provide two functions to the generic PPP layer,
50 via the ppp_channel.ops pointer:
52 * start_xmit() is called by the generic layer when it has a frame to
53   send.  The channel has the option of rejecting the frame for
55   and the channel should call the ppp_output_wakeup() function at a
56   later time when it can accept frames again, and the generic layer
57   will then attempt to retransmit the rejected frame(s).  If the frame
58   is accepted, the start_xmit() function should return 1.
61   program to control aspects of the channel's behaviour.  This
63   system call on an instance of /dev/ppp which is bound to the
66 The generic PPP layer provides seven functions to channels:
69   notify the PPP generic layer of its presence.  For example, setting
70   a serial port to the PPPDISC line discipline causes the ppp_async
74   destroyed.  For example, the ppp_async channel code calls this when
75   a hangup is detected on the serial port.
88 * ppp_channel_index() returns the channel index assigned by the PPP
89   generic layer to this channel.  The channel should provide some way
93 * ppp_unit_number() returns the unit number of the ppp network
94   interface to which this channel is connected, or -1 if the channel
97 Connecting a channel to the ppp generic layer is initiated from the
98 channel code, rather than from the generic layer.  The channel is
100 independently of the ppp generic layer.  For example, with the
101 ppp_async channel, this is provided by the file descriptor to the
104 Generally a user-level process will initialize the underlying
106 async tty, this can involve setting the tty speed and modes, issuing
107 modem commands, and then going through some sort of dialog with the
109 as ``discovery``.  Then the user-level process tells the medium to
110 become a PPP channel and register itself with the generic PPP layer.
111 The channel then has to report the channel number assigned to it back
112 to the user-level process.  From that point, the PPP negotiation code
113 in the PPP daemon (pppd) can take over and perform the PPP
114 negotiation, accessing the channel through the /dev/ppp interface.
116 At the interface to the PPP generic layer, PPP frames are stored in
117 skbuff structures and start with the two-byte PPP protocol number.
118 The frame does *not* include the 0xff ``address`` byte or the 0x03
121 characters included.  That is all the responsibility of the channel
122 code, if it is needed for the particular medium.  That is, the skbuffs
123 presented to the start_xmit() function contain only the 2-byte
124 protocol number and the data, and the skbuffs presented to ppp_input()
125 must be in the same format.
127 The channel must provide an instance of a ppp_channel struct to
128 represent the channel.  The channel is free to use the ``private`` field
129 however it wishes.  The channel should initialize the ``mtu`` and
131 them until after ppp_unregister_channel() returns.  The ``mtu`` field
132 represents the maximum size of the data part of the PPP frames, that
133 is, it does not include the 2-byte protocol number.
135 If the channel needs some headroom in the skbuffs presented to it for
136 transmission (i.e., some space free in the skbuff data area before the
137 start of the PPP frame), it should set the ``hdrlen`` field of the
138 ppp_channel struct to the amount of headroom required.  The generic
139 PPP layer will attempt to provide that much headroom but the channel
140 should still check if there is sufficient headroom and copy the skbuff
143 On the input side, channels should ideally provide at least 2 bytes of
144 headroom in the skbuffs presented to ppp_input().  The generic PPP
151 The generic PPP layer has been designed to minimize the amount of data
152 that it buffers in the transmit direction.  It maintains a queue of
153 transmit packets for the PPP unit (network interface device) plus a
154 queue of transmit packets for each attached channel.  Normally the
155 transmit queue for the unit will contain at most one packet; the
157 when the core networking code calls the generic layer's start_xmit()
158 function with the queue stopped, i.e. when the generic layer has
160 The start_xmit function always accepts and queues the packet which it
163 Transmit packets are dequeued from the PPP unit transmit queue and
166 point the packets can no longer be reordered, as the decompression
167 algorithms rely on receiving compressed packets in the same order that
170 If multilink is not in use, this packet is then passed to the attached
171 channel's start_xmit() function.  If the channel refuses to take
172 the packet, the generic layer saves it for later transmission.  The
173 generic layer will call the channel's start_xmit() function again
174 when the channel calls  ppp_output_wakeup() or when the core
175 networking code calls the generic layer's start_xmit() function
176 again.  The generic layer contains no timeout and retransmission
177 logic; it relies on the core networking code for that.
179 If multilink is in use, the generic layer divides the packet into one
181 decides how many fragments to use based on the length of the packet
182 and the number of channels which are potentially able to accept a
183 fragment at the moment.  A channel is potentially able to accept a
185 to transmit.  The channel may still refuse a fragment; in this case
186 the fragment is queued up for the channel to transmit later.  This
187 scheme has the effect that more fragments are given to higher-
188 bandwidth channels.  It also means that under light load, the generic
189 layer will tend to fragment large packets across all the channels,
191 transmitted as single fragments, thus reducing the overhead of
198 The PPP generic layer has been designed to be SMP-safe.  Locks are
199 used around accesses to the internal data structures where necessary
200 to ensure their integrity.  As part of this, the generic layer
201 requires that the channels adhere to certain requirements and in turn
202 provides certain guarantees to the channels.  Essentially the channels
203 are required to provide the appropriate locking on the ppp_channel
204 structures that form the basis of the communication between the
205 channel and the generic layer.  This is because the channel provides
206 the storage for the ppp_channel structure, and so the channel is
207 required to provide the guarantee that this storage exists and is
208 valid at the appropriate times.
210 The generic layer requires these guarantees from the channel:
212 * The ppp_channel object must exist from the time that
213   ppp_register_channel() is called until after the call to
218   channel at the time that ppp_unregister_channel() is called for that
224 * The remaining generic layer functions may be called at softirq/BH
227 * The generic layer may call the channel start_xmit() function at
228   softirq/BH level but will not call it at interrupt level.  Thus the
231 * The generic layer will only call the channel ioctl() function in
234 The generic layer provides these guarantees to the channels:
236 * The generic layer will not call the start_xmit() function for a
240 * The generic layer will not call the ioctl() function for a channel
244 * By the time a call to ppp_unregister_channel() returns, no thread
245   will be executing in a call from the generic layer to that channel's
246   start_xmit() or ioctl() function, and the generic layer will not
253 The PPP generic layer exports a character device interface called
257 or a PPP channel.  This is achieved using the file->private_data field
267 and receive PPP control frames, using the read() and write() system
272 In multilink terms, the unit represents the bundle, while the channels
273 represent the individual physical links.  Thus, a PPP frame sent by a
274 write to the unit (i.e., to an instance of /dev/ppp attached to the
276 across the individual links (if multilink is in use).  In contrast, a
277 PPP frame sent by a write to the channel will be sent as-is on that
281 be used for PPP negotiation but not for the transfer of data packets.
285 The ioctl calls which are available on an instance of /dev/ppp depend
287 to a PPP channel.  The ioctl calls which are available on an
291   instance the "owner" of the interface.  The argument should point to
292   an int which is the desired unit number if >= 0, or -1 to assign the
293   lowest unused unit number.  Being the owner of the interface means
294   that the interface will be shut down if this instance of /dev/ppp is
298   The argument should point to an int containing the unit number.
299   This does not make this instance the owner of the PPP interface.
302   The argument should point to an int containing the channel number.
304 The ioctl calls available on an instance of /dev/ppp attached to a
307 * PPPIOCCONNECT connects this channel to a PPP interface.  The
308   argument should point to an int containing the interface unit
309   number.  It will return an EINVAL error if the channel is already
310   connected to an interface, or ENXIO if the requested interface does
313 * PPPIOCDISCONN disconnects this channel from the PPP interface that
314   it is connected to.  It will return an EINVAL error if the channel
317 * PPPIOCBRIDGECHAN bridges a channel with another. The argument should
318   point to an int containing the channel number of the channel to bridge
320   ppp_input() are passed to the bridge instance for onward transmission.
323   bridging interrupts the normal ppp_input() path, a given channel may
324   not be part of a bridge at the same time as being part of a unit.
325   This ioctl will return an EALREADY error if the channel is already
326   part of a bridge or unit, or ENXIO if the requested channel does not
329 * PPPIOCUNBRIDGECHAN performs the inverse of PPPIOCBRIDGECHAN, unbridging
330   a channel pair.  This ioctl will return an EINVAL error if the channel
333 * All other ioctl commands are passed to the channel ioctl() function.
335 The ioctl calls that are available on an instance that is attached to
338 * PPPIOCSMRU sets the MRU (maximum receive unit) for the interface.
339   The argument should point to an int containing the new MRU value.
341 * PPPIOCSFLAGS sets flags which control the operation of the
342   interface.  The argument should be a pointer to an int containing
343   the new flags value.  The bits in the flags value that can be set
362   The values of these flags are defined in <linux/ppp-ioctl.h>.  Note
363   that the values of the SC_MULTILINK, SC_MP_SHORTSEQ and
364   SC_MP_XSHORTSEQ bits are ignored if the CONFIG_PPP_MULTILINK option
367 * PPPIOCGFLAGS returns the value of the status/control flags for the
368   interface unit.  The argument should point to an int where the ioctl
369   will store the flags value.  As well as the values listed above for
370   PPPIOCSFLAGS, the following bits may be set in the returned value:
379 * PPPIOCSCOMPRESS sets the parameters for packet compression or
380   decompression.  The argument should point to a ppp_option_data
384   parameters.  The ppp_option_data struct also contains a ``transmit``
385   field.  If this is 0, the ioctl will affect the receive path,
386   otherwise the transmit path.
388 * PPPIOCGUNIT returns, in the int pointed to by the argument, the unit
391 * PPPIOCSDEBUG sets the debug flags for the interface to the value in
392   the int pointed to by the argument.  Only the least significant bit
393   is used; if this is 1 the generic layer will print some debug
395   the generic PPP layer code; it is generally not helpful for working
398 * PPPIOCGDEBUG returns the debug flags for the interface in the int
399   pointed to by the argument.
401 * PPPIOCGIDLE returns the time, in seconds, since the last data
402   packets were sent and received.  The argument should point to a
403   ppp_idle structure (defined in <linux/ppp_defs.h>).  If the
404   CONFIG_PPP_FILTER option is enabled, the set of packets which reset
405   the transmit and receive idle timers is restricted to those which
406   pass the ``active`` packet filter.
410 * PPPIOCSMAXCID sets the maximum connection-ID parameter (and thus the
411   number of connection slots) for the TCP header compressor and
412   decompressor.  The lower 16 bits of the int pointed to by the
413   argument specify the maximum connection-ID for the compressor.  If
414   the upper 16 bits of that int are non-zero, they specify the maximum
415   connection-ID for the decompressor, otherwise the decompressor's
418 * PPPIOCSNPMODE sets the network-protocol mode for a given network
419   protocol.  The argument should point to an npioctl struct (defined
420   in <linux/ppp-ioctl.h>).  The ``protocol`` field gives the PPP protocol
421   number for the protocol to be affected, and the ``mode`` field
432   At present NPMODE_ERROR and NPMODE_QUEUE have the same effect as
435 * PPPIOCGNPMODE returns the network-protocol mode for a given
436   protocol.  The argument should point to an npioctl struct with the
437   ``protocol`` field set to the PPP protocol number for the protocol of
438   interest.  On return the ``mode`` field will be set to the network-
441 * PPPIOCSPASS and PPPIOCSACTIVE set the ``pass`` and ``active`` packet
442   filters.  These ioctls are only available if the CONFIG_PPP_FILTER
443   option is selected.  The argument should point to a sock_fprog
444   structure (defined in <linux/filter.h>) containing the compiled BPF
445   instructions for the filter.  Packets are dropped if they fail the
446   ``pass`` filter; otherwise, if they fail the ``active`` filter they are
447   passed but they do not reset the transmit or receive idle timer.
450   packets and sets the multilink MRRU (maximum reconstructed receive
451   unit).  The argument should point to an int containing the new MRRU
452   value.  If the MRRU value is 0, processing of received multilink
453   fragments is disabled.  This ioctl is only available if the