VirtualBox

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

Last change on this file since 34801 was 34222, checked in by vboxsync, 14 years ago

PDMDriver: Helper to create a block cache for drivers
  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 68.5 KB
Line 
1/** @file
2 * PDM - Pluggable Device Manager, Drivers. (VMM)
3 */
4
5/*
6 * Copyright (C) 2006-2010 Oracle Corporation
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_pdmdrv_h
27#define ___VBox_pdmdrv_h
28
29#include <VBox/pdmqueue.h>
30#include <VBox/pdmcritsect.h>
31#include <VBox/pdmthread.h>
32#include <VBox/pdmifs.h>
33#include <VBox/pdmins.h>
34#include <VBox/pdmcommon.h>
35#include <VBox/pdmasynccompletion.h>
36#include <VBox/pdmblkcache.h>
37#include <VBox/tm.h>
38#include <VBox/ssm.h>
39#include <VBox/cfgm.h>
40#include <VBox/dbgf.h>
41#include <VBox/mm.h>
42#include <VBox/err.h>
43#include <VBox/ftm.h>
44#include <iprt/stdarg.h>
45
46RT_C_DECLS_BEGIN
47
48/** @defgroup grp_pdm_driver The PDM Drivers API
49 * @ingroup grp_pdm
50 * @{
51 */
52
53/** Pointer const PDM Driver API, ring-3. */
54typedef R3PTRTYPE(struct PDMDRVHLPR3 const *) PCPDMDRVHLPR3;
55/** Pointer const PDM Driver API, ring-0. */
56typedef R0PTRTYPE(struct PDMDRVHLPR0 const *) PCPDMDRVHLPR0;
57/** Pointer const PDM Driver API, raw-mode context. */
58typedef RCPTRTYPE(struct PDMDRVHLPRC const *) PCPDMDRVHLPRC;
59
60
61/**
62 * Construct a driver instance for a VM.
63 *
64 * @returns VBox status.
65 * @param pDrvIns The driver instance data. If the registration structure
66 * is needed, it can be accessed thru pDrvIns->pReg.
67 * @param pCfg Configuration node handle for the driver. This is
68 * expected to be in high demand in the constructor and is
69 * therefore passed as an argument. When using it at other
70 * times, it can be accessed via pDrvIns->pCfg.
71 * @param fFlags Flags, combination of the PDM_TACH_FLAGS_* \#defines.
72 */
73typedef DECLCALLBACK(int) FNPDMDRVCONSTRUCT(PPDMDRVINS pDrvIns, PCFGMNODE pCfg, uint32_t fFlags);
74/** Pointer to a FNPDMDRVCONSTRUCT() function. */
75typedef FNPDMDRVCONSTRUCT *PFNPDMDRVCONSTRUCT;
76
77/**
78 * Destruct a driver instance.
79 *
80 * Most VM resources are freed by the VM. This callback is provided so that
81 * any non-VM resources can be freed correctly.
82 *
83 * @param pDrvIns The driver instance data.
84 */
85typedef DECLCALLBACK(void) FNPDMDRVDESTRUCT(PPDMDRVINS pDrvIns);
86/** Pointer to a FNPDMDRVDESTRUCT() function. */
87typedef FNPDMDRVDESTRUCT *PFNPDMDRVDESTRUCT;
88
89/**
90 * Driver relocation callback.
91 *
92 * This is called when the instance data has been relocated in raw-mode context
93 * (RC). It is also called when the RC hypervisor selects changes. The driver
94 * must fixup all necessary pointers and re-query all interfaces to other RC
95 * devices and drivers.
96 *
97 * Before the RC code is executed the first time, this function will be called
98 * with a 0 delta so RC pointer calculations can be one in one place.
99 *
100 * @param pDrvIns Pointer to the driver instance.
101 * @param offDelta The relocation delta relative to the old location.
102 *
103 * @remark A relocation CANNOT fail.
104 */
105typedef DECLCALLBACK(void) FNPDMDRVRELOCATE(PPDMDRVINS pDrvIns, RTGCINTPTR offDelta);
106/** Pointer to a FNPDMDRVRELOCATE() function. */
107typedef FNPDMDRVRELOCATE *PFNPDMDRVRELOCATE;
108
109/**
110 * Driver I/O Control interface.
111 *
112 * This is used by external components, such as the COM interface, to
113 * communicate with a driver using a driver specific interface. Generally,
114 * the driver interfaces are used for this task.
115 *
116 * @returns VBox status code.
117 * @param pDrvIns Pointer to the driver instance.
118 * @param uFunction Function to perform.
119 * @param pvIn Pointer to input data.
120 * @param cbIn Size of input data.
121 * @param pvOut Pointer to output data.
122 * @param cbOut Size of output data.
123 * @param pcbOut Where to store the actual size of the output data.
124 */
125typedef DECLCALLBACK(int) FNPDMDRVIOCTL(PPDMDRVINS pDrvIns, uint32_t uFunction,
126 void *pvIn, uint32_t cbIn,
127 void *pvOut, uint32_t cbOut, uint32_t *pcbOut);
128/** Pointer to a FNPDMDRVIOCTL() function. */
129typedef FNPDMDRVIOCTL *PFNPDMDRVIOCTL;
130
131/**
132 * Power On notification.
133 *
134 * @param pDrvIns The driver instance data.
135 */
136typedef DECLCALLBACK(void) FNPDMDRVPOWERON(PPDMDRVINS pDrvIns);
137/** Pointer to a FNPDMDRVPOWERON() function. */
138typedef FNPDMDRVPOWERON *PFNPDMDRVPOWERON;
139
140/**
141 * Reset notification.
142 *
143 * @returns VBox status.
144 * @param pDrvIns The driver instance data.
145 */
146typedef DECLCALLBACK(void) FNPDMDRVRESET(PPDMDRVINS pDrvIns);
147/** Pointer to a FNPDMDRVRESET() function. */
148typedef FNPDMDRVRESET *PFNPDMDRVRESET;
149
150/**
151 * Suspend notification.
152 *
153 * @returns VBox status.
154 * @param pDrvIns The driver instance data.
155 */
156typedef DECLCALLBACK(void) FNPDMDRVSUSPEND(PPDMDRVINS pDrvIns);
157/** Pointer to a FNPDMDRVSUSPEND() function. */
158typedef FNPDMDRVSUSPEND *PFNPDMDRVSUSPEND;
159
160/**
161 * Resume notification.
162 *
163 * @returns VBox status.
164 * @param pDrvIns The driver instance data.
165 */
166typedef DECLCALLBACK(void) FNPDMDRVRESUME(PPDMDRVINS pDrvIns);
167/** Pointer to a FNPDMDRVRESUME() function. */
168typedef FNPDMDRVRESUME *PFNPDMDRVRESUME;
169
170/**
171 * Power Off notification.
172 *
173 * This is only called when the VMR3PowerOff call is made on a running VM. This
174 * means that there is no notification if the VM was suspended before being
175 * powered of. There will also be no callback when hot plugging devices or when
176 * replumbing the driver stack.
177 *
178 * @param pDrvIns The driver instance data.
179 */
180typedef DECLCALLBACK(void) FNPDMDRVPOWEROFF(PPDMDRVINS pDrvIns);
181/** Pointer to a FNPDMDRVPOWEROFF() function. */
182typedef FNPDMDRVPOWEROFF *PFNPDMDRVPOWEROFF;
183
184/**
185 * Attach command.
186 *
187 * This is called to let the drive attach to a driver at runtime. This is not
188 * called during VM construction, the driver constructor have to do this by
189 * calling PDMDrvHlpAttach.
190 *
191 * This is like plugging in the keyboard or mouse after turning on the PC.
192 *
193 * @returns VBox status code.
194 * @param pDrvIns The driver instance.
195 * @param fFlags Flags, combination of the PDM_TACH_FLAGS_* \#defines.
196 */
197typedef DECLCALLBACK(int) FNPDMDRVATTACH(PPDMDRVINS pDrvIns, uint32_t fFlags);
198/** Pointer to a FNPDMDRVATTACH() function. */
199typedef FNPDMDRVATTACH *PFNPDMDRVATTACH;
200
201/**
202 * Detach notification.
203 *
204 * This is called when a driver below it in the chain is detaching itself
205 * from it. The driver should adjust it's state to reflect this.
206 *
207 * This is like ejecting a cdrom or floppy.
208 *
209 * @param pDrvIns The driver instance.
210 * @param fFlags PDM_TACH_FLAGS_NOT_HOT_PLUG or 0.
211 */
212typedef DECLCALLBACK(void) FNPDMDRVDETACH(PPDMDRVINS pDrvIns, uint32_t fFlags);
213/** Pointer to a FNPDMDRVDETACH() function. */
214typedef FNPDMDRVDETACH *PFNPDMDRVDETACH;
215
216
217
218/**
219 * PDM Driver Registration Structure.
220 *
221 * This structure is used when registering a driver from VBoxInitDrivers() (in
222 * host ring-3 context). PDM will continue use till the VM is terminated.
223 */
224typedef struct PDMDRVREG
225{
226 /** Structure version. PDM_DRVREG_VERSION defines the current version. */
227 uint32_t u32Version;
228 /** Driver name. */
229 char szName[32];
230 /** Name of the raw-mode context module (no path).
231 * Only evalutated if PDM_DRVREG_FLAGS_RC is set. */
232 char szRCMod[32];
233 /** Name of the ring-0 module (no path).
234 * Only evalutated if PDM_DRVREG_FLAGS_R0 is set. */
235 char szR0Mod[32];
236 /** The description of the driver. The UTF-8 string pointed to shall, like this structure,
237 * remain unchanged from registration till VM destruction. */
238 const char *pszDescription;
239
240 /** Flags, combination of the PDM_DRVREG_FLAGS_* \#defines. */
241 uint32_t fFlags;
242 /** Driver class(es), combination of the PDM_DRVREG_CLASS_* \#defines. */
243 uint32_t fClass;
244 /** Maximum number of instances (per VM). */
245 uint32_t cMaxInstances;
246 /** Size of the instance data. */
247 uint32_t cbInstance;
248
249 /** Construct instance - required. */
250 PFNPDMDRVCONSTRUCT pfnConstruct;
251 /** Destruct instance - optional. */
252 PFNPDMDRVDESTRUCT pfnDestruct;
253 /** Relocation command - optional. */
254 PFNPDMDRVRELOCATE pfnRelocate;
255 /** I/O control - optional. */
256 PFNPDMDRVIOCTL pfnIOCtl;
257 /** Power on notification - optional. */
258 PFNPDMDRVPOWERON pfnPowerOn;
259 /** Reset notification - optional. */
260 PFNPDMDRVRESET pfnReset;
261 /** Suspend notification - optional. */
262 PFNPDMDRVSUSPEND pfnSuspend;
263 /** Resume notification - optional. */
264 PFNPDMDRVRESUME pfnResume;
265 /** Attach command - optional. */
266 PFNPDMDRVATTACH pfnAttach;
267 /** Detach notification - optional. */
268 PFNPDMDRVDETACH pfnDetach;
269 /** Power off notification - optional. */
270 PFNPDMDRVPOWEROFF pfnPowerOff;
271 /** @todo */
272 PFNRT pfnSoftReset;
273 /** Initialization safty marker. */
274 uint32_t u32VersionEnd;
275} PDMDRVREG;
276/** Pointer to a PDM Driver Structure. */
277typedef PDMDRVREG *PPDMDRVREG;
278/** Const pointer to a PDM Driver Structure. */
279typedef PDMDRVREG const *PCPDMDRVREG;
280
281/** Current DRVREG version number. */
282#define PDM_DRVREG_VERSION PDM_VERSION_MAKE(0xf0ff, 1, 0)
283
284/** PDM Driver Flags.
285 * @{ */
286/** @def PDM_DRVREG_FLAGS_HOST_BITS_DEFAULT
287 * The bit count for the current host. */
288#if HC_ARCH_BITS == 32
289# define PDM_DRVREG_FLAGS_HOST_BITS_DEFAULT UINT32_C(0x00000001)
290#elif HC_ARCH_BITS == 64
291# define PDM_DRVREG_FLAGS_HOST_BITS_DEFAULT UINT32_C(0x00000002)
292#else
293# error Unsupported HC_ARCH_BITS value.
294#endif
295/** The host bit count mask. */
296#define PDM_DRVREG_FLAGS_HOST_BITS_MASK UINT32_C(0x00000003)
297/** This flag is used to indicate that the driver has a RC component. */
298#define PDM_DRVREG_FLAGS_RC UINT32_C(0x00000010)
299/** This flag is used to indicate that the driver has a R0 component. */
300#define PDM_DRVREG_FLAGS_R0 UINT32_C(0x00000020)
301
302/** @} */
303
304
305/** PDM Driver Classes.
306 * @{ */
307/** Mouse input driver. */
308#define PDM_DRVREG_CLASS_MOUSE RT_BIT(0)
309/** Keyboard input driver. */
310#define PDM_DRVREG_CLASS_KEYBOARD RT_BIT(1)
311/** Display driver. */
312#define PDM_DRVREG_CLASS_DISPLAY RT_BIT(2)
313/** Network transport driver. */
314#define PDM_DRVREG_CLASS_NETWORK RT_BIT(3)
315/** Block driver. */
316#define PDM_DRVREG_CLASS_BLOCK RT_BIT(4)
317/** Media driver. */
318#define PDM_DRVREG_CLASS_MEDIA RT_BIT(5)
319/** Mountable driver. */
320#define PDM_DRVREG_CLASS_MOUNTABLE RT_BIT(6)
321/** Audio driver. */
322#define PDM_DRVREG_CLASS_AUDIO RT_BIT(7)
323/** VMMDev driver. */
324#define PDM_DRVREG_CLASS_VMMDEV RT_BIT(8)
325/** Status driver. */
326#define PDM_DRVREG_CLASS_STATUS RT_BIT(9)
327/** ACPI driver. */
328#define PDM_DRVREG_CLASS_ACPI RT_BIT(10)
329/** USB related driver. */
330#define PDM_DRVREG_CLASS_USB RT_BIT(11)
331/** ISCSI Transport related driver. */
332#define PDM_DRVREG_CLASS_ISCSITRANSPORT RT_BIT(12)
333/** Char driver. */
334#define PDM_DRVREG_CLASS_CHAR RT_BIT(13)
335/** Stream driver. */
336#define PDM_DRVREG_CLASS_STREAM RT_BIT(14)
337/** SCSI driver. */
338#define PDM_DRVREG_CLASS_SCSI RT_BIT(15)
339/** @} */
340
341
342/**
343 * PDM Driver Instance.
344 *
345 * @implements PDMIBASE
346 */
347typedef struct PDMDRVINS
348{
349 /** Structure version. PDM_DRVINS_VERSION defines the current version. */
350 uint32_t u32Version;
351 /** Driver instance number. */
352 uint32_t iInstance;
353
354 /** Pointer the PDM Driver API. */
355 RCPTRTYPE(PCPDMDRVHLPRC) pHlpRC;
356 /** Pointer to driver instance data. */
357 RCPTRTYPE(void *) pvInstanceDataRC;
358
359 /** Pointer the PDM Driver API. */
360 R0PTRTYPE(PCPDMDRVHLPR0) pHlpR0;
361 /** Pointer to driver instance data. */
362 R0PTRTYPE(void *) pvInstanceDataR0;
363
364 /** Pointer the PDM Driver API. */
365 R3PTRTYPE(PCPDMDRVHLPR3) pHlpR3;
366 /** Pointer to driver instance data. */
367 R3PTRTYPE(void *) pvInstanceDataR3;
368
369 /** Pointer to driver registration structure. */
370 R3PTRTYPE(PCPDMDRVREG) pReg;
371 /** Configuration handle. */
372 R3PTRTYPE(PCFGMNODE) pCfg;
373
374 /** Pointer to the base interface of the device/driver instance above. */
375 R3PTRTYPE(PPDMIBASE) pUpBase;
376 /** Pointer to the base interface of the driver instance below. */
377 R3PTRTYPE(PPDMIBASE) pDownBase;
378
379 /** The base interface of the driver.
380 * The driver constructor initializes this. */
381 PDMIBASE IBase;
382 /** Align the internal data more naturally. */
383 RTR3PTR R3PtrPadding;
384
385 /** Internal data. */
386 union
387 {
388#ifdef PDMDRVINSINT_DECLARED
389 PDMDRVINSINT s;
390#endif
391 uint8_t padding[HC_ARCH_BITS == 32 ? 40 + 32 : 72 + 24];
392 } Internal;
393
394 /** Driver instance data. The size of this area is defined
395 * in the PDMDRVREG::cbInstanceData field. */
396 char achInstanceData[4];
397} PDMDRVINS;
398
399/** Current DRVREG version number. */
400#define PDM_DRVINS_VERSION PDM_VERSION_MAKE(0xf0fe, 1, 0)
401
402/** Converts a pointer to the PDMDRVINS::IBase to a pointer to PDMDRVINS. */
403#define PDMIBASE_2_PDMDRV(pInterface) ( (PPDMDRVINS)((char *)(pInterface) - RT_OFFSETOF(PDMDRVINS, IBase)) )
404
405/** @def PDMDRVINS_2_RCPTR
406 * Converts a PDM Driver instance pointer a RC PDM Driver instance pointer.
407 */
408#define PDMDRVINS_2_RCPTR(pDrvIns) ( (RCPTRTYPE(PPDMDRVINS))((RTGCUINTPTR)(pDrvIns)->pvInstanceDataRC - RT_OFFSETOF(PDMDRVINS, achInstanceData)) )
409
410/** @def PDMDRVINS_2_R3PTR
411 * Converts a PDM Driver instance pointer a R3 PDM Driver instance pointer.
412 */
413#define PDMDRVINS_2_R3PTR(pDrvIns) ( (R3PTRTYPE(PPDMDRVINS))((RTHCUINTPTR)(pDrvIns)->pvInstanceDataR3 - RT_OFFSETOF(PDMDRVINS, achInstanceData)) )
414
415/** @def PDMDRVINS_2_R0PTR
416 * Converts a PDM Driver instance pointer a R0 PDM Driver instance pointer.
417 */
418#define PDMDRVINS_2_R0PTR(pDrvIns) ( (R0PTRTYPE(PPDMDRVINS))((RTR0UINTPTR)(pDrvIns)->pvInstanceDataR0 - RT_OFFSETOF(PDMDRVINS, achInstanceData)) )
419
420
421
422/**
423 * Checks the structure versions of the drive instance and driver helpers,
424 * returning if they are incompatible.
425 *
426 * Intended for the constructor.
427 *
428 * @param pDrvIns Pointer to the PDM driver instance.
429 */
430#define PDMDRV_CHECK_VERSIONS_RETURN(pDrvIns) \
431 do \
432 { \
433 PPDMDRVINS pDrvInsTypeCheck = (pDrvIns); NOREF(pDrvInsTypeCheck); \
434 AssertLogRelMsgReturn(PDM_VERSION_ARE_COMPATIBLE((pDrvIns)->u32Version, PDM_DRVINS_VERSION), \
435 ("DrvIns=%#x mine=%#x\n", (pDrvIns)->u32Version, PDM_DRVINS_VERSION), \
436 VERR_VERSION_MISMATCH); \
437 AssertLogRelMsgReturn(PDM_VERSION_ARE_COMPATIBLE((pDrvIns)->pHlpR3->u32Version, PDM_DRVHLPR3_VERSION), \
438 ("DrvHlp=%#x mine=%#x\n", (pDrvIns)->pHlpR3->u32Version, PDM_DRVHLPR3_VERSION), \
439 VERR_VERSION_MISMATCH); \
440 } while (0)
441
442/**
443 * Quietly checks the structure versions of the drive instance and driver
444 * helpers, returning if they are incompatible.
445 *
446 * Intended for the destructor.
447 *
448 * @param pDrvIns Pointer to the PDM driver instance.
449 */
450#define PDMDRV_CHECK_VERSIONS_RETURN_VOID(pDrvIns) \
451 do \
452 { \
453 PPDMDRVINS pDrvInsTypeCheck = (pDrvIns); NOREF(pDrvInsTypeCheck); \
454 if (RT_UNLIKELY( !PDM_VERSION_ARE_COMPATIBLE((pDrvIns)->u32Version, PDM_DRVINS_VERSION) \
455 || !PDM_VERSION_ARE_COMPATIBLE((pDrvIns)->pHlpR3->u32Version, PDM_DRVHLPR3_VERSION)) ) \
456 return; \
457 } while (0)
458
459/**
460 * Wrapper around CFGMR3ValidateConfig for the root config for use in the
461 * constructor - returns on failure.
462 *
463 * This should be invoked after having initialized the instance data
464 * sufficiently for the correct operation of the destructor. The destructor is
465 * always called!
466 *
467 * @param pDrvIns Pointer to the PDM driver instance.
468 * @param pszValidValues Patterns describing the valid value names. See
469 * RTStrSimplePatternMultiMatch for details on the
470 * pattern syntax.
471 * @param pszValidNodes Patterns describing the valid node (key) names.
472 * Pass empty string if no valid nodess.
473 */
474#define PDMDRV_VALIDATE_CONFIG_RETURN(pDrvIns, pszValidValues, pszValidNodes) \
475 do \
476 { \
477 int rcValCfg = CFGMR3ValidateConfig((pDrvIns)->pCfg, "/", pszValidValues, pszValidNodes, \
478 (pDrvIns)->pReg->szName, (pDrvIns)->iInstance); \
479 if (RT_FAILURE(rcValCfg)) \
480 return rcValCfg; \
481 } while (0)
482
483
484
485/**
486 * USB hub registration structure.
487 */
488typedef struct PDMUSBHUBREG
489{
490 /** Structure version number. PDM_USBHUBREG_VERSION defines the current version. */
491 uint32_t u32Version;
492
493 /**
494 * Request the hub to attach of the specified device.
495 *
496 * @returns VBox status code.
497 * @param pDrvIns The hub instance.
498 * @param pUsbIns The device to attach.
499 * @param piPort Where to store the port number the device was attached to.
500 * @thread EMT.
501 */
502 DECLR3CALLBACKMEMBER(int, pfnAttachDevice,(PPDMDRVINS pDrvIns, PPDMUSBINS pUsbIns, uint32_t *piPort));
503
504 /**
505 * Request the hub to detach of the specified device.
506 *
507 * The device has previously been attached to the hub with the
508 * pfnAttachDevice call. This call is not currently expected to
509 * fail.
510 *
511 * @returns VBox status code.
512 * @param pDrvIns The hub instance.
513 * @param pUsbIns The device to detach.
514 * @param iPort The port number returned by the attach call.
515 * @thread EMT.
516 */
517 DECLR3CALLBACKMEMBER(int, pfnDetachDevice,(PPDMDRVINS pDrvIns, PPDMUSBINS pUsbIns, uint32_t iPort));
518
519 /** Counterpart to u32Version, same value. */
520 uint32_t u32TheEnd;
521} PDMUSBHUBREG;
522/** Pointer to a const USB hub registration structure. */
523typedef const PDMUSBHUBREG *PCPDMUSBHUBREG;
524
525/** Current PDMUSBHUBREG version number. */
526#define PDM_USBHUBREG_VERSION PDM_VERSION_MAKE(0xf0fd, 1, 0)
527
528
529/**
530 * USB hub helpers.
531 * This is currently just a place holder.
532 */
533typedef struct PDMUSBHUBHLP
534{
535 /** Structure version. PDM_USBHUBHLP_VERSION defines the current version. */
536 uint32_t u32Version;
537
538 /** Just a safety precaution. */
539 uint32_t u32TheEnd;
540} PDMUSBHUBHLP;
541/** Pointer to PCI helpers. */
542typedef PDMUSBHUBHLP *PPDMUSBHUBHLP;
543/** Pointer to const PCI helpers. */
544typedef const PDMUSBHUBHLP *PCPDMUSBHUBHLP;
545/** Pointer to const PCI helpers pointer. */
546typedef PCPDMUSBHUBHLP *PPCPDMUSBHUBHLP;
547
548/** Current PDMUSBHUBHLP version number. */
549#define PDM_USBHUBHLP_VERSION PDM_VERSION_MAKE(0xf0fc, 1, 0)
550
551
552/**
553 * PDM Driver API - raw-mode context variant.
554 */
555typedef struct PDMDRVHLPRC
556{
557 /** Structure version. PDM_DRVHLPRC_VERSION defines the current version. */
558 uint32_t u32Version;
559
560 /**
561 * Set the VM error message
562 *
563 * @returns rc.
564 * @param pDrvIns Driver instance.
565 * @param rc VBox status code.
566 * @param RT_SRC_POS_DECL Use RT_SRC_POS.
567 * @param pszFormat Error message format string.
568 * @param ... Error message arguments.
569 */
570 DECLRCCALLBACKMEMBER(int, pfnVMSetError,(PPDMDRVINS pDrvIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, ...));
571
572 /**
573 * Set the VM error message
574 *
575 * @returns rc.
576 * @param pDrvIns Driver instance.
577 * @param rc VBox status code.
578 * @param RT_SRC_POS_DECL Use RT_SRC_POS.
579 * @param pszFormat Error message format string.
580 * @param va Error message arguments.
581 */
582 DECLRCCALLBACKMEMBER(int, pfnVMSetErrorV,(PPDMDRVINS pDrvIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va));
583
584 /**
585 * Set the VM runtime error message
586 *
587 * @returns VBox status code.
588 * @param pDrvIns Driver instance.
589 * @param fFlags The action flags. See VMSETRTERR_FLAGS_*.
590 * @param pszErrorId Error ID string.
591 * @param pszFormat Error message format string.
592 * @param ... Error message arguments.
593 */
594 DECLRCCALLBACKMEMBER(int, pfnVMSetRuntimeError,(PPDMDRVINS pDrvIns, uint32_t fFlags, const char *pszErrorId, const char *pszFormat, ...));
595
596 /**
597 * Set the VM runtime error message
598 *
599 * @returns VBox status code.
600 * @param pDrvIns Driver instance.
601 * @param fFlags The action flags. See VMSETRTERR_FLAGS_*.
602 * @param pszErrorId Error ID string.
603 * @param pszFormat Error message format string.
604 * @param va Error message arguments.
605 */
606 DECLRCCALLBACKMEMBER(int, pfnVMSetRuntimeErrorV,(PPDMDRVINS pDrvIns, uint32_t fFlags, const char *pszErrorId, const char *pszFormat, va_list va));
607
608 /**
609 * Assert that the current thread is the emulation thread.
610 *
611 * @returns True if correct.
612 * @returns False if wrong.
613 * @param pDrvIns Driver instance.
614 * @param pszFile Filename of the assertion location.
615 * @param iLine Linenumber of the assertion location.
616 * @param pszFunction Function of the assertion location.
617 */
618 DECLRCCALLBACKMEMBER(bool, pfnAssertEMT,(PPDMDRVINS pDrvIns, const char *pszFile, unsigned iLine, const char *pszFunction));
619
620 /**
621 * Assert that the current thread is NOT the emulation thread.
622 *
623 * @returns True if correct.
624 * @returns False if wrong.
625 * @param pDrvIns Driver instance.
626 * @param pszFile Filename of the assertion location.
627 * @param iLine Linenumber of the assertion location.
628 * @param pszFunction Function of the assertion location.
629 */
630 DECLRCCALLBACKMEMBER(bool, pfnAssertOther,(PPDMDRVINS pDrvIns, const char *pszFile, unsigned iLine, const char *pszFunction));
631
632 /**
633 * Notify FTM about a checkpoint occurrence
634 *
635 * @param pDrvIns The driver instance.
636 * @param enmType Checkpoint type
637 * @thread Any
638 */
639 DECLRCCALLBACKMEMBER(int, pfnFTSetCheckpoint,(PPDMDRVINS pDrvIns, FTMCHECKPOINTTYPE enmType));
640
641 /** Just a safety precaution. */
642 uint32_t u32TheEnd;
643} PDMDRVHLPRC;
644/** Current PDMDRVHLPRC version number. */
645#define PDM_DRVHLPRC_VERSION PDM_VERSION_MAKE(0xf0f9, 2, 0)
646
647
648/**
649 * PDM Driver API, ring-0 context.
650 */
651typedef struct PDMDRVHLPR0
652{
653 /** Structure version. PDM_DRVHLPR0_VERSION defines the current version. */
654 uint32_t u32Version;
655
656 /**
657 * Set the VM error message
658 *
659 * @returns rc.
660 * @param pDrvIns Driver instance.
661 * @param rc VBox status code.
662 * @param RT_SRC_POS_DECL Use RT_SRC_POS.
663 * @param pszFormat Error message format string.
664 * @param ... Error message arguments.
665 */
666 DECLR0CALLBACKMEMBER(int, pfnVMSetError,(PPDMDRVINS pDrvIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, ...));
667
668 /**
669 * Set the VM error message
670 *
671 * @returns rc.
672 * @param pDrvIns Driver instance.
673 * @param rc VBox status code.
674 * @param RT_SRC_POS_DECL Use RT_SRC_POS.
675 * @param pszFormat Error message format string.
676 * @param va Error message arguments.
677 */
678 DECLR0CALLBACKMEMBER(int, pfnVMSetErrorV,(PPDMDRVINS pDrvIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va));
679
680 /**
681 * Set the VM runtime error message
682 *
683 * @returns VBox status code.
684 * @param pDrvIns Driver instance.
685 * @param fFlags The action flags. See VMSETRTERR_FLAGS_*.
686 * @param pszErrorId Error ID string.
687 * @param pszFormat Error message format string.
688 * @param ... Error message arguments.
689 */
690 DECLR0CALLBACKMEMBER(int, pfnVMSetRuntimeError,(PPDMDRVINS pDrvIns, uint32_t fFlags, const char *pszErrorId, const char *pszFormat, ...));
691
692 /**
693 * Set the VM runtime error message
694 *
695 * @returns VBox status code.
696 * @param pDrvIns Driver instance.
697 * @param fFlags The action flags. See VMSETRTERR_FLAGS_*.
698 * @param pszErrorId Error ID string.
699 * @param pszFormat Error message format string.
700 * @param va Error message arguments.
701 */
702 DECLR0CALLBACKMEMBER(int, pfnVMSetRuntimeErrorV,(PPDMDRVINS pDrvIns, uint32_t fFlags, const char *pszErrorId, const char *pszFormat, va_list va));
703
704 /**
705 * Assert that the current thread is the emulation thread.
706 *
707 * @returns True if correct.
708 * @returns False if wrong.
709 * @param pDrvIns Driver instance.
710 * @param pszFile Filename of the assertion location.
711 * @param iLine Linenumber of the assertion location.
712 * @param pszFunction Function of the assertion location.
713 */
714 DECLR0CALLBACKMEMBER(bool, pfnAssertEMT,(PPDMDRVINS pDrvIns, const char *pszFile, unsigned iLine, const char *pszFunction));
715
716 /**
717 * Assert that the current thread is NOT the emulation thread.
718 *
719 * @returns True if correct.
720 * @returns False if wrong.
721 * @param pDrvIns Driver instance.
722 * @param pszFile Filename of the assertion location.
723 * @param iLine Linenumber of the assertion location.
724 * @param pszFunction Function of the assertion location.
725 */
726 DECLR0CALLBACKMEMBER(bool, pfnAssertOther,(PPDMDRVINS pDrvIns, const char *pszFile, unsigned iLine, const char *pszFunction));
727
728 /**
729 * Notify FTM about a checkpoint occurrence
730 *
731 * @param pDrvIns The driver instance.
732 * @param enmType Checkpoint type
733 * @thread Any
734 */
735 DECLR0CALLBACKMEMBER(int, pfnFTSetCheckpoint,(PPDMDRVINS pDrvIns, FTMCHECKPOINTTYPE enmType));
736
737 /** Just a safety precaution. */
738 uint32_t u32TheEnd;
739} PDMDRVHLPR0;
740/** Current DRVHLP version number. */
741#define PDM_DRVHLPR0_VERSION PDM_VERSION_MAKE(0xf0f8, 2, 0)
742
743
744#ifdef IN_RING3
745
746/**
747 * PDM Driver API.
748 */
749typedef struct PDMDRVHLPR3
750{
751 /** Structure version. PDM_DRVHLPR3_VERSION defines the current version. */
752 uint32_t u32Version;
753
754 /**
755 * Attaches a driver (chain) to the driver.
756 *
757 * @returns VBox status code.
758 * @param pDrvIns Driver instance.
759 * @param fFlags PDM_TACH_FLAGS_NOT_HOT_PLUG or 0.
760 * @param ppBaseInterface Where to store the pointer to the base interface.
761 */
762 DECLR3CALLBACKMEMBER(int, pfnAttach,(PPDMDRVINS pDrvIns, uint32_t fFlags, PPDMIBASE *ppBaseInterface));
763
764 /**
765 * Detach the driver the drivers below us.
766 *
767 * @returns VBox status code.
768 * @param pDrvIns Driver instance.
769 * @param fFlags PDM_TACH_FLAGS_NOT_HOT_PLUG or 0.
770 */
771 DECLR3CALLBACKMEMBER(int, pfnDetach,(PPDMDRVINS pDrvIns, uint32_t fFlags));
772
773 /**
774 * Detach the driver from the driver above it and destroy this
775 * driver and all drivers below it.
776 *
777 * @returns VBox status code.
778 * @param pDrvIns Driver instance.
779 * @param fFlags PDM_TACH_FLAGS_NOT_HOT_PLUG or 0.
780 */
781 DECLR3CALLBACKMEMBER(int, pfnDetachSelf,(PPDMDRVINS pDrvIns, uint32_t fFlags));
782
783 /**
784 * Prepare a media mount.
785 *
786 * The driver must not have anything attached to itself
787 * when calling this function as the purpose is to set up the configuration
788 * of an future attachment.
789 *
790 * @returns VBox status code
791 * @param pDrvIns Driver instance.
792 * @param pszFilename Pointer to filename. If this is NULL it assumed that the caller have
793 * constructed a configuration which can be attached to the bottom driver.
794 * @param pszCoreDriver Core driver name. NULL will cause autodetection. Ignored if pszFilanem is NULL.
795 */
796 DECLR3CALLBACKMEMBER(int, pfnMountPrepare,(PPDMDRVINS pDrvIns, const char *pszFilename, const char *pszCoreDriver));
797
798 /**
799 * Assert that the current thread is the emulation thread.
800 *
801 * @returns True if correct.
802 * @returns False if wrong.
803 * @param pDrvIns Driver instance.
804 * @param pszFile Filename of the assertion location.
805 * @param iLine Linenumber of the assertion location.
806 * @param pszFunction Function of the assertion location.
807 */
808 DECLR3CALLBACKMEMBER(bool, pfnAssertEMT,(PPDMDRVINS pDrvIns, const char *pszFile, unsigned iLine, const char *pszFunction));
809
810 /**
811 * Assert that the current thread is NOT the emulation thread.
812 *
813 * @returns True if correct.
814 * @returns False if wrong.
815 * @param pDrvIns Driver instance.
816 * @param pszFile Filename of the assertion location.
817 * @param iLine Linenumber of the assertion location.
818 * @param pszFunction Function of the assertion location.
819 */
820 DECLR3CALLBACKMEMBER(bool, pfnAssertOther,(PPDMDRVINS pDrvIns, const char *pszFile, unsigned iLine, const char *pszFunction));
821
822 /**
823 * Set the VM error message
824 *
825 * @returns rc.
826 * @param pDrvIns Driver instance.
827 * @param rc VBox status code.
828 * @param RT_SRC_POS_DECL Use RT_SRC_POS.
829 * @param pszFormat Error message format string.
830 * @param ... Error message arguments.
831 */
832 DECLR3CALLBACKMEMBER(int, pfnVMSetError,(PPDMDRVINS pDrvIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, ...));
833
834 /**
835 * Set the VM error message
836 *
837 * @returns rc.
838 * @param pDrvIns Driver instance.
839 * @param rc VBox status code.
840 * @param RT_SRC_POS_DECL Use RT_SRC_POS.
841 * @param pszFormat Error message format string.
842 * @param va Error message arguments.
843 */
844 DECLR3CALLBACKMEMBER(int, pfnVMSetErrorV,(PPDMDRVINS pDrvIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va));
845
846 /**
847 * Set the VM runtime error message
848 *
849 * @returns VBox status code.
850 * @param pDrvIns Driver instance.
851 * @param fFlags The action flags. See VMSETRTERR_FLAGS_*.
852 * @param pszErrorId Error ID string.
853 * @param pszFormat Error message format string.
854 * @param ... Error message arguments.
855 */
856 DECLR3CALLBACKMEMBER(int, pfnVMSetRuntimeError,(PPDMDRVINS pDrvIns, uint32_t fFlags, const char *pszErrorId, const char *pszFormat, ...));
857
858 /**
859 * Set the VM runtime error message
860 *
861 * @returns VBox status code.
862 * @param pDrvIns Driver instance.
863 * @param fFlags The action flags. See VMSETRTERR_FLAGS_*.
864 * @param pszErrorId Error ID string.
865 * @param pszFormat Error message format string.
866 * @param va Error message arguments.
867 */
868 DECLR3CALLBACKMEMBER(int, pfnVMSetRuntimeErrorV,(PPDMDRVINS pDrvIns, uint32_t fFlags, const char *pszErrorId, const char *pszFormat, va_list va));
869
870 /**
871 * Gets the VM state.
872 *
873 * @returns VM state.
874 * @param pDrvIns The driver instance.
875 * @thread Any thread (just keep in mind that it's volatile info).
876 */
877 DECLR3CALLBACKMEMBER(VMSTATE, pfnVMState, (PPDMDRVINS pDrvIns));
878
879 /**
880 * Checks if the VM was teleported and hasn't been fully resumed yet.
881 *
882 * @returns true / false.
883 * @param pDrvIns The driver instance.
884 * @thread Any thread.
885 */
886 DECLR3CALLBACKMEMBER(bool, pfnVMTeleportedAndNotFullyResumedYet,(PPDMDRVINS pDrvIns));
887
888 /**
889 * Gets the support driver session.
890 *
891 * This is intended for working using the semaphore API.
892 *
893 * @returns Support driver session handle.
894 * @param pDrvIns The driver instance.
895 */
896 DECLR3CALLBACKMEMBER(PSUPDRVSESSION, pfnGetSupDrvSession,(PPDMDRVINS pDrvIns));
897
898 /**
899 * Create a queue.
900 *
901 * @returns VBox status code.
902 * @param pDrvIns Driver instance.
903 * @param cbItem Size a queue item.
904 * @param cItems Number of items in the queue.
905 * @param cMilliesInterval Number of milliseconds between polling the queue.
906 * If 0 then the emulation thread will be notified whenever an item arrives.
907 * @param pfnCallback The consumer function.
908 * @param pszName The queue base name. The instance number will be
909 * appended automatically.
910 * @param ppQueue Where to store the queue handle on success.
911 * @thread The emulation thread.
912 */
913 DECLR3CALLBACKMEMBER(int, pfnQueueCreate,(PPDMDRVINS pDrvIns, uint32_t cbItem, uint32_t cItems, uint32_t cMilliesInterval,
914 PFNPDMQUEUEDRV pfnCallback, const char *pszName, PPDMQUEUE *ppQueue));
915
916 /**
917 * Query the virtual timer frequency.
918 *
919 * @returns Frequency in Hz.
920 * @param pDrvIns Driver instance.
921 * @thread Any thread.
922 */
923 DECLR3CALLBACKMEMBER(uint64_t, pfnTMGetVirtualFreq,(PPDMDRVINS pDrvIns));
924
925 /**
926 * Query the virtual time.
927 *
928 * @returns The current virtual time.
929 * @param pDrvIns Driver instance.
930 * @thread Any thread.
931 */
932 DECLR3CALLBACKMEMBER(uint64_t, pfnTMGetVirtualTime,(PPDMDRVINS pDrvIns));
933
934 /**
935 * Creates a timer.
936 *
937 * @returns VBox status.
938 * @param pDrvIns Driver instance.
939 * @param enmClock The clock to use on this timer.
940 * @param pfnCallback Callback function.
941 * @param pvUser The user argument to the callback.
942 * @param fFlags Timer creation flags, see grp_tm_timer_flags.
943 * @param pszDesc Pointer to description string which must stay around
944 * until the timer is fully destroyed (i.e. a bit after TMTimerDestroy()).
945 * @param ppTimer Where to store the timer on success.
946 * @thread EMT
947 */
948 DECLR3CALLBACKMEMBER(int, pfnTMTimerCreate,(PPDMDRVINS pDrvIns, TMCLOCK enmClock, PFNTMTIMERDRV pfnCallback, void *pvUser, uint32_t fFlags, const char *pszDesc, PPTMTIMERR3 ppTimer));
949
950 /**
951 * Register a save state data unit.
952 *
953 * @returns VBox status.
954 * @param pDrvIns Driver instance.
955 * @param uVersion Data layout version number.
956 * @param cbGuess The approximate amount of data in the unit.
957 * Only for progress indicators.
958 *
959 * @param pfnLivePrep Prepare live save callback, optional.
960 * @param pfnLiveExec Execute live save callback, optional.
961 * @param pfnLiveVote Vote live save callback, optional.
962 *
963 * @param pfnSavePrep Prepare save callback, optional.
964 * @param pfnSaveExec Execute save callback, optional.
965 * @param pfnSaveDone Done save callback, optional.
966 *
967 * @param pfnLoadPrep Prepare load callback, optional.
968 * @param pfnLoadExec Execute load callback, optional.
969 * @param pfnLoadDone Done load callback, optional.
970 */
971 DECLR3CALLBACKMEMBER(int, pfnSSMRegister,(PPDMDRVINS pDrvIns, uint32_t uVersion, size_t cbGuess,
972 PFNSSMDRVLIVEPREP pfnLivePrep, PFNSSMDRVLIVEEXEC pfnLiveExec, PFNSSMDRVLIVEVOTE pfnLiveVote,
973 PFNSSMDRVSAVEPREP pfnSavePrep, PFNSSMDRVSAVEEXEC pfnSaveExec, PFNSSMDRVSAVEDONE pfnSaveDone,
974 PFNSSMDRVLOADPREP pfnLoadPrep, PFNSSMDRVLOADEXEC pfnLoadExec, PFNSSMDRVLOADDONE pfnLoadDone));
975
976 /**
977 * Deregister a save state data unit.
978 *
979 * @returns VBox status.
980 * @param pDrvIns Driver instance.
981 * @param pszName Data unit name.
982 * @param uInstance The instance identifier of the data unit.
983 * This must together with the name be unique.
984 */
985 DECLR3CALLBACKMEMBER(int, pfnSSMDeregister,(PPDMDRVINS pDrvIns, const char *pszName, uint32_t uInstance));
986
987 /**
988 * Register an info handler with DBGF.
989 *
990 * @returns VBox status code.
991 * @param pDrvIns Driver instance.
992 * @param pszName Data unit name.
993 * @param pszDesc The description of the info and any arguments
994 * the handler may take.
995 * @param pfnHandler The handler function to be called to display the
996 * info.
997 */
998 DECLR3CALLBACKMEMBER(int, pfnDBGFInfoRegister,(PPDMDRVINS pDrvIns, const char *pszName, const char *pszDesc, PFNDBGFHANDLERDRV pfnHandler));
999
1000 /**
1001 * Deregister an info handler from DBGF.
1002 *
1003 * @returns VBox status code.
1004 * @param pDrvIns Driver instance.
1005 * @param pszName Data unit name.
1006 */
1007 DECLR3CALLBACKMEMBER(int, pfnDBGFInfoDeregister,(PPDMDRVINS pDrvIns, const char *pszName));
1008
1009 /**
1010 * Registers a statistics sample if statistics are enabled.
1011 *
1012 * @param pDrvIns Driver instance.
1013 * @param pvSample Pointer to the sample.
1014 * @param enmType Sample type. This indicates what pvSample is pointing at.
1015 * @param pszName Sample name. The name is on this form "/<component>/<sample>".
1016 * Further nesting is possible.
1017 * @param enmUnit Sample unit.
1018 * @param pszDesc Sample description.
1019 */
1020 DECLR3CALLBACKMEMBER(void, pfnSTAMRegister,(PPDMDRVINS pDrvIns, void *pvSample, STAMTYPE enmType, const char *pszName,
1021 STAMUNIT enmUnit, const char *pszDesc));
1022
1023 /**
1024 * Same as pfnSTAMRegister except that the name is specified in a
1025 * RTStrPrintf like fashion.
1026 *
1027 * @param pDrvIns Driver instance.
1028 * @param pvSample Pointer to the sample.
1029 * @param enmType Sample type. This indicates what pvSample is pointing at.
1030 * @param enmVisibility Visibility type specifying whether unused statistics should be visible or not.
1031 * @param enmUnit Sample unit.
1032 * @param pszDesc Sample description.
1033 * @param pszName The sample name format string.
1034 * @param ... Arguments to the format string.
1035 */
1036 DECLR3CALLBACKMEMBER(void, pfnSTAMRegisterF,(PPDMDRVINS pDrvIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,
1037 STAMUNIT enmUnit, const char *pszDesc, const char *pszName, ...));
1038
1039 /**
1040 * Same as pfnSTAMRegister except that the name is specified in a
1041 * RTStrPrintfV like fashion.
1042 *
1043 * @param pDrvIns Driver instance.
1044 * @param pvSample Pointer to the sample.
1045 * @param enmType Sample type. This indicates what pvSample is pointing at.
1046 * @param enmVisibility Visibility type specifying whether unused statistics should be visible or not.
1047 * @param enmUnit Sample unit.
1048 * @param pszDesc Sample description.
1049 * @param pszName The sample name format string.
1050 * @param args Arguments to the format string.
1051 */
1052 DECLR3CALLBACKMEMBER(void, pfnSTAMRegisterV,(PPDMDRVINS pDrvIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,
1053 STAMUNIT enmUnit, const char *pszDesc, const char *pszName, va_list args));
1054
1055 /**
1056 * Deregister a statistic item previously registered with pfnSTAMRegister,
1057 * pfnSTAMRegisterF or pfnSTAMRegisterV
1058 *
1059 * @returns VBox status.
1060 * @param pDrvIns Driver instance.
1061 * @param pvSample Pointer to the sample.
1062 */
1063 DECLR3CALLBACKMEMBER(int, pfnSTAMDeregister,(PPDMDRVINS pDrvIns, void *pvSample));
1064
1065 /**
1066 * Calls the HC R0 VMM entry point, in a safer but slower manner than
1067 * SUPR3CallVMMR0.
1068 *
1069 * When entering using this call the R0 components can call into the host kernel
1070 * (i.e. use the SUPR0 and RT APIs).
1071 *
1072 * See VMMR0Entry() for more details.
1073 *
1074 * @returns error code specific to uFunction.
1075 * @param pDrvIns The driver instance.
1076 * @param uOperation Operation to execute.
1077 * This is limited to services.
1078 * @param pvArg Pointer to argument structure or if cbArg is 0 just an value.
1079 * @param cbArg The size of the argument. This is used to copy whatever the argument
1080 * points at into a kernel buffer to avoid problems like the user page
1081 * being invalidated while we're executing the call.
1082 */
1083 DECLR3CALLBACKMEMBER(int, pfnSUPCallVMMR0Ex,(PPDMDRVINS pDrvIns, unsigned uOperation, void *pvArg, unsigned cbArg));
1084
1085 /**
1086 * Registers a USB HUB.
1087 *
1088 * @returns VBox status code.
1089 * @param pDrvIns The driver instance.
1090 * @param fVersions Indicates the kinds of USB devices that can be attached to this HUB.
1091 * @param cPorts The number of ports.
1092 * @param pUsbHubReg The hub callback structure that PDMUsb uses to interact with it.
1093 * @param ppUsbHubHlp The helper callback structure that the hub uses to talk to PDMUsb.
1094 *
1095 * @thread EMT.
1096 */
1097 DECLR3CALLBACKMEMBER(int, pfnUSBRegisterHub,(PPDMDRVINS pDrvIns, uint32_t fVersions, uint32_t cPorts, PCPDMUSBHUBREG pUsbHubReg, PPCPDMUSBHUBHLP ppUsbHubHlp));
1098
1099 /**
1100 * Set up asynchronous handling of a suspend, reset or power off notification.
1101 *
1102 * This shall only be called when getting the notification. It must be called
1103 * for each one.
1104 *
1105 * @returns VBox status code.
1106 * @param pDrvIns The driver instance.
1107 * @param pfnAsyncNotify The callback.
1108 * @thread EMT(0)
1109 */
1110 DECLR3CALLBACKMEMBER(int, pfnSetAsyncNotification, (PPDMDRVINS pDrvIns, PFNPDMDRVASYNCNOTIFY pfnAsyncNotify));
1111
1112 /**
1113 * Notify EMT(0) that the driver has completed the asynchronous notification
1114 * handling.
1115 *
1116 * This can be called at any time, spurious calls will simply be ignored.
1117 *
1118 * @param pDrvIns The driver instance.
1119 * @thread Any
1120 */
1121 DECLR3CALLBACKMEMBER(void, pfnAsyncNotificationCompleted, (PPDMDRVINS pDrvIns));
1122
1123 /**
1124 * Creates a PDM thread.
1125 *
1126 * This differs from the RTThreadCreate() API in that PDM takes care of suspending,
1127 * resuming, and destroying the thread as the VM state changes.
1128 *
1129 * @returns VBox status code.
1130 * @param pDrvIns The driver instance.
1131 * @param ppThread Where to store the thread 'handle'.
1132 * @param pvUser The user argument to the thread function.
1133 * @param pfnThread The thread function.
1134 * @param pfnWakeup The wakup callback. This is called on the EMT thread when
1135 * a state change is pending.
1136 * @param cbStack See RTThreadCreate.
1137 * @param enmType See RTThreadCreate.
1138 * @param pszName See RTThreadCreate.
1139 */
1140 DECLR3CALLBACKMEMBER(int, pfnThreadCreate,(PPDMDRVINS pDrvIns, PPPDMTHREAD ppThread, void *pvUser, PFNPDMTHREADDRV pfnThread,
1141 PFNPDMTHREADWAKEUPDRV pfnWakeup, size_t cbStack, RTTHREADTYPE enmType, const char *pszName));
1142
1143 /**
1144 * Creates a async completion template for a driver instance.
1145 *
1146 * The template is used when creating new completion tasks.
1147 *
1148 * @returns VBox status code.
1149 * @param pDrvIns The driver instance.
1150 * @param ppTemplate Where to store the template pointer on success.
1151 * @param pfnCompleted The completion callback routine.
1152 * @param pvTemplateUser Template user argument.
1153 * @param pszDesc Description.
1154 */
1155 DECLR3CALLBACKMEMBER(int, pfnAsyncCompletionTemplateCreate,(PPDMDRVINS pDrvIns, PPPDMASYNCCOMPLETIONTEMPLATE ppTemplate,
1156 PFNPDMASYNCCOMPLETEDRV pfnCompleted, void *pvTemplateUser,
1157 const char *pszDesc));
1158
1159
1160 /**
1161 * Resolves the symbol for a raw-mode context interface.
1162 *
1163 * @returns VBox status code.
1164 * @param pDrvIns The driver instance.
1165 * @param pvInterface The interface structure.
1166 * @param cbInterface The size of the interface structure.
1167 * @param pszSymPrefix What to prefix the symbols in the list with before
1168 * resolving them. This must start with 'drv' and
1169 * contain the driver name.
1170 * @param pszSymList List of symbols corresponding to the interface.
1171 * There is generally a there is generally a define
1172 * holding this list associated with the interface
1173 * definition (INTERFACE_SYM_LIST). For more details
1174 * see PDMR3LdrGetInterfaceSymbols.
1175 * @thread EMT
1176 */
1177 DECLR3CALLBACKMEMBER(int, pfnLdrGetRCInterfaceSymbols,(PPDMDRVINS pDrvIns, void *pvInterface, size_t cbInterface,
1178 const char *pszSymPrefix, const char *pszSymList));
1179
1180 /**
1181 * Resolves the symbol for a ring-0 context interface.
1182 *
1183 * @returns VBox status code.
1184 * @param pDrvIns The driver instance.
1185 * @param pvInterface The interface structure.
1186 * @param cbInterface The size of the interface structure.
1187 * @param pszSymPrefix What to prefix the symbols in the list with before
1188 * resolving them. This must start with 'drv' and
1189 * contain the driver name.
1190 * @param pszSymList List of symbols corresponding to the interface.
1191 * There is generally a there is generally a define
1192 * holding this list associated with the interface
1193 * definition (INTERFACE_SYM_LIST). For more details
1194 * see PDMR3LdrGetInterfaceSymbols.
1195 * @thread EMT
1196 */
1197 DECLR3CALLBACKMEMBER(int, pfnLdrGetR0InterfaceSymbols,(PPDMDRVINS pDrvIns, void *pvInterface, size_t cbInterface,
1198 const char *pszSymPrefix, const char *pszSymList));
1199 /**
1200 * Initializes a PDM critical section.
1201 *
1202 * The PDM critical sections are derived from the IPRT critical sections, but
1203 * works in both RC and R0 as well as R3.
1204 *
1205 * @returns VBox status code.
1206 * @param pDrvIns The driver instance.
1207 * @param pCritSect Pointer to the critical section.
1208 * @param RT_SRC_POS_DECL Use RT_SRC_POS.
1209 * @param pszName The base name of the critical section. Will be
1210 * mangeled with the instance number. For
1211 * statistics and lock validation.
1212 * @param va Arguments for the format string.
1213 * @thread EMT
1214 */
1215 DECLR3CALLBACKMEMBER(int, pfnCritSectInit,(PPDMDRVINS pDrvIns, PPDMCRITSECT pCritSect,
1216 RT_SRC_POS_DECL, const char *pszName));
1217
1218 /**
1219 * Call the ring-0 request handler routine of the driver.
1220 *
1221 * For this to work, the driver must be ring-0 enabled and export a request
1222 * handler function. The name of the function must be the driver name in the
1223 * PDMDRVREG struct prefixed with 'drvR0' and suffixed with 'ReqHandler'.
1224 * The driver name will be capitalized. It shall take the exact same
1225 * arguments as this function and be declared using PDMBOTHCBDECL. See
1226 * FNPDMDRVREQHANDLERR0.
1227 *
1228 * @returns VBox status code.
1229 * @retval VERR_SYMBOL_NOT_FOUND if the driver doesn't export the required
1230 * handler function.
1231 * @retval VERR_ACCESS_DENIED if the driver isn't ring-0 capable.
1232 *
1233 * @param pDrvIns The driver instance.
1234 * @param uOperation The operation to perform.
1235 * @param u64Arg 64-bit integer argument.
1236 * @thread Any
1237 */
1238 DECLR3CALLBACKMEMBER(int, pfnCallR0,(PPDMDRVINS pDrvIns, uint32_t uOperation, uint64_t u64Arg));
1239
1240 /**
1241 * Notify FTM about a checkpoint occurrence
1242 *
1243 * @param pDrvIns The driver instance.
1244 * @param enmType Checkpoint type
1245 * @thread Any
1246 */
1247 DECLR3CALLBACKMEMBER(int, pfnFTSetCheckpoint,(PPDMDRVINS pDrvIns, FTMCHECKPOINTTYPE enmType));
1248
1249 /**
1250 * Creates a block cache for a driver driver instance.
1251 *
1252 * @returns VBox status code.
1253 * @param pDrvIns The driver instance.
1254 * @param ppBlkCache Where to store the handle to the block cache.
1255 * @param pfnXferComplete The I/O transfer complete callback.
1256 * @param pfnXferEnqueue The I/O request enqueue callback.
1257 * @param pcszId Unique ID used to identify the user.
1258 */
1259 DECLR3CALLBACKMEMBER(int, pfnBlkCacheRetain, (PPDMDRVINS pDrvIns, PPPDMBLKCACHE ppBlkCache,
1260 PFNPDMBLKCACHEXFERCOMPLETEDRV pfnXferComplete,
1261 PFNPDMBLKCACHEXFERENQUEUEDRV pfnXferEnqueue,
1262 const char *pcszId));
1263
1264 /** Just a safety precaution. */
1265 uint32_t u32TheEnd;
1266} PDMDRVHLPR3;
1267/** Current DRVHLP version number. */
1268#define PDM_DRVHLPR3_VERSION PDM_VERSION_MAKE(0xf0fb, 2, 0)
1269
1270#endif /* IN_RING3 */
1271
1272
1273/**
1274 * @copydoc PDMDRVHLP::pfnVMSetError
1275 */
1276DECLINLINE(int) PDMDrvHlpVMSetError(PPDMDRVINS pDrvIns, const int rc, RT_SRC_POS_DECL, const char *pszFormat, ...)
1277{
1278 va_list va;
1279 va_start(va, pszFormat);
1280 pDrvIns->CTX_SUFF(pHlp)->pfnVMSetErrorV(pDrvIns, rc, RT_SRC_POS_ARGS, pszFormat, va);
1281 va_end(va);
1282 return rc;
1283}
1284
1285/** @def PDMDRV_SET_ERROR
1286 * Set the VM error. See PDMDrvHlpVMSetError() for printf like message formatting.
1287 */
1288#define PDMDRV_SET_ERROR(pDrvIns, rc, pszError) \
1289 PDMDrvHlpVMSetError(pDrvIns, rc, RT_SRC_POS, "%s", pszError)
1290
1291/**
1292 * @copydoc PDMDRVHLP::pfnVMSetErrorV
1293 */
1294DECLINLINE(int) PDMDrvHlpVMSetErrorV(PPDMDRVINS pDrvIns, const int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va)
1295{
1296 return pDrvIns->CTX_SUFF(pHlp)->pfnVMSetErrorV(pDrvIns, rc, RT_SRC_POS_ARGS, pszFormat, va);
1297}
1298
1299
1300/**
1301 * @copydoc PDMDRVHLP::pfnVMSetRuntimeError
1302 */
1303DECLINLINE(int) PDMDrvHlpVMSetRuntimeError(PPDMDRVINS pDrvIns, uint32_t fFlags, const char *pszErrorId, const char *pszFormat, ...)
1304{
1305 va_list va;
1306 int rc;
1307 va_start(va, pszFormat);
1308 rc = pDrvIns->CTX_SUFF(pHlp)->pfnVMSetRuntimeErrorV(pDrvIns, fFlags, pszErrorId, pszFormat, va);
1309 va_end(va);
1310 return rc;
1311}
1312
1313/** @def PDMDRV_SET_RUNTIME_ERROR
1314 * Set the VM runtime error. See PDMDrvHlpVMSetRuntimeError() for printf like message formatting.
1315 */
1316#define PDMDRV_SET_RUNTIME_ERROR(pDrvIns, fFlags, pszErrorId, pszError) \
1317 PDMDrvHlpVMSetRuntimeError(pDrvIns, fFlags, pszErrorId, "%s", pszError)
1318
1319/**
1320 * @copydoc PDMDRVHLP::pfnVMSetRuntimeErrorV
1321 */
1322DECLINLINE(int) PDMDrvHlpVMSetRuntimeErrorV(PPDMDRVINS pDrvIns, uint32_t fFlags, const char *pszErrorId, const char *pszFormat, va_list va)
1323{
1324 return pDrvIns->CTX_SUFF(pHlp)->pfnVMSetRuntimeErrorV(pDrvIns, fFlags, pszErrorId, pszFormat, va);
1325}
1326
1327
1328
1329/** @def PDMDRV_ASSERT_EMT
1330 * Assert that the current thread is the emulation thread.
1331 */
1332#ifdef VBOX_STRICT
1333# define PDMDRV_ASSERT_EMT(pDrvIns) pDrvIns->CTX_SUFF(pHlp)->pfnAssertEMT(pDrvIns, __FILE__, __LINE__, __FUNCTION__)
1334#else
1335# define PDMDRV_ASSERT_EMT(pDrvIns) do { } while (0)
1336#endif
1337
1338/** @def PDMDRV_ASSERT_OTHER
1339 * Assert that the current thread is NOT the emulation thread.
1340 */
1341#ifdef VBOX_STRICT
1342# define PDMDRV_ASSERT_OTHER(pDrvIns) pDrvIns->CTX_SUFF(pHlp)->pfnAssertOther(pDrvIns, __FILE__, __LINE__, __FUNCTION__)
1343#else
1344# define PDMDRV_ASSERT_OTHER(pDrvIns) do { } while (0)
1345#endif
1346
1347/**
1348 * @copydoc PDMDRVHLP::pfnFTSetCheckpoint
1349 */
1350DECLINLINE(int) PDMDrvHlpFTSetCheckpoint(PPDMDRVINS pDrvIns, FTMCHECKPOINTTYPE enmType)
1351{
1352 return pDrvIns->CTX_SUFF(pHlp)->pfnFTSetCheckpoint(pDrvIns, enmType);
1353}
1354
1355
1356#ifdef IN_RING3
1357
1358/**
1359 * @copydoc PDMDRVHLP::pfnAttach
1360 */
1361DECLINLINE(int) PDMDrvHlpAttach(PPDMDRVINS pDrvIns, uint32_t fFlags, PPDMIBASE *ppBaseInterface)
1362{
1363 return pDrvIns->pHlpR3->pfnAttach(pDrvIns, fFlags, ppBaseInterface);
1364}
1365
1366/**
1367 * Check that there is no driver below the us that we should attach to.
1368 *
1369 * @returns VERR_PDM_NO_ATTACHED_DRIVER if there is no driver.
1370 * @param pDrvIns The driver instance.
1371 */
1372DECLINLINE(int) PDMDrvHlpNoAttach(PPDMDRVINS pDrvIns)
1373{
1374 return pDrvIns->pHlpR3->pfnAttach(pDrvIns, 0, NULL);
1375}
1376
1377/**
1378 * @copydoc PDMDRVHLP::pfnDetach
1379 */
1380DECLINLINE(int) PDMDrvHlpDetach(PPDMDRVINS pDrvIns, uint32_t fFlags)
1381{
1382 return pDrvIns->pHlpR3->pfnDetach(pDrvIns, fFlags);
1383}
1384
1385/**
1386 * @copydoc PDMDRVHLP::pfnDetachSelf
1387 */
1388DECLINLINE(int) PDMDrvHlpDetachSelf(PPDMDRVINS pDrvIns, uint32_t fFlags)
1389{
1390 return pDrvIns->pHlpR3->pfnDetachSelf(pDrvIns, fFlags);
1391}
1392
1393/**
1394 * @copydoc PDMDRVHLP::pfnMountPrepare
1395 */
1396DECLINLINE(int) PDMDrvHlpMountPrepare(PPDMDRVINS pDrvIns, const char *pszFilename, const char *pszCoreDriver)
1397{
1398 return pDrvIns->pHlpR3->pfnMountPrepare(pDrvIns, pszFilename, pszCoreDriver);
1399}
1400
1401/**
1402 * @copydoc PDMDRVHLP::pfnVMState
1403 */
1404DECLINLINE(VMSTATE) PDMDrvHlpVMState(PPDMDRVINS pDrvIns)
1405{
1406 return pDrvIns->CTX_SUFF(pHlp)->pfnVMState(pDrvIns);
1407}
1408
1409/**
1410 * @copydoc PDMDRVHLP::pfnVMTeleportedAndNotFullyResumedYet
1411 */
1412DECLINLINE(bool) PDMDrvHlpVMTeleportedAndNotFullyResumedYet(PPDMDRVINS pDrvIns)
1413{
1414 return pDrvIns->pHlpR3->pfnVMTeleportedAndNotFullyResumedYet(pDrvIns);
1415}
1416
1417/**
1418 * @copydoc PDMDRVHLP::pfnGetSupDrvSession
1419 */
1420DECLINLINE(PSUPDRVSESSION) PDMDrvHlpGetSupDrvSession(PPDMDRVINS pDrvIns)
1421{
1422 return pDrvIns->pHlpR3->pfnGetSupDrvSession(pDrvIns);
1423}
1424
1425/**
1426 * @copydoc PDMDRVHLP::pfnQueueCreate
1427 */
1428DECLINLINE(int) PDMDrvHlpQueueCreate(PPDMDRVINS pDrvIns, uint32_t cbItem, uint32_t cItems, uint32_t cMilliesInterval,
1429 PFNPDMQUEUEDRV pfnCallback, const char *pszName, PPDMQUEUE *ppQueue)
1430{
1431 return pDrvIns->pHlpR3->pfnQueueCreate(pDrvIns, cbItem, cItems, cMilliesInterval, pfnCallback, pszName, ppQueue);
1432}
1433
1434/**
1435 * @copydoc PDMDRVHLP::pfnTMGetVirtualFreq
1436 */
1437DECLINLINE(uint64_t) PDMDrvHlpTMGetVirtualFreq(PPDMDRVINS pDrvIns)
1438{
1439 return pDrvIns->pHlpR3->pfnTMGetVirtualFreq(pDrvIns);
1440}
1441
1442/**
1443 * @copydoc PDMDRVHLP::pfnTMGetVirtualTime
1444 */
1445DECLINLINE(uint64_t) PDMDrvHlpTMGetVirtualTime(PPDMDRVINS pDrvIns)
1446{
1447 return pDrvIns->pHlpR3->pfnTMGetVirtualTime(pDrvIns);
1448}
1449
1450/**
1451 * @copydoc PDMDRVHLP::pfnTMTimerCreate
1452 */
1453DECLINLINE(int) PDMDrvHlpTMTimerCreate(PPDMDRVINS pDrvIns, TMCLOCK enmClock, PFNTMTIMERDRV pfnCallback, void *pvUser, uint32_t fFlags, const char *pszDesc, PPTMTIMERR3 ppTimer)
1454{
1455 return pDrvIns->pHlpR3->pfnTMTimerCreate(pDrvIns, enmClock, pfnCallback, pvUser, fFlags, pszDesc, ppTimer);
1456}
1457
1458/**
1459 * Register a save state data unit.
1460 *
1461 * @returns VBox status.
1462 * @param pDrvIns Driver instance.
1463 * @param uVersion Data layout version number.
1464 * @param cbGuess The approximate amount of data in the unit.
1465 * Only for progress indicators.
1466 * @param pfnSaveExec Execute save callback, optional.
1467 * @param pfnLoadExec Execute load callback, optional.
1468 */
1469DECLINLINE(int) PDMDrvHlpSSMRegister(PPDMDRVINS pDrvIns, uint32_t uVersion, size_t cbGuess,
1470 PFNSSMDRVSAVEEXEC pfnSaveExec, PFNSSMDRVLOADEXEC pfnLoadExec)
1471{
1472 return pDrvIns->pHlpR3->pfnSSMRegister(pDrvIns, uVersion, cbGuess,
1473 NULL /*pfnLivePrep*/, NULL /*pfnLiveExec*/, NULL /*pfnLiveVote*/,
1474 NULL /*pfnSavePrep*/, pfnSaveExec, NULL /*pfnSaveDone*/,
1475 NULL /*pfnLoadPrep*/, pfnLoadExec, NULL /*pfnLoadDone*/);
1476}
1477
1478/**
1479 * @copydoc PDMDRVHLP::pfnSSMRegister
1480 */
1481DECLINLINE(int) PDMDrvHlpSSMRegisterEx(PPDMDRVINS pDrvIns, uint32_t uVersion, size_t cbGuess,
1482 PFNSSMDRVLIVEPREP pfnLivePrep, PFNSSMDRVLIVEEXEC pfnLiveExec, PFNSSMDRVLIVEVOTE pfnLiveVote,
1483 PFNSSMDRVSAVEPREP pfnSavePrep, PFNSSMDRVSAVEEXEC pfnSaveExec, PFNSSMDRVSAVEDONE pfnSaveDone,
1484 PFNSSMDRVLOADPREP pfnLoadPrep, PFNSSMDRVLOADEXEC pfnLoadExec, PFNSSMDRVLOADDONE pfnLoadDone)
1485{
1486 return pDrvIns->pHlpR3->pfnSSMRegister(pDrvIns, uVersion, cbGuess,
1487 pfnLivePrep, pfnLiveExec, pfnLiveVote,
1488 pfnSavePrep, pfnSaveExec, pfnSaveDone,
1489 pfnLoadPrep, pfnLoadExec, pfnLoadDone);
1490}
1491
1492/**
1493 * Register a load done callback.
1494 *
1495 * @returns VBox status.
1496 * @param pDrvIns Driver instance.
1497 * @param pfnLoadDone Done load callback, optional.
1498 */
1499DECLINLINE(int) PDMDrvHlpSSMRegisterLoadDone(PPDMDRVINS pDrvIns, PFNSSMDRVLOADDONE pfnLoadDone)
1500{
1501 return pDrvIns->pHlpR3->pfnSSMRegister(pDrvIns, 0 /*uVersion*/, 0 /*cbGuess*/,
1502 NULL /*pfnLivePrep*/, NULL /*pfnLiveExec*/, NULL /*pfnLiveVote*/,
1503 NULL /*pfnSavePrep*/, NULL /*pfnSaveExec*/, NULL /*pfnSaveDone*/,
1504 NULL /*pfnLoadPrep*/, NULL /*pfnLoadExec*/, pfnLoadDone);
1505}
1506
1507/**
1508 * @copydoc PDMDRVHLP::pfnDBGFInfoRegister
1509 */
1510DECLINLINE(int) PDMDrvHlpDBGFInfoRegister(PPDMDRVINS pDrvIns, const char *pszName, const char *pszDesc, PFNDBGFHANDLERDRV pfnHandler)
1511{
1512 return pDrvIns->pHlpR3->pfnDBGFInfoRegister(pDrvIns, pszName, pszDesc, pfnHandler);
1513}
1514
1515/**
1516 * @copydoc PDMDRVHLP::pfnDBGFInfoDeregister
1517 */
1518DECLINLINE(int) PDMDrvHlpDBGFInfoDeregister(PPDMDRVINS pDrvIns, const char *pszName, const char *pszDesc, PFNDBGFHANDLERDRV pfnHandler)
1519{
1520 return pDrvIns->pHlpR3->pfnDBGFInfoRegister(pDrvIns, pszName, pszDesc, pfnHandler);
1521}
1522
1523/**
1524 * @copydoc PDMDRVHLP::pfnSTAMRegister
1525 */
1526DECLINLINE(void) PDMDrvHlpSTAMRegister(PPDMDRVINS pDrvIns, void *pvSample, STAMTYPE enmType, const char *pszName, STAMUNIT enmUnit, const char *pszDesc)
1527{
1528 pDrvIns->pHlpR3->pfnSTAMRegister(pDrvIns, pvSample, enmType, pszName, enmUnit, pszDesc);
1529}
1530
1531/**
1532 * @copydoc PDMDRVHLP::pfnSTAMRegisterF
1533 */
1534DECLINLINE(void) PDMDrvHlpSTAMRegisterF(PPDMDRVINS pDrvIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility, STAMUNIT enmUnit,
1535 const char *pszDesc, const char *pszName, ...)
1536{
1537 va_list va;
1538 va_start(va, pszName);
1539 pDrvIns->pHlpR3->pfnSTAMRegisterV(pDrvIns, pvSample, enmType, enmVisibility, enmUnit, pszDesc, pszName, va);
1540 va_end(va);
1541}
1542
1543/**
1544 * Convenience wrapper that registers counter which is always visible.
1545 *
1546 * @param pDrvIns The driver instance.
1547 * @param pCounter Pointer to the counter variable.
1548 * @param pszName The name of the sample. This is prefixed with
1549 * "/Drivers/<drivername>-<instance no>/".
1550 * @param enmUnit The unit.
1551 * @param pszDesc The description.
1552 */
1553DECLINLINE(void) PDMDrvHlpSTAMRegCounterEx(PPDMDRVINS pDrvIns, PSTAMCOUNTER pCounter, const char *pszName, STAMUNIT enmUnit, const char *pszDesc)
1554{
1555 pDrvIns->pHlpR3->pfnSTAMRegisterF(pDrvIns, pCounter, STAMTYPE_COUNTER, STAMVISIBILITY_ALWAYS, enmUnit, pszDesc,
1556 "/Drivers/%s-%u/%s", pDrvIns->pReg->szName, pDrvIns->iInstance, pszName);
1557}
1558
1559/**
1560 * Convenience wrapper that registers counter which is always visible and has
1561 * the STAMUNIT_COUNT unit.
1562 *
1563 * @param pDrvIns The driver instance.
1564 * @param pCounter Pointer to the counter variable.
1565 * @param pszName The name of the sample. This is prefixed with
1566 * "/Drivers/<drivername>-<instance no>/".
1567 * @param pszDesc The description.
1568 */
1569DECLINLINE(void) PDMDrvHlpSTAMRegCounter(PPDMDRVINS pDrvIns, PSTAMCOUNTER pCounter, const char *pszName, const char *pszDesc)
1570{
1571 PDMDrvHlpSTAMRegCounterEx(pDrvIns, pCounter, pszName, STAMUNIT_COUNT, pszDesc);
1572}
1573
1574/**
1575 * Convenience wrapper that registers profiling sample which is always visible.
1576 *
1577 * @param pDrvIns The driver instance.
1578 * @param pProfile Pointer to the profiling variable.
1579 * @param pszName The name of the sample. This is prefixed with
1580 * "/Drivers/<drivername>-<instance no>/".
1581 * @param enmUnit The unit.
1582 * @param pszDesc The description.
1583 */
1584DECLINLINE(void) PDMDrvHlpSTAMRegProfileEx(PPDMDRVINS pDrvIns, PSTAMPROFILE pProfile, const char *pszName, STAMUNIT enmUnit, const char *pszDesc)
1585{
1586 pDrvIns->pHlpR3->pfnSTAMRegisterF(pDrvIns, pProfile, STAMTYPE_PROFILE, STAMVISIBILITY_ALWAYS, enmUnit, pszDesc,
1587 "/Drivers/%s-%u/%s", pDrvIns->pReg->szName, pDrvIns->iInstance, pszName);
1588}
1589
1590/**
1591 * Convenience wrapper that registers profiling sample which is always visible
1592 * hand counts ticks per call (STAMUNIT_TICKS_PER_CALL).
1593 *
1594 * @param pDrvIns The driver instance.
1595 * @param pProfile Pointer to the profiling variable.
1596 * @param pszName The name of the sample. This is prefixed with
1597 * "/Drivers/<drivername>-<instance no>/".
1598 * @param pszDesc The description.
1599 */
1600DECLINLINE(void) PDMDrvHlpSTAMRegProfile(PPDMDRVINS pDrvIns, PSTAMPROFILE pProfile, const char *pszName, const char *pszDesc)
1601{
1602 PDMDrvHlpSTAMRegProfileEx(pDrvIns, pProfile, pszName, STAMUNIT_TICKS_PER_CALL, pszDesc);
1603}
1604
1605/**
1606 * Convenience wrapper that registers an advanced profiling sample which is
1607 * always visible.
1608 *
1609 * @param pDrvIns The driver instance.
1610 * @param pProfile Pointer to the profiling variable.
1611 * @param enmUnit The unit.
1612 * @param pszName The name of the sample. This is prefixed with
1613 * "/Drivers/<drivername>-<instance no>/".
1614 * @param pszDesc The description.
1615 */
1616DECLINLINE(void) PDMDrvHlpSTAMRegProfileAdvEx(PPDMDRVINS pDrvIns, PSTAMPROFILEADV pProfile, const char *pszName, STAMUNIT enmUnit, const char *pszDesc)
1617{
1618 pDrvIns->pHlpR3->pfnSTAMRegisterF(pDrvIns, pProfile, STAMTYPE_PROFILE, STAMVISIBILITY_ALWAYS, enmUnit, pszDesc,
1619 "/Drivers/%s-%u/%s", pDrvIns->pReg->szName, pDrvIns->iInstance, pszName);
1620}
1621
1622/**
1623 * Convenience wrapper that registers an advanced profiling sample which is
1624 * always visible.
1625 *
1626 * @param pDrvIns The driver instance.
1627 * @param pProfile Pointer to the profiling variable.
1628 * @param pszName The name of the sample. This is prefixed with
1629 * "/Drivers/<drivername>-<instance no>/".
1630 * @param pszDesc The description.
1631 */
1632DECLINLINE(void) PDMDrvHlpSTAMRegProfileAdv(PPDMDRVINS pDrvIns, PSTAMPROFILEADV pProfile, const char *pszName, const char *pszDesc)
1633{
1634 PDMDrvHlpSTAMRegProfileAdvEx(pDrvIns, pProfile, pszName, STAMUNIT_TICKS_PER_CALL, pszDesc);
1635}
1636
1637/**
1638 * @copydoc PDMDRVHLP::pfnSTAMDeregister
1639 */
1640DECLINLINE(int) PDMDrvHlpSTAMDeregister(PPDMDRVINS pDrvIns, void *pvSample)
1641{
1642 return pDrvIns->pHlpR3->pfnSTAMDeregister(pDrvIns, pvSample);
1643}
1644
1645/**
1646 * @copydoc PDMDRVHLP::pfnSUPCallVMMR0Ex
1647 */
1648DECLINLINE(int) PDMDrvHlpSUPCallVMMR0Ex(PPDMDRVINS pDrvIns, unsigned uOperation, void *pvArg, unsigned cbArg)
1649{
1650 return pDrvIns->pHlpR3->pfnSUPCallVMMR0Ex(pDrvIns, uOperation, pvArg, cbArg);
1651}
1652
1653/**
1654 * @copydoc PDMDRVHLP::pfnUSBRegisterHub
1655 */
1656DECLINLINE(int) PDMDrvHlpUSBRegisterHub(PPDMDRVINS pDrvIns, uint32_t fVersions, uint32_t cPorts, PCPDMUSBHUBREG pUsbHubReg, PPCPDMUSBHUBHLP ppUsbHubHlp)
1657{
1658 return pDrvIns->pHlpR3->pfnUSBRegisterHub(pDrvIns, fVersions, cPorts, pUsbHubReg, ppUsbHubHlp);
1659}
1660
1661/**
1662 * @copydoc PDMDRVHLP::pfnSetAsyncNotification
1663 */
1664DECLINLINE(int) PDMDrvHlpSetAsyncNotification(PPDMDRVINS pDrvIns, PFNPDMDRVASYNCNOTIFY pfnAsyncNotify)
1665{
1666 return pDrvIns->pHlpR3->pfnSetAsyncNotification(pDrvIns, pfnAsyncNotify);
1667}
1668
1669/**
1670 * @copydoc PDMDRVHLP::pfnAsyncNotificationCompleted
1671 */
1672DECLINLINE(void) PDMDrvHlpAsyncNotificationCompleted(PPDMDRVINS pDrvIns)
1673{
1674 pDrvIns->pHlpR3->pfnAsyncNotificationCompleted(pDrvIns);
1675}
1676
1677/**
1678 * @copydoc PDMDRVHLP::pfnThreadCreate
1679 */
1680DECLINLINE(int) PDMDrvHlpThreadCreate(PPDMDRVINS pDrvIns, PPPDMTHREAD ppThread, void *pvUser, PFNPDMTHREADDRV pfnThread,
1681 PFNPDMTHREADWAKEUPDRV pfnWakeup, size_t cbStack, RTTHREADTYPE enmType, const char *pszName)
1682{
1683 return pDrvIns->pHlpR3->pfnThreadCreate(pDrvIns, ppThread, pvUser, pfnThread, pfnWakeup, cbStack, enmType, pszName);
1684}
1685
1686# ifdef VBOX_WITH_PDM_ASYNC_COMPLETION
1687/**
1688 * @copydoc PDMDRVHLP::pfnAsyncCompletionTemplateCreate
1689 */
1690DECLINLINE(int) PDMDrvHlpAsyncCompletionTemplateCreate(PPDMDRVINS pDrvIns, PPPDMASYNCCOMPLETIONTEMPLATE ppTemplate,
1691 PFNPDMASYNCCOMPLETEDRV pfnCompleted, void *pvTemplateUser, const char *pszDesc)
1692{
1693 return pDrvIns->pHlpR3->pfnAsyncCompletionTemplateCreate(pDrvIns, ppTemplate, pfnCompleted, pvTemplateUser, pszDesc);
1694}
1695# endif
1696
1697/**
1698 * @copydoc PDMDRVHLP::pfnCritSectInit
1699 */
1700DECLINLINE(int) PDMDrvHlpCritSectInit(PPDMDRVINS pDrvIns, PPDMCRITSECT pCritSect, RT_SRC_POS_DECL, const char *pszName)
1701{
1702 return pDrvIns->pHlpR3->pfnCritSectInit(pDrvIns, pCritSect, RT_SRC_POS_ARGS, pszName);
1703}
1704
1705/**
1706 * @copydoc PDMDRVHLP::pfnCallR0
1707 */
1708DECLINLINE(int) PDMDrvHlpCallR0(PPDMDRVINS pDrvIns, uint32_t uOperation, uint64_t u64Arg)
1709{
1710 return pDrvIns->pHlpR3->pfnCallR0(pDrvIns, uOperation, u64Arg);
1711}
1712
1713/**
1714 * @copydoc PDMDRVHLP::pfnBlkCacheRetain
1715 */
1716DECLINLINE(int) PDMDrvHlpBlkCacheRetain(PPDMDRVINS pDrvIns, PPPDMBLKCACHE ppBlkCache,
1717 PFNPDMBLKCACHEXFERCOMPLETEDRV pfnXferComplete,
1718 PFNPDMBLKCACHEXFERENQUEUEDRV pfnXferEnqueue,
1719 const char *pcszId)
1720{
1721 return pDrvIns->pHlpR3->pfnBlkCacheRetain(pDrvIns, ppBlkCache, pfnXferComplete, pfnXferEnqueue, pcszId);
1722}
1723
1724/** Pointer to callbacks provided to the VBoxDriverRegister() call. */
1725typedef struct PDMDRVREGCB *PPDMDRVREGCB;
1726/** Pointer to const callbacks provided to the VBoxDriverRegister() call. */
1727typedef const struct PDMDRVREGCB *PCPDMDRVREGCB;
1728
1729/**
1730 * Callbacks for VBoxDriverRegister().
1731 */
1732typedef struct PDMDRVREGCB
1733{
1734 /** Interface version.
1735 * This is set to PDM_DRVREG_CB_VERSION. */
1736 uint32_t u32Version;
1737
1738 /**
1739 * Registers a driver with the current VM instance.
1740 *
1741 * @returns VBox status code.
1742 * @param pCallbacks Pointer to the callback table.
1743 * @param pReg Pointer to the driver registration record.
1744 * This data must be permanent and readonly.
1745 */
1746 DECLR3CALLBACKMEMBER(int, pfnRegister,(PCPDMDRVREGCB pCallbacks, PCPDMDRVREG pReg));
1747} PDMDRVREGCB;
1748
1749/** Current version of the PDMDRVREGCB structure. */
1750#define PDM_DRVREG_CB_VERSION PDM_VERSION_MAKE(0xf0fa, 1, 0)
1751
1752
1753/**
1754 * The VBoxDriverRegister callback function.
1755 *
1756 * PDM will invoke this function after loading a driver module and letting
1757 * the module decide which drivers to register and how to handle conflicts.
1758 *
1759 * @returns VBox status code.
1760 * @param pCallbacks Pointer to the callback table.
1761 * @param u32Version VBox version number.
1762 */
1763typedef DECLCALLBACK(int) FNPDMVBOXDRIVERSREGISTER(PCPDMDRVREGCB pCallbacks, uint32_t u32Version);
1764
1765VMMR3DECL(int) PDMR3RegisterDrivers(PVM pVM, FNPDMVBOXDRIVERSREGISTER pfnCallback);
1766
1767#endif /* IN_RING3 */
1768
1769/** @} */
1770
1771RT_C_DECLS_END
1772
1773#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