Re: [Xen-devel] [PATCH] blkif.h: document blkif multi-queue/ring extension

[Konrad Rzeszutek Wilk <konrad.wilk@xxxxxxxxxx>]

On Thu, Oct 29, 2015 at 10:37:39AM +0800, Bob Liu wrote:
> Document the multi-queue/ring feature in terms of XenStore keys to be written
> by the backend and by the frontend.
> 
> Signed-off-by: Bob Liu <bob.liu@xxxxxxxxxx>
> ---
>  xen/include/public/io/blkif.h |   48 
> +++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 48 insertions(+)
> 
> diff --git a/xen/include/public/io/blkif.h b/xen/include/public/io/blkif.h
> index 8f0f9a6..f7823bb 100644
> --- a/xen/include/public/io/blkif.h
> +++ b/xen/include/public/io/blkif.h
> @@ -394,6 +394,54 @@
>   */
>  
>  /*
> + * Multiple hardware queues/rings:
> + * If supported, the backend will write the key "multi-queue-max-queues" to
> + * the directory for that vbd, 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" with the number they wish to use, which must 
> be
> + * greater than zero, and no more than the value reported by the backend in
> + * "multi-queue-max-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 those keys under sub-keys
> + * having the name "queue-N" where N is the integer ID of the queue/ring for
> + * which those keys belong. Queues are indexed from zero.
> + * For example, a frontend with two queues must write the following set of
> + * queue-related keys:
> + *
> + * /local/domain/1/device/vbd/0/multi-queue-num-queues = "2"
> + * /local/domain/1/device/vbd/0/queue-0 = ""
> + * /local/domain/1/device/vbd/0/queue-0/ring-ref = "<ring-ref>"

<ring-ref#0>
> + * /local/domain/1/device/vbd/0/queue-0/event-channel = "<evtchn>"
<evtchn#0>

> + * /local/domain/1/device/vbd/0/queue-1 = ""
> + * /local/domain/1/device/vbd/0/queue-1/ring-ref = "<ring-ref>"

<ring-ref#1>
> + * /local/domain/1/device/vbd/0/queue-1/event-channel = "<evtchn>"
<evtchn#1>

So that one can distinguish that the ring-reg / event channel for
each queue MUST not be the same. Maybe even spell it out.

> + *
> + * It is also possible to use multiple queues/rings together with
> + * feature multi-page ring buffer.
> + * For example, a frontend requests two queues/rings and the size of each 
> ring
> + * buffer is two pages must write the following set of related keys:
> + *
> + * /local/domain/1/device/vbd/0/multi-queue-num-queues = "2"
> + * /local/domain/1/device/vbd/0/ring-page-order = "1"
> + * /local/domain/1/device/vbd/0/queue-0 = ""
> + * /local/domain/1/device/vbd/0/queue-0/ring-ref0 = "<ring-ref0>"

s/ref0/ref#0
> + * /local/domain/1/device/vbd/0/queue-0/ring-ref1 = "<ring-ref1>"

s/ref1/ref#1

> + * /local/domain/1/device/vbd/0/queue-0/event-channel = "<evtchn>"

evtchn#0
> + * /local/domain/1/device/vbd/0/queue-1 = ""
> + * /local/domain/1/device/vbd/0/queue-1/ring-ref0 = "<ring-ref0>"

s/ref0/ref#2/
> + * /local/domain/1/device/vbd/0/queue-1/ring-ref1 = "<ring-ref1>"
s/ref1/ref#3/

> + * /local/domain/1/device/vbd/0/queue-1/event-channel = "<evtchn>"

s/evtchn/evtchn#1/

> + *
> + */
> +
> +/*
>   * STATE DIAGRAMS
>   *
>   
> *****************************************************************************
> -- 
> 1.7.10.4
> 

_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel