Changeset 38621 in vbox for trunk/include/VBox

Timestamp:

Sep 4, 2011 4:56:56 PM (14 years ago)

Author:

vboxsync

svn:sync-xref-src-repo-rev:

73828

Message:

VD: Initial support to discard unused blocks in an image + support for VDI images

Location:

trunk/include/VBox

Files:

• err.h (modified) (1 diff)
• vd-plugin.h (modified) (4 diffs)
• vd.h (modified) (5 diffs)

trunk/include/VBox/err.h

@@ -1334 +1334 @@
 /** The cache is not up to date with the image. */
 #define VERR_VD_CACHE_NOT_UP_TO_DATE                (-3276)
+/** The given range does not meet the required alignment. */
+#define VERR_VD_DISCARD_ALIGNMENT_NOT_MET           (-3277)
+/** The discard operation is not supported for this image. */
+#define VERR_VD_DISCARD_NOT_SUPPORTED               (-3278)
 /** @} */
 

trunk/include/VBox/vd-plugin.h

@@ -4 +4 @@
 
 /*
- * Copyright (C) 2006-2010 Oracle Corporation
+ * Copyright (C) 2006-2011 Oracle Corporation
  *
  * This file is part of VirtualBox Open Source Edition (OSE), as
@@ -40 +40 @@
 /** @}*/
 
+/** @name VBox HDD backend discard flags
+ * @{
+ */
+/** Don't discard block but mark the given range as unused
+ * (usually by writing 0's to it).
+ * This doesn't require the range to be aligned on a block boundary but
+ * the image size might not be decreased. */
+#define VD_DISCARD_MARK_UNUSED RT_BIT(0)
+/** @}*/
+
 
 /**
@@ -540 +550 @@
      *
      * @returns VBox status code.
-     * @returns VERR_NOT_SUPPORTED if this image cannot be compacted yet.
+     * @returns VERR_NOT_SUPPORTED if this image cannot be resized yet.
      * @param   pBackendData    Opaque state data for this image.
      * @param   cbSize          New size of the image.
@@ -559 +569 @@
                                           PVDINTERFACE pVDIfsImage,
                                           PVDINTERFACE pVDIfsOperation));
+
+    /**
+     * Discards the given amount of bytes decreasing the size of the image if possible.
+     *
+     * @returns VBox status code.
+     * @retval  VERR_VD_DISCARD_ALIGNMENT_NOT_MET if the range doesn't meet the required alignment
+     *          for the discard.
+     * @param   pBackendData         Opaque state data for this image.
+     * @param   uOffset              The offset of the first byte to discard.
+     * @param   cbDiscard            How many bytes to discard.
+     * @param   pcbPreAllocated      Pointer to the returned amount of bytes that must
+     *                               be discarded before the range to perform a full
+     *                               block discard.
+     * @param   pcbPostAllocated     Pointer to the returned amount of bytes that must
+     *                               be discarded after the range to perform a full
+     *                               block discard.
+     * @param   pcbActuallyDiscarded Pointer to the returned amount of bytes which
+     *                               could be actually discarded.
+     * @param   ppbmAllocationBitmap Where to store the pointer to the allocation bitmap
+     *                               if VERR_VD_DISCARD_ALIGNMENT_NOT_MET is returned or NULL
+     *                               if the allocation bitmap should be returned.
+     * @param   fDiscard             Flags which affect discard behavior. Combination
+     *                               of the VD_DISCARD_* flags.
+     */
+    DECLR3CALLBACKMEMBER(int, pfnDiscard, (void *pBackendData,
+                                           uint64_t uOffset, size_t cbDiscard,
+                                           size_t *pcbPreAllocated,
+                                           size_t *pcbPostAllocated,
+                                           size_t *pcbActuallyDiscarded,
+                                           void   **ppbmAllocationBitmap,
+                                           unsigned fDiscard));
 
 } VBOXHDDBACKEND;

trunk/include/VBox/vd.h

@@ -4 +4 @@
 
 /*
- * Copyright (C) 2006-2010 Oracle Corporation
+ * Copyright (C) 2006-2011 Oracle Corporation
  *
  * This file is part of VirtualBox Open Source Edition (OSE), as
@@ -180 +180 @@
  * will not fail if it cannot do this, the flag will be simply ignored. */
 #define VD_OPEN_FLAGS_SEQUENTIAL    RT_BIT(6)
+/** Allow the discard operation if supported. Only available if VD_CAP_DISCARD
+ * is set. VDOpen fails with VERR_VD_DISCARD_NOT_SUPPORTED if discarding is not
+ * supported. */
+#define VD_OPEN_FLAGS_DISCARD       RT_BIT(7)
 /** Mask of valid flags. */
-#define VD_OPEN_FLAGS_MASK          (VD_OPEN_FLAGS_NORMAL | VD_OPEN_FLAGS_READONLY | VD_OPEN_FLAGS_HONOR_ZEROES | VD_OPEN_FLAGS_HONOR_SAME | VD_OPEN_FLAGS_INFO | VD_OPEN_FLAGS_ASYNC_IO | VD_OPEN_FLAGS_SHAREABLE | VD_OPEN_FLAGS_SEQUENTIAL)
+#define VD_OPEN_FLAGS_MASK          (VD_OPEN_FLAGS_NORMAL | VD_OPEN_FLAGS_READONLY | VD_OPEN_FLAGS_HONOR_ZEROES | VD_OPEN_FLAGS_HONOR_SAME | VD_OPEN_FLAGS_INFO | VD_OPEN_FLAGS_ASYNC_IO | VD_OPEN_FLAGS_SHAREABLE | VD_OPEN_FLAGS_SEQUENTIAL | VD_OPEN_FLAGS_DISCARD)
 /** @}*/
 
@@ -249 +253 @@
  * VDINTERFACEIO exclusively for all file operations. */
 #define VD_CAP_VFS                  RT_BIT(9)
+/** The backend supports the discard operation. */
+#define VD_CAP_DISCARD              RT_BIT(10)
 /** @}*/
 
@@ -392 +398 @@
 
 /**
+ * VD range descriptor.
+ */
+typedef struct VDRANGE
+{
+    /** Start offset in bytes, multiple of 512. */
+    uint64_t    offStart;
+    /** Amount of bytes described by this range, multiple of 512. */
+    size_t      cbRange;
+} VDRANGE;
+
+/** Pointer to a range descriptor. */
+typedef VDRANGE *PVDRANGE;
+/** Pointer to a constant range descriptor. */
+typedef const VDRANGE *PCVDRANGE;
+
+/**
  * VBox HDD Container main structure.
  */
@@ -1090 +1112 @@
 
 /**
+ * Discards unused ranges given as a list.
+ *
+ * @return  VBox status code.
+ * @param   pDisk           Pointer to HDD container.
+ * @param   paRanges        The array of ranges to discard.
+ * @param   cRanges         Number of entries in the array.
+ *
+ * @note In contrast to VDCompact() the ranges are always discarded even if they
+ *       appear to contain data. This method is mainly used to implement TRIM support.
+ */
+VBOXDDU_DECL(int) VDDiscardRanges(PVBOXHDD pDisk, PCVDRANGE paRanges, unsigned cRanges);
+
+
+/**
  * Start an asynchronous read request.
  *