PDMAsyncCompletionInternal.h revision 22ec733a5e041fcdfe02fce2eafc9faf8b0077dd
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * PDM - Pluggable Device Manager, Async I/O Completion internal header.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * Copyright (C) 2006-2008 Sun Microsystems, Inc.
010ad423d45c61ef874fa1602d46459a798b54d2vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
010ad423d45c61ef874fa1602d46459a798b54d2vboxsync * available from http://www.virtualbox.org. This file is free software;
010ad423d45c61ef874fa1602d46459a798b54d2vboxsync * you can redistribute it and/or modify it under the terms of the GNU
010ad423d45c61ef874fa1602d46459a798b54d2vboxsync * General Public License (GPL) as published by the Free Software
010ad423d45c61ef874fa1602d46459a798b54d2vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
010ad423d45c61ef874fa1602d46459a798b54d2vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
010ad423d45c61ef874fa1602d46459a798b54d2vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * Clara, CA 95054 USA or visit http://www.sun.com if you need
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * additional information or have any questions.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * Supported endpoint classes.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync /** File class. */
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync /** Number of supported classes. */
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync /** 32bit hack. */
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync PDMASYNCCOMPLETIONEPCLASSTYPE_32BIT_HACK = 0x7fffffff
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * PDM Async completion endpoint operations.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync /** Version identifier. */
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync /** Name of the endpoint class. */
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync const char *pcszName;
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync /** Class type. */
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync /** Size of the global endpoint class data in bytes. */
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync /** Size of an endpoint in bytes. */
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync /** size of a task in bytes. */
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * Initializes the global data for a endpoint class.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @returns VBox status code.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @param pClassGlobals Pointer to the uninitialized globals data.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @param pCfgNode Node for querying configuration data.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync DECLR3CALLBACKMEMBER(int, pfnInitialize, (PPDMASYNCCOMPLETIONEPCLASS pClassGlobals, PCFGMNODE pCfgNode));
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * Frees all allocated ressources which were allocated during init.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @returns VBox status code.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @param pClassGlobals Pointer to the globals data.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync DECLR3CALLBACKMEMBER(void, pfnTerminate, (PPDMASYNCCOMPLETIONEPCLASS pClassGlobals));
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * Initializes a given endpoint.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @returns VBox status code.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @param pEndpoint Pointer to the uninitialized endpoint.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @param pszUri Pointer to the string containing the endpoint
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * destination (filename, IP address, ...)
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @param fFlags Creation flags.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync DECLR3CALLBACKMEMBER(int, pfnEpInitialize, (PPDMASYNCCOMPLETIONENDPOINT pEndpoint,
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * Closes a endpoint finishing all tasks.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @returns VBox status code.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @param pEndpoint Pointer to the endpoint to be closed.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync DECLR3CALLBACKMEMBER(int, pfnEpClose, (PPDMASYNCCOMPLETIONENDPOINT pEndpoint));
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * Initiates a read request from the given endpoint.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @returns VBox status code.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @param pTask Pointer to the task object associated with the request.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @param pEndpoint Endpoint the request is for.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @param off Where to start reading from.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @param paSegments Scatter gather list to store the data in.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @param cSegments Number of segments in the list.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @param cbRead The overall number of bytes to read.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync DECLR3CALLBACKMEMBER(int, pfnEpRead, (PPDMASYNCCOMPLETIONTASK pTask,
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * Initiates a write request to the given endpoint.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @returns VBox status code.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @param pTask Pointer to the task object associated with the request.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @param pEndpoint Endpoint the request is for.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @param off Where to start writing to.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @param paSegments Scatter gather list to store the data in.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @param cSegments Number of segments in the list.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @param cbRead The overall number of bytes to write.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync DECLR3CALLBACKMEMBER(int, pfnEpWrite, (PPDMASYNCCOMPLETIONTASK pTask,
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * Initiates a flush request on the given endpoint.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @returns VBox status code.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @param pTask Pointer to the task object associated with the request.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @param pEndpoint Endpoint the request is for.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync DECLR3CALLBACKMEMBER(int, pfnEpFlush, (PPDMASYNCCOMPLETIONTASK pTask,
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * Queries the size of the endpoint. Optional.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @returns VBox status code.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @param pEndpoint Endpoint the request is for.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @param pcbSize Where to store the size of the endpoint.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync DECLR3CALLBACKMEMBER(int, pfnEpGetSize, (PPDMASYNCCOMPLETIONENDPOINT pEndpoint,
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * Sets the size of the endpoint. Optional.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * This is a synchronous operation.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @returns VBox status code.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @param pEndpoint Endpoint the request is for.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @param cbSize New size for the endpoint.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync DECLR3CALLBACKMEMBER(int, pfnEpSetSize, (PPDMASYNCCOMPLETIONENDPOINT pEndpoint,
a1e68eac9a1478fd1957826cb4bd631f808b7cc0vboxsync /** Initialization safety marker. */
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync/** Pointer to a async completion endpoint class operation table. */
d0eec04539061d14a7e51f492aea90fa5394615fvboxsynctypedef PDMASYNCCOMPLETIONEPCLASSOPS *PPDMASYNCCOMPLETIONEPCLASSOPS;
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync/** Const pointer to a async completion endpoint class operation table. */
d0eec04539061d14a7e51f492aea90fa5394615fvboxsynctypedef const PDMASYNCCOMPLETIONEPCLASSOPS *PCPDMASYNCCOMPLETIONEPCLASSOPS;
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync/** Version for the endpoint class operations structure. */
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * PDM Async completion endpoint class.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * Common data.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync /** Pointer to the shared VM structure. */
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync /** Critical section protecting the endpoint list. */
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync /** Number of endpoints in the list. */
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync volatile unsigned cEndpoints;
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync /** Head of endpoints with this class. */
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync R3PTRTYPE(PPDMASYNCCOMPLETIONENDPOINT) pEndpointsHead;
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync /** Pointer to the callback table. */
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync R3PTRTYPE(PCPDMASYNCCOMPLETIONEPCLASSOPS) pEndpointOps;
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync /** Task cache. */
a1e68eac9a1478fd1957826cb4bd631f808b7cc0vboxsync/** Pointer to the PDM async completion endpoint class data. */
a1e68eac9a1478fd1957826cb4bd631f808b7cc0vboxsynctypedef PDMASYNCCOMPLETIONEPCLASS *PPDMASYNCCOMPLETIONEPCLASS;
a1e68eac9a1478fd1957826cb4bd631f808b7cc0vboxsync * A PDM Async completion endpoint.
a1e68eac9a1478fd1957826cb4bd631f808b7cc0vboxsync * Common data.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync /** Next endpoint in the list. */
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync /** Previous endpoint in the list. */
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync /** Pointer to the class this endpoint belongs to. */
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync /** ID of the next task to ensure consistency. */
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync /** Flag whether a wraparound occurred for the ID counter. */
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync /** Template associated with this endpoint. */
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync /** Reference count. */
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync /** URI describing the endpoint */
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * A PDM async completion task handle.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * Common data.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync /** Next task in the list
a1e68eac9a1478fd1957826cb4bd631f808b7cc0vboxsync * (for free and assigned tasks). */
a1e68eac9a1478fd1957826cb4bd631f808b7cc0vboxsync /** Previous task in the list
a1e68eac9a1478fd1957826cb4bd631f808b7cc0vboxsync * (for free and assigned tasks). */
a1e68eac9a1478fd1957826cb4bd631f808b7cc0vboxsync /** Endpoint this task is assigned to. */
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync /** Opaque user data for this task. */
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync /** Task id. */
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync /** Start timestamp. */
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * Called by the endpoint if a task has finished.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @returns nothing
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @param pTask Pointer to the finished task.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @param rc Status code of the completed request.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * @param fCallCompletionHandler Flag whether the completion handler should be called to
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync * inform the owner of the task that it has completed.
d0eec04539061d14a7e51f492aea90fa5394615fvboxsyncvoid pdmR3AsyncCompletionCompleteTask(PPDMASYNCCOMPLETIONTASK pTask, int rc, bool fCallCompletionHandler);
d0eec04539061d14a7e51f492aea90fa5394615fvboxsyncextern const PDMASYNCCOMPLETIONEPCLASSOPS g_PDMAsyncCompletionEndpointClassFile;
d0eec04539061d14a7e51f492aea90fa5394615fvboxsync#endif /* __PDMAsyncCompletionInternal_h */