[PATCH] docs: document persistent grants

[PATCH] docs: document persistent grants

[Roger Pau Monne]

Document the new persistent grants block-device feature.

Signed-off-by: Roger Pau Monne <roger.pau@citrix.com>
---
 xen/include/public/io/blkif.h |   29 +++++++++++++++++++++++++++++
 1 files changed, 29 insertions(+), 0 deletions(-)

diff --git a/xen/include/public/io/blkif.h b/xen/include/public/io/blkif.h
index d71c7f1..accdda4 100644
--- a/xen/include/public/io/blkif.h
+++ b/xen/include/public/io/blkif.h
@@ -126,6 +126,19 @@
  *      of this type may still be returned at any time with the
  *      BLKIF_RSP_EOPNOTSUPP result code.
  *
+ * feature-persistent
+ *      Values:         0/1 (boolean)
+ *      Default Value:  0
+ *      Notes: 7
+ *
+ *      A value of "1" indicates that the backend can keep the grants used
+ *      by the frontend driver mapped, so the same set of grants should be
+ *      used in all transactions. The maximum number of grants the backend
+ *      can map persistently depends on the implementation, but ideally it
+ *      should be RING_SIZE * BLKIF_MAX_SEGMENTS_PER_REQUEST. Using this
+ *      feature the backend doesn't need to unmap each grant, preventing
+ *      costly TLB flushes.
+ *
  *----------------------- Request Transport Parameters ------------------------
  *
  * max-ring-page-order
@@ -242,6 +255,15 @@
  *      The size of the frontend allocated request ring buffer in units of
  *      machine pages.  The value must be a power of 2.
  *
+ * feature-persistent
+ *      Values:         0/1 (boolean)
+ *      Default Value:  0
+ *      Notes: 7, 8
+ *
+ *      A value of "1" indicates that the frontend will reuse the same grants
+ *      for all transactions, allowing the backend to map them with write
+ *      access (even when it should be read-only).
+ *
  *------------------------- Virtual Device Properties -------------------------
  *
  * device-type
@@ -279,6 +301,13 @@
  *     'ring-ref' is used to communicate the grant reference for this
  *     page to the backend.  When using a multi-page ring, the 'ring-ref'
  *     node is not created.  Instead 'ring-ref0' - 'ring-refN' are used.
+ * (7) When using persistent grants data has to be copied from/to the page
+ *     where the grant is currently mapped. The overhead of doing this copy
+ *     however doesn't suppress the speed improvement of not having to unmap
+ *     the grants.
+ * (8) The frontend driver has to allow the backend driver to map all grants
+ *     with write access, even when they should be mapped read-only, since
+ *     further requests may reuse this grants and require write permisions.
  */
 
 /*
-- 
1.7.7.5 (Apple Git-26)

Re: [PATCH] docs: document persistent grants

[Ian Jackson]

Roger Pau Monne writes ("[Xen-devel] [PATCH] docs: document persistent grants"):
> Document the new persistent grants block-device feature.
> 
> Signed-off-by: Roger Pau Monne <roger.pau@citrix.com>

Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>
Committed-by: Ian Jackson <ian.jackson@eu.citrix.com>

Re: [PATCH] docs: document persistent grants

[Konrad Rzeszutek Wilk]

On Mon, Oct 29, 2012 at 12:09:56PM +0100, Roger Pau Monne wrote:
> Document the new persistent grants block-device feature.
> 
> Signed-off-by: Roger Pau Monne <roger.pau@citrix.com>
> ---
>  xen/include/public/io/blkif.h |   29 +++++++++++++++++++++++++++++
>  1 files changed, 29 insertions(+), 0 deletions(-)
> 
> diff --git a/xen/include/public/io/blkif.h b/xen/include/public/io/blkif.h
> index d71c7f1..accdda4 100644
> --- a/xen/include/public/io/blkif.h
> +++ b/xen/include/public/io/blkif.h
> @@ -126,6 +126,19 @@
>   *      of this type may still be returned at any time with the
>   *      BLKIF_RSP_EOPNOTSUPP result code.
>   *
> + * feature-persistent
> + *      Values:         0/1 (boolean)

That is not a boolean strickly. That would be 'true/false'. Perhaps 'int'?

> + *      Default Value:  0
> + *      Notes: 7
> + *
> + *      A value of "1" indicates that the backend can keep the grants used
> + *      by the frontend driver mapped, so the same set of grants should be
> + *      used in all transactions. The maximum number of grants the backend
> + *      can map persistently depends on the implementation, but ideally it
> + *      should be RING_SIZE * BLKIF_MAX_SEGMENTS_PER_REQUEST. Using this
> + *      feature the backend doesn't need to unmap each grant, preventing
> + *      costly TLB flushes.
> + *
>   *----------------------- Request Transport Parameters ------------------------
>   *
>   * max-ring-page-order
> @@ -242,6 +255,15 @@
>   *      The size of the frontend allocated request ring buffer in units of
>   *      machine pages.  The value must be a power of 2.
>   *
> + * feature-persistent
> + *      Values:         0/1 (boolean)
> + *      Default Value:  0
> + *      Notes: 7, 8
> + *
> + *      A value of "1" indicates that the frontend will reuse the same grants
> + *      for all transactions, allowing the backend to map them with write
> + *      access (even when it should be read-only).
> + *
>   *------------------------- Virtual Device Properties -------------------------
>   *
>   * device-type
> @@ -279,6 +301,13 @@
>   *     'ring-ref' is used to communicate the grant reference for this
>   *     page to the backend.  When using a multi-page ring, the 'ring-ref'
>   *     node is not created.  Instead 'ring-ref0' - 'ring-refN' are used.
> + * (7) When using persistent grants data has to be copied from/to the page
> + *     where the grant is currently mapped. The overhead of doing this copy
> + *     however doesn't suppress the speed improvement of not having to unmap
> + *     the grants.
> + * (8) The frontend driver has to allow the backend driver to map all grants
> + *     with write access, even when they should be mapped read-only, since
> + *     further requests may reuse this grants and require write permisions.
>   */
>  
>  /*
> -- 
> 1.7.7.5 (Apple Git-26)
> 
> 
> _______________________________________________
> Xen-devel mailing list
> Xen-devel@lists.xen.org
> http://lists.xen.org/xen-devel
> 

Re: [PATCH] docs: document persistent grants

[Ian Campbell]

On Mon, 2012-10-29 at 11:09 +0000, Roger Pau Monne wrote:
> + *      A value of "1" indicates that the backend can keep the grants used
> + *      by the frontend driver mapped, so the same set of grants should be
> + *      used in all transactions. The maximum number of grants the backend
> + *      can map persistently depends on the implementation, but ideally it
> + *      should be RING_SIZE * BLKIF_MAX_SEGMENTS_PER_REQUEST. Using this
> + *      feature the backend doesn't need to unmap each grant, preventing
> + *      costly TLB flushes.
> 
> @@ -279,6 +301,13 @@
>   *     'ring-ref' is used to communicate the grant reference for this
>   *     page to the backend.  When using a multi-page ring, the 'ring-ref'
>   *     node is not created.  Instead 'ring-ref0' - 'ring-refN' are used.
> + * (7) When using persistent grants data has to be copied from/to the page
> + *     where the grant is currently mapped. The overhead of doing this copy
> + *     however doesn't suppress the speed improvement of not having to unmap
> + *     the grants.
> + * (8) The frontend driver has to allow the backend driver to map all grants
> + *     with write access, even when they should be mapped read-only, since
> + *     further requests may reuse this grants and require write permisions.

                                                                  permissions

It not clear if it is required to always reuse a grant or if the
frontend can use a normal grant if it has run out of persistent slots.
It's also not all that clear how a grant becomes persistent and who
(front or back) gets to make that determination.

AIUI the backend makes the decision whether to keep a grant mapped
persistently or not while the frontend is expect to try and reuse grants
as much as possible when persistent mode is enabled, is that right?

Is there any provision for shrinking the size of the cached pool of
mappings when usage is low? I suppose that's a backend implementation
detail?

Ian.