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