Re: [PATCH v7 1/2] public/io/netif.h: clarifications to wire formats

[Ian Campbell <ian.campbell@citrix.com>]

On Tue, 2016-01-12 at 09:58 +0000, Paul Durrant wrote:
> My previous patch 03809ae7 "document transmit and receive wire formats
> separately" improved documentation of the receive and transmit wire
> formats but further clarifications were requested.
> 
> This patch adds those clarifications.
> 
> Signed-off-by: Paul Durrant <paul.durrant@citrix.com>

Acked-by: 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>
> ---
> 
> v6:
>  - v4 of the original patch was committed so this is an
>    incremental version of the patch in v5.
> 
> v5:
>  - Add extra clarifications.
> ---
>  xen/include/public/io/netif.h | 28 ++++++++++++++++++++++++----
>  1 file changed, 24 insertions(+), 4 deletions(-)
> 
> diff --git a/xen/include/public/io/netif.h
> b/xen/include/public/io/netif.h
> index 1790ea0..0a3272f 100644
> --- a/xen/include/public/io/netif.h
> +++ b/xen/include/public/io/netif.h
> @@ -154,19 +154,29 @@
>   * Guest transmit
>   * ==============
>   *
> - * This is the 'wire' format for packets:
> + * 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)
> + *                                     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,19 +212,29 @@
>   * Guest receive
>   * =============
>   *
> - * This is the 'wire' format for packets:
> + * 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)
> + *                                     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)
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
http://lists.xen.org/xen-devel