Commit | Line | Data |
---|---|---|
71120802 | 1 | .. SPDX-License-Identifier: GPL-2.0 |
1da177e4 | 2 | |
71120802 MCC |
3 | ======================================== |
4 | PPP Generic Driver and Channel Interface | |
5 | ======================================== | |
6 | ||
7 | Paul Mackerras | |
1da177e4 | 8 | paulus@samba.org |
71120802 | 9 | |
1da177e4 LT |
10 | 7 Feb 2002 |
11 | ||
12 | The generic PPP driver in linux-2.4 provides an implementation of the | |
13 | functionality which is of use in any PPP implementation, including: | |
14 | ||
15 | * the network interface unit (ppp0 etc.) | |
16 | * the interface to the networking code | |
17 | * PPP multilink: splitting datagrams between multiple links, and | |
18 | ordering and combining received fragments | |
19 | * the interface to pppd, via a /dev/ppp character device | |
20 | * packet compression and decompression | |
21 | * TCP/IP header compression and decompression | |
22 | * detecting network traffic for demand dialling and for idle timeouts | |
23 | * simple packet filtering | |
24 | ||
25 | For sending and receiving PPP frames, the generic PPP driver calls on | |
71120802 | 26 | the services of PPP ``channels``. A PPP channel encapsulates a |
1da177e4 LT |
27 | mechanism for transporting PPP frames from one machine to another. A |
28 | PPP channel implementation can be arbitrarily complex internally but | |
29 | has a very simple interface with the generic PPP code: it merely has | |
30 | to be able to send PPP frames, receive PPP frames, and optionally | |
31 | handle ioctl requests. Currently there are PPP channel | |
32 | implementations for asynchronous serial ports, synchronous serial | |
33 | ports, and for PPP over ethernet. | |
34 | ||
35 | This architecture makes it possible to implement PPP multilink in a | |
36 | natural and straightforward way, by allowing more than one channel to | |
37 | be linked to each ppp network interface unit. The generic layer is | |
38 | responsible for splitting datagrams on transmit and recombining them | |
39 | on receive. | |
40 | ||
41 | ||
42 | PPP channel API | |
43 | --------------- | |
44 | ||
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 | |
47 | channels. | |
48 | ||
49 | Each channel has to provide two functions to the generic PPP layer, | |
50 | via the ppp_channel.ops pointer: | |
51 | ||
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 | |
54 | flow-control reasons. In this case, start_xmit() should return 0 | |
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. | |
59 | ||
60 | * ioctl() provides an interface which can be used by a user-space | |
61 | program to control aspects of the channel's behaviour. This | |
62 | procedure will be called when a user-space program does an ioctl | |
63 | system call on an instance of /dev/ppp which is bound to the | |
64 | channel. (Usually it would only be pppd which would do this.) | |
65 | ||
66 | The generic PPP layer provides seven functions to channels: | |
67 | ||
68 | * ppp_register_channel() is called when a channel has been created, to | |
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 | |
71 | channel code to call this function. | |
72 | ||
73 | * ppp_unregister_channel() is called when a channel is to be | |
74 | destroyed. For example, the ppp_async channel code calls this when | |
75 | a hangup is detected on the serial port. | |
76 | ||
77 | * ppp_output_wakeup() is called by a channel when it has previously | |
78 | rejected a call to its start_xmit function, and can now accept more | |
79 | packets. | |
80 | ||
81 | * ppp_input() is called by a channel when it has received a complete | |
82 | PPP frame. | |
83 | ||
84 | * ppp_input_error() is called by a channel when it has detected that a | |
85 | frame has been lost or dropped (for example, because of a FCS (frame | |
86 | check sequence) error). | |
87 | ||
88 | * ppp_channel_index() returns the channel index assigned by the PPP | |
89 | generic layer to this channel. The channel should provide some way | |
90 | (e.g. an ioctl) to transmit this back to user-space, as user-space | |
91 | will need it to attach an instance of /dev/ppp to this channel. | |
92 | ||
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 | |
95 | is not connected. | |
96 | ||
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 | |
99 | expected to have some way for a user-level process to control it | |
100 | independently of the ppp generic layer. For example, with the | |
101 | ppp_async channel, this is provided by the file descriptor to the | |
102 | serial port. | |
103 | ||
104 | Generally a user-level process will initialize the underlying | |
105 | communications medium and prepare it to do PPP. For example, with an | |
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 | |
108 | remote system to invoke PPP service there. We refer to this process | |
71120802 | 109 | as ``discovery``. Then the user-level process tells the medium to |
1da177e4 LT |
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. | |
115 | ||
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. | |
71120802 MCC |
118 | The frame does *not* include the 0xff ``address`` byte or the 0x03 |
119 | ``control`` byte that are optionally used in async PPP. Nor is there | |
1da177e4 LT |
120 | any escaping of control characters, nor are there any FCS or framing |
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. | |
126 | ||
127 | The channel must provide an instance of a ppp_channel struct to | |
71120802 MCC |
128 | represent the channel. The channel is free to use the ``private`` field |
129 | however it wishes. The channel should initialize the ``mtu`` and | |
130 | ``hdrlen`` fields before calling ppp_register_channel() and not change | |
131 | them until after ppp_unregister_channel() returns. The ``mtu`` field | |
1da177e4 LT |
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. | |
134 | ||
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 | |
71120802 | 137 | start of the PPP frame), it should set the ``hdrlen`` field of the |
1da177e4 LT |
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 | |
141 | if there isn't. | |
142 | ||
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 | |
145 | code does not require this but will be more efficient if this is done. | |
146 | ||
147 | ||
148 | Buffering and flow control | |
149 | -------------------------- | |
150 | ||
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 | |
156 | exceptions are when pppd sends packets by writing to /dev/ppp, and | |
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 | |
159 | called netif_stop_queue(), which only happens on a transmit timeout. | |
160 | The start_xmit function always accepts and queues the packet which it | |
161 | is asked to transmit. | |
162 | ||
163 | Transmit packets are dequeued from the PPP unit transmit queue and | |
164 | then subjected to TCP/IP header compression and packet compression | |
165 | (Deflate or BSD-Compress compression), as appropriate. After this | |
166 | point the packets can no longer be reordered, as the decompression | |
167 | algorithms rely on receiving compressed packets in the same order that | |
168 | they were generated. | |
169 | ||
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. | |
178 | ||
179 | If multilink is in use, the generic layer divides the packet into one | |
180 | or more fragments and puts a multilink header on each fragment. It | |
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 | |
184 | fragment if it doesn't have any fragments currently queued up for it | |
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, | |
190 | thus reducing latency, while under heavy load, packets will tend to be | |
191 | transmitted as single fragments, thus reducing the overhead of | |
192 | fragmentation. | |
193 | ||
194 | ||
195 | SMP safety | |
196 | ---------- | |
197 | ||
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. | |
209 | ||
210 | The generic layer requires these guarantees from the channel: | |
211 | ||
212 | * The ppp_channel object must exist from the time that | |
213 | ppp_register_channel() is called until after the call to | |
214 | ppp_unregister_channel() returns. | |
215 | ||
216 | * No thread may be in a call to any of ppp_input(), ppp_input_error(), | |
217 | ppp_output_wakeup(), ppp_channel_index() or ppp_unit_number() for a | |
218 | channel at the time that ppp_unregister_channel() is called for that | |
219 | channel. | |
220 | ||
221 | * ppp_register_channel() and ppp_unregister_channel() must be called | |
222 | from process context, not interrupt or softirq/BH context. | |
223 | ||
224 | * The remaining generic layer functions may be called at softirq/BH | |
225 | level but must not be called from a hardware interrupt handler. | |
226 | ||
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 | |
229 | start_xmit() function may not block. | |
230 | ||
231 | * The generic layer will only call the channel ioctl() function in | |
232 | process context. | |
233 | ||
234 | The generic layer provides these guarantees to the channels: | |
235 | ||
236 | * The generic layer will not call the start_xmit() function for a | |
237 | channel while any thread is already executing in that function for | |
238 | that channel. | |
239 | ||
240 | * The generic layer will not call the ioctl() function for a channel | |
241 | while any thread is already executing in that function for that | |
242 | channel. | |
243 | ||
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 | |
247 | call either of those functions subsequently. | |
248 | ||
249 | ||
250 | Interface to pppd | |
251 | ----------------- | |
252 | ||
253 | The PPP generic layer exports a character device interface called | |
254 | /dev/ppp. This is used by pppd to control PPP interface units and | |
255 | channels. Although there is only one /dev/ppp, each open instance of | |
256 | /dev/ppp acts independently and can be attached either to a PPP unit | |
257 | or a PPP channel. This is achieved using the file->private_data field | |
258 | to point to a separate object for each open instance of /dev/ppp. In | |
259 | this way an effect similar to Solaris' clone open is obtained, | |
260 | allowing us to control an arbitrary number of PPP interfaces and | |
261 | channels without having to fill up /dev with hundreds of device names. | |
262 | ||
263 | When /dev/ppp is opened, a new instance is created which is initially | |
264 | unattached. Using an ioctl call, it can then be attached to an | |
265 | existing unit, attached to a newly-created unit, or attached to an | |
266 | existing channel. An instance attached to a unit can be used to send | |
267 | and receive PPP control frames, using the read() and write() system | |
268 | calls, along with poll() if necessary. Similarly, an instance | |
269 | attached to a channel can be used to send and receive PPP frames on | |
270 | that channel. | |
271 | ||
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 | |
275 | unit) will be subject to bundle-level compression and to fragmentation | |
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 | |
278 | channel, without any multilink header. | |
279 | ||
280 | A channel is not initially attached to any unit. In this state it can | |
281 | be used for PPP negotiation but not for the transfer of data packets. | |
282 | It can then be connected to a PPP unit with an ioctl call, which | |
283 | makes it available to send and receive data packets for that unit. | |
284 | ||
285 | The ioctl calls which are available on an instance of /dev/ppp depend | |
286 | on whether it is unattached, attached to a PPP interface, or attached | |
287 | to a PPP channel. The ioctl calls which are available on an | |
288 | unattached instance are: | |
289 | ||
290 | * PPPIOCNEWUNIT creates a new PPP interface and makes this /dev/ppp | |
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 | |
295 | closed. | |
296 | ||
297 | * PPPIOCATTACH attaches this instance to an existing PPP interface. | |
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. | |
300 | ||
301 | * PPPIOCATTCHAN attaches this instance to an existing PPP channel. | |
302 | The argument should point to an int containing the channel number. | |
303 | ||
304 | The ioctl calls available on an instance of /dev/ppp attached to a | |
305 | channel are: | |
306 | ||
1da177e4 LT |
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 | |
311 | not exist. | |
312 | ||
313 | * PPPIOCDISCONN disconnects this channel from the PPP interface that | |
314 | it is connected to. It will return an EINVAL error if the channel | |
315 | is not connected to an interface. | |
316 | ||
563b603b TP |
317 | * PPPIOCBRIDGECHAN bridges a channel with another. The argument should |
318 | point to an int containing the channel number of the channel to bridge | |
319 | to. Once two channels are bridged, frames presented to one channel by | |
320 | ppp_input() are passed to the bridge instance for onward transmission. | |
321 | This allows frames to be switched from one channel into another: for | |
322 | example, to pass PPPoE frames into a PPPoL2TP session. Since channel | |
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 | |
327 | exist. | |
328 | ||
329 | * PPPIOCUNBRIDGECHAN performs the inverse of PPPIOCBRIDGECHAN, unbridging | |
330 | a channel pair. This ioctl will return an EINVAL error if the channel | |
331 | does not form part of a bridge. | |
332 | ||
1da177e4 LT |
333 | * All other ioctl commands are passed to the channel ioctl() function. |
334 | ||
335 | The ioctl calls that are available on an instance that is attached to | |
336 | an interface unit are: | |
337 | ||
338 | * PPPIOCSMRU sets the MRU (maximum receive unit) for the interface. | |
339 | The argument should point to an int containing the new MRU value. | |
340 | ||
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 | |
344 | are: | |
71120802 MCC |
345 | |
346 | ================ ======================================== | |
1da177e4 LT |
347 | SC_COMP_TCP enable transmit TCP header compression |
348 | SC_NO_TCP_CCID disable connection-id compression for | |
349 | TCP header compression | |
350 | SC_REJ_COMP_TCP disable receive TCP header decompression | |
351 | SC_CCP_OPEN Compression Control Protocol (CCP) is | |
352 | open, so inspect CCP packets | |
353 | SC_CCP_UP CCP is up, may (de)compress packets | |
354 | SC_LOOP_TRAFFIC send IP traffic to pppd | |
355 | SC_MULTILINK enable PPP multilink fragmentation on | |
356 | transmitted packets | |
357 | SC_MP_SHORTSEQ expect short multilink sequence | |
358 | numbers on received multilink fragments | |
359 | SC_MP_XSHORTSEQ transmit short multilink sequence nos. | |
71120802 | 360 | ================ ======================================== |
1da177e4 | 361 | |
bf7daebb | 362 | The values of these flags are defined in <linux/ppp-ioctl.h>. Note |
1da177e4 LT |
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 | |
365 | is not selected. | |
366 | ||
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: | |
71120802 MCC |
371 | |
372 | ================ ========================================= | |
1da177e4 LT |
373 | SC_COMP_RUN CCP compressor is running |
374 | SC_DECOMP_RUN CCP decompressor is running | |
375 | SC_DC_ERROR CCP decompressor detected non-fatal error | |
376 | SC_DC_FERROR CCP decompressor detected fatal error | |
71120802 | 377 | ================ ========================================= |
1da177e4 LT |
378 | |
379 | * PPPIOCSCOMPRESS sets the parameters for packet compression or | |
380 | decompression. The argument should point to a ppp_option_data | |
bf7daebb | 381 | structure (defined in <linux/ppp-ioctl.h>), which contains a |
1da177e4 LT |
382 | pointer/length pair which should describe a block of memory |
383 | containing a CCP option specifying a compression method and its | |
71120802 | 384 | parameters. The ppp_option_data struct also contains a ``transmit`` |
1da177e4 LT |
385 | field. If this is 0, the ioctl will affect the receive path, |
386 | otherwise the transmit path. | |
387 | ||
388 | * PPPIOCGUNIT returns, in the int pointed to by the argument, the unit | |
389 | number of this interface unit. | |
390 | ||
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 | |
394 | messages during its operation. This is only intended for debugging | |
395 | the generic PPP layer code; it is generally not helpful for working | |
396 | out why a PPP connection is failing. | |
397 | ||
398 | * PPPIOCGDEBUG returns the debug flags for the interface in the int | |
399 | pointed to by the argument. | |
400 | ||
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 | |
71120802 | 406 | pass the ``active`` packet filter. |
17c7e7f4 AB |
407 | Two versions of this command exist, to deal with user space |
408 | expecting times as either 32-bit or 64-bit time_t seconds. | |
1da177e4 LT |
409 | |
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 | |
416 | maximum connection-ID is set to 15. | |
417 | ||
418 | * PPPIOCSNPMODE sets the network-protocol mode for a given network | |
419 | protocol. The argument should point to an npioctl struct (defined | |
71120802 MCC |
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 | |
1da177e4 LT |
422 | specifies what to do with packets for that protocol: |
423 | ||
71120802 | 424 | ============= ============================================== |
1da177e4 LT |
425 | NPMODE_PASS normal operation, transmit and receive packets |
426 | NPMODE_DROP silently drop packets for this protocol | |
427 | NPMODE_ERROR drop packets and return an error on transmit | |
428 | NPMODE_QUEUE queue up packets for transmit, drop received | |
429 | packets | |
71120802 | 430 | ============= ============================================== |
1da177e4 LT |
431 | |
432 | At present NPMODE_ERROR and NPMODE_QUEUE have the same effect as | |
433 | NPMODE_DROP. | |
434 | ||
435 | * PPPIOCGNPMODE returns the network-protocol mode for a given | |
436 | protocol. The argument should point to an npioctl struct with the | |
71120802 MCC |
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- | |
1da177e4 LT |
439 | protocol mode for that protocol. |
440 | ||
71120802 | 441 | * PPPIOCSPASS and PPPIOCSACTIVE set the ``pass`` and ``active`` packet |
1da177e4 LT |
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 | |
71120802 | 446 | ``pass`` filter; otherwise, if they fail the ``active`` filter they are |
1da177e4 LT |
447 | passed but they do not reset the transmit or receive idle timer. |
448 | ||
449 | * PPPIOCSMRRU enables or disables multilink processing for received | |
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 | |
454 | CONFIG_PPP_MULTILINK option is selected. | |
455 | ||
456 | Last modified: 7-feb-2002 |