Documentation/isdn/README.concap

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