ppp_generic.rst 21 KB

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