[v5,1/2] public/io/netif.h: document transmit and receive wire formats separately
diff mbox

Message ID 1452525938-9493-2-git-send-email-paul.durrant@citrix.com
State New, archived
Headers show

Commit Message

Paul Durrant Jan. 11, 2016, 3:25 p.m. UTC
Currently there is no documented wire format for guest receive-side
packets but the location of the 'wire format' comment block suggests
it is the same as transmit-side. This is almost true but there is a
subtle difference in the use of the 'size' field for the first fragment.

For clarity this patch creates separate comment blocks for receive
and transmit side packet wire formats, tries to be more clear about the
distinction between 'fragments' and 'extras', and documents the subtlety
concerning the size field of the first fragment.

Signed-off-by: Paul Durrant <paul.durrant@citrix.com>
Cc: Ian Campbell <ian.campbell@citrix.com>
Cc: Ian Jackson <ian.jackson@eu.citrix.com>
Cc: Jan Beulich <jbeulich@suse.com>
Cc: Keir Fraser <keir@xen.org>
Cc: Tim Deegan <tim@xen.org>
---

v5:
 - Add extra clarifications.
---
 xen/include/public/io/netif.h | 59 +++++++++++++++++++++++++++++++++----------
 1 file changed, 46 insertions(+), 13 deletions(-)

Comments

Jan Beulich Jan. 11, 2016, 3:52 p.m. UTC | #1
>>> On 11.01.16 at 16:25, <paul.durrant@citrix.com> wrote:
> Currently there is no documented wire format for guest receive-side
> packets but the location of the 'wire format' comment block suggests
> it is the same as transmit-side. This is almost true but there is a
> subtle difference in the use of the 'size' field for the first fragment.
> 
> For clarity this patch creates separate comment blocks for receive
> and transmit side packet wire formats, tries to be more clear about the
> distinction between 'fragments' and 'extras', and documents the subtlety
> concerning the size field of the first fragment.
> 
> Signed-off-by: Paul Durrant <paul.durrant@citrix.com>
> Cc: Ian Campbell <ian.campbell@citrix.com>
> Cc: Ian Jackson <ian.jackson@eu.citrix.com>
> Cc: Jan Beulich <jbeulich@suse.com>
> Cc: Keir Fraser <keir@xen.org>
> Cc: Tim Deegan <tim@xen.org>
> ---
> 
> v5:
>  - Add extra clarifications.

Di you perhaps not notice that v4 went in, and hence an incremental
patch would be needed?

Jan
Paul Durrant Jan. 11, 2016, 3:59 p.m. UTC | #2
> -----Original Message-----
> From: Jan Beulich [mailto:JBeulich@suse.com]
> Sent: 11 January 2016 15:53
> To: Paul Durrant
> Cc: Ian Campbell; Ian Jackson; xen-devel@lists.xenproject.org; Keir
> (Xen.org); Tim (Xen.org)
> Subject: Re: [PATCH v5 1/2] public/io/netif.h: document transmit and receive
> wire formats separately
> 
> >>> On 11.01.16 at 16:25, <paul.durrant@citrix.com> wrote:
> > Currently there is no documented wire format for guest receive-side
> > packets but the location of the 'wire format' comment block suggests
> > it is the same as transmit-side. This is almost true but there is a
> > subtle difference in the use of the 'size' field for the first fragment.
> >
> > For clarity this patch creates separate comment blocks for receive
> > and transmit side packet wire formats, tries to be more clear about the
> > distinction between 'fragments' and 'extras', and documents the subtlety
> > concerning the size field of the first fragment.
> >
> > Signed-off-by: Paul Durrant <paul.durrant@citrix.com>
> > Cc: Ian Campbell <ian.campbell@citrix.com>
> > Cc: Ian Jackson <ian.jackson@eu.citrix.com>
> > Cc: Jan Beulich <jbeulich@suse.com>
> > Cc: Keir Fraser <keir@xen.org>
> > Cc: Tim Deegan <tim@xen.org>
> > ---
> >
> > v5:
> >  - Add extra clarifications.
> 
> Di you perhaps not notice that v4 went in, and hence an incremental
> patch would be needed?

Nope, clearly I didn't. I did not see an Acked-by so I didn't check.

I'll send v6 with an incremental patch.

  Paul

> 
> Jan

Patch
diff mbox

diff --git a/xen/include/public/io/netif.h b/xen/include/public/io/netif.h
index e103cf3..0a3272f 100644
--- a/xen/include/public/io/netif.h
+++ b/xen/include/public/io/netif.h
@@ -151,22 +151,32 @@ 
  */
 
 /*
- * This is the 'wire' format for packets:
- *  Request 1: netif_tx_request_t -- NETTXF_* (any flags)
- * [Request 2: netif_extra_info_t] (only if request 1 has
- *                                  NETTXF_extra_info)
- * [Request 3: netif_extra_info_t] (only if request 2 has
- *                                  XEN_NETIF_EXTRA_MORE)
- *  Request 4: netif_tx_request_t -- NETTXF_more_data
- *  Request 5: netif_tx_request_t -- NETTXF_more_data
- *  ...
- *  Request N: netif_tx_request_t -- 0
- */
-
-/*
  * Guest transmit
  * ==============
  *
+ * This is the 'wire' format for transmit (frontend -> backend) packets:
+ *
+ *  Fragment 1: netif_tx_request_t  - flags = NETTXF_*
+ *                                    size = total packet size
+ * [Extra 1: netif_extra_info_t]    - (only if fragment 1 flags include
+ *                                     NETTXF_extra_info)
+ *  ...
+ * [Extra N: netif_extra_info_t]    - (only if extra N-1 flags include
+ *                                     XEN_NETIF_EXTRA_MORE)
+ *  ...
+ *  Fragment N: netif_tx_request_t  - (only if fragment N-1 flags include
+ *                                     NETTXF_more_data - flags on preceding
+ *                                     extras are not relevent here)
+ *                                    flags = 0
+ *                                    size = fragment size
+ *
+ * NOTE:
+ *
+ * This format slightly is different from that used for receive
+ * (backend -> frontend) packets. Specifically, in a multi-fragment
+ * packet the actual size of fragment 1 can only be determined by
+ * subtracting the sizes of fragments 2..N from the total packet size.
+ *
  * Ring slot size is 12 octets, however not all request/response
  * structs use the full size.
  *
@@ -202,6 +212,29 @@ 
  * Guest receive
  * =============
  *
+ * This is the 'wire' format for receive (backend -> frontend) packets:
+ *
+ *  Fragment 1: netif_rx_request_t  - flags = NETRXF_*
+ *                                    size = fragment size
+ * [Extra 1: netif_extra_info_t]    - (only if fragment 1 flags include
+ *                                     NETRXF_extra_info)
+ *  ...
+ * [Extra N: netif_extra_info_t]    - (only if extra N-1 flags include
+ *                                     XEN_NETIF_EXTRA_MORE)
+ *  ...
+ *  Fragment N: netif_rx_request_t  - (only if fragment N-1 flags include
+ *                                     NETRXF_more_data - flags on preceding
+ *                                     extras are not relevent here)
+ *                                    flags = 0
+ *                                    size = fragment size
+ *
+ * NOTE:
+ *
+ * This format slightly is different from that used for transmit
+ * (frontend -> backend) packets. Specifically, in a multi-fragment
+ * packet the size of the packet can only be determined by summing the
+ * sizes of fragments 1..N.
+ *
  * Ring slot size is 8 octets.
  *
  * rx request (netif_rx_request_t)