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