VirtualBox

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

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

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