Re: [Xen-devel] [PATCH v4 1/3] public/io/netif.h: document transmit and receive wire formats separately

[Ian Campbell <ian.campbell@xxxxxxxxxx>]

On Thu, 2016-01-07 at 13:05 +0000, Paul Durrant 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@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>
> ---
> Âxen/include/public/io/netif.h | 39 ++++++++++++++++++++++++++-----------
> --
> Â1 file changed, 26 insertions(+), 13 deletions(-)
> 
> diff --git a/xen/include/public/io/netif.h
> b/xen/include/public/io/netif.h
> index e103cf3..1790ea0 100644
> --- a/xen/include/public/io/netif.h
> +++ b/xen/include/public/io/netif.h
> @@ -151,22 +151,22 @@
> Â */
> Â
> Â/*
> - * 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 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)

For Fragment 2 is it the Flags of Fragment N-1 = 1 which are relevant, or
the flags in the optional Extra N which may be in the middle (i.e. the
immediately preceding slot)?

Am I correct in remembering that in the presence of NETTXF_more_data the
only way to know the actual size of Fragment 1 is to take away the total of
all the extras from Frag 1's size?

> + *ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂflags = 0
> + *ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂsize = fragment size
> + *
> Â * Ring slot size is 12 octets, however not all request/response
> Â * structs use the full size.
> Â *
> @@ -202,6 +202,19 @@
> Â * Guest receive
> Â * =============
> Â *
> + * This is the 'wire' format for 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 = 0
> + *ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂsize = fragment size

Same Q re which NETRXF_more_data is relevant.

In this path there is no indication of the total packet size other than
adding everything up?

Given that they differ in a subtle way would a quick but explicit "NOTE: RX
and TX differ" be a useful addition do you think?

> + *
> Â * Ring slot size is 8 octets.
> Â *
> Â * rx request (netif_rx_request_t)
_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel