Commit | Line | Data |
---|---|---|
1da177e4 LT |
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. | |
0f035b8e | 114 | cprot may no longer be referenced after calling this */ |
1da177e4 LT |
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 |