1 /* SPDX-License-Identifier: MIT */ 1 /* SPDX-License-Identifier: MIT */
2 /********************************************* 2 /******************************************************************************
3 * xen_netif.h 3 * xen_netif.h
4 * 4 *
5 * Unified network-device I/O interface for Xe 5 * Unified network-device I/O interface for Xen guest OSes.
6 * 6 *
7 * Copyright (c) 2003-2004, Keir Fraser 7 * Copyright (c) 2003-2004, Keir Fraser
8 */ 8 */
9 9
10 #ifndef __XEN_PUBLIC_IO_XEN_NETIF_H__ 10 #ifndef __XEN_PUBLIC_IO_XEN_NETIF_H__
11 #define __XEN_PUBLIC_IO_XEN_NETIF_H__ 11 #define __XEN_PUBLIC_IO_XEN_NETIF_H__
12 12
13 #include "ring.h" 13 #include "ring.h"
14 #include "../grant_table.h" 14 #include "../grant_table.h"
15 15
16 /* 16 /*
17 * Older implementation of Xen network fronten 17 * Older implementation of Xen network frontend / backend has an
18 * implicit dependency on the MAX_SKB_FRAGS as 18 * implicit dependency on the MAX_SKB_FRAGS as the maximum number of
19 * ring slots a skb can use. Netfront / netbac 19 * ring slots a skb can use. Netfront / netback may not work as
20 * expected when frontend and backend have dif 20 * expected when frontend and backend have different MAX_SKB_FRAGS.
21 * 21 *
22 * A better approach is to add mechanism for n 22 * A better approach is to add mechanism for netfront / netback to
23 * negotiate this value. However we cannot fix 23 * negotiate this value. However we cannot fix all possible
24 * frontends, so we need to define a value whi 24 * frontends, so we need to define a value which states the minimum
25 * slots backend must support. 25 * slots backend must support.
26 * 26 *
27 * The minimum value derives from older Linux 27 * The minimum value derives from older Linux kernel's MAX_SKB_FRAGS
28 * (18), which is proved to work with most fro 28 * (18), which is proved to work with most frontends. Any new backend
29 * which doesn't negotiate with frontend shoul 29 * which doesn't negotiate with frontend should expect frontend to
30 * send a valid packet using slots up to this 30 * send a valid packet using slots up to this value.
31 */ 31 */
32 #define XEN_NETIF_NR_SLOTS_MIN 18 32 #define XEN_NETIF_NR_SLOTS_MIN 18
33 33
34 /* 34 /*
35 * Notifications after enqueuing any type of m 35 * Notifications after enqueuing any type of message should be conditional on
36 * the appropriate req_event or rsp_event fiel 36 * the appropriate req_event or rsp_event field in the shared ring.
37 * If the client sends notification for rx req 37 * If the client sends notification for rx requests then it should specify
38 * feature 'feature-rx-notify' via xenbus. Oth 38 * feature 'feature-rx-notify' via xenbus. Otherwise the backend will assume
39 * that it cannot safely queue packets (as it 39 * that it cannot safely queue packets (as it may not be kicked to send them).
40 */ 40 */
41 41
42 /* 42 /*
43 * "feature-split-event-channels" is introduce 43 * "feature-split-event-channels" is introduced to separate guest TX
44 * and RX notification. Backend either doesn't 44 * and RX notification. Backend either doesn't support this feature or
45 * advertises it via xenstore as 0 (disabled) 45 * advertises it via xenstore as 0 (disabled) or 1 (enabled).
46 * 46 *
47 * To make use of this feature, frontend shoul 47 * To make use of this feature, frontend should allocate two event
48 * channels for TX and RX, advertise them to b 48 * channels for TX and RX, advertise them to backend as
49 * "event-channel-tx" and "event-channel-rx" r 49 * "event-channel-tx" and "event-channel-rx" respectively. If frontend
50 * doesn't want to use this feature, it just w 50 * doesn't want to use this feature, it just writes "event-channel"
51 * node as before. 51 * node as before.
52 */ 52 */
53 53
54 /* 54 /*
55 * Multiple transmit and receive queues: 55 * Multiple transmit and receive queues:
56 * If supported, the backend will write the ke 56 * If supported, the backend will write the key "multi-queue-max-queues" to
57 * the directory for that vif, and set its val 57 * the directory for that vif, and set its value to the maximum supported
58 * number of queues. 58 * number of queues.
59 * Frontends that are aware of this feature an 59 * Frontends that are aware of this feature and wish to use it can write the
60 * key "multi-queue-num-queues", set to the nu 60 * key "multi-queue-num-queues", set to the number they wish to use, which
61 * must be greater than zero, and no more than 61 * must be greater than zero, and no more than the value reported by the backend
62 * in "multi-queue-max-queues". 62 * in "multi-queue-max-queues".
63 * 63 *
64 * Queues replicate the shared rings and event 64 * Queues replicate the shared rings and event channels.
65 * "feature-split-event-channels" may optional 65 * "feature-split-event-channels" may optionally be used when using
66 * multiple queues, but is not mandatory. 66 * multiple queues, but is not mandatory.
67 * 67 *
68 * Each queue consists of one shared ring pair 68 * Each queue consists of one shared ring pair, i.e. there must be the same
69 * number of tx and rx rings. 69 * number of tx and rx rings.
70 * 70 *
71 * For frontends requesting just one queue, th 71 * For frontends requesting just one queue, the usual event-channel and
72 * ring-ref keys are written as before, simpli 72 * ring-ref keys are written as before, simplifying the backend processing
73 * to avoid distinguishing between a frontend 73 * to avoid distinguishing between a frontend that doesn't understand the
74 * multi-queue feature, and one that does, but 74 * multi-queue feature, and one that does, but requested only one queue.
75 * 75 *
76 * Frontends requesting two or more queues mus 76 * Frontends requesting two or more queues must not write the toplevel
77 * event-channel (or event-channel-{tx,rx}) an 77 * event-channel (or event-channel-{tx,rx}) and {tx,rx}-ring-ref keys,
78 * instead writing those keys under sub-keys h 78 * instead writing those keys under sub-keys having the name "queue-N" where
79 * N is the integer ID of the queue for which 79 * N is the integer ID of the queue for which those keys belong. Queues
80 * are indexed from zero. For example, a front 80 * are indexed from zero. For example, a frontend with two queues and split
81 * event channels must write the following set 81 * event channels must write the following set of queue-related keys:
82 * 82 *
83 * /local/domain/1/device/vif/0/multi-queue-nu 83 * /local/domain/1/device/vif/0/multi-queue-num-queues = "2"
84 * /local/domain/1/device/vif/0/queue-0 = "" 84 * /local/domain/1/device/vif/0/queue-0 = ""
85 * /local/domain/1/device/vif/0/queue-0/tx-rin 85 * /local/domain/1/device/vif/0/queue-0/tx-ring-ref = "<ring-ref-tx0>"
86 * /local/domain/1/device/vif/0/queue-0/rx-rin 86 * /local/domain/1/device/vif/0/queue-0/rx-ring-ref = "<ring-ref-rx0>"
87 * /local/domain/1/device/vif/0/queue-0/event- 87 * /local/domain/1/device/vif/0/queue-0/event-channel-tx = "<evtchn-tx0>"
88 * /local/domain/1/device/vif/0/queue-0/event- 88 * /local/domain/1/device/vif/0/queue-0/event-channel-rx = "<evtchn-rx0>"
89 * /local/domain/1/device/vif/0/queue-1 = "" 89 * /local/domain/1/device/vif/0/queue-1 = ""
90 * /local/domain/1/device/vif/0/queue-1/tx-rin 90 * /local/domain/1/device/vif/0/queue-1/tx-ring-ref = "<ring-ref-tx1>"
91 * /local/domain/1/device/vif/0/queue-1/rx-rin 91 * /local/domain/1/device/vif/0/queue-1/rx-ring-ref = "<ring-ref-rx1"
92 * /local/domain/1/device/vif/0/queue-1/event- 92 * /local/domain/1/device/vif/0/queue-1/event-channel-tx = "<evtchn-tx1>"
93 * /local/domain/1/device/vif/0/queue-1/event- 93 * /local/domain/1/device/vif/0/queue-1/event-channel-rx = "<evtchn-rx1>"
94 * 94 *
95 * If there is any inconsistency in the XenSto 95 * If there is any inconsistency in the XenStore data, the backend may
96 * choose not to connect any queues, instead t 96 * choose not to connect any queues, instead treating the request as an
97 * error. This includes scenarios where more ( 97 * error. This includes scenarios where more (or fewer) queues were
98 * requested than the frontend provided detail 98 * requested than the frontend provided details for.
99 * 99 *
100 * Mapping of packets to queues is considered 100 * Mapping of packets to queues is considered to be a function of the
101 * transmitting system (backend or frontend) a 101 * transmitting system (backend or frontend) and is not negotiated
102 * between the two. Guests are free to transmi 102 * between the two. Guests are free to transmit packets on any queue
103 * they choose, provided it has been set up co 103 * they choose, provided it has been set up correctly. Guests must be
104 * prepared to receive packets on any queue th 104 * prepared to receive packets on any queue they have requested be set up.
105 */ 105 */
106 106
107 /* 107 /*
108 * "feature-no-csum-offload" should be used to 108 * "feature-no-csum-offload" should be used to turn IPv4 TCP/UDP checksum
109 * offload off or on. If it is missing then th 109 * offload off or on. If it is missing then the feature is assumed to be on.
110 * "feature-ipv6-csum-offload" should be used 110 * "feature-ipv6-csum-offload" should be used to turn IPv6 TCP/UDP checksum
111 * offload on or off. If it is missing then th 111 * offload on or off. If it is missing then the feature is assumed to be off.
112 */ 112 */
113 113
114 /* 114 /*
115 * "feature-gso-tcpv4" and "feature-gso-tcpv6" 115 * "feature-gso-tcpv4" and "feature-gso-tcpv6" advertise the capability to
116 * handle large TCP packets (in IPv4 or IPv6 f 116 * handle large TCP packets (in IPv4 or IPv6 form respectively). Neither
117 * frontends nor backends are assumed to be ca 117 * frontends nor backends are assumed to be capable unless the flags are
118 * present. 118 * present.
119 */ 119 */
120 120
121 /* 121 /*
122 * "feature-multicast-control" and "feature-dy 122 * "feature-multicast-control" and "feature-dynamic-multicast-control"
123 * advertise the capability to filter ethernet 123 * advertise the capability to filter ethernet multicast packets in the
124 * backend. If the frontend wishes to take adv 124 * backend. If the frontend wishes to take advantage of this feature then
125 * it may set "request-multicast-control". If 125 * it may set "request-multicast-control". If the backend only advertises
126 * "feature-multicast-control" then "request-m 126 * "feature-multicast-control" then "request-multicast-control" must be set
127 * before the frontend moves into the connecte 127 * before the frontend moves into the connected state. The backend will
128 * sample the value on this state transition a 128 * sample the value on this state transition and any subsequent change in
129 * value will have no effect. However, if the 129 * value will have no effect. However, if the backend also advertises
130 * "feature-dynamic-multicast-control" then "r 130 * "feature-dynamic-multicast-control" then "request-multicast-control"
131 * may be set by the frontend at any time. In 131 * may be set by the frontend at any time. In this case, the backend will
132 * watch the value and re-sample on watch even 132 * watch the value and re-sample on watch events.
133 * 133 *
134 * If the sampled value of "request-multicast- 134 * If the sampled value of "request-multicast-control" is set then the
135 * backend transmit side should no longer floo 135 * backend transmit side should no longer flood multicast packets to the
136 * frontend, it should instead drop any multic 136 * frontend, it should instead drop any multicast packet that does not
137 * match in a filter list. 137 * match in a filter list.
138 * The list is amended by the frontend by send 138 * The list is amended by the frontend by sending dummy transmit requests
139 * containing XEN_NETIF_EXTRA_TYPE_MCAST_{ADD, 139 * containing XEN_NETIF_EXTRA_TYPE_MCAST_{ADD,DEL} extra-info fragments as
140 * specified below. 140 * specified below.
141 * Note that the filter list may be amended ev 141 * Note that the filter list may be amended even if the sampled value of
142 * "request-multicast-control" is not set, how 142 * "request-multicast-control" is not set, however the filter should only
143 * be applied if it is set. 143 * be applied if it is set.
144 */ 144 */
145 145
146 /* 146 /*
147 * "xdp-headroom" is used to request that extr 147 * "xdp-headroom" is used to request that extra space is added
148 * for XDP processing. The value is measured 148 * for XDP processing. The value is measured in bytes and passed by
149 * the frontend to be consistent between both 149 * the frontend to be consistent between both ends.
150 * If the value is greater than zero that mean 150 * If the value is greater than zero that means that
151 * an RX response is going to be passed to an 151 * an RX response is going to be passed to an XDP program for processing.
152 * XEN_NETIF_MAX_XDP_HEADROOM defines the maxi 152 * XEN_NETIF_MAX_XDP_HEADROOM defines the maximum headroom offset in bytes
153 * 153 *
154 * "feature-xdp-headroom" is set to "1" by the 154 * "feature-xdp-headroom" is set to "1" by the netback side like other features
155 * so a guest can check if an XDP program can 155 * so a guest can check if an XDP program can be processed.
156 */ 156 */
157 #define XEN_NETIF_MAX_XDP_HEADROOM 0x7FFF 157 #define XEN_NETIF_MAX_XDP_HEADROOM 0x7FFF
158 158
159 /* 159 /*
160 * Control ring 160 * Control ring
161 * ============ 161 * ============
162 * 162 *
163 * Some features, such as hashing (detailed be 163 * Some features, such as hashing (detailed below), require a
164 * significant amount of out-of-band data to b 164 * significant amount of out-of-band data to be passed from frontend to
165 * backend. Use of xenstore is not suitable fo 165 * backend. Use of xenstore is not suitable for large quantities of data
166 * because of quota limitations and so a dedic 166 * because of quota limitations and so a dedicated 'control ring' is used.
167 * The ability of the backend to use a control 167 * The ability of the backend to use a control ring is advertised by
168 * setting: 168 * setting:
169 * 169 *
170 * /local/domain/X/backend/<domid>/<vif>/featu 170 * /local/domain/X/backend/<domid>/<vif>/feature-ctrl-ring = "1"
171 * 171 *
172 * The frontend provides a control ring to the 172 * The frontend provides a control ring to the backend by setting:
173 * 173 *
174 * /local/domain/<domid>/device/vif/<vif>/ctrl 174 * /local/domain/<domid>/device/vif/<vif>/ctrl-ring-ref = <gref>
175 * /local/domain/<domid>/device/vif/<vif>/even 175 * /local/domain/<domid>/device/vif/<vif>/event-channel-ctrl = <port>
176 * 176 *
177 * where <gref> is the grant reference of the 177 * where <gref> is the grant reference of the shared page used to
178 * implement the control ring and <port> is an 178 * implement the control ring and <port> is an event channel to be used
179 * as a mailbox interrupt. These keys must be 179 * as a mailbox interrupt. These keys must be set before the frontend
180 * moves into the connected state. 180 * moves into the connected state.
181 * 181 *
182 * The control ring uses a fixed request/respo 182 * The control ring uses a fixed request/response message size and is
183 * balanced (i.e. one request to one response) 183 * balanced (i.e. one request to one response), so operationally it is much
184 * the same as a transmit or receive ring. 184 * the same as a transmit or receive ring.
185 * Note that there is no requirement that resp 185 * Note that there is no requirement that responses are issued in the same
186 * order as requests. 186 * order as requests.
187 */ 187 */
188 188
189 /* 189 /*
190 * Hash types 190 * Hash types
191 * ========== 191 * ==========
192 * 192 *
193 * For the purposes of the definitions below, 193 * For the purposes of the definitions below, 'Packet[]' is an array of
194 * octets containing an IP packet without opti 194 * octets containing an IP packet without options, 'Array[X..Y]' means a
195 * sub-array of 'Array' containing bytes X thr 195 * sub-array of 'Array' containing bytes X thru Y inclusive, and '+' is
196 * used to indicate concatenation of arrays. 196 * used to indicate concatenation of arrays.
197 */ 197 */
198 198
199 /* 199 /*
200 * A hash calculated over an IP version 4 head 200 * A hash calculated over an IP version 4 header as follows:
201 * 201 *
202 * Buffer[0..8] = Packet[12..15] (source addre 202 * Buffer[0..8] = Packet[12..15] (source address) +
203 * Packet[16..19] (destination 203 * Packet[16..19] (destination address)
204 * 204 *
205 * Result = Hash(Buffer, 8) 205 * Result = Hash(Buffer, 8)
206 */ 206 */
207 #define _XEN_NETIF_CTRL_HASH_TYPE_IPV4 0 207 #define _XEN_NETIF_CTRL_HASH_TYPE_IPV4 0
208 #define XEN_NETIF_CTRL_HASH_TYPE_IPV4 \ 208 #define XEN_NETIF_CTRL_HASH_TYPE_IPV4 \
209 (1 << _XEN_NETIF_CTRL_HASH_TYPE_IPV4) 209 (1 << _XEN_NETIF_CTRL_HASH_TYPE_IPV4)
210 210
211 /* 211 /*
212 * A hash calculated over an IP version 4 head 212 * A hash calculated over an IP version 4 header and TCP header as
213 * follows: 213 * follows:
214 * 214 *
215 * Buffer[0..12] = Packet[12..15] (source addr 215 * Buffer[0..12] = Packet[12..15] (source address) +
216 * Packet[16..19] (destination 216 * Packet[16..19] (destination address) +
217 * Packet[20..21] (source port 217 * Packet[20..21] (source port) +
218 * Packet[22..23] (destination 218 * Packet[22..23] (destination port)
219 * 219 *
220 * Result = Hash(Buffer, 12) 220 * Result = Hash(Buffer, 12)
221 */ 221 */
222 #define _XEN_NETIF_CTRL_HASH_TYPE_IPV4_TCP 1 222 #define _XEN_NETIF_CTRL_HASH_TYPE_IPV4_TCP 1
223 #define XEN_NETIF_CTRL_HASH_TYPE_IPV4_TCP \ 223 #define XEN_NETIF_CTRL_HASH_TYPE_IPV4_TCP \
224 (1 << _XEN_NETIF_CTRL_HASH_TYPE_IPV4_T 224 (1 << _XEN_NETIF_CTRL_HASH_TYPE_IPV4_TCP)
225 225
226 /* 226 /*
227 * A hash calculated over an IP version 6 head 227 * A hash calculated over an IP version 6 header as follows:
228 * 228 *
229 * Buffer[0..32] = Packet[8..23] (source addr 229 * Buffer[0..32] = Packet[8..23] (source address ) +
230 * Packet[24..39] (destination 230 * Packet[24..39] (destination address)
231 * 231 *
232 * Result = Hash(Buffer, 32) 232 * Result = Hash(Buffer, 32)
233 */ 233 */
234 #define _XEN_NETIF_CTRL_HASH_TYPE_IPV6 2 234 #define _XEN_NETIF_CTRL_HASH_TYPE_IPV6 2
235 #define XEN_NETIF_CTRL_HASH_TYPE_IPV6 \ 235 #define XEN_NETIF_CTRL_HASH_TYPE_IPV6 \
236 (1 << _XEN_NETIF_CTRL_HASH_TYPE_IPV6) 236 (1 << _XEN_NETIF_CTRL_HASH_TYPE_IPV6)
237 237
238 /* 238 /*
239 * A hash calculated over an IP version 6 head 239 * A hash calculated over an IP version 6 header and TCP header as
240 * follows: 240 * follows:
241 * 241 *
242 * Buffer[0..36] = Packet[8..23] (source addr 242 * Buffer[0..36] = Packet[8..23] (source address) +
243 * Packet[24..39] (destination 243 * Packet[24..39] (destination address) +
244 * Packet[40..41] (source port 244 * Packet[40..41] (source port) +
245 * Packet[42..43] (destination 245 * Packet[42..43] (destination port)
246 * 246 *
247 * Result = Hash(Buffer, 36) 247 * Result = Hash(Buffer, 36)
248 */ 248 */
249 #define _XEN_NETIF_CTRL_HASH_TYPE_IPV6_TCP 3 249 #define _XEN_NETIF_CTRL_HASH_TYPE_IPV6_TCP 3
250 #define XEN_NETIF_CTRL_HASH_TYPE_IPV6_TCP \ 250 #define XEN_NETIF_CTRL_HASH_TYPE_IPV6_TCP \
251 (1 << _XEN_NETIF_CTRL_HASH_TYPE_IPV6_T 251 (1 << _XEN_NETIF_CTRL_HASH_TYPE_IPV6_TCP)
252 252
253 /* 253 /*
254 * Hash algorithms 254 * Hash algorithms
255 * =============== 255 * ===============
256 */ 256 */
257 257
258 #define XEN_NETIF_CTRL_HASH_ALGORITHM_NONE 0 258 #define XEN_NETIF_CTRL_HASH_ALGORITHM_NONE 0
259 259
260 /* 260 /*
261 * Toeplitz hash: 261 * Toeplitz hash:
262 */ 262 */
263 263
264 #define XEN_NETIF_CTRL_HASH_ALGORITHM_TOEPLITZ 264 #define XEN_NETIF_CTRL_HASH_ALGORITHM_TOEPLITZ 1
265 265
266 /* 266 /*
267 * This algorithm uses a 'key' as well as the 267 * This algorithm uses a 'key' as well as the data buffer itself.
268 * (Buffer[] and Key[] are treated as shift-re 268 * (Buffer[] and Key[] are treated as shift-registers where the MSB of
269 * Buffer/Key[0] is considered 'left-most' and 269 * Buffer/Key[0] is considered 'left-most' and the LSB of Buffer/Key[N-1]
270 * is the 'right-most'). 270 * is the 'right-most').
271 * 271 *
272 * Value = 0 272 * Value = 0
273 * For number of bits in Buffer[] 273 * For number of bits in Buffer[]
274 * If (left-most bit of Buffer[] is 1) 274 * If (left-most bit of Buffer[] is 1)
275 * Value ^= left-most 32 bits of Key[] 275 * Value ^= left-most 32 bits of Key[]
276 * Key[] << 1 276 * Key[] << 1
277 * Buffer[] << 1 277 * Buffer[] << 1
278 * 278 *
279 * The code below is provided for convenience 279 * The code below is provided for convenience where an operating system
280 * does not already provide an implementation. 280 * does not already provide an implementation.
281 */ 281 */
282 #ifdef XEN_NETIF_DEFINE_TOEPLITZ 282 #ifdef XEN_NETIF_DEFINE_TOEPLITZ
283 static uint32_t xen_netif_toeplitz_hash(const 283 static uint32_t xen_netif_toeplitz_hash(const uint8_t *key,
284 unsign 284 unsigned int keylen,
285 const 285 const uint8_t *buf, unsigned int buflen)
286 { 286 {
287 unsigned int keyi, bufi; 287 unsigned int keyi, bufi;
288 uint64_t prefix = 0; 288 uint64_t prefix = 0;
289 uint64_t hash = 0; 289 uint64_t hash = 0;
290 290
291 /* Pre-load prefix with the first 8 by 291 /* Pre-load prefix with the first 8 bytes of the key */
292 for (keyi = 0; keyi < 8; keyi++) { 292 for (keyi = 0; keyi < 8; keyi++) {
293 prefix <<= 8; 293 prefix <<= 8;
294 prefix |= (keyi < keylen) ? ke 294 prefix |= (keyi < keylen) ? key[keyi] : 0;
295 } 295 }
296 296
297 for (bufi = 0; bufi < buflen; bufi++) 297 for (bufi = 0; bufi < buflen; bufi++) {
298 uint8_t byte = buf[bufi]; 298 uint8_t byte = buf[bufi];
299 unsigned int bit; 299 unsigned int bit;
300 300
301 for (bit = 0; bit < 8; bit++) 301 for (bit = 0; bit < 8; bit++) {
302 if (byte & 0x80) 302 if (byte & 0x80)
303 hash ^= prefix 303 hash ^= prefix;
304 prefix <<= 1; 304 prefix <<= 1;
305 byte <<= 1; 305 byte <<= 1;
306 } 306 }
307 307
308 /* 308 /*
309 * 'prefix' has now been left- 309 * 'prefix' has now been left-shifted by 8, so
310 * OR in the next byte. 310 * OR in the next byte.
311 */ 311 */
312 prefix |= (keyi < keylen) ? ke 312 prefix |= (keyi < keylen) ? key[keyi] : 0;
313 keyi++; 313 keyi++;
314 } 314 }
315 315
316 /* The valid part of the hash is in th 316 /* The valid part of the hash is in the upper 32 bits. */
317 return hash >> 32; 317 return hash >> 32;
318 } 318 }
319 #endif /* XEN_NETIF_D 319 #endif /* XEN_NETIF_DEFINE_TOEPLITZ */
320 320
321 /* 321 /*
322 * Control requests (struct xen_netif_ctrl_req 322 * Control requests (struct xen_netif_ctrl_request)
323 * =========================================== 323 * ================================================
324 * 324 *
325 * All requests have the following format: 325 * All requests have the following format:
326 * 326 *
327 * 0 1 2 3 4 5 6 327 * 0 1 2 3 4 5 6 7 octet
328 * +-----+-----+-----+-----+-----+-----+-----+ 328 * +-----+-----+-----+-----+-----+-----+-----+-----+
329 * | id | type | data[0] 329 * | id | type | data[0] |
330 * +-----+-----+-----+-----+-----+-----+-----+ 330 * +-----+-----+-----+-----+-----+-----+-----+-----+
331 * | data[1] | data[2] 331 * | data[1] | data[2] |
332 * +-----+-----+-----+-----+------------------ 332 * +-----+-----+-----+-----+-----------------------+
333 * 333 *
334 * id: the request identifier, echoed in respo 334 * id: the request identifier, echoed in response.
335 * type: the type of request (see below) 335 * type: the type of request (see below)
336 * data[]: any data associated with the reques 336 * data[]: any data associated with the request (determined by type)
337 */ 337 */
338 338
339 struct xen_netif_ctrl_request { 339 struct xen_netif_ctrl_request {
340 uint16_t id; 340 uint16_t id;
341 uint16_t type; 341 uint16_t type;
342 342
343 #define XEN_NETIF_CTRL_TYPE_INVALID 343 #define XEN_NETIF_CTRL_TYPE_INVALID 0
344 #define XEN_NETIF_CTRL_TYPE_GET_HASH_FLAGS 344 #define XEN_NETIF_CTRL_TYPE_GET_HASH_FLAGS 1
345 #define XEN_NETIF_CTRL_TYPE_SET_HASH_FLAGS 345 #define XEN_NETIF_CTRL_TYPE_SET_HASH_FLAGS 2
346 #define XEN_NETIF_CTRL_TYPE_SET_HASH_KEY 346 #define XEN_NETIF_CTRL_TYPE_SET_HASH_KEY 3
347 #define XEN_NETIF_CTRL_TYPE_GET_HASH_MAPPING_S 347 #define XEN_NETIF_CTRL_TYPE_GET_HASH_MAPPING_SIZE 4
348 #define XEN_NETIF_CTRL_TYPE_SET_HASH_MAPPING_S 348 #define XEN_NETIF_CTRL_TYPE_SET_HASH_MAPPING_SIZE 5
349 #define XEN_NETIF_CTRL_TYPE_SET_HASH_MAPPING 349 #define XEN_NETIF_CTRL_TYPE_SET_HASH_MAPPING 6
350 #define XEN_NETIF_CTRL_TYPE_SET_HASH_ALGORITHM 350 #define XEN_NETIF_CTRL_TYPE_SET_HASH_ALGORITHM 7
351 351
352 uint32_t data[3]; 352 uint32_t data[3];
353 }; 353 };
354 354
355 /* 355 /*
356 * Control responses (struct xen_netif_ctrl_re 356 * Control responses (struct xen_netif_ctrl_response)
357 * =========================================== 357 * ==================================================
358 * 358 *
359 * All responses have the following format: 359 * All responses have the following format:
360 * 360 *
361 * 0 1 2 3 4 5 6 361 * 0 1 2 3 4 5 6 7 octet
362 * +-----+-----+-----+-----+-----+-----+-----+ 362 * +-----+-----+-----+-----+-----+-----+-----+-----+
363 * | id | type | status 363 * | id | type | status |
364 * +-----+-----+-----+-----+-----+-----+-----+ 364 * +-----+-----+-----+-----+-----+-----+-----+-----+
365 * | data | 365 * | data |
366 * +-----+-----+-----+-----+ 366 * +-----+-----+-----+-----+
367 * 367 *
368 * id: the corresponding request identifier 368 * id: the corresponding request identifier
369 * type: the type of the corresponding request 369 * type: the type of the corresponding request
370 * status: the status of request processing 370 * status: the status of request processing
371 * data: any data associated with the response 371 * data: any data associated with the response (determined by type and
372 * status) 372 * status)
373 */ 373 */
374 374
375 struct xen_netif_ctrl_response { 375 struct xen_netif_ctrl_response {
376 uint16_t id; 376 uint16_t id;
377 uint16_t type; 377 uint16_t type;
378 uint32_t status; 378 uint32_t status;
379 379
380 #define XEN_NETIF_CTRL_STATUS_SUCCESS 380 #define XEN_NETIF_CTRL_STATUS_SUCCESS 0
381 #define XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED 381 #define XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED 1
382 #define XEN_NETIF_CTRL_STATUS_INVALID_PARAMETE 382 #define XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER 2
383 #define XEN_NETIF_CTRL_STATUS_BUFFER_OVERFLOW 383 #define XEN_NETIF_CTRL_STATUS_BUFFER_OVERFLOW 3
384 384
385 uint32_t data; 385 uint32_t data;
386 }; 386 };
387 387
388 /* 388 /*
389 * Control messages 389 * Control messages
390 * ================ 390 * ================
391 * 391 *
392 * XEN_NETIF_CTRL_TYPE_SET_HASH_ALGORITHM 392 * XEN_NETIF_CTRL_TYPE_SET_HASH_ALGORITHM
393 * -------------------------------------- 393 * --------------------------------------
394 * 394 *
395 * This is sent by the frontend to set the des 395 * This is sent by the frontend to set the desired hash algorithm.
396 * 396 *
397 * Request: 397 * Request:
398 * 398 *
399 * type = XEN_NETIF_CTRL_TYPE_SET_HASH_ALG 399 * type = XEN_NETIF_CTRL_TYPE_SET_HASH_ALGORITHM
400 * data[0] = a XEN_NETIF_CTRL_HASH_ALGORITHM_ 400 * data[0] = a XEN_NETIF_CTRL_HASH_ALGORITHM_* value
401 * data[1] = 0 401 * data[1] = 0
402 * data[2] = 0 402 * data[2] = 0
403 * 403 *
404 * Response: 404 * Response:
405 * 405 *
406 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORT 406 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not
407 * 407 * supported
408 * XEN_NETIF_CTRL_STATUS_INVALID_PAR 408 * XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER - The algorithm is not
409 * 409 * supported
410 * XEN_NETIF_CTRL_STATUS_SUCCESS 410 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful
411 * 411 *
412 * NOTE: Setting data[0] to XEN_NETIF_CTRL_HAS 412 * NOTE: Setting data[0] to XEN_NETIF_CTRL_HASH_ALGORITHM_NONE disables
413 * hashing and the backend is free to ch 413 * hashing and the backend is free to choose how it steers packets
414 * to queues (which is the default behav 414 * to queues (which is the default behaviour).
415 * 415 *
416 * XEN_NETIF_CTRL_TYPE_GET_HASH_FLAGS 416 * XEN_NETIF_CTRL_TYPE_GET_HASH_FLAGS
417 * ---------------------------------- 417 * ----------------------------------
418 * 418 *
419 * This is sent by the frontend to query the t 419 * This is sent by the frontend to query the types of hash supported by
420 * the backend. 420 * the backend.
421 * 421 *
422 * Request: 422 * Request:
423 * 423 *
424 * type = XEN_NETIF_CTRL_TYPE_GET_HASH_FLA 424 * type = XEN_NETIF_CTRL_TYPE_GET_HASH_FLAGS
425 * data[0] = 0 425 * data[0] = 0
426 * data[1] = 0 426 * data[1] = 0
427 * data[2] = 0 427 * data[2] = 0
428 * 428 *
429 * Response: 429 * Response:
430 * 430 *
431 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORT 431 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not supported
432 * XEN_NETIF_CTRL_STATUS_SUCCESS 432 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful
433 * data = supported hash types (if operatio 433 * data = supported hash types (if operation was successful)
434 * 434 *
435 * NOTE: A valid hash algorithm must be select 435 * NOTE: A valid hash algorithm must be selected before this operation can
436 * succeed. 436 * succeed.
437 * 437 *
438 * XEN_NETIF_CTRL_TYPE_SET_HASH_FLAGS 438 * XEN_NETIF_CTRL_TYPE_SET_HASH_FLAGS
439 * ---------------------------------- 439 * ----------------------------------
440 * 440 *
441 * This is sent by the frontend to set the typ 441 * This is sent by the frontend to set the types of hash that the backend
442 * should calculate. (See above for hash type 442 * should calculate. (See above for hash type definitions).
443 * Note that the 'maximal' type of hash should 443 * Note that the 'maximal' type of hash should always be chosen. For
444 * example, if the frontend sets both IPV4 and 444 * example, if the frontend sets both IPV4 and IPV4_TCP hash types then
445 * the latter hash type should be calculated f 445 * the latter hash type should be calculated for any TCP packet and the
446 * former only calculated for non-TCP packets. 446 * former only calculated for non-TCP packets.
447 * 447 *
448 * Request: 448 * Request:
449 * 449 *
450 * type = XEN_NETIF_CTRL_TYPE_SET_HASH_FLA 450 * type = XEN_NETIF_CTRL_TYPE_SET_HASH_FLAGS
451 * data[0] = bitwise OR of XEN_NETIF_CTRL_HAS 451 * data[0] = bitwise OR of XEN_NETIF_CTRL_HASH_TYPE_* values
452 * data[1] = 0 452 * data[1] = 0
453 * data[2] = 0 453 * data[2] = 0
454 * 454 *
455 * Response: 455 * Response:
456 * 456 *
457 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORT 457 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not
458 * 458 * supported
459 * XEN_NETIF_CTRL_STATUS_INVALID_PAR 459 * XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER - One or more flag
460 * 460 * value is invalid or
461 * 461 * unsupported
462 * XEN_NETIF_CTRL_STATUS_SUCCESS 462 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful
463 * data = 0 463 * data = 0
464 * 464 *
465 * NOTE: A valid hash algorithm must be select 465 * NOTE: A valid hash algorithm must be selected before this operation can
466 * succeed. 466 * succeed.
467 * Also, setting data[0] to zero disable 467 * Also, setting data[0] to zero disables hashing and the backend
468 * is free to choose how it steers packe 468 * is free to choose how it steers packets to queues.
469 * 469 *
470 * XEN_NETIF_CTRL_TYPE_SET_HASH_KEY 470 * XEN_NETIF_CTRL_TYPE_SET_HASH_KEY
471 * -------------------------------- 471 * --------------------------------
472 * 472 *
473 * This is sent by the frontend to set the key 473 * This is sent by the frontend to set the key of the hash if the algorithm
474 * requires it. (See hash algorithms above). 474 * requires it. (See hash algorithms above).
475 * 475 *
476 * Request: 476 * Request:
477 * 477 *
478 * type = XEN_NETIF_CTRL_TYPE_SET_HASH_KEY 478 * type = XEN_NETIF_CTRL_TYPE_SET_HASH_KEY
479 * data[0] = grant reference of page containi 479 * data[0] = grant reference of page containing the key (assumed to
480 * start at beginning of grant) 480 * start at beginning of grant)
481 * data[1] = size of key in octets 481 * data[1] = size of key in octets
482 * data[2] = 0 482 * data[2] = 0
483 * 483 *
484 * Response: 484 * Response:
485 * 485 *
486 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORT 486 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not
487 * 487 * supported
488 * XEN_NETIF_CTRL_STATUS_INVALID_PAR 488 * XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER - Key size is invalid
489 * XEN_NETIF_CTRL_STATUS_BUFFER_OVER 489 * XEN_NETIF_CTRL_STATUS_BUFFER_OVERFLOW - Key size is larger
490 * 490 * than the backend
491 * 491 * supports
492 * XEN_NETIF_CTRL_STATUS_SUCCESS 492 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful
493 * data = 0 493 * data = 0
494 * 494 *
495 * NOTE: Any key octets not specified are assu 495 * NOTE: Any key octets not specified are assumed to be zero (the key
496 * is assumed to be empty by default) an 496 * is assumed to be empty by default) and specifying a new key
497 * invalidates any previous key, hence s 497 * invalidates any previous key, hence specifying a key size of
498 * zero will clear the key (which ensure 498 * zero will clear the key (which ensures that the calculated hash
499 * will always be zero). 499 * will always be zero).
500 * The maximum size of key is algorithm 500 * The maximum size of key is algorithm and backend specific, but
501 * is also limited by the single grant r 501 * is also limited by the single grant reference.
502 * The grant reference may be read-only 502 * The grant reference may be read-only and must remain valid until
503 * the response has been processed. 503 * the response has been processed.
504 * 504 *
505 * XEN_NETIF_CTRL_TYPE_GET_HASH_MAPPING_SIZE 505 * XEN_NETIF_CTRL_TYPE_GET_HASH_MAPPING_SIZE
506 * ----------------------------------------- 506 * -----------------------------------------
507 * 507 *
508 * This is sent by the frontend to query the m 508 * This is sent by the frontend to query the maximum size of mapping
509 * table supported by the backend. The size is 509 * table supported by the backend. The size is specified in terms of
510 * table entries. 510 * table entries.
511 * 511 *
512 * Request: 512 * Request:
513 * 513 *
514 * type = XEN_NETIF_CTRL_TYPE_GET_HASH_MAP 514 * type = XEN_NETIF_CTRL_TYPE_GET_HASH_MAPPING_SIZE
515 * data[0] = 0 515 * data[0] = 0
516 * data[1] = 0 516 * data[1] = 0
517 * data[2] = 0 517 * data[2] = 0
518 * 518 *
519 * Response: 519 * Response:
520 * 520 *
521 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORT 521 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not supported
522 * XEN_NETIF_CTRL_STATUS_SUCCESS 522 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful
523 * data = maximum number of entries allowed 523 * data = maximum number of entries allowed in the mapping table
524 * (if operation was successful) or 524 * (if operation was successful) or zero if a mapping table is
525 * not supported (i.e. hash mapping 525 * not supported (i.e. hash mapping is done only by modular
526 * arithmetic). 526 * arithmetic).
527 * 527 *
528 * XEN_NETIF_CTRL_TYPE_SET_HASH_MAPPING_SIZE 528 * XEN_NETIF_CTRL_TYPE_SET_HASH_MAPPING_SIZE
529 * ------------------------------------- 529 * -------------------------------------
530 * 530 *
531 * This is sent by the frontend to set the act 531 * This is sent by the frontend to set the actual size of the mapping
532 * table to be used by the backend. The size i 532 * table to be used by the backend. The size is specified in terms of
533 * table entries. 533 * table entries.
534 * Any previous table is invalidated by this m 534 * Any previous table is invalidated by this message and any new table
535 * is assumed to be zero filled. 535 * is assumed to be zero filled.
536 * 536 *
537 * Request: 537 * Request:
538 * 538 *
539 * type = XEN_NETIF_CTRL_TYPE_SET_HASH_MAP 539 * type = XEN_NETIF_CTRL_TYPE_SET_HASH_MAPPING_SIZE
540 * data[0] = number of entries in mapping tab 540 * data[0] = number of entries in mapping table
541 * data[1] = 0 541 * data[1] = 0
542 * data[2] = 0 542 * data[2] = 0
543 * 543 *
544 * Response: 544 * Response:
545 * 545 *
546 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORT 546 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not
547 * 547 * supported
548 * XEN_NETIF_CTRL_STATUS_INVALID_PAR 548 * XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER - Table size is invalid
549 * XEN_NETIF_CTRL_STATUS_SUCCESS 549 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful
550 * data = 0 550 * data = 0
551 * 551 *
552 * NOTE: Setting data[0] to 0 means that hash 552 * NOTE: Setting data[0] to 0 means that hash mapping should be done
553 * using modular arithmetic. 553 * using modular arithmetic.
554 * 554 *
555 * XEN_NETIF_CTRL_TYPE_SET_HASH_MAPPING 555 * XEN_NETIF_CTRL_TYPE_SET_HASH_MAPPING
556 * ------------------------------------ 556 * ------------------------------------
557 * 557 *
558 * This is sent by the frontend to set the con 558 * This is sent by the frontend to set the content of the table mapping
559 * hash value to queue number. The backend sho 559 * hash value to queue number. The backend should calculate the hash from
560 * the packet header, use it as an index into 560 * the packet header, use it as an index into the table (modulo the size
561 * of the table) and then steer the packet to 561 * of the table) and then steer the packet to the queue number found at
562 * that index. 562 * that index.
563 * 563 *
564 * Request: 564 * Request:
565 * 565 *
566 * type = XEN_NETIF_CTRL_TYPE_SET_HASH_MAP 566 * type = XEN_NETIF_CTRL_TYPE_SET_HASH_MAPPING
567 * data[0] = grant reference of page containi 567 * data[0] = grant reference of page containing the mapping (sub-)table
568 * (assumed to start at beginning o 568 * (assumed to start at beginning of grant)
569 * data[1] = size of (sub-)table in entries 569 * data[1] = size of (sub-)table in entries
570 * data[2] = offset, in entries, of sub-table 570 * data[2] = offset, in entries, of sub-table within overall table
571 * 571 *
572 * Response: 572 * Response:
573 * 573 *
574 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORT 574 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not
575 * 575 * supported
576 * XEN_NETIF_CTRL_STATUS_INVALID_PAR 576 * XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER - Table size or content
577 * 577 * is invalid
578 * XEN_NETIF_CTRL_STATUS_BUFFER_OVER 578 * XEN_NETIF_CTRL_STATUS_BUFFER_OVERFLOW - Table size is larger
579 * 579 * than the backend
580 * 580 * supports
581 * XEN_NETIF_CTRL_STATUS_SUCCESS 581 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful
582 * data = 0 582 * data = 0
583 * 583 *
584 * NOTE: The overall table has the following f 584 * NOTE: The overall table has the following format:
585 * 585 *
586 * 0 1 2 3 4 5 586 * 0 1 2 3 4 5 6 7 octet
587 * +-----+-----+-----+-----+-----+-----+ 587 * +-----+-----+-----+-----+-----+-----+-----+-----+
588 * | mapping[0] | mappi 588 * | mapping[0] | mapping[1] |
589 * +-----+-----+-----+-----+-----+-----+ 589 * +-----+-----+-----+-----+-----+-----+-----+-----+
590 * | . 590 * | . |
591 * | . 591 * | . |
592 * | . 592 * | . |
593 * +-----+-----+-----+-----+-----+-----+ 593 * +-----+-----+-----+-----+-----+-----+-----+-----+
594 * | mapping[N-2] | mappin 594 * | mapping[N-2] | mapping[N-1] |
595 * +-----+-----+-----+-----+-----+-----+ 595 * +-----+-----+-----+-----+-----+-----+-----+-----+
596 * 596 *
597 * where N is specified by a XEN_NETIF_C 597 * where N is specified by a XEN_NETIF_CTRL_TYPE_SET_HASH_MAPPING_SIZE
598 * message and each mapping must specif 598 * message and each mapping must specifies a queue between 0 and
599 * "multi-queue-num-queues" (see above). 599 * "multi-queue-num-queues" (see above).
600 * The backend may support a mapping tab 600 * The backend may support a mapping table larger than can be
601 * mapped by a single grant reference. T 601 * mapped by a single grant reference. Thus sub-tables within a
602 * larger table can be individually set 602 * larger table can be individually set by sending multiple messages
603 * with differing offset values. Specify 603 * with differing offset values. Specifying a new sub-table does not
604 * invalidate any table data outside tha 604 * invalidate any table data outside that range.
605 * The grant reference may be read-only 605 * The grant reference may be read-only and must remain valid until
606 * the response has been processed. 606 * the response has been processed.
607 */ 607 */
608 608
609 DEFINE_RING_TYPES(xen_netif_ctrl, 609 DEFINE_RING_TYPES(xen_netif_ctrl,
610 struct xen_netif_ctrl_reques 610 struct xen_netif_ctrl_request,
611 struct xen_netif_ctrl_respon 611 struct xen_netif_ctrl_response);
612 612
613 /* 613 /*
614 * Guest transmit 614 * Guest transmit
615 * ============== 615 * ==============
616 * 616 *
617 * This is the 'wire' format for transmit (fro 617 * This is the 'wire' format for transmit (frontend -> backend) packets:
618 * 618 *
619 * Fragment 1: xen_netif_tx_request_t - flag 619 * Fragment 1: xen_netif_tx_request_t - flags = XEN_NETTXF_*
620 * size = t 620 * size = total packet size
621 * [Extra 1: xen_netif_extra_info_t] - (onl 621 * [Extra 1: xen_netif_extra_info_t] - (only if fragment 1 flags include
622 * XEN_NET 622 * XEN_NETTXF_extra_info)
623 * ... 623 * ...
624 * [Extra N: xen_netif_extra_info_t] - (onl 624 * [Extra N: xen_netif_extra_info_t] - (only if extra N-1 flags include
625 * XEN_NET 625 * XEN_NETIF_EXTRA_MORE)
626 * ... 626 * ...
627 * Fragment N: xen_netif_tx_request_t - (onl 627 * Fragment N: xen_netif_tx_request_t - (only if fragment N-1 flags include
628 * XEN_NET 628 * XEN_NETTXF_more_data - flags on preceding
629 * extras 629 * extras are not relevant here)
630 * flags = 630 * flags = 0
631 * size = f 631 * size = fragment size
632 * 632 *
633 * NOTE: 633 * NOTE:
634 * 634 *
635 * This format slightly is different from that 635 * This format slightly is different from that used for receive
636 * (backend -> frontend) packets. Specifically 636 * (backend -> frontend) packets. Specifically, in a multi-fragment
637 * packet the actual size of fragment 1 can on 637 * packet the actual size of fragment 1 can only be determined by
638 * subtracting the sizes of fragments 2..N fro 638 * subtracting the sizes of fragments 2..N from the total packet size.
639 * 639 *
640 * Ring slot size is 12 octets, however not al 640 * Ring slot size is 12 octets, however not all request/response
641 * structs use the full size. 641 * structs use the full size.
642 * 642 *
643 * tx request data (xen_netif_tx_request_t) 643 * tx request data (xen_netif_tx_request_t)
644 * ------------------------------------ 644 * ------------------------------------
645 * 645 *
646 * 0 1 2 3 4 5 6 646 * 0 1 2 3 4 5 6 7 octet
647 * +-----+-----+-----+-----+-----+-----+-----+ 647 * +-----+-----+-----+-----+-----+-----+-----+-----+
648 * | grant ref | offset | flags 648 * | grant ref | offset | flags |
649 * +-----+-----+-----+-----+-----+-----+-----+ 649 * +-----+-----+-----+-----+-----+-----+-----+-----+
650 * | id | size | 650 * | id | size |
651 * +-----+-----+-----+-----+ 651 * +-----+-----+-----+-----+
652 * 652 *
653 * grant ref: Reference to buffer page. 653 * grant ref: Reference to buffer page.
654 * offset: Offset within buffer page. 654 * offset: Offset within buffer page.
655 * flags: XEN_NETTXF_*. 655 * flags: XEN_NETTXF_*.
656 * id: request identifier, echoed in response. 656 * id: request identifier, echoed in response.
657 * size: packet size in bytes. 657 * size: packet size in bytes.
658 * 658 *
659 * tx response (xen_netif_tx_response_t) 659 * tx response (xen_netif_tx_response_t)
660 * --------------------------------- 660 * ---------------------------------
661 * 661 *
662 * 0 1 2 3 4 5 6 662 * 0 1 2 3 4 5 6 7 octet
663 * +-----+-----+-----+-----+-----+-----+-----+ 663 * +-----+-----+-----+-----+-----+-----+-----+-----+
664 * | id | status | unused 664 * | id | status | unused |
665 * +-----+-----+-----+-----+-----+-----+-----+ 665 * +-----+-----+-----+-----+-----+-----+-----+-----+
666 * | unused | 666 * | unused |
667 * +-----+-----+-----+-----+ 667 * +-----+-----+-----+-----+
668 * 668 *
669 * id: reflects id in transmit request 669 * id: reflects id in transmit request
670 * status: XEN_NETIF_RSP_* 670 * status: XEN_NETIF_RSP_*
671 * 671 *
672 * Guest receive 672 * Guest receive
673 * ============= 673 * =============
674 * 674 *
675 * This is the 'wire' format for receive (back 675 * This is the 'wire' format for receive (backend -> frontend) packets:
676 * 676 *
677 * Fragment 1: xen_netif_rx_request_t - flag 677 * Fragment 1: xen_netif_rx_request_t - flags = XEN_NETRXF_*
678 * size = f 678 * size = fragment size
679 * [Extra 1: xen_netif_extra_info_t] - (onl 679 * [Extra 1: xen_netif_extra_info_t] - (only if fragment 1 flags include
680 * XEN_NET 680 * XEN_NETRXF_extra_info)
681 * ... 681 * ...
682 * [Extra N: xen_netif_extra_info_t] - (onl 682 * [Extra N: xen_netif_extra_info_t] - (only if extra N-1 flags include
683 * XEN_NET 683 * XEN_NETIF_EXTRA_MORE)
684 * ... 684 * ...
685 * Fragment N: xen_netif_rx_request_t - (onl 685 * Fragment N: xen_netif_rx_request_t - (only if fragment N-1 flags include
686 * XEN_NET 686 * XEN_NETRXF_more_data - flags on preceding
687 * extras 687 * extras are not relevant here)
688 * flags = 688 * flags = 0
689 * size = f 689 * size = fragment size
690 * 690 *
691 * NOTE: 691 * NOTE:
692 * 692 *
693 * This format slightly is different from that 693 * This format slightly is different from that used for transmit
694 * (frontend -> backend) packets. Specifically 694 * (frontend -> backend) packets. Specifically, in a multi-fragment
695 * packet the size of the packet can only be d 695 * packet the size of the packet can only be determined by summing the
696 * sizes of fragments 1..N. 696 * sizes of fragments 1..N.
697 * 697 *
698 * Ring slot size is 8 octets. 698 * Ring slot size is 8 octets.
699 * 699 *
700 * rx request (xen_netif_rx_request_t) 700 * rx request (xen_netif_rx_request_t)
701 * ------------------------------- 701 * -------------------------------
702 * 702 *
703 * 0 1 2 3 4 5 6 703 * 0 1 2 3 4 5 6 7 octet
704 * +-----+-----+-----+-----+-----+-----+-----+ 704 * +-----+-----+-----+-----+-----+-----+-----+-----+
705 * | id | pad | gref 705 * | id | pad | gref |
706 * +-----+-----+-----+-----+-----+-----+-----+ 706 * +-----+-----+-----+-----+-----+-----+-----+-----+
707 * 707 *
708 * id: request identifier, echoed in response. 708 * id: request identifier, echoed in response.
709 * gref: reference to incoming granted frame. 709 * gref: reference to incoming granted frame.
710 * 710 *
711 * rx response (xen_netif_rx_response_t) 711 * rx response (xen_netif_rx_response_t)
712 * --------------------------------- 712 * ---------------------------------
713 * 713 *
714 * 0 1 2 3 4 5 6 714 * 0 1 2 3 4 5 6 7 octet
715 * +-----+-----+-----+-----+-----+-----+-----+ 715 * +-----+-----+-----+-----+-----+-----+-----+-----+
716 * | id | offset | flags | statu 716 * | id | offset | flags | status |
717 * +-----+-----+-----+-----+-----+-----+-----+ 717 * +-----+-----+-----+-----+-----+-----+-----+-----+
718 * 718 *
719 * id: reflects id in receive request 719 * id: reflects id in receive request
720 * offset: offset in page of start of received 720 * offset: offset in page of start of received packet
721 * flags: XEN_NETRXF_* 721 * flags: XEN_NETRXF_*
722 * status: -ve: XEN_NETIF_RSP_*; +ve: Rx'ed pk 722 * status: -ve: XEN_NETIF_RSP_*; +ve: Rx'ed pkt size.
723 * 723 *
724 * NOTE: Historically, to support GSO on the f 724 * NOTE: Historically, to support GSO on the frontend receive side, Linux
725 * netfront does not make use of the rx 725 * netfront does not make use of the rx response id (because, as
726 * described below, extra info structure 726 * described below, extra info structures overlay the id field).
727 * Instead it assumes that responses alw 727 * Instead it assumes that responses always appear in the same ring
728 * slot as their corresponding request. 728 * slot as their corresponding request. Thus, to maintain
729 * compatibility, backends must make sur 729 * compatibility, backends must make sure this is the case.
730 * 730 *
731 * Extra Info 731 * Extra Info
732 * ========== 732 * ==========
733 * 733 *
734 * Can be present if initial request or respon 734 * Can be present if initial request or response has NET{T,R}XF_extra_info,
735 * or previous extra request has XEN_NETIF_EXT 735 * or previous extra request has XEN_NETIF_EXTRA_MORE.
736 * 736 *
737 * The struct therefore needs to fit into eith 737 * The struct therefore needs to fit into either a tx or rx slot and
738 * is therefore limited to 8 octets. 738 * is therefore limited to 8 octets.
739 * 739 *
740 * NOTE: Because extra info data overlays the 740 * NOTE: Because extra info data overlays the usual request/response
741 * structures, there is no id informatio 741 * structures, there is no id information in the opposite direction.
742 * So, if an extra info overlays an rx r 742 * So, if an extra info overlays an rx response the frontend can
743 * assume that it is in the same ring sl 743 * assume that it is in the same ring slot as the request that was
744 * consumed to make the slot available, 744 * consumed to make the slot available, and the backend must ensure
745 * this assumption is true. 745 * this assumption is true.
746 * 746 *
747 * extra info (xen_netif_extra_info_t) 747 * extra info (xen_netif_extra_info_t)
748 * ------------------------------- 748 * -------------------------------
749 * 749 *
750 * General format: 750 * General format:
751 * 751 *
752 * 0 1 2 3 4 5 6 752 * 0 1 2 3 4 5 6 7 octet
753 * +-----+-----+-----+-----+-----+-----+-----+ 753 * +-----+-----+-----+-----+-----+-----+-----+-----+
754 * |type |flags| type specific data 754 * |type |flags| type specific data |
755 * +-----+-----+-----+-----+-----+-----+-----+ 755 * +-----+-----+-----+-----+-----+-----+-----+-----+
756 * | padding for tx | 756 * | padding for tx |
757 * +-----+-----+-----+-----+ 757 * +-----+-----+-----+-----+
758 * 758 *
759 * type: XEN_NETIF_EXTRA_TYPE_* 759 * type: XEN_NETIF_EXTRA_TYPE_*
760 * flags: XEN_NETIF_EXTRA_FLAG_* 760 * flags: XEN_NETIF_EXTRA_FLAG_*
761 * padding for tx: present only in the tx case 761 * padding for tx: present only in the tx case due to 8 octet limit
762 * from rx case. Not shown in 762 * from rx case. Not shown in type specific entries
763 * below. 763 * below.
764 * 764 *
765 * XEN_NETIF_EXTRA_TYPE_GSO: 765 * XEN_NETIF_EXTRA_TYPE_GSO:
766 * 766 *
767 * 0 1 2 3 4 5 6 767 * 0 1 2 3 4 5 6 7 octet
768 * +-----+-----+-----+-----+-----+-----+-----+ 768 * +-----+-----+-----+-----+-----+-----+-----+-----+
769 * |type |flags| size |type | pad | featu 769 * |type |flags| size |type | pad | features |
770 * +-----+-----+-----+-----+-----+-----+-----+ 770 * +-----+-----+-----+-----+-----+-----+-----+-----+
771 * 771 *
772 * type: Must be XEN_NETIF_EXTRA_TYPE_GSO 772 * type: Must be XEN_NETIF_EXTRA_TYPE_GSO
773 * flags: XEN_NETIF_EXTRA_FLAG_* 773 * flags: XEN_NETIF_EXTRA_FLAG_*
774 * size: Maximum payload size of each segment. 774 * size: Maximum payload size of each segment. For example,
775 * for TCP this is just the path MSS. 775 * for TCP this is just the path MSS.
776 * type: XEN_NETIF_GSO_TYPE_*: This determines 776 * type: XEN_NETIF_GSO_TYPE_*: This determines the protocol of
777 * the packet and any extra features req 777 * the packet and any extra features required to segment the
778 * packet properly. 778 * packet properly.
779 * features: EN_XEN_NETIF_GSO_FEAT_*: This spe 779 * features: EN_XEN_NETIF_GSO_FEAT_*: This specifies any extra GSO
780 * features required to process this 780 * features required to process this packet, such as ECN
781 * support for TCPv4. 781 * support for TCPv4.
782 * 782 *
783 * XEN_NETIF_EXTRA_TYPE_MCAST_{ADD,DEL}: 783 * XEN_NETIF_EXTRA_TYPE_MCAST_{ADD,DEL}:
784 * 784 *
785 * 0 1 2 3 4 5 6 785 * 0 1 2 3 4 5 6 7 octet
786 * +-----+-----+-----+-----+-----+-----+-----+ 786 * +-----+-----+-----+-----+-----+-----+-----+-----+
787 * |type |flags| addr 787 * |type |flags| addr |
788 * +-----+-----+-----+-----+-----+-----+-----+ 788 * +-----+-----+-----+-----+-----+-----+-----+-----+
789 * 789 *
790 * type: Must be XEN_NETIF_EXTRA_TYPE_MCAST_{A 790 * type: Must be XEN_NETIF_EXTRA_TYPE_MCAST_{ADD,DEL}
791 * flags: XEN_NETIF_EXTRA_FLAG_* 791 * flags: XEN_NETIF_EXTRA_FLAG_*
792 * addr: address to add/remove 792 * addr: address to add/remove
793 * 793 *
794 * XEN_NETIF_EXTRA_TYPE_HASH: 794 * XEN_NETIF_EXTRA_TYPE_HASH:
795 * 795 *
796 * A backend that supports teoplitz hashing is 796 * A backend that supports teoplitz hashing is assumed to accept
797 * this type of extra info in transmit packets 797 * this type of extra info in transmit packets.
798 * A frontend that enables hashing is assumed 798 * A frontend that enables hashing is assumed to accept
799 * this type of extra info in receive packets. 799 * this type of extra info in receive packets.
800 * 800 *
801 * 0 1 2 3 4 5 6 801 * 0 1 2 3 4 5 6 7 octet
802 * +-----+-----+-----+-----+-----+-----+-----+ 802 * +-----+-----+-----+-----+-----+-----+-----+-----+
803 * |type |flags|htype| alg |LSB ---- value --- 803 * |type |flags|htype| alg |LSB ---- value ---- MSB|
804 * +-----+-----+-----+-----+-----+-----+-----+ 804 * +-----+-----+-----+-----+-----+-----+-----+-----+
805 * 805 *
806 * type: Must be XEN_NETIF_EXTRA_TYPE_HASH 806 * type: Must be XEN_NETIF_EXTRA_TYPE_HASH
807 * flags: XEN_NETIF_EXTRA_FLAG_* 807 * flags: XEN_NETIF_EXTRA_FLAG_*
808 * htype: Hash type (one of _XEN_NETIF_CTRL_HA 808 * htype: Hash type (one of _XEN_NETIF_CTRL_HASH_TYPE_* - see above)
809 * alg: The algorithm used to calculate the ha 809 * alg: The algorithm used to calculate the hash (one of
810 * XEN_NETIF_CTRL_HASH_TYPE_ALGORITHM_* - 810 * XEN_NETIF_CTRL_HASH_TYPE_ALGORITHM_* - see above)
811 * value: Hash value 811 * value: Hash value
812 */ 812 */
813 813
814 /* Protocol checksum field is blank in the pac 814 /* Protocol checksum field is blank in the packet (hardware offload)? */
815 #define _XEN_NETTXF_csum_blank (0) 815 #define _XEN_NETTXF_csum_blank (0)
816 #define XEN_NETTXF_csum_blank (1U<<_XEN_N 816 #define XEN_NETTXF_csum_blank (1U<<_XEN_NETTXF_csum_blank)
817 817
818 /* Packet data has been validated against prot 818 /* Packet data has been validated against protocol checksum. */
819 #define _XEN_NETTXF_data_validated (1) 819 #define _XEN_NETTXF_data_validated (1)
820 #define XEN_NETTXF_data_validated (1U<<_XEN_N 820 #define XEN_NETTXF_data_validated (1U<<_XEN_NETTXF_data_validated)
821 821
822 /* Packet continues in the next request descri 822 /* Packet continues in the next request descriptor. */
823 #define _XEN_NETTXF_more_data (2) 823 #define _XEN_NETTXF_more_data (2)
824 #define XEN_NETTXF_more_data (1U<<_XEN_N 824 #define XEN_NETTXF_more_data (1U<<_XEN_NETTXF_more_data)
825 825
826 /* Packet to be followed by extra descriptor(s 826 /* Packet to be followed by extra descriptor(s). */
827 #define _XEN_NETTXF_extra_info (3) 827 #define _XEN_NETTXF_extra_info (3)
828 #define XEN_NETTXF_extra_info (1U<<_XEN_N 828 #define XEN_NETTXF_extra_info (1U<<_XEN_NETTXF_extra_info)
829 829
830 #define XEN_NETIF_MAX_TX_SIZE 0xFFFF 830 #define XEN_NETIF_MAX_TX_SIZE 0xFFFF
831 struct xen_netif_tx_request { 831 struct xen_netif_tx_request {
832 grant_ref_t gref; 832 grant_ref_t gref;
833 uint16_t offset; 833 uint16_t offset;
834 uint16_t flags; 834 uint16_t flags;
835 uint16_t id; 835 uint16_t id;
836 uint16_t size; 836 uint16_t size;
837 }; 837 };
838 838
839 /* Types of xen_netif_extra_info descriptors. 839 /* Types of xen_netif_extra_info descriptors. */
840 #define XEN_NETIF_EXTRA_TYPE_NONE (0) 840 #define XEN_NETIF_EXTRA_TYPE_NONE (0) /* Never used - invalid */
841 #define XEN_NETIF_EXTRA_TYPE_GSO (1) 841 #define XEN_NETIF_EXTRA_TYPE_GSO (1) /* u.gso */
842 #define XEN_NETIF_EXTRA_TYPE_MCAST_ADD (2) 842 #define XEN_NETIF_EXTRA_TYPE_MCAST_ADD (2) /* u.mcast */
843 #define XEN_NETIF_EXTRA_TYPE_MCAST_DEL (3) 843 #define XEN_NETIF_EXTRA_TYPE_MCAST_DEL (3) /* u.mcast */
844 #define XEN_NETIF_EXTRA_TYPE_HASH (4) 844 #define XEN_NETIF_EXTRA_TYPE_HASH (4) /* u.hash */
845 #define XEN_NETIF_EXTRA_TYPE_XDP (5) 845 #define XEN_NETIF_EXTRA_TYPE_XDP (5) /* u.xdp */
846 #define XEN_NETIF_EXTRA_TYPE_MAX (6) 846 #define XEN_NETIF_EXTRA_TYPE_MAX (6)
847 847
848 /* xen_netif_extra_info_t flags. */ 848 /* xen_netif_extra_info_t flags. */
849 #define _XEN_NETIF_EXTRA_FLAG_MORE (0) 849 #define _XEN_NETIF_EXTRA_FLAG_MORE (0)
850 #define XEN_NETIF_EXTRA_FLAG_MORE (1U<<_XEN_N 850 #define XEN_NETIF_EXTRA_FLAG_MORE (1U<<_XEN_NETIF_EXTRA_FLAG_MORE)
851 851
852 /* GSO types */ 852 /* GSO types */
853 #define XEN_NETIF_GSO_TYPE_NONE (0) 853 #define XEN_NETIF_GSO_TYPE_NONE (0)
854 #define XEN_NETIF_GSO_TYPE_TCPV4 (1) 854 #define XEN_NETIF_GSO_TYPE_TCPV4 (1)
855 #define XEN_NETIF_GSO_TYPE_TCPV6 (2) 855 #define XEN_NETIF_GSO_TYPE_TCPV6 (2)
856 856
857 /* 857 /*
858 * This structure needs to fit within both xen 858 * This structure needs to fit within both xen_netif_tx_request_t and
859 * xen_netif_rx_response_t for compatibility. 859 * xen_netif_rx_response_t for compatibility.
860 */ 860 */
861 struct xen_netif_extra_info { 861 struct xen_netif_extra_info {
862 uint8_t type; 862 uint8_t type;
863 uint8_t flags; 863 uint8_t flags;
864 union { 864 union {
865 struct { 865 struct {
866 uint16_t size; 866 uint16_t size;
867 uint8_t type; 867 uint8_t type;
868 uint8_t pad; 868 uint8_t pad;
869 uint16_t features; 869 uint16_t features;
870 } gso; 870 } gso;
871 struct { 871 struct {
872 uint8_t addr[6]; 872 uint8_t addr[6];
873 } mcast; 873 } mcast;
874 struct { 874 struct {
875 uint8_t type; 875 uint8_t type;
876 uint8_t algorithm; 876 uint8_t algorithm;
877 uint8_t value[4]; 877 uint8_t value[4];
878 } hash; 878 } hash;
879 struct { 879 struct {
880 uint16_t headroom; 880 uint16_t headroom;
881 uint16_t pad[2]; 881 uint16_t pad[2];
882 } xdp; 882 } xdp;
883 uint16_t pad[3]; 883 uint16_t pad[3];
884 } u; 884 } u;
885 }; 885 };
886 886
887 struct xen_netif_tx_response { 887 struct xen_netif_tx_response {
888 uint16_t id; 888 uint16_t id;
889 int16_t status; 889 int16_t status;
890 }; 890 };
891 891
892 struct xen_netif_rx_request { 892 struct xen_netif_rx_request {
893 uint16_t id; /* Echoed in r 893 uint16_t id; /* Echoed in response message. */
894 uint16_t pad; 894 uint16_t pad;
895 grant_ref_t gref; 895 grant_ref_t gref;
896 }; 896 };
897 897
898 /* Packet data has been validated against prot 898 /* Packet data has been validated against protocol checksum. */
899 #define _XEN_NETRXF_data_validated (0) 899 #define _XEN_NETRXF_data_validated (0)
900 #define XEN_NETRXF_data_validated (1U<<_XEN_N 900 #define XEN_NETRXF_data_validated (1U<<_XEN_NETRXF_data_validated)
901 901
902 /* Protocol checksum field is blank in the pac 902 /* Protocol checksum field is blank in the packet (hardware offload)? */
903 #define _XEN_NETRXF_csum_blank (1) 903 #define _XEN_NETRXF_csum_blank (1)
904 #define XEN_NETRXF_csum_blank (1U<<_XEN_N 904 #define XEN_NETRXF_csum_blank (1U<<_XEN_NETRXF_csum_blank)
905 905
906 /* Packet continues in the next request descri 906 /* Packet continues in the next request descriptor. */
907 #define _XEN_NETRXF_more_data (2) 907 #define _XEN_NETRXF_more_data (2)
908 #define XEN_NETRXF_more_data (1U<<_XEN_N 908 #define XEN_NETRXF_more_data (1U<<_XEN_NETRXF_more_data)
909 909
910 /* Packet to be followed by extra descriptor(s 910 /* Packet to be followed by extra descriptor(s). */
911 #define _XEN_NETRXF_extra_info (3) 911 #define _XEN_NETRXF_extra_info (3)
912 #define XEN_NETRXF_extra_info (1U<<_XEN_N 912 #define XEN_NETRXF_extra_info (1U<<_XEN_NETRXF_extra_info)
913 913
914 /* Packet has GSO prefix. Deprecated but inclu 914 /* Packet has GSO prefix. Deprecated but included for compatibility */
915 #define _XEN_NETRXF_gso_prefix (4) 915 #define _XEN_NETRXF_gso_prefix (4)
916 #define XEN_NETRXF_gso_prefix (1U<<_XEN_N 916 #define XEN_NETRXF_gso_prefix (1U<<_XEN_NETRXF_gso_prefix)
917 917
918 struct xen_netif_rx_response { 918 struct xen_netif_rx_response {
919 uint16_t id; 919 uint16_t id;
920 uint16_t offset; 920 uint16_t offset;
921 uint16_t flags; 921 uint16_t flags;
922 int16_t status; 922 int16_t status;
923 }; 923 };
924 924
925 /* 925 /*
926 * Generate xen_netif ring structures and type 926 * Generate xen_netif ring structures and types.
927 */ 927 */
928 928
929 DEFINE_RING_TYPES(xen_netif_tx, struct xen_net 929 DEFINE_RING_TYPES(xen_netif_tx, struct xen_netif_tx_request,
930 struct xen_netif_tx_response 930 struct xen_netif_tx_response);
931 DEFINE_RING_TYPES(xen_netif_rx, struct xen_net 931 DEFINE_RING_TYPES(xen_netif_rx, struct xen_netif_rx_request,
932 struct xen_netif_rx_response 932 struct xen_netif_rx_response);
933 933
934 #define XEN_NETIF_RSP_DROPPED -2 934 #define XEN_NETIF_RSP_DROPPED -2
935 #define XEN_NETIF_RSP_ERROR -1 935 #define XEN_NETIF_RSP_ERROR -1
936 #define XEN_NETIF_RSP_OKAY 0 936 #define XEN_NETIF_RSP_OKAY 0
937 /* No response: used for auxiliary requests (e 937 /* No response: used for auxiliary requests (e.g., xen_netif_extra_info_t). */
938 #define XEN_NETIF_RSP_NULL 1 938 #define XEN_NETIF_RSP_NULL 1
939 939
940 #endif 940 #endif
941 941
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.