From mboxrd@z Thu Jan  1 00:00:00 1970
From: Stefano Stabellini <stefano.stabellini@eu.citrix.com>
Subject: [PATCH v2] introduce a cache options for PV disks
Date: Thu, 27 Jun 2013 12:40:20 +0100
Message-ID: <alpine.DEB.2.02.1306271238100.4782@kaball.uk.xensource.com>
Mime-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: 7bit
Return-path: <xen-devel-bounces@lists.xen.org>
List-Unsubscribe: <http://lists.xen.org/cgi-bin/mailman/options/xen-devel>,
	<mailto:xen-devel-request@lists.xen.org?subject=unsubscribe>
List-Post: <mailto:xen-devel@lists.xen.org>
List-Help: <mailto:xen-devel-request@lists.xen.org?subject=help>
List-Subscribe: <http://lists.xen.org/cgi-bin/mailman/listinfo/xen-devel>,
	<mailto:xen-devel-request@lists.xen.org?subject=subscribe>
Sender: xen-devel-bounces@lists.xen.org
Errors-To: xen-devel-bounces@lists.xen.org
To: xen-devel@lists.xensource.com
Cc: Ian Jackson <Ian.Jackson@eu.citrix.com>, Ian Campbell <Ian.Campbell@citrix.com>, Stefano Stabellini <Stefano.Stabellini@eu.citrix.com>
List-Id: xen-devel@lists.xenproject.org

Document a per-disk cache option in the xl config file to allow users to
select the cache mode that the backend should use to open the disk file
or device.

Document a "cache" xenstore backend option, part of the vbd xenstore
interface.

Add a reference to xen/include/public/io/blkif.h in
docs/misc/vbd-interface.txt.

Signed-off-by: Stefano Stabellini <stefano.stabellini@eu.citrix.com>


diff --git a/docs/misc/vbd-interface.txt b/docs/misc/vbd-interface.txt
index 3952e73..f873db0 100644
--- a/docs/misc/vbd-interface.txt
+++ b/docs/misc/vbd-interface.txt
@@ -125,3 +125,9 @@ because they directly map the bottom 8 bits of the xenstore integer
 directly to the Linux guest's device number and throw away the rest;
 they can crash due to minor number clashes.  With these guests, the
 workaround is not to supply problematic combinations of devices.
+
+
+Other frontend and backend options
+----------------------------------
+
+See xen/include/public/io/blkif.h for the full list of options.
diff --git a/docs/misc/xl-disk-configuration.txt b/docs/misc/xl-disk-configuration.txt
index 5bd456d..51d376f 100644
--- a/docs/misc/xl-disk-configuration.txt
+++ b/docs/misc/xl-disk-configuration.txt
@@ -178,6 +178,25 @@ information to be interpreted by the executable program <script>,
 These scripts are normally called "block-<script>".
 
 
+cache=<cache>
+-------------
+
+Description:           Specifies what type of disk cache to use in the backend
+Supported values:      writeback, writethrough, none
+Mandatory:             No
+Default value:         depends on the backend type
+
+This does not affect the guest's view of the device. 
+Not all backends implement all cache modes: "phy" only supports "none",
+"qdisk" supports all of them and defaults to "writeback".
+It's important to note that if you are storing the VM disk on a network
+filesystem or a network block device (NFS or ISCSI) it might not be safe
+to use "none", see
+http://lists.xen.org/archives/html/xen-devel/2012-12/msg01154.html.
+Otherwise using "none" is safe and gives you better performances.
+
+
+
 
 ============================================
 DEPRECATED PARAMETERS, PREFIXES AND SYNTAXES
diff --git a/xen/include/public/io/blkif.h b/xen/include/public/io/blkif.h
index b9b9d98..f4a271c 100644
--- a/xen/include/public/io/blkif.h
+++ b/xen/include/public/io/blkif.h
@@ -97,6 +97,16 @@
  *
  *      The type of the backing device/object.
  *
+ *
+ * cache
+ *      Values:         "none", "writeback", "writethrough"
+ *      Optional
+ *
+ *      The cache mode that the backend should use to open the backing
+ *      device/object. The backend is not required to support all the
+ *      possible cache modes. If an unsupported cache is requested, the
+ *      backend is free to ignore it.
+ *
  *--------------------------------- Features ---------------------------------
  *
  * feature-barrier