63
64
* @param pCfgHandle Configuration node handle for the driver. Use this to obtain the configuration
64
65
* of the driver instance. It's also found in pDrvIns->pCfgHandle as it's expected
65
66
* to be used frequently in this function.
67
* @param fFlags Flags, combination of the PDM_TACH_FLAGS_* \#defines.
67
typedef DECLCALLBACK(int) FNPDMDRVCONSTRUCT(PPDMDRVINS pDrvIns, PCFGMNODE pCfgHandle);
69
typedef DECLCALLBACK(int) FNPDMDRVCONSTRUCT(PPDMDRVINS pDrvIns, PCFGMNODE pCfgHandle, uint32_t fFlags);
68
70
/** Pointer to a FNPDMDRVCONSTRUCT() function. */
69
71
typedef FNPDMDRVCONSTRUCT *PFNPDMDRVCONSTRUCT;
151
153
typedef FNPDMDRVPOWEROFF *PFNPDMDRVPOWEROFF;
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.
162
* This is like plugging in the keyboard or mouse after turning on the PC.
164
* @returns VBox status code.
165
* @param pDrvIns The driver instance.
166
* @param fFlags Flags, combination of the PDM_TACH_FLAGS_* \#defines.
168
typedef DECLCALLBACK(int) FNPDMDRVATTACH(PPDMDRVINS pDrvIns, uint32_t fFlags);
169
/** Pointer to a FNPDMDRVATTACH() function. */
170
typedef FNPDMDRVATTACH *PFNPDMDRVATTACH;
154
173
* Detach notification.
156
175
* This is called when a driver below it in the chain is detaching itself
204
224
PFNPDMDRVSUSPEND pfnSuspend;
205
225
/** Resume notification - optional. */
206
226
PFNPDMDRVRESUME pfnResume;
227
/** Attach command - optional. */
228
PFNPDMDRVATTACH pfnAttach;
207
229
/** Detach notification - optional. */
208
230
PFNPDMDRVDETACH pfnDetach;
209
231
/** Power off notification - optional. */
210
232
PFNPDMDRVPOWEROFF pfnPowerOff;
235
/** Initialization safty marker. */
236
uint32_t u32VersionEnd;
213
238
/** Pointer to a PDM Driver Structure. */
214
239
typedef PDMDRVREG *PPDMDRVREG;
364
389
* @returns VBox status code.
365
390
* @param pDrvIns Driver instance.
391
* @param fFlags PDM_TACH_FLAGS_NOT_HOT_PLUG or 0.
366
392
* @param ppBaseInterface Where to store the pointer to the base interface.
368
DECLR3CALLBACKMEMBER(int, pfnAttach,(PPDMDRVINS pDrvIns, PPDMIBASE *ppBaseInterface));
394
DECLR3CALLBACKMEMBER(int, pfnAttach,(PPDMDRVINS pDrvIns, uint32_t fFlags, PPDMIBASE *ppBaseInterface));
371
397
* Detach the driver the drivers below us.
373
399
* @returns VBox status code.
374
400
* @param pDrvIns Driver instance.
401
* @param fFlags PDM_TACH_FLAGS_NOT_HOT_PLUG or 0.
376
DECLR3CALLBACKMEMBER(int, pfnDetach,(PPDMDRVINS pDrvIns));
403
DECLR3CALLBACKMEMBER(int, pfnDetach,(PPDMDRVINS pDrvIns, uint32_t fFlags));
379
406
* Detach the driver from the driver above it and destroy this
472
500
DECLR3CALLBACKMEMBER(int, pfnVMSetRuntimeErrorV,(PPDMDRVINS pDrvIns, uint32_t fFlags, const char *pszErrorId, const char *pszFormat, va_list va));
506
* @param pDrvIns The driver instance.
507
* @thread Any thread (just keep in mind that it's volatile info).
509
DECLR3CALLBACKMEMBER(VMSTATE, pfnVMState, (PPDMDRVINS pDrvIns));
512
* Checks if the VM was teleported and hasn't been fully resumed yet.
514
* @returns true / false.
515
* @param pDrvIns The driver instance.
516
* @thread Any thread.
518
DECLR3CALLBACKMEMBER(bool, pfnVMTeleportedAndNotFullyResumedYet,(PPDMDRVINS pDrvIns));
475
521
* Create a queue.
477
523
* @returns VBox status code.
481
527
* @param cMilliesInterval Number of milliseconds between polling the queue.
482
528
* If 0 then the emulation thread will be notified whenever an item arrives.
483
529
* @param pfnCallback The consumer function.
530
* @param pszName The queue base name. The instance number will be
531
* appended automatically.
484
532
* @param ppQueue Where to store the queue handle on success.
485
533
* @thread The emulation thread.
487
DECLR3CALLBACKMEMBER(int, pfnPDMQueueCreate,(PPDMDRVINS pDrvIns, RTUINT cbItem, RTUINT cItems, uint32_t cMilliesInterval, PFNPDMQUEUEDRV pfnCallback, PPDMQUEUE *ppQueue));
490
* Register a poller function.
491
* TEMPORARY HACK FOR NETWORKING! DON'T USE!
493
* @returns VBox status code.
494
* @param pDrvIns Driver instance.
495
* @param pfnPoller The callback function.
497
DECLR3CALLBACKMEMBER(int, pfnPDMPollerRegister,(PPDMDRVINS pDrvIns, PFNPDMDRVPOLLER pfnPoller));
535
DECLR3CALLBACKMEMBER(int, pfnPDMQueueCreate,(PPDMDRVINS pDrvIns, RTUINT cbItem, RTUINT cItems, uint32_t cMilliesInterval,
536
PFNPDMQUEUEDRV pfnCallback, const char *pszName, PPDMQUEUE *ppQueue));
500
539
* Query the virtual timer frequency.
536
575
* @returns VBox status.
537
576
* @param pDrvIns Driver instance.
538
* @param pszName Data unit name.
539
* @param u32Instance The instance identifier of the data unit.
540
* This must together with the name be unique.
541
* @param u32Version Data layout version number.
577
* @param uVersion Data layout version number.
542
578
* @param cbGuess The approximate amount of data in the unit.
543
579
* Only for progress indicators.
581
* @param pfnLivePrep Prepare live save callback, optional.
582
* @param pfnLiveExec Execute live save callback, optional.
583
* @param pfnLiveVote Vote live save callback, optional.
544
585
* @param pfnSavePrep Prepare save callback, optional.
545
586
* @param pfnSaveExec Execute save callback, optional.
546
587
* @param pfnSaveDone Done save callback, optional.
547
589
* @param pfnLoadPrep Prepare load callback, optional.
548
590
* @param pfnLoadExec Execute load callback, optional.
549
591
* @param pfnLoadDone Done load callback, optional.
551
DECLR3CALLBACKMEMBER(int, pfnSSMRegister,(PPDMDRVINS pDrvIns, const char *pszName, uint32_t u32Instance, uint32_t u32Version, size_t cbGuess,
593
DECLR3CALLBACKMEMBER(int, pfnSSMRegister,(PPDMDRVINS pDrvIns, uint32_t uVersion, size_t cbGuess,
594
PFNSSMDRVLIVEPREP pfnLivePrep, PFNSSMDRVLIVEEXEC pfnLiveExec, PFNSSMDRVLIVEVOTE pfnLiveVote,
552
595
PFNSSMDRVSAVEPREP pfnSavePrep, PFNSSMDRVSAVEEXEC pfnSaveExec, PFNSSMDRVSAVEDONE pfnSaveDone,
553
596
PFNSSMDRVLOADPREP pfnLoadPrep, PFNSSMDRVLOADEXEC pfnLoadExec, PFNSSMDRVLOADDONE pfnLoadDone));
558
601
* @returns VBox status.
559
602
* @param pDrvIns Driver instance.
560
603
* @param pszName Data unit name.
561
* @param u32Instance The instance identifier of the data unit.
604
* @param uInstance The instance identifier of the data unit.
562
605
* This must together with the name be unique.
564
DECLR3CALLBACKMEMBER(int, pfnSSMDeregister,(PPDMDRVINS pDrvIns, const char *pszName, uint32_t u32Instance));
607
DECLR3CALLBACKMEMBER(int, pfnSSMDeregister,(PPDMDRVINS pDrvIns, const char *pszName, uint32_t uInstance));
567
610
* Registers a statistics sample if statistics are enabled.
654
697
DECLR3CALLBACKMEMBER(int, pfnUSBRegisterHub,(PPDMDRVINS pDrvIns, uint32_t fVersions, uint32_t cPorts, PCPDMUSBHUBREG pUsbHubReg, PPCPDMUSBHUBHLP ppUsbHubHlp));
700
* Set up asynchronous handling of a suspend, reset or power off notification.
702
* This shall only be called when getting the notification. It must be called
705
* @returns VBox status code.
706
* @param pDrvIns The driver instance.
707
* @param pfnAsyncNotify The callback.
710
DECLR3CALLBACKMEMBER(int, pfnSetAsyncNotification, (PPDMDRVINS pDrvIns, PFNPDMDRVASYNCNOTIFY pfnAsyncNotify));
713
* Notify EMT(0) that the driver has completed the asynchronous notification
716
* This can be called at any time, spurious calls will simply be ignored.
718
* @param pDrvIns The driver instance.
721
DECLR3CALLBACKMEMBER(void, pfnAsyncNotificationCompleted, (PPDMDRVINS pDrvIns));
657
724
* Creates a PDM thread.
659
726
* This differs from the RTThreadCreate() API in that PDM takes care of suspending,
673
740
DECLR3CALLBACKMEMBER(int, pfnPDMThreadCreate,(PPDMDRVINS pDrvIns, PPPDMTHREAD ppThread, void *pvUser, PFNPDMTHREADDRV pfnThread,
674
741
PFNPDMTHREADWAKEUPDRV pfnWakeup, size_t cbStack, RTTHREADTYPE enmType, const char *pszName));
680
* @param pDrvIns The driver instance.
681
* @thread Any thread (just keep in mind that it's volatile info).
683
DECLR3CALLBACKMEMBER(VMSTATE, pfnVMState, (PPDMDRVINS pDrvIns));
685
743
#ifdef VBOX_WITH_PDM_ASYNC_COMPLETION
687
745
* Creates a async completion template for a driver instance.
883
* @copydoc PDMDRVHLP::pfnAttach
885
DECLINLINE(int) PDMDrvHlpAttach(PPDMDRVINS pDrvIns, uint32_t fFlags, PPDMIBASE *ppBaseInterface)
887
return pDrvIns->pDrvHlp->pfnAttach(pDrvIns, fFlags, ppBaseInterface);
891
* Check that there is no driver below the us that we should attach to.
893
* @returns VERR_PDM_NO_ATTACHED_DRIVER if there is no driver.
894
* @param pDrvIns The driver instance.
896
DECLINLINE(int) PDMDrvHlpNoAttach(PPDMDRVINS pDrvIns)
898
return pDrvIns->pDrvHlp->pfnAttach(pDrvIns, 0, NULL);
902
* @copydoc PDMDRVHLP::pfnDetach
904
DECLINLINE(int) PDMDrvHlpDetach(PPDMDRVINS pDrvIns, uint32_t fFlags)
906
return pDrvIns->pDrvHlp->pfnDetach(pDrvIns, fFlags);
910
* @copydoc PDMDRVHLP::pfnDetachSelf
912
DECLINLINE(int) PDMDrvHlpDetachSelf(PPDMDRVINS pDrvIns, uint32_t fFlags)
914
return pDrvIns->pDrvHlp->pfnDetachSelf(pDrvIns, fFlags);
918
* @copydoc PDMDRVHLP::pfnVMState
920
DECLINLINE(VMSTATE) PDMDrvHlpVMState(PPDMDRVINS pDrvIns)
922
return pDrvIns->pDrvHlp->pfnVMState(pDrvIns);
926
* @copydoc PDMDRVHLP::pfnVMTeleportedAndNotFullyResumedYet
928
DECLINLINE(bool) PDMDrvHlpVMTeleportedAndNotFullyResumedYet(PPDMDRVINS pDrvIns)
930
return pDrvIns->pDrvHlp->pfnVMTeleportedAndNotFullyResumedYet(pDrvIns);
825
934
* @copydoc PDMDRVHLP::pfnPDMQueueCreate
827
936
DECLINLINE(int) PDMDrvHlpPDMQueueCreate(PPDMDRVINS pDrvIns, RTUINT cbItem, RTUINT cItems, uint32_t cMilliesInterval,
828
PFNPDMQUEUEDRV pfnCallback, PPDMQUEUE *ppQueue)
937
PFNPDMQUEUEDRV pfnCallback, const char *pszName, PPDMQUEUE *ppQueue)
830
return pDrvIns->pDrvHlp->pfnPDMQueueCreate(pDrvIns, cbItem, cItems, cMilliesInterval, pfnCallback, ppQueue);
939
return pDrvIns->pDrvHlp->pfnPDMQueueCreate(pDrvIns, cbItem, cItems, cMilliesInterval, pfnCallback, pszName, ppQueue);
967
* Register a save state data unit.
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.
977
DECLINLINE(int) PDMDrvHlpSSMRegister(PPDMDRVINS pDrvIns, uint32_t uVersion, size_t cbGuess,
978
PFNSSMDRVSAVEEXEC pfnSaveExec, PFNSSMDRVLOADEXEC pfnLoadExec)
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*/);
858
987
* @copydoc PDMDRVHLP::pfnSSMRegister
860
DECLINLINE(int) PDMDrvHlpSSMRegister(PPDMDRVINS pDrvIns, const char *pszName, uint32_t u32Instance, uint32_t u32Version, size_t cbGuess,
861
PFNSSMDRVSAVEPREP pfnSavePrep, PFNSSMDRVSAVEEXEC pfnSaveExec, PFNSSMDRVSAVEDONE pfnSaveDone,
862
PFNSSMDRVLOADPREP pfnLoadPrep, PFNSSMDRVLOADEXEC pfnLoadExec, PFNSSMDRVLOADDONE pfnLoadDone)
989
DECLINLINE(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)
864
return pDrvIns->pDrvHlp->pfnSSMRegister(pDrvIns, pszName, u32Instance, u32Version, cbGuess,
994
return pDrvIns->pDrvHlp->pfnSSMRegister(pDrvIns, uVersion, cbGuess,
995
pfnLivePrep, pfnLiveExec, pfnLiveVote,
865
996
pfnSavePrep, pfnSaveExec, pfnSaveDone,
866
997
pfnLoadPrep, pfnLoadExec, pfnLoadDone);
1001
* Register a load done callback.
1003
* @returns VBox status.
1004
* @param pDrvIns Driver instance.
1005
* @param pfnLoadDone Done load callback, optional.
1007
DECLINLINE(int) PDMDrvHlpSSMRegisterLoadDone(PPDMDRVINS pDrvIns, PFNSSMDRVLOADDONE pfnLoadDone)
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);
870
1016
* @copydoc PDMDRVHLP::pfnSTAMRegister
872
1018
DECLINLINE(void) PDMDrvHlpSTAMRegister(PPDMDRVINS pDrvIns, void *pvSample, STAMTYPE enmType, const char *pszName, STAMUNIT enmUnit, const char *pszDesc)
1052
* @copydoc PDMDRVHLP::pfnSetAsyncNotification
1054
DECLINLINE(int) PDMDrvHlpSetAsyncNotification(PPDMDRVINS pDrvIns, PFNPDMDRVASYNCNOTIFY pfnAsyncNotify)
1056
return pDrvIns->pDrvHlp->pfnSetAsyncNotification(pDrvIns, pfnAsyncNotify);
1060
* @copydoc PDMDRVHLP::pfnAsyncNotificationCompleted
1062
DECLINLINE(void) PDMDrvHlpAsyncNotificationCompleted(PPDMDRVINS pDrvIns)
1064
pDrvIns->pDrvHlp->pfnAsyncNotificationCompleted(pDrvIns);
906
1068
* @copydoc PDMDRVHLP::pfnPDMThreadCreate
908
1070
DECLINLINE(int) PDMDrvHlpPDMThreadCreate(PPDMDRVINS pDrvIns, PPPDMTHREAD ppThread, void *pvUser, PFNPDMTHREADDRV pfnThread,