interface/io/netif.h

1 /* SPDX-License-Identifier: MIT */
5  * Unified network-device I/O interface for Xen guest OSes.
7  * Copyright (c) 2003-2004, Keir Fraser
19  * ring slots a skb can use. Netfront / netback may not work as
22  * A better approach is to add mechanism for netfront / netback to
24  * frontends, so we need to define a value which states the minimum
28  * (18), which is proved to work with most frontends. Any new backend
29  * which doesn't negotiate with frontend should expect frontend to
30  * send a valid packet using slots up to this value.
37  * If the client sends notification for rx requests then it should specify
38  * feature 'feature-rx-notify' via xenbus. Otherwise the backend will assume
39  * that it cannot safely queue packets (as it may not be kicked to send them).
43  * "feature-split-event-channels" is introduced to separate guest TX
44  * and RX notification. Backend either doesn't support this feature or
47  * To make use of this feature, frontend should allocate two event
48  * channels for TX and RX, advertise them to backend as
49  * "event-channel-tx" and "event-channel-rx" respectively. If frontend
50  * doesn't want to use this feature, it just writes "event-channel"
55  * Multiple transmit and receive queues:
56  * If supported, the backend will write the key "multi-queue-max-queues" to
57  * the directory for that vif, and set its value to the maximum supported
58  * number of queues.
59  * Frontends that are aware of this feature and wish to use it can write the
60  * key "multi-queue-num-queues", set to the number they wish to use, which
62  * in "multi-queue-max-queues".
64  * Queues replicate the shared rings and event channels.
65  * "feature-split-event-channels" may optionally be used when using
66  * multiple queues, but is not mandatory.
69  * number of tx and rx rings.
71  * For frontends requesting just one queue, the usual event-channel and
72  * ring-ref keys are written as before, simplifying the backend processing
73  * to avoid distinguishing between a frontend that doesn't understand the
74  * multi-queue feature, and one that does, but requested only one queue.
76  * Frontends requesting two or more queues must not write the toplevel
77  * event-channel (or event-channel-{tx,rx}) and {tx,rx}-ring-ref keys,
78  * instead writing those keys under sub-keys having the name "queue-N" where
79  * N is the integer ID of the queue for which those keys belong. Queues
80  * are indexed from zero. For example, a frontend with two queues and split
81  * event channels must write the following set of queue-related keys:
83  * /local/domain/1/device/vif/0/multi-queue-num-queues = "2"
84  * /local/domain/1/device/vif/0/queue-0 = ""
85  * /local/domain/1/device/vif/0/queue-0/tx-ring-ref = "<ring-ref-tx0>"
86  * /local/domain/1/device/vif/0/queue-0/rx-ring-ref = "<ring-ref-rx0>"
87  * /local/domain/1/device/vif/0/queue-0/event-channel-tx = "<evtchn-tx0>"
88  * /local/domain/1/device/vif/0/queue-0/event-channel-rx = "<evtchn-rx0>"
89  * /local/domain/1/device/vif/0/queue-1 = ""
90  * /local/domain/1/device/vif/0/queue-1/tx-ring-ref = "<ring-ref-tx1>"
91  * /local/domain/1/device/vif/0/queue-1/rx-ring-ref = "<ring-ref-rx1"
92  * /local/domain/1/device/vif/0/queue-1/event-channel-tx = "<evtchn-tx1>"
93  * /local/domain/1/device/vif/0/queue-1/event-channel-rx = "<evtchn-rx1>"
96  * choose not to connect any queues, instead treating the request as an
97  * error. This includes scenarios where more (or fewer) queues were
100  * Mapping of packets to queues is considered to be a function of the
102  * between the two. Guests are free to transmit packets on any queue
104  * prepared to receive packets on any queue they have requested be set up.
108  * "feature-no-csum-offload" should be used to turn IPv4 TCP/UDP checksum
109  * offload off or on. If it is missing then the feature is assumed to be on.
110  * "feature-ipv6-csum-offload" should be used to turn IPv6 TCP/UDP checksum
111  * offload on or off. If it is missing then the feature is assumed to be off.
115  * "feature-gso-tcpv4" and "feature-gso-tcpv6" advertise the capability to
117  * frontends nor backends are assumed to be capable unless the flags are
122  * "feature-multicast-control" and "feature-dynamic-multicast-control"
123  * advertise the capability to filter ethernet multicast packets in the
124  * backend. If the frontend wishes to take advantage of this feature then
125  * it may set "request-multicast-control". If the backend only advertises
126  * "feature-multicast-control" then "request-multicast-control" must be set
130  * "feature-dynamic-multicast-control" then "request-multicast-control"
132  * watch the value and re-sample on watch events.
134  * If the sampled value of "request-multicast-control" is set then the
135  * backend transmit side should no longer flood multicast packets to the
139  * containing XEN_NETIF_EXTRA_TYPE_MCAST_{ADD,DEL} extra-info fragments as
142  * "request-multicast-control" is not set, however the filter should only
147  * "xdp-headroom" is used to request that extra space is added
149  * the frontend to be consistent between both ends.
151  * an RX response is going to be passed to an XDP program for processing.
154  * "feature-xdp-headroom" is set to "1" by the netback side like other features
164  * significant amount of out-of-band data to be passed from frontend to
165  * backend. Use of xenstore is not suitable for large quantities of data
167  * The ability of the backend to use a control ring is advertised by
170  * /local/domain/X/backend/<domid>/<vif>/feature-ctrl-ring = "1"
172  * The frontend provides a control ring to the backend by setting:
174  * /local/domain/<domid>/device/vif/<vif>/ctrl-ring-ref = <gref>
175  * /local/domain/<domid>/device/vif/<vif>/event-channel-ctrl = <port>
177  * where <gref> is the grant reference of the shared page used to
178  * implement the control ring and <port> is an event channel to be used
183  * balanced (i.e. one request to one response), so operationally it is much
195  * sub-array of 'Array' containing bytes X thru Y inclusive, and '+' is
196  * used to indicate concatenation of arrays.
268  * (Buffer[] and Key[] are treated as shift-registers where the MSB of
269  * Buffer/Key[0] is considered 'left-most' and the LSB of Buffer/Key[N-1]
270  * is the 'right-most').
274  *    If (left-most bit of Buffer[] is 1)
275  *        Value ^= left-most 32 bits of Key[]
291 	/* Pre-load prefix with the first 8 bytes of the key */  in xen_netif_toeplitz_hash()
309 		 * 'prefix' has now been left-shifted by 8, so  in xen_netif_toeplitz_hash()
328  * +-----+-----+-----+-----+-----+-----+-----+-----+
330  * +-----+-----+-----+-----+-----+-----+-----+-----+
332  * +-----+-----+-----+-----+-----------------------+
362  * +-----+-----+-----+-----+-----+-----+-----+-----+
364  * +-----+-----+-----+-----+-----+-----+-----+-----+
366  * +-----+-----+-----+-----+
393  * --------------------------------------
395  * This is sent by the frontend to set the desired hash algorithm.
406  *  status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED     - Operation not
408  *           XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER - The algorithm is not
410  *           XEN_NETIF_CTRL_STATUS_SUCCESS           - Operation successful
412  * NOTE: Setting data[0] to XEN_NETIF_CTRL_HASH_ALGORITHM_NONE disables
413  *       hashing and the backend is free to choose how it steers packets
414  *       to queues (which is the default behaviour).
417  * ----------------------------------
419  * This is sent by the frontend to query the types of hash supported by
431  *  status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not supported
432  *           XEN_NETIF_CTRL_STATUS_SUCCESS       - Operation successful
439  * ----------------------------------
441  * This is sent by the frontend to set the types of hash that the backend
446  * former only calculated for non-TCP packets.
457  *  status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED     - Operation not
459  *           XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER - One or more flag
462  *           XEN_NETIF_CTRL_STATUS_SUCCESS           - Operation successful
467  *       Also, setting data[0] to zero disables hashing and the backend
468  *       is free to choose how it steers packets to queues.
471  * --------------------------------
473  * This is sent by the frontend to set the key of the hash if the algorithm
479  *  data[0] = grant reference of page containing the key (assumed to
486  *  status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED     - Operation not
488  *           XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER - Key size is invalid
489  *           XEN_NETIF_CTRL_STATUS_BUFFER_OVERFLOW   - Key size is larger
492  *           XEN_NETIF_CTRL_STATUS_SUCCESS           - Operation successful
495  * NOTE: Any key octets not specified are assumed to be zero (the key
496  *       is assumed to be empty by default) and specifying a new key
502  *       The grant reference may be read-only and must remain valid until
506  * -----------------------------------------
508  * This is sent by the frontend to query the maximum size of mapping
521  *  status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not supported
522  *           XEN_NETIF_CTRL_STATUS_SUCCESS       - Operation successful
529  * -------------------------------------
531  * This is sent by the frontend to set the actual size of the mapping
532  * table to be used by the backend. The size is specified in terms of
535  * is assumed to be zero filled.
546  *  status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED     - Operation not
548  *           XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER - Table size is invalid
549  *           XEN_NETIF_CTRL_STATUS_SUCCESS           - Operation successful
552  * NOTE: Setting data[0] to 0 means that hash mapping should be done
556  * ------------------------------------
558  * This is sent by the frontend to set the content of the table mapping
559  * hash value to queue number. The backend should calculate the hash from
560  * the packet header, use it as an index into the table (modulo the size
561  * of the table) and then steer the packet to the queue number found at
567  *  data[0] = grant reference of page containing the mapping (sub-)table
568  *            (assumed to start at beginning of grant)
569  *  data[1] = size of (sub-)table in entries
570  *  data[2] = offset, in entries, of sub-table within overall table
574  *  status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED     - Operation not
576  *           XEN_NETIF_CTRL_STATUS_INVALID_PARAMETER - Table size or content
578  *           XEN_NETIF_CTRL_STATUS_BUFFER_OVERFLOW   - Table size is larger
581  *           XEN_NETIF_CTRL_STATUS_SUCCESS           - Operation successful
587  *       +-----+-----+-----+-----+-----+-----+-----+-----+
589  *       +-----+-----+-----+-----+-----+-----+-----+-----+
593  *       +-----+-----+-----+-----+-----+-----+-----+-----+
594  *       |      mapping[N-2]     |      mapping[N-1]     |
595  *       +-----+-----+-----+-----+-----+-----+-----+-----+
599  *       "multi-queue-num-queues" (see above).
601  *       mapped by a single grant reference. Thus sub-tables within a
603  *       with differing offset values. Specifying a new sub-table does not
605  *       The grant reference may be read-only and must remain valid until
617  * This is the 'wire' format for transmit (frontend -> backend) packets:
619  *  Fragment 1: xen_netif_tx_request_t  - flags = XEN_NETTXF_*
621  * [Extra 1: xen_netif_extra_info_t]    - (only if fragment 1 flags include
624  * [Extra N: xen_netif_extra_info_t]    - (only if extra N-1 flags include
627  *  Fragment N: xen_netif_tx_request_t  - (only if fragment N-1 flags include
628  *                                     XEN_NETTXF_more_data - flags on preceding
636  * (backend -> frontend) packets. Specifically, in a multi-fragment
641  * structs use the full size.
644  * ------------------------------------
647  * +-----+-----+-----+-----+-----+-----+-----+-----+
649  * +-----+-----+-----+-----+-----+-----+-----+-----+
651  * +-----+-----+-----+-----+
653  * grant ref: Reference to buffer page.
660  * ---------------------------------
663  * +-----+-----+-----+-----+-----+-----+-----+-----+
665  * +-----+-----+-----+-----+-----+-----+-----+-----+
667  * +-----+-----+-----+-----+
675  * This is the 'wire' format for receive (backend -> frontend) packets:
677  *  Fragment 1: xen_netif_rx_request_t  - flags = XEN_NETRXF_*
679  * [Extra 1: xen_netif_extra_info_t]    - (only if fragment 1 flags include
682  * [Extra N: xen_netif_extra_info_t]    - (only if extra N-1 flags include
685  *  Fragment N: xen_netif_rx_request_t  - (only if fragment N-1 flags include
686  *                                     XEN_NETRXF_more_data - flags on preceding
694  * (frontend -> backend) packets. Specifically, in a multi-fragment
700  * rx request (xen_netif_rx_request_t)
701  * -------------------------------
704  * +-----+-----+-----+-----+-----+-----+-----+-----+
706  * +-----+-----+-----+-----+-----+-----+-----+-----+
709  * gref: reference to incoming granted frame.
711  * rx response (xen_netif_rx_response_t)
712  * ---------------------------------
715  * +-----+-----+-----+-----+-----+-----+-----+-----+
717  * +-----+-----+-----+-----+-----+-----+-----+-----+
722  * status: -ve: XEN_NETIF_RSP_*; +ve: Rx'ed pkt size.
724  * NOTE: Historically, to support GSO on the frontend receive side, Linux
725  *       netfront does not make use of the rx response id (because, as
728  *       slot as their corresponding request. Thus, to maintain
737  * The struct therefore needs to fit into either a tx or rx slot and
738  * is therefore limited to 8 octets.
742  *       So, if an extra info overlays an rx response the frontend can
744  *       consumed to make the slot available, and the backend must ensure
748  * -------------------------------
753  * +-----+-----+-----+-----+-----+-----+-----+-----+
755  * +-----+-----+-----+-----+-----+-----+-----+-----+
757  * +-----+-----+-----+-----+
761  * padding for tx: present only in the tx case due to 8 octet limit
762  *                 from rx case. Not shown in type specific entries
768  * +-----+-----+-----+-----+-----+-----+-----+-----+
770  * +-----+-----+-----+-----+-----+-----+-----+-----+
777  *       the packet and any extra features required to segment the
780  *           features required to process this packet, such as ECN
786  * +-----+-----+-----+-----+-----+-----+-----+-----+
788  * +-----+-----+-----+-----+-----+-----+-----+-----+
792  * addr: address to add/remove
796  * A backend that supports teoplitz hashing is assumed to accept
798  * A frontend that enables hashing is assumed to accept
802  * +-----+-----+-----+-----+-----+-----+-----+-----+
803  * |type |flags|htype| alg |LSB ---- value ---- MSB|
804  * +-----+-----+-----+-----+-----+-----+-----+-----+
808  * htype: Hash type (one of _XEN_NETIF_CTRL_HASH_TYPE_* - see above)
809  * alg: The algorithm used to calculate the hash (one of
810  *      XEN_NETIF_CTRL_HASH_TYPE_ALGORITHM_* - see above)
826 /* Packet to be followed by extra descriptor(s). */
840 #define XEN_NETIF_EXTRA_TYPE_NONE      (0)	/* Never used - invalid */
858  * This structure needs to fit within both xen_netif_tx_request_t and
910 /* Packet to be followed by extra descriptor(s). */
934 #define XEN_NETIF_RSP_DROPPED         -2
935 #define XEN_NETIF_RSP_ERROR           -1