[PATCH 1/4] public/io/netif.h: document the reality of netif_rx_request/reponse id

[Paul Durrant <paul.durrant@citrix.com>]

The id field of the netif_rx_request_t abd netif_rx_response_t structures
is actually useless.

Because GSO metadata is passed from backend to frontend using
netif_extra_info segments, which do not carry information stating which
netif_rx_request_t was consumed to free up their slot, frontends assume
that the consumed request is the one that previously occupied that same
slot in the shared ring. Also, whilst theoretically possible for other
responses to be re-ordered, they never have been and that assumption has
always been baked into Linux xen-netfront.

Hence this patch documents that the request id and the response id must
be equal to the ring slot index modulo the ring size.

Signed-off-by: Paul Durrant <paul.durrant@citrix.com>
---
 xen/include/public/io/netif.h | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/xen/include/public/io/netif.h b/xen/include/public/io/netif.h
index 5c31ae3..0fd413a 100644
--- a/xen/include/public/io/netif.h
+++ b/xen/include/public/io/netif.h
@@ -210,7 +210,7 @@
  * | id        | pad       | gref                  |
  * +-----+-----+-----+-----+-----+-----+-----+-----+
  *
- * id: request identifier, echoed in response.
+ * id: must be identical to ring slot index modulo ring size.
  * gref: reference to incoming granted frame.
  *
  * rx response (netif_rx_response_t)
@@ -221,11 +221,18 @@
  * | id        | offset    | flags     | status    |
  * +-----+-----+-----+-----+-----+-----+-----+-----+
  *
- * id: reflects id in receive request
+ * id: must be identical to ring slot index modulo ring size.
  * offset: offset in page of start of received packet
  * flags: NETRXF_*
  * status: -ve: NETIF_RSP_*; +ve: Rx'ed pkt size.
  *
+ * NOTE: The reason that id must be identical to ring slot index
+ *       modulo ring size is because extra info segments (see below)
+ *       carry no indication of the netif_rx_request_t that was
+ *       consumed to make their slot available. The only way a
+ *       frontend can determine which netif_rx_request_t was consumed
+ *       is using the id -> slot identity relation.
+ *
  * Extra Info
  * ==========
  *
-- 
2.1.4