| blob | 48fa530950cab844addbb2aff7bb0c829b639cc3 |
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 */
27 #ifndef __XEN_PUBLIC_IO_NETIF_H__
28 #define __XEN_PUBLIC_IO_NETIF_H__
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
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 */
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 */
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 */
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 */
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 */
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 */
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/<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 */
193 /*
194 * Hash types
195 * ==========
196 *
197 * For the purposes of the definitions below, 'Packet[]' is an array of
198 * octets containing an IP packet without options, 'Array[X..Y]' means a
199 * sub-array of 'Array' containing bytes X thru Y inclusive, and '+' is
200 * used to indicate concatenation of arrays.
201 */
203 /*
204 * A hash calculated over an IP version 4 header as follows:
205 *
206 * Buffer[0..8] = Packet[12..15] (source address) +
207 * Packet[16..19] (destination address)
208 *
209 * Result = Hash(Buffer, 8)
210 */
211 #define _XEN_NETIF_CTRL_HASH_TYPE_IPV4 0
212 #define XEN_NETIF_CTRL_HASH_TYPE_IPV4 \
213 (1 << _XEN_NETIF_CTRL_HASH_TYPE_IPV4)
215 /*
216 * A hash calculated over an IP version 4 header and TCP header as
217 * follows:
218 *
219 * Buffer[0..12] = Packet[12..15] (source address) +
220 * Packet[16..19] (destination address) +
221 * Packet[20..21] (source port) +
222 * Packet[22..23] (destination port)
223 *
224 * Result = Hash(Buffer, 12)
225 */
226 #define _XEN_NETIF_CTRL_HASH_TYPE_IPV4_TCP 1
227 #define XEN_NETIF_CTRL_HASH_TYPE_IPV4_TCP \
228 (1 << _XEN_NETIF_CTRL_HASH_TYPE_IPV4_TCP)
230 /*
231 * A hash calculated over an IP version 6 header as follows:
232 *
233 * Buffer[0..32] = Packet[8..23] (source address ) +
234 * Packet[24..39] (destination address)
235 *
236 * Result = Hash(Buffer, 32)
237 */
238 #define _XEN_NETIF_CTRL_HASH_TYPE_IPV6 2
239 #define XEN_NETIF_CTRL_HASH_TYPE_IPV6 \
240 (1 << _XEN_NETIF_CTRL_HASH_TYPE_IPV6)
242 /*
243 * A hash calculated over an IP version 6 header and TCP header as
244 * follows:
245 *
246 * Buffer[0..36] = Packet[8..23] (source address) +
247 * Packet[24..39] (destination address) +
248 * Packet[40..41] (source port) +
249 * Packet[42..43] (destination port)
250 *
251 * Result = Hash(Buffer, 36)
252 */
253 #define _XEN_NETIF_CTRL_HASH_TYPE_IPV6_TCP 3
254 #define XEN_NETIF_CTRL_HASH_TYPE_IPV6_TCP \
255 (1 << _XEN_NETIF_CTRL_HASH_TYPE_IPV6_TCP)
257 /*
258 * Hash algorithms
259 * ===============
260 */
262 #define XEN_NETIF_CTRL_HASH_ALGORITHM_NONE 0
264 /*
265 * Toeplitz hash:
266 */
268 #define XEN_NETIF_CTRL_HASH_ALGORITHM_TOEPLITZ 1
270 /*
271 * Control requests (struct xen_netif_ctrl_request)
272 * ================================================
273 *
274 * All requests have the following format:
275 *
276 * 0 1 2 3 4 5 6 7 octet
277 * +-----+-----+-----+-----+-----+-----+-----+-----+
278 * | id | type | data[0] |
279 * +-----+-----+-----+-----+-----+-----+-----+-----+
280 * | data[1] | data[2] |
281 * +-----+-----+-----+-----+-----------------------+
282 *
283 * id: the request identifier, echoed in response.
284 * type: the type of request (see below)
285 * data[]: any data associated with the request (determined by type)
286 */
292 #define XEN_NETIF_CTRL_TYPE_INVALID 0
293 #define XEN_NETIF_CTRL_TYPE_GET_HASH_FLAGS 1
294 #define XEN_NETIF_CTRL_TYPE_SET_HASH_FLAGS 2
295 #define XEN_NETIF_CTRL_TYPE_SET_HASH_KEY 3
296 #define XEN_NETIF_CTRL_TYPE_GET_HASH_MAPPING_SIZE 4
297 #define XEN_NETIF_CTRL_TYPE_SET_HASH_MAPPING_SIZE 5
298 #define XEN_NETIF_CTRL_TYPE_SET_HASH_MAPPING 6
299 #define XEN_NETIF_CTRL_TYPE_SET_HASH_ALGORITHM 7
300 #define XEN_NETIF_CTRL_TYPE_GET_GREF_MAPPING_SIZE 8
301 #define XEN_NETIF_CTRL_TYPE_ADD_GREF_MAPPING 9
302 #define XEN_NETIF_CTRL_TYPE_DEL_GREF_MAPPING 10
305 };
307 /*
308 * Control responses (struct xen_netif_ctrl_response)
309 * ==================================================
310 *
311 * All responses have the following format:
312 *
313 * 0 1 2 3 4 5 6 7 octet
314 * +-----+-----+-----+-----+-----+-----+-----+-----+
315 * | id | type | status |
316 * +-----+-----+-----+-----+-----+-----+-----+-----+
317 * | data |
318 * +-----+-----+-----+-----+
319 *
320 * id: the corresponding request identifier
321 * type: the type of the corresponding request
322 * status: the status of request processing
323 * data: any data associated with the response (determined by type and
324 * status)
325 */
332 #define XEN_NETIF_CTRL_STATUS_SUCCESS 0
333 #define XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED 1
334 #define XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER 2
335 #define XEN_NETIF_CTRL_STATUS_BUFFER_OVERFLOW 3
338 };
340 /*
341 * Static Grants (struct xen_netif_gref)
342 * =====================================
343 *
344 * A frontend may provide a fixed set of grant references to be mapped on
345 * the backend. The message of type XEN_NETIF_CTRL_TYPE_ADD_GREF_MAPPING
346 * prior its usage in the command ring allows for creation of these mappings.
347 * The backend will maintain a fixed amount of these mappings.
348 *
349 * XEN_NETIF_CTRL_TYPE_GET_GREF_MAPPING_SIZE lets a frontend query how many
350 * of these mappings can be kept.
351 *
352 * Each entry in the XEN_NETIF_CTRL_TYPE_{ADD,DEL}_GREF_MAPPING input table has
353 * the following format:
354 *
355 * 0 1 2 3 4 5 6 7 octet
356 * +-----+-----+-----+-----+-----+-----+-----+-----+
357 * | grant ref | flags | status |
358 * +-----+-----+-----+-----+-----+-----+-----+-----+
359 *
360 * grant ref: grant reference (IN)
361 * flags: flags describing the control operation (IN)
362 * status: XEN_NETIF_CTRL_STATUS_* (OUT)
363 *
364 * 'status' is an output parameter which does not require to be set to zero
365 * prior to its usage in the corresponding control messages.
366 */
369 grant_ref_t ref;
372 #define _XEN_NETIF_CTRLF_GREF_readonly 0
373 #define XEN_NETIF_CTRLF_GREF_readonly (1U<<_XEN_NETIF_CTRLF_GREF_readonly)
376 };
378 /*
379 * Control messages
380 * ================
381 *
382 * XEN_NETIF_CTRL_TYPE_SET_HASH_ALGORITHM
383 * --------------------------------------
384 *
385 * This is sent by the frontend to set the desired hash algorithm.
386 *
387 * Request:
388 *
389 * type = XEN_NETIF_CTRL_TYPE_SET_HASH_ALGORITHM
390 * data[0] = a XEN_NETIF_CTRL_HASH_ALGORITHM_* value
391 * data[1] = 0
392 * data[2] = 0
393 *
394 * Response:
395 *
396 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not
397 * supported
398 * XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER - The algorithm is not
399 * supported
400 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful
401 *
402 * NOTE: Setting data[0] to XEN_NETIF_CTRL_HASH_ALGORITHM_NONE disables
403 * hashing and the backend is free to choose how it steers packets
404 * to queues (which is the default behaviour).
405 *
406 * XEN_NETIF_CTRL_TYPE_GET_HASH_FLAGS
407 * ----------------------------------
408 *
409 * This is sent by the frontend to query the types of hash supported by
410 * the backend.
411 *
412 * Request:
413 *
414 * type = XEN_NETIF_CTRL_TYPE_GET_HASH_FLAGS
415 * data[0] = 0
416 * data[1] = 0
417 * data[2] = 0
418 *
419 * Response:
420 *
421 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not supported
422 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful
423 * data = supported hash types (if operation was successful)
424 *
425 * NOTE: A valid hash algorithm must be selected before this operation can
426 * succeed.
427 *
428 * XEN_NETIF_CTRL_TYPE_SET_HASH_FLAGS
429 * ----------------------------------
430 *
431 * This is sent by the frontend to set the types of hash that the backend
432 * should calculate. (See above for hash type definitions).
433 * Note that the 'maximal' type of hash should always be chosen. For
434 * example, if the frontend sets both IPV4 and IPV4_TCP hash types then
435 * the latter hash type should be calculated for any TCP packet and the
436 * former only calculated for non-TCP packets.
437 *
438 * Request:
439 *
440 * type = XEN_NETIF_CTRL_TYPE_SET_HASH_FLAGS
441 * data[0] = bitwise OR of XEN_NETIF_CTRL_HASH_TYPE_* values
442 * data[1] = 0
443 * data[2] = 0
444 *
445 * Response:
446 *
447 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not
448 * supported
449 * XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER - One or more flag
450 * value is invalid or
451 * unsupported
452 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful
453 * data = 0
454 *
455 * NOTE: A valid hash algorithm must be selected before this operation can
456 * succeed.
457 * Also, setting data[0] to zero disables hashing and the backend
458 * is free to choose how it steers packets to queues.
459 *
460 * XEN_NETIF_CTRL_TYPE_SET_HASH_KEY
461 * --------------------------------
462 *
463 * This is sent by the frontend to set the key of the hash if the algorithm
464 * requires it. (See hash algorithms above).
465 *
466 * Request:
467 *
468 * type = XEN_NETIF_CTRL_TYPE_SET_HASH_KEY
469 * data[0] = grant reference of page containing the key (assumed to
470 * start at beginning of grant)
471 * data[1] = size of key in octets
472 * data[2] = 0
473 *
474 * Response:
475 *
476 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not
477 * supported
478 * XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER - Key size is invalid
479 * XEN_NETIF_CTRL_STATUS_BUFFER_OVERFLOW - Key size is larger
480 * than the backend
481 * supports
482 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful
483 * data = 0
484 *
485 * NOTE: Any key octets not specified are assumed to be zero (the key
486 * is assumed to be empty by default) and specifying a new key
487 * invalidates any previous key, hence specifying a key size of
488 * zero will clear the key (which ensures that the calculated hash
489 * will always be zero).
490 * The maximum size of key is algorithm and backend specific, but
491 * is also limited by the single grant reference.
492 * The grant reference may be read-only and must remain valid until
493 * the response has been processed.
494 *
495 * XEN_NETIF_CTRL_TYPE_GET_HASH_MAPPING_SIZE
496 * -----------------------------------------
497 *
498 * This is sent by the frontend to query the maximum size of mapping
499 * table supported by the backend. The size is specified in terms of
500 * table entries.
501 *
502 * Request:
503 *
504 * type = XEN_NETIF_CTRL_TYPE_GET_HASH_MAPPING_SIZE
505 * data[0] = 0
506 * data[1] = 0
507 * data[2] = 0
508 *
509 * Response:
510 *
511 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not supported
512 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful
513 * data = maximum number of entries allowed in the mapping table
514 * (if operation was successful) or zero if a mapping table is
515 * not supported (i.e. hash mapping is done only by modular
516 * arithmetic).
517 *
518 * XEN_NETIF_CTRL_TYPE_SET_HASH_MAPPING_SIZE
519 * -------------------------------------
520 *
521 * This is sent by the frontend to set the actual size of the mapping
522 * table to be used by the backend. The size is specified in terms of
523 * table entries.
524 * Any previous table is invalidated by this message and any new table
525 * is assumed to be zero filled.
526 *
527 * Request:
528 *
529 * type = XEN_NETIF_CTRL_TYPE_SET_HASH_MAPPING_SIZE
530 * data[0] = number of entries in mapping table
531 * data[1] = 0
532 * data[2] = 0
533 *
534 * Response:
535 *
536 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not
537 * supported
538 * XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER - Table size is invalid
539 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful
540 * data = 0
541 *
542 * NOTE: Setting data[0] to 0 means that hash mapping should be done
543 * using modular arithmetic.
544 *
545 * XEN_NETIF_CTRL_TYPE_SET_HASH_MAPPING
546 * ------------------------------------
547 *
548 * This is sent by the frontend to set the content of the table mapping
549 * hash value to queue number. The backend should calculate the hash from
550 * the packet header, use it as an index into the table (modulo the size
551 * of the table) and then steer the packet to the queue number found at
552 * that index.
553 *
554 * Request:
555 *
556 * type = XEN_NETIF_CTRL_TYPE_SET_HASH_MAPPING
557 * data[0] = grant reference of page containing the mapping (sub-)table
558 * (assumed to start at beginning of grant)
559 * data[1] = size of (sub-)table in entries
560 * data[2] = offset, in entries, of sub-table within overall table
561 *
562 * Response:
563 *
564 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not
565 * supported
566 * XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER - Table size or content
567 * is invalid
568 * XEN_NETIF_CTRL_STATUS_BUFFER_OVERFLOW - Table size is larger
569 * than the backend
570 * supports
571 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful
572 * data = 0
573 *
574 * NOTE: The overall table has the following format:
575 *
576 * 0 1 2 3 4 5 6 7 octet
577 * +-----+-----+-----+-----+-----+-----+-----+-----+
578 * | mapping[0] | mapping[1] |
579 * +-----+-----+-----+-----+-----+-----+-----+-----+
580 * | . |
581 * | . |
582 * | . |
583 * +-----+-----+-----+-----+-----+-----+-----+-----+
584 * | mapping[N-2] | mapping[N-1] |
585 * +-----+-----+-----+-----+-----+-----+-----+-----+
586 *
587 * where N is specified by a XEN_NETIF_CTRL_TYPE_SET_HASH_MAPPING_SIZE
588 * message and each mapping must specifies a queue between 0 and
589 * "multi-queue-num-queues" (see above).
590 * The backend may support a mapping table larger than can be
591 * mapped by a single grant reference. Thus sub-tables within a
592 * larger table can be individually set by sending multiple messages
593 * with differing offset values. Specifying a new sub-table does not
594 * invalidate any table data outside that range.
595 * The grant reference may be read-only and must remain valid until
596 * the response has been processed.
597 *
598 * XEN_NETIF_CTRL_TYPE_GET_GREF_MAPPING_SIZE
599 * -----------------------------------------
600 *
601 * This is sent by the frontend to fetch the number of grefs that can be kept
602 * mapped in the backend.
603 *
604 * Request:
605 *
606 * type = XEN_NETIF_CTRL_TYPE_GET_GREF_MAPPING_SIZE
607 * data[0] = queue index (assumed 0 for single queue)
608 * data[1] = 0
609 * data[2] = 0
610 *
611 * Response:
612 *
613 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not
614 * supported
615 * XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER - The queue index is
616 * out of range
617 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful
618 * data = maximum number of entries allowed in the gref mapping table
619 * (if operation was successful) or zero if it is not supported.
620 *
621 * XEN_NETIF_CTRL_TYPE_ADD_GREF_MAPPING
622 * ------------------------------------
623 *
624 * This is sent by the frontend for backend to map a list of grant
625 * references.
626 *
627 * Request:
628 *
629 * type = XEN_NETIF_CTRL_TYPE_ADD_GREF_MAPPING
630 * data[0] = queue index
631 * data[1] = grant reference of page containing the mapping list
632 * (r/w and assumed to start at beginning of page)
633 * data[2] = size of list in entries
634 *
635 * Response:
636 *
637 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not
638 * supported
639 * XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER - Operation failed
640 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful
641 *
642 * NOTE: Each entry in the input table has the format outlined
643 * in struct xen_netif_gref.
644 * Contrary to XEN_NETIF_CTRL_TYPE_DEL_GREF_MAPPING, the struct
645 * xen_netif_gref 'status' field is not used and therefore the response
646 * 'status' determines the success of this operation. In case of
647 * failure none of grants mappings get added in the backend.
648 *
649 * XEN_NETIF_CTRL_TYPE_DEL_GREF_MAPPING
650 * ------------------------------------
651 *
652 * This is sent by the frontend for backend to unmap a list of grant
653 * references.
654 *
655 * Request:
656 *
657 * type = XEN_NETIF_CTRL_TYPE_DEL_GREF_MAPPING
658 * data[0] = queue index
659 * data[1] = grant reference of page containing the mapping list
660 * (r/w and assumed to start at beginning of page)
661 * data[2] = size of list in entries
662 *
663 * Response:
664 *
665 * status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not
666 * supported
667 * XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER - Operation failed
668 * XEN_NETIF_CTRL_STATUS_SUCCESS - Operation successful
669 * data = number of entries that were unmapped
670 *
671 * NOTE: Each entry in the input table has the format outlined in struct
672 * xen_netif_gref.
673 * The struct xen_netif_gref 'status' field determines if the entry
674 * was successfully removed.
675 * The entries used are only the ones representing grant references that
676 * were previously the subject of a XEN_NETIF_CTRL_TYPE_ADD_GREF_MAPPING
677 * operation. Any other entries will have their status set to
678 * XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER upon completion.
679 */
685 /*
686 * Guest transmit
687 * ==============
688 *
689 * This is the 'wire' format for transmit (frontend -> backend) packets:
690 *
691 * Fragment 1: netif_tx_request_t - flags = NETTXF_*
692 * size = total packet size
693 * [Extra 1: netif_extra_info_t] - (only if fragment 1 flags include
694 * NETTXF_extra_info)
695 * ...
696 * [Extra N: netif_extra_info_t] - (only if extra N-1 flags include
697 * XEN_NETIF_EXTRA_MORE)
698 * ...
699 * Fragment N: netif_tx_request_t - (only if fragment N-1 flags include
700 * NETTXF_more_data - flags on preceding
701 * extras are not relevant here)
702 * flags = 0
703 * size = fragment size
704 *
705 * NOTE:
706 *
707 * This format slightly is different from that used for receive
708 * (backend -> frontend) packets. Specifically, in a multi-fragment
709 * packet the actual size of fragment 1 can only be determined by
710 * subtracting the sizes of fragments 2..N from the total packet size.
711 *
712 * Ring slot size is 12 octets, however not all request/response
713 * structs use the full size.
714 *
715 * tx request data (netif_tx_request_t)
716 * ------------------------------------
717 *
718 * 0 1 2 3 4 5 6 7 octet
719 * +-----+-----+-----+-----+-----+-----+-----+-----+
720 * | grant ref | offset | flags |
721 * +-----+-----+-----+-----+-----+-----+-----+-----+
722 * | id | size |
723 * +-----+-----+-----+-----+
724 *
725 * grant ref: Reference to buffer page.
726 * offset: Offset within buffer page.
727 * flags: NETTXF_*.
728 * id: request identifier, echoed in response.
729 * size: packet size in bytes.
730 *
731 * tx response (netif_tx_response_t)
732 * ---------------------------------
733 *
734 * 0 1 2 3 4 5 6 7 octet
735 * +-----+-----+-----+-----+-----+-----+-----+-----+
736 * | id | status | unused |
737 * +-----+-----+-----+-----+-----+-----+-----+-----+
738 * | unused |
739 * +-----+-----+-----+-----+
740 *
741 * id: reflects id in transmit request
742 * status: NETIF_RSP_*
743 *
744 * Guest receive
745 * =============
746 *
747 * This is the 'wire' format for receive (backend -> frontend) packets:
748 *
749 * Fragment 1: netif_rx_request_t - flags = NETRXF_*
750 * size = fragment size
751 * [Extra 1: netif_extra_info_t] - (only if fragment 1 flags include
752 * NETRXF_extra_info)
753 * ...
754 * [Extra N: netif_extra_info_t] - (only if extra N-1 flags include
755 * XEN_NETIF_EXTRA_MORE)
756 * ...
757 * Fragment N: netif_rx_request_t - (only if fragment N-1 flags include
758 * NETRXF_more_data - flags on preceding
759 * extras are not relevant here)
760 * flags = 0
761 * size = fragment size
762 *
763 * NOTE:
764 *
765 * This format slightly is different from that used for transmit
766 * (frontend -> backend) packets. Specifically, in a multi-fragment
767 * packet the size of the packet can only be determined by summing the
768 * sizes of fragments 1..N.
769 *
770 * Ring slot size is 8 octets.
771 *
772 * rx request (netif_rx_request_t)
773 * -------------------------------
774 *
775 * 0 1 2 3 4 5 6 7 octet
776 * +-----+-----+-----+-----+-----+-----+-----+-----+
777 * | id | pad | gref |
778 * +-----+-----+-----+-----+-----+-----+-----+-----+
779 *
780 * id: request identifier, echoed in response.
781 * gref: reference to incoming granted frame.
782 *
783 * rx response (netif_rx_response_t)
784 * ---------------------------------
785 *
786 * 0 1 2 3 4 5 6 7 octet
787 * +-----+-----+-----+-----+-----+-----+-----+-----+
788 * | id | offset | flags | status |
789 * +-----+-----+-----+-----+-----+-----+-----+-----+
790 *
791 * id: reflects id in receive request
792 * offset: offset in page of start of received packet
793 * flags: NETRXF_*
794 * status: -ve: NETIF_RSP_*; +ve: Rx'ed pkt size.
795 *
796 * NOTE: Historically, to support GSO on the frontend receive side, Linux
797 * netfront does not make use of the rx response id (because, as
798 * described below, extra info structures overlay the id field).
799 * Instead it assumes that responses always appear in the same ring
800 * slot as their corresponding request. Thus, to maintain
801 * compatibility, backends must make sure this is the case.
802 *
803 * Extra Info
804 * ==========
805 *
806 * Can be present if initial request or response has NET{T,R}XF_extra_info,
807 * or previous extra request has XEN_NETIF_EXTRA_MORE.
808 *
809 * The struct therefore needs to fit into either a tx or rx slot and
810 * is therefore limited to 8 octets.
811 *
812 * NOTE: Because extra info data overlays the usual request/response
813 * structures, there is no id information in the opposite direction.
814 * So, if an extra info overlays an rx response the frontend can
815 * assume that it is in the same ring slot as the request that was
816 * consumed to make the slot available, and the backend must ensure
817 * this assumption is true.
818 *
819 * extra info (netif_extra_info_t)
820 * -------------------------------
821 *
822 * General format:
823 *
824 * 0 1 2 3 4 5 6 7 octet
825 * +-----+-----+-----+-----+-----+-----+-----+-----+
826 * |type |flags| type specific data |
827 * +-----+-----+-----+-----+-----+-----+-----+-----+
828 * | padding for tx |
829 * +-----+-----+-----+-----+
830 *
831 * type: XEN_NETIF_EXTRA_TYPE_*
832 * flags: XEN_NETIF_EXTRA_FLAG_*
833 * padding for tx: present only in the tx case due to 8 octet limit
834 * from rx case. Not shown in type specific entries
835 * below.
836 *
837 * XEN_NETIF_EXTRA_TYPE_GSO:
838 *
839 * 0 1 2 3 4 5 6 7 octet
840 * +-----+-----+-----+-----+-----+-----+-----+-----+
841 * |type |flags| size |type | pad | features |
842 * +-----+-----+-----+-----+-----+-----+-----+-----+
843 *
844 * type: Must be XEN_NETIF_EXTRA_TYPE_GSO
845 * flags: XEN_NETIF_EXTRA_FLAG_*
846 * size: Maximum payload size of each segment. For example,
847 * for TCP this is just the path MSS.
848 * type: XEN_NETIF_GSO_TYPE_*: This determines the protocol of
849 * the packet and any extra features required to segment the
850 * packet properly.
851 * features: EN_NETIF_GSO_FEAT_*: This specifies any extra GSO
852 * features required to process this packet, such as ECN
853 * support for TCPv4.
854 *
855 * XEN_NETIF_EXTRA_TYPE_MCAST_{ADD,DEL}:
856 *
857 * 0 1 2 3 4 5 6 7 octet
858 * +-----+-----+-----+-----+-----+-----+-----+-----+
859 * |type |flags| addr |
860 * +-----+-----+-----+-----+-----+-----+-----+-----+
861 *
862 * type: Must be XEN_NETIF_EXTRA_TYPE_MCAST_{ADD,DEL}
863 * flags: XEN_NETIF_EXTRA_FLAG_*
864 * addr: address to add/remove
865 *
866 * XEN_NETIF_EXTRA_TYPE_HASH:
867 *
868 * A backend that supports teoplitz hashing is assumed to accept
869 * this type of extra info in transmit packets.
870 * A frontend that enables hashing is assumed to accept
871 * this type of extra info in receive packets.
872 *
873 * 0 1 2 3 4 5 6 7 octet
874 * +-----+-----+-----+-----+-----+-----+-----+-----+
875 * |type |flags|htype| alg |LSB ---- value ---- MSB|
876 * +-----+-----+-----+-----+-----+-----+-----+-----+
877 *
878 * type: Must be XEN_NETIF_EXTRA_TYPE_HASH
879 * flags: XEN_NETIF_EXTRA_FLAG_*
880 * htype: Hash type (one of _XEN_NETIF_CTRL_HASH_TYPE_* - see above)
881 * alg: The algorithm used to calculate the hash (one of
882 * XEN_NETIF_CTRL_HASH_TYPE_ALGORITHM_* - see above)
883 * value: Hash value
884 */
886 /* Protocol checksum field is blank in the packet (hardware offload)? */
887 #define _NETTXF_csum_blank (0)
888 #define NETTXF_csum_blank (1U<<_NETTXF_csum_blank)
890 /* Packet data has been validated against protocol checksum. */
891 #define _NETTXF_data_validated (1)
892 #define NETTXF_data_validated (1U<<_NETTXF_data_validated)
894 /* Packet continues in the next request descriptor. */
895 #define _NETTXF_more_data (2)
896 #define NETTXF_more_data (1U<<_NETTXF_more_data)
898 /* Packet to be followed by extra descriptor(s). */
899 #define _NETTXF_extra_info (3)
900 #define NETTXF_extra_info (1U<<_NETTXF_extra_info)
902 #define XEN_NETIF_MAX_TX_SIZE 0xFFFF
904 grant_ref_t gref;
909 };
912 /* Types of netif_extra_info descriptors. */
918 #define XEN_NETIF_EXTRA_TYPE_MAX (5)
920 /* netif_extra_info_t flags. */
921 #define _XEN_NETIF_EXTRA_FLAG_MORE (0)
922 #define XEN_NETIF_EXTRA_FLAG_MORE (1U<<_XEN_NETIF_EXTRA_FLAG_MORE)
924 /* GSO types */
925 #define XEN_NETIF_GSO_TYPE_NONE (0)
926 #define XEN_NETIF_GSO_TYPE_TCPV4 (1)
927 #define XEN_NETIF_GSO_TYPE_TCPV6 (2)
929 /*
930 * This structure needs to fit within both netif_tx_request_t and
931 * netif_rx_response_t for compatibility.
932 */
953 };
959 };
965 grant_ref_t gref;
966 };
969 /* Packet data has been validated against protocol checksum. */
970 #define _NETRXF_data_validated (0)
971 #define NETRXF_data_validated (1U<<_NETRXF_data_validated)
973 /* Protocol checksum field is blank in the packet (hardware offload)? */
974 #define _NETRXF_csum_blank (1)
975 #define NETRXF_csum_blank (1U<<_NETRXF_csum_blank)
977 /* Packet continues in the next request descriptor. */
978 #define _NETRXF_more_data (2)
979 #define NETRXF_more_data (1U<<_NETRXF_more_data)
981 /* Packet to be followed by extra descriptor(s). */
982 #define _NETRXF_extra_info (3)
983 #define NETRXF_extra_info (1U<<_NETRXF_extra_info)
985 /* Packet has GSO prefix. Deprecated but included for compatibility */
986 #define _NETRXF_gso_prefix (4)
987 #define NETRXF_gso_prefix (1U<<_NETRXF_gso_prefix)
994 };
997 /*
998 * Generate netif ring structures and types.
999 */
1004 #define NETIF_RSP_DROPPED -2
1005 #define NETIF_RSP_ERROR -1
1006 #define NETIF_RSP_OKAY 0
1007 /* No response: used for auxiliary requests (e.g., netif_extra_info_t). */
1008 #define NETIF_RSP_NULL 1
1010 #endif