README.concap 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259
  1. Description of the "concap" encapsulation protocol interface
  2. ============================================================
  3. The "concap" interface is intended to be used by network device
  4. drivers that need to process an encapsulation protocol.
  5. It is assumed that the protocol interacts with a linux network device by
  6. - data transmission
  7. - connection control (establish, release)
  8. Thus, the mnemonic: "CONnection CONtrolling eNCAPsulation Protocol".
  9. This is currently only used inside the isdn subsystem. But it might
  10. also be useful to other kinds of network devices. Thus, if you want
  11. to suggest changes that improve usability or performance of the
  12. interface, please let me know. I'm willing to include them in future
  13. releases (even if I needed to adapt the current isdn code to the
  14. changed interface).
  15. Why is this useful?
  16. ===================
  17. The encapsulation protocol used on top of WAN connections or permanent
  18. point-to-point links are frequently chosen upon bilateral agreement.
  19. Thus, a device driver for a certain type of hardware must support
  20. several different encapsulation protocols at once.
  21. The isdn device driver did already support several different
  22. encapsulation protocols. The encapsulation protocol is configured by a
  23. user space utility (isdnctrl). The isdn network interface code then
  24. uses several case statements which select appropriate actions
  25. depending on the currently configured encapsulation protocol.
  26. In contrast, LAN network interfaces always used a single encapsulation
  27. protocol which is unique to the hardware type of the interface. The LAN
  28. encapsulation is usually done by just sticking a header on the data. Thus,
  29. traditional linux network device drivers used to process the
  30. encapsulation protocol directly (usually by just providing a hard_header()
  31. method in the device structure) using some hardware type specific support
  32. functions. This is simple, direct and efficient. But it doesn't fit all
  33. the requirements for complex WAN encapsulations.
  34. The configurability of the encapsulation protocol to be used
  35. makes isdn network interfaces more flexible, but also much more
  36. complex than traditional lan network interfaces.
  37. Many Encapsulation protocols used on top of WAN connections will not just
  38. stick a header on the data. They also might need to set up or release
  39. the WAN connection. They also might want to send other data for their
  40. private purpose over the wire, e.g. ppp does a lot of link level
  41. negotiation before the first piece of user data can be transmitted.
  42. Such encapsulation protocols for WAN devices are typically more complex
  43. than encapsulation protocols for lan devices. Thus, network interface
  44. code for typical WAN devices also tends to be more complex.
  45. In order to support Linux' x25 PLP implementation on top of
  46. isdn network interfaces I could have introduced yet another branch to
  47. the various case statements inside drivers/isdn/isdn_net.c.
  48. This eventually made isdn_net.c even more complex. In addition, it made
  49. isdn_net.c harder to maintain. Thus, by identifying an abstract
  50. interface between the network interface code and the encapsulation
  51. protocol, complexity could be reduced and maintainability could be
  52. increased.
  53. Likewise, a similar encapsulation protocol will frequently be needed by
  54. several different interfaces of even different hardware type, e.g. the
  55. synchronous ppp implementation used by the isdn driver and the
  56. asynchronous ppp implementation used by the ppp driver have a lot of
  57. similar code in them. By cleanly separating the encapsulation protocol
  58. from the hardware specific interface stuff such code could be shared
  59. better in future.
  60. When operating over dial-up-connections (e.g. telephone lines via modem,
  61. non-permanent virtual circuits of wide area networks, ISDN) many
  62. encapsulation protocols will need to control the connection. Therefore,
  63. some basic connection control primitives are supported. The type and
  64. semantics of the connection (i.e the ISO layer where connection service
  65. is provided) is outside our scope and might be different depending on
  66. the encapsulation protocol used, e.g. for a ppp module using our service
  67. on top of a modem connection a connect_request will result in dialing
  68. a (somewhere else configured) remote phone number. For an X25-interface
  69. module (LAPB semantics, as defined in Documentation/networking/x25-iface.txt)
  70. a connect_request will ask for establishing a reliable lapb
  71. datalink connection.
  72. The encapsulation protocol currently provides the following
  73. service primitives to the network device.
  74. - create a new encapsulation protocol instance
  75. - delete encapsulation protocol instance and free all its resources
  76. - initialize (open) the encapsulation protocol instance for use.
  77. - deactivate (close) an encapsulation protocol instance.
  78. - process (xmit) data handed down by upper protocol layer
  79. - receive data from lower (hardware) layer
  80. - process connect indication from lower (hardware) layer
  81. - process disconnect indication from lower (hardware) layer
  82. The network interface driver accesses those primitives via callbacks
  83. provided by the encapsulation protocol instance within a
  84. struct concap_proto_ops.
  85. struct concap_proto_ops{
  86. /* create a new encapsulation protocol instance of same type */
  87. struct concap_proto * (*proto_new) (void);
  88. /* delete encapsulation protocol instance and free all its resources.
  89. cprot may no loger be referenced after calling this */
  90. void (*proto_del)(struct concap_proto *cprot);
  91. /* initialize the protocol's data. To be called at interface startup
  92. or when the device driver resets the interface. All services of the
  93. encapsulation protocol may be used after this*/
  94. int (*restart)(struct concap_proto *cprot,
  95. struct net_device *ndev,
  96. struct concap_device_ops *dops);
  97. /* deactivate an encapsulation protocol instance. The encapsulation
  98. protocol may not call any *dops methods after this. */
  99. int (*close)(struct concap_proto *cprot);
  100. /* process a frame handed down to us by upper layer */
  101. int (*encap_and_xmit)(struct concap_proto *cprot, struct sk_buff *skb);
  102. /* to be called for each data entity received from lower layer*/
  103. int (*data_ind)(struct concap_proto *cprot, struct sk_buff *skb);
  104. /* to be called when a connection was set up/down.
  105. Protocols that don't process these primitives might fill in
  106. dummy methods here */
  107. int (*connect_ind)(struct concap_proto *cprot);
  108. int (*disconn_ind)(struct concap_proto *cprot);
  109. };
  110. The data structures are defined in the header file include/linux/concap.h.
  111. A Network interface using encapsulation protocols must also provide
  112. some service primitives to the encapsulation protocol:
  113. - request data being submitted by lower layer (device hardware)
  114. - request a connection being set up by lower layer
  115. - request a connection being released by lower layer
  116. The encapsulation protocol accesses those primitives via callbacks
  117. provided by the network interface within a struct concap_device_ops.
  118. struct concap_device_ops{
  119. /* to request data be submitted by device */
  120. int (*data_req)(struct concap_proto *, struct sk_buff *);
  121. /* Control methods must be set to NULL by devices which do not
  122. support connection control. */
  123. /* to request a connection be set up */
  124. int (*connect_req)(struct concap_proto *);
  125. /* to request a connection be released */
  126. int (*disconn_req)(struct concap_proto *);
  127. };
  128. The network interface does not explicitly provide a receive service
  129. because the encapsulation protocol directly calls netif_rx().
  130. An encapsulation protocol itself is actually the
  131. struct concap_proto{
  132. struct net_device *net_dev; /* net device using our service */
  133. struct concap_device_ops *dops; /* callbacks provided by device */
  134. struct concap_proto_ops *pops; /* callbacks provided by us */
  135. int flags;
  136. void *proto_data; /* protocol specific private data, to
  137. be accessed via *pops methods only*/
  138. /*
  139. :
  140. whatever
  141. :
  142. */
  143. };
  144. Most of this is filled in when the device requests the protocol to
  145. be reset (opend). The network interface must provide the net_dev and
  146. dops pointers. Other concap_proto members should be considered private
  147. data that are only accessed by the pops callback functions. Likewise,
  148. a concap proto should access the network device's private data
  149. only by means of the callbacks referred to by the dops pointer.
  150. A possible extended device structure which uses the connection controlling
  151. encapsulation services could look like this:
  152. struct concap_device{
  153. struct net_device net_dev;
  154. struct my_priv /* device->local stuff */
  155. /* the my_priv struct might contain a
  156. struct concap_device_ops *dops;
  157. to provide the device specific callbacks
  158. */
  159. struct concap_proto *cprot; /* callbacks provided by protocol */
  160. };
  161. Misc Thoughts
  162. =============
  163. The concept of the concap proto might help to reuse protocol code and
  164. reduce the complexity of certain network interface implementations.
  165. The trade off is that it introduces yet another procedure call layer
  166. when processing the protocol. This has of course some impact on
  167. performance. However, typically the concap interface will be used by
  168. devices attached to slow lines (like telephone, isdn, leased synchronous
  169. lines). For such slow lines, the overhead is probably negligible.
  170. This might no longer hold for certain high speed WAN links (like
  171. ATM).
  172. If general linux network interfaces explicitly supported concap
  173. protocols (e.g. by a member struct concap_proto* in struct net_device)
  174. then the interface of the service function could be changed
  175. by passing a pointer of type (struct net_device*) instead of
  176. type (struct concap_proto*). Doing so would make many of the service
  177. functions compatible to network device support functions.
  178. e.g. instead of the concap protocol's service function
  179. int (*encap_and_xmit)(struct concap_proto *cprot, struct sk_buff *skb);
  180. we could have
  181. int (*encap_and_xmit)(struct net_device *ndev, struct sk_buff *skb);
  182. As this is compatible to the dev->hard_start_xmit() method, the device
  183. driver could directly register the concap protocol's encap_and_xmit()
  184. function as its hard_start_xmit() method. This would eliminate one
  185. procedure call layer.
  186. The device's data request function could also be defined as
  187. int (*data_req)(struct net_device *ndev, struct sk_buff *skb);
  188. This might even allow for some protocol stacking. And the network
  189. interface might even register the same data_req() function directly
  190. as its hard_start_xmit() method when a zero layer encapsulation
  191. protocol is configured. Thus, eliminating the performance penalty
  192. of the concap interface when a trivial concap protocol is used.
  193. Nevertheless, the device remains able to support encapsulation
  194. protocol configuration.