On Tue, 2016-11-29 at 15:34 -0800, Stefano Stabellini wrote:
> ### Frontend XenBus Nodes
> 
>     num-rings
>          Values:         <uint32_t>
>     
>          Number of rings. It needs to be lower or equal to max-rings.
>     
>     port-<num> (port-0, port-1, etc)
>          Values:         <uint32_t>
>     
>          The identifier of the Xen event channel used to signal
> activity
>          in the ring buffer. One for each ring.
>     
>     ring-ref-<num> (ring-ref-0, ring-ref-1, etc)
>
blkif uses ring-ref%u, rather than ring-ref-%u (i.e., no dash before
the index). Not a big deal, I guess, but I thought it could be nice to
be a bit more uniform.

>          Values:         <uint32_t>
>     
>          The Xen grant reference granting permission for the backend
> to
>          map a page with information to setup a share ring. One for
> each
>          ring.
> 
So, this means there can be multiple rings (up to max-rings advertised
by backend), _each_of_which_ has its own event channel, and
_each_of_which_ can be a multi-page (in case ring_order > 0) ring... Is
this correct?

If it is, what's the typical envisioned use of these multiple rings, if
I can ask?

(Maybe it's obvious, I'm still not so familiar with these protocols..
but I'm trying to improve, and that's why I'm here, so bear with me if
possible. :-D)

> ## Ring Setup
> 
> The shared page has the following layout:
> 
>     typedef uint32_t XEN_9PFS_RING_IDX;
> 
>     struct xen_9pfs_intf {
>     	XEN_9PFS_RING_IDX in_cons, in_prod;
>     	XEN_9PFS_RING_IDX out_cons, out_prod;
>     
>     	uint32_t ring_order;
>     	grant_ref_t ref[];
>     };
> 
>     /* not actually C compliant (ring_order changes from socket to
> socket) */
>     struct ring_data {
>         char in[((1 << ring_order) << PAGE_SHIFT) / 2];
>         char out[((1 << ring_order) << PAGE_SHIFT) / 2];
>     };
>
Sorry, what does "ring_order changes from socket to socket" mean?

> The binary layout of `struct xen_9pfs_intf` follows:
> 
>     0         4         8         12        16        20
>     +---------+---------+---------+---------+---------+
>     | in_cons | in_prod |out_cons |out_prod |ring_orde|
>     +---------+---------+---------+---------+---------+
> 
>     20        24        26      4092      4096
>     +---------+---------+----//---+---------+
>     |  ref[0] |  ref[1] |         |  ref[N] |
>     +---------+---------+----//---+---------+
> 
> **N.B** For one page, N is maximum 1019 ((4096-20)/4), but given that
> N
> needs to be a power of two, actually max N is 512.
>
It may again be me being still too naive, but I'd quickly add at least
another example, with the value of N computed for a multiple pages
ring. Something like: "For 4 pages (i.e., ring_orfer=2), N is..."

Regards,
Dario
-- 
<<This happens because I choose it to happen!>> (Raistlin Majere)
-----------------------------------------------------------------
Dario Faggioli, Ph.D, http://about.me/dario.faggioli
Senior Software Engineer, Citrix Systems R&D Ltd., Cambridge (UK)