[Xen-changelog] [xen master] public/io/netif.h: document the reality of netif_rx_request/reponse

[patchbot@xxxxxxx]

commit 19167b11606df3c9598566a870ccd312b10d6d4b
Author:     Paul Durrant <paul.durrant@xxxxxxxxxx>
AuthorDate: Wed Nov 25 11:12:26 2015 +0100
Commit:     Jan Beulich <jbeulich@xxxxxxxx>
CommitDate: Wed Nov 25 11:12:26 2015 +0100

    public/io/netif.h: document the reality of netif_rx_request/reponse
    
    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 must
    assume some form of identity relation between ring slot and request.
    Hence, so that it is able to use GSO metadata, Linux netfront simply
    assumes rx responses appear in the same ring slot as their corresponding
    request.
    
    This patch documents the assumption made by Linux netfront and the
    necessity of the assumption (to support GSO) so that backends are coded
    to be compatible.
    
    Signed-off-by: Paul Durrant <paul.durrant@xxxxxxxxxx>
    Acked-by: Ian Campbell <ian.campbell@xxxxxxxxxx>
---
 xen/include/public/io/netif.h |   18 ++++++++++++++++--
 1 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/xen/include/public/io/netif.h b/xen/include/public/io/netif.h
index 5c31ae3..04d8026 100644
--- a/xen/include/public/io/netif.h
+++ b/xen/include/public/io/netif.h
@@ -226,15 +226,29 @@
  * flags: NETRXF_*
  * status: -ve: NETIF_RSP_*; +ve: Rx'ed pkt size.
  *
+ * NOTE: Historically, to support GSO on the frontend receive side, Linux
+ *       netfront does not make use of the rx response id (because, as
+ *       described below, extra info structures overlay the id field).
+ *       Instead it assumes that responses always appear in the same ring
+ *       slot as their corresponding request. Thus, to maintain
+ *       compatibilty, backends must make sure this is the case.
+ *
  * Extra Info
  * ==========
  *
- * Can be present if initial request has NET{T,R}XF_extra_info, or
- * previous extra request has XEN_NETIF_EXTRA_MORE.
+ * Can be present if initial request or response has NET{T,R}XF_extra_info,
+ * or previous extra request has XEN_NETIF_EXTRA_MORE.
  *
  * The struct therefore needs to fit into either a tx or rx slot and
  * is therefore limited to 8 octets.
  *
+ * NOTE: Because extra info data overlays the usual request/response
+ *       structures, there is no id information in the opposite direction.
+ *       So, if an extra info overlays an rx response the frontend can
+ *       assume that it is in the same ring slot as the request that was
+ *       consumed to make the slot available, and the backend must ensure
+ *       this assumption is true.
+ *
  * extra info (netif_extra_info_t)
  * -------------------------------
  *
--
generated by git-patchbot for /home/xen/git/xen.git#master

_______________________________________________
Xen-changelog mailing list
Xen-changelog@xxxxxxxxxxxxx
http://lists.xensource.com/xen-changelog