diff options
Diffstat (limited to 'Documentation/isdn/README.concap')
| -rw-r--r-- | Documentation/isdn/README.concap | 259 |
1 files changed, 259 insertions, 0 deletions
diff --git a/Documentation/isdn/README.concap b/Documentation/isdn/README.concap new file mode 100644 index 000000000..a76d74845 --- /dev/null +++ b/Documentation/isdn/README.concap @@ -0,0 +1,259 @@ +Description of the "concap" encapsulation protocol interface +============================================================ + +The "concap" interface is intended to be used by network device +drivers that need to process an encapsulation protocol. +It is assumed that the protocol interacts with a linux network device by +- data transmission +- connection control (establish, release) +Thus, the mnemonic: "CONnection CONtrolling eNCAPsulation Protocol". + +This is currently only used inside the isdn subsystem. But it might +also be useful to other kinds of network devices. Thus, if you want +to suggest changes that improve usability or performance of the +interface, please let me know. I'm willing to include them in future +releases (even if I needed to adapt the current isdn code to the +changed interface). + + +Why is this useful? +=================== + +The encapsulation protocol used on top of WAN connections or permanent +point-to-point links are frequently chosen upon bilateral agreement. +Thus, a device driver for a certain type of hardware must support +several different encapsulation protocols at once. + +The isdn device driver did already support several different +encapsulation protocols. The encapsulation protocol is configured by a +user space utility (isdnctrl). The isdn network interface code then +uses several case statements which select appropriate actions +depending on the currently configured encapsulation protocol. + +In contrast, LAN network interfaces always used a single encapsulation +protocol which is unique to the hardware type of the interface. The LAN +encapsulation is usually done by just sticking a header on the data. Thus, +traditional linux network device drivers used to process the +encapsulation protocol directly (usually by just providing a hard_header() +method in the device structure) using some hardware type specific support +functions. This is simple, direct and efficient. But it doesn't fit all +the requirements for complex WAN encapsulations. + + + The configurability of the encapsulation protocol to be used + makes isdn network interfaces more flexible, but also much more + complex than traditional lan network interfaces. + + +Many Encapsulation protocols used on top of WAN connections will not just +stick a header on the data. They also might need to set up or release +the WAN connection. They also might want to send other data for their +private purpose over the wire, e.g. ppp does a lot of link level +negotiation before the first piece of user data can be transmitted. +Such encapsulation protocols for WAN devices are typically more complex +than encapsulation protocols for lan devices. Thus, network interface +code for typical WAN devices also tends to be more complex. + + +In order to support Linux' x25 PLP implementation on top of +isdn network interfaces I could have introduced yet another branch to +the various case statements inside drivers/isdn/isdn_net.c. +This eventually made isdn_net.c even more complex. In addition, it made +isdn_net.c harder to maintain. Thus, by identifying an abstract +interface between the network interface code and the encapsulation +protocol, complexity could be reduced and maintainability could be +increased. + + +Likewise, a similar encapsulation protocol will frequently be needed by +several different interfaces of even different hardware type, e.g. the +synchronous ppp implementation used by the isdn driver and the +asynchronous ppp implementation used by the ppp driver have a lot of +similar code in them. By cleanly separating the encapsulation protocol +from the hardware specific interface stuff such code could be shared +better in future. + + +When operating over dial-up-connections (e.g. telephone lines via modem, +non-permanent virtual circuits of wide area networks, ISDN) many +encapsulation protocols will need to control the connection. Therefore, +some basic connection control primitives are supported. The type and +semantics of the connection (i.e the ISO layer where connection service +is provided) is outside our scope and might be different depending on +the encapsulation protocol used, e.g. for a ppp module using our service +on top of a modem connection a connect_request will result in dialing +a (somewhere else configured) remote phone number. For an X25-interface +module (LAPB semantics, as defined in Documentation/networking/x25-iface.txt) +a connect_request will ask for establishing a reliable lapb +datalink connection. + + +The encapsulation protocol currently provides the following +service primitives to the network device. + +- create a new encapsulation protocol instance +- delete encapsulation protocol instance and free all its resources +- initialize (open) the encapsulation protocol instance for use. +- deactivate (close) an encapsulation protocol instance. +- process (xmit) data handed down by upper protocol layer +- receive data from lower (hardware) layer +- process connect indication from lower (hardware) layer +- process disconnect indication from lower (hardware) layer + + +The network interface driver accesses those primitives via callbacks +provided by the encapsulation protocol instance within a +struct concap_proto_ops. + +struct concap_proto_ops{ + + /* create a new encapsulation protocol instance of same type */ + struct concap_proto * (*proto_new) (void); + + /* delete encapsulation protocol instance and free all its resources. + cprot may no longer be referenced after calling this */ + void (*proto_del)(struct concap_proto *cprot); + + /* initialize the protocol's data. To be called at interface startup + or when the device driver resets the interface. All services of the + encapsulation protocol may be used after this*/ + int (*restart)(struct concap_proto *cprot, + struct net_device *ndev, + struct concap_device_ops *dops); + + /* deactivate an encapsulation protocol instance. The encapsulation + protocol may not call any *dops methods after this. */ + int (*close)(struct concap_proto *cprot); + + /* process a frame handed down to us by upper layer */ + int (*encap_and_xmit)(struct concap_proto *cprot, struct sk_buff *skb); + + /* to be called for each data entity received from lower layer*/ + int (*data_ind)(struct concap_proto *cprot, struct sk_buff *skb); + + /* to be called when a connection was set up/down. + Protocols that don't process these primitives might fill in + dummy methods here */ + int (*connect_ind)(struct concap_proto *cprot); + int (*disconn_ind)(struct concap_proto *cprot); +}; + + +The data structures are defined in the header file include/linux/concap.h. + + +A Network interface using encapsulation protocols must also provide +some service primitives to the encapsulation protocol: + +- request data being submitted by lower layer (device hardware) +- request a connection being set up by lower layer +- request a connection being released by lower layer + +The encapsulation protocol accesses those primitives via callbacks +provided by the network interface within a struct concap_device_ops. + +struct concap_device_ops{ + + /* to request data be submitted by device */ + int (*data_req)(struct concap_proto *, struct sk_buff *); + + /* Control methods must be set to NULL by devices which do not + support connection control. */ + /* to request a connection be set up */ + int (*connect_req)(struct concap_proto *); + + /* to request a connection be released */ + int (*disconn_req)(struct concap_proto *); +}; + +The network interface does not explicitly provide a receive service +because the encapsulation protocol directly calls netif_rx(). + + + + +An encapsulation protocol itself is actually the +struct concap_proto{ + struct net_device *net_dev; /* net device using our service */ + struct concap_device_ops *dops; /* callbacks provided by device */ + struct concap_proto_ops *pops; /* callbacks provided by us */ + int flags; + void *proto_data; /* protocol specific private data, to + be accessed via *pops methods only*/ + /* + : + whatever + : + */ +}; + +Most of this is filled in when the device requests the protocol to +be reset (opend). The network interface must provide the net_dev and +dops pointers. Other concap_proto members should be considered private +data that are only accessed by the pops callback functions. Likewise, +a concap proto should access the network device's private data +only by means of the callbacks referred to by the dops pointer. + + +A possible extended device structure which uses the connection controlling +encapsulation services could look like this: + +struct concap_device{ + struct net_device net_dev; + struct my_priv /* device->local stuff */ + /* the my_priv struct might contain a + struct concap_device_ops *dops; + to provide the device specific callbacks + */ + struct concap_proto *cprot; /* callbacks provided by protocol */ +}; + + + +Misc Thoughts +============= + +The concept of the concap proto might help to reuse protocol code and +reduce the complexity of certain network interface implementations. +The trade off is that it introduces yet another procedure call layer +when processing the protocol. This has of course some impact on +performance. However, typically the concap interface will be used by +devices attached to slow lines (like telephone, isdn, leased synchronous +lines). For such slow lines, the overhead is probably negligible. +This might no longer hold for certain high speed WAN links (like +ATM). + + +If general linux network interfaces explicitly supported concap +protocols (e.g. by a member struct concap_proto* in struct net_device) +then the interface of the service function could be changed +by passing a pointer of type (struct net_device*) instead of +type (struct concap_proto*). Doing so would make many of the service +functions compatible to network device support functions. + +e.g. instead of the concap protocol's service function + + int (*encap_and_xmit)(struct concap_proto *cprot, struct sk_buff *skb); + +we could have + + int (*encap_and_xmit)(struct net_device *ndev, struct sk_buff *skb); + +As this is compatible to the dev->hard_start_xmit() method, the device +driver could directly register the concap protocol's encap_and_xmit() +function as its hard_start_xmit() method. This would eliminate one +procedure call layer. + + +The device's data request function could also be defined as + + int (*data_req)(struct net_device *ndev, struct sk_buff *skb); + +This might even allow for some protocol stacking. And the network +interface might even register the same data_req() function directly +as its hard_start_xmit() method when a zero layer encapsulation +protocol is configured. Thus, eliminating the performance penalty +of the concap interface when a trivial concap protocol is used. +Nevertheless, the device remains able to support encapsulation +protocol configuration. + |