1 /******************************************************************************
2 * netif.h
3 *
4 * Unified network-device I/O interface for Xen guest OSes.
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining a copy
7 * of this software and associated documentation files (the "Software"), to
8 * deal in the Software without restriction, including without limitation the
9 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10 * sell copies of the Software, and to permit persons to whom the Software is
11 * furnished to do so, subject to the following conditions:
12 *
13 * The above copyright notice and this permission notice shall be included in
14 * all copies or substantial portions of the Software.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
22 * DEALINGS IN THE SOFTWARE.
23 *
24 * Copyright (c) 2003-2004, Keir Fraser
25 */
26
27 #ifndef __XEN_PUBLIC_IO_NETIF_H__
28 #define __XEN_PUBLIC_IO_NETIF_H__
29
30 #include "ring.h"
31 #include "../grant_table.h"
32
33 /*
34 * Older implementation of Xen network frontend / backend has an
35 * implicit dependency on the MAX_SKB_FRAGS as the maximum number of
36 * ring slots a skb can use. Netfront / netback may not work as
37 * expected when frontend and backend have different MAX_SKB_FRAGS.
38 *
39 * A better approach is to add mechanism for netfront / netback to
40 * negotiate this value. However we cannot fix all possible
41 * frontends, so we need to define a value which states the minimum
42 * slots backend must support.
43 *
44 * The minimum value derives from older Linux kernel's MAX_SKB_FRAGS
45 * (18), which is proved to work with most frontends. Any new backend
46 * which doesn't negotiate with frontend should expect frontend to
47 * send a valid packet using slots up to this value.
48 */
49 #define XEN_NETIF_NR_SLOTS_MIN 18
50
51 /*
52 * Notifications after enqueuing any type of message should be conditional on
53 * the appropriate req_event or rsp_event field in the shared ring.
54 * If the client sends notification for rx requests then it should specify
55 * feature 'feature-rx-notify' via xenbus. Otherwise the backend will assume
56 * that it cannot safely queue packets (as it may not be kicked to send them).
57 */
58
59 /*
60 * "feature-split-event-channels" is introduced to separate guest TX
61 * and RX notification. Backend either doesn't support this feature or
62 * advertises it via xenstore as 0 (disabled) or 1 (enabled).
63 *
64 * To make use of this feature, frontend should allocate two event
65 * channels for TX and RX, advertise them to backend as
66 * "event-channel-tx" and "event-channel-rx" respectively. If frontend
67 * doesn't want to use this feature, it just writes "event-channel"
68 * node as before.
69 */
70
71 /*
72 * Multiple transmit and receive queues:
73 * If supported, the backend will write the key "multi-queue-max-queues" to
74 * the directory for that vif, and set its value to the maximum supported
75 * number of queues.
76 * Frontends that are aware of this feature and wish to use it can write the
77 * key "multi-queue-num-queues", set to the number they wish to use, which
78 * must be greater than zero, and no more than the value reported by the backend
79 * in "multi-queue-max-queues".
80 *
81 * Queues replicate the shared rings and event channels.
82 * "feature-split-event-channels" may optionally be used when using
83 * multiple queues, but is not mandatory.
84 *
85 * Each queue consists of one shared ring pair, i.e. there must be the same
86 * number of tx and rx rings.
87 *
88 * For frontends requesting just one queue, the usual event-channel and
89 * ring-ref keys are written as before, simplifying the backend processing
90 * to avoid distinguishing between a frontend that doesn't understand the
91 * multi-queue feature, and one that does, but requested only one queue.
92 *
93 * Frontends requesting two or more queues must not write the toplevel
94 * event-channel (or event-channel-{tx,rx}) and {tx,rx}-ring-ref keys,
95 * instead writing those keys under sub-keys having the name "queue-N" where
96 * N is the integer ID of the queue for which those keys belong. Queues
97 * are indexed from zero. For example, a frontend with two queues and split
98 * event channels must write the following set of queue-related keys:
99 *
100 * /local/domain/1/device/vif/0/multi-queue-num-queues = "2"
101 * /local/domain/1/device/vif/0/queue-0 = ""
102 * /local/domain/1/device/vif/0/queue-0/tx-ring-ref = "<ring-ref-tx0>"
103 * /local/domain/1/device/vif/0/queue-0/rx-ring-ref = "<ring-ref-rx0>"
104 * /local/domain/1/device/vif/0/queue-0/event-channel-tx = "<evtchn-tx0>"
105 * /local/domain/1/device/vif/0/queue-0/event-channel-rx = "<evtchn-rx0>"
106 * /local/domain/1/device/vif/0/queue-1 = ""
107 * /local/domain/1/device/vif/0/queue-1/tx-ring-ref = "<ring-ref-tx1>"
108 * /local/domain/1/device/vif/0/queue-1/rx-ring-ref = "<ring-ref-rx1"
109 * /local/domain/1/device/vif/0/queue-1/event-channel-tx = "<evtchn-tx1>"
110 * /local/domain/1/device/vif/0/queue-1/event-channel-rx = "<evtchn-rx1>"
111 *
112 * If there is any inconsistency in the XenStore data, the backend may
113 * choose not to connect any queues, instead treating the request as an
114 * error. This includes scenarios where more (or fewer) queues were
115 * requested than the frontend provided details for.
116 *
117 * Mapping of packets to queues is considered to be a function of the
118 * transmitting system (backend or frontend) and is not negotiated
119 * between the two. Guests are free to transmit packets on any queue
120 * they choose, provided it has been set up correctly. Guests must be
121 * prepared to receive packets on any queue they have requested be set up.
122 */
123
124 /*
125 * "feature-no-csum-offload" should be used to turn IPv4 TCP/UDP checksum
126 * offload off or on. If it is missing then the feature is assumed to be on.
127 * "feature-ipv6-csum-offload" should be used to turn IPv6 TCP/UDP checksum
128 * offload on or off. If it is missing then the feature is assumed to be off.
129 */
130
131 /*
132 * "feature-gso-tcpv4" and "feature-gso-tcpv6" advertise the capability to
133 * handle large TCP packets (in IPv4 or IPv6 form respectively). Neither
134 * frontends nor backends are assumed to be capable unless the flags are
135 * present.
136 */
137
138 /*
139 * "feature-multicast-control" and "feature-dynamic-multicast-control"
140 * advertise the capability to filter ethernet multicast packets in the
141 * backend. If the frontend wishes to take advantage of this feature then
142 * it may set "request-multicast-control". If the backend only advertises
143 * "feature-multicast-control" then "request-multicast-control" must be set
144 * before the frontend moves into the connected state. The backend will
145 * sample the value on this state transition and any subsequent change in
146 * value will have no effect. However, if the backend also advertises
147 * "feature-dynamic-multicast-control" then "request-multicast-control"
148 * may be set by the frontend at any time. In this case, the backend will
149 * watch the value and re-sample on watch events.
150 *
151 * If the sampled value of "request-multicast-control" is set then the
152 * backend transmit side should no longer flood multicast packets to the
153 * frontend, it should instead drop any multicast packet that does not
154 * match in a filter list.
155 * The list is amended by the frontend by sending dummy transmit requests
156 * containing XEN_NETIF_EXTRA_TYPE_MCAST_{ADD,DEL} extra-info fragments as
157 * specified below.
158 * Note that the filter list may be amended even if the sampled value of
159 * "request-multicast-control" is not set, however the filter should only
160 * be applied if it is set.
161 */
162
163 /*
164 * Control ring
165 * ============
166 *
167 * Some features, such as hashing (detailed below), require a
168 * significant amount of out-of-band data to be passed from frontend to
169 * backend. Use of xenstore is not suitable for large quantities of data
170 * because of quota limitations and so a dedicated 'control ring' is used.
171 * The ability of the backend to use a control ring is advertised by
172 * setting:
173 *
174 * /local/domain/X/backend/vif/<domid>/<vif>/feature-ctrl-ring = "1"
175 *
176 * The frontend provides a control ring to the backend by setting:
177 *
178 * /local/domain/<domid>/device/vif/<vif>/ctrl-ring-ref = <gref>
179 * /local/domain/<domid>/device/vif/<vif>/event-channel-ctrl = <port>
180 *
181 * where <gref> is the grant reference of the shared page used to
182 * implement the control ring and <port> is an event channel to be used
183 * as a mailbox interrupt. These keys must be set before the frontend
184 * moves into the connected state.
185 *
186 * The control ring uses a fixed request/response message size and is
187 * balanced (i.e. one request to one response), so operationally it is much
188 * the same as a transmit or receive ring.
189 * Note that there is no requirement that responses are issued in the same
190 * order as requests.
191 */
192
193 /*
194 * Link state
195 * ==========
196 *
197 * The backend can advertise its current link (carrier) state to the
198 * frontend using the /local/domain/X/backend/vif/<domid>/<vif>/carrier
199 * node. If this node is not present, then the frontend should assume that
200 * the link is up (for compatibility with backends that do not implement
201 * this feature). If this node is present, then a value of "0" should be
202 * interpreted by the frontend as the link being down (no carrier) and a
203 * value of "1" should be interpreted as the link being up (carrier
204 * present).
205 */
206
207 /*
208 * MTU
209 * ===
210 *
211 * The toolstack may set a value of MTU for the frontend by setting the
212 * /local/domain/<domid>/device/vif/<vif>/mtu node with the MTU value in
213 * octets. If this node is absent the frontend should assume an MTU value
214 * of 1500 octets. A frontend is also at liberty to ignore this value so
215 * it is only suitable for informing the frontend that a packet payload
216 * >1500 octets is permitted.
217 */
218
219 /*
220 * Hash types
221 * ==========
222 *
223 * For the purposes of the definitions below, 'Packet[]' is an array of
224 * octets containing an IP packet without options, 'Array[X..Y]' means a
225 * sub-array of 'Array' containing bytes X thru Y inclusive, and '+' is
226 * used to indicate concatenation of arrays.
227 */
228
229 /*
230 * A hash calculated over an IP version 4 header as follows:
231 *
232 * Buffer[0..8] = Packet[12..15] (source address) +
233 * Packet[16..19] (destination address)
234 *
235 * Result = Hash(Buffer, 8)
236 */
237 #define _XEN_NETIF_CTRL_HASH_TYPE_IPV4 0
238 #define XEN_NETIF_CTRL_HASH_TYPE_IPV4 \
239 (1 << _XEN_NETIF_CTRL_HASH_TYPE_IPV4)
240
241 /*
242 * A hash calculated over an IP version 4 header and TCP header as
243 * follows:
244 *
245 * Buffer[0..12] = Packet[12..15] (source address) +
246 * Packet[16..19] (destination address) +
247 * Packet[20..21] (source port) +
248 * Packet[22..23] (destination port)
249 *
250 * Result = Hash(Buffer, 12)
251 */
252 #define _XEN_NETIF_CTRL_HASH_TYPE_IPV4_TCP 1
253 #define XEN_NETIF_CTRL_HASH_TYPE_IPV4_TCP \
254 (1 << _XEN_NETIF_CTRL_HASH_TYPE_IPV4_TCP)
255
256 /*
257 * A hash calculated over an IP version 6 header as follows:
258 *
259 * Buffer[0..32] = Packet[8..23] (source address ) +
260 * Packet[24..39] (destination address)
261 *
262 * Result = Hash(Buffer, 32)
263 */
264 #define _XEN_NETIF_CTRL_HASH_TYPE_IPV6 2
265 #define XEN_NETIF_CTRL_HASH_TYPE_IPV6 \
266 (1 << _XEN_NETIF_CTRL_HASH_TYPE_IPV6)
267
268 /*
269 * A hash calculated over an IP version 6 header and TCP header as
270 * follows:
271 *
272 * Buffer[0..36] = Packet[8..23] (source address) +
273 * Packet[24..39] (destination address) +
274 * Packet[40..41] (source port) +
275 * Packet[42..43] (destination port)
276 *
277 * Result = Hash(Buffer, 36)
278 */
279 #define _XEN_NETIF_CTRL_HASH_TYPE_IPV6_TCP 3
280 #define XEN_NETIF_CTRL_HASH_TYPE_IPV6_TCP \
281 (1 << _XEN_NETIF_CTRL_HASH_TYPE_IPV6_TCP)
282
283 /*
284 * Hash algorithms
285 * ===============
286 */
287
288 #define XEN_NETIF_CTRL_HASH_ALGORITHM_NONE 0
289
290 /*
291 * Toeplitz hash:
292 */
293
294 #define XEN_NETIF_CTRL_HASH_ALGORITHM_TOEPLITZ 1
295
296 /*
297 * This algorithm uses a 'key' as well as the data buffer itself.
298 * (Buffer[] and Key[] are treated as shift-registers where the MSB of
299 * Buffer/Key[0] is considered 'left-most' and the LSB of Buffer/Key[N-1]
300 * is the 'right-most').
301 *
302 * Value = 0
303 * For number of bits in Buffer[]
304 * If (left-most bit of Buffer[] is 1)
305 * Value ^= left-most 32 bits of Key[]
306 * Key[] << 1
307 * Buffer[] << 1
308 *
309 * The code below is provided for convenience where an operating system
310 * does not already provide an implementation.
311 */
312 #ifdef XEN_NETIF_DEFINE_TOEPLITZ
xen_netif_toeplitz_hash(const uint8_t * key,unsigned int keylen,const uint8_t * buf,unsigned int buflen)313 static uint32_t xen_netif_toeplitz_hash(const uint8_t *key,
314 unsigned int keylen,
315 const uint8_t *buf,
316 unsigned int buflen)
317 {
318 unsigned int keyi, bufi;
319 uint64_t prefix = 0;
320 uint64_t hash = 0;
321
322 /* Pre-load prefix with the first 8 bytes of the key */
323 for (keyi = 0; keyi < 8; keyi++) {
324 prefix <<= 8;
325 prefix |= (keyi < keylen) ? key[keyi] : 0;
326 }
327
328 for (bufi = 0; bufi < buflen; bufi++) {
329 uint8_t byte = buf[bufi];
330 unsigned int bit;
331
332 for (bit = 0; bit < 8; bit++) {
333 if (byte & 0x80)
334 hash ^= prefix;
335 prefix <<= 1;
336 byte <<=1;
337 }
338
339 /*
340 * 'prefix' has now been left-shifted by 8, so
341 * OR in the next byte.
342 */
343 prefix |= (keyi < keylen) ? key[keyi] : 0;
344 keyi++;
345 }
346
347 /* The valid part of the hash is in the upper 32 bits. */
348 return hash >> 32;
349 }
350 #endif /* XEN_NETIF_DEFINE_TOEPLITZ */
351
352 /*
353 * Control requests (struct xen_netif_ctrl_request)
354 * ================================================
355 *
356 * All requests have the following format:
357 *
358 * 0 1 2 3 4 5 6 7 octet
359 * +-----+-----+-----+-----+-----+-----+-----+-----+
360 * | id | type | data[0] |
361 * +-----+-----+-----+-----+-----+-----+-----+-----+
362 * | data[1] | data[2] |
363 * +-----+-----+-----+-----+-----------------------+
364 *
365 * id: the request identifier, echoed in response.
366 * type: the type of request (see below)
367 * data[]: any data associated with the request (determined by type)
368 */
369
370 struct xen_netif_ctrl_request {
371 uint16_t id;
372 uint16_t type;
373
374 #define XEN_NETIF_CTRL_TYPE_INVALID 0
375 #define XEN_NETIF_CTRL_TYPE_GET_HASH_FLAGS 1
376 #define XEN_NETIF_CTRL_TYPE_SET_HASH_FLAGS 2
377 #define XEN_NETIF_CTRL_TYPE_SET_HASH_KEY 3
378 #define XEN_NETIF_CTRL_TYPE_GET_HASH_MAPPING_SIZE 4
379 #define XEN_NETIF_CTRL_TYPE_SET_HASH_MAPPING_SIZE 5
380 #define XEN_NETIF_CTRL_TYPE_SET_HASH_MAPPING 6
381 #define XEN_NETIF_CTRL_TYPE_SET_HASH_ALGORITHM 7
382 #define XEN_NETIF_CTRL_TYPE_GET_GREF_MAPPING_SIZE 8
383 #define XEN_NETIF_CTRL_TYPE_ADD_GREF_MAPPING 9
384 #define XEN_NETIF_CTRL_TYPE_DEL_GREF_MAPPING 10
385
386 uint32_t data[3];
387 };
388
389 /*
390 * Control responses (struct xen_netif_ctrl_response)
391 * ==================================================
392 *
393 * All responses have the following format:
394 *
395 * 0 1 2 3 4 5 6 7 octet
396 * +-----+-----+-----+-----+-----+-----+-----+-----+
397 * | id | type | status |
398 * +-----+-----+-----+-----+-----+-----+-----+-----+
399 * | data |
400 * +-----+-----+-----+-----+
401 *
402 * id: the corresponding request identifier
403 * type: the type of the corresponding request
404 * status: the status of request processing
405 * data: any data associated with the response (determined by type and
406 * status)
407 */
408
409 struct xen_netif_ctrl_response {
410 uint16_t id;
411 uint16_t type;
412 uint32_t status;
413
414 #define XEN_NETIF_CTRL_STATUS_SUCCESS 0
415 #define XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED 1
416 #define XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER 2
417 #define XEN_NETIF_CTRL_STATUS_BUFFER_OVERFLOW 3
418
419 uint32_t data;
420 };
421
422 /*
423 * Static Grants (struct xen_netif_gref)
424 * =====================================
425 *
426 * A frontend may provide a fixed set of grant references to be mapped on
427 * the backend. The message of type XEN_NETIF_CTRL_TYPE_ADD_GREF_MAPPING
428 * prior its usage in the command ring allows for creation of these mappings.
429 * The backend will maintain a fixed amount of these mappings.
430 *
431 * XEN_NETIF_CTRL_TYPE_GET_GREF_MAPPING_SIZE lets a frontend query how many
432 * of these mappings can be kept.
433 *
434 * Each entry in the XEN_NETIF_CTRL_TYPE_{ADD,DEL}_GREF_MAPPING input table has
435 * the following format:
436 *
437 * 0 1 2 3 4 5 6 7 octet
438 * +-----+-----+-----+-----+-----+-----+-----+-----+
439 * | grant ref | flags | status |
440 * +-----+-----+-----+-----+-----+-----+-----+-----+
441 *
442 * grant ref: grant reference (IN)
443 * flags: flags describing the control operation (IN)
444 * status: XEN_NETIF_CTRL_STATUS_* (OUT)
445 *
446 * 'status' is an output parameter which does not require to be set to zero
447 * prior to its usage in the corresponding control messages.
448 */
449
450 struct xen_netif_gref {
451 grant_ref_t ref;
452 uint16_t flags;
453
454 #define _XEN_NETIF_CTRLF_GREF_readonly 0
455 #define XEN_NETIF_CTRLF_GREF_readonly (1U<<_XEN_NETIF_CTRLF_GREF_readonly)
456
457 uint16_t status;
458 };
459
460 /*
461 * Control messages
462 * ================
463 *
464 * XEN_NETIF_CTRL_TYPE_SET_HASH_ALGORITHM
465 * --------------------------------------
466 *
467 * This is sent by the frontend to set the desired hash algorithm.
468 *
469 * Request:
470 *
471 * type = XEN_NETIF_CTRL_TYPE_SET_HASH_ALGORITHM
472 * data[0] = a XEN_NETIF_CTRL_HASH_ALGORITHM_* value
473 * data[1] = 0
474 * data[2] = 0
475 *
476 * Response:
477 *
478 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not
479 * supported
480 * XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER - The algorithm is not
481 * supported
482 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful
483 *
484 * NOTE: Setting data[0] to XEN_NETIF_CTRL_HASH_ALGORITHM_NONE disables
485 * hashing and the backend is free to choose how it steers packets
486 * to queues (which is the default behaviour).
487 *
488 * XEN_NETIF_CTRL_TYPE_GET_HASH_FLAGS
489 * ----------------------------------
490 *
491 * This is sent by the frontend to query the types of hash supported by
492 * the backend.
493 *
494 * Request:
495 *
496 * type = XEN_NETIF_CTRL_TYPE_GET_HASH_FLAGS
497 * data[0] = 0
498 * data[1] = 0
499 * data[2] = 0
500 *
501 * Response:
502 *
503 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not supported
504 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful
505 * data = supported hash types (if operation was successful)
506 *
507 * NOTE: A valid hash algorithm must be selected before this operation can
508 * succeed.
509 *
510 * XEN_NETIF_CTRL_TYPE_SET_HASH_FLAGS
511 * ----------------------------------
512 *
513 * This is sent by the frontend to set the types of hash that the backend
514 * should calculate. (See above for hash type definitions).
515 * Note that the 'maximal' type of hash should always be chosen. For
516 * example, if the frontend sets both IPV4 and IPV4_TCP hash types then
517 * the latter hash type should be calculated for any TCP packet and the
518 * former only calculated for non-TCP packets.
519 *
520 * Request:
521 *
522 * type = XEN_NETIF_CTRL_TYPE_SET_HASH_FLAGS
523 * data[0] = bitwise OR of XEN_NETIF_CTRL_HASH_TYPE_* values
524 * data[1] = 0
525 * data[2] = 0
526 *
527 * Response:
528 *
529 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not
530 * supported
531 * XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER - One or more flag
532 * value is invalid or
533 * unsupported
534 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful
535 * data = 0
536 *
537 * NOTE: A valid hash algorithm must be selected before this operation can
538 * succeed.
539 * Also, setting data[0] to zero disables hashing and the backend
540 * is free to choose how it steers packets to queues.
541 *
542 * XEN_NETIF_CTRL_TYPE_SET_HASH_KEY
543 * --------------------------------
544 *
545 * This is sent by the frontend to set the key of the hash if the algorithm
546 * requires it. (See hash algorithms above).
547 *
548 * Request:
549 *
550 * type = XEN_NETIF_CTRL_TYPE_SET_HASH_KEY
551 * data[0] = grant reference of page containing the key (assumed to
552 * start at beginning of grant)
553 * data[1] = size of key in octets
554 * data[2] = 0
555 *
556 * Response:
557 *
558 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not
559 * supported
560 * XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER - Key size is invalid
561 * XEN_NETIF_CTRL_STATUS_BUFFER_OVERFLOW - Key size is larger
562 * than the backend
563 * supports
564 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful
565 * data = 0
566 *
567 * NOTE: Any key octets not specified are assumed to be zero (the key
568 * is assumed to be empty by default) and specifying a new key
569 * invalidates any previous key, hence specifying a key size of
570 * zero will clear the key (which ensures that the calculated hash
571 * will always be zero).
572 * The maximum size of key is algorithm and backend specific, but
573 * is also limited by the single grant reference.
574 * The grant reference may be read-only and must remain valid until
575 * the response has been processed.
576 *
577 * XEN_NETIF_CTRL_TYPE_GET_HASH_MAPPING_SIZE
578 * -----------------------------------------
579 *
580 * This is sent by the frontend to query the maximum size of mapping
581 * table supported by the backend. The size is specified in terms of
582 * table entries.
583 *
584 * Request:
585 *
586 * type = XEN_NETIF_CTRL_TYPE_GET_HASH_MAPPING_SIZE
587 * data[0] = 0
588 * data[1] = 0
589 * data[2] = 0
590 *
591 * Response:
592 *
593 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not supported
594 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful
595 * data = maximum number of entries allowed in the mapping table
596 * (if operation was successful) or zero if a mapping table is
597 * not supported (i.e. hash mapping is done only by modular
598 * arithmetic).
599 *
600 * XEN_NETIF_CTRL_TYPE_SET_HASH_MAPPING_SIZE
601 * -------------------------------------
602 *
603 * This is sent by the frontend to set the actual size of the mapping
604 * table to be used by the backend. The size is specified in terms of
605 * table entries.
606 * Any previous table is invalidated by this message and any new table
607 * is assumed to be zero filled.
608 *
609 * Request:
610 *
611 * type = XEN_NETIF_CTRL_TYPE_SET_HASH_MAPPING_SIZE
612 * data[0] = number of entries in mapping table
613 * data[1] = 0
614 * data[2] = 0
615 *
616 * Response:
617 *
618 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not
619 * supported
620 * XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER - Table size is invalid
621 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful
622 * data = 0
623 *
624 * NOTE: Setting data[0] to 0 means that hash mapping should be done
625 * using modular arithmetic.
626 *
627 * XEN_NETIF_CTRL_TYPE_SET_HASH_MAPPING
628 * ------------------------------------
629 *
630 * This is sent by the frontend to set the content of the table mapping
631 * hash value to queue number. The backend should calculate the hash from
632 * the packet header, use it as an index into the table (modulo the size
633 * of the table) and then steer the packet to the queue number found at
634 * that index.
635 *
636 * Request:
637 *
638 * type = XEN_NETIF_CTRL_TYPE_SET_HASH_MAPPING
639 * data[0] = grant reference of page containing the mapping (sub-)table
640 * (assumed to start at beginning of grant)
641 * data[1] = size of (sub-)table in entries
642 * data[2] = offset, in entries, of sub-table within overall table
643 *
644 * Response:
645 *
646 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not
647 * supported
648 * XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER - Table size or content
649 * is invalid
650 * XEN_NETIF_CTRL_STATUS_BUFFER_OVERFLOW - Table size is larger
651 * than the backend
652 * supports
653 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful
654 * data = 0
655 *
656 * NOTE: The overall table has the following format:
657 *
658 * 0 1 2 3 4 5 6 7 octet
659 * +-----+-----+-----+-----+-----+-----+-----+-----+
660 * | mapping[0] | mapping[1] |
661 * +-----+-----+-----+-----+-----+-----+-----+-----+
662 * | . |
663 * | . |
664 * | . |
665 * +-----+-----+-----+-----+-----+-----+-----+-----+
666 * | mapping[N-2] | mapping[N-1] |
667 * +-----+-----+-----+-----+-----+-----+-----+-----+
668 *
669 * where N is specified by a XEN_NETIF_CTRL_TYPE_SET_HASH_MAPPING_SIZE
670 * message and each mapping must specifies a queue between 0 and
671 * "multi-queue-num-queues" (see above).
672 * The backend may support a mapping table larger than can be
673 * mapped by a single grant reference. Thus sub-tables within a
674 * larger table can be individually set by sending multiple messages
675 * with differing offset values. Specifying a new sub-table does not
676 * invalidate any table data outside that range.
677 * The grant reference may be read-only and must remain valid until
678 * the response has been processed.
679 *
680 * XEN_NETIF_CTRL_TYPE_GET_GREF_MAPPING_SIZE
681 * -----------------------------------------
682 *
683 * This is sent by the frontend to fetch the number of grefs that can be kept
684 * mapped in the backend.
685 *
686 * Request:
687 *
688 * type = XEN_NETIF_CTRL_TYPE_GET_GREF_MAPPING_SIZE
689 * data[0] = queue index (assumed 0 for single queue)
690 * data[1] = 0
691 * data[2] = 0
692 *
693 * Response:
694 *
695 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not
696 * supported
697 * XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER - The queue index is
698 * out of range
699 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful
700 * data = maximum number of entries allowed in the gref mapping table
701 * (if operation was successful) or zero if it is not supported.
702 *
703 * XEN_NETIF_CTRL_TYPE_ADD_GREF_MAPPING
704 * ------------------------------------
705 *
706 * This is sent by the frontend for backend to map a list of grant
707 * references.
708 *
709 * Request:
710 *
711 * type = XEN_NETIF_CTRL_TYPE_ADD_GREF_MAPPING
712 * data[0] = queue index
713 * data[1] = grant reference of page containing the mapping list
714 * (r/w and assumed to start at beginning of page)
715 * data[2] = size of list in entries
716 *
717 * Response:
718 *
719 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not
720 * supported
721 * XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER - Operation failed
722 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful
723 *
724 * NOTE: Each entry in the input table has the format outlined
725 * in struct xen_netif_gref.
726 * Contrary to XEN_NETIF_CTRL_TYPE_DEL_GREF_MAPPING, the struct
727 * xen_netif_gref 'status' field is not used and therefore the response
728 * 'status' determines the success of this operation. In case of
729 * failure none of grants mappings get added in the backend.
730 *
731 * XEN_NETIF_CTRL_TYPE_DEL_GREF_MAPPING
732 * ------------------------------------
733 *
734 * This is sent by the frontend for backend to unmap a list of grant
735 * references.
736 *
737 * Request:
738 *
739 * type = XEN_NETIF_CTRL_TYPE_DEL_GREF_MAPPING
740 * data[0] = queue index
741 * data[1] = grant reference of page containing the mapping list
742 * (r/w and assumed to start at beginning of page)
743 * data[2] = size of list in entries
744 *
745 * Response:
746 *
747 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not
748 * supported
749 * XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER - Operation failed
750 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful
751 * data = number of entries that were unmapped
752 *
753 * NOTE: Each entry in the input table has the format outlined in struct
754 * xen_netif_gref.
755 * The struct xen_netif_gref 'status' field determines if the entry
756 * was successfully removed.
757 * The entries used are only the ones representing grant references that
758 * were previously the subject of a XEN_NETIF_CTRL_TYPE_ADD_GREF_MAPPING
759 * operation. Any other entries will have their status set to
760 * XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER upon completion.
761 */
762
763 DEFINE_RING_TYPES(xen_netif_ctrl,
764 struct xen_netif_ctrl_request,
765 struct xen_netif_ctrl_response);
766
767 /*
768 * Guest transmit
769 * ==============
770 *
771 * This is the 'wire' format for transmit (frontend -> backend) packets:
772 *
773 * Fragment 1: netif_tx_request_t - flags = NETTXF_*
774 * size = total packet size
775 * [Extra 1: netif_extra_info_t] - (only if fragment 1 flags include
776 * NETTXF_extra_info)
777 * ...
778 * [Extra N: netif_extra_info_t] - (only if extra N-1 flags include
779 * XEN_NETIF_EXTRA_MORE)
780 * ...
781 * Fragment N: netif_tx_request_t - (only if fragment N-1 flags include
782 * NETTXF_more_data - flags on preceding
783 * extras are not relevant here)
784 * flags = 0
785 * size = fragment size
786 *
787 * NOTE:
788 *
789 * This format slightly is different from that used for receive
790 * (backend -> frontend) packets. Specifically, in a multi-fragment
791 * packet the actual size of fragment 1 can only be determined by
792 * subtracting the sizes of fragments 2..N from the total packet size.
793 *
794 * Ring slot size is 12 octets, however not all request/response
795 * structs use the full size.
796 *
797 * tx request data (netif_tx_request_t)
798 * ------------------------------------
799 *
800 * 0 1 2 3 4 5 6 7 octet
801 * +-----+-----+-----+-----+-----+-----+-----+-----+
802 * | grant ref | offset | flags |
803 * +-----+-----+-----+-----+-----+-----+-----+-----+
804 * | id | size |
805 * +-----+-----+-----+-----+
806 *
807 * grant ref: Reference to buffer page.
808 * offset: Offset within buffer page.
809 * flags: NETTXF_*.
810 * id: request identifier, echoed in response.
811 * size: packet size in bytes.
812 *
813 * tx response (netif_tx_response_t)
814 * ---------------------------------
815 *
816 * 0 1 2 3 4 5 6 7 octet
817 * +-----+-----+-----+-----+-----+-----+-----+-----+
818 * | id | status | unused |
819 * +-----+-----+-----+-----+-----+-----+-----+-----+
820 * | unused |
821 * +-----+-----+-----+-----+
822 *
823 * id: reflects id in transmit request
824 * status: NETIF_RSP_*
825 *
826 * Guest receive
827 * =============
828 *
829 * This is the 'wire' format for receive (backend -> frontend) packets:
830 *
831 * Fragment 1: netif_rx_request_t - flags = NETRXF_*
832 * size = fragment size
833 * [Extra 1: netif_extra_info_t] - (only if fragment 1 flags include
834 * NETRXF_extra_info)
835 * ...
836 * [Extra N: netif_extra_info_t] - (only if extra N-1 flags include
837 * XEN_NETIF_EXTRA_MORE)
838 * ...
839 * Fragment N: netif_rx_request_t - (only if fragment N-1 flags include
840 * NETRXF_more_data - flags on preceding
841 * extras are not relevant here)
842 * flags = 0
843 * size = fragment size
844 *
845 * NOTE:
846 *
847 * This format slightly is different from that used for transmit
848 * (frontend -> backend) packets. Specifically, in a multi-fragment
849 * packet the size of the packet can only be determined by summing the
850 * sizes of fragments 1..N.
851 *
852 * Ring slot size is 8 octets.
853 *
854 * rx request (netif_rx_request_t)
855 * -------------------------------
856 *
857 * 0 1 2 3 4 5 6 7 octet
858 * +-----+-----+-----+-----+-----+-----+-----+-----+
859 * | id | pad | gref |
860 * +-----+-----+-----+-----+-----+-----+-----+-----+
861 *
862 * id: request identifier, echoed in response.
863 * gref: reference to incoming granted frame.
864 *
865 * rx response (netif_rx_response_t)
866 * ---------------------------------
867 *
868 * 0 1 2 3 4 5 6 7 octet
869 * +-----+-----+-----+-----+-----+-----+-----+-----+
870 * | id | offset | flags | status |
871 * +-----+-----+-----+-----+-----+-----+-----+-----+
872 *
873 * id: reflects id in receive request
874 * offset: offset in page of start of received packet
875 * flags: NETRXF_*
876 * status: -ve: NETIF_RSP_*; +ve: Rx'ed pkt size.
877 *
878 * NOTE: Historically, to support GSO on the frontend receive side, Linux
879 * netfront does not make use of the rx response id (because, as
880 * described below, extra info structures overlay the id field).
881 * Instead it assumes that responses always appear in the same ring
882 * slot as their corresponding request. Thus, to maintain
883 * compatibility, backends must make sure this is the case.
884 *
885 * Extra Info
886 * ==========
887 *
888 * Can be present if initial request or response has NET{T,R}XF_extra_info,
889 * or previous extra request has XEN_NETIF_EXTRA_MORE.
890 *
891 * The struct therefore needs to fit into either a tx or rx slot and
892 * is therefore limited to 8 octets.
893 *
894 * NOTE: Because extra info data overlays the usual request/response
895 * structures, there is no id information in the opposite direction.
896 * So, if an extra info overlays an rx response the frontend can
897 * assume that it is in the same ring slot as the request that was
898 * consumed to make the slot available, and the backend must ensure
899 * this assumption is true.
900 *
901 * extra info (netif_extra_info_t)
902 * -------------------------------
903 *
904 * General format:
905 *
906 * 0 1 2 3 4 5 6 7 octet
907 * +-----+-----+-----+-----+-----+-----+-----+-----+
908 * |type |flags| type specific data |
909 * +-----+-----+-----+-----+-----+-----+-----+-----+
910 * | padding for tx |
911 * +-----+-----+-----+-----+
912 *
913 * type: XEN_NETIF_EXTRA_TYPE_*
914 * flags: XEN_NETIF_EXTRA_FLAG_*
915 * padding for tx: present only in the tx case due to 8 octet limit
916 * from rx case. Not shown in type specific entries
917 * below.
918 *
919 * XEN_NETIF_EXTRA_TYPE_GSO:
920 *
921 * 0 1 2 3 4 5 6 7 octet
922 * +-----+-----+-----+-----+-----+-----+-----+-----+
923 * |type |flags| size |type | pad | features |
924 * +-----+-----+-----+-----+-----+-----+-----+-----+
925 *
926 * type: Must be XEN_NETIF_EXTRA_TYPE_GSO
927 * flags: XEN_NETIF_EXTRA_FLAG_*
928 * size: Maximum payload size of each segment. For example,
929 * for TCP this is just the path MSS.
930 * type: XEN_NETIF_GSO_TYPE_*: This determines the protocol of
931 * the packet and any extra features required to segment the
932 * packet properly.
933 * features: EN_NETIF_GSO_FEAT_*: This specifies any extra GSO
934 * features required to process this packet, such as ECN
935 * support for TCPv4.
936 *
937 * XEN_NETIF_EXTRA_TYPE_MCAST_{ADD,DEL}:
938 *
939 * 0 1 2 3 4 5 6 7 octet
940 * +-----+-----+-----+-----+-----+-----+-----+-----+
941 * |type |flags| addr |
942 * +-----+-----+-----+-----+-----+-----+-----+-----+
943 *
944 * type: Must be XEN_NETIF_EXTRA_TYPE_MCAST_{ADD,DEL}
945 * flags: XEN_NETIF_EXTRA_FLAG_*
946 * addr: address to add/remove
947 *
948 * XEN_NETIF_EXTRA_TYPE_HASH:
949 *
950 * A backend that supports teoplitz hashing is assumed to accept
951 * this type of extra info in transmit packets.
952 * A frontend that enables hashing is assumed to accept
953 * this type of extra info in receive packets.
954 *
955 * 0 1 2 3 4 5 6 7 octet
956 * +-----+-----+-----+-----+-----+-----+-----+-----+
957 * |type |flags|htype| alg |LSB ---- value ---- MSB|
958 * +-----+-----+-----+-----+-----+-----+-----+-----+
959 *
960 * type: Must be XEN_NETIF_EXTRA_TYPE_HASH
961 * flags: XEN_NETIF_EXTRA_FLAG_*
962 * htype: Hash type (one of _XEN_NETIF_CTRL_HASH_TYPE_* - see above)
963 * alg: The algorithm used to calculate the hash (one of
964 * XEN_NETIF_CTRL_HASH_TYPE_ALGORITHM_* - see above)
965 * value: Hash value
966 */
967
968 /* Protocol checksum field is blank in the packet (hardware offload)? */
969 #define _NETTXF_csum_blank (0)
970 #define NETTXF_csum_blank (1U<<_NETTXF_csum_blank)
971
972 /* Packet data has been validated against protocol checksum. */
973 #define _NETTXF_data_validated (1)
974 #define NETTXF_data_validated (1U<<_NETTXF_data_validated)
975
976 /* Packet continues in the next request descriptor. */
977 #define _NETTXF_more_data (2)
978 #define NETTXF_more_data (1U<<_NETTXF_more_data)
979
980 /* Packet to be followed by extra descriptor(s). */
981 #define _NETTXF_extra_info (3)
982 #define NETTXF_extra_info (1U<<_NETTXF_extra_info)
983
984 #define XEN_NETIF_MAX_TX_SIZE 0xFFFF
985 struct netif_tx_request {
986 grant_ref_t gref;
987 uint16_t offset;
988 uint16_t flags;
989 uint16_t id;
990 uint16_t size;
991 };
992 typedef struct netif_tx_request netif_tx_request_t;
993
994 /* Types of netif_extra_info descriptors. */
995 #define XEN_NETIF_EXTRA_TYPE_NONE (0) /* Never used - invalid */
996 #define XEN_NETIF_EXTRA_TYPE_GSO (1) /* u.gso */
997 #define XEN_NETIF_EXTRA_TYPE_MCAST_ADD (2) /* u.mcast */
998 #define XEN_NETIF_EXTRA_TYPE_MCAST_DEL (3) /* u.mcast */
999 #define XEN_NETIF_EXTRA_TYPE_HASH (4) /* u.hash */
1000 #define XEN_NETIF_EXTRA_TYPE_MAX (5)
1001
1002 /* netif_extra_info_t flags. */
1003 #define _XEN_NETIF_EXTRA_FLAG_MORE (0)
1004 #define XEN_NETIF_EXTRA_FLAG_MORE (1U<<_XEN_NETIF_EXTRA_FLAG_MORE)
1005
1006 /* GSO types */
1007 #define XEN_NETIF_GSO_TYPE_NONE (0)
1008 #define XEN_NETIF_GSO_TYPE_TCPV4 (1)
1009 #define XEN_NETIF_GSO_TYPE_TCPV6 (2)
1010
1011 /*
1012 * This structure needs to fit within both netif_tx_request_t and
1013 * netif_rx_response_t for compatibility.
1014 */
1015 struct netif_extra_info {
1016 uint8_t type;
1017 uint8_t flags;
1018 union {
1019 struct {
1020 uint16_t size;
1021 uint8_t type;
1022 uint8_t pad;
1023 uint16_t features;
1024 } gso;
1025 struct {
1026 uint8_t addr[6];
1027 } mcast;
1028 struct {
1029 uint8_t type;
1030 uint8_t algorithm;
1031 uint8_t value[4];
1032 } hash;
1033 uint16_t pad[3];
1034 } u;
1035 };
1036 typedef struct netif_extra_info netif_extra_info_t;
1037
1038 struct netif_tx_response {
1039 uint16_t id;
1040 int16_t status;
1041 };
1042 typedef struct netif_tx_response netif_tx_response_t;
1043
1044 struct netif_rx_request {
1045 uint16_t id; /* Echoed in response message. */
1046 uint16_t pad;
1047 grant_ref_t gref;
1048 };
1049 typedef struct netif_rx_request netif_rx_request_t;
1050
1051 /* Packet data has been validated against protocol checksum. */
1052 #define _NETRXF_data_validated (0)
1053 #define NETRXF_data_validated (1U<<_NETRXF_data_validated)
1054
1055 /* Protocol checksum field is blank in the packet (hardware offload)? */
1056 #define _NETRXF_csum_blank (1)
1057 #define NETRXF_csum_blank (1U<<_NETRXF_csum_blank)
1058
1059 /* Packet continues in the next request descriptor. */
1060 #define _NETRXF_more_data (2)
1061 #define NETRXF_more_data (1U<<_NETRXF_more_data)
1062
1063 /* Packet to be followed by extra descriptor(s). */
1064 #define _NETRXF_extra_info (3)
1065 #define NETRXF_extra_info (1U<<_NETRXF_extra_info)
1066
1067 /* Packet has GSO prefix. Deprecated but included for compatibility */
1068 #define _NETRXF_gso_prefix (4)
1069 #define NETRXF_gso_prefix (1U<<_NETRXF_gso_prefix)
1070
1071 struct netif_rx_response {
1072 uint16_t id;
1073 uint16_t offset;
1074 uint16_t flags;
1075 int16_t status;
1076 };
1077 typedef struct netif_rx_response netif_rx_response_t;
1078
1079 /*
1080 * Generate netif ring structures and types.
1081 */
1082
1083 DEFINE_RING_TYPES(netif_tx, struct netif_tx_request, struct netif_tx_response);
1084 DEFINE_RING_TYPES(netif_rx, struct netif_rx_request, struct netif_rx_response);
1085
1086 #define NETIF_RSP_DROPPED -2
1087 #define NETIF_RSP_ERROR -1
1088 #define NETIF_RSP_OKAY 0
1089 /* No response: used for auxiliary requests (e.g., netif_extra_info_t). */
1090 #define NETIF_RSP_NULL 1
1091
1092 #endif
1093
1094 /*
1095 * Local variables:
1096 * mode: C
1097 * c-file-style: "BSD"
1098 * c-basic-offset: 4
1099 * tab-width: 4
1100 * indent-tabs-mode: nil
1101 * End:
1102 */
1103