This patch documents a new shared ring between frontend and backend that
can be used to pass bulk out-of-band data, such as that required to
implement toeplitz hashing in the backend such that it is configurable by
the frontend (which is needed to support NDIS RSS for Windows guests).
The patch then goes on to document the messages passed over the control
ring that can be used to configure toeplitz hashing and a new extra info
fragment that can be used to pass hash values between frontend and
backend for both transmit and receive packets.
Signed-off-by: Paul Durrant
Cc: Ian Campbell
Cc: Ian Jackson
Cc: Jan Beulich
Cc: Keir Fraser
Cc: Tim Deegan
---
v5:
- Clarify the control API for toeplitz hashing in many places.
- Add messages for getting and setting mapping table order to allow
for a table that is larger than can be mapped by a single grant
reference.
- Fold in the definition of the new extra info type for passing
hash values and make it toeplitz specific.
v4:
- Fix netif_ctrl_response_t definition to match specification.
v3:
- Fix commit comment.
v2:
- Use a balanced fix-sized message ring for the control ring
(bulk data now passed by grant reference).
---
xen/include/public/io/netif.h | 380 +-
1 file changed, 379 insertions(+), 1 deletion(-)
diff --git a/xen/include/public/io/netif.h b/xen/include/public/io/netif.h
index 0a3272f..e437d6d 100644
--- a/xen/include/public/io/netif.h
+++ b/xen/include/public/io/netif.h
@@ -151,6 +151,361 @@
*/
/*
+ * Control ring
+ *
+ *
+ * Some features, such as toeplitz hashing (detailed below), require a
+ * significant amount of out-of-band data to be passed from frontend to
+ * backend. Use of xenstore is not suitable for large quantities of data
+ * because of quota limitations and so a dedicated 'control ring' is used.
+ * The ability of the backend to use a control ring is advertised by
+ * setting:
+ *
+ * /local/domain/X/backend///feature-control-ring = "1"
+ *
+ * The frontend provides a control ring to the backend by setting:
+ *
+ * /local/domain//device/vif//ctrl-ring-ref =
+ * /local/domain//device/vif//event-channel-ctrl =
+ *
+ * where is the grant reference of the shared page used to
+ * implement the control ring and is an event channel to be used
+ * as a mailbox interrupt. These keys must be set before the frontend
+ * moves into the connected state.
+ *
+ * The control ring uses a fixed request/response message size and is
+ * balanced (i.e. one request to one response), so operationally it is much
+ * the same as a transmit or receive ring.
+ * Note that there is no requirement that responses are issued in the same
+ * order as requests.
+ */
+
+/*
+ * Toeplitz hash types
+ * ===
+ *
+ * For the purposes of the definitions below, 'Packet[]' is an array of
+ * octets containing an IP packet without options, 'Array[X..Y]' means a
+ * sub-array of 'Array' containing bytes X thru Y inclusive, and '+' is
+ * used to indicate concatenation of arrays.
+ */
+
+/*
+ * A hash calculated over an IP version 4 header as follows:
+ *
+ * Buffer[0..8] = Packet[12..15] (source address) +
+ *Packet[16..19] (destination address)
+ *
+ * Result = ToeplitzHash(Buffer, 8)
+ */
+#define _NETIF_CTRL_TOEPLITZ_HASH_IPV4 0
+#define NETIF_CTRL_TOEPLITZ_HASH_IPV4 (1 <<
_NETIF_CTRL_TOEPLITZ_HASH_IPV4)
+
+/*
+ * A hash calculated over an IP version 4 header and TCP header as
+ * follows:
+ *
+ * Buffer[0..12] = Packet[12..15] (source address) +
+ * Packet[16..19] (destination address) +
+ * Packet[20..21] (source port) +
+ * Packet[22..23] (destination port)
+ *
+ * Result = ToeplitzHash(Buffer, 12)
+ */
+#define _NETIF_CTRL_TOEPLITZ_HASH_IPV4_TCP 1
+#define NETIF_CTRL_TOEPLITZ_HASH_IPV4_TCP (1 <<
_NETIF_CTRL_TOEPLITZ_HASH_IPV4_TCP)
+
+/*
+ * A hash calculated over an IP version 6 header as follows:
+ *
+ * Buffer[0..32] = Packet[8..23] (source address ) +
+ * Packet[24..39] (destination address)
+ *
+ * Result = ToeplitzHash(Buffer, 32)
+ */
+#define _NETIF_CTRL_TOEPLITZ_HASH_IPV6 2
+#define NETIF_CTRL_TOEPLITZ_HASH_IPV6 (1 <<
_NETIF_CTRL_TOEPLITZ_HASH_IPV4)
+
+/*
+ * A hash calculated over an IP version 6 header and TCP header as
+ * follows:
+ *
+ * Buffer[0..36] = Packet[8..23] (source address) +
+ * Packet[24..39] (destination address) +
+ * Packet[40..41] (source port) +
+ * Packet[42..43] (destination port)
+ *
+ * Result = ToeplitzHash(Buffer, 36)
+ */
+#define _NETIF_CTRL_TOEPLITZ_HASH_IPV6_TCP 3
+#define NETIF_CTRL_TOEPLITZ_HASH_IPV6_TCP (1 <<
_NETIF_CTRL_TOEPLITZ_HASH_IPV4_TCP)
+
+/*
+ * Control requests (netif_ctrl_request_t)
+ * ===
+ *
+ * All requests have the following format:
+ *
+ *0 1 2 3 4 5 6 7 octet
+ * +-+-+-+-+-
