Documentation/networking/ppp_generic.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ========================================
   4 PPP Generic Driver and Channel Interface
   5 ========================================
   6
   7                            Paul Mackerras
   8                            paulus@samba.org
   9
  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
  26 the services of PPP ``channels``.  A PPP channel encapsulates a
  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
 109 as ``discovery``.  Then the user-level process tells the medium to
 110 become a PPP channel and register itself with the generic PPP layer.
 111 The channel then has to report the channel number assigned to it back
 112 to the user-level process.  From that point, the PPP negotiation code
 113 in the PPP daemon (pppd) can take over and perform the PPP
 114 negotiation, accessing the channel through the /dev/ppp interface.
 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.
 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
 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
 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
 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
 137 start of the PPP frame), it should set the ``hdrlen`` field of the
 138 ppp_channel struct to the amount of headroom required.  The generic
 139 PPP layer will attempt to provide that much headroom but the channel
 140 should still check if there is sufficient headroom and copy the skbuff
 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
 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
 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:
 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
 456 Last modified: 7-feb-2002