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

[Andrew Bennieston <andrew.bennieston@citrix.com>]

On 19/02/14 11:06, Ian Campbell wrote:
> On Mon, 2014-02-17 at 18:01 +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>
>> ---
>>   xen/include/public/io/netif.h |   21 +++++++++++++++++++++
>>   1 file changed, 21 insertions(+)
>>
>> diff --git a/xen/include/public/io/netif.h b/xen/include/public/io/netif.h
>> index d7fb771..90be2fc 100644
>> --- a/xen/include/public/io/netif.h
>> +++ b/xen/include/public/io/netif.h
>> @@ -69,6 +69,27 @@
>>    */
>>
>>   /*
>> + * 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" is required when using multiple queues.
>> + *
>> + * 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 and 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.
>
> If "feature-split-event-channels" is required then I think what should
> be written is queue-N/event-channel-{tx,rx} and
> queue-N/{tx,rx}-ring-ref, rather than queue-N/{event-channel,ring-ref}
> as the final paragraph sort of implies?
I can change the wording to make this more clear.

>
> (what a shame we have event-channel-DIR and DIR-ring-ref, oh well!)
>
> Is it required to have the same number of RX and TX queues?
Strictly speaking, no. But the implementation assumes this to be the 
case. Since the code already sets up one pair, simply looping over this 
sufficient times to create N pairs was a fairly sane approach to this. 
In practice, if you have an asymmetry between RX and TX queues, you will 
end up hitting a bottleneck sooner in one direction than the other, 
which seems impractical.

>
> Are there any other properties/behaviours which should be documented,
> e.g. relating to the selection of which queue to use for a given frame
> (on either TX or RX)? If not and it is up to the relevant end to do what
> it wants then I think it would be useful to say so.
There are no other requirements. The current implementation will 
transmit anything it cannot hash sensibly on queue 0, but this is an 
arbitrary choice (albeit a sensible one, since queue 0 should always 
exist). I'll document this.

>
>> + */
>> +
>> +/*
>>    * "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
>
>