VirtualBox

source: vbox/trunk/include/VBox/pdmdrv.h@ 25891

Last change on this file since 25891 was 25891, checked in by vboxsync, 15 years ago

PDMDrv,*: multi context drivers, part 1.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 43.7 KB
Line 
1/** @file
2 * PDM - Pluggable Device Manager, Drivers. (VMM)
3 */
4
5/*
6 * Copyright (C) 2006-2010 Sun Microsystems, Inc.
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 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
26 * Clara, CA 95054 USA or visit http://www.sun.com if you need
27 * additional information or have any questions.
28 */
29
30#ifndef ___VBox_pdmdrv_h
31#define ___VBox_pdmdrv_h
32
33#include <VBox/pdmqueue.h>
34#include <VBox/pdmcritsect.h>
35#include <VBox/pdmthread.h>
36#include <VBox/pdmifs.h>
37#include <VBox/pdmins.h>
38#include <VBox/pdmcommon.h>
39#include <VBox/tm.h>
40#include <VBox/ssm.h>
41#include <VBox/cfgm.h>
42#include <VBox/dbgf.h>
43#include <VBox/mm.h>
44#include <VBox/err.h>
45#include <iprt/stdarg.h>
46
47#ifdef VBOX_WITH_PDM_ASYNC_COMPLETION
48# include <VBox/pdmasynccompletion.h>
49#endif
50
51RT_C_DECLS_BEGIN
52
53/** @defgroup grp_pdm_driver The PDM Drivers API
54 * @ingroup grp_pdm
55 * @{
56 */
57
58/** Pointer const PDM Driver API, ring-3. */
59typedef R3PTRTYPE(struct PDMDRVHLPR3 const *) PCPDMDRVHLPR3;
60/** Pointer const PDM Driver API, ring-0. */
61typedef R0PTRTYPE(struct PDMDRVHLPR0 const *) PCPDMDRVHLPR0;
62/** Pointer const PDM Driver API, raw-mode context. */
63typedef RCPTRTYPE(struct PDMDRVHLPRC const *) PCPDMDRVHLPRC;
64
65
66/**
67 * Construct a driver instance for a VM.
68 *
69 * @returns VBox status.
70 * @param pDrvIns The driver instance data.
71 * If the registration structure is needed, pDrvIns->pDrvReg points to it.
72 * @param pCfgHandle Configuration node handle for the driver. Use this to obtain the configuration
73 * of the driver instance. It's also found in pDrvIns->pCfgHandle as it's expected
74 * to be used frequently in this function.
75 * @param fFlags Flags, combination of the PDM_TACH_FLAGS_* \#defines.
76 */
77typedef DECLCALLBACK(int) FNPDMDRVCONSTRUCT(PPDMDRVINS pDrvIns, PCFGMNODE pCfgHandle, uint32_t fFlags);
78/** Pointer to a FNPDMDRVCONSTRUCT() function. */
79typedef FNPDMDRVCONSTRUCT *PFNPDMDRVCONSTRUCT;
80
81/**
82 * Destruct a driver instance.
83 *
84 * Most VM resources are freed by the VM. This callback is provided so that
85 * any non-VM resources can be freed correctly.
86 *
87 * @param pDrvIns The driver instance data.
88 */
89typedef DECLCALLBACK(void) FNPDMDRVDESTRUCT(PPDMDRVINS pDrvIns);
90/** Pointer to a FNPDMDRVDESTRUCT() function. */
91typedef FNPDMDRVDESTRUCT *PFNPDMDRVDESTRUCT;
92
93/**
94 * Driver I/O Control interface.
95 *
96 * This is used by external components, such as the COM interface, to
97 * communicate with a driver using a driver specific interface. Generally,
98 * the driver interfaces are used for this task.
99 *
100 * @returns VBox status code.
101 * @param pDrvIns Pointer to the driver instance.
102 * @param uFunction Function to perform.
103 * @param pvIn Pointer to input data.
104 * @param cbIn Size of input data.
105 * @param pvOut Pointer to output data.
106 * @param cbOut Size of output data.
107 * @param pcbOut Where to store the actual size of the output data.
108 */
109typedef DECLCALLBACK(int) FNPDMDRVIOCTL(PPDMDRVINS pDrvIns, RTUINT uFunction,
110 void *pvIn, RTUINT cbIn,
111 void *pvOut, RTUINT cbOut, PRTUINT pcbOut);
112/** Pointer to a FNPDMDRVIOCTL() function. */
113typedef FNPDMDRVIOCTL *PFNPDMDRVIOCTL;
114
115/**
116 * Power On notification.
117 *
118 * @param pDrvIns The driver instance data.
119 */
120typedef DECLCALLBACK(void) FNPDMDRVPOWERON(PPDMDRVINS pDrvIns);
121/** Pointer to a FNPDMDRVPOWERON() function. */
122typedef FNPDMDRVPOWERON *PFNPDMDRVPOWERON;
123
124/**
125 * Reset notification.
126 *
127 * @returns VBox status.
128 * @param pDrvIns The driver instance data.
129 */
130typedef DECLCALLBACK(void) FNPDMDRVRESET(PPDMDRVINS pDrvIns);
131/** Pointer to a FNPDMDRVRESET() function. */
132typedef FNPDMDRVRESET *PFNPDMDRVRESET;
133
134/**
135 * Suspend notification.
136 *
137 * @returns VBox status.
138 * @param pDrvIns The driver instance data.
139 */
140typedef DECLCALLBACK(void) FNPDMDRVSUSPEND(PPDMDRVINS pDrvIns);
141/** Pointer to a FNPDMDRVSUSPEND() function. */
142typedef FNPDMDRVSUSPEND *PFNPDMDRVSUSPEND;
143
144/**
145 * Resume notification.
146 *
147 * @returns VBox status.
148 * @param pDrvIns The driver instance data.
149 */
150typedef DECLCALLBACK(void) FNPDMDRVRESUME(PPDMDRVINS pDrvIns);
151/** Pointer to a FNPDMDRVRESUME() function. */
152typedef FNPDMDRVRESUME *PFNPDMDRVRESUME;
153
154/**
155 * Power Off notification.
156 *
157 * @param pDrvIns The driver instance data.
158 */
159typedef DECLCALLBACK(void) FNPDMDRVPOWEROFF(PPDMDRVINS pDrvIns);
160/** Pointer to a FNPDMDRVPOWEROFF() function. */
161typedef FNPDMDRVPOWEROFF *PFNPDMDRVPOWEROFF;
162
163/**
164 * Attach command.
165 *
166 * This is called to let the drive attach to a driver at runtime. This is not
167 * called during VM construction, the driver constructor have to do this by
168 * calling PDMDrvHlpAttach.
169 *
170 * This is like plugging in the keyboard or mouse after turning on the PC.
171 *
172 * @returns VBox status code.
173 * @param pDrvIns The driver instance.
174 * @param fFlags Flags, combination of the PDM_TACH_FLAGS_* \#defines.
175 */
176typedef DECLCALLBACK(int) FNPDMDRVATTACH(PPDMDRVINS pDrvIns, uint32_t fFlags);
177/** Pointer to a FNPDMDRVATTACH() function. */
178typedef FNPDMDRVATTACH *PFNPDMDRVATTACH;
179
180/**
181 * Detach notification.
182 *
183 * This is called when a driver below it in the chain is detaching itself
184 * from it. The driver should adjust it's state to reflect this.
185 *
186 * This is like ejecting a cdrom or floppy.
187 *
188 * @param pDrvIns The driver instance.
189 * @param fFlags PDM_TACH_FLAGS_NOT_HOT_PLUG or 0.
190 */
191typedef DECLCALLBACK(void) FNPDMDRVDETACH(PPDMDRVINS pDrvIns, uint32_t fFlags);
192/** Pointer to a FNPDMDRVDETACH() function. */
193typedef FNPDMDRVDETACH *PFNPDMDRVDETACH;
194
195
196
197/** PDM Driver Registration Structure,
198 * This structure is used when registering a driver from
199 * VBoxInitDrivers() (HC Ring-3). PDM will continue use till
200 * the VM is terminated.
201 */
202typedef struct PDMDRVREG
203{
204 /** Structure version. PDM_DRVREG_VERSION defines the current version. */
205 uint32_t u32Version;
206 /** Driver name. */
207 char szDriverName[32];
208 /** The description of the driver. The UTF-8 string pointed to shall, like this structure,
209 * remain unchanged from registration till VM destruction. */
210 const char *pszDescription;
211
212 /** Flags, combination of the PDM_DRVREG_FLAGS_* \#defines. */
213 RTUINT fFlags;
214 /** Driver class(es), combination of the PDM_DRVREG_CLASS_* \#defines. */
215 RTUINT fClass;
216 /** Maximum number of instances (per VM). */
217 RTUINT cMaxInstances;
218 /** Size of the instance data. */
219 RTUINT cbInstance;
220
221 /** Construct instance - required. */
222 PFNPDMDRVCONSTRUCT pfnConstruct;
223 /** Destruct instance - optional. */
224 PFNPDMDRVDESTRUCT pfnDestruct;
225 /** I/O control - optional. */
226 PFNPDMDRVIOCTL pfnIOCtl;
227 /** Power on notification - optional. */
228 PFNPDMDRVPOWERON pfnPowerOn;
229 /** Reset notification - optional. */
230 PFNPDMDRVRESET pfnReset;
231 /** Suspend notification - optional. */
232 PFNPDMDRVSUSPEND pfnSuspend;
233 /** Resume notification - optional. */
234 PFNPDMDRVRESUME pfnResume;
235 /** Attach command - optional. */
236 PFNPDMDRVATTACH pfnAttach;
237 /** Detach notification - optional. */
238 PFNPDMDRVDETACH pfnDetach;
239 /** Power off notification - optional. */
240 PFNPDMDRVPOWEROFF pfnPowerOff;
241 /** @todo */
242 PFNRT pfnSoftReset;
243 /** Initialization safty marker. */
244 uint32_t u32VersionEnd;
245} PDMDRVREG;
246/** Pointer to a PDM Driver Structure. */
247typedef PDMDRVREG *PPDMDRVREG;
248/** Const pointer to a PDM Driver Structure. */
249typedef PDMDRVREG const *PCPDMDRVREG;
250
251/** Current DRVREG version number. */
252#define PDM_DRVREG_VERSION UINT32_C(0x80030000)
253
254/** PDM Driver Flags.
255 * @{ */
256/** @def PDM_DRVREG_FLAGS_HOST_BITS_DEFAULT
257 * The bit count for the current host. */
258#if HC_ARCH_BITS == 32
259# define PDM_DRVREG_FLAGS_HOST_BITS_DEFAULT UINT32_C(0x00000001)
260#elif HC_ARCH_BITS == 64
261# define PDM_DRVREG_FLAGS_HOST_BITS_DEFAULT UINT32_C(0x00000002)
262#else
263# error Unsupported HC_ARCH_BITS value.
264#endif
265/** The host bit count mask. */
266#define PDM_DRVREG_FLAGS_HOST_BITS_MASK UINT32_C(0x00000003)
267/** This flag is used to indicate that the driver has a RC component. */
268#define PDM_DRVREG_FLAGS_RC UINT32_C(0x00000010)
269/** This flag is used to indicate that the driver has a R0 component. */
270#define PDM_DRVREG_FLAGS_R0 UINT32_C(0x00000020)
271
272/** @} */
273
274
275/** PDM Driver Classes.
276 * @{ */
277/** Mouse input driver. */
278#define PDM_DRVREG_CLASS_MOUSE RT_BIT(0)
279/** Keyboard input driver. */
280#define PDM_DRVREG_CLASS_KEYBOARD RT_BIT(1)
281/** Display driver. */
282#define PDM_DRVREG_CLASS_DISPLAY RT_BIT(2)
283/** Network transport driver. */
284#define PDM_DRVREG_CLASS_NETWORK RT_BIT(3)
285/** Block driver. */
286#define PDM_DRVREG_CLASS_BLOCK RT_BIT(4)
287/** Media driver. */
288#define PDM_DRVREG_CLASS_MEDIA RT_BIT(5)
289/** Mountable driver. */
290#define PDM_DRVREG_CLASS_MOUNTABLE RT_BIT(6)
291/** Audio driver. */
292#define PDM_DRVREG_CLASS_AUDIO RT_BIT(7)
293/** VMMDev driver. */
294#define PDM_DRVREG_CLASS_VMMDEV RT_BIT(8)
295/** Status driver. */
296#define PDM_DRVREG_CLASS_STATUS RT_BIT(9)
297/** ACPI driver. */
298#define PDM_DRVREG_CLASS_ACPI RT_BIT(10)
299/** USB related driver. */
300#define PDM_DRVREG_CLASS_USB RT_BIT(11)
301/** ISCSI Transport related driver. */
302#define PDM_DRVREG_CLASS_ISCSITRANSPORT RT_BIT(12)
303/** Char driver. */
304#define PDM_DRVREG_CLASS_CHAR RT_BIT(13)
305/** Stream driver. */
306#define PDM_DRVREG_CLASS_STREAM RT_BIT(14)
307/** SCSI driver. */
308#define PDM_DRVREG_CLASS_SCSI RT_BIT(15)
309/** @} */
310
311
312/**
313 * PDM Driver Instance.
314 */
315typedef struct PDMDRVINS
316{
317 /** Structure version. PDM_DRVINS_VERSION defines the current version. */
318 uint32_t u32Version;
319 /** Driver instance number. */
320 uint32_t iInstance;
321
322 /** Pointer the PDM Driver API. */
323 RCPTRTYPE(PCPDMDRVHLPRC) pDrvHlpRC;
324 /** Pointer to driver instance data. */
325 RCPTRTYPE(void *) pvInstanceDataRC;
326
327 /** Pointer the PDM Driver API. */
328 R0PTRTYPE(PCPDMDRVHLPR0) pDrvHlpR0;
329 /** Pointer to driver instance data. */
330 R0PTRTYPE(void *) pvInstanceDataR0;
331
332 /** Pointer the PDM Driver API. */
333 R3PTRTYPE(PCPDMDRVHLPR3) pDrvHlpR3;
334 /** Pointer to driver instance data. */
335 R3PTRTYPE(void *) pvInstanceDataR3;
336
337 /** Pointer to driver registration structure. */
338 R3PTRTYPE(PCPDMDRVREG) pDrvReg;
339 /** Configuration handle. */
340 R3PTRTYPE(PCFGMNODE) pCfgHandle;
341
342 /** Pointer to the base interface of the device/driver instance above. */
343 R3PTRTYPE(PPDMIBASE) pUpBase;
344 /** Pointer to the base interface of the driver instance below. */
345 R3PTRTYPE(PPDMIBASE) pDownBase;
346
347 /** The base interface of the driver.
348 * The driver constructor initializes this. */
349 PDMIBASE IBase;
350 /** Align the internal data more naturally. */
351 RTR3PTR R3PtrPadding;
352
353 /** Internal data. */
354 union
355 {
356#ifdef PDMDRVINSINT_DECLARED
357 PDMDRVINSINT s;
358#endif
359 uint8_t padding[HC_ARCH_BITS == 32 ? 40 + 32 : 72 + 24];
360 } Internal;
361
362 /** Driver instance data. The size of this area is defined
363 * in the PDMDRVREG::cbInstanceData field. */
364 char achInstanceData[4];
365} PDMDRVINS;
366
367/** Current DRVREG version number. */
368#define PDM_DRVINS_VERSION UINT32_C(0xa0020000)
369
370/** Converts a pointer to the PDMDRVINS::IBase to a pointer to PDMDRVINS. */
371#define PDMIBASE_2_PDMDRV(pInterface) ( (PPDMDRVINS)((char *)(pInterface) - RT_OFFSETOF(PDMDRVINS, IBase)) )
372
373
374
375
376/**
377 * USB hub registration structure.
378 */
379typedef struct PDMUSBHUBREG
380{
381 /** Structure version number. PDM_USBHUBREG_VERSION defines the current version. */
382 uint32_t u32Version;
383
384 /**
385 * Request the hub to attach of the specified device.
386 *
387 * @returns VBox status code.
388 * @param pDrvIns The hub instance.
389 * @param pUsbIns The device to attach.
390 * @param piPort Where to store the port number the device was attached to.
391 * @thread EMT.
392 */
393 DECLR3CALLBACKMEMBER(int, pfnAttachDevice,(PPDMDRVINS pDrvIns, PPDMUSBINS pUsbIns, uint32_t *piPort));
394
395 /**
396 * Request the hub to detach of the specified device.
397 *
398 * The device has previously been attached to the hub with the
399 * pfnAttachDevice call. This call is not currently expected to
400 * fail.
401 *
402 * @returns VBox status code.
403 * @param pDrvIns The hub instance.
404 * @param pUsbIns The device to detach.
405 * @param iPort The port number returned by the attach call.
406 * @thread EMT.
407 */
408 DECLR3CALLBACKMEMBER(int, pfnDetachDevice,(PPDMDRVINS pDrvIns, PPDMUSBINS pUsbIns, uint32_t iPort));
409
410 /** Counterpart to u32Version, same value. */
411 uint32_t u32TheEnd;
412} PDMUSBHUBREG;
413/** Pointer to a const USB hub registration structure. */
414typedef const PDMUSBHUBREG *PCPDMUSBHUBREG;
415
416/** Current PDMUSBHUBREG version number. */
417#define PDM_USBHUBREG_VERSION UINT32_C(0xeb010000)
418
419
420/**
421 * USB hub helpers.
422 * This is currently just a place holder.
423 */
424typedef struct PDMUSBHUBHLP
425{
426 /** Structure version. PDM_USBHUBHLP_VERSION defines the current version. */
427 uint32_t u32Version;
428
429 /** Just a safety precaution. */
430 uint32_t u32TheEnd;
431} PDMUSBHUBHLP;
432/** Pointer to PCI helpers. */
433typedef PDMUSBHUBHLP *PPDMUSBHUBHLP;
434/** Pointer to const PCI helpers. */
435typedef const PDMUSBHUBHLP *PCPDMUSBHUBHLP;
436/** Pointer to const PCI helpers pointer. */
437typedef PCPDMUSBHUBHLP *PPCPDMUSBHUBHLP;
438
439/** Current PDMUSBHUBHLP version number. */
440#define PDM_USBHUBHLP_VERSION UINT32_C(0xea010000)
441
442
443#ifdef IN_RING3
444/**
445 * PDM Driver API.
446 */
447typedef struct PDMDRVHLPR3
448{
449 /** Structure version. PDM_DRVHLP_VERSION defines the current version. */
450 uint32_t u32Version;
451
452 /**
453 * Attaches a driver (chain) to the driver.
454 *
455 * @returns VBox status code.
456 * @param pDrvIns Driver instance.
457 * @param fFlags PDM_TACH_FLAGS_NOT_HOT_PLUG or 0.
458 * @param ppBaseInterface Where to store the pointer to the base interface.
459 */
460 DECLR3CALLBACKMEMBER(int, pfnAttach,(PPDMDRVINS pDrvIns, uint32_t fFlags, PPDMIBASE *ppBaseInterface));
461
462 /**
463 * Detach the driver the drivers below us.
464 *
465 * @returns VBox status code.
466 * @param pDrvIns Driver instance.
467 * @param fFlags PDM_TACH_FLAGS_NOT_HOT_PLUG or 0.
468 */
469 DECLR3CALLBACKMEMBER(int, pfnDetach,(PPDMDRVINS pDrvIns, uint32_t fFlags));
470
471 /**
472 * Detach the driver from the driver above it and destroy this
473 * driver and all drivers below it.
474 *
475 * @returns VBox status code.
476 * @param pDrvIns Driver instance.
477 * @param fFlags PDM_TACH_FLAGS_NOT_HOT_PLUG or 0.
478 */
479 DECLR3CALLBACKMEMBER(int, pfnDetachSelf,(PPDMDRVINS pDrvIns, uint32_t fFlags));
480
481 /**
482 * Prepare a media mount.
483 *
484 * The driver must not have anything attached to itself
485 * when calling this function as the purpose is to set up the configuration
486 * of an future attachment.
487 *
488 * @returns VBox status code
489 * @param pDrvIns Driver instance.
490 * @param pszFilename Pointer to filename. If this is NULL it assumed that the caller have
491 * constructed a configuration which can be attached to the bottom driver.
492 * @param pszCoreDriver Core driver name. NULL will cause autodetection. Ignored if pszFilanem is NULL.
493 */
494 DECLR3CALLBACKMEMBER(int, pfnMountPrepare,(PPDMDRVINS pDrvIns, const char *pszFilename, const char *pszCoreDriver));
495
496 /**
497 * Assert that the current thread is the emulation thread.
498 *
499 * @returns True if correct.
500 * @returns False if wrong.
501 * @param pDrvIns Driver instance.
502 * @param pszFile Filename of the assertion location.
503 * @param iLine Linenumber of the assertion location.
504 * @param pszFunction Function of the assertion location.
505 */
506 DECLR3CALLBACKMEMBER(bool, pfnAssertEMT,(PPDMDRVINS pDrvIns, const char *pszFile, unsigned iLine, const char *pszFunction));
507
508 /**
509 * Assert that the current thread is NOT the emulation thread.
510 *
511 * @returns True if correct.
512 * @returns False if wrong.
513 * @param pDrvIns Driver instance.
514 * @param pszFile Filename of the assertion location.
515 * @param iLine Linenumber of the assertion location.
516 * @param pszFunction Function of the assertion location.
517 */
518 DECLR3CALLBACKMEMBER(bool, pfnAssertOther,(PPDMDRVINS pDrvIns, const char *pszFile, unsigned iLine, const char *pszFunction));
519
520 /**
521 * Set the VM error message
522 *
523 * @returns rc.
524 * @param pDrvIns Driver instance.
525 * @param rc VBox status code.
526 * @param RT_SRC_POS_DECL Use RT_SRC_POS.
527 * @param pszFormat Error message format string.
528 * @param ... Error message arguments.
529 */
530 DECLR3CALLBACKMEMBER(int, pfnVMSetError,(PPDMDRVINS pDrvIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, ...));
531
532 /**
533 * Set the VM error message
534 *
535 * @returns rc.
536 * @param pDrvIns Driver instance.
537 * @param rc VBox status code.
538 * @param RT_SRC_POS_DECL Use RT_SRC_POS.
539 * @param pszFormat Error message format string.
540 * @param va Error message arguments.
541 */
542 DECLR3CALLBACKMEMBER(int, pfnVMSetErrorV,(PPDMDRVINS pDrvIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va));
543
544 /**
545 * Set the VM runtime error message
546 *
547 * @returns VBox status code.
548 * @param pDrvIns Driver instance.
549 * @param fFlags The action flags. See VMSETRTERR_FLAGS_*.
550 * @param pszErrorId Error ID string.
551 * @param pszFormat Error message format string.
552 * @param ... Error message arguments.
553 */
554 DECLR3CALLBACKMEMBER(int, pfnVMSetRuntimeError,(PPDMDRVINS pDrvIns, uint32_t fFlags, const char *pszErrorId, const char *pszFormat, ...));
555
556 /**
557 * Set the VM runtime error message
558 *
559 * @returns VBox status code.
560 * @param pDrvIns Driver instance.
561 * @param fFlags The action flags. See VMSETRTERR_FLAGS_*.
562 * @param pszErrorId Error ID string.
563 * @param pszFormat Error message format string.
564 * @param va Error message arguments.
565 */
566 DECLR3CALLBACKMEMBER(int, pfnVMSetRuntimeErrorV,(PPDMDRVINS pDrvIns, uint32_t fFlags, const char *pszErrorId, const char *pszFormat, va_list va));
567
568 /**
569 * Gets the VM state.
570 *
571 * @returns VM state.
572 * @param pDrvIns The driver instance.
573 * @thread Any thread (just keep in mind that it's volatile info).
574 */
575 DECLR3CALLBACKMEMBER(VMSTATE, pfnVMState, (PPDMDRVINS pDrvIns));
576
577 /**
578 * Checks if the VM was teleported and hasn't been fully resumed yet.
579 *
580 * @returns true / false.
581 * @param pDrvIns The driver instance.
582 * @thread Any thread.
583 */
584 DECLR3CALLBACKMEMBER(bool, pfnVMTeleportedAndNotFullyResumedYet,(PPDMDRVINS pDrvIns));
585
586 /**
587 * Create a queue.
588 *
589 * @returns VBox status code.
590 * @param pDrvIns Driver instance.
591 * @param cbItem Size a queue item.
592 * @param cItems Number of items in the queue.
593 * @param cMilliesInterval Number of milliseconds between polling the queue.
594 * If 0 then the emulation thread will be notified whenever an item arrives.
595 * @param pfnCallback The consumer function.
596 * @param pszName The queue base name. The instance number will be
597 * appended automatically.
598 * @param ppQueue Where to store the queue handle on success.
599 * @thread The emulation thread.
600 */
601 DECLR3CALLBACKMEMBER(int, pfnPDMQueueCreate,(PPDMDRVINS pDrvIns, RTUINT cbItem, RTUINT cItems, uint32_t cMilliesInterval,
602 PFNPDMQUEUEDRV pfnCallback, const char *pszName, PPDMQUEUE *ppQueue));
603
604 /**
605 * Query the virtual timer frequency.
606 *
607 * @returns Frequency in Hz.
608 * @param pDrvIns Driver instance.
609 * @thread Any thread.
610 */
611 DECLR3CALLBACKMEMBER(uint64_t, pfnTMGetVirtualFreq,(PPDMDRVINS pDrvIns));
612
613 /**
614 * Query the virtual time.
615 *
616 * @returns The current virtual time.
617 * @param pDrvIns Driver instance.
618 * @thread Any thread.
619 */
620 DECLR3CALLBACKMEMBER(uint64_t, pfnTMGetVirtualTime,(PPDMDRVINS pDrvIns));
621
622 /**
623 * Creates a timer.
624 *
625 * @returns VBox status.
626 * @param pDrvIns Driver instance.
627 * @param enmClock The clock to use on this timer.
628 * @param pfnCallback Callback function.
629 * @param pvUser The user argument to the callback.
630 * @param fFlags Timer creation flags, see grp_tm_timer_flags.
631 * @param pszDesc Pointer to description string which must stay around
632 * until the timer is fully destroyed (i.e. a bit after TMTimerDestroy()).
633 * @param ppTimer Where to store the timer on success.
634 * @thread EMT
635 */
636 DECLR3CALLBACKMEMBER(int, pfnTMTimerCreate,(PPDMDRVINS pDrvIns, TMCLOCK enmClock, PFNTMTIMERDRV pfnCallback, void *pvUser, uint32_t fFlags, const char *pszDesc, PPTMTIMERR3 ppTimer));
637
638 /**
639 * Register a save state data unit.
640 *
641 * @returns VBox status.
642 * @param pDrvIns Driver instance.
643 * @param uVersion Data layout version number.
644 * @param cbGuess The approximate amount of data in the unit.
645 * Only for progress indicators.
646 *
647 * @param pfnLivePrep Prepare live save callback, optional.
648 * @param pfnLiveExec Execute live save callback, optional.
649 * @param pfnLiveVote Vote live save callback, optional.
650 *
651 * @param pfnSavePrep Prepare save callback, optional.
652 * @param pfnSaveExec Execute save callback, optional.
653 * @param pfnSaveDone Done save callback, optional.
654 *
655 * @param pfnLoadPrep Prepare load callback, optional.
656 * @param pfnLoadExec Execute load callback, optional.
657 * @param pfnLoadDone Done load callback, optional.
658 */
659 DECLR3CALLBACKMEMBER(int, pfnSSMRegister,(PPDMDRVINS pDrvIns, uint32_t uVersion, size_t cbGuess,
660 PFNSSMDRVLIVEPREP pfnLivePrep, PFNSSMDRVLIVEEXEC pfnLiveExec, PFNSSMDRVLIVEVOTE pfnLiveVote,
661 PFNSSMDRVSAVEPREP pfnSavePrep, PFNSSMDRVSAVEEXEC pfnSaveExec, PFNSSMDRVSAVEDONE pfnSaveDone,
662 PFNSSMDRVLOADPREP pfnLoadPrep, PFNSSMDRVLOADEXEC pfnLoadExec, PFNSSMDRVLOADDONE pfnLoadDone));
663
664 /**
665 * Deregister a save state data unit.
666 *
667 * @returns VBox status.
668 * @param pDrvIns Driver instance.
669 * @param pszName Data unit name.
670 * @param uInstance The instance identifier of the data unit.
671 * This must together with the name be unique.
672 */
673 DECLR3CALLBACKMEMBER(int, pfnSSMDeregister,(PPDMDRVINS pDrvIns, const char *pszName, uint32_t uInstance));
674
675 /**
676 * Registers a statistics sample if statistics are enabled.
677 *
678 * @param pDrvIns Driver instance.
679 * @param pvSample Pointer to the sample.
680 * @param enmType Sample type. This indicates what pvSample is pointing at.
681 * @param pszName Sample name. The name is on this form "/<component>/<sample>".
682 * Further nesting is possible.
683 * @param enmUnit Sample unit.
684 * @param pszDesc Sample description.
685 */
686 DECLR3CALLBACKMEMBER(void, pfnSTAMRegister,(PPDMDRVINS pDrvIns, void *pvSample, STAMTYPE enmType, const char *pszName,
687 STAMUNIT enmUnit, const char *pszDesc));
688
689 /**
690 * Same as pfnSTAMRegister except that the name is specified in a
691 * RTStrPrintf like fashion.
692 *
693 * @param pDrvIns Driver instance.
694 * @param pvSample Pointer to the sample.
695 * @param enmType Sample type. This indicates what pvSample is pointing at.
696 * @param enmVisibility Visibility type specifying whether unused statistics should be visible or not.
697 * @param enmUnit Sample unit.
698 * @param pszDesc Sample description.
699 * @param pszName The sample name format string.
700 * @param ... Arguments to the format string.
701 */
702 DECLR3CALLBACKMEMBER(void, pfnSTAMRegisterF,(PPDMDRVINS pDrvIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,
703 STAMUNIT enmUnit, const char *pszDesc, const char *pszName, ...));
704
705 /**
706 * Same as pfnSTAMRegister except that the name is specified in a
707 * RTStrPrintfV like fashion.
708 *
709 * @param pDrvIns Driver instance.
710 * @param pvSample Pointer to the sample.
711 * @param enmType Sample type. This indicates what pvSample is pointing at.
712 * @param enmVisibility Visibility type specifying whether unused statistics should be visible or not.
713 * @param enmUnit Sample unit.
714 * @param pszDesc Sample description.
715 * @param pszName The sample name format string.
716 * @param args Arguments to the format string.
717 */
718 DECLR3CALLBACKMEMBER(void, pfnSTAMRegisterV,(PPDMDRVINS pDrvIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,
719 STAMUNIT enmUnit, const char *pszDesc, const char *pszName, va_list args));
720
721 /**
722 * Deregister a statistic item previously registered with pfnSTAMRegister,
723 * pfnSTAMRegisterF or pfnSTAMRegisterV
724 *
725 * @returns VBox status.
726 * @param pDrvIns Driver instance.
727 * @param pvSample Pointer to the sample.
728 */
729 DECLR3CALLBACKMEMBER(int, pfnSTAMDeregister,(PPDMDRVINS pDrvIns, void *pvSample));
730
731 /**
732 * Calls the HC R0 VMM entry point, in a safer but slower manner than
733 * SUPR3CallVMMR0.
734 *
735 * When entering using this call the R0 components can call into the host kernel
736 * (i.e. use the SUPR0 and RT APIs).
737 *
738 * See VMMR0Entry() for more details.
739 *
740 * @returns error code specific to uFunction.
741 * @param pDrvIns The driver instance.
742 * @param uOperation Operation to execute.
743 * This is limited to services.
744 * @param pvArg Pointer to argument structure or if cbArg is 0 just an value.
745 * @param cbArg The size of the argument. This is used to copy whatever the argument
746 * points at into a kernel buffer to avoid problems like the user page
747 * being invalidated while we're executing the call.
748 */
749 DECLR3CALLBACKMEMBER(int, pfnSUPCallVMMR0Ex,(PPDMDRVINS pDrvIns, unsigned uOperation, void *pvArg, unsigned cbArg));
750
751 /**
752 * Registers a USB HUB.
753 *
754 * @returns VBox status code.
755 * @param pDrvIns The driver instance.
756 * @param fVersions Indicates the kinds of USB devices that can be attached to this HUB.
757 * @param cPorts The number of ports.
758 * @param pUsbHubReg The hub callback structure that PDMUsb uses to interact with it.
759 * @param ppUsbHubHlp The helper callback structure that the hub uses to talk to PDMUsb.
760 *
761 * @thread EMT.
762 */
763 DECLR3CALLBACKMEMBER(int, pfnUSBRegisterHub,(PPDMDRVINS pDrvIns, uint32_t fVersions, uint32_t cPorts, PCPDMUSBHUBREG pUsbHubReg, PPCPDMUSBHUBHLP ppUsbHubHlp));
764
765 /**
766 * Set up asynchronous handling of a suspend, reset or power off notification.
767 *
768 * This shall only be called when getting the notification. It must be called
769 * for each one.
770 *
771 * @returns VBox status code.
772 * @param pDrvIns The driver instance.
773 * @param pfnAsyncNotify The callback.
774 * @thread EMT(0)
775 */
776 DECLR3CALLBACKMEMBER(int, pfnSetAsyncNotification, (PPDMDRVINS pDrvIns, PFNPDMDRVASYNCNOTIFY pfnAsyncNotify));
777
778 /**
779 * Notify EMT(0) that the driver has completed the asynchronous notification
780 * handling.
781 *
782 * This can be called at any time, spurious calls will simply be ignored.
783 *
784 * @param pDrvIns The driver instance.
785 * @thread Any
786 */
787 DECLR3CALLBACKMEMBER(void, pfnAsyncNotificationCompleted, (PPDMDRVINS pDrvIns));
788
789 /**
790 * Creates a PDM thread.
791 *
792 * This differs from the RTThreadCreate() API in that PDM takes care of suspending,
793 * resuming, and destroying the thread as the VM state changes.
794 *
795 * @returns VBox status code.
796 * @param pDrvIns The driver instance.
797 * @param ppThread Where to store the thread 'handle'.
798 * @param pvUser The user argument to the thread function.
799 * @param pfnThread The thread function.
800 * @param pfnWakeup The wakup callback. This is called on the EMT thread when
801 * a state change is pending.
802 * @param cbStack See RTThreadCreate.
803 * @param enmType See RTThreadCreate.
804 * @param pszName See RTThreadCreate.
805 */
806 DECLR3CALLBACKMEMBER(int, pfnPDMThreadCreate,(PPDMDRVINS pDrvIns, PPPDMTHREAD ppThread, void *pvUser, PFNPDMTHREADDRV pfnThread,
807 PFNPDMTHREADWAKEUPDRV pfnWakeup, size_t cbStack, RTTHREADTYPE enmType, const char *pszName));
808
809#ifdef VBOX_WITH_PDM_ASYNC_COMPLETION
810 /**
811 * Creates a async completion template for a driver instance.
812 *
813 * The template is used when creating new completion tasks.
814 *
815 * @returns VBox status code.
816 * @param pDrvIns The driver instance.
817 * @param ppTemplate Where to store the template pointer on success.
818 * @param pfnCompleted The completion callback routine.
819 * @param pvTemplateUser Template user argument.
820 * @param pszDesc Description.
821 */
822 DECLR3CALLBACKMEMBER(int, pfnPDMAsyncCompletionTemplateCreate,(PPDMDRVINS pDrvIns, PPPDMASYNCCOMPLETIONTEMPLATE ppTemplate,
823 PFNPDMASYNCCOMPLETEDRV pfnCompleted, void *pvTemplateUser,
824 const char *pszDesc));
825#endif
826
827 /** Just a safety precaution. */
828 uint32_t u32TheEnd;
829} PDMDRVHLPR3;
830/** Current DRVHLP version number. */
831#define PDM_DRVHLPR3_VERSION UINT32_C(0x90050000)
832
833
834/**
835 * @copydoc PDMDRVHLP::pfnVMSetError
836 */
837DECLINLINE(int) PDMDrvHlpVMSetError(PPDMDRVINS pDrvIns, const int rc, RT_SRC_POS_DECL, const char *pszFormat, ...)
838{
839 va_list va;
840 va_start(va, pszFormat);
841 pDrvIns->CTX_SUFF(pDrvHlp)->pfnVMSetErrorV(pDrvIns, rc, RT_SRC_POS_ARGS, pszFormat, va);
842 va_end(va);
843 return rc;
844}
845
846/** @def PDMDRV_SET_ERROR
847 * Set the VM error. See PDMDrvHlpVMSetError() for printf like message formatting.
848 */
849#define PDMDRV_SET_ERROR(pDrvIns, rc, pszError) \
850 PDMDrvHlpVMSetError(pDrvIns, rc, RT_SRC_POS, "%s", pszError)
851
852/**
853 * @copydoc PDMDRVHLP::pfnVMSetErrorV
854 */
855DECLINLINE(int) PDMDrvHlpVMSetErrorV(PPDMDRVINS pDrvIns, const int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va)
856{
857 return pDrvIns->CTX_SUFF(pDrvHlp)->pfnVMSetErrorV(pDrvIns, rc, RT_SRC_POS_ARGS, pszFormat, va);
858}
859
860
861/**
862 * @copydoc PDMDRVHLP::pfnVMSetRuntimeError
863 */
864DECLINLINE(int) PDMDrvHlpVMSetRuntimeError(PPDMDRVINS pDrvIns, uint32_t fFlags, const char *pszErrorId, const char *pszFormat, ...)
865{
866 va_list va;
867 int rc;
868 va_start(va, pszFormat);
869 rc = pDrvIns->CTX_SUFF(pDrvHlp)->pfnVMSetRuntimeErrorV(pDrvIns, fFlags, pszErrorId, pszFormat, va);
870 va_end(va);
871 return rc;
872}
873
874/** @def PDMDRV_SET_RUNTIME_ERROR
875 * Set the VM runtime error. See PDMDrvHlpVMSetRuntimeError() for printf like message formatting.
876 */
877#define PDMDRV_SET_RUNTIME_ERROR(pDrvIns, fFlags, pszErrorId, pszError) \
878 PDMDrvHlpVMSetRuntimeError(pDrvIns, fFlags, pszErrorId, "%s", pszError)
879
880/**
881 * @copydoc PDMDRVHLP::pfnVMSetRuntimeErrorV
882 */
883DECLINLINE(int) PDMDrvHlpVMSetRuntimeErrorV(PPDMDRVINS pDrvIns, uint32_t fFlags, const char *pszErrorId, const char *pszFormat, va_list va)
884{
885 return pDrvIns->CTX_SUFF(pDrvHlp)->pfnVMSetRuntimeErrorV(pDrvIns, fFlags, pszErrorId, pszFormat, va);
886}
887
888#endif /* IN_RING3 */
889
890
891/** @def PDMDRV_ASSERT_EMT
892 * Assert that the current thread is the emulation thread.
893 */
894#ifdef VBOX_STRICT
895# define PDMDRV_ASSERT_EMT(pDrvIns) pDrvIns->CTX_SUFF(pDrvHlp)->pfnAssertEMT(pDrvIns, __FILE__, __LINE__, __FUNCTION__)
896#else
897# define PDMDRV_ASSERT_EMT(pDrvIns) do { } while (0)
898#endif
899
900/** @def PDMDRV_ASSERT_OTHER
901 * Assert that the current thread is NOT the emulation thread.
902 */
903#ifdef VBOX_STRICT
904# define PDMDRV_ASSERT_OTHER(pDrvIns) pDrvIns->CTX_SUFF(pDrvHlp)->pfnAssertOther(pDrvIns, __FILE__, __LINE__, __FUNCTION__)
905#else
906# define PDMDRV_ASSERT_OTHER(pDrvIns) do { } while (0)
907#endif
908
909
910#ifdef IN_RING3
911
912/**
913 * @copydoc PDMDRVHLP::pfnAttach
914 */
915DECLINLINE(int) PDMDrvHlpAttach(PPDMDRVINS pDrvIns, uint32_t fFlags, PPDMIBASE *ppBaseInterface)
916{
917 return pDrvIns->pDrvHlpR3->pfnAttach(pDrvIns, fFlags, ppBaseInterface);
918}
919
920/**
921 * Check that there is no driver below the us that we should attach to.
922 *
923 * @returns VERR_PDM_NO_ATTACHED_DRIVER if there is no driver.
924 * @param pDrvIns The driver instance.
925 */
926DECLINLINE(int) PDMDrvHlpNoAttach(PPDMDRVINS pDrvIns)
927{
928 return pDrvIns->pDrvHlpR3->pfnAttach(pDrvIns, 0, NULL);
929}
930
931/**
932 * @copydoc PDMDRVHLP::pfnDetach
933 */
934DECLINLINE(int) PDMDrvHlpDetach(PPDMDRVINS pDrvIns, uint32_t fFlags)
935{
936 return pDrvIns->pDrvHlpR3->pfnDetach(pDrvIns, fFlags);
937}
938
939/**
940 * @copydoc PDMDRVHLP::pfnDetachSelf
941 */
942DECLINLINE(int) PDMDrvHlpDetachSelf(PPDMDRVINS pDrvIns, uint32_t fFlags)
943{
944 return pDrvIns->pDrvHlpR3->pfnDetachSelf(pDrvIns, fFlags);
945}
946
947/**
948 * @copydoc PDMDRVHLP::pfnMountPrepare
949 */
950DECLINLINE(int) PDMDrvHlpMountPrepare(PPDMDRVINS pDrvIns, const char *pszFilename, const char *pszCoreDriver)
951{
952 return pDrvIns->pDrvHlpR3->pfnMountPrepare(pDrvIns, pszFilename, pszCoreDriver);
953}
954
955/**
956 * @copydoc PDMDRVHLP::pfnVMState
957 */
958DECLINLINE(VMSTATE) PDMDrvHlpVMState(PPDMDRVINS pDrvIns)
959{
960 return pDrvIns->CTX_SUFF(pDrvHlp)->pfnVMState(pDrvIns);
961}
962
963/**
964 * @copydoc PDMDRVHLP::pfnVMTeleportedAndNotFullyResumedYet
965 */
966DECLINLINE(bool) PDMDrvHlpVMTeleportedAndNotFullyResumedYet(PPDMDRVINS pDrvIns)
967{
968 return pDrvIns->pDrvHlpR3->pfnVMTeleportedAndNotFullyResumedYet(pDrvIns);
969}
970
971/**
972 * @copydoc PDMDRVHLP::pfnPDMQueueCreate
973 */
974DECLINLINE(int) PDMDrvHlpPDMQueueCreate(PPDMDRVINS pDrvIns, RTUINT cbItem, RTUINT cItems, uint32_t cMilliesInterval,
975 PFNPDMQUEUEDRV pfnCallback, const char *pszName, PPDMQUEUE *ppQueue)
976{
977 return pDrvIns->pDrvHlpR3->pfnPDMQueueCreate(pDrvIns, cbItem, cItems, cMilliesInterval, pfnCallback, pszName, ppQueue);
978}
979
980/**
981 * @copydoc PDMDRVHLP::pfnTMGetVirtualFreq
982 */
983DECLINLINE(uint64_t) PDMDrvHlpTMGetVirtualFreq(PPDMDRVINS pDrvIns)
984{
985 return pDrvIns->pDrvHlpR3->pfnTMGetVirtualFreq(pDrvIns);
986}
987
988/**
989 * @copydoc PDMDRVHLP::pfnTMGetVirtualTime
990 */
991DECLINLINE(uint64_t) PDMDrvHlpTMGetVirtualTime(PPDMDRVINS pDrvIns)
992{
993 return pDrvIns->pDrvHlpR3->pfnTMGetVirtualTime(pDrvIns);
994}
995
996/**
997 * @copydoc PDMDRVHLP::pfnTMTimerCreate
998 */
999DECLINLINE(int) PDMDrvHlpTMTimerCreate(PPDMDRVINS pDrvIns, TMCLOCK enmClock, PFNTMTIMERDRV pfnCallback, void *pvUser, uint32_t fFlags, const char *pszDesc, PPTMTIMERR3 ppTimer)
1000{
1001 return pDrvIns->pDrvHlpR3->pfnTMTimerCreate(pDrvIns, enmClock, pfnCallback, pvUser, fFlags, pszDesc, ppTimer);
1002}
1003
1004/**
1005 * Register a save state data unit.
1006 *
1007 * @returns VBox status.
1008 * @param pDrvIns Driver instance.
1009 * @param uVersion Data layout version number.
1010 * @param cbGuess The approximate amount of data in the unit.
1011 * Only for progress indicators.
1012 * @param pfnSaveExec Execute save callback, optional.
1013 * @param pfnLoadExec Execute load callback, optional.
1014 */
1015DECLINLINE(int) PDMDrvHlpSSMRegister(PPDMDRVINS pDrvIns, uint32_t uVersion, size_t cbGuess,
1016 PFNSSMDRVSAVEEXEC pfnSaveExec, PFNSSMDRVLOADEXEC pfnLoadExec)
1017{
1018 return pDrvIns->pDrvHlpR3->pfnSSMRegister(pDrvIns, uVersion, cbGuess,
1019 NULL /*pfnLivePrep*/, NULL /*pfnLiveExec*/, NULL /*pfnLiveVote*/,
1020 NULL /*pfnSavePrep*/, pfnSaveExec, NULL /*pfnSaveDone*/,
1021 NULL /*pfnLoadPrep*/, pfnLoadExec, NULL /*pfnLoadDone*/);
1022}
1023
1024/**
1025 * @copydoc PDMDRVHLP::pfnSSMRegister
1026 */
1027DECLINLINE(int) PDMDrvHlpSSMRegisterEx(PPDMDRVINS pDrvIns, uint32_t uVersion, size_t cbGuess,
1028 PFNSSMDRVLIVEPREP pfnLivePrep, PFNSSMDRVLIVEEXEC pfnLiveExec, PFNSSMDRVLIVEVOTE pfnLiveVote,
1029 PFNSSMDRVSAVEPREP pfnSavePrep, PFNSSMDRVSAVEEXEC pfnSaveExec, PFNSSMDRVSAVEDONE pfnSaveDone,
1030 PFNSSMDRVLOADPREP pfnLoadPrep, PFNSSMDRVLOADEXEC pfnLoadExec, PFNSSMDRVLOADDONE pfnLoadDone)
1031{
1032 return pDrvIns->pDrvHlpR3->pfnSSMRegister(pDrvIns, uVersion, cbGuess,
1033 pfnLivePrep, pfnLiveExec, pfnLiveVote,
1034 pfnSavePrep, pfnSaveExec, pfnSaveDone,
1035 pfnLoadPrep, pfnLoadExec, pfnLoadDone);
1036}
1037
1038/**
1039 * Register a load done callback.
1040 *
1041 * @returns VBox status.
1042 * @param pDrvIns Driver instance.
1043 * @param pfnLoadDone Done load callback, optional.
1044 */
1045DECLINLINE(int) PDMDrvHlpSSMRegisterLoadDone(PPDMDRVINS pDrvIns, PFNSSMDRVLOADDONE pfnLoadDone)
1046{
1047 return pDrvIns->pDrvHlpR3->pfnSSMRegister(pDrvIns, 0 /*uVersion*/, 0 /*cbGuess*/,
1048 NULL /*pfnLivePrep*/, NULL /*pfnLiveExec*/, NULL /*pfnLiveVote*/,
1049 NULL /*pfnSavePrep*/, NULL /*pfnSaveExec*/, NULL /*pfnSaveDone*/,
1050 NULL /*pfnLoadPrep*/, NULL /*pfnLoadExec*/, pfnLoadDone);
1051}
1052
1053/**
1054 * @copydoc PDMDRVHLP::pfnSTAMRegister
1055 */
1056DECLINLINE(void) PDMDrvHlpSTAMRegister(PPDMDRVINS pDrvIns, void *pvSample, STAMTYPE enmType, const char *pszName, STAMUNIT enmUnit, const char *pszDesc)
1057{
1058 pDrvIns->pDrvHlpR3->pfnSTAMRegister(pDrvIns, pvSample, enmType, pszName, enmUnit, pszDesc);
1059}
1060
1061/**
1062 * @copydoc PDMDRVHLP::pfnSTAMRegisterF
1063 */
1064DECLINLINE(void) PDMDrvHlpSTAMRegisterF(PPDMDRVINS pDrvIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility, STAMUNIT enmUnit,
1065 const char *pszDesc, const char *pszName, ...)
1066{
1067 va_list va;
1068 va_start(va, pszName);
1069 pDrvIns->pDrvHlpR3->pfnSTAMRegisterV(pDrvIns, pvSample, enmType, enmVisibility, enmUnit, pszDesc, pszName, va);
1070 va_end(va);
1071}
1072
1073/**
1074 * @copydoc PDMDRVHLP::pfnSTAMDeregister
1075 */
1076DECLINLINE(int) PDMDrvHlpSTAMDeregister(PPDMDRVINS pDrvIns, void *pvSample)
1077{
1078 return pDrvIns->pDrvHlpR3->pfnSTAMDeregister(pDrvIns, pvSample);
1079}
1080
1081/**
1082 * @copydoc PDMDRVHLP::pfnSUPCallVMMR0Ex
1083 */
1084DECLINLINE(int) PDMDrvHlpSUPCallVMMR0Ex(PPDMDRVINS pDrvIns, unsigned uOperation, void *pvArg, unsigned cbArg)
1085{
1086 return pDrvIns->pDrvHlpR3->pfnSUPCallVMMR0Ex(pDrvIns, uOperation, pvArg, cbArg);
1087}
1088
1089/**
1090 * @copydoc PDMDRVHLP::pfnUSBRegisterHub
1091 */
1092DECLINLINE(int) PDMDrvHlpUSBRegisterHub(PPDMDRVINS pDrvIns, uint32_t fVersions, uint32_t cPorts, PCPDMUSBHUBREG pUsbHubReg, PPCPDMUSBHUBHLP ppUsbHubHlp)
1093{
1094 return pDrvIns->pDrvHlpR3->pfnUSBRegisterHub(pDrvIns, fVersions, cPorts, pUsbHubReg, ppUsbHubHlp);
1095}
1096
1097/**
1098 * @copydoc PDMDRVHLP::pfnSetAsyncNotification
1099 */
1100DECLINLINE(int) PDMDrvHlpSetAsyncNotification(PPDMDRVINS pDrvIns, PFNPDMDRVASYNCNOTIFY pfnAsyncNotify)
1101{
1102 return pDrvIns->pDrvHlpR3->pfnSetAsyncNotification(pDrvIns, pfnAsyncNotify);
1103}
1104
1105/**
1106 * @copydoc PDMDRVHLP::pfnAsyncNotificationCompleted
1107 */
1108DECLINLINE(void) PDMDrvHlpAsyncNotificationCompleted(PPDMDRVINS pDrvIns)
1109{
1110 pDrvIns->pDrvHlpR3->pfnAsyncNotificationCompleted(pDrvIns);
1111}
1112
1113/**
1114 * @copydoc PDMDRVHLP::pfnPDMThreadCreate
1115 */
1116DECLINLINE(int) PDMDrvHlpPDMThreadCreate(PPDMDRVINS pDrvIns, PPPDMTHREAD ppThread, void *pvUser, PFNPDMTHREADDRV pfnThread,
1117 PFNPDMTHREADWAKEUPDRV pfnWakeup, size_t cbStack, RTTHREADTYPE enmType, const char *pszName)
1118{
1119 return pDrvIns->pDrvHlpR3->pfnPDMThreadCreate(pDrvIns, ppThread, pvUser, pfnThread, pfnWakeup, cbStack, enmType, pszName);
1120}
1121
1122# ifdef VBOX_WITH_PDM_ASYNC_COMPLETION
1123/**
1124 * @copydoc PDMDRVHLP::pfnPDMAsyncCompletionTemplateCreate
1125 */
1126DECLINLINE(int) PDMDrvHlpPDMAsyncCompletionTemplateCreate(PPDMDRVINS pDrvIns, PPPDMASYNCCOMPLETIONTEMPLATE ppTemplate,
1127 PFNPDMASYNCCOMPLETEDRV pfnCompleted, void *pvTemplateUser, const char *pszDesc)
1128{
1129 return pDrvIns->pDrvHlpR3->pfnPDMAsyncCompletionTemplateCreate(pDrvIns, ppTemplate, pfnCompleted, pvTemplateUser, pszDesc);
1130}
1131# endif
1132
1133
1134/** Pointer to callbacks provided to the VBoxDriverRegister() call. */
1135typedef struct PDMDRVREGCB *PPDMDRVREGCB;
1136/** Pointer to const callbacks provided to the VBoxDriverRegister() call. */
1137typedef const struct PDMDRVREGCB *PCPDMDRVREGCB;
1138
1139/**
1140 * Callbacks for VBoxDriverRegister().
1141 */
1142typedef struct PDMDRVREGCB
1143{
1144 /** Interface version.
1145 * This is set to PDM_DRVREG_CB_VERSION. */
1146 uint32_t u32Version;
1147
1148 /**
1149 * Registers a driver with the current VM instance.
1150 *
1151 * @returns VBox status code.
1152 * @param pCallbacks Pointer to the callback table.
1153 * @param pDrvReg Pointer to the driver registration record.
1154 * This data must be permanent and readonly.
1155 */
1156 DECLR3CALLBACKMEMBER(int, pfnRegister,(PCPDMDRVREGCB pCallbacks, PCPDMDRVREG pDrvReg));
1157} PDMDRVREGCB;
1158
1159/** Current version of the PDMDRVREGCB structure. */
1160#define PDM_DRVREG_CB_VERSION UINT32_C(0xb0010000)
1161
1162
1163/**
1164 * The VBoxDriverRegister callback function.
1165 *
1166 * PDM will invoke this function after loading a driver module and letting
1167 * the module decide which drivers to register and how to handle conflicts.
1168 *
1169 * @returns VBox status code.
1170 * @param pCallbacks Pointer to the callback table.
1171 * @param u32Version VBox version number.
1172 */
1173typedef DECLCALLBACK(int) FNPDMVBOXDRIVERSREGISTER(PCPDMDRVREGCB pCallbacks, uint32_t u32Version);
1174
1175VMMR3DECL(int) PDMR3RegisterDrivers(PVM pVM, FNPDMVBOXDRIVERSREGISTER pfnCallback);
1176
1177#endif /* IN_RING3 */
1178
1179/** @} */
1180
1181RT_C_DECLS_END
1182
1183#endif
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