Re: [PATCH v6 2/2] public/io/netif.h: document control ring and toeplitz hashing

[Paul Durrant <Paul.Durrant@citrix.com>]

> -----Original Message-----
> From: Paul Durrant [mailto:paul.durrant@citrix.com]
> Sent: 11 January 2016 16:05
> To: xen-devel@lists.xenproject.org
> Cc: Paul Durrant; Ian Campbell; Ian Jackson; Jan Beulich; Keir (Xen.org); Tim
> (Xen.org)
> Subject: [PATCH v6 2/2] public/io/netif.h: document control ring and toeplitz
> hashing
> 
> This patch documents a new shared ring between frontend and backend that
> can be used to pass bulk out-of-band data, such as that required to
> implement toeplitz hashing in the backend such that it is configurable by
> the frontend (which is needed to support NDIS RSS for Windows guests).
> 
> The patch then goes on to document the messages passed over the control
> ring that can be used to configure toeplitz hashing and a new extra info
> fragment that can be used to pass hash values between frontend and
> backend for both transmit and receive packets.
> 
> 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:
>  - Clarify the control API for toeplitz hashing in many places.
>  - Add messages for getting and setting mapping table order to allow
>    for a table that is larger than can be mapped by a single grant
>    reference.
>  - Fold in the definition of the new extra info type for passing
>    hash values and make it toeplitz specific.
> 
> v4:
>  - Fix netif_ctrl_response_t definition to match specification.
> 
> v3:
>  - Fix commit comment.
> 
> v2:
>  - Use a balanced fix-sized message ring for the control ring
>    (bulk data now passed by grant reference).
> ---
>  xen/include/public/io/netif.h | 380
> +++++++++++++++++++++++++++++++++++++++++-
>  1 file changed, 379 insertions(+), 1 deletion(-)
> 
> diff --git a/xen/include/public/io/netif.h b/xen/include/public/io/netif.h
> index 0a3272f..e437d6d 100644
> --- a/xen/include/public/io/netif.h
> +++ b/xen/include/public/io/netif.h
> @@ -151,6 +151,361 @@
>   */
> 
>  /*
> + * Control ring
> + * ============
> + *
> + * Some features, such as toeplitz hashing (detailed below), require a
> + * significant amount of out-of-band data to be passed from frontend to
> + * backend. Use of xenstore is not suitable for large quantities of data
> + * because of quota limitations and so a dedicated 'control ring' is used.
> + * The ability of the backend to use a control ring is advertised by
> + * setting:
> + *
> + * /local/domain/X/backend/<domid>/<vif>/feature-control-ring = "1"

I noticed this isn't consistent with the abbreviation of 'control' to 'ctrl' below so I'll change it.

  Paul

> + *
> + * The frontend provides a control ring to the backend by setting:
> + *
> + * /local/domain/<domid>/device/vif/<vif>/ctrl-ring-ref = <gref>
> + * /local/domain/<domid>/device/vif/<vif>/event-channel-ctrl = <port>
> + *
> + * where <gref> is the grant reference of the shared page used to
> + * implement the control ring and <port> is an event channel to be used
> + * as a mailbox interrupt. These keys must be set before the frontend
> + * moves into the connected state.