1.. SPDX-License-Identifier: GPL-2.0 2 3======================================== 4PPP Generic Driver and Channel Interface 5======================================== 6 7 Paul Mackerras 8 paulus@samba.org 9 10 7 Feb 2002 11 12The generic PPP driver in linux-2.4 provides an implementation of the 13functionality 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 25For sending and receiving PPP frames, the generic PPP driver calls on 26the services of PPP ``channels``. A PPP channel encapsulates a 27mechanism for transporting PPP frames from one machine to another. A 28PPP channel implementation can be arbitrarily complex internally but 29has a very simple interface with the generic PPP code: it merely has 30to be able to send PPP frames, receive PPP frames, and optionally 31handle ioctl requests. Currently there are PPP channel 32implementations for asynchronous serial ports, synchronous serial 33ports, and for PPP over ethernet. 34 35This architecture makes it possible to implement PPP multilink in a 36natural and straightforward way, by allowing more than one channel to 37be linked to each ppp network interface unit. The generic layer is 38responsible for splitting datagrams on transmit and recombining them 39on receive. 40 41 42PPP channel API 43--------------- 44 45See include/linux/ppp_channel.h for the declaration of the types and 46functions used to communicate between the generic PPP layer and PPP 47channels. 48 49Each channel has to provide two functions to the generic PPP layer, 50via 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 66The 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 97Connecting a channel to the ppp generic layer is initiated from the 98channel code, rather than from the generic layer. The channel is 99expected to have some way for a user-level process to control it 100independently of the ppp generic layer. For example, with the 101ppp_async channel, this is provided by the file descriptor to the 102serial port. 103 104Generally a user-level process will initialize the underlying 105communications medium and prepare it to do PPP. For example, with an 106async tty, this can involve setting the tty speed and modes, issuing 107modem commands, and then going through some sort of dialog with the 108remote system to invoke PPP service there. We refer to this process 109as ``discovery``. Then the user-level process tells the medium to 110become a PPP channel and register itself with the generic PPP layer. 111The channel then has to report the channel number assigned to it back 112to the user-level process. From that point, the PPP negotiation code 113in the PPP daemon (pppd) can take over and perform the PPP 114negotiation, accessing the channel through the /dev/ppp interface. 115 116At the interface to the PPP generic layer, PPP frames are stored in 117skbuff structures and start with the two-byte PPP protocol number. 118The frame does *not* include the 0xff ``address`` byte or the 0x03 119``control`` byte that are optionally used in async PPP. Nor is there 120any escaping of control characters, nor are there any FCS or framing 121characters included. That is all the responsibility of the channel 122code, if it is needed for the particular medium. That is, the skbuffs 123presented to the start_xmit() function contain only the 2-byte 124protocol number and the data, and the skbuffs presented to ppp_input() 125must be in the same format. 126 127The channel must provide an instance of a ppp_channel struct to 128represent the channel. The channel is free to use the ``private`` field 129however it wishes. The channel should initialize the ``mtu`` and 130``hdrlen`` fields before calling ppp_register_channel() and not change 131them until after ppp_unregister_channel() returns. The ``mtu`` field 132represents the maximum size of the data part of the PPP frames, that 133is, it does not include the 2-byte protocol number. 134 135If the channel needs some headroom in the skbuffs presented to it for 136transmission (i.e., some space free in the skbuff data area before the 137start of the PPP frame), it should set the ``hdrlen`` field of the 138ppp_channel struct to the amount of headroom required. The generic 139PPP layer will attempt to provide that much headroom but the channel 140should still check if there is sufficient headroom and copy the skbuff 141if there isn't. 142 143On the input side, channels should ideally provide at least 2 bytes of 144headroom in the skbuffs presented to ppp_input(). The generic PPP 145code does not require this but will be more efficient if this is done. 146 147 148Buffering and flow control 149-------------------------- 150 151The generic PPP layer has been designed to minimize the amount of data 152that it buffers in the transmit direction. It maintains a queue of 153transmit packets for the PPP unit (network interface device) plus a 154queue of transmit packets for each attached channel. Normally the 155transmit queue for the unit will contain at most one packet; the 156exceptions are when pppd sends packets by writing to /dev/ppp, and 157when the core networking code calls the generic layer's start_xmit() 158function with the queue stopped, i.e. when the generic layer has 159called netif_stop_queue(), which only happens on a transmit timeout. 160The start_xmit function always accepts and queues the packet which it 161is asked to transmit. 162 163Transmit packets are dequeued from the PPP unit transmit queue and 164then subjected to TCP/IP header compression and packet compression 165(Deflate or BSD-Compress compression), as appropriate. After this 166point the packets can no longer be reordered, as the decompression 167algorithms rely on receiving compressed packets in the same order that 168they were generated. 169 170If multilink is not in use, this packet is then passed to the attached 171channel's start_xmit() function. If the channel refuses to take 172the packet, the generic layer saves it for later transmission. The 173generic layer will call the channel's start_xmit() function again 174when the channel calls ppp_output_wakeup() or when the core 175networking code calls the generic layer's start_xmit() function 176again. The generic layer contains no timeout and retransmission 177logic; it relies on the core networking code for that. 178 179If multilink is in use, the generic layer divides the packet into one 180or more fragments and puts a multilink header on each fragment. It 181decides how many fragments to use based on the length of the packet 182and the number of channels which are potentially able to accept a 183fragment at the moment. A channel is potentially able to accept a 184fragment if it doesn't have any fragments currently queued up for it 185to transmit. The channel may still refuse a fragment; in this case 186the fragment is queued up for the channel to transmit later. This 187scheme has the effect that more fragments are given to higher- 188bandwidth channels. It also means that under light load, the generic 189layer will tend to fragment large packets across all the channels, 190thus reducing latency, while under heavy load, packets will tend to be 191transmitted as single fragments, thus reducing the overhead of 192fragmentation. 193 194 195SMP safety 196---------- 197 198The PPP generic layer has been designed to be SMP-safe. Locks are 199used around accesses to the internal data structures where necessary 200to ensure their integrity. As part of this, the generic layer 201requires that the channels adhere to certain requirements and in turn 202provides certain guarantees to the channels. Essentially the channels 203are required to provide the appropriate locking on the ppp_channel 204structures that form the basis of the communication between the 205channel and the generic layer. This is because the channel provides 206the storage for the ppp_channel structure, and so the channel is 207required to provide the guarantee that this storage exists and is 208valid at the appropriate times. 209 210The 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 234The 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 250Interface to pppd 251----------------- 252 253The PPP generic layer exports a character device interface called 254/dev/ppp. This is used by pppd to control PPP interface units and 255channels. 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 257or a PPP channel. This is achieved using the file->private_data field 258to point to a separate object for each open instance of /dev/ppp. In 259this way an effect similar to Solaris' clone open is obtained, 260allowing us to control an arbitrary number of PPP interfaces and 261channels without having to fill up /dev with hundreds of device names. 262 263When /dev/ppp is opened, a new instance is created which is initially 264unattached. Using an ioctl call, it can then be attached to an 265existing unit, attached to a newly-created unit, or attached to an 266existing channel. An instance attached to a unit can be used to send 267and receive PPP control frames, using the read() and write() system 268calls, along with poll() if necessary. Similarly, an instance 269attached to a channel can be used to send and receive PPP frames on 270that channel. 271 272In multilink terms, the unit represents the bundle, while the channels 273represent the individual physical links. Thus, a PPP frame sent by a 274write to the unit (i.e., to an instance of /dev/ppp attached to the 275unit) will be subject to bundle-level compression and to fragmentation 276across the individual links (if multilink is in use). In contrast, a 277PPP frame sent by a write to the channel will be sent as-is on that 278channel, without any multilink header. 279 280A channel is not initially attached to any unit. In this state it can 281be used for PPP negotiation but not for the transfer of data packets. 282It can then be connected to a PPP unit with an ioctl call, which 283makes it available to send and receive data packets for that unit. 284 285The ioctl calls which are available on an instance of /dev/ppp depend 286on whether it is unattached, attached to a PPP interface, or attached 287to a PPP channel. The ioctl calls which are available on an 288unattached 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 304The ioctl calls available on an instance of /dev/ppp attached to a 305channel are: 306 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 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 333* All other ioctl commands are passed to the channel ioctl() function. 334 335The ioctl calls that are available on an instance that is attached to 336an 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: 345 346 ================ ======================================== 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. 360 ================ ======================================== 361 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 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: 371 372 ================ ========================================= 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 377 ================ ========================================= 378 379* PPPIOCSCOMPRESS sets the parameters for packet compression or 380 decompression. The argument should point to a ppp_option_data 381 structure (defined in <linux/ppp-ioctl.h>), which contains a 382 pointer/length pair which should describe a block of memory 383 containing a CCP option specifying a compression method and its 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. 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 406 pass the ``active`` packet filter. 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. 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 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 422 specifies what to do with packets for that protocol: 423 424 ============= ============================================== 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 430 ============= ============================================== 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 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- 439 protocol mode for that protocol. 440 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. 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 456Last modified: 7-feb-2002 457