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
38  * feature 'feature-rx-notify' via xenbus. Otherwise the backend will assume
43  * "feature-split-event-channels" is introduced to separate guest TX
49  * "event-channel-tx" and "event-channel-rx" respectively. If frontend
50  * doesn't want to use this feature, it just writes "event-channel"
56  * If supported, the backend will write the key "multi-queue-max-queues" to
60  * key "multi-queue-num-queues", set to the number they wish to use, which
62  * in "multi-queue-max-queues".
65  * "feature-split-event-channels" may optionally be used when using
71  * For frontends requesting just one queue, the usual event-channel and
72  * ring-ref keys are written as before, simplifying the backend processing
74  * multi-queue feature, and one that does, but requested only one queue.
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
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>"
108  * "feature-no-csum-offload" should be used to turn IPv4 TCP/UDP checksum
110  * "feature-ipv6-csum-offload" should be used to turn IPv6 TCP/UDP checksum
115  * "feature-gso-tcpv4" and "feature-gso-tcpv6" advertise the capability to
122  * "feature-multicast-control" and "feature-dynamic-multicast-control"
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
139  * containing XEN_NETIF_EXTRA_TYPE_MCAST_{ADD,DEL} extra-info fragments as
141  * Note that the filter list may be amended even if the sampled value of
142  * "request-multicast-control" is not set, however the filter should only
147  * "xdp-headroom" is used to request that extra space is added
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
170  * /local/domain/X/backend/<domid>/<vif>/feature-ctrl-ring = "1"
174  * /local/domain/<domid>/device/vif/<vif>/ctrl-ring-ref = <gref>
175  * /local/domain/<domid>/device/vif/<vif>/event-channel-ctrl = <port>
195  * sub-array of 'Array' containing bytes X thru Y inclusive, and '+' is
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  * --------------------------------------
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
417  * ----------------------------------
431  *  status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not supported
432  *           XEN_NETIF_CTRL_STATUS_SUCCESS       - Operation successful
439  * ----------------------------------
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
471  * --------------------------------
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
502  *       The grant reference may be read-only and must remain valid until
506  * -----------------------------------------
521  *  status = XEN_NETIF_CTRL_STATUS_NOT_SUPPORTED - Operation not supported
522  *           XEN_NETIF_CTRL_STATUS_SUCCESS       - Operation successful
529  * -------------------------------------
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
556  * ------------------------------------
567  *  data[0] = grant reference of page containing the mapping (sub-)table
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
644  * ------------------------------------
647  * +-----+-----+-----+-----+-----+-----+-----+-----+
649  * +-----+-----+-----+-----+-----+-----+-----+-----+
651  * +-----+-----+-----+-----+
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
701  * -------------------------------
704  * +-----+-----+-----+-----+-----+-----+-----+-----+
706  * +-----+-----+-----+-----+-----+-----+-----+-----+
712  * ---------------------------------
715  * +-----+-----+-----+-----+-----+-----+-----+-----+
717  * +-----+-----+-----+-----+-----+-----+-----+-----+
722  * status: -ve: XEN_NETIF_RSP_*; +ve: Rx'ed pkt size.
748  * -------------------------------
753  * +-----+-----+-----+-----+-----+-----+-----+-----+
755  * +-----+-----+-----+-----+-----+-----+-----+-----+
757  * +-----+-----+-----+-----+
768  * +-----+-----+-----+-----+-----+-----+-----+-----+
770  * +-----+-----+-----+-----+-----+-----+-----+-----+
786  * +-----+-----+-----+-----+-----+-----+-----+-----+
788  * +-----+-----+-----+-----+-----+-----+-----+-----+
802  * +-----+-----+-----+-----+-----+-----+-----+-----+
803  * |type |flags|htype| alg |LSB ---- value ---- MSB|
804  * +-----+-----+-----+-----+-----+-----+-----+-----+
808  * htype: Hash type (one of _XEN_NETIF_CTRL_HASH_TYPE_* - see above)
810  *      XEN_NETIF_CTRL_HASH_TYPE_ALGORITHM_* - see above)
840 #define XEN_NETIF_EXTRA_TYPE_NONE      (0)	/* Never used - invalid */
934 #define XEN_NETIF_RSP_DROPPED         -2
935 #define XEN_NETIF_RSP_ERROR           -1