[Xen-changelog] [xen-unstable] interface: Flesh out the BLKIF_OP_DISCARD description.

[Xen patchbot-unstable <patchbot@xxxxxxx>]

# HG changeset patch
# User Konrad Rzeszutek Wilk <konrad.wilk@xxxxxxxxxx>
# Date 1319727857 -3600
# Node ID 083797fda372341278757b5e23db6de0862c4242
# Parent  be1a190becae07485081d170fd41215203a2886b
interface: Flesh out the BLKIF_OP_DISCARD description.

We flesh out details on what is expected of 'feature-flush' and
what are some of the extra parameters that the frontend can read
from the backend. Those extra parameters are: : discard-aligment,
and discard-granularity.

Acked-by: Jan Beulich <JBeulich@xxxxxxxx>
Signed-off-by: Konrad Rzeszutek Wilk <konrad.wilk@xxxxxxxxxx>
Committed-by: Keir Fraser <keir@xxxxxxx>
---


diff -r be1a190becae -r 083797fda372 xen/include/public/io/blkif.h
--- a/xen/include/public/io/blkif.h     Thu Oct 27 16:03:51 2011 +0100
+++ b/xen/include/public/io/blkif.h     Thu Oct 27 16:04:17 2011 +0100
@@ -83,22 +83,43 @@
 #define BLKIF_OP_RESERVED_1        4
 /*
  * Recognised only if "feature-discard" is present in backend xenbus info.
- * The "feature-discard" node contains a boolean indicating whether discard
- * requests are likely to succeed or fail. Either way, a discard request
+ * The "feature-discard" node contains a boolean indicating whether trim
+ * (ATA) or unmap (SCSI) - conviently called discard requests are likely
+ * to succeed or fail. Either way, a discard request
  * may fail at any time with BLKIF_RSP_EOPNOTSUPP if it is unsupported by
  * the underlying block-device hardware. The boolean simply indicates whether
  * or not it is worthwhile for the frontend to attempt discard requests.
  * If a backend does not recognise BLKIF_OP_DISCARD, it should *not*
  * create the "feature-discard" node!
- * 
+ *
  * Discard operation is a request for the underlying block device to mark
- * extents to be erased. Discard operations are passed with sector_number as 
the
+ * extents to be erased. However, discard does not guarantee that the blocks
+ * will be erased from the device - it is just a hint to the device
+ * controller that these blocks are no longer in use. What the device
+ * controller does with that information is left to the controller.
+ * Discard operations are passed with sector_number as the
  * sector index to begin discard operations at and nr_sectors as the number of
  * sectors to be discarded. The specified sectors should be discarded if the
- * underlying block device supports discard operations, or a 
BLKIF_RSP_EOPNOTSUPP
- * should be returned. More information about discard operations at:
+ * underlying block device supports trim (ATA) or unmap (SCSI) operations,
+ * or a BLKIF_RSP_EOPNOTSUPP  should be returned.
+ * More information about trim/unmap operations at:
  * http://t13.org/Documents/UploadedDocuments/docs2008/
  *     e07154r6-Data_Set_Management_Proposal_for_ATA-ACS2.doc
+ * http://www.seagate.com/staticfiles/support/disc/manuals/
+ *     Interface%20manuals/100293068c.pdf
+ * The backend can optionally provide these extra XenBus attributes to
+ * further optimize the discard functionality:
+ * 'discard-aligment' - Devices that support discard functionality may
+ * internally allocate space in units that are bigger than the exported
+ * logical block size. The discard-alignment parameter indicates how many bytes
+ * the beginning of the partition is offset from the internal allocation unit's
+ * natural alignment. Do not confuse this with natural disk alignment offset.
+ * 'discard-granularity'  - Devices that support discard functionality may
+ * internally allocate space using units that are bigger than the logical block
+ * size. The discard-granularity parameter indicates the size of the internal
+ * allocation unit in bytes if reported by the device. Otherwise the
+ * discard-granularity will be set to match the device's physical block size.
+ * It is the minimum size you can discard.
  */
 #define BLKIF_OP_DISCARD           5
 

_______________________________________________
Xen-changelog mailing list
Xen-changelog@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/xen-changelog