Changeset 10715 in vbox for trunk/include/VBox

Timestamp:

Jul 16, 2008 10:38:23 PM (16 years ago)

Author:

vboxsync

Message:

Merge async I/O for VMDK backend from private branch

Location:

trunk/include/VBox

Files:

• VBoxHDD-new.h (modified) (7 diffs)
• err.h (modified) (1 diff)
• pdmifs.h (modified) (15 diffs)
• types.h (modified) (1 diff)

trunk/include/VBox/VBoxHDD-new.h

@@ -178 +178 @@
  * used for querying information, and nothing else. */
 #define VD_OPEN_FLAGS_INFO          RT_BIT(3)
+/** Open image for asynchronous access.
+ *  Only available if VD_CAP_ASYNC_IO is set
+ *  Check with VDIsAsynchonousIoSupported wether
+ *  asynchronous I/O is really supported for this file.
+ */
+#define VD_OPEN_FLAGS_ASYNC_IO      RT_BIT(4)
 /** 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)
+#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)
 /** @}*/
 
@@ -196 +202 @@
 /** Supports being used as differencing image format backend. */
 #define VD_CAP_DIFF                 RT_BIT(4)
+/** Supports asynchronous I/O operations for at least some configurations. */
+#define VD_CAP_ASYNC                RT_BIT(5)
 /** The backend operates on files. The caller needs to know to handle the
  * location appropriately. */
 #define VD_CAP_FILE                 RT_BIT(6)
 /** @}*/
-
 
 /**
@@ -213 +220 @@
 } VDBACKENDINFO, *PVDBACKENDINFO;
 
-
-/**
- * Error message callback.
- *
- * @param   pvUser          The opaque data passed on container creation.
- * @param   rc              The VBox error code.
- * @param   RT_SRC_POS_DECL Use RT_SRC_POS.
- * @param   pszFormat       Error message format string.
- * @param   va              Error message arguments.
- */
-typedef DECLCALLBACK(void) FNVDERROR(void *pvUser, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va);
-/** Pointer to a FNVDERROR(). */
-typedef FNVDERROR *PFNVDERROR;
+/**
+ * Supported interface types.
+ */
+typedef enum VDINTERFACETYPE
+{
+    /** First valid interface. */
+    VDINTERFACETYPE_FIRST = 0,
+    /** Interface to pass error message to upper layers. */
+    VDINTERFACETYPE_ERROR = VDINTERFACETYPE_FIRST,
+    /** Interface for asynchronous I/O operations. */
+    VDINTERFACETYPE_ASYNCIO,
+    /** Interface for progress notification. */
+    VDINTERFACETYPE_PROGRESS,
+    /** invalid interface. */
+    VDINTERFACETYPE_INVALID
+} VDINTERFACETYPE;
+
+/**
+ * Common structure for all interfaces.
+ */
+typedef struct VDINTERFACE
+{
+    /** Human readable interface name. */
+    const char         *pszInterfaceName;
+    /** The size of the struct. */
+    uint32_t            cbSize;
+    /** Pointer to the next common interface structure. */
+    struct VDINTERFACE *pNext;
+    /** Interface type. */
+    VDINTERFACETYPE     enmInterface;
+    /** Opaque user data which is passed on every call. */
+    void               *pvUser;
+    /** Pointer to the function call table of the interface. 
+     *  As this is opaque this must be casted to the right interface
+     *  struct defined below based on the interface type in enmInterface. */
+    void               *pCallbacks;
+} VDINTERFACE, *PVDINTERFACE;
+/** Pointer to a const PVDINTERFACE. */
+typedef const PVDINTERFACE PCVDINTERFACE;
+
+/**
+ * Helper functions to handle interface lists.
+ */
+
+/**
+ * Get a specific interface from a list of interfaces specified by the type.
+ *
+ * @returns Pointer to the matching interface or NULL if none was found.
+ * @param   pInterfaces     Pointer to the first interface in the list.
+ * @param   enmInterface    Interface to search for.
+ */
+DECLINLINE(PVDINTERFACE) VDGetInterfaceFromList(PVDINTERFACE pInterfaces, VDINTERFACETYPE enmInterface)
+{
+    AssertMsgReturn(   (enmInterface >= VDINTERFACETYPE_FIRST)
+                    && (enmInterface < VDINTERFACETYPE_INVALID),
+                    ("enmInterface=%u", enmInterface), NULL);
+
+    while (pInterfaces)
+    {
+        /* Sanity checks. */
+        AssertMsgBreak(pInterfaces->cbSize == sizeof(VDINTERFACE),
+                       ("cbSize=%u\n", pInterfaces->cbSize));
+                       
+        if (pInterfaces->enmInterface == enmInterface)
+            return pInterfaces;
+        pInterfaces = pInterfaces->pNext;
+    }
+
+    /* No matching interface was found. */
+    return NULL;
+}
+
+/**
+ * Initialize a common interface structure.
+ *
+ * @return VBox status code.
+ * @param  pInterface   Pointer to an unitialized common interface structure.
+ * @param  pszName      Name of the interface.
+ * @param  enmInterface Type of the interface.
+ * @param  pCallbacks   The callback table of the interface.
+ * @param  pvUser       Opaque user data passed on every function call.
+ * @param  pNext        Pointer to the next supported interface if any.
+ */
+DECLINLINE(int) VDInterfaceCreate(PVDINTERFACE pInterface, const char *pszName,
+                                  VDINTERFACETYPE enmInterface, void *pCallbacks,
+                                  void *pvUser, PVDINTERFACE pNext)
+{
+
+    /** Argument checks. */
+    AssertMsgReturn(   (enmInterface >= VDINTERFACETYPE_FIRST)
+                    && (enmInterface < VDINTERFACETYPE_INVALID),
+                    ("enmInterface=%u", enmInterface), VERR_INVALID_PARAMETER);
+
+    AssertMsgReturn(VALID_PTR(pCallbacks),
+                    ("pCallbacks=%#p", pCallbacks),
+                    VERR_INVALID_PARAMETER);
+
+    pInterface->cbSize           = sizeof(VDINTERFACE);
+    pInterface->pszInterfaceName = pszName;
+    pInterface->enmInterface     = enmInterface;
+    pInterface->pCallbacks       = pCallbacks;
+    pInterface->pvUser           = pvUser;
+    pInterface->pNext            = pNext;
+    return VINF_SUCCESS;
+}
+
+/**
+ * Interface to deliver error messages to upper layers.
+ */
+typedef struct VDINTERFACEERROR
+{
+    /**
+     * Size of the error interface.
+     */
+    uint32_t    cbSize;
+
+    /**
+     * Interface type.
+     */
+    VDINTERFACETYPE enmInterface;
+
+    /**
+     * Error message callback.
+     *
+     * @param   pvUser          The opaque data passed on container creation.
+     * @param   rc              The VBox error code.
+     * @param   RT_SRC_POS_DECL Use RT_SRC_POS.
+     * @param   pszFormat       Error message format string.
+     * @param   va              Error message arguments.
+     */
+    DECLR3CALLBACKMEMBER(void, pfnError, (void *pvUser, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va));
+
+} VDINTERFACEERROR, *PVDINTERFACEERROR;
+
+/**
+ * Get error interface from opaque callback table.
+ *
+ * @return Pointer to the callback table.
+ * @param  pCallbacks Opaque interface pointer.
+ */
+DECLINLINE(PVDINTERFACEERROR) VDGetInterfaceError(void *pCallbacks)
+{
+    PVDINTERFACEERROR pInterfaceError = (PVDINTERFACEERROR)pCallbacks;
+
+    /* Do basic checks. */
+    AssertMsgReturn(   (pInterfaceError->cbSize == sizeof(VDINTERFACEERROR))
+                    && (pInterfaceError->enmInterface == VDINTERFACETYPE_ERROR),
+                    ("Not an error interface\n"), NULL);
+
+    return pInterfaceError;
+}
+
+/** 
+ * Completion callback which is called by the interface owner
+ * to inform the backend that a task finished.
+ * 
+ * @returns VBox status code.
+ * @param   pvUser          Opaque user data which is passed on request submission.
+ */
+typedef DECLCALLBACK(int) FNVDCOMPLETED(void *pvUser);
+/** Pointer to FNVDCOMPLETED() */
+typedef FNVDCOMPLETED *PFNVDCOMPLETED;
+
+
+/**
+ * Support interface for asynchronous I/O
+ */
+typedef struct VDINTERFACEASYNCIO
+{
+    /**
+     * Size of the async interface.
+     */
+    uint32_t    cbSize;
+
+    /**
+     * Interface type.
+     */
+    VDINTERFACETYPE enmInterface;
+
+    /**
+     * Open callback
+     *
+     * @returns VBox status code.
+     * @param   pvUser          The opaque data passed on container creation.
+     * @param   pszLocation     Name of the location to open.
+     * @param   fReadonly       Whether to open the storage medium read only.
+     * @param   ppStorage       Where to store the opaque storage handle.
+     */
+    DECLR3CALLBACKMEMBER(int, pfnOpen, (void *pvUser, const char *pszLocation, bool fReadonly, void **ppStorage));
+
+    /**
+     * Close callback.
+     *
+     * @returns VBox status code.
+     * @param   pvUser          The opaque data passed on container creation.
+     * @param   pStorage        The opaque storage handle to close.
+     */
+    DECLR3CALLBACKMEMBER(int, pfnClose, (void *pvUser, void *pStorage));
+
+    /**
+     * Synchronous write callback.
+     *
+     * @returns VBox status code.
+     * @param   pvUser          The opaque data passed on container creation.
+     * @param   pStorage        The storage handle to use.
+     * @param   uOffset         The offset to start from.
+     * @þaram   cbWrite         How many bytes to write.
+     * @param   pvBuf           Pointer to the bits need to be written.
+     * @param   pcbWritten      Where to store how many bytes where actually written.
+     */
+    DECLR3CALLBACKMEMBER(int, pfnWrite, (void *pvUser, void *pStorage, uint64_t uOffset, 
+                                         size_t cbWrite, const void *pvBuf, size_t *pcbWritten));
+
+    /**
+     * Synchronous read callback.
+     *
+     * @returns VBox status code.
+     * @param   pvUser          The opaque data passed on container creation.
+     * @param   pStorage        The storage handle to use.
+     * @param   uOffset         The offset to start from.
+     * @þaram   cbRead          How many bytes to read.
+     * @param   pvBuf           Where to store the read bits.
+     * @param   pcbRead         Where to store how many bytes where actually read.
+     */
+    DECLR3CALLBACKMEMBER(int, pfnRead, (void *pvUser, void *pStorage, uint64_t uOffset, 
+                                        size_t cbRead, void *pvBuf, size_t *pcbRead));
+
+    /**
+     * Flush data to the storage backend.
+     *
+     * @returns VBox statis code.
+     * @param   pvUser          The opaque data passed on container creation.
+     * @param   pStorage        The storage handle to flush.
+     */
+    DECLR3CALLBACKMEMBER(int, pfnFlush, (void *pvUser, void *pStorage));
+
+    /**
+     * Prepare an asynchronous read task.
+     *
+     * @returns VBox status code.
+     * @param   pvUser         The opqaue user data passed on container creation.
+     * @param   pStorage       The storage handle.
+     * @param   uOffset        The offset to start reading from.
+     * @param   pvBuf          Where to store read bits.
+     * @param   cbRead         How many bytes to read.
+     * @param   ppTask         Where to store the opaque task handle.
+     */
+    DECLR3CALLBACKMEMBER(int, pfnPrepareRead, (void *pvUser, void *pStorage, uint64_t uOffset, 
+                                               void *pvBuf, size_t cbRead, void **ppTask));
+
+    /**
+     * Prepare an asynchronous write task.
+     *
+     * @returns VBox status code.
+     * @param   pvUser         The opaque user data passed on conatiner creation.
+     * @param   pStorage       The storage handle.
+     * @param   uOffset        The offset to start writing to.
+     * @param   pvBuf          Where to read the data from.
+     * @param   cbWrite        How many bytes to write.
+     * @param   ppTask         Where to store the opaque task handle.
+     */
+    DECLR3CALLBACKMEMBER(int, pfnPrepareWrite, (void *pvUser, void *pStorage, uint64_t uOffset, 
+                                                void *pvBuf, size_t cbWrite, void **ppTask));
+
+    /**
+     * Submit an array of tasks for processing
+     *
+     * @returns VBox status code.
+     * @param   pvUser        The opaque user data passed on container creation.
+     * @param   apTasks       Array of task handles to submit.
+     * @param   cTasks        How many tasks to submit.
+     * @param   pvUser2       User data which is passed on completion.
+     * @param   pvUserCaller  Opaque user data the caller of VDAsyncWrite/Read passed.
+     * @param   pfnTasksCompleted Pointer to callback which is called on request completion.
+     */
+    DECLR3CALLBACKMEMBER(int, pfnTasksSubmit, (void *pvUser, void *apTasks[], unsigned cTasks, void *pvUser2,
+                                               void *pvUserCaller, PFNVDCOMPLETED pfnTasksCompleted));
+
+} VDINTERFACEASYNCIO, *PVDINTERFACEASYNCIO;
+
+/**
+ * Get async I/O interface from opaque callback table.
+ *
+ * @return Pointer to the callback table.
+ * @param  pCallbacks Opaque interface pointer.
+ */
+DECLINLINE(PVDINTERFACEASYNCIO) VDGetInterfaceAsyncIO(void *pCallbacks)
+{
+    PVDINTERFACEASYNCIO pInterfaceAsyncIO = (PVDINTERFACEASYNCIO)pCallbacks;
+
+    /* Do basic checks. */
+    AssertMsgReturn(   (pInterfaceAsyncIO->cbSize == sizeof(VDINTERFACEASYNCIO))
+                    && (pInterfaceAsyncIO->enmInterface == VDINTERFACETYPE_ASYNCIO),
+                    ("Not an async I/O interface\n"), NULL);
+
+    return pInterfaceAsyncIO;
+}
+
+/**
+ * Progress notification interface
+ */
+typedef struct VDINTERFACEPROGRESS
+{
+    /**
+     * Size of the progress interface.
+     */
+    uint32_t    cbSize;
+
+    /**
+     * Interface type.
+     */
+    VDINTERFACETYPE enmInterface;
+
+    /**
+     * Progress notification callbacks.
+     */
+    PFNVMPROGRESS   pfnProgress;
+} VDINTERFACEPROGRESS, *PVDINTERFACEPROGRESS;
+
+/**
+ * Get progress interface from opaque callback table.
+ *
+ * @return Pointer to the callback table.
+ * @param  pCallbacks Opaque interface pointer.
+ */
+DECLINLINE(PVDINTERFACEPROGRESS) VDGetInterfaceProgress(void *pCallbacks)
+{
+    PVDINTERFACEPROGRESS pInterfaceProgress = (PVDINTERFACEPROGRESS)pCallbacks;
+
+    /* Do basic checks. */
+    AssertMsgReturn(   (pInterfaceProgress->cbSize == sizeof(VDINTERFACEPROGRESS))
+                    && (pInterfaceProgress->enmInterface == VDINTERFACETYPE_PROGRESS),
+                    ("Not an progress notification interface\n"), NULL);
+
+    return pInterfaceProgress;
+}
 
 
@@ -250 +580 @@
                                 unsigned *pcEntriesUsed);
 
+/**
+ * Lists the capablities of a backend indentified by its name.
+ * Free all returned names with RTStrFree() when you no longer need them.
+ *
+ * @returns VBox status code.
+ * @param   pszBackend      The backend name.
+ * @param   pEntries        Pointer to an entry.
+ */
+VBOXDDU_DECL(int) VDBackendInfoOne(const char *pszBackend, PVDBACKENDINFO pEntry);
 
 /**
@@ -256 +595 @@
  *
  * @returns VBox status code.
- * @param   pfnError        Callback for setting extended error information.
- * @param   pvErrorUser     Opaque parameter for pfnError.
+ * @param   pInterfaces     Pointer to the first supported interface.
  * @param   ppDisk          Where to store the reference to HDD container.
  */
-VBOXDDU_DECL(int) VDCreate(PFNVDERROR pfnError, void *pvErrorUser,
-                           PVBOXHDD *ppDisk);
+VBOXDDU_DECL(int) VDCreate(PVDINTERFACE pInterfaces, PVBOXHDD *ppDisk);
 
 /**
@@ -559 +896 @@
 
 /**
+ * List the capabilities of image backend in HDD container.
+ *
+ * @returns VBox status code.
+ * @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
+ * @param   pDisk           Pointer to the HDD container.
+ * @param   nImage          Image number, counts from 0. 0 is always base image of container.
+ * @param   pbackendInfo    Where to store the backend information.
+ */
+VBOXDDU_DECL(int) VDBackendInfoSingle(PVBOXHDD pDisk, unsigned nImage,
+                                      PVDBACKENDINFO pBackendInfo);
+
+/**
  * Get flags of image in HDD container.
  *
@@ -714 +1063 @@
 VBOXDDU_DECL(void) VDDumpImages(PVBOXHDD pDisk);
 
+
+/**
+ * Query if asynchronous operations are supported for this disk.
+ *
+ * @returns VBox status code.
+ * @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
+ * @param   pDisk           Pointer to the HDD container.
+ * @param   nImage          Image number, counts from 0. 0 is always base image of container.
+ * @param   pfAIOSupported  Where to store if async IO is supported.
+ */
+VBOXDDU_DECL(int) VDImageIsAsyncIOSupported(PVBOXHDD pDisk, unsigned nImage, bool *pfAIOSupported);
+
+
+/**
+ * Start a asynchronous read request.
+ *
+ * @returns VBox status code.
+ * @param   pDisk           Pointer to the HDD container.
+ * @param   uOffset         The offset of the virtual disk to read from.
+ * @param   cbRead          How many bytes to read.
+ * @param   paSeg           Pointer to an array of segments.
+ * @param   cSeg            Number of segments in the array.
+ * @param   pvUser          User data which is passed on completion
+ */
+VBOXDDU_DECL(int) VDAsyncRead(PVBOXHDD pDisk, uint64_t uOffset, size_t cbRead, 
+                              PPDMDATASEG paSeg, unsigned cSeg,
+                              void *pvUser);
+
+
+/**
+ * Start a asynchronous write request.
+ *
+ * @returns VBox status code.
+ * @param   pDisk           Pointer to the HDD container.
+ * @param   uOffset         The offset of the virtual disk to write to.
+ * @param   cbWrtie         How many bytes to write.
+ * @param   paSeg           Pointer to an array of segments.
+ * @param   cSeg            Number of segments in the array.
+ * @param   pvUser          User data which is passed on completion.
+ */
+VBOXDDU_DECL(int) VDAsyncWrite(PVBOXHDD pDisk, uint64_t uOffset, size_t cbWrite,
+                               PPDMDATASEG paSeg, unsigned cSeg,
+                               void *pvUser);
+
+
 __END_DECLS
 

trunk/include/VBox/err.h

@@ -1049 +1049 @@
 /** Configuration value not found. */
 #define VERR_VDI_VALUE_NOT_FOUND                    (-3216)
+/** Asynchronous I/O request finished. */
+#define VINF_VDI_ASYNC_IO_FINISHED                  3218
+/** Asynchronous I/O is not finished yet. */
+#define VERR_VDI_ASYNC_IO_IN_PROGRESS               (-3219)
 /** @} */
 

trunk/include/VBox/pdmifs.h

@@ -1115 +1115 @@
 
 
-/**
- * Data transport buffer (scatter/gather)
- */
-typedef struct PDMIDATATRANSPORTSEG
-{
-    /** Length of buffer in entry. */
-    size_t  cbSeg;
-    /** Pointer to the start of the buffer. */
-    void   *pvSeg;
-} PDMIDATATRANSPORTSEG;
-/** Pointer to a data transport segment. */
-typedef PDMIDATATRANSPORTSEG *PPDMIDATATRANSPORTSEG;
-/** Pointer to a const data transport segment. */
-typedef PDMIDATATRANSPORTSEG const *PCPDMIDATATRANSPORTSEG;
-
-
 /** Pointer to an asynchronous iSCSI transport driver interface. */
 typedef struct PDMIISCSITRANSPORTASYNC *PPDMIISCSITRANSPORTASYNC;
@@ -1207 +1191 @@
 {
     /**
-     * Notify completion of a read task.
-     *
-     * @returns VBox status code.
-     * @param   pInterface      Pointer to the interface structure containing the called function pointer.
-     * @param   off             Offset the task read from.
-     * @param   pSeg            Pointer to the first element in the gather list.
-     * @param   cSeg            Number of segments in the gather list.
-     * @param   cbRead          Number of bytes read.
-     * @param   pvUser          The user argument given in pfnStartRead.
-     * @thread  Any thread.
-     */
-    DECLR3CALLBACKMEMBER(int, pfnReadCompleteNotify, (PPDMIBLOCKASYNCPORT pInterface, uint64_t off, PPDMIDATATRANSPORTSEG pSeg, unsigned cSeg, size_t cbRead, void *pvUser));
-
-    /**
-     * Notify completion of a write task.
-     *
-     * @returns VBox status code.
-     * @param   pInterface      Pointer to the interface structure containing the called function pointer.
-     * @param   off             Offset the task has written to.
-     * @param   pSeg            Pointer to the first element in the scatter list.
-     * @param   cSeg            Number of segments in the scatter list.
-     * @param   cbWritten       Number of bytes actually written.
-     * @param   pvUser          The user argument given in pfnStartWrite.
-     * @thread  Any thread.
-     */
-    DECLR3CALLBACKMEMBER(int, pfnWriteCompleteNotify, (PPDMIBLOCKASYNCPORT pInterface, uint64_t off, PPDMIDATATRANSPORTSEG pSeg, unsigned cSeg, size_t cbWritten, void *pvUser));
+     * Notify completion of a asynchronous transfer.
+     *
+     * @returns VBox status code.
+     * @param   pInterface      Pointer to the interface structure containing the called function pointer.
+     * @param   pvUser          The user argument given in pfnStartWrite/Read.
+     * @thread  Any thread.
+     */
+    DECLR3CALLBACKMEMBER(int, pfnTransferCompleteNotify, (PPDMIBLOCKASYNCPORT pInterface, void *pvUser));
 } PDMIBLOCKASYNCPORT;
 
@@ -1256 +1222 @@
      * @thread  Any thread.
      */
-    DECLR3CALLBACKMEMBER(int, pfnStartRead,(PPDMIBLOCKASYNC pInterface, uint64_t off, PPDMIDATATRANSPORTSEG pSeg, unsigned cSeg, size_t cbRead, void *pvUser));
+    DECLR3CALLBACKMEMBER(int, pfnStartRead,(PPDMIBLOCKASYNC pInterface, uint64_t off, PPDMDATASEG pSeg, unsigned cSeg, size_t cbRead, void *pvUser));
 
     /**
@@ -1270 +1236 @@
      * @thread  Any thread.
      */
-    DECLR3CALLBACKMEMBER(int, pfnStartWrite,(PPDMIBLOCKASYNC pInterface, uint64_t off, PPDMIDATATRANSPORTSEG pSeg, unsigned cSeg, size_t cbWrite, void *pvUser));
+    DECLR3CALLBACKMEMBER(int, pfnStartWrite,(PPDMIBLOCKASYNC pInterface, uint64_t off, PPDMDATASEG pSeg, unsigned cSeg, size_t cbWrite, void *pvUser));
 
 } PDMIBLOCKASYNC;
@@ -1284 +1250 @@
 {
     /**
-     * Notify completion of a read task.
-     *
-     * @returns VBox status code.
-     * @param   pInterface      Pointer to the interface structure containing the called function pointer.
-     * @param   off             Offset the task read from.
-     * @param   pSeg            Pointer to the first element in the scatter list.
-     * @param   cSeg            Number of entries in the list.
-     * @param   cbRead          Number of bytes read.
-     * @param   pvUser          The user argument given in pfnStartRead.
-     * @thread  Any thread.
-     */
-    DECLR3CALLBACKMEMBER(int, pfnReadCompleteNotify, (PPDMIMEDIAASYNCPORT pInterface, uint64_t off, PPDMIDATATRANSPORTSEG pSeg, unsigned cSeg, size_t cbRead, void *pvUser));
-
-    /**
-     * Notify completion of a write task.
-     *
-     * @returns VBox status code.
-     * @param   pInterface      Pointer to the interface structure containing the called function pointer.
-     * @param   off             Offset the task has written to.
-     * @param   pSeg            Pointer to the first element in the gather list.
-     * @param   cSeg            Number of entries in the list.
-     * @param   cbWritten       Number of bytes actually written.
+     * Notify completion of a task.
+     *
+     * @returns VBox status code.
+     * @param   pInterface      Pointer to the interface structure containing the called function pointer.
      * @param   pvUser          The user argument given in pfnStartWrite.
      * @thread  Any thread.
      */
-    DECLR3CALLBACKMEMBER(int, pfnWriteCompleteNotify, (PPDMIMEDIAASYNCPORT pInterface, uint64_t off, PPDMIDATATRANSPORTSEG pSeg, unsigned cSeg, size_t cbWritten, void *pvUser));
+    DECLR3CALLBACKMEMBER(int, pfnTransferCompleteNotify, (PPDMIMEDIAASYNCPORT pInterface, void *pvUser));
 } PDMIMEDIAASYNCPORT;
 
@@ -1333 +1281 @@
      * @thread  Any thread.
      */
-    DECLR3CALLBACKMEMBER(int, pfnStartRead,(PPDMIMEDIAASYNC pInterface, uint64_t off, PPDMIDATATRANSPORTSEG pSeg, unsigned cSeg, size_t cbRead, void *pvUser));
+    DECLR3CALLBACKMEMBER(int, pfnStartRead,(PPDMIMEDIAASYNC pInterface, uint64_t off, PPDMDATASEG pSeg, unsigned cSeg, size_t cbRead, void *pvUser));
 
     /**
@@ -1347 +1295 @@
      * @thread  Any thread.
      */
-    DECLR3CALLBACKMEMBER(int, pfnStartWrite,(PPDMIMEDIAASYNC pInterface, uint64_t off, PPDMIDATATRANSPORTSEG pSeg, unsigned cSeg, size_t cbWrite, void *pvUser));
+    DECLR3CALLBACKMEMBER(int, pfnStartWrite,(PPDMIMEDIAASYNC pInterface, uint64_t off, PPDMDATASEG pSeg, unsigned cSeg, size_t cbWrite, void *pvUser));
 
 } PDMIMEDIAASYNC;
@@ -1361 +1309 @@
 {
     /**
-     * Notify completion of a read task.
-     *
-     * @returns VBox status code.
-     * @param   pInterface      Pointer to the interface structure containing the called function pointer.
-     * @param   off             Offset the task read from.
-     * @param   pSeg            Pointer to the first element in the scatter list.
-     * @param   cSeg            Number of entries in the list.
-     * @param   cbRead          Number of bytes read.
-     * @param   pvUser          The user argument given in pfnStartRead.
-     * @thread  Any thread.
-     */
-    DECLR3CALLBACKMEMBER(int, pfnReadCompleteNotify, (PPDMITRANSPORTASYNCPORT pInterface, uint64_t off, PPDMIDATATRANSPORTSEG pSeg, unsigned cSeg,
-                                                      size_t cbRead, void *pvUser));
-
-    /**
-     * Notify completion of a write task.
-     *
-     * @returns VBox status code.
-     * @param   pInterface      Pointer to the interface structure containing the called function pointer.
-     * @param   off             Offset the task has written to.
-     * @param   pSeg            Pointer to the first element in the gather list.
-     * @param   cSeg            Number of entries in the list.
-     * @param   cbWritten       Number of bytes actually written.
-     * @param   pvUser          The user argument given in pfnStartWrite.
-     * @thread  Any thread.
-     */
-    DECLR3CALLBACKMEMBER(int, pfnWriteCompleteNotify, (PPDMITRANSPORTASYNCPORT pInterface, uint64_t off, PPDMIDATATRANSPORTSEG pSeg, unsigned cSeg,
-                                                       size_t cbWritten, void *pvUser));
+     * Notify completion of tasks.
+     *
+     * @returns VBox status code.
+     * @param   pInterface      Pointer to the interface structure containing the called function pointer.
+     * @param   pvUser          The user argument given in pfnTasksSubmit.
+     * @thread  Any thread.
+     */
+    DECLR3CALLBACKMEMBER(int, pfnTaskCompleteNotify, (PPDMITRANSPORTASYNCPORT pInterface, void *pvUser));
+
 } PDMITRANSPORTASYNCPORT;
 
@@ -1406 +1335 @@
      * @returns VBox status code.
      * @param   pInterface      Pointer to the interface structure containint the called function pointer.
+     * @param   pStorage        The storage handle to read from.
      * @param   off             Offset to start reading from.
-     * @param   pvBuf           here to store the read bits.
+     * @param   pvBuf           Where to store the read bits.
      * @param   cbRead          Number of bytes to read.
      * @param   pcbRead         Where to store the number of bytes actually read.
      * @thread  Any thread.
      */
-    DECLR3CALLBACKMEMBER(int, pfnReadSynchronous, (PPDMITRANSPORTASYNC pInterface, uint64_t off, void *pvBuf, size_t cbRead, size_t *pcbRead));
+    DECLR3CALLBACKMEMBER(int, pfnReadSynchronous, (PPDMITRANSPORTASYNC pInterface, void *pStorage,
+                                                   uint64_t off, void *pvBuf, size_t cbRead, size_t *pcbRead));
 
     /**
@@ -1420 +1351 @@
      * @returns VBox status code.
      * @param   pInterface      Pointer to the interface structure containint the called function pointer.
+     * @param   pStorage        The storage handle to write to.
      * @param   off             Offset to start reading from.
-     * @param   pvBuf           here to store the read bits.
+     * @param   pvBuf           Pointer to the buffer which contains the data to write.
      * @param   cbWrite         Number of bytes to read.
      * @param   pcbWritten      Where to store the number of bytes actually read.
      * @thread  Any thread.
      */
-    DECLR3CALLBACKMEMBER(int, pfnWriteSynchronous, (PPDMITRANSPORTASYNC pInterface, uint64_t off, void *pvBuf, size_t cbWrite, size_t *pcbWritten));
-
-    /**
-     * Start asynchronous read.
-     *
-     * @returns VBox status code.
-     * @param   pInterface      Pointer to the interface structure containing the called function pointer.
-     * @param   off             Offset to start reading from.
-     * @param   pSeg            Pointer to the first element in the scatter list.
-     * @param   cSeg            Number of entries in the list.
-     * @param   cbRead          Number of bytes to read.
-     * @param   pvUser          User argument returned in completion callback.
-     * @thread  Any thread.
-     */
-    DECLR3CALLBACKMEMBER(int, pfnReadStartAsynchronous,(PPDMITRANSPORTASYNC pInterface, uint64_t off, PPDMIDATATRANSPORTSEG pSeg, unsigned cSeg,
-                                                        size_t cbRead, void *pvUser));
-
-    /**
-     * Start asynchronous write.
-     *
-     * @returns VBox status code.
-     * @param   pInterface      Pointer to the interface structure containing the called function pointer.
-     * @param   off             Offset to start writing at.
-     * @param   pSeg            Pointer to the first element in the gather list.
-     * @param   cSeg            Number of entries in the list.
-     * @param   cbWrite         Number of bytes to write.
-     * @param   pvUser          User argument returned in completion callback.
-     * @thread  Any thread.
-     */
-    DECLR3CALLBACKMEMBER(int, pfnWriteStartAsynchronous,(PPDMITRANSPORTASYNC pInterface, uint64_t off, PPDMIDATATRANSPORTSEG pSeg, unsigned cSeg,
-                                                         size_t cbWrite, void *pvUser));
+    DECLR3CALLBACKMEMBER(int, pfnWriteSynchronous, (PPDMITRANSPORTASYNC pInterface, void *pStorage,
+                                                    uint64_t off, const void *pvBuf, size_t cbWrite, size_t *pcbWritten));
 
     /**
@@ -1464 +1367 @@
      * @returns VBox status code.
      * @param   pInterface      Pointer to the interface structure containing the called function pointer.
-     * @thread  Any thread.
-     */
-    DECLR3CALLBACKMEMBER(int, pfnFlushSynchronous,(PPDMITRANSPORTASYNC pInterface));
+     * @param   pStorage        The storage handle to flush-
+     * @thread  Any thread.
+     */
+    DECLR3CALLBACKMEMBER(int, pfnFlushSynchronous,(PPDMITRANSPORTASYNC pInterface, void *pStorage));
 
     /**
@@ -1473 +1377 @@
      * @returns Media size in bytes.
      * @param   pInterface      Pointer to the interface structure containing the called function pointer.
-     * @thread  Any thread.
-     */
-    DECLR3CALLBACKMEMBER(uint64_t, pfnGetSize,(PPDMITRANSPORTASYNC pInterface));
+     * @param   pStorage        The storage handle.
+     * @thread  Any thread.
+     */
+    DECLR3CALLBACKMEMBER(uint64_t, pfnGetSize,(PPDMITRANSPORTASYNC pInterface, void *pStorage));
 
     /**
@@ -1483 +1388 @@
      * @returns false if read/write.
      * @param   pInterface      Pointer to the interface structure containing the called function pointer.
-     * @thread  Any thread.
-     */
-    DECLR3CALLBACKMEMBER(bool, pfnIsReadOnly,(PPDMITRANSPORTASYNC pInterface));
+     * @param   pStorage        The storage handle.
+     * @thread  Any thread.
+     */
+    DECLR3CALLBACKMEMBER(bool, pfnIsReadOnly,(PPDMITRANSPORTASYNC pInterface, void *pStorage));
 
     /**
@@ -1494 +1400 @@
      * @param   pszPath         The path to open.
      * @param   fReadonly       If the target shoudl opened readonly.
-     * @thread  Any thread.
-     */
-    DECLR3CALLBACKMEMBER(int, pfnOpen, (PPDMITRANSPORTASYNC pInterface, const char *pszTargetPath, bool fReadonly));
+     * @param   ppStorage       Where to store the storage handle.
+     * @thread  Any thread.
+     */
+    DECLR3CALLBACKMEMBER(int, pfnOpen, (PPDMITRANSPORTASYNC pInterface, const char *pszTargetPath, bool fReadonly, void **ppStorage));
 
     /**
@@ -1503 +1410 @@
      * @returns VBox status code.
      * @param   pInterface      Pointer to the interface structure containing the called function pointer.
-     * @thread  Any thread.
-     */
-    DECLR3CALLBACKMEMBER(int, pfnClose, (PPDMITRANSPORTASYNC pInterface));
-
+     * @param   pStorage        The storage handle to close.
+     * @thread  Any thread.
+     */
+    DECLR3CALLBACKMEMBER(int, pfnClose, (PPDMITRANSPORTASYNC pInterface, void *pStorage));
+
+    /**
+     * Prepare an asynchronous read task.
+     *
+     * @returns VBox status code.
+     * @param   pInterface     Pointer to the interface structure containing the called function pointer.
+     * @param   pStorage       The storage handle.
+     * @param   uOffset        The offset to start reading from.
+     * @param   pvBuf          Where to store read bits.
+     * @param   cbRead         How many bytes to read.
+     * @param   ppTask         Where to store the opaque task handle.
+     */
+    DECLR3CALLBACKMEMBER(int, pfnPrepareRead, (PPDMITRANSPORTASYNC pInterface, void *pStorage, uint64_t uOffset, 
+                                               void *pvBuf, size_t cbRead, void **ppTask));
+
+    /**
+     * Prepare an asynchronous write task.
+     *
+     * @returns VBox status code.
+     * @param   pInterface     Pointer to the interface structure containing the called function pointer.
+     * @param   pStorage       The storage handle.
+     * @param   uOffset        The offset to start writing to.
+     * @param   pvBuf          Where to read the data from.
+     * @param   cbWrite        How many bytes to write.
+     * @param   ppTask         Where to store the opaque task handle.
+     */
+    DECLR3CALLBACKMEMBER(int, pfnPrepareWrite, (PPDMITRANSPORTASYNC pInterface, void *pStorage, uint64_t uOffset, 
+                                                void *pvBuf, size_t cbWrite, void **ppTask));
+
+    /**
+     * Submit an array of tasks for processing
+     *
+     * @returns VBox status code.
+     * @param   pInterface    Pointer to the interface structure containing the called function pointer.
+     * @param   apTasks       Array of task handles to submit.
+     * @param   cTasks        How many tasks to submit.
+     * @param   pvUser        User data which is passed on completion.
+     */
+    DECLR3CALLBACKMEMBER(int, pfnTasksSubmit, (PPDMITRANSPORTASYNC pInterface, void *apTasks[], unsigned cTasks, void *pvUser));
 } PDMITRANSPORTASYNC;
 

trunk/include/VBox/types.h

@@ -508 +508 @@
 typedef const PDMMAC *PCPDMMAC;
 
+/**
+ * Data transport buffer (scatter/gather)
+ */
+typedef struct PDMDATASEG
+{
+    /** Length of buffer in entry. */
+    size_t  cbSeg;
+    /** Pointer to the start of the buffer. */
+    void   *pvSeg;
+} PDMDATASEG;
+/** Pointer to a data transport segment. */
+typedef PDMDATASEG *PPDMDATASEG;
+/** Pointer to a const data transport segment. */
+typedef PDMDATASEG const *PCPDMDATASEG;
 
 /** @} */