457 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3========================================4PPP Generic Driver and Channel Interface5========================================6 7 Paul Mackerras8 paulus@samba.org9 10 7 Feb 200211 12The generic PPP driver in linux-2.4 provides an implementation of the13functionality which is of use in any PPP implementation, including:14 15* the network interface unit (ppp0 etc.)16* the interface to the networking code17* PPP multilink: splitting datagrams between multiple links, and18 ordering and combining received fragments19* the interface to pppd, via a /dev/ppp character device20* packet compression and decompression21* TCP/IP header compression and decompression22* detecting network traffic for demand dialling and for idle timeouts23* simple packet filtering24 25For sending and receiving PPP frames, the generic PPP driver calls on26the services of PPP ``channels``. A PPP channel encapsulates a27mechanism for transporting PPP frames from one machine to another. A28PPP channel implementation can be arbitrarily complex internally but29has a very simple interface with the generic PPP code: it merely has30to be able to send PPP frames, receive PPP frames, and optionally31handle ioctl requests. Currently there are PPP channel32implementations for asynchronous serial ports, synchronous serial33ports, and for PPP over ethernet.34 35This architecture makes it possible to implement PPP multilink in a36natural and straightforward way, by allowing more than one channel to37be linked to each ppp network interface unit. The generic layer is38responsible for splitting datagrams on transmit and recombining them39on receive.40 41 42PPP channel API43---------------44 45See include/linux/ppp_channel.h for the declaration of the types and46functions used to communicate between the generic PPP layer and PPP47channels.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 to53 send. The channel has the option of rejecting the frame for54 flow-control reasons. In this case, start_xmit() should return 055 and the channel should call the ppp_output_wakeup() function at a56 later time when it can accept frames again, and the generic layer57 will then attempt to retransmit the rejected frame(s). If the frame58 is accepted, the start_xmit() function should return 1.59 60* ioctl() provides an interface which can be used by a user-space61 program to control aspects of the channel's behaviour. This62 procedure will be called when a user-space program does an ioctl63 system call on an instance of /dev/ppp which is bound to the64 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, to69 notify the PPP generic layer of its presence. For example, setting70 a serial port to the PPPDISC line discipline causes the ppp_async71 channel code to call this function.72 73* ppp_unregister_channel() is called when a channel is to be74 destroyed. For example, the ppp_async channel code calls this when75 a hangup is detected on the serial port.76 77* ppp_output_wakeup() is called by a channel when it has previously78 rejected a call to its start_xmit function, and can now accept more79 packets.80 81* ppp_input() is called by a channel when it has received a complete82 PPP frame.83 84* ppp_input_error() is called by a channel when it has detected that a85 frame has been lost or dropped (for example, because of a FCS (frame86 check sequence) error).87 88* ppp_channel_index() returns the channel index assigned by the PPP89 generic layer to this channel. The channel should provide some way90 (e.g. an ioctl) to transmit this back to user-space, as user-space91 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 network94 interface to which this channel is connected, or -1 if the channel95 is not connected.96 97Connecting a channel to the ppp generic layer is initiated from the98channel code, rather than from the generic layer. The channel is99expected to have some way for a user-level process to control it100independently of the ppp generic layer. For example, with the101ppp_async channel, this is provided by the file descriptor to the102serial port.103 104Generally a user-level process will initialize the underlying105communications medium and prepare it to do PPP. For example, with an106async tty, this can involve setting the tty speed and modes, issuing107modem commands, and then going through some sort of dialog with the108remote system to invoke PPP service there. We refer to this process109as ``discovery``. Then the user-level process tells the medium to110become a PPP channel and register itself with the generic PPP layer.111The channel then has to report the channel number assigned to it back112to the user-level process. From that point, the PPP negotiation code113in the PPP daemon (pppd) can take over and perform the PPP114negotiation, accessing the channel through the /dev/ppp interface.115 116At the interface to the PPP generic layer, PPP frames are stored in117skbuff structures and start with the two-byte PPP protocol number.118The frame does *not* include the 0xff ``address`` byte or the 0x03119``control`` byte that are optionally used in async PPP. Nor is there120any escaping of control characters, nor are there any FCS or framing121characters included. That is all the responsibility of the channel122code, if it is needed for the particular medium. That is, the skbuffs123presented to the start_xmit() function contain only the 2-byte124protocol 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 to128represent the channel. The channel is free to use the ``private`` field129however it wishes. The channel should initialize the ``mtu`` and130``hdrlen`` fields before calling ppp_register_channel() and not change131them until after ppp_unregister_channel() returns. The ``mtu`` field132represents the maximum size of the data part of the PPP frames, that133is, it does not include the 2-byte protocol number.134 135If the channel needs some headroom in the skbuffs presented to it for136transmission (i.e., some space free in the skbuff data area before the137start of the PPP frame), it should set the ``hdrlen`` field of the138ppp_channel struct to the amount of headroom required. The generic139PPP layer will attempt to provide that much headroom but the channel140should still check if there is sufficient headroom and copy the skbuff141if there isn't.142 143On the input side, channels should ideally provide at least 2 bytes of144headroom in the skbuffs presented to ppp_input(). The generic PPP145code does not require this but will be more efficient if this is done.146 147 148Buffering and flow control149--------------------------150 151The generic PPP layer has been designed to minimize the amount of data152that it buffers in the transmit direction. It maintains a queue of153transmit packets for the PPP unit (network interface device) plus a154queue of transmit packets for each attached channel. Normally the155transmit queue for the unit will contain at most one packet; the156exceptions are when pppd sends packets by writing to /dev/ppp, and157when the core networking code calls the generic layer's start_xmit()158function with the queue stopped, i.e. when the generic layer has159called netif_stop_queue(), which only happens on a transmit timeout.160The start_xmit function always accepts and queues the packet which it161is asked to transmit.162 163Transmit packets are dequeued from the PPP unit transmit queue and164then subjected to TCP/IP header compression and packet compression165(Deflate or BSD-Compress compression), as appropriate. After this166point the packets can no longer be reordered, as the decompression167algorithms rely on receiving compressed packets in the same order that168they were generated.169 170If multilink is not in use, this packet is then passed to the attached171channel's start_xmit() function. If the channel refuses to take172the packet, the generic layer saves it for later transmission. The173generic layer will call the channel's start_xmit() function again174when the channel calls ppp_output_wakeup() or when the core175networking code calls the generic layer's start_xmit() function176again. The generic layer contains no timeout and retransmission177logic; it relies on the core networking code for that.178 179If multilink is in use, the generic layer divides the packet into one180or more fragments and puts a multilink header on each fragment. It181decides how many fragments to use based on the length of the packet182and the number of channels which are potentially able to accept a183fragment at the moment. A channel is potentially able to accept a184fragment if it doesn't have any fragments currently queued up for it185to transmit. The channel may still refuse a fragment; in this case186the fragment is queued up for the channel to transmit later. This187scheme has the effect that more fragments are given to higher-188bandwidth channels. It also means that under light load, the generic189layer will tend to fragment large packets across all the channels,190thus reducing latency, while under heavy load, packets will tend to be191transmitted as single fragments, thus reducing the overhead of192fragmentation.193 194 195SMP safety196----------197 198The PPP generic layer has been designed to be SMP-safe. Locks are199used around accesses to the internal data structures where necessary200to ensure their integrity. As part of this, the generic layer201requires that the channels adhere to certain requirements and in turn202provides certain guarantees to the channels. Essentially the channels203are required to provide the appropriate locking on the ppp_channel204structures that form the basis of the communication between the205channel and the generic layer. This is because the channel provides206the storage for the ppp_channel structure, and so the channel is207required to provide the guarantee that this storage exists and is208valid 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 that213 ppp_register_channel() is called until after the call to214 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 a218 channel at the time that ppp_unregister_channel() is called for that219 channel.220 221* ppp_register_channel() and ppp_unregister_channel() must be called222 from process context, not interrupt or softirq/BH context.223 224* The remaining generic layer functions may be called at softirq/BH225 level but must not be called from a hardware interrupt handler.226 227* The generic layer may call the channel start_xmit() function at228 softirq/BH level but will not call it at interrupt level. Thus the229 start_xmit() function may not block.230 231* The generic layer will only call the channel ioctl() function in232 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 a237 channel while any thread is already executing in that function for238 that channel.239 240* The generic layer will not call the ioctl() function for a channel241 while any thread is already executing in that function for that242 channel.243 244* By the time a call to ppp_unregister_channel() returns, no thread245 will be executing in a call from the generic layer to that channel's246 start_xmit() or ioctl() function, and the generic layer will not247 call either of those functions subsequently.248 249 250Interface to pppd251-----------------252 253The PPP generic layer exports a character device interface called254/dev/ppp. This is used by pppd to control PPP interface units and255channels. Although there is only one /dev/ppp, each open instance of256/dev/ppp acts independently and can be attached either to a PPP unit257or a PPP channel. This is achieved using the file->private_data field258to point to a separate object for each open instance of /dev/ppp. In259this way an effect similar to Solaris' clone open is obtained,260allowing us to control an arbitrary number of PPP interfaces and261channels without having to fill up /dev with hundreds of device names.262 263When /dev/ppp is opened, a new instance is created which is initially264unattached. Using an ioctl call, it can then be attached to an265existing unit, attached to a newly-created unit, or attached to an266existing channel. An instance attached to a unit can be used to send267and receive PPP control frames, using the read() and write() system268calls, along with poll() if necessary. Similarly, an instance269attached to a channel can be used to send and receive PPP frames on270that channel.271 272In multilink terms, the unit represents the bundle, while the channels273represent the individual physical links. Thus, a PPP frame sent by a274write to the unit (i.e., to an instance of /dev/ppp attached to the275unit) will be subject to bundle-level compression and to fragmentation276across the individual links (if multilink is in use). In contrast, a277PPP frame sent by a write to the channel will be sent as-is on that278channel, without any multilink header.279 280A channel is not initially attached to any unit. In this state it can281be 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, which283makes it available to send and receive data packets for that unit.284 285The ioctl calls which are available on an instance of /dev/ppp depend286on whether it is unattached, attached to a PPP interface, or attached287to a PPP channel. The ioctl calls which are available on an288unattached instance are:289 290* PPPIOCNEWUNIT creates a new PPP interface and makes this /dev/ppp291 instance the "owner" of the interface. The argument should point to292 an int which is the desired unit number if >= 0, or -1 to assign the293 lowest unused unit number. Being the owner of the interface means294 that the interface will be shut down if this instance of /dev/ppp is295 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 a305channel are:306 307* PPPIOCCONNECT connects this channel to a PPP interface. The308 argument should point to an int containing the interface unit309 number. It will return an EINVAL error if the channel is already310 connected to an interface, or ENXIO if the requested interface does311 not exist.312 313* PPPIOCDISCONN disconnects this channel from the PPP interface that314 it is connected to. It will return an EINVAL error if the channel315 is not connected to an interface.316 317* PPPIOCBRIDGECHAN bridges a channel with another. The argument should318 point to an int containing the channel number of the channel to bridge319 to. Once two channels are bridged, frames presented to one channel by320 ppp_input() are passed to the bridge instance for onward transmission.321 This allows frames to be switched from one channel into another: for322 example, to pass PPPoE frames into a PPPoL2TP session. Since channel323 bridging interrupts the normal ppp_input() path, a given channel may324 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 already326 part of a bridge or unit, or ENXIO if the requested channel does not327 exist.328 329* PPPIOCUNBRIDGECHAN performs the inverse of PPPIOCBRIDGECHAN, unbridging330 a channel pair. This ioctl will return an EINVAL error if the channel331 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 to336an 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 the342 interface. The argument should be a pointer to an int containing343 the new flags value. The bits in the flags value that can be set344 are:345 346 ================ ========================================347 SC_COMP_TCP enable transmit TCP header compression348 SC_NO_TCP_CCID disable connection-id compression for349 TCP header compression350 SC_REJ_COMP_TCP disable receive TCP header decompression351 SC_CCP_OPEN Compression Control Protocol (CCP) is352 open, so inspect CCP packets353 SC_CCP_UP CCP is up, may (de)compress packets354 SC_LOOP_TRAFFIC send IP traffic to pppd355 SC_MULTILINK enable PPP multilink fragmentation on356 transmitted packets357 SC_MP_SHORTSEQ expect short multilink sequence358 numbers on received multilink fragments359 SC_MP_XSHORTSEQ transmit short multilink sequence nos.360 ================ ========================================361 362 The values of these flags are defined in <linux/ppp-ioctl.h>. Note363 that the values of the SC_MULTILINK, SC_MP_SHORTSEQ and364 SC_MP_XSHORTSEQ bits are ignored if the CONFIG_PPP_MULTILINK option365 is not selected.366 367* PPPIOCGFLAGS returns the value of the status/control flags for the368 interface unit. The argument should point to an int where the ioctl369 will store the flags value. As well as the values listed above for370 PPPIOCSFLAGS, the following bits may be set in the returned value:371 372 ================ =========================================373 SC_COMP_RUN CCP compressor is running374 SC_DECOMP_RUN CCP decompressor is running375 SC_DC_ERROR CCP decompressor detected non-fatal error376 SC_DC_FERROR CCP decompressor detected fatal error377 ================ =========================================378 379* PPPIOCSCOMPRESS sets the parameters for packet compression or380 decompression. The argument should point to a ppp_option_data381 structure (defined in <linux/ppp-ioctl.h>), which contains a382 pointer/length pair which should describe a block of memory383 containing a CCP option specifying a compression method and its384 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 unit389 number of this interface unit.390 391* PPPIOCSDEBUG sets the debug flags for the interface to the value in392 the int pointed to by the argument. Only the least significant bit393 is used; if this is 1 the generic layer will print some debug394 messages during its operation. This is only intended for debugging395 the generic PPP layer code; it is generally not helpful for working396 out why a PPP connection is failing.397 398* PPPIOCGDEBUG returns the debug flags for the interface in the int399 pointed to by the argument.400 401* PPPIOCGIDLE returns the time, in seconds, since the last data402 packets were sent and received. The argument should point to a403 ppp_idle structure (defined in <linux/ppp_defs.h>). If the404 CONFIG_PPP_FILTER option is enabled, the set of packets which reset405 the transmit and receive idle timers is restricted to those which406 pass the ``active`` packet filter.407 Two versions of this command exist, to deal with user space408 expecting times as either 32-bit or 64-bit time_t seconds.409 410* PPPIOCSMAXCID sets the maximum connection-ID parameter (and thus the411 number of connection slots) for the TCP header compressor and412 decompressor. The lower 16 bits of the int pointed to by the413 argument specify the maximum connection-ID for the compressor. If414 the upper 16 bits of that int are non-zero, they specify the maximum415 connection-ID for the decompressor, otherwise the decompressor's416 maximum connection-ID is set to 15.417 418* PPPIOCSNPMODE sets the network-protocol mode for a given network419 protocol. The argument should point to an npioctl struct (defined420 in <linux/ppp-ioctl.h>). The ``protocol`` field gives the PPP protocol421 number for the protocol to be affected, and the ``mode`` field422 specifies what to do with packets for that protocol:423 424 ============= ==============================================425 NPMODE_PASS normal operation, transmit and receive packets426 NPMODE_DROP silently drop packets for this protocol427 NPMODE_ERROR drop packets and return an error on transmit428 NPMODE_QUEUE queue up packets for transmit, drop received429 packets430 ============= ==============================================431 432 At present NPMODE_ERROR and NPMODE_QUEUE have the same effect as433 NPMODE_DROP.434 435* PPPIOCGNPMODE returns the network-protocol mode for a given436 protocol. The argument should point to an npioctl struct with the437 ``protocol`` field set to the PPP protocol number for the protocol of438 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`` packet442 filters. These ioctls are only available if the CONFIG_PPP_FILTER443 option is selected. The argument should point to a sock_fprog444 structure (defined in <linux/filter.h>) containing the compiled BPF445 instructions for the filter. Packets are dropped if they fail the446 ``pass`` filter; otherwise, if they fail the ``active`` filter they are447 passed but they do not reset the transmit or receive idle timer.448 449* PPPIOCSMRRU enables or disables multilink processing for received450 packets and sets the multilink MRRU (maximum reconstructed receive451 unit). The argument should point to an int containing the new MRRU452 value. If the MRRU value is 0, processing of received multilink453 fragments is disabled. This ioctl is only available if the454 CONFIG_PPP_MULTILINK option is selected.455 456Last modified: 7-feb-2002457