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

[PATCH V3] 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>

---
Changes since V2:
- Clarified several areas of text which may be confusing or ambiguous.
- Made clear that split event channels may be used in conjunction with
  multiple queues, but are not required.

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

diff --git a/xen/include/public/io/netif.h b/xen/include/public/io/netif.h
index d7fb771..0c3b5bd 100644
--- a/xen/include/public/io/netif.h
+++ b/xen/include/public/io/netif.h
@@ -69,6 +69,52 @@
  */
 
 /*
+ * Multiple transmit and receive queues:
+ * If supported, the backend will write the key "multi-queue-max-queues" to
+ * the directory for that vif, 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, but
+ * are not required to do so.
+ *
+ * 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 those keys 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. For example, a frontend with two queues and split
+ * event channels may write the following set of queue-related keys:
+ *
+ * /local/domain/1/device/vif/0/multi-queue-num-queues = "2"
+ * /local/domain/1/device/vif/0/queue-0 = ""
+ * /local/domain/1/device/vif/0/queue-0/tx-ring-ref = "<ring-ref-tx0>"
+ * /local/domain/1/device/vif/0/queue-0/rx-ring-ref = "<ring-ref-rx0>"
+ * /local/domain/1/device/vif/0/queue-0/event-channel-tx = "<evtchn-tx0>"
+ * /local/domain/1/device/vif/0/queue-0/event-channel-rx = "<evtchn-rx0>"
+ * /local/domain/1/device/vif/0/queue-1 = ""
+ * /local/domain/1/device/vif/0/queue-1/tx-ring-ref = "<ring-ref-tx1>"
+ * /local/domain/1/device/vif/0/queue-1/rx-ring-ref = "<ring-ref-rx1"
+ * /local/domain/1/device/vif/0/queue-1/event-channel-tx = "<evtchn-tx1>"
+ * /local/domain/1/device/vif/0/queue-1/event-channel-rx = "<evtchn-rx1>"
+ * 
+ * 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. Guests must be
+ * prepared to receive packets on any queue they have requested be set up.
+ */
+
+/*
  * "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 V3] netif.h: Document xen-net{back, front} multi-queue feature

[David Vrabel]

On 30/04/14 13:26, 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>

Reviewed-by: David Vrabel <david.vrabel@citrix.com>

David

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

[Wei Liu]

On Wed, Apr 30, 2014 at 01:26:41PM +0100, 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>
> 

Acked-by: Wei Liu <wei.liu2@citrix.com>

Thanks

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

[Ian Campbell]

On Wed, 2014-04-30 at 13:26 +0100, Andrew J. Bennieston wrote:
> + * Queues replicate the shared rings and event channels, and
> + * "feature-split-event-channels" may be used when using multiple queues, but
> + * are not required to do so.

I cannot parse the second two thirds of this sentence, in particular
"but are to required to do so".

Is a word (drivers?) missing between "but" and "are"? Or did you mean
"but it is not required..." maybe.

How about:
 * Queues replicate the shared rings and event channels. "feature-split-event-channels" may
 * optionally be used when using multiple queues, but is not mandatory.

?

Ian.

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

[Andrew Bennieston]

On 02/05/14 17:23, Ian Campbell wrote:
> On Wed, 2014-04-30 at 13:26 +0100, Andrew J. Bennieston wrote:
>> + * Queues replicate the shared rings and event channels, and
>> + * "feature-split-event-channels" may be used when using multiple queues, but
>> + * are not required to do so.
>
> I cannot parse the second two thirds of this sentence, in particular
> "but are to required to do so".
>
> Is a word (drivers?) missing between "but" and "are"? Or did you mean
> "but it is not required..." maybe.
>
> How about:
>   * Queues replicate the shared rings and event channels. "feature-split-event-channels" may
>   * optionally be used when using multiple queues, but is not mandatory.
>
> ?
Er, yes. Looking back over that I've no idea what I intended to write, 
but it clearly isn't what I actually wrote! I will resend with your 
suggested wording.

>
> Ian.
>
>