pdmdrv.h@ 26089

Last change on this file since 26089 was 26001, checked in by vboxsync, 15 years ago
PDM,*: Redid the PDM structure versions. Check the instance and helper versions in every device and driver constructor.
Property svn:eol-style set to `native` Property svn:keywords set to `Id`
File size: 46.6 KB

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

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: