[Xen-devel] [PATCH v4 1/5] public/io/netif.h: document the reality of netif_rx_request/reponse id

[Paul Durrant <paul.durrant@xxxxxxxxxx>]

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@xxxxxxxxxx>
Cc: Ian Campbell <ian.campbell@xxxxxxxxxx>
Cc: Ian Jackson <ian.jackson@xxxxxxxxxxxxx>
Cc: Jan Beulich <jbeulich@xxxxxxxx>
Cc: Keir Fraser <keir@xxxxxxx>
Cc: Tim Deegan <tim@xxxxxxx>
---

v4:
 - Add slightly more explanation in a comment
---
 xen/include/public/io/netif.h | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)

diff --git a/xen/include/public/io/netif.h b/xen/include/public/io/netif.h
index 5c31ae3..7ea9ea7 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,20 @@
  * | id        | offset    | flags     | status    |
  * +-----+-----+-----+-----+-----+-----+-----+-----+
  *
- * id: reflects id in receive request
+ * id: must be identical to request id (and hence, by implication, rx
+ *     responses must be located in the same ring slot as their
+ *     corresponding requests).
  * 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
  * ==========
  *
@@ -373,7 +382,7 @@ struct netif_tx_response {
 typedef struct netif_tx_response netif_tx_response_t;
 
 struct netif_rx_request {
-    uint16_t    id;        /* Echoed in response message.        */
+    uint16_t    id;
     uint16_t    pad;
     grant_ref_t gref;      /* Reference to incoming granted frame */
 };
-- 
2.1.4


_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel