[PATCH V2] netif.h: Document xen-net{back, front} multi-queue feature

[PATCH V2] netif.h: Document xen-net{back, front} multi-queue feature

[Andrew J. Bennieston]

From: "Andrew J. Bennieston" <andrew.bennieston@citrix.com>

Document the multi-queue feature in terms of XenStore keys to be written
by the backend and by the frontend.

Signed-off-by: Andrew J. Bennieston <andrew.bennieston@citrix.com>

---
V2: Improve documentation based on comments about areas which were unclear.

---
 xen/include/public/io/netif.h |   29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/xen/include/public/io/netif.h b/xen/include/public/io/netif.h
index d7fb771..5d98734 100644
--- a/xen/include/public/io/netif.h
+++ b/xen/include/public/io/netif.h
@@ -69,6 +69,35 @@
  */
 
 /*
+ * Multiple transmit and receive queues:
+ * If supported, the backend will write "multi-queue-max-queues" and set its
+ * value to the maximum supported number of queues.
+ * Frontends that are aware of this feature and wish to use it can write the
+ * key "multi-queue-num-queues", set to the number they wish to use.
+ *
+ * Queues replicate the shared rings and event channels, and
+ * "feature-split-event-channels" may be used when using multiple queues.
+ * Each queue consists of one shared ring pair, i.e. there must be the same
+ * number of tx and rx rings.
+ *
+ * For frontends requesting just one queue, the usual event-channel and
+ * ring-ref keys are written as before, simplifying the backend processing
+ * to avoid distinguishing between a frontend that doesn't understand the
+ * multi-queue feature, and one that does, but requested only one queue.
+ *
+ * Frontends requesting two or more queues must not write the toplevel
+ * event-channel (or event-channel-{tx,rx}) and {tx,rx}-ring-ref keys,
+ * instead writing them under sub-keys having the name "queue-N" where
+ * N is the integer ID of the queue for which those keys belong. Queues 
+ * are indexed from zero.
+ *
+ * Mapping of packets to queues is considered to be a function of the
+ * transmitting system (backend or frontend) and is not negotiated
+ * between the two. Guests are free to transmit packets on any queue
+ * they choose, provided it has been set up correctly.
+ */
+
+/*
  * "feature-no-csum-offload" should be used to turn IPv4 TCP/UDP checksum
  * offload off or on. If it is missing then the feature is assumed to be on.
  * "feature-ipv6-csum-offload" should be used to turn IPv6 TCP/UDP checksum
-- 
1.7.10.4

Re: [PATCH V2] netif.h: Document xen-net{back, front} multi-queue feature

[Jan Beulich]

>>> On 24.02.14 at 15:28, "Andrew J. Bennieston" <andrew.bennieston@citrix.com> wrote:
> From: "Andrew J. Bennieston" <andrew.bennieston@citrix.com>
> 
> Document the multi-queue feature in terms of XenStore keys to be written
> by the backend and by the frontend.
> 
> Signed-off-by: Andrew J. Bennieston <andrew.bennieston@citrix.com>

Anyone of you networking people care to review/ack this?

Thanks, Jan

> ---
> V2: Improve documentation based on comments about areas which were unclear.
> 
> ---
>  xen/include/public/io/netif.h |   29 +++++++++++++++++++++++++++++
>  1 file changed, 29 insertions(+)
> 
> diff --git a/xen/include/public/io/netif.h b/xen/include/public/io/netif.h
> index d7fb771..5d98734 100644
> --- a/xen/include/public/io/netif.h
> +++ b/xen/include/public/io/netif.h
> @@ -69,6 +69,35 @@
>   */
>  
>  /*
> + * Multiple transmit and receive queues:
> + * If supported, the backend will write "multi-queue-max-queues" and set its
> + * value to the maximum supported number of queues.
> + * Frontends that are aware of this feature and wish to use it can write 
> the
> + * key "multi-queue-num-queues", set to the number they wish to use.
> + *
> + * Queues replicate the shared rings and event channels, and
> + * "feature-split-event-channels" may be used when using multiple queues.
> + * Each queue consists of one shared ring pair, i.e. there must be the same
> + * number of tx and rx rings.
> + *
> + * For frontends requesting just one queue, the usual event-channel and
> + * ring-ref keys are written as before, simplifying the backend processing
> + * to avoid distinguishing between a frontend that doesn't understand the
> + * multi-queue feature, and one that does, but requested only one queue.
> + *
> + * Frontends requesting two or more queues must not write the toplevel
> + * event-channel (or event-channel-{tx,rx}) and {tx,rx}-ring-ref keys,
> + * instead writing them under sub-keys having the name "queue-N" where
> + * N is the integer ID of the queue for which those keys belong. Queues 
> + * are indexed from zero.
> + *
> + * Mapping of packets to queues is considered to be a function of the
> + * transmitting system (backend or frontend) and is not negotiated
> + * between the two. Guests are free to transmit packets on any queue
> + * they choose, provided it has been set up correctly.
> + */
> +
> +/*
>   * "feature-no-csum-offload" should be used to turn IPv4 TCP/UDP checksum
>   * offload off or on. If it is missing then the feature is assumed to be 
> on.
>   * "feature-ipv6-csum-offload" should be used to turn IPv6 TCP/UDP checksum
> -- 
> 1.7.10.4
> 
> 
> _______________________________________________
> Xen-devel mailing list
> Xen-devel@lists.xen.org 
> http://lists.xen.org/xen-devel 

Re: [PATCH V2] netif.h: Document xen-net{back, front} multi-queue feature

[Paul Durrant]

> -----Original Message-----
> From: Jan Beulich [mailto:JBeulich@suse.com]
> Sent: 28 February 2014 14:45
> To: Ian Campbell; Paul Durrant; Wei Liu
> Cc: Andrew Bennieston; David Vrabel; xen-devel@lists.xenproject.org
> Subject: Re: [Xen-devel] [PATCH V2] netif.h: Document xen-net{back, front}
> multi-queue feature
> 
> >>> On 24.02.14 at 15:28, "Andrew J. Bennieston"
> <andrew.bennieston@citrix.com> wrote:
> > From: "Andrew J. Bennieston" <andrew.bennieston@citrix.com>
> >
> > Document the multi-queue feature in terms of XenStore keys to be written
> > by the backend and by the frontend.
> >
> > Signed-off-by: Andrew J. Bennieston <andrew.bennieston@citrix.com>
> 
> Anyone of you networking people care to review/ack this?
> 

I'm not a maintainer, so I can't ack, but

Reviewed-by: Paul Durrant <paul.durrant@citrix.com>

> Thanks, Jan
> 
> > ---
> > V2: Improve documentation based on comments about areas which were
> unclear.
> >
> > ---
> >  xen/include/public/io/netif.h |   29 +++++++++++++++++++++++++++++
> >  1 file changed, 29 insertions(+)
> >
> > diff --git a/xen/include/public/io/netif.h b/xen/include/public/io/netif.h
> > index d7fb771..5d98734 100644
> > --- a/xen/include/public/io/netif.h
> > +++ b/xen/include/public/io/netif.h
> > @@ -69,6 +69,35 @@
> >   */
> >
> >  /*
> > + * Multiple transmit and receive queues:
> > + * If supported, the backend will write "multi-queue-max-queues" and
> set its
> > + * value to the maximum supported number of queues.
> > + * Frontends that are aware of this feature and wish to use it can write
> > the
> > + * key "multi-queue-num-queues", set to the number they wish to use.
> > + *
> > + * Queues replicate the shared rings and event channels, and
> > + * "feature-split-event-channels" may be used when using multiple
> queues.
> > + * Each queue consists of one shared ring pair, i.e. there must be the
> same
> > + * number of tx and rx rings.
> > + *
> > + * For frontends requesting just one queue, the usual event-channel and
> > + * ring-ref keys are written as before, simplifying the backend processing
> > + * to avoid distinguishing between a frontend that doesn't understand the
> > + * multi-queue feature, and one that does, but requested only one
> queue.
> > + *
> > + * Frontends requesting two or more queues must not write the toplevel
> > + * event-channel (or event-channel-{tx,rx}) and {tx,rx}-ring-ref keys,
> > + * instead writing them under sub-keys having the name "queue-N"
> where
> > + * N is the integer ID of the queue for which those keys belong. Queues
> > + * are indexed from zero.
> > + *
> > + * Mapping of packets to queues is considered to be a function of the
> > + * transmitting system (backend or frontend) and is not negotiated
> > + * between the two. Guests are free to transmit packets on any queue
> > + * they choose, provided it has been set up correctly.
> > + */
> > +
> > +/*
> >   * "feature-no-csum-offload" should be used to turn IPv4 TCP/UDP
> checksum
> >   * offload off or on. If it is missing then the feature is assumed to be
> > on.
> >   * "feature-ipv6-csum-offload" should be used to turn IPv6 TCP/UDP
> checksum
> > --
> > 1.7.10.4
> >
> >
> > _______________________________________________
> > Xen-devel mailing list
> > Xen-devel@lists.xen.org
> > http://lists.xen.org/xen-devel
> 
> 

Re: [PATCH V2] netif.h: Document xen-net{back, front} multi-queue feature

[Wei Liu]

On Fri, Feb 28, 2014 at 02:44:57PM +0000, Jan Beulich wrote:
> >>> On 24.02.14 at 15:28, "Andrew J. Bennieston" <andrew.bennieston@citrix.com> wrote:
> > From: "Andrew J. Bennieston" <andrew.bennieston@citrix.com>
> > 
> > Document the multi-queue feature in terms of XenStore keys to be written
> > by the backend and by the frontend.
> > 
> > Signed-off-by: Andrew J. Bennieston <andrew.bennieston@citrix.com>
> 
> Anyone of you networking people care to review/ack this?
> 
> Thanks, Jan
> 

Sorry for the late response.

I was actually thinking about acking this after Linux code goes in.
If there's no user and acutal implementation of this feature it wouldn't
be very useful to make it to master tree anyway.

Wei.

Re: [PATCH V2] netif.h: Document xen-net{back, front} multi-queue feature

[Jan Beulich]

>>> On 28.02.14 at 16:07, Wei Liu <wei.liu2@citrix.com> wrote:
> On Fri, Feb 28, 2014 at 02:44:57PM +0000, Jan Beulich wrote:
>> >>> On 24.02.14 at 15:28, "Andrew J. Bennieston" <andrew.bennieston@citrix.com> 
> wrote:
>> > From: "Andrew J. Bennieston" <andrew.bennieston@citrix.com>
>> > 
>> > Document the multi-queue feature in terms of XenStore keys to be written
>> > by the backend and by the frontend.
>> > 
>> > Signed-off-by: Andrew J. Bennieston <andrew.bennieston@citrix.com>
>> 
>> Anyone of you networking people care to review/ack this?
> 
> Sorry for the late response.
> 
> I was actually thinking about acking this after Linux code goes in.
> If there's no user and acutal implementation of this feature it wouldn't
> be very useful to make it to master tree anyway.

Why not - a specification doesn't depend on there being an
actual implementation.

Jan

Re: [PATCH V2] netif.h: Document xen-net{back, front} multi-queue feature

[Jan Beulich]

>>> On 28.02.14 at 15:56, Paul Durrant <Paul.Durrant@citrix.com> wrote:
>>  -----Original Message-----
>> From: Jan Beulich [mailto:JBeulich@suse.com]
>> Sent: 28 February 2014 14:45
>> To: Ian Campbell; Paul Durrant; Wei Liu
>> Cc: Andrew Bennieston; David Vrabel; xen-devel@lists.xenproject.org 
>> Subject: Re: [Xen-devel] [PATCH V2] netif.h: Document xen-net{back, front}
>> multi-queue feature
>> 
>> >>> On 24.02.14 at 15:28, "Andrew J. Bennieston"
>> <andrew.bennieston@citrix.com> wrote:
>> > From: "Andrew J. Bennieston" <andrew.bennieston@citrix.com>
>> >
>> > Document the multi-queue feature in terms of XenStore keys to be written
>> > by the backend and by the frontend.
>> >
>> > Signed-off-by: Andrew J. Bennieston <andrew.bennieston@citrix.com>
>> 
>> Anyone of you networking people care to review/ack this?
>> 
> 
> I'm not a maintainer, so I can't ack, but
> 
> Reviewed-by: Paul Durrant <paul.durrant@citrix.com>

Yeah, the situation with the public headers is all but satisfying.

Jan

Re: [PATCH V2] netif.h: Document xen-net{back, front} multi-queue feature

[Ian Campbell]

On Fri, 2014-02-28 at 14:44 +0000, Jan Beulich wrote:
> >>> On 24.02.14 at 15:28, "Andrew J. Bennieston" <andrew.bennieston@citrix.com> wrote:
> > From: "Andrew J. Bennieston" <andrew.bennieston@citrix.com>
> > 
> > Document the multi-queue feature in terms of XenStore keys to be written
> > by the backend and by the frontend.
> > 
> > Signed-off-by: Andrew J. Bennieston <andrew.bennieston@citrix.com>
> 
> Anyone of you networking people care to review/ack this?

It's in my queue, I'll probably get to it after my current bout of
travel. The first version was looking pretty good so I expect it'll be
ok.

Ian.

Re: [PATCH V2] netif.h: Document xen-net{back, front} multi-queue feature

[Ian Campbell]

Sorry for the delay replying to this.

On Mon, 2014-02-24 at 14:28 +0000, Andrew J. Bennieston wrote:
> From: "Andrew J. Bennieston" <andrew.bennieston@citrix.com>
> 
> Document the multi-queue feature in terms of XenStore keys to be written
> by the backend and by the frontend.
> 
> Signed-off-by: Andrew J. Bennieston <andrew.bennieston@citrix.com>
> 
> ---
> V2: Improve documentation based on comments about areas which were unclear.
> 
> ---
>  xen/include/public/io/netif.h |   29 +++++++++++++++++++++++++++++
>  1 file changed, 29 insertions(+)
> 
> diff --git a/xen/include/public/io/netif.h b/xen/include/public/io/netif.h
> index d7fb771..5d98734 100644
> --- a/xen/include/public/io/netif.h
> +++ b/xen/include/public/io/netif.h
> @@ -69,6 +69,35 @@
>   */
>  
>  /*
> + * Multiple transmit and receive queues:
> + * If supported, the backend will write "multi-queue-max-queues" and set its
> + * value to the maximum supported number of queues.
> + * Frontends that are aware of this feature and wish to use it can write the
> + * key "multi-queue-num-queues", set to the number they wish to use.

In each case they write to their respective directories in xenstore.
Perhaps that's stating the obvious though.

> + *
> + * Queues replicate the shared rings and event channels, and
> + * "feature-split-event-channels" may be used when using multiple queues.

Do you mean s/may/must/ here? (this is my only significant comment on
this patch, the rest are really minor nits)

> + * Each queue consists of one shared ring pair, i.e. there must be the same
> + * number of tx and rx rings.
> + *
> + * For frontends requesting just one queue, the usual event-channel and
> + * ring-ref keys are written as before, simplifying the backend processing
> + * to avoid distinguishing between a frontend that doesn't understand the
> + * multi-queue feature, and one that does, but requested only one queue.
> + *
> + * Frontends requesting two or more queues must not write the toplevel
> + * event-channel (or event-channel-{tx,rx}) and {tx,rx}-ring-ref keys,
> + * instead writing them under sub-keys having the name "queue-N" where
> + * N is the integer ID of the queue for which those keys belong.

and following on from that the "them" which must be written under the
sub-keys could perhaps be spelled out otherwise the prior reference
event-channel or event-channel-{tx,rx} makes things a little ambiguous.

>  Queues 
> + * are indexed from zero.
> + *
> + * Mapping of packets to queues is considered to be a function of the
> + * transmitting system (backend or frontend) and is not negotiated
> + * between the two. Guests are free to transmit packets on any queue
> + * they choose, provided it has been set up correctly.

Perhaps stating the obvious again but "...and must be prepared to
receive a packet on any ring"?

Ian.

Re: [PATCH V2] netif.h: Document xen-net{back, front} multi-queue feature

[Ian Campbell]

On Thu, 2014-03-13 at 12:35 +0000, Ian Campbell wrote:
> Sorry for the delay replying to this.

Was there a v3 which I missed?