VirtualBox

source: vbox/trunk/src/VBox/VMM/include/PDMAsyncCompletionInternal.h@ 41777

Last change on this file since 41777 was 41777, checked in by vboxsync, 13 years ago

Doxygen.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 10.9 KB
Line 
1/* $Id: PDMAsyncCompletionInternal.h 41777 2012-06-16 18:49:15Z vboxsync $ */
2/** @file
3 * PDM - Pluggable Device Manager, Async I/O Completion internal header.
4 */
5
6/*
7 * Copyright (C) 2006-2010 Oracle Corporation
8 *
9 * This file is part of VirtualBox Open Source Edition (OSE), as
10 * available from http://www.virtualbox.org. This file is free software;
11 * you can redistribute it and/or modify it under the terms of the GNU
12 * General Public License (GPL) as published by the Free Software
13 * Foundation, in version 2 as it comes in the "COPYING" file of the
14 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16 */
17
18#ifndef ___PDMAsyncCompletionInternal_h
19#define ___PDMAsyncCompletionInternal_h
20
21#include <iprt/critsect.h>
22#include <iprt/memcache.h>
23#include <iprt/sg.h>
24#include <VBox/types.h>
25#include <VBox/vmm/cfgm.h>
26#include <VBox/vmm/stam.h>
27#include <VBox/vmm/pdmasynccompletion.h>
28#include "PDMInternal.h"
29
30RT_C_DECLS_BEGIN
31
32
33/**
34 * PDM Async completion endpoint operations.
35 */
36typedef struct PDMASYNCCOMPLETIONEPCLASSOPS
37{
38 /** Version identifier. */
39 uint32_t u32Version;
40 /** Name of the endpoint class. */
41 const char *pcszName;
42 /** Class type. */
43 PDMASYNCCOMPLETIONEPCLASSTYPE enmClassType;
44 /** Size of the global endpoint class data in bytes. */
45 size_t cbEndpointClassGlobal;
46 /** Size of an endpoint in bytes. */
47 size_t cbEndpoint;
48 /** size of a task in bytes. */
49 size_t cbTask;
50
51 /**
52 * Initializes the global data for a endpoint class.
53 *
54 * @returns VBox status code.
55 * @param pClassGlobals Pointer to the uninitialized globals data.
56 * @param pCfgNode Node for querying configuration data.
57 */
58 DECLR3CALLBACKMEMBER(int, pfnInitialize, (PPDMASYNCCOMPLETIONEPCLASS pClassGlobals, PCFGMNODE pCfgNode));
59
60 /**
61 * Frees all allocated resources which were allocated during init.
62 *
63 * @returns VBox status code.
64 * @param pClassGlobals Pointer to the globals data.
65 */
66 DECLR3CALLBACKMEMBER(void, pfnTerminate, (PPDMASYNCCOMPLETIONEPCLASS pClassGlobals));
67
68 /**
69 * Initializes a given endpoint.
70 *
71 * @returns VBox status code.
72 * @param pEndpoint Pointer to the uninitialized endpoint.
73 * @param pszUri Pointer to the string containing the endpoint
74 * destination (filename, IP address, ...)
75 * @param fFlags Creation flags.
76 */
77 DECLR3CALLBACKMEMBER(int, pfnEpInitialize, (PPDMASYNCCOMPLETIONENDPOINT pEndpoint,
78 const char *pszUri, uint32_t fFlags));
79
80 /**
81 * Closes a endpoint finishing all tasks.
82 *
83 * @returns VBox status code.
84 * @param pEndpoint Pointer to the endpoint to be closed.
85 */
86 DECLR3CALLBACKMEMBER(int, pfnEpClose, (PPDMASYNCCOMPLETIONENDPOINT pEndpoint));
87
88 /**
89 * Initiates a read request from the given endpoint.
90 *
91 * @returns VBox status code.
92 * @param pTask Pointer to the task object associated with the request.
93 * @param pEndpoint Endpoint the request is for.
94 * @param off Where to start reading from.
95 * @param paSegments Scatter gather list to store the data in.
96 * @param cSegments Number of segments in the list.
97 * @param cbRead The overall number of bytes to read.
98 */
99 DECLR3CALLBACKMEMBER(int, pfnEpRead, (PPDMASYNCCOMPLETIONTASK pTask,
100 PPDMASYNCCOMPLETIONENDPOINT pEndpoint, RTFOFF off,
101 PCRTSGSEG paSegments, size_t cSegments,
102 size_t cbRead));
103
104 /**
105 * Initiates a write request to the given endpoint.
106 *
107 * @returns VBox status code.
108 * @param pTask Pointer to the task object associated with the request.
109 * @param pEndpoint Endpoint the request is for.
110 * @param off Where to start writing to.
111 * @param paSegments Scatter gather list to store the data in.
112 * @param cSegments Number of segments in the list.
113 * @param cbRead The overall number of bytes to write.
114 */
115 DECLR3CALLBACKMEMBER(int, pfnEpWrite, (PPDMASYNCCOMPLETIONTASK pTask,
116 PPDMASYNCCOMPLETIONENDPOINT pEndpoint, RTFOFF off,
117 PCRTSGSEG paSegments, size_t cSegments,
118 size_t cbWrite));
119
120 /**
121 * Initiates a flush request on the given endpoint.
122 *
123 * @returns VBox status code.
124 * @param pTask Pointer to the task object associated with the request.
125 * @param pEndpoint Endpoint the request is for.
126 */
127 DECLR3CALLBACKMEMBER(int, pfnEpFlush, (PPDMASYNCCOMPLETIONTASK pTask,
128 PPDMASYNCCOMPLETIONENDPOINT pEndpoint));
129
130 /**
131 * Queries the size of the endpoint. Optional.
132 *
133 * @returns VBox status code.
134 * @param pEndpoint Endpoint the request is for.
135 * @param pcbSize Where to store the size of the endpoint.
136 */
137 DECLR3CALLBACKMEMBER(int, pfnEpGetSize, (PPDMASYNCCOMPLETIONENDPOINT pEndpoint,
138 uint64_t *pcbSize));
139
140 /**
141 * Sets the size of the endpoint. Optional.
142 * This is a synchronous operation.
143 *
144 *
145 * @returns VBox status code.
146 * @param pEndpoint Endpoint the request is for.
147 * @param cbSize New size for the endpoint.
148 */
149 DECLR3CALLBACKMEMBER(int, pfnEpSetSize, (PPDMASYNCCOMPLETIONENDPOINT pEndpoint,
150 uint64_t cbSize));
151
152 /** Initialization safety marker. */
153 uint32_t u32VersionEnd;
154} PDMASYNCCOMPLETIONEPCLASSOPS;
155/** Pointer to a async completion endpoint class operation table. */
156typedef PDMASYNCCOMPLETIONEPCLASSOPS *PPDMASYNCCOMPLETIONEPCLASSOPS;
157/** Const pointer to a async completion endpoint class operation table. */
158typedef const PDMASYNCCOMPLETIONEPCLASSOPS *PCPDMASYNCCOMPLETIONEPCLASSOPS;
159
160/** Version for the endpoint class operations structure. */
161#define PDMAC_EPCLASS_OPS_VERSION 0x00000001
162
163/** Pointer to a bandwidth control manager. */
164typedef struct PDMACBWMGR *PPDMACBWMGR;
165
166/**
167 * PDM Async completion endpoint class.
168 * Common data.
169 */
170typedef struct PDMASYNCCOMPLETIONEPCLASS
171{
172 /** Pointer to the VM. */
173 PVM pVM;
174 /** Critical section protecting the lists below. */
175 RTCRITSECT CritSect;
176 /** Number of endpoints in the list. */
177 volatile unsigned cEndpoints;
178 /** Head of endpoints with this class. */
179 R3PTRTYPE(PPDMASYNCCOMPLETIONENDPOINT) pEndpointsHead;
180 /** Head of the bandwidth managers for this class. */
181 R3PTRTYPE(PPDMACBWMGR) pBwMgrsHead;
182 /** Pointer to the callback table. */
183 R3PTRTYPE(PCPDMASYNCCOMPLETIONEPCLASSOPS) pEndpointOps;
184 /** Task cache. */
185 RTMEMCACHE hMemCacheTasks;
186} PDMASYNCCOMPLETIONEPCLASS;
187/** Pointer to the PDM async completion endpoint class data. */
188typedef PDMASYNCCOMPLETIONEPCLASS *PPDMASYNCCOMPLETIONEPCLASS;
189
190/**
191 * A PDM Async completion endpoint.
192 * Common data.
193 */
194typedef struct PDMASYNCCOMPLETIONENDPOINT
195{
196 /** Next endpoint in the list. */
197 R3PTRTYPE(PPDMASYNCCOMPLETIONENDPOINT) pNext;
198 /** Previous endpoint in the list. */
199 R3PTRTYPE(PPDMASYNCCOMPLETIONENDPOINT) pPrev;
200 /** Pointer to the class this endpoint belongs to. */
201 R3PTRTYPE(PPDMASYNCCOMPLETIONEPCLASS) pEpClass;
202 /** Template associated with this endpoint. */
203 PPDMASYNCCOMPLETIONTEMPLATE pTemplate;
204 /** Reference count. */
205 unsigned cUsers;
206 /** URI describing the endpoint */
207 char *pszUri;
208 /** Pointer to the assigned bandwidth manager. */
209 volatile PPDMACBWMGR pBwMgr;
210#ifdef VBOX_WITH_STATISTICS
211 uint32_t u32Alignment;
212 STAMCOUNTER StatTaskRunTimesNs[10];
213 STAMCOUNTER StatTaskRunTimesUs[10];
214 STAMCOUNTER StatTaskRunTimesMs[10];
215 STAMCOUNTER StatTaskRunTimesSec[10];
216 STAMCOUNTER StatTaskRunOver100Sec;
217 STAMCOUNTER StatIoOpsPerSec;
218 STAMCOUNTER StatIoOpsStarted;
219 STAMCOUNTER StatIoOpsCompleted;
220 uint64_t tsIntervalStartMs;
221 uint64_t cIoOpsCompleted;
222#endif
223} PDMASYNCCOMPLETIONENDPOINT;
224#ifdef VBOX_WITH_STATISTICS
225AssertCompileMemberAlignment(PDMASYNCCOMPLETIONENDPOINT, StatTaskRunTimesNs, sizeof(uint64_t));
226#endif
227
228/**
229 * A PDM async completion task handle.
230 * Common data.
231 */
232typedef struct PDMASYNCCOMPLETIONTASK
233{
234 /** Next task in the list
235 * (for free and assigned tasks). */
236 R3PTRTYPE(PPDMASYNCCOMPLETIONTASK) pNext;
237 /** Previous task in the list
238 * (for free and assigned tasks). */
239 R3PTRTYPE(PPDMASYNCCOMPLETIONTASK) pPrev;
240 /** Endpoint this task is assigned to. */
241 R3PTRTYPE(PPDMASYNCCOMPLETIONENDPOINT) pEndpoint;
242 /** Opaque user data for this task. */
243 void *pvUser;
244 /** Start timestamp. */
245 uint64_t tsNsStart;
246} PDMASYNCCOMPLETIONTASK;
247
248/**
249 * Called by the endpoint if a task has finished.
250 *
251 * @returns nothing
252 * @param pTask Pointer to the finished task.
253 * @param rc Status code of the completed request.
254 * @param fCallCompletionHandler Flag whether the completion handler should be called to
255 * inform the owner of the task that it has completed.
256 */
257void pdmR3AsyncCompletionCompleteTask(PPDMASYNCCOMPLETIONTASK pTask, int rc, bool fCallCompletionHandler);
258
259/**
260 * Checks if the endpoint is allowed to transfer the given amount of bytes.
261 *
262 * @returns true if the endpoint is allowed to transfer the data.
263 * false otherwise
264 * @param pEndpoint The endpoint.
265 * @param cbTransfer The number of bytes to transfer.
266 * @param pmsWhenNext Where to store the number of milliseconds
267 * until the bandwidth is refreshed.
268 * Only set if false is returned.
269 */
270bool pdmacEpIsTransferAllowed(PPDMASYNCCOMPLETIONENDPOINT pEndpoint, uint32_t cbTransfer, RTMSINTERVAL *pmsWhenNext);
271
272RT_C_DECLS_END
273
274extern const PDMASYNCCOMPLETIONEPCLASSOPS g_PDMAsyncCompletionEndpointClassFile;
275
276#endif /* !___PDMAsyncCompletionInternal_h */
277
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette