pdmdrv.h@ 26151

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

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

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

Download in other formats: