VirtualBox

source: vbox/trunk/include/VBox/pdmasynccompletion.h@ 6000

Last change on this file since 6000 was 6000, checked in by vboxsync, 17 years ago

The Giant CDDL Dual-License Header Change, fixes.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id Revision
File size: 14.1 KB
Line 
1/** @file
2 * PDM - Pluggable Device Manager, Async I/O Completion.
3 */
4
5/*
6 * Copyright (C) 2007 innotek GmbH
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 */
25
26#ifndef ___VBox_pdmasynccompletion_h
27#define ___VBox_pdmasynccompletion_h
28
29#include <VBox/types.h>
30
31__BEGIN_DECLS
32
33/** @defgroup grp_pdm_async_completion Async I/O Completion
34 * @ingroup grp_pdm
35 * @{
36 */
37
38/** Pointer to a PDM async completion template handle. */
39typedef struct PDMASYNCCOMPLETIONTEMPLATE *PPDMASYNCCOMPLETIONTEMPLATE;
40/** Pointer to a PDM async completion template handle pointer. */
41typedef PPDMASYNCCOMPLETIONTEMPLATE *PPPDMASYNCCOMPLETIONTEMPLATE;
42
43/** Pointer to a PDM async completion task handle. */
44typedef struct PDMASYNCCOMPLETION *PPDMASYNCCOMPLETION;
45/** Pointer to a PDM async completion task handle pointer. */
46typedef PPDMASYNCCOMPLETION *PPPDMASYNCCOMPLETION;
47
48
49/**
50 * Completion callback for devices.
51 *
52 * @param pDevIns The device instance.
53 * @param pTask Pointer to the completion task.
54 * The task is at the time of the call setup to be resumed. So, the callback must
55 * call PDMR3AsyncCompletionSuspend or PDMR3AsyncCompletionDestroy if any other
56 * action is wanted upon return.
57 * @param pvCtx Pointer to any additional, OS specific, completion context. TBD.
58 * @param pvUser User argument.
59 */
60typedef DECLCALLBACK(void) FNPDMASYNCCOMPLETEDEV(PPDMDEVINS pDevIns, PPDMASYNCCOMPLETION pTask, void *pvCtx, void *pvUser);
61/** Pointer to a FNPDMASYNCCOMPLETEDEV(). */
62typedef FNPDMASYNCCOMPLETEDEV *PFNPDMASYNCCOMPLETEDEV;
63
64
65/**
66 * Completion callback for drivers.
67 *
68 * @param pDrvIns The driver instance.
69 * @param pTask Pointer to the completion task.
70 * The task is at the time of the call setup to be resumed. So, the callback must
71 * call PDMR3AsyncCompletionSuspend or PDMR3AsyncCompletionDestroy if any other
72 * action is wanted upon return.
73 * @param pvCtx Pointer to any additional, OS specific, completion context. TBD.
74 * @param pvUser User argument.
75 */
76typedef DECLCALLBACK(void) FNPDMASYNCCOMPLETEDRV(PPDMDRVINS pDrvIns, PPDMASYNCCOMPLETION pTask, void *pvCtx, void *pvUser);
77/** Pointer to a FNPDMASYNCCOMPLETEDRV(). */
78typedef FNPDMASYNCCOMPLETEDRV *PFNPDMASYNCCOMPLETEDRV;
79
80
81/**
82 * Completion callback for USB devices.
83 *
84 * @param pUsbIns The USB device instance.
85 * @param pTask Pointer to the completion task.
86 * The task is at the time of the call setup to be resumed. So, the callback must
87 * call PDMR3AsyncCompletionSuspend or PDMR3AsyncCompletionDestroy if any other
88 * action is wanted upon return.
89 * @param pvCtx Pointer to any additional, OS specific, completion context. TBD.
90 * @param pvUser User argument.
91 */
92typedef DECLCALLBACK(void) FNPDMASYNCCOMPLETEUSB(PPDMUSBINS pUsbIns, PPDMASYNCCOMPLETION pTask, void *pvCtx, void *pvUser);
93/** Pointer to a FNPDMASYNCCOMPLETEUSB(). */
94typedef FNPDMASYNCCOMPLETEUSB *PFNPDMASYNCCOMPLETEUSB;
95
96
97/**
98 * Completion callback for internal.
99 *
100 * @param pVM Pointer to the shared VM structure.
101 * @param pTask Pointer to the completion task.
102 * The task is at the time of the call setup to be resumed. So, the callback must
103 * call PDMR3AsyncCompletionSuspend or PDMR3AsyncCompletionDestroy if any other
104 * action is wanted upon return.
105 * @param pvCtx Pointer to any additional, OS specific, completion context. TBD.
106 * @param pvUser User argument for the task.
107 * @param pvUser2 User argument for the template.
108 */
109typedef DECLCALLBACK(void) FNPDMASYNCCOMPLETEINT(PVM pVM, PPDMASYNCCOMPLETION pTask, void *pvCtx, void *pvUser, void *pvUser2);
110/** Pointer to a FNPDMASYNCCOMPLETEINT(). */
111typedef FNPDMASYNCCOMPLETEINT *PFNPDMASYNCCOMPLETEINT;
112
113
114/**
115 * Creates a async completion template for a device instance.
116 *
117 * The template is used when creating new completion tasks.
118 *
119 * @returns VBox status code.
120 * @param pVM Pointer to the shared VM structure.
121 * @param pDevIns The device instance.
122 * @param ppTemplate Where to store the template pointer on success.
123 * @param pfnCompleted The completion callback routine.
124 * @param pszDesc Description.
125 */
126PDMR3DECL(int) PDMR3AsyncCompletionTemplateCreateDevice(PVM pVM, PPDMDEVINS pDevIns, PPPDMASYNCCOMPLETIONTEMPLATE ppTemplate, PFNPDMASYNCCOMPLETEDEV pfnCompleted, const char *pszDesc);
127
128/**
129 * Creates a async completion template for a driver instance.
130 *
131 * The template is used when creating new completion tasks.
132 *
133 * @returns VBox status code.
134 * @param pVM Pointer to the shared VM structure.
135 * @param pDrvIns The driver instance.
136 * @param ppTemplate Where to store the template pointer on success.
137 * @param pfnCompleted The completion callback routine.
138 * @param pszDesc Description.
139 */
140PDMR3DECL(int) PDMR3AsyncCompletionTemplateCreateDriver(PVM pVM, PPDMDRVINS pDrvIns, PPPDMASYNCCOMPLETIONTEMPLATE ppTemplate, PFNPDMASYNCCOMPLETEDRV pfnCompleted, const char *pszDesc);
141
142/**
143 * Creates a async completion template for a USB device instance.
144 *
145 * The template is used when creating new completion tasks.
146 *
147 * @returns VBox status code.
148 * @param pVM Pointer to the shared VM structure.
149 * @param pUsbIns The USB device instance.
150 * @param ppTemplate Where to store the template pointer on success.
151 * @param pfnCompleted The completion callback routine.
152 * @param pszDesc Description.
153 */
154PDMR3DECL(int) PDMR3AsyncCompletionTemplateCreateUsb(PVM pVM, PPDMUSBINS pUsbIns, PPPDMASYNCCOMPLETIONTEMPLATE ppTemplate, PFNPDMASYNCCOMPLETEUSB pfnCompleted, const char *pszDesc);
155
156/**
157 * Creates a async completion template for internally by the VMM.
158 *
159 * The template is used when creating new completion tasks.
160 *
161 * @returns VBox status code.
162 * @param pVM Pointer to the shared VM structure.
163 * @param ppTemplate Where to store the template pointer on success.
164 * @param pfnCompleted The completion callback routine.
165 * @param pvUser2 The 2nd user argument for the callback.
166 * @param pszDesc Description.
167 */
168PDMR3DECL(int) PDMR3AsyncCompletionTemplateCreateInternal(PVM pVM, PPPDMASYNCCOMPLETIONTEMPLATE ppTemplate, PFNPDMASYNCCOMPLETEINT pfnCompleted, void *pvUser2, const char *pszDesc);
169
170/**
171 * Destroys the specified async completion template.
172 *
173 * @returns VBox status codes:
174 * @retval VINF_SUCCESS on success.
175 * @retval VERR_PDM_ASYNC_TEMPLATE_BUSY if the template is still in use.
176 *
177 * @param pTemplate The template in question.
178 */
179PDMR3DECL(int) PDMR3AsyncCompletionTemplateDestroy(PPDMASYNCCOMPLETIONTEMPLATE pTemplate);
180
181/**
182 * Destroys all the specified async completion templates for the given device instance.
183 *
184 * @returns VBox status codes:
185 * @retval VINF_SUCCESS on success.
186 * @retval VERR_PDM_ASYNC_TEMPLATE_BUSY if one or more of the templates are still in use.
187 *
188 * @param pVM Pointer to the shared VM structure.
189 * @param pDevIns The device instance.
190 */
191PDMR3DECL(int) PDMR3AsyncCompletionTemplateDestroyDevice(PVM pVM, PPDMDEVINS pDevIns);
192
193/**
194 * Destroys all the specified async completion templates for the given driver instance.
195 *
196 * @returns VBox status codes:
197 * @retval VINF_SUCCESS on success.
198 * @retval VERR_PDM_ASYNC_TEMPLATE_BUSY if one or more of the templates are still in use.
199 *
200 * @param pVM Pointer to the shared VM structure.
201 * @param pDrvIns The driver instance.
202 */
203PDMR3DECL(int) PDMR3AsyncCompletionTemplateDestroyDriver(PVM pVM, PPDMDRVINS pDrvIns);
204
205/**
206 * Destroys all the specified async completion templates for the given USB device instance.
207 *
208 * @returns VBox status codes:
209 * @retval VINF_SUCCESS on success.
210 * @retval VERR_PDM_ASYNC_TEMPLATE_BUSY if one or more of the templates are still in use.
211 *
212 * @param pVM Pointer to the shared VM structure.
213 * @param pUsbIns The USB device instance.
214 */
215PDMR3DECL(int) PDMR3AsyncCompletionTemplateDestroyUsb(PVM pVM, PPDMUSBINS pUsbIns);
216
217
218/**
219 * Socket completion context (pvCtx).
220 */
221typedef struct PDMASYNCCOMPLETIONSOCKET
222{
223 /** The socket. */
224 RTSOCKET Socket;
225 /** Readable. */
226 bool fReadable;
227 /** Writable. */
228 bool fWriteable;
229 /** Exceptions. */
230 bool fXcpt;
231} PDMASYNCCOMPLETIONSOCKET;
232/** Pointer to a socket completion context. */
233typedef PDMASYNCCOMPLETIONSOCKET *PPDMASYNCCOMPLETIONSOCKET;
234
235
236/**
237 * Creates a completion task for a socket.
238 *
239 * The pvCtx callback argument will be pointing to a PDMASYNCCOMPLETIONSOCKET structure.
240 *
241 * @returns VBox status code.
242 * @param ppTask Where to store the task handle on success.
243 * @param pTemplate The async completion template.
244 * @param Socket The socket.
245 * @param fReadable Whether to callback when the socket becomes readable.
246 * @param fWriteable Whether to callback when the socket becomes writable.
247 * @param fXcpt Whether to callback on exception.
248 * @param pvUser The user argument for the callback.
249 */
250PDMR3DECL(int) PDMR3AsyncCompletionCreateSocket(PPPDMASYNCCOMPLETION ppTask, PPDMASYNCCOMPLETIONTEMPLATE pTemplate, RTSOCKET Socket, bool fReadable, bool fWriteable, bool fXcpt, void *pvUser);
251
252/**
253 * Modifies a socket completion task.
254 *
255 * @returns VBox status code.
256 * @retval VINF_SUCCESS on success.
257 * @retval VERR_NOT_SUPPORTED if the task isn't a socket task.
258 * @param pTemplate The async completion template.
259 * @param fReadable Whether to callback when the socket becomes readable.
260 * @param fWriteable Whether to callback when the socket becomes writable.
261 * @param fXcpt Whether to callback on exception.
262 */
263PDMR3DECL(int) PDMR3AsyncCompletionModifySocket(PPDMASYNCCOMPLETION pTask, bool fReadable, bool fWriteable, bool fXcpt);
264
265
266#if defined(RT_OS_LINUX) && defined(_AIO_H)
267/**
268 * Creates a completion task for an AIO operation on Linux.
269 *
270 * The pvCtx callback argument will be pAioCB.
271 *
272 * @returns VBox status code.
273 * @param ppTask Where to store the task handle on success.
274 * @param pTemplate The async completion template.
275 * @param pAioCB The asynchronous I/O control block to wait for.
276 * @param pvUser The user argument for the callback.
277 */
278PDMR3DECL(int) PDMR3AsyncCompletionCreateLnxAIO(PPPDMASYNCCOMPLETION ppTask, PPDMASYNCCOMPLETIONTEMPLATE pTemplate, const struct aiocb *pAioCB, void *pvUser);
279#endif /* RT_OS_LINUX */
280
281#ifdef RT_OS_OS2
282/**
283 * Creates a completion task for an event semaphore on OS/2.
284 *
285 * The pvCtx callback argument will be hev.
286 *
287 * @returns VBox status code.
288 * @param ppTask Where to store the task handle on success.
289 * @param pTemplate The async completion template.
290 * @param hev The handle of the event semaphore to wait on.
291 * @param pvUser The user argument for the callback.
292 */
293PDMR3DECL(int) PDMR3AsyncCompletionCreateOs2Event(PPPDMASYNCCOMPLETION ppTask, PPDMASYNCCOMPLETIONTEMPLATE pTemplate, unsigned long hev, void *pvUser);
294#endif /* RT_OS_OS2 */
295
296#ifdef RT_OS_WINDOWS
297/**
298 * Creates a completion task for an object on Windows.
299 *
300 * The pvCtx callback argument will be hObject.
301 *
302 * @returns VBox status code.
303 * @param ppTask Where to store the task handle on success.
304 * @param pTemplate The async completion template.
305 * @param hObject The object to wait for.
306 * @param pvUser The user argument for the callback.
307 */
308PDMR3DECL(int) PDMR3AsyncCompletionCreateWinObject(PPPDMASYNCCOMPLETION ppTask, PPDMASYNCCOMPLETIONTEMPLATE pTemplate, void *hObject, void *pvUser);
309#endif /* RT_OS_WINDOWS */
310
311
312
313/**
314 * Sets the user argument of a completion task.
315 *
316 * @returns VBox status code.
317 * @param pTask The async completion task.
318 * @param pvUser The user argument for the callback.
319 */
320PDMR3DECL(int) PDMR3AsyncCompletionSetUserArg(PPDMASYNCCOMPLETION pTask, void *pvUser);
321
322/**
323 * Suspends a async completion task.
324 *
325 * @returns VBox status codes:
326 * @retval VINF_SUCCESS on success.
327 * @retval VERR_PDM_ASYNC_COMPLETION_ALREADY_SUSPENDED if already suspended.
328 * @retval VERR_INVALID_HANDLE if pTask is invalid (asserts).
329 * @param pTask The async completion task.
330 */
331PDMR3DECL(int) PDMR3AsyncCompletionSuspend(PPDMASYNCCOMPLETION pTask);
332
333/**
334 * Suspends a async completion task.
335 *
336 * @returns VBox status codes:
337 * @retval VINF_SUCCESS on success.
338 * @retval VERR_PDM_ASYNC_COMPLETION_NOT_SUSPENDED if not suspended.
339 * @retval VERR_INVALID_HANDLE if pTask is invalid (asserts).
340 * @param pTask The async completion task.
341 */
342PDMR3DECL(int) PDMR3AsyncCompletionResume(PPDMASYNCCOMPLETION pTask);
343
344/**
345 * Destroys a async completion task.
346 *
347 * The task doesn't have to be suspended or anything.
348 *
349 * @returns VBox status codes:
350 * @retval VINF_SUCCESS on success.
351 * @retval VERR_INVALID_HANDLE if pTask is invalid but not NIL (asserts).
352 * @param pTask The async completion task.
353 */
354PDMR3DECL(int) PDMR3AsyncCompletionDestroy(PPDMASYNCCOMPLETION pTask);
355
356/** @} */
357
358__END_DECLS
359
360#endif
361
362
363
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