pdmdev.h@ 107308

Last change on this file since 107308 was 107308, checked in by vboxsync, 3 months ago
VMM: bugref:10759 Refactor GIC for use with different backends.
Property svn:eol-style set to `native` Property svn:keywords set to `Id Revision`
File size: 407.2 KB

Line
1	/** @file
2	* PDM - Pluggable Device Manager, Devices.
3	*/
4
5	/*
6	* Copyright (C) 2006-2024 Oracle and/or its affiliates.
7	*
8	* This file is part of VirtualBox base platform packages, as
9	* available from https://www.virtualbox.org.
10	*
11	* This program is free software; you can redistribute it and/or
12	* modify it under the terms of the GNU General Public License
13	* as published by the Free Software Foundation, in version 3 of the
14	* License.
15	*
16	* This program is distributed in the hope that it will be useful, but
17	* WITHOUT ANY WARRANTY; without even the implied warranty of
18	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19	* General Public License for more details.
20	*
21	* You should have received a copy of the GNU General Public License
22	* along with this program; if not, see <https://www.gnu.org/licenses>.
23	*
24	* The contents of this file may alternatively be used under the terms
25	* of the Common Development and Distribution License Version 1.0
26	* (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
27	* in the VirtualBox distribution, in which case the provisions of the
28	* CDDL are applicable instead of those of the GPL.
29	*
30	* You may elect to license modified versions of this file under the
31	* terms and conditions of either the GPL or the CDDL or both.
32	*
33	* SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
34	*/
35
36	#ifndef VBOX_INCLUDED_vmm_pdmdev_h
37	#define VBOX_INCLUDED_vmm_pdmdev_h
38	#ifndef RT_WITHOUT_PRAGMA_ONCE
39	# pragma once
40	#endif
41
42	#include <VBox/vmm/pdmcritsect.h>
43	#include <VBox/vmm/pdmcritsectrw.h>
44	#include <VBox/vmm/pdmqueue.h>
45	#include <VBox/vmm/pdmtask.h>
46	#ifdef IN_RING3
47	# include <VBox/vmm/pdmthread.h>
48	#endif
49	#include <VBox/vmm/pdmifs.h>
50	#include <VBox/vmm/pdmins.h>
51	#include <VBox/vmm/pdmcommon.h>
52	#include <VBox/vmm/pdmpcidev.h>
53	#include <VBox/vmm/iom.h>
54	#include <VBox/vmm/mm.h>
55	#include <VBox/vmm/tm.h>
56	#include <VBox/vmm/ssm.h>
57	#include <VBox/vmm/cfgm.h>
58	#include <VBox/vmm/cpum.h>
59	#include <VBox/vmm/dbgf.h>
60	#include <VBox/vmm/pgm.h> /* PGMR3HandlerPhysicalTypeRegister() argument types. */
61	#include <VBox/vmm/gim.h>
62	#include <VBox/err.h> /* VINF_EM_DBG_STOP, also 120+ source files expecting this. */
63	#include <VBox/msi.h>
64	#include <iprt/stdarg.h>
65	#include <iprt/list.h>
66
67
68	RT_C_DECLS_BEGIN
69
70	/** @defgroup grp_pdm_device The PDM Devices API
71	* @ingroup grp_pdm
72	* @{
73	*/
74
75	/**
76	* Construct a device instance for a VM.
77	*
78	* @returns VBox status.
79	* @param pDevIns The device instance data. If the registration structure
80	* is needed, it can be accessed thru pDevIns->pReg.
81	* @param iInstance Instance number. Use this to figure out which registers
82	* and such to use. The instance number is also found in
83	* pDevIns->iInstance, but since it's likely to be
84	* frequently used PDM passes it as parameter.
85	* @param pCfg Configuration node handle for the driver. This is
86	* expected to be in high demand in the constructor and is
87	* therefore passed as an argument. When using it at other
88	* times, it can be found in pDevIns->pCfg.
89	*/
90	typedef DECLCALLBACKTYPE(int, FNPDMDEVCONSTRUCT,(PPDMDEVINS pDevIns, int iInstance, PCFGMNODE pCfg));
91	/** Pointer to a FNPDMDEVCONSTRUCT() function. */
92	typedef FNPDMDEVCONSTRUCT *PFNPDMDEVCONSTRUCT;
93
94	/**
95	* Destruct a device instance.
96	*
97	* Most VM resources are freed by the VM. This callback is provided so that any non-VM
98	* resources can be freed correctly.
99	*
100	* @returns VBox status.
101	* @param pDevIns The device instance data.
102	*
103	* @remarks The device critical section is not entered. The routine may delete
104	* the critical section, so the caller cannot exit it.
105	*/
106	typedef DECLCALLBACKTYPE(int, FNPDMDEVDESTRUCT,(PPDMDEVINS pDevIns));
107	/** Pointer to a FNPDMDEVDESTRUCT() function. */
108	typedef FNPDMDEVDESTRUCT *PFNPDMDEVDESTRUCT;
109
110	/**
111	* Device relocation callback.
112	*
113	* This is called when the instance data has been relocated in raw-mode context
114	* (RC). It is also called when the RC hypervisor selects changes. The device
115	* must fixup all necessary pointers and re-query all interfaces to other RC
116	* devices and drivers.
117	*
118	* Before the RC code is executed the first time, this function will be called
119	* with a 0 delta so RC pointer calculations can be one in one place.
120	*
121	* @param pDevIns Pointer to the device instance.
122	* @param offDelta The relocation delta relative to the old location.
123	*
124	* @remarks A relocation CANNOT fail.
125	*
126	* @remarks The device critical section is not entered. The relocations should
127	* not normally require any locking.
128	*/
129	typedef DECLCALLBACKTYPE(void, FNPDMDEVRELOCATE,(PPDMDEVINS pDevIns, RTGCINTPTR offDelta));
130	/** Pointer to a FNPDMDEVRELOCATE() function. */
131	typedef FNPDMDEVRELOCATE *PFNPDMDEVRELOCATE;
132
133	/**
134	* Power On notification.
135	*
136	* @param pDevIns The device instance data.
137	*
138	* @remarks Caller enters the device critical section.
139	*/
140	typedef DECLCALLBACKTYPE(void, FNPDMDEVPOWERON,(PPDMDEVINS pDevIns));
141	/** Pointer to a FNPDMDEVPOWERON() function. */
142	typedef FNPDMDEVPOWERON *PFNPDMDEVPOWERON;
143
144	/**
145	* Reset notification.
146	*
147	* @param pDevIns The device instance data.
148	*
149	* @remarks Caller enters the device critical section.
150	*/
151	typedef DECLCALLBACKTYPE(void, FNPDMDEVRESET,(PPDMDEVINS pDevIns));
152	/** Pointer to a FNPDMDEVRESET() function. */
153	typedef FNPDMDEVRESET *PFNPDMDEVRESET;
154
155	/**
156	* Soft reset notification.
157	*
158	* This is mainly for emulating the 286 style protected mode exits, in which
159	* most devices should remain in their current state.
160	*
161	* @param pDevIns The device instance data.
162	* @param fFlags PDMVMRESET_F_XXX (only bits relevant to soft resets).
163	*
164	* @remarks Caller enters the device critical section.
165	*/
166	typedef DECLCALLBACKTYPE(void, FNPDMDEVSOFTRESET,(PPDMDEVINS pDevIns, uint32_t fFlags));
167	/** Pointer to a FNPDMDEVSOFTRESET() function. */
168	typedef FNPDMDEVSOFTRESET *PFNPDMDEVSOFTRESET;
169
170	/** @name PDMVMRESET_F_XXX - VM reset flags.
171	* These flags are used both for FNPDMDEVSOFTRESET and for hardware signalling
172	* reset via PDMDevHlpVMReset.
173	* @{ */
174	/** Unknown reason. */
175	#define PDMVMRESET_F_UNKNOWN UINT32_C(0x00000000)
176	/** GIM triggered reset. */
177	#define PDMVMRESET_F_GIM UINT32_C(0x00000001)
178	/** The last source always causing hard resets. */
179	#define PDMVMRESET_F_LAST_ALWAYS_HARD PDMVMRESET_F_GIM
180	/** ACPI triggered reset. */
181	#define PDMVMRESET_F_ACPI UINT32_C(0x0000000c)
182	/** PS/2 system port A (92h) reset. */
183	#define PDMVMRESET_F_PORT_A UINT32_C(0x0000000d)
184	/** Keyboard reset. */
185	#define PDMVMRESET_F_KBD UINT32_C(0x0000000e)
186	/** Tripple fault. */
187	#define PDMVMRESET_F_TRIPLE_FAULT UINT32_C(0x0000000f)
188	/** Reset source mask. */
189	#define PDMVMRESET_F_SRC_MASK UINT32_C(0x0000000f)
190	/** @} */
191
192	/**
193	* Suspend notification.
194	*
195	* @param pDevIns The device instance data.
196	* @thread EMT(0)
197	*
198	* @remarks Caller enters the device critical section.
199	*/
200	typedef DECLCALLBACKTYPE(void, FNPDMDEVSUSPEND,(PPDMDEVINS pDevIns));
201	/** Pointer to a FNPDMDEVSUSPEND() function. */
202	typedef FNPDMDEVSUSPEND *PFNPDMDEVSUSPEND;
203
204	/**
205	* Resume notification.
206	*
207	* @param pDevIns The device instance data.
208	*
209	* @remarks Caller enters the device critical section.
210	*/
211	typedef DECLCALLBACKTYPE(void, FNPDMDEVRESUME,(PPDMDEVINS pDevIns));
212	/** Pointer to a FNPDMDEVRESUME() function. */
213	typedef FNPDMDEVRESUME *PFNPDMDEVRESUME;
214
215	/**
216	* Power Off notification.
217	*
218	* This is always called when VMR3PowerOff is called.
219	* There will be no callback when hot plugging devices.
220	*
221	* @param pDevIns The device instance data.
222	* @thread EMT(0)
223	*
224	* @remarks Caller enters the device critical section.
225	*/
226	typedef DECLCALLBACKTYPE(void, FNPDMDEVPOWEROFF,(PPDMDEVINS pDevIns));
227	/** Pointer to a FNPDMDEVPOWEROFF() function. */
228	typedef FNPDMDEVPOWEROFF *PFNPDMDEVPOWEROFF;
229
230	/**
231	* Attach command.
232	*
233	* This is called to let the device attach to a driver for a specified LUN
234	* at runtime. This is not called during VM construction, the device
235	* constructor has to attach to all the available drivers.
236	*
237	* This is like plugging in the keyboard or mouse after turning on the PC.
238	*
239	* @returns VBox status code.
240	* @param pDevIns The device instance.
241	* @param iLUN The logical unit which is being attached.
242	* @param fFlags Flags, combination of the PDM_TACH_FLAGS_* \#defines.
243	*
244	* @remarks Caller enters the device critical section.
245	*/
246	typedef DECLCALLBACKTYPE(int, FNPDMDEVATTACH,(PPDMDEVINS pDevIns, unsigned iLUN, uint32_t fFlags));
247	/** Pointer to a FNPDMDEVATTACH() function. */
248	typedef FNPDMDEVATTACH *PFNPDMDEVATTACH;
249
250	/**
251	* Detach notification.
252	*
253	* This is called when a driver is detaching itself from a LUN of the device.
254	* The device should adjust its state to reflect this.
255	*
256	* This is like unplugging the network cable to use it for the laptop or
257	* something while the PC is still running.
258	*
259	* @param pDevIns The device instance.
260	* @param iLUN The logical unit which is being detached.
261	* @param fFlags Flags, combination of the PDMDEVATT_FLAGS_* \#defines.
262	*
263	* @remarks Caller enters the device critical section.
264	*/
265	typedef DECLCALLBACKTYPE(void, FNPDMDEVDETACH,(PPDMDEVINS pDevIns, unsigned iLUN, uint32_t fFlags));
266	/** Pointer to a FNPDMDEVDETACH() function. */
267	typedef FNPDMDEVDETACH *PFNPDMDEVDETACH;
268
269	/**
270	* Query the base interface of a logical unit.
271	*
272	* @returns VBOX status code.
273	* @param pDevIns The device instance.
274	* @param iLUN The logicial unit to query.
275	* @param ppBase Where to store the pointer to the base interface of the LUN.
276	*
277	* @remarks The device critical section is not entered.
278	*/
279	typedef DECLCALLBACKTYPE(int, FNPDMDEVQUERYINTERFACE,(PPDMDEVINS pDevIns, unsigned iLUN, PPDMIBASE *ppBase));
280	/** Pointer to a FNPDMDEVQUERYINTERFACE() function. */
281	typedef FNPDMDEVQUERYINTERFACE *PFNPDMDEVQUERYINTERFACE;
282
283	/**
284	* Init complete notification (after ring-0 & RC init since 5.1).
285	*
286	* This can be done to do communication with other devices and other
287	* initialization which requires everything to be in place.
288	*
289	* @returns VBOX status code.
290	* @param pDevIns The device instance.
291	*
292	* @remarks Caller enters the device critical section.
293	*/
294	typedef DECLCALLBACKTYPE(int, FNPDMDEVINITCOMPLETE,(PPDMDEVINS pDevIns));
295	/** Pointer to a FNPDMDEVINITCOMPLETE() function. */
296	typedef FNPDMDEVINITCOMPLETE *PFNPDMDEVINITCOMPLETE;
297
298
299	/**
300	* The context of a pfnMemSetup call.
301	*/
302	typedef enum PDMDEVMEMSETUPCTX
303	{
304	/** Invalid zero value. */
305	PDMDEVMEMSETUPCTX_INVALID = 0,
306	/** After construction. */
307	PDMDEVMEMSETUPCTX_AFTER_CONSTRUCTION,
308	/** After reset. */
309	PDMDEVMEMSETUPCTX_AFTER_RESET,
310	/** Type size hack. */
311	PDMDEVMEMSETUPCTX_32BIT_HACK = 0x7fffffff
312	} PDMDEVMEMSETUPCTX;
313
314
315	/**
316	* PDM Device Registration Structure.
317	*
318	* This structure is used when registering a device from VBoxInitDevices() in HC
319	* Ring-3. PDM will continue use till the VM is terminated.
320	*
321	* @note The first part is the same in every context.
322	*/
323	typedef struct PDMDEVREGR3
324	{
325	/** Structure version. PDM_DEVREGR3_VERSION defines the current version. */
326	uint32_t u32Version;
327	/** Reserved, must be zero. */
328	uint32_t uReserved0;
329	/** Device name, must match the ring-3 one. */
330	char szName[32];
331	/** Flags, combination of the PDM_DEVREG_FLAGS_* \#defines. */
332	uint32_t fFlags;
333	/** Device class(es), combination of the PDM_DEVREG_CLASS_* \#defines. */
334	uint32_t fClass;
335	/** Maximum number of instances (per VM). */
336	uint32_t cMaxInstances;
337	/** The shared data structure version number. */
338	uint32_t uSharedVersion;
339	/** Size of the instance data. */
340	uint32_t cbInstanceShared;
341	/** Size of the ring-0 instance data. */
342	uint32_t cbInstanceCC;
343	/** Size of the raw-mode instance data. */
344	uint32_t cbInstanceRC;
345	/** Max number of PCI devices. */
346	uint16_t cMaxPciDevices;
347	/** Max number of MSI-X vectors in any of the PCI devices. */
348	uint16_t cMaxMsixVectors;
349	/** The description of the device. The UTF-8 string pointed to shall, like this structure,
350	* remain unchanged from registration till VM destruction. */
351	const char *pszDescription;
352
353	/** Name of the raw-mode context module (no path).
354	* Only evalutated if PDM_DEVREG_FLAGS_RC is set. */
355	const char *pszRCMod;
356	/** Name of the ring-0 module (no path).
357	* Only evalutated if PDM_DEVREG_FLAGS_R0 is set. */
358	const char *pszR0Mod;
359
360	/** Construct instance - required. */
361	PFNPDMDEVCONSTRUCT pfnConstruct;
362	/** Destruct instance - optional.
363	* Critical section NOT entered (will be destroyed). */
364	PFNPDMDEVDESTRUCT pfnDestruct;
365	/** Relocation command - optional.
366	* Critical section NOT entered. */
367	PFNPDMDEVRELOCATE pfnRelocate;
368	/**
369	* Memory setup callback.
370	*
371	* @param pDevIns The device instance data.
372	* @param enmCtx Indicates the context of the call.
373	* @remarks The critical section is entered prior to calling this method.
374	*/
375	DECLR3CALLBACKMEMBER(void, pfnMemSetup, (PPDMDEVINS pDevIns, PDMDEVMEMSETUPCTX enmCtx));
376	/** Power on notification - optional.
377	* Critical section is entered. */
378	PFNPDMDEVPOWERON pfnPowerOn;
379	/** Reset notification - optional.
380	* Critical section is entered. */
381	PFNPDMDEVRESET pfnReset;
382	/** Suspend notification - optional.
383	* Critical section is entered. */
384	PFNPDMDEVSUSPEND pfnSuspend;
385	/** Resume notification - optional.
386	* Critical section is entered. */
387	PFNPDMDEVRESUME pfnResume;
388	/** Attach command - optional.
389	* Critical section is entered. */
390	PFNPDMDEVATTACH pfnAttach;
391	/** Detach notification - optional.
392	* Critical section is entered. */
393	PFNPDMDEVDETACH pfnDetach;
394	/** Query a LUN base interface - optional.
395	* Critical section is NOT entered. */
396	PFNPDMDEVQUERYINTERFACE pfnQueryInterface;
397	/** Init complete notification - optional.
398	* Critical section is entered. */
399	PFNPDMDEVINITCOMPLETE pfnInitComplete;
400	/** Power off notification - optional.
401	* Critical section is entered. */
402	PFNPDMDEVPOWEROFF pfnPowerOff;
403	/** Software system reset notification - optional.
404	* Critical section is entered. */
405	PFNPDMDEVSOFTRESET pfnSoftReset;
406
407	/** @name Reserved for future extensions, must be zero.
408	* @{ */
409	DECLR3CALLBACKMEMBER(int, pfnReserved0, (PPDMDEVINS pDevIns));
410	DECLR3CALLBACKMEMBER(int, pfnReserved1, (PPDMDEVINS pDevIns));
411	DECLR3CALLBACKMEMBER(int, pfnReserved2, (PPDMDEVINS pDevIns));
412	DECLR3CALLBACKMEMBER(int, pfnReserved3, (PPDMDEVINS pDevIns));
413	DECLR3CALLBACKMEMBER(int, pfnReserved4, (PPDMDEVINS pDevIns));
414	DECLR3CALLBACKMEMBER(int, pfnReserved5, (PPDMDEVINS pDevIns));
415	DECLR3CALLBACKMEMBER(int, pfnReserved6, (PPDMDEVINS pDevIns));
416	DECLR3CALLBACKMEMBER(int, pfnReserved7, (PPDMDEVINS pDevIns));
417	/** @} */
418
419	/** Initialization safty marker. */
420	uint32_t u32VersionEnd;
421	} PDMDEVREGR3;
422	/** Pointer to a PDM Device Structure. */
423	typedef PDMDEVREGR3 *PPDMDEVREGR3;
424	/** Const pointer to a PDM Device Structure. */
425	typedef PDMDEVREGR3 const *PCPDMDEVREGR3;
426	/** Current DEVREGR3 version number. */
427	#define PDM_DEVREGR3_VERSION PDM_VERSION_MAKE(0xffff, 4, 0)
428
429
430	/** PDM Device Flags.
431	* @{ */
432	/** This flag is used to indicate that the device has a R0 component. */
433	#define PDM_DEVREG_FLAGS_R0 UINT32_C(0x00000001)
434	/** Requires the ring-0 component, ignore configuration values. */
435	#define PDM_DEVREG_FLAGS_REQUIRE_R0 UINT32_C(0x00000002)
436	/** Requires the ring-0 component, ignore configuration values. */
437	#define PDM_DEVREG_FLAGS_OPT_IN_R0 UINT32_C(0x00000004)
438
439	/** This flag is used to indicate that the device has a RC component. */
440	#define PDM_DEVREG_FLAGS_RC UINT32_C(0x00000010)
441	/** Requires the raw-mode component, ignore configuration values. */
442	#define PDM_DEVREG_FLAGS_REQUIRE_RC UINT32_C(0x00000020)
443	/** Requires the raw-mode component, ignore configuration values. */
444	#define PDM_DEVREG_FLAGS_OPT_IN_RC UINT32_C(0x00000040)
445
446	/** Convenience: PDM_DEVREG_FLAGS_R0 + PDM_DEVREG_FLAGS_RC */
447	#define PDM_DEVREG_FLAGS_RZ (PDM_DEVREG_FLAGS_R0 \| PDM_DEVREG_FLAGS_RC)
448
449	/** @def PDM_DEVREG_FLAGS_HOST_BITS_DEFAULT
450	* The bit count for the current host.
451	* @note Superfluous, but still around for hysterical raisins. */
452	#if HC_ARCH_BITS == 32
453	# define PDM_DEVREG_FLAGS_HOST_BITS_DEFAULT UINT32_C(0x00000100)
454	#elif HC_ARCH_BITS == 64
455	# define PDM_DEVREG_FLAGS_HOST_BITS_DEFAULT UINT32_C(0x00000200)
456	#else
457	# error Unsupported HC_ARCH_BITS value.
458	#endif
459	/** The host bit count mask. */
460	#define PDM_DEVREG_FLAGS_HOST_BITS_MASK UINT32_C(0x00000300)
461
462	/** The device support only 32-bit guests. */
463	#define PDM_DEVREG_FLAGS_GUEST_BITS_32 UINT32_C(0x00001000)
464	/** The device support only 64-bit guests. */
465	#define PDM_DEVREG_FLAGS_GUEST_BITS_64 UINT32_C(0x00002000)
466	/** The device support both 32-bit & 64-bit guests. */
467	#define PDM_DEVREG_FLAGS_GUEST_BITS_32_64 UINT32_C(0x00003000)
468	/** @def PDM_DEVREG_FLAGS_GUEST_BITS_DEFAULT
469	* The guest bit count for the current compilation. */
470	#if GC_ARCH_BITS == 32
471	# define PDM_DEVREG_FLAGS_GUEST_BITS_DEFAULT PDM_DEVREG_FLAGS_GUEST_BITS_32
472	#elif GC_ARCH_BITS == 64
473	# define PDM_DEVREG_FLAGS_GUEST_BITS_DEFAULT PDM_DEVREG_FLAGS_GUEST_BITS_32_64
474	#else
475	# error Unsupported GC_ARCH_BITS value.
476	#endif
477	/** The guest bit count mask. */
478	#define PDM_DEVREG_FLAGS_GUEST_BITS_MASK UINT32_C(0x00003000)
479
480	/** A convenience. */
481	#define PDM_DEVREG_FLAGS_DEFAULT_BITS (PDM_DEVREG_FLAGS_GUEST_BITS_DEFAULT \| PDM_DEVREG_FLAGS_HOST_BITS_DEFAULT)
482
483	/** Indicates that the device needs to be notified before the drivers when suspending. */
484	#define PDM_DEVREG_FLAGS_FIRST_SUSPEND_NOTIFICATION UINT32_C(0x00010000)
485	/** Indicates that the device needs to be notified before the drivers when powering off. */
486	#define PDM_DEVREG_FLAGS_FIRST_POWEROFF_NOTIFICATION UINT32_C(0x00020000)
487	/** Indicates that the device needs to be notified before the drivers when resetting. */
488	#define PDM_DEVREG_FLAGS_FIRST_RESET_NOTIFICATION UINT32_C(0x00040000)
489
490	/** This flag is used to indicate that the device has been converted to the
491	* new device style. */
492	#define PDM_DEVREG_FLAGS_NEW_STYLE UINT32_C(0x80000000)
493
494	/** @} */
495
496
497	/** PDM Device Classes.
498	* The order is important, lower bit earlier instantiation.
499	* @{ */
500	/** Architecture device. */
501	#define PDM_DEVREG_CLASS_ARCH RT_BIT(0)
502	/** Architecture BIOS device. */
503	#define PDM_DEVREG_CLASS_ARCH_BIOS RT_BIT(1)
504	/** PCI bus brigde. */
505	#define PDM_DEVREG_CLASS_BUS_PCI RT_BIT(2)
506	/** PCI built-in device (e.g. PCI root complex devices). */
507	#define PDM_DEVREG_CLASS_PCI_BUILTIN RT_BIT(3)
508	/** Input device (mouse, keyboard, joystick, HID, ...). */
509	#define PDM_DEVREG_CLASS_INPUT RT_BIT(4)
510	/** Interrupt controller (PIC). */
511	#define PDM_DEVREG_CLASS_PIC RT_BIT(5)
512	/** Interval controoler (PIT). */
513	#define PDM_DEVREG_CLASS_PIT RT_BIT(6)
514	/** RTC/CMOS. */
515	#define PDM_DEVREG_CLASS_RTC RT_BIT(7)
516	/** DMA controller. */
517	#define PDM_DEVREG_CLASS_DMA RT_BIT(8)
518	/** VMM Device. */
519	#define PDM_DEVREG_CLASS_VMM_DEV RT_BIT(9)
520	/** Graphics device, like VGA. */
521	#define PDM_DEVREG_CLASS_GRAPHICS RT_BIT(10)
522	/** Storage controller device. */
523	#define PDM_DEVREG_CLASS_STORAGE RT_BIT(11)
524	/** Network interface controller. */
525	#define PDM_DEVREG_CLASS_NETWORK RT_BIT(12)
526	/** Audio. */
527	#define PDM_DEVREG_CLASS_AUDIO RT_BIT(13)
528	/** USB HIC. */
529	#define PDM_DEVREG_CLASS_BUS_USB RT_BIT(14)
530	/** ACPI. */
531	#define PDM_DEVREG_CLASS_ACPI RT_BIT(15)
532	/** Serial controller device. */
533	#define PDM_DEVREG_CLASS_SERIAL RT_BIT(16)
534	/** Parallel controller device */
535	#define PDM_DEVREG_CLASS_PARALLEL RT_BIT(17)
536	/** Host PCI pass-through device */
537	#define PDM_DEVREG_CLASS_HOST_DEV RT_BIT(18)
538	/** GPIO device */
539	#define PDM_DEVREG_CLASS_GPIO RT_BIT(19)
540	/** Misc devices (always last). */
541	#define PDM_DEVREG_CLASS_MISC RT_BIT(31)
542	/** @} */
543
544
545	/**
546	* PDM Device Registration Structure, ring-0.
547	*
548	* This structure is used when registering a device from VBoxInitDevices() in HC
549	* Ring-0. PDM will continue use till the VM is terminated.
550	*/
551	typedef struct PDMDEVREGR0
552	{
553	/** Structure version. PDM_DEVREGR0_VERSION defines the current version. */
554	uint32_t u32Version;
555	/** Reserved, must be zero. */
556	uint32_t uReserved0;
557	/** Device name, must match the ring-3 one. */
558	char szName[32];
559	/** Flags, combination of the PDM_DEVREG_FLAGS_* \#defines. */
560	uint32_t fFlags;
561	/** Device class(es), combination of the PDM_DEVREG_CLASS_* \#defines. */
562	uint32_t fClass;
563	/** Maximum number of instances (per VM). */
564	uint32_t cMaxInstances;
565	/** The shared data structure version number. */
566	uint32_t uSharedVersion;
567	/** Size of the instance data. */
568	uint32_t cbInstanceShared;
569	/** Size of the ring-0 instance data. */
570	uint32_t cbInstanceCC;
571	/** Size of the raw-mode instance data. */
572	uint32_t cbInstanceRC;
573	/** Max number of PCI devices. */
574	uint16_t cMaxPciDevices;
575	/** Max number of MSI-X vectors in any of the PCI devices. */
576	uint16_t cMaxMsixVectors;
577	/** The description of the device. The UTF-8 string pointed to shall, like this structure,
578	* remain unchanged from registration till VM destruction. */
579	const char *pszDescription;
580
581	/**
582	* Early construction callback (optional).
583	*
584	* This is called right after the device instance structure has been allocated
585	* and before the ring-3 constructor gets called.
586	*
587	* @returns VBox status code.
588	* @param pDevIns The device instance data.
589	* @note The destructure is always called, regardless of the return status.
590	*/
591	DECLR0CALLBACKMEMBER(int, pfnEarlyConstruct, (PPDMDEVINS pDevIns));
592
593	/**
594	* Regular construction callback (optional).
595	*
596	* This is called after (or during) the ring-3 constructor.
597	*
598	* @returns VBox status code.
599	* @param pDevIns The device instance data.
600	* @note The destructure is always called, regardless of the return status.
601	*/
602	DECLR0CALLBACKMEMBER(int, pfnConstruct, (PPDMDEVINS pDevIns));
603
604	/**
605	* Destructor (optional).
606	*
607	* This is called after the ring-3 destruction. This is not called if ring-3
608	* fails to trigger it (e.g. process is killed or crashes).
609	*
610	* @param pDevIns The device instance data.
611	*/
612	DECLR0CALLBACKMEMBER(void, pfnDestruct, (PPDMDEVINS pDevIns));
613
614	/**
615	* Final destructor (optional).
616	*
617	* This is called right before the memory is freed, which happens when the
618	* VM/GVM object is destroyed. This is always called.
619	*
620	* @param pDevIns The device instance data.
621	*/
622	DECLR0CALLBACKMEMBER(void, pfnFinalDestruct, (PPDMDEVINS pDevIns));
623
624	/**
625	* Generic request handler (optional).
626	*
627	* @param pDevIns The device instance data.
628	* @param uReq Device specific request.
629	* @param uArg Request argument.
630	*/
631	DECLR0CALLBACKMEMBER(int, pfnRequest, (PPDMDEVINS pDevIns, uint32_t uReq, uint64_t uArg));
632
633	/** @name Reserved for future extensions, must be zero.
634	* @{ */
635	DECLR0CALLBACKMEMBER(int, pfnReserved0, (PPDMDEVINS pDevIns));
636	DECLR0CALLBACKMEMBER(int, pfnReserved1, (PPDMDEVINS pDevIns));
637	DECLR0CALLBACKMEMBER(int, pfnReserved2, (PPDMDEVINS pDevIns));
638	DECLR0CALLBACKMEMBER(int, pfnReserved3, (PPDMDEVINS pDevIns));
639	DECLR0CALLBACKMEMBER(int, pfnReserved4, (PPDMDEVINS pDevIns));
640	DECLR0CALLBACKMEMBER(int, pfnReserved5, (PPDMDEVINS pDevIns));
641	DECLR0CALLBACKMEMBER(int, pfnReserved6, (PPDMDEVINS pDevIns));
642	DECLR0CALLBACKMEMBER(int, pfnReserved7, (PPDMDEVINS pDevIns));
643	/** @} */
644
645	/** Initialization safty marker. */
646	uint32_t u32VersionEnd;
647	} PDMDEVREGR0;
648	/** Pointer to a ring-0 PDM device registration structure. */
649	typedef PDMDEVREGR0 *PPDMDEVREGR0;
650	/** Pointer to a const ring-0 PDM device registration structure. */
651	typedef PDMDEVREGR0 const *PCPDMDEVREGR0;
652	/** Current DEVREGR0 version number. */
653	#define PDM_DEVREGR0_VERSION PDM_VERSION_MAKE(0xff80, 1, 0)
654
655
656	/**
657	* PDM Device Registration Structure, raw-mode
658	*
659	* At the moment, this structure is mostly here to match the other two contexts.
660	*/
661	typedef struct PDMDEVREGRC
662	{
663	/** Structure version. PDM_DEVREGRC_VERSION defines the current version. */
664	uint32_t u32Version;
665	/** Reserved, must be zero. */
666	uint32_t uReserved0;
667	/** Device name, must match the ring-3 one. */
668	char szName[32];
669	/** Flags, combination of the PDM_DEVREG_FLAGS_* \#defines. */
670	uint32_t fFlags;
671	/** Device class(es), combination of the PDM_DEVREG_CLASS_* \#defines. */
672	uint32_t fClass;
673	/** Maximum number of instances (per VM). */
674	uint32_t cMaxInstances;
675	/** The shared data structure version number. */
676	uint32_t uSharedVersion;
677	/** Size of the instance data. */
678	uint32_t cbInstanceShared;
679	/** Size of the ring-0 instance data. */
680	uint32_t cbInstanceCC;
681	/** Size of the raw-mode instance data. */
682	uint32_t cbInstanceRC;
683	/** Max number of PCI devices. */
684	uint16_t cMaxPciDevices;
685	/** Max number of MSI-X vectors in any of the PCI devices. */
686	uint16_t cMaxMsixVectors;
687	/** The description of the device. The UTF-8 string pointed to shall, like this structure,
688	* remain unchanged from registration till VM destruction. */
689	const char *pszDescription;
690
691	/**
692	* Constructor callback.
693	*
694	* This is called much later than both the ring-0 and ring-3 constructors, since
695	* raw-mode v2 require a working VMM to run actual code.
696	*
697	* @returns VBox status code.
698	* @param pDevIns The device instance data.
699	* @note The destructure is always called, regardless of the return status.
700	*/
701	DECLRGCALLBACKMEMBER(int, pfnConstruct, (PPDMDEVINS pDevIns));
702
703	/** @name Reserved for future extensions, must be zero.
704	* @{ */
705	DECLRCCALLBACKMEMBER(int, pfnReserved0, (PPDMDEVINS pDevIns));
706	DECLRCCALLBACKMEMBER(int, pfnReserved1, (PPDMDEVINS pDevIns));
707	DECLRCCALLBACKMEMBER(int, pfnReserved2, (PPDMDEVINS pDevIns));
708	DECLRCCALLBACKMEMBER(int, pfnReserved3, (PPDMDEVINS pDevIns));
709	DECLRCCALLBACKMEMBER(int, pfnReserved4, (PPDMDEVINS pDevIns));
710	DECLRCCALLBACKMEMBER(int, pfnReserved5, (PPDMDEVINS pDevIns));
711	DECLRCCALLBACKMEMBER(int, pfnReserved6, (PPDMDEVINS pDevIns));
712	DECLRCCALLBACKMEMBER(int, pfnReserved7, (PPDMDEVINS pDevIns));
713	/** @} */
714
715	/** Initialization safty marker. */
716	uint32_t u32VersionEnd;
717	} PDMDEVREGRC;
718	/** Pointer to a raw-mode PDM device registration structure. */
719	typedef PDMDEVREGRC *PPDMDEVREGRC;
720	/** Pointer to a const raw-mode PDM device registration structure. */
721	typedef PDMDEVREGRC const *PCPDMDEVREGRC;
722	/** Current DEVREGRC version number. */
723	#define PDM_DEVREGRC_VERSION PDM_VERSION_MAKE(0xff81, 1, 0)
724
725
726
727	/** @def PDM_DEVREG_VERSION
728	* Current DEVREG version number. */
729	/** @typedef PDMDEVREGR3
730	* A current context PDM device registration structure. */
731	/** @typedef PPDMDEVREGR3
732	* Pointer to a current context PDM device registration structure. */
733	/** @typedef PCPDMDEVREGR3
734	* Pointer to a const current context PDM device registration structure. */
735	#if defined(IN_RING3) \|\| defined(DOXYGEN_RUNNING)
736	# define PDM_DEVREG_VERSION PDM_DEVREGR3_VERSION
737	typedef PDMDEVREGR3 PDMDEVREG;
738	typedef PPDMDEVREGR3 PPDMDEVREG;
739	typedef PCPDMDEVREGR3 PCPDMDEVREG;
740	#elif defined(IN_RING0)
741	# define PDM_DEVREG_VERSION PDM_DEVREGR0_VERSION
742	typedef PDMDEVREGR0 PDMDEVREG;
743	typedef PPDMDEVREGR0 PPDMDEVREG;
744	typedef PCPDMDEVREGR0 PCPDMDEVREG;
745	#elif defined(IN_RC)
746	# define PDM_DEVREG_VERSION PDM_DEVREGRC_VERSION
747	typedef PDMDEVREGRC PDMDEVREG;
748	typedef PPDMDEVREGRC PPDMDEVREG;
749	typedef PCPDMDEVREGRC PCPDMDEVREG;
750	#else
751	# error "Not IN_RING3, IN_RING0 or IN_RC"
752	#endif
753
754	#if defined(VBOX_VMM_TARGET_X86) \|\| defined(VBOX_VMM_TARGET_AGNOSTIC)
755	/** The PDM APIC device registration structure. */
756	extern const PDMDEVREG g_DeviceAPIC;
757	#elif defined(VBOX_VMM_TARGET_ARMV8)
758	/** The PDM GIC device registration structure. */
759	extern const PDMDEVREG g_DeviceGIC;
760	/** The PDM GIC NEM device registration structure. */
761	extern const PDMDEVREG g_DeviceGICNem;
762	#endif
763
764	/**
765	* Device registrations for ring-0 modules.
766	*
767	* This structure is used directly and must therefore reside in persistent
768	* memory (i.e. the data section).
769	*/
770	typedef struct PDMDEVMODREGR0
771	{
772	/** The structure version (PDM_DEVMODREGR0_VERSION). */
773	uint32_t u32Version;
774	/** Number of devices in the array papDevRegs points to. */
775	uint32_t cDevRegs;
776	/** Pointer to device registration structures. */
777	PCPDMDEVREGR0 *papDevRegs;
778	/** The ring-0 module handle - PDM internal, fingers off. */
779	void *hMod;
780	/** List entry - PDM internal, fingers off. */
781	RTLISTNODE ListEntry;
782	} PDMDEVMODREGR0;
783	/** Pointer to device registriations for a ring-0 module. */
784	typedef PDMDEVMODREGR0 *PPDMDEVMODREGR0;
785	/** Current PDMDEVMODREGR0 version number. */
786	#define PDM_DEVMODREGR0_VERSION PDM_VERSION_MAKE(0xff85, 1, 0)
787
788
789	/** @name IRQ Level for use with the *SetIrq APIs.
790	* @{
791	*/
792	/** Assert the IRQ (can assume value 1). */
793	#define PDM_IRQ_LEVEL_HIGH RT_BIT(0)
794	/** Deassert the IRQ (can assume value 0). */
795	#define PDM_IRQ_LEVEL_LOW 0
796	/** flip-flop - deassert and then assert the IRQ again immediately (PIC) /
797	* automatically deasserts it after delivery to the APIC (IOAPIC).
798	* @note Only suitable for edge trigger interrupts. */
799	#define PDM_IRQ_LEVEL_FLIP_FLOP (RT_BIT(1) \| PDM_IRQ_LEVEL_HIGH)
800	/** @} */
801
802	/**
803	* Registration record for MSI/MSI-X emulation.
804	*/
805	typedef struct PDMMSIREG
806	{
807	/** Number of MSI interrupt vectors, 0 if MSI not supported */
808	uint16_t cMsiVectors;
809	/** Offset of MSI capability */
810	uint8_t iMsiCapOffset;
811	/** Offset of next capability to MSI */
812	uint8_t iMsiNextOffset;
813	/** If we support 64-bit MSI addressing */
814	bool fMsi64bit;
815	/** If we do not support per-vector masking */
816	bool fMsiNoMasking;
817
818	/** Number of MSI-X interrupt vectors, 0 if MSI-X not supported */
819	uint16_t cMsixVectors;
820	/** Offset of MSI-X capability */
821	uint8_t iMsixCapOffset;
822	/** Offset of next capability to MSI-X */
823	uint8_t iMsixNextOffset;
824	/** Value of PCI BAR (base addresss register) assigned by device for MSI-X page access */
825	uint8_t iMsixBar;
826	} PDMMSIREG;
827	typedef PDMMSIREG *PPDMMSIREG;
828
829	/**
830	* PCI Bus registration structure.
831	* All the callbacks, except the PCIBIOS hack, are working on PCI devices.
832	*/
833	typedef struct PDMPCIBUSREGR3
834	{
835	/** Structure version number. PDM_PCIBUSREGR3_VERSION defines the current version. */
836	uint32_t u32Version;
837
838	/**
839	* Registers the device with the default PCI bus.
840	*
841	* @returns VBox status code.
842	* @param pDevIns Device instance of the PCI Bus.
843	* @param pPciDev The PCI device structure.
844	* @param fFlags Reserved for future use, PDMPCIDEVREG_F_MBZ.
845	* @param uPciDevNo PDMPCIDEVREG_DEV_NO_FIRST_UNUSED, or a specific
846	* device number (0-31).
847	* @param uPciFunNo PDMPCIDEVREG_FUN_NO_FIRST_UNUSED, or a specific
848	* function number (0-7).
849	* @param pszName Device name (static but not unique).
850	*
851	* @remarks Caller enters the PDM critical section.
852	*/
853	DECLR3CALLBACKMEMBER(int, pfnRegisterR3,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t fFlags,
854	uint8_t uPciDevNo, uint8_t uPciFunNo, const char *pszName));
855
856	/**
857	* Initialize MSI or MSI-X emulation support in a PCI device.
858	*
859	* This cannot handle all corner cases of the MSI/MSI-X spec, but for the
860	* vast majority of device emulation it covers everything necessary. It's
861	* fully automatic, taking care of all BAR and config space requirements,
862	* and interrupt delivery is done using PDMDevHlpPCISetIrq and friends.
863	* When MSI/MSI-X is enabled then the iIrq parameter is redefined to take
864	* the vector number (otherwise it has the usual INTA-D meaning for PCI).
865	*
866	* A device not using this can still offer MSI/MSI-X. In this case it's
867	* completely up to the device (in the MSI-X case) to create/register the
868	* necessary MMIO BAR, handle all config space/BAR updating and take care
869	* of delivering the interrupts appropriately.
870	*
871	* @returns VBox status code.
872	* @param pDevIns Device instance of the PCI Bus.
873	* @param pPciDev The PCI device structure.
874	* @param pMsiReg MSI emulation registration structure
875	* @remarks Caller enters the PDM critical section.
876	*/
877	DECLR3CALLBACKMEMBER(int, pfnRegisterMsiR3,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, PPDMMSIREG pMsiReg));
878
879	/**
880	* Registers a I/O region (memory mapped or I/O ports) for a PCI device.
881	*
882	* @returns VBox status code.
883	* @param pDevIns Device instance of the PCI Bus.
884	* @param pPciDev The PCI device structure.
885	* @param iRegion The region number.
886	* @param cbRegion Size of the region.
887	* @param enmType PCI_ADDRESS_SPACE_MEM, PCI_ADDRESS_SPACE_IO or
888	* PCI_ADDRESS_SPACE_MEM_PREFETCH, optionally with
889	* PCI_ADDRESS_SPACE_BAR64 or'ed in.
890	* @param fFlags PDMPCIDEV_IORGN_F_XXX.
891	* @param hHandle An I/O port, MMIO or MMIO2 handle according to
892	* @a fFlags, UINT64_MAX if no handle is passed
893	* (old style).
894	* @param pfnMapUnmap Callback for doing the mapping. Optional if a handle
895	* is given.
896	* @remarks Caller enters the PDM critical section.
897	*/
898	DECLR3CALLBACKMEMBER(int, pfnIORegionRegisterR3,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t iRegion,
899	RTGCPHYS cbRegion, PCIADDRESSSPACE enmType, uint32_t fFlags,
900	uint64_t hHandle, PFNPCIIOREGIONMAP pfnMapUnmap));
901
902	/**
903	* Register PCI configuration space read/write intercept callbacks.
904	*
905	* @param pDevIns Device instance of the PCI Bus.
906	* @param pPciDev The PCI device structure.
907	* @param pfnRead Pointer to the user defined PCI config read function.
908	* @param pfnWrite Pointer to the user defined PCI config write function.
909	* to call default PCI config write function. Can be NULL.
910	* @remarks Caller enters the PDM critical section.
911	* @thread EMT
912	*/
913	DECLR3CALLBACKMEMBER(void, pfnInterceptConfigAccesses,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev,
914	PFNPCICONFIGREAD pfnRead, PFNPCICONFIGWRITE pfnWrite));
915
916	/**
917	* Perform a PCI configuration space write, bypassing interception.
918	*
919	* This is for devices that make use of PDMDevHlpPCIInterceptConfigAccesses().
920	*
921	* @returns Strict VBox status code (mainly DBGFSTOP).
922	* @param pDevIns Device instance of the PCI Bus.
923	* @param pPciDev The PCI device which config space is being read.
924	* @param uAddress The config space address.
925	* @param cb The size of the read: 1, 2 or 4 bytes.
926	* @param u32Value The value to write.
927	* @note The caller (PDM) does not enter the PDM critsect, but it is possible
928	* that the (root) bus will have done that already.
929	*/
930	DECLR3CALLBACKMEMBER(VBOXSTRICTRC, pfnConfigWrite,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev,
931	uint32_t uAddress, unsigned cb, uint32_t u32Value));
932
933	/**
934	* Perform a PCI configuration space read, bypassing interception.
935	*
936	* This is for devices that make use of PDMDevHlpPCIInterceptConfigAccesses().
937	*
938	* @returns Strict VBox status code (mainly DBGFSTOP).
939	* @param pDevIns Device instance of the PCI Bus.
940	* @param pPciDev The PCI device which config space is being read.
941	* @param uAddress The config space address.
942	* @param cb The size of the read: 1, 2 or 4 bytes.
943	* @param pu32Value Where to return the value.
944	* @note The caller (PDM) does not enter the PDM critsect, but it is possible
945	* that the (root) bus will have done that already.
946	*/
947	DECLR3CALLBACKMEMBER(VBOXSTRICTRC, pfnConfigRead,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev,
948	uint32_t uAddress, unsigned cb, uint32_t *pu32Value));
949
950	/**
951	* Set the IRQ for a PCI device.
952	*
953	* @param pDevIns Device instance of the PCI Bus.
954	* @param pPciDev The PCI device structure.
955	* @param iIrq IRQ number to set.
956	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
957	* @param uTagSrc The IRQ tag and source (for tracing).
958	* @remarks Caller enters the PDM critical section.
959	*/
960	DECLR3CALLBACKMEMBER(void, pfnSetIrqR3,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, int iIrq, int iLevel, uint32_t uTagSrc));
961
962	/** Marks the end of the structure with PDM_PCIBUSREGR3_VERSION. */
963	uint32_t u32EndVersion;
964	} PDMPCIBUSREGR3;
965	/** Pointer to a PCI bus registration structure. */
966	typedef PDMPCIBUSREGR3 *PPDMPCIBUSREGR3;
967	/** Current PDMPCIBUSREGR3 version number. */
968	#define PDM_PCIBUSREGR3_VERSION PDM_VERSION_MAKE(0xff86, 2, 0)
969
970	/**
971	* PCI Bus registration structure for ring-0.
972	*/
973	typedef struct PDMPCIBUSREGR0
974	{
975	/** Structure version number. PDM_PCIBUSREGR0_VERSION defines the current version. */
976	uint32_t u32Version;
977	/** The PCI bus number (from ring-3 registration). */
978	uint32_t iBus;
979	/**
980	* Set the IRQ for a PCI device.
981	*
982	* @param pDevIns Device instance of the PCI Bus.
983	* @param pPciDev The PCI device structure.
984	* @param iIrq IRQ number to set.
985	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
986	* @param uTagSrc The IRQ tag and source (for tracing).
987	* @remarks Caller enters the PDM critical section.
988	*/
989	DECLR0CALLBACKMEMBER(void, pfnSetIrq,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, int iIrq, int iLevel, uint32_t uTagSrc));
990	/** Marks the end of the structure with PDM_PCIBUSREGR0_VERSION. */
991	uint32_t u32EndVersion;
992	} PDMPCIBUSREGR0;
993	/** Pointer to a PCI bus ring-0 registration structure. */
994	typedef PDMPCIBUSREGR0 *PPDMPCIBUSREGR0;
995	/** Current PDMPCIBUSREGR0 version number. */
996	#define PDM_PCIBUSREGR0_VERSION PDM_VERSION_MAKE(0xff87, 1, 0)
997
998	/**
999	* PCI Bus registration structure for raw-mode.
1000	*/
1001	typedef struct PDMPCIBUSREGRC
1002	{
1003	/** Structure version number. PDM_PCIBUSREGRC_VERSION defines the current version. */
1004	uint32_t u32Version;
1005	/** The PCI bus number (from ring-3 registration). */
1006	uint32_t iBus;
1007	/**
1008	* Set the IRQ for a PCI device.
1009	*
1010	* @param pDevIns Device instance of the PCI Bus.
1011	* @param pPciDev The PCI device structure.
1012	* @param iIrq IRQ number to set.
1013	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
1014	* @param uTagSrc The IRQ tag and source (for tracing).
1015	* @remarks Caller enters the PDM critical section.
1016	*/
1017	DECLRCCALLBACKMEMBER(void, pfnSetIrq,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, int iIrq, int iLevel, uint32_t uTagSrc));
1018	/** Marks the end of the structure with PDM_PCIBUSREGRC_VERSION. */
1019	uint32_t u32EndVersion;
1020	} PDMPCIBUSREGRC;
1021	/** Pointer to a PCI bus raw-mode registration structure. */
1022	typedef PDMPCIBUSREGRC *PPDMPCIBUSREGRC;
1023	/** Current PDMPCIBUSREGRC version number. */
1024	#define PDM_PCIBUSREGRC_VERSION PDM_VERSION_MAKE(0xff88, 1, 0)
1025
1026	/** PCI bus registration structure for the current context. */
1027	typedef CTX_SUFF(PDMPCIBUSREG) PDMPCIBUSREGCC;
1028	/** Pointer to a PCI bus registration structure for the current context. */
1029	typedef CTX_SUFF(PPDMPCIBUSREG) PPDMPCIBUSREGCC;
1030	/** PCI bus registration structure version for the current context. */
1031	#define PDM_PCIBUSREGCC_VERSION CTX_MID(PDM_PCIBUSREG,_VERSION)
1032
1033
1034	/**
1035	* PCI Bus RC helpers.
1036	*/
1037	typedef struct PDMPCIHLPRC
1038	{
1039	/** Structure version. PDM_PCIHLPRC_VERSION defines the current version. */
1040	uint32_t u32Version;
1041
1042	/**
1043	* Set an ISA IRQ.
1044	*
1045	* @param pDevIns PCI device instance.
1046	* @param iIrq IRQ number to set.
1047	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
1048	* @param uTagSrc The IRQ tag and source (for tracing).
1049	* @thread EMT only.
1050	*/
1051	DECLRCCALLBACKMEMBER(void, pfnIsaSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel, uint32_t uTagSrc));
1052
1053	/**
1054	* Set an I/O-APIC IRQ.
1055	*
1056	* @param pDevIns PCI device instance.
1057	* @param uBusDevFn The bus:device:function of the device initiating the
1058	* IRQ. Pass NIL_PCIBDF when it's not a PCI device or
1059	* interrupt.
1060	* @param iIrq IRQ number to set.
1061	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
1062	* @param uTagSrc The IRQ tag and source (for tracing).
1063	* @thread EMT only.
1064	*/
1065	DECLRCCALLBACKMEMBER(void, pfnIoApicSetIrq,(PPDMDEVINS pDevIns, PCIBDF uBusDevFn, int iIrq, int iLevel, uint32_t uTagSrc));
1066
1067	/**
1068	* Send an MSI.
1069	*
1070	* @param pDevIns PCI device instance.
1071	* @param uBusDevFn The bus:device:function of the device initiating the
1072	* MSI. Cannot be NIL_PCIBDF.
1073	* @param pMsi The MSI to send.
1074	* @param uTagSrc The IRQ tag and source (for tracing).
1075	* @thread EMT only.
1076	*/
1077	DECLRCCALLBACKMEMBER(void, pfnIoApicSendMsi,(PPDMDEVINS pDevIns, PCIBDF uBusDevFn, PCMSIMSG pMsi, uint32_t uTagSrc));
1078
1079
1080	/**
1081	* Acquires the PDM lock.
1082	*
1083	* @returns VINF_SUCCESS on success.
1084	* @returns rc if we failed to acquire the lock.
1085	* @param pDevIns The PCI device instance.
1086	* @param rc What to return if we fail to acquire the lock.
1087	*
1088	* @sa PDMCritSectEnter
1089	*/
1090	DECLRCCALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
1091
1092	/**
1093	* Releases the PDM lock.
1094	*
1095	* @param pDevIns The PCI device instance.
1096	*/
1097	DECLRCCALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
1098
1099	/**
1100	* Gets a bus by it's PDM ordinal (typically the parent bus).
1101	*
1102	* @returns Pointer to the device instance of the bus.
1103	* @param pDevIns The PCI bus device instance.
1104	* @param idxPdmBus The PDM ordinal value of the bus to get.
1105	*/
1106	DECLRCCALLBACKMEMBER(PPDMDEVINS, pfnGetBusByNo,(PPDMDEVINS pDevIns, uint32_t idxPdmBus));
1107
1108	/** Just a safety precaution. */
1109	uint32_t u32TheEnd;
1110	} PDMPCIHLPRC;
1111	/** Pointer to PCI helpers. */
1112	typedef RCPTRTYPE(PDMPCIHLPRC *) PPDMPCIHLPRC;
1113	/** Pointer to const PCI helpers. */
1114	typedef RCPTRTYPE(const PDMPCIHLPRC *) PCPDMPCIHLPRC;
1115
1116	/** Current PDMPCIHLPRC version number. */
1117	#define PDM_PCIHLPRC_VERSION PDM_VERSION_MAKE(0xfffd, 4, 0)
1118
1119
1120	/**
1121	* PCI Bus R0 helpers.
1122	*/
1123	typedef struct PDMPCIHLPR0
1124	{
1125	/** Structure version. PDM_PCIHLPR0_VERSION defines the current version. */
1126	uint32_t u32Version;
1127
1128	/**
1129	* Set an ISA IRQ.
1130	*
1131	* @param pDevIns PCI device instance.
1132	* @param iIrq IRQ number to set.
1133	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
1134	* @param uTagSrc The IRQ tag and source (for tracing).
1135	* @thread EMT only.
1136	*/
1137	DECLR0CALLBACKMEMBER(void, pfnIsaSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel, uint32_t uTagSrc));
1138
1139	/**
1140	* Set an I/O-APIC IRQ.
1141	*
1142	* @param pDevIns PCI device instance.
1143	* @param uBusDevFn The bus:device:function of the device initiating the
1144	* IRQ. Pass NIL_PCIBDF when it's not a PCI device or
1145	* interrupt.
1146	* @param iIrq IRQ number to set.
1147	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
1148	* @param uTagSrc The IRQ tag and source (for tracing).
1149	* @thread EMT only.
1150	*/
1151	DECLR0CALLBACKMEMBER(void, pfnIoApicSetIrq,(PPDMDEVINS pDevIns, PCIBDF uBusDevFn, int iIrq, int iLevel, uint32_t uTagSrc));
1152
1153	/**
1154	* Send an MSI.
1155	*
1156	* @param pDevIns PCI device instance.
1157	* @param uBusDevFn The bus:device:function of the device initiating the
1158	* MSI. Cannot be NIL_PCIBDF.
1159	* @param pMsi The MSI to send.
1160	* @param uTagSrc The IRQ tag and source (for tracing).
1161	* @thread EMT only.
1162	*/
1163	DECLR0CALLBACKMEMBER(void, pfnIoApicSendMsi,(PPDMDEVINS pDevIns, PCIBDF uBusDevFn, PCMSIMSG pMsi, uint32_t uTagSrc));
1164
1165	/**
1166	* Acquires the PDM lock.
1167	*
1168	* @returns VINF_SUCCESS on success.
1169	* @returns rc if we failed to acquire the lock.
1170	* @param pDevIns The PCI device instance.
1171	* @param rc What to return if we fail to acquire the lock.
1172	*
1173	* @sa PDMCritSectEnter
1174	*/
1175	DECLR0CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
1176
1177	/**
1178	* Releases the PDM lock.
1179	*
1180	* @param pDevIns The PCI device instance.
1181	*/
1182	DECLR0CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
1183
1184	/**
1185	* Gets a bus by it's PDM ordinal (typically the parent bus).
1186	*
1187	* @returns Pointer to the device instance of the bus.
1188	* @param pDevIns The PCI bus device instance.
1189	* @param idxPdmBus The PDM ordinal value of the bus to get.
1190	*/
1191	DECLR0CALLBACKMEMBER(PPDMDEVINS, pfnGetBusByNo,(PPDMDEVINS pDevIns, uint32_t idxPdmBus));
1192
1193	/** Just a safety precaution. */
1194	uint32_t u32TheEnd;
1195	} PDMPCIHLPR0;
1196	/** Pointer to PCI helpers. */
1197	typedef R0PTRTYPE(PDMPCIHLPR0 *) PPDMPCIHLPR0;
1198	/** Pointer to const PCI helpers. */
1199	typedef R0PTRTYPE(const PDMPCIHLPR0 *) PCPDMPCIHLPR0;
1200
1201	/** Current PDMPCIHLPR0 version number. */
1202	#define PDM_PCIHLPR0_VERSION PDM_VERSION_MAKE(0xfffc, 6, 0)
1203
1204	/**
1205	* PCI device helpers.
1206	*/
1207	typedef struct PDMPCIHLPR3
1208	{
1209	/** Structure version. PDM_PCIHLPR3_VERSION defines the current version. */
1210	uint32_t u32Version;
1211
1212	/**
1213	* Set an ISA IRQ.
1214	*
1215	* @param pDevIns The PCI device instance.
1216	* @param iIrq IRQ number to set.
1217	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
1218	* @param uTagSrc The IRQ tag and source (for tracing).
1219	*/
1220	DECLR3CALLBACKMEMBER(void, pfnIsaSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel, uint32_t uTagSrc));
1221
1222	/**
1223	* Set an I/O-APIC IRQ.
1224	*
1225	* @param pDevIns The PCI device instance.
1226	* @param uBusDevFn The bus:device:function of the device initiating the
1227	* IRQ. Pass NIL_PCIBDF when it's not a PCI device or
1228	* interrupt.
1229	* @param iIrq IRQ number to set.
1230	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
1231	* @param uTagSrc The IRQ tag and source (for tracing).
1232	*/
1233	DECLR3CALLBACKMEMBER(void, pfnIoApicSetIrq,(PPDMDEVINS pDevIns, PCIBDF uBusDevFn, int iIrq, int iLevel, uint32_t uTagSrc));
1234
1235	/**
1236	* Send an MSI.
1237	*
1238	* @param pDevIns PCI device instance.
1239	* @param uBusDevFn The bus:device:function of the device initiating the
1240	* MSI. Cannot be NIL_PCIBDF.
1241	* @param pMsi The MSI to send.
1242	* @param uTagSrc The IRQ tag and source (for tracing).
1243	*/
1244	DECLR3CALLBACKMEMBER(void, pfnIoApicSendMsi,(PPDMDEVINS pDevIns, PCIBDF uBusDevFn, PCMSIMSG pMsi, uint32_t uTagSrc));
1245
1246	/**
1247	* Acquires the PDM lock.
1248	*
1249	* @returns VINF_SUCCESS on success.
1250	* @returns Fatal error on failure.
1251	* @param pDevIns The PCI device instance.
1252	* @param rc Dummy for making the interface identical to the RC and R0 versions.
1253	*
1254	* @sa PDMCritSectEnter
1255	*/
1256	DECLR3CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
1257
1258	/**
1259	* Releases the PDM lock.
1260	*
1261	* @param pDevIns The PCI device instance.
1262	*/
1263	DECLR3CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
1264
1265	/**
1266	* Gets a bus by it's PDM ordinal (typically the parent bus).
1267	*
1268	* @returns Pointer to the device instance of the bus.
1269	* @param pDevIns The PCI bus device instance.
1270	* @param idxPdmBus The PDM ordinal value of the bus to get.
1271	*/
1272	DECLR3CALLBACKMEMBER(PPDMDEVINS, pfnGetBusByNo,(PPDMDEVINS pDevIns, uint32_t idxPdmBus));
1273
1274	/** Just a safety precaution. */
1275	uint32_t u32TheEnd;
1276	} PDMPCIHLPR3;
1277	/** Pointer to PCI helpers. */
1278	typedef R3PTRTYPE(PDMPCIHLPR3 *) PPDMPCIHLPR3;
1279	/** Pointer to const PCI helpers. */
1280	typedef R3PTRTYPE(const PDMPCIHLPR3 *) PCPDMPCIHLPR3;
1281
1282	/** Current PDMPCIHLPR3 version number. */
1283	#define PDM_PCIHLPR3_VERSION PDM_VERSION_MAKE(0xfffb, 5, 0)
1284
1285
1286	/** @name PDMIOMMU_MEM_F_XXX - IOMMU memory access transaction flags.
1287	* These flags are used for memory access transactions via the IOMMU interface.
1288	* @{ */
1289	/** Memory read. */
1290	#define PDMIOMMU_MEM_F_READ RT_BIT_32(0)
1291	/** Memory write. */
1292	#define PDMIOMMU_MEM_F_WRITE RT_BIT_32(1)
1293	/** Valid flag mask. */
1294	#define PDMIOMMU_MEM_F_VALID_MASK (PDMIOMMU_MEM_F_READ \| PDMIOMMU_MEM_F_WRITE)
1295	/** @} */
1296
1297	/**
1298	* IOMMU registration structure for ring-0.
1299	*/
1300	typedef struct PDMIOMMUREGR0
1301	{
1302	/** Structure version number. PDM_IOMMUREG_VERSION defines the current
1303	* version. */
1304	uint32_t u32Version;
1305	/** Index into the PDM IOMMU array (PDM::aIommus) from ring-3. */
1306	uint32_t idxIommu;
1307
1308	/**
1309	* Translates the physical address for a memory transaction through the IOMMU.
1310	*
1311	* @returns VBox status code.
1312	* @param pDevIns The IOMMU device instance.
1313	* @param idDevice The device identifier (bus, device, function).
1314	* @param uIova The I/O virtual address being accessed.
1315	* @param cbIova The size of the access.
1316	* @param fFlags Access flags, see PDMIOMMU_MEM_F_XXX.
1317	* @param pGCPhysSpa Where to store the translated system physical address.
1318	* @param pcbContiguous Where to store the number of contiguous bytes translated
1319	* and permission-checked.
1320	*
1321	* @thread Any.
1322	*/
1323	DECLR0CALLBACKMEMBER(int, pfnMemAccess,(PPDMDEVINS pDevIns, uint16_t idDevice, uint64_t uIova, size_t cbIova,
1324	uint32_t fFlags, PRTGCPHYS pGCPhysSpa, size_t *pcbContiguous));
1325
1326	/**
1327	* Translates in bulk physical page addresses for memory transactions through the
1328	* IOMMU.
1329	*
1330	* @returns VBox status code.
1331	* @param pDevIns The IOMMU device instance.
1332	* @param idDevice The device identifier (bus, device, function).
1333	* @param cIovas The number of I/O virtual addresses being accessed.
1334	* @param pauIovas The I/O virtual addresses being accessed.
1335	* @param fFlags Access flags, see PDMIOMMU_MEM_F_XXX.
1336	* @param paGCPhysSpa Where to store the translated system physical page
1337	* addresses.
1338	*
1339	* @thread Any.
1340	*/
1341	DECLR0CALLBACKMEMBER(int, pfnMemBulkAccess,(PPDMDEVINS pDevIns, uint16_t idDevice, size_t cIovas, uint64_t const *pauIovas,
1342	uint32_t fFlags, PRTGCPHYS paGCPhysSpa));
1343
1344	/**
1345	* Performs an interrupt remap request through the IOMMU.
1346	*
1347	* @returns VBox status code.
1348	* @param pDevIns The IOMMU device instance.
1349	* @param idDevice The device identifier (bus, device, function).
1350	* @param pMsiIn The source MSI.
1351	* @param pMsiOut Where to store the remapped MSI.
1352	*
1353	* @thread Any.
1354	*/
1355	DECLR0CALLBACKMEMBER(int, pfnMsiRemap,(PPDMDEVINS pDevIns, uint16_t idDevice, PCMSIMSG pMsiIn, PMSIMSG pMsiOut));
1356
1357	/** Just a safety precaution. */
1358	uint32_t u32TheEnd;
1359	} PDMIOMMUREGR0;
1360	/** Pointer to a IOMMU registration structure. */
1361	typedef PDMIOMMUREGR0 *PPDMIOMMUREGR0;
1362
1363	/** Current PDMIOMMUREG version number. */
1364	#define PDM_IOMMUREGR0_VERSION PDM_VERSION_MAKE(0xff10, 3, 0)
1365
1366
1367	/**
1368	* IOMMU registration structure for raw-mode.
1369	*/
1370	typedef struct PDMIOMMUREGRC
1371	{
1372	/** Structure version number. PDM_IOMMUREG_VERSION defines the current
1373	* version. */
1374	uint32_t u32Version;
1375	/** Index into the PDM IOMMU array (PDM::aIommus) from ring-3. */
1376	uint32_t idxIommu;
1377
1378	/**
1379	* Translates the physical address for a memory transaction through the IOMMU.
1380	*
1381	* @returns VBox status code.
1382	* @param pDevIns The IOMMU device instance.
1383	* @param idDevice The device identifier (bus, device, function).
1384	* @param uIova The I/O virtual address being accessed.
1385	* @param cbIova The size of the access.
1386	* @param fFlags Access flags, see PDMIOMMU_MEM_F_XXX.
1387	* @param pGCPhysSpa Where to store the translated system physical address.
1388	* @param pcbContiguous Where to store the number of contiguous bytes translated
1389	* and permission-checked.
1390	*
1391	* @thread Any.
1392	*/
1393	DECLRCCALLBACKMEMBER(int, pfnMemAccess,(PPDMDEVINS pDevIns, uint16_t idDevice, uint64_t uIova, size_t cbIova,
1394	uint32_t fFlags, PRTGCPHYS pGCPhysSpa, size_t *pcbContiguous));
1395
1396	/**
1397	* Translates in bulk physical page addresses for memory transactions through the
1398	* IOMMU.
1399	*
1400	* @returns VBox status code.
1401	* @param pDevIns The IOMMU device instance.
1402	* @param idDevice The device identifier (bus, device, function).
1403	* @param cIovas The number of I/O virtual addresses being accessed.
1404	* @param pauIovas The I/O virtual addresses being accessed.
1405	* @param fFlags Access flags, see PDMIOMMU_MEM_F_XXX.
1406	* @param paGCPhysSpa Where to store the translated system physical page
1407	* addresses.
1408	*
1409	* @thread Any.
1410	*/
1411	DECLRCCALLBACKMEMBER(int, pfnMemBulkAccess,(PPDMDEVINS pDevIns, uint16_t idDevice, size_t cIovas, uint64_t const *pauIovas,
1412	uint32_t fFlags, PRTGCPHYS paGCPhysSpa));
1413
1414	/**
1415	* Performs an interrupt remap request through the IOMMU.
1416	*
1417	* @returns VBox status code.
1418	* @param pDevIns The IOMMU device instance.
1419	* @param idDevice The device identifier (bus, device, function).
1420	* @param pMsiIn The source MSI.
1421	* @param pMsiOut Where to store the remapped MSI.
1422	*
1423	* @thread Any.
1424	*/
1425	DECLRCCALLBACKMEMBER(int, pfnMsiRemap,(PPDMDEVINS pDevIns, uint16_t idDevice, PCMSIMSG pMsiIn, PMSIMSG pMsiOut));
1426
1427	/** Just a safety precaution. */
1428	uint32_t u32TheEnd;
1429	} PDMIOMMUREGRC;
1430	/** Pointer to a IOMMU registration structure. */
1431	typedef PDMIOMMUREGRC *PPDMIOMMUREGRC;
1432
1433	/** Current PDMIOMMUREG version number. */
1434	#define PDM_IOMMUREGRC_VERSION PDM_VERSION_MAKE(0xff11, 3, 0)
1435
1436
1437	/**
1438	* IOMMU registration structure for ring-3.
1439	*/
1440	typedef struct PDMIOMMUREGR3
1441	{
1442	/** Structure version number. PDM_IOMMUREG_VERSION defines the current
1443	* version. */
1444	uint32_t u32Version;
1445	/** Padding. */
1446	uint32_t uPadding0;
1447
1448	/**
1449	* Translates the physical address for a memory transaction through the IOMMU.
1450	*
1451	* @returns VBox status code.
1452	* @param pDevIns The IOMMU device instance.
1453	* @param idDevice The device identifier (bus, device, function).
1454	* @param uIova The I/O virtual address being accessed.
1455	* @param cbIova The size of the access.
1456	* @param fFlags Access flags, see PDMIOMMU_MEM_F_XXX.
1457	* @param pGCPhysSpa Where to store the translated system physical address.
1458	* @param pcbContiguous Where to store the number of contiguous bytes translated
1459	* and permission-checked.
1460	*
1461	* @thread Any.
1462	*/
1463	DECLR3CALLBACKMEMBER(int, pfnMemAccess,(PPDMDEVINS pDevIns, uint16_t idDevice, uint64_t uIova, size_t cbIova,
1464	uint32_t fFlags, PRTGCPHYS pGCPhysSpa, size_t *pcbContiguous));
1465
1466	/**
1467	* Translates in bulk physical page addresses for memory transactions through the
1468	* IOMMU.
1469	*
1470	* @returns VBox status code.
1471	* @param pDevIns The IOMMU device instance.
1472	* @param idDevice The device identifier (bus, device, function).
1473	* @param cIovas The number of I/O virtual addresses being accessed.
1474	* @param pauIovas The I/O virtual addresses being accessed.
1475	* @param fFlags Access flags, see PDMIOMMU_MEM_F_XXX.
1476	* @param paGCPhysSpa Where to store the translated system physical page
1477	* addresses.
1478	*
1479	* @thread Any.
1480	*/
1481	DECLR3CALLBACKMEMBER(int, pfnMemBulkAccess,(PPDMDEVINS pDevIns, uint16_t idDevice, size_t cIovas, uint64_t const *pauIovas,
1482	uint32_t fFlags, PRTGCPHYS paGCPhysSpa));
1483
1484	/**
1485	* Performs an interrupt remap request through the IOMMU.
1486	*
1487	* @returns VBox status code.
1488	* @param pDevIns The IOMMU device instance.
1489	* @param idDevice The device identifier (bus, device, function).
1490	* @param pMsiIn The source MSI.
1491	* @param pMsiOut Where to store the remapped MSI.
1492	*
1493	* @thread Any.
1494	*/
1495	DECLR3CALLBACKMEMBER(int, pfnMsiRemap,(PPDMDEVINS pDevIns, uint16_t idDevice, PCMSIMSG pMsiIn, PMSIMSG pMsiOut));
1496
1497	/** Just a safety precaution. */
1498	uint32_t u32TheEnd;
1499	} PDMIOMMUREGR3;
1500	/** Pointer to a IOMMU registration structure. */
1501	typedef PDMIOMMUREGR3 *PPDMIOMMUREGR3;
1502
1503	/** Current PDMIOMMUREG version number. */
1504	#define PDM_IOMMUREGR3_VERSION PDM_VERSION_MAKE(0xff12, 3, 0)
1505
1506	/** IOMMU registration structure for the current context. */
1507	typedef CTX_SUFF(PDMIOMMUREG) PDMIOMMUREGCC;
1508	/** Pointer to an IOMMU registration structure for the current context. */
1509	typedef CTX_SUFF(PPDMIOMMUREG) PPDMIOMMUREGCC;
1510	/** IOMMU registration structure version for the current context. */
1511	#define PDM_IOMMUREGCC_VERSION CTX_MID(PDM_IOMMUREG,_VERSION)
1512
1513
1514	/**
1515	* IOMMU helpers for ring-0.
1516	*/
1517	typedef struct PDMIOMMUHLPR0
1518	{
1519	/** Structure version. PDM_IOMMUHLP_VERSION defines the current version. */
1520	uint32_t u32Version;
1521
1522	/**
1523	* Acquires the PDM lock.
1524	*
1525	* @returns VINF_SUCCESS on success.
1526	* @returns rc if we failed to acquire the lock.
1527	* @param pDevIns The PCI device instance.
1528	* @param rc What to return if we fail to acquire the lock.
1529	*
1530	* @sa PDMCritSectEnter
1531	*/
1532	DECLR0CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
1533
1534	/**
1535	* Releases the PDM lock.
1536	*
1537	* @param pDevIns The PCI device instance.
1538	*/
1539	DECLR0CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
1540
1541	/**
1542	* Check whether the calling thread owns the PDM lock.
1543	*
1544	* @returns @c true if the PDM lock is owned, @c false otherwise.
1545	* @param pDevIns The PCI device instance.
1546	*/
1547	DECLR0CALLBACKMEMBER(bool, pfnLockIsOwner,(PPDMDEVINS pDevIns));
1548
1549	/**
1550	* Send an MSI (when generated by the IOMMU device itself).
1551	*
1552	* @param pDevIns PCI device instance.
1553	* @param pMsi The MSI to send.
1554	* @param uTagSrc The IRQ tag and source (for tracing).
1555	*/
1556	DECLR0CALLBACKMEMBER(void, pfnSendMsi,(PPDMDEVINS pDevIns, PCMSIMSG pMsi, uint32_t uTagSrc));
1557
1558	/** Just a safety precaution. */
1559	uint32_t u32TheEnd;
1560	} PDMIOMMUHLPR0;
1561	/** Pointer to IOMMU helpers for ring-0. */
1562	typedef PDMIOMMUHLPR0 *PPDMIOMMUHLPR0;
1563	/** Pointer to const IOMMU helpers for ring-0. */
1564	typedef const PDMIOMMUHLPR0 *PCPDMIOMMUHLPR0;
1565
1566	/** Current PDMIOMMUHLPR0 version number. */
1567	#define PDM_IOMMUHLPR0_VERSION PDM_VERSION_MAKE(0xff13, 5, 0)
1568
1569
1570	/**
1571	* IOMMU helpers for raw-mode.
1572	*/
1573	typedef struct PDMIOMMUHLPRC
1574	{
1575	/** Structure version. PDM_IOMMUHLP_VERSION defines the current version. */
1576	uint32_t u32Version;
1577
1578	/**
1579	* Acquires the PDM lock.
1580	*
1581	* @returns VINF_SUCCESS on success.
1582	* @returns rc if we failed to acquire the lock.
1583	* @param pDevIns The PCI device instance.
1584	* @param rc What to return if we fail to acquire the lock.
1585	*
1586	* @sa PDMCritSectEnter
1587	*/
1588	DECLRCCALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
1589
1590	/**
1591	* Releases the PDM lock.
1592	*
1593	* @param pDevIns The PCI device instance.
1594	*/
1595	DECLRCCALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
1596
1597	/**
1598	* Check whether the threads owns the PDM lock.
1599	*
1600	* @returns @c true if the PDM lock is owned, @c false otherwise.
1601	* @param pDevIns The PCI device instance.
1602	*/
1603	DECLRCCALLBACKMEMBER(bool, pfnLockIsOwner,(PPDMDEVINS pDevIns));
1604
1605	/**
1606	* Send an MSI (when generated by the IOMMU device itself).
1607	*
1608	* @param pDevIns PCI device instance.
1609	* @param pMsi The MSI to send.
1610	* @param uTagSrc The IRQ tag and source (for tracing).
1611	*/
1612	DECLRCCALLBACKMEMBER(void, pfnSendMsi,(PPDMDEVINS pDevIns, PCMSIMSG pMsi, uint32_t uTagSrc));
1613
1614	/** Just a safety precaution. */
1615	uint32_t u32TheEnd;
1616	} PDMIOMMUHLPRC;
1617	/** Pointer to IOMMU helpers for raw-mode. */
1618	typedef PDMIOMMUHLPRC *PPDMIOMMUHLPRC;
1619	/** Pointer to const IOMMU helpers for raw-mode. */
1620	typedef const PDMIOMMUHLPRC *PCPDMIOMMUHLPRC;
1621
1622	/** Current PDMIOMMUHLPRC version number. */
1623	#define PDM_IOMMUHLPRC_VERSION PDM_VERSION_MAKE(0xff14, 5, 0)
1624
1625
1626	/**
1627	* IOMMU helpers for ring-3.
1628	*/
1629	typedef struct PDMIOMMUHLPR3
1630	{
1631	/** Structure version. PDM_IOMMUHLP_VERSION defines the current version. */
1632	uint32_t u32Version;
1633
1634	/**
1635	* Acquires the PDM lock.
1636	*
1637	* @returns VINF_SUCCESS on success.
1638	* @returns rc if we failed to acquire the lock.
1639	* @param pDevIns The PCI device instance.
1640	* @param rc What to return if we fail to acquire the lock.
1641	*
1642	* @sa PDMCritSectEnter
1643	*/
1644	DECLR3CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
1645
1646	/**
1647	* Releases the PDM lock.
1648	*
1649	* @param pDevIns The PCI device instance.
1650	*/
1651	DECLR3CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
1652
1653	/**
1654	* Check whether the threads owns the PDM lock.
1655	*
1656	* @returns @c true if the PDM lock is owned, @c false otherwise.
1657	* @param pDevIns The PCI device instance.
1658	*/
1659	DECLR3CALLBACKMEMBER(bool, pfnLockIsOwner,(PPDMDEVINS pDevIns));
1660
1661	/**
1662	* Send an MSI (when generated by the IOMMU device itself).
1663	*
1664	* @param pDevIns PCI device instance.
1665	* @param pMsi The MSI to send.
1666	* @param uTagSrc The IRQ tag and source (for tracing).
1667	*/
1668	DECLR3CALLBACKMEMBER(void, pfnSendMsi,(PPDMDEVINS pDevIns, PCMSIMSG pMsi, uint32_t uTagSrc));
1669
1670	/** Just a safety precaution. */
1671	uint32_t u32TheEnd;
1672	} PDMIOMMUHLPR3;
1673	/** Pointer to IOMMU helpers for raw-mode. */
1674	typedef PDMIOMMUHLPR3 *PPDMIOMMUHLPR3;
1675	/** Pointer to const IOMMU helpers for raw-mode. */
1676	typedef const PDMIOMMUHLPR3 *PCPDMIOMMUHLPR3;
1677
1678	/** Current PDMIOMMUHLPR3 version number. */
1679	#define PDM_IOMMUHLPR3_VERSION PDM_VERSION_MAKE(0xff15, 5, 0)
1680
1681
1682	/**
1683	* Programmable Interrupt Controller registration structure (all contexts).
1684	*/
1685	typedef struct PDMPICREG
1686	{
1687	/** Structure version number. PDM_PICREG_VERSION defines the current version. */
1688	uint32_t u32Version;
1689
1690	/**
1691	* Set the an IRQ.
1692	*
1693	* @param pDevIns Device instance of the PIC.
1694	* @param iIrq IRQ number to set.
1695	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
1696	* @param uTagSrc The IRQ tag and source (for tracing).
1697	* @remarks Caller enters the PDM critical section.
1698	*/
1699	DECLCALLBACKMEMBER(void, pfnSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel, uint32_t uTagSrc));
1700
1701	/**
1702	* Get a pending interrupt.
1703	*
1704	* @returns Pending interrupt number.
1705	* @param pDevIns Device instance of the PIC.
1706	* @param puTagSrc Where to return the IRQ tag and source.
1707	* @remarks Caller enters the PDM critical section.
1708	*/
1709	DECLCALLBACKMEMBER(int, pfnGetInterrupt,(PPDMDEVINS pDevIns, uint32_t *puTagSrc));
1710
1711	/** Just a safety precaution. */
1712	uint32_t u32TheEnd;
1713	} PDMPICREG;
1714	/** Pointer to a PIC registration structure. */
1715	typedef PDMPICREG *PPDMPICREG;
1716
1717	/** Current PDMPICREG version number. */
1718	#define PDM_PICREG_VERSION PDM_VERSION_MAKE(0xfffa, 3, 0)
1719
1720	/**
1721	* PIC helpers, same in all contexts.
1722	*/
1723	typedef struct PDMPICHLP
1724	{
1725	/** Structure version. PDM_PICHLP_VERSION defines the current version. */
1726	uint32_t u32Version;
1727
1728	/**
1729	* Set the interrupt force action flag.
1730	*
1731	* @param pDevIns Device instance of the PIC.
1732	*/
1733	DECLCALLBACKMEMBER(void, pfnSetInterruptFF,(PPDMDEVINS pDevIns));
1734
1735	/**
1736	* Clear the interrupt force action flag.
1737	*
1738	* @param pDevIns Device instance of the PIC.
1739	*/
1740	DECLCALLBACKMEMBER(void, pfnClearInterruptFF,(PPDMDEVINS pDevIns));
1741
1742	/**
1743	* Acquires the PDM lock.
1744	*
1745	* @returns VINF_SUCCESS on success.
1746	* @returns rc if we failed to acquire the lock.
1747	* @param pDevIns The PIC device instance.
1748	* @param rc What to return if we fail to acquire the lock.
1749	*
1750	* @sa PDMCritSectEnter
1751	*/
1752	DECLCALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
1753
1754	/**
1755	* Releases the PDM lock.
1756	*
1757	* @param pDevIns The PIC device instance.
1758	*/
1759	DECLCALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
1760
1761	/** Just a safety precaution. */
1762	uint32_t u32TheEnd;
1763	} PDMPICHLP;
1764	/** Pointer to PIC helpers. */
1765	typedef PDMPICHLP *PPDMPICHLP;
1766	/** Pointer to const PIC helpers. */
1767	typedef const PDMPICHLP *PCPDMPICHLP;
1768
1769	/** Current PDMPICHLP version number. */
1770	#define PDM_PICHLP_VERSION PDM_VERSION_MAKE(0xfff9, 3, 0)
1771
1772
1773	/**
1774	* Firmware registration structure.
1775	*/
1776	typedef struct PDMFWREG
1777	{
1778	/** Struct version+magic number (PDM_FWREG_VERSION). */
1779	uint32_t u32Version;
1780
1781	/**
1782	* Checks whether this is a hard or soft reset.
1783	*
1784	* The current definition of soft reset is what the PC BIOS does when CMOS[0xF]
1785	* is 5, 9 or 0xA.
1786	*
1787	* @returns true if hard reset, false if soft.
1788	* @param pDevIns Device instance of the firmware.
1789	* @param fFlags PDMRESET_F_XXX passed to the PDMDevHlpVMReset API.
1790	*/
1791	DECLR3CALLBACKMEMBER(bool, pfnIsHardReset,(PPDMDEVINS pDevIns, uint32_t fFlags));
1792
1793	/** Just a safety precaution. */
1794	uint32_t u32TheEnd;
1795	} PDMFWREG;
1796	/** Pointer to a FW registration structure. */
1797	typedef PDMFWREG *PPDMFWREG;
1798	/** Pointer to a const FW registration structure. */
1799	typedef PDMFWREG const *PCPDMFWREG;
1800
1801	/** Current PDMFWREG version number. */
1802	#define PDM_FWREG_VERSION PDM_VERSION_MAKE(0xffdd, 1, 0)
1803
1804	/**
1805	* Firmware R3 helpers.
1806	*/
1807	typedef struct PDMFWHLPR3
1808	{
1809	/** Structure version. PDM_FWHLP_VERSION defines the current version. */
1810	uint32_t u32Version;
1811
1812	/** Just a safety precaution. */
1813	uint32_t u32TheEnd;
1814	} PDMFWHLPR3;
1815
1816	/** Pointer to FW R3 helpers. */
1817	typedef R3PTRTYPE(PDMFWHLPR3 *) PPDMFWHLPR3;
1818	/** Pointer to const FW R3 helpers. */
1819	typedef R3PTRTYPE(const PDMFWHLPR3 *) PCPDMFWHLPR3;
1820
1821	/** Current PDMFWHLPR3 version number. */
1822	#define PDM_FWHLPR3_VERSION PDM_VERSION_MAKE(0xffdb, 1, 0)
1823
1824
1825	/**
1826	* I/O APIC registration structure (all contexts).
1827	*/
1828	typedef struct PDMIOAPICREG
1829	{
1830	/** Struct version+magic number (PDM_IOAPICREG_VERSION). */
1831	uint32_t u32Version;
1832
1833	/**
1834	* Set an IRQ.
1835	*
1836	* @param pDevIns Device instance of the I/O APIC.
1837	* @param uBusDevFn The bus:device:function of the device initiating the
1838	* IRQ. Can be NIL_PCIBDF.
1839	* @param iIrq IRQ number to set.
1840	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
1841	* @param uTagSrc The IRQ tag and source (for tracing).
1842	*
1843	* @remarks Caller enters the PDM critical section
1844	* Actually, as per 2018-07-21 this isn't true (bird).
1845	*/
1846	DECLCALLBACKMEMBER(void, pfnSetIrq,(PPDMDEVINS pDevIns, PCIBDF uBusDevFn, int iIrq, int iLevel, uint32_t uTagSrc));
1847
1848	/**
1849	* Send a MSI.
1850	*
1851	* @param pDevIns Device instance of the I/O APIC.
1852	* @param uBusDevFn The bus:device:function of the device initiating the
1853	* MSI. Cannot be NIL_PCIBDF.
1854	* @param pMsi The MSI to send.
1855	* @param uTagSrc The IRQ tag and source (for tracing).
1856	*
1857	* @remarks Caller enters the PDM critical section
1858	* Actually, as per 2018-07-21 this isn't true (bird).
1859	*/
1860	DECLCALLBACKMEMBER(void, pfnSendMsi,(PPDMDEVINS pDevIns, PCIBDF uBusDevFn, PCMSIMSG pMsi, uint32_t uTagSrc));
1861
1862	/**
1863	* Set the EOI for an interrupt vector.
1864	*
1865	* @param pDevIns Device instance of the I/O APIC.
1866	* @param u8Vector The vector.
1867	*
1868	* @remarks Caller enters the PDM critical section
1869	* Actually, as per 2018-07-21 this isn't true (bird).
1870	*/
1871	DECLCALLBACKMEMBER(void, pfnSetEoi,(PPDMDEVINS pDevIns, uint8_t u8Vector));
1872
1873	/** Just a safety precaution. */
1874	uint32_t u32TheEnd;
1875	} PDMIOAPICREG;
1876	/** Pointer to an APIC registration structure. */
1877	typedef PDMIOAPICREG *PPDMIOAPICREG;
1878
1879	/** Current PDMAPICREG version number. */
1880	#define PDM_IOAPICREG_VERSION PDM_VERSION_MAKE(0xfff2, 8, 0)
1881
1882
1883	/**
1884	* IOAPIC helpers, same in all contexts.
1885	*/
1886	typedef struct PDMIOAPICHLP
1887	{
1888	/** Structure version. PDM_IOAPICHLP_VERSION defines the current version. */
1889	uint32_t u32Version;
1890
1891	/**
1892	* Private interface between the IOAPIC and APIC.
1893	*
1894	* @returns status code.
1895	* @param pDevIns Device instance of the IOAPIC.
1896	* @param u8Dest See APIC implementation.
1897	* @param u8DestMode See APIC implementation.
1898	* @param u8DeliveryMode See APIC implementation.
1899	* @param uVector See APIC implementation.
1900	* @param u8Polarity See APIC implementation.
1901	* @param u8TriggerMode See APIC implementation.
1902	* @param uTagSrc The IRQ tag and source (for tracing).
1903	*
1904	* @sa PDMApicBusDeliver()
1905	*/
1906	DECLCALLBACKMEMBER(int, pfnApicBusDeliver,(PPDMDEVINS pDevIns, uint8_t u8Dest, uint8_t u8DestMode, uint8_t u8DeliveryMode,
1907	uint8_t uVector, uint8_t u8Polarity, uint8_t u8TriggerMode, uint32_t uTagSrc));
1908
1909	/**
1910	* Acquires the PDM lock.
1911	*
1912	* @returns VINF_SUCCESS on success.
1913	* @returns rc if we failed to acquire the lock.
1914	* @param pDevIns The IOAPIC device instance.
1915	* @param rc What to return if we fail to acquire the lock.
1916	*
1917	* @sa PDMCritSectEnter
1918	*/
1919	DECLCALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
1920
1921	/**
1922	* Releases the PDM lock.
1923	*
1924	* @param pDevIns The IOAPIC device instance.
1925	*/
1926	DECLCALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
1927
1928	/**
1929	* Checks if the calling thread owns the PDM lock.
1930	*
1931	* @param pDevIns The IOAPIC device instance.
1932	*/
1933	DECLCALLBACKMEMBER(bool, pfnLockIsOwner,(PPDMDEVINS pDevIns));
1934
1935	/**
1936	* Private interface between the IOAPIC and IOMMU.
1937	*
1938	* @returns status code.
1939	* @param pDevIns Device instance of the IOAPIC.
1940	* @param idDevice The device identifier (bus, device, function).
1941	* @param pMsiIn The source MSI.
1942	* @param pMsiOut Where to store the remapped MSI (only updated when
1943	* VINF_SUCCESS is returned).
1944	*/
1945	DECLCALLBACKMEMBER(int, pfnIommuMsiRemap,(PPDMDEVINS pDevIns, uint16_t idDevice, PCMSIMSG pMsiIn, PMSIMSG pMsiOut));
1946
1947	/** Just a safety precaution. */
1948	uint32_t u32TheEnd;
1949	} PDMIOAPICHLP;
1950	/** Pointer to IOAPIC helpers. */
1951	typedef PDMIOAPICHLP * PPDMIOAPICHLP;
1952	/** Pointer to const IOAPIC helpers. */
1953	typedef const PDMIOAPICHLP * PCPDMIOAPICHLP;
1954
1955	/** Current PDMIOAPICHLP version number. */
1956	#define PDM_IOAPICHLP_VERSION PDM_VERSION_MAKE(0xfff0, 3, 1)
1957
1958
1959	/**
1960	* HPET registration structure.
1961	*/
1962	typedef struct PDMHPETREG
1963	{
1964	/** Struct version+magic number (PDM_HPETREG_VERSION). */
1965	uint32_t u32Version;
1966	} PDMHPETREG;
1967	/** Pointer to an HPET registration structure. */
1968	typedef PDMHPETREG *PPDMHPETREG;
1969
1970	/** Current PDMHPETREG version number. */
1971	#define PDM_HPETREG_VERSION PDM_VERSION_MAKE(0xffe2, 1, 0)
1972
1973	/**
1974	* HPET RC helpers.
1975	*
1976	* @remarks Keep this around in case HPET will need PDM interaction in again RC
1977	* at some later point.
1978	*/
1979	typedef struct PDMHPETHLPRC
1980	{
1981	/** Structure version. PDM_HPETHLPRC_VERSION defines the current version. */
1982	uint32_t u32Version;
1983
1984	/** Just a safety precaution. */
1985	uint32_t u32TheEnd;
1986	} PDMHPETHLPRC;
1987
1988	/** Pointer to HPET RC helpers. */
1989	typedef RCPTRTYPE(PDMHPETHLPRC *) PPDMHPETHLPRC;
1990	/** Pointer to const HPET RC helpers. */
1991	typedef RCPTRTYPE(const PDMHPETHLPRC *) PCPDMHPETHLPRC;
1992
1993	/** Current PDMHPETHLPRC version number. */
1994	#define PDM_HPETHLPRC_VERSION PDM_VERSION_MAKE(0xffee, 2, 0)
1995
1996
1997	/**
1998	* HPET R0 helpers.
1999	*
2000	* @remarks Keep this around in case HPET will need PDM interaction in again R0
2001	* at some later point.
2002	*/
2003	typedef struct PDMHPETHLPR0
2004	{
2005	/** Structure version. PDM_HPETHLPR0_VERSION defines the current version. */
2006	uint32_t u32Version;
2007
2008	/** Just a safety precaution. */
2009	uint32_t u32TheEnd;
2010	} PDMHPETHLPR0;
2011
2012	/** Pointer to HPET R0 helpers. */
2013	typedef R0PTRTYPE(PDMHPETHLPR0 *) PPDMHPETHLPR0;
2014	/** Pointer to const HPET R0 helpers. */
2015	typedef R0PTRTYPE(const PDMHPETHLPR0 *) PCPDMHPETHLPR0;
2016
2017	/** Current PDMHPETHLPR0 version number. */
2018	#define PDM_HPETHLPR0_VERSION PDM_VERSION_MAKE(0xffed, 2, 0)
2019
2020	/**
2021	* HPET R3 helpers.
2022	*/
2023	typedef struct PDMHPETHLPR3
2024	{
2025	/** Structure version. PDM_HPETHLP_VERSION defines the current version. */
2026	uint32_t u32Version;
2027
2028	/**
2029	* Set legacy mode on PIT and RTC.
2030	*
2031	* @returns VINF_SUCCESS on success.
2032	* @returns rc if we failed to set legacy mode.
2033	* @param pDevIns Device instance of the HPET.
2034	* @param fActivated Whether legacy mode is activated or deactivated.
2035	*/
2036	DECLR3CALLBACKMEMBER(int, pfnSetLegacyMode,(PPDMDEVINS pDevIns, bool fActivated));
2037
2038
2039	/**
2040	* Set IRQ, bypassing ISA bus override rules.
2041	*
2042	* @returns VINF_SUCCESS on success.
2043	* @returns rc if we failed to set legacy mode.
2044	* @param pDevIns Device instance of the HPET.
2045	* @param iIrq IRQ number to set.
2046	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
2047	*/
2048	DECLR3CALLBACKMEMBER(int, pfnSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
2049
2050	/** Just a safety precaution. */
2051	uint32_t u32TheEnd;
2052	} PDMHPETHLPR3;
2053
2054	/** Pointer to HPET R3 helpers. */
2055	typedef R3PTRTYPE(PDMHPETHLPR3 *) PPDMHPETHLPR3;
2056	/** Pointer to const HPET R3 helpers. */
2057	typedef R3PTRTYPE(const PDMHPETHLPR3 *) PCPDMHPETHLPR3;
2058
2059	/** Current PDMHPETHLPR3 version number. */
2060	#define PDM_HPETHLPR3_VERSION PDM_VERSION_MAKE(0xffec, 3, 0)
2061
2062
2063	/**
2064	* Raw PCI device registration structure.
2065	*/
2066	typedef struct PDMPCIRAWREG
2067	{
2068	/** Struct version+magic number (PDM_PCIRAWREG_VERSION). */
2069	uint32_t u32Version;
2070	/** Just a safety precaution. */
2071	uint32_t u32TheEnd;
2072	} PDMPCIRAWREG;
2073	/** Pointer to a raw PCI registration structure. */
2074	typedef PDMPCIRAWREG *PPDMPCIRAWREG;
2075
2076	/** Current PDMPCIRAWREG version number. */
2077	#define PDM_PCIRAWREG_VERSION PDM_VERSION_MAKE(0xffe1, 1, 0)
2078
2079	/**
2080	* Raw PCI device raw-mode context helpers.
2081	*/
2082	typedef struct PDMPCIRAWHLPRC
2083	{
2084	/** Structure version and magic number (PDM_PCIRAWHLPRC_VERSION). */
2085	uint32_t u32Version;
2086	/** Just a safety precaution. */
2087	uint32_t u32TheEnd;
2088	} PDMPCIRAWHLPRC;
2089	/** Pointer to a raw PCI deviec raw-mode context helper structure. */
2090	typedef RCPTRTYPE(PDMPCIRAWHLPRC *) PPDMPCIRAWHLPRC;
2091	/** Pointer to a const raw PCI deviec raw-mode context helper structure. */
2092	typedef RCPTRTYPE(const PDMPCIRAWHLPRC *) PCPDMPCIRAWHLPRC;
2093
2094	/** Current PDMPCIRAWHLPRC version number. */
2095	#define PDM_PCIRAWHLPRC_VERSION PDM_VERSION_MAKE(0xffe0, 1, 0)
2096
2097	/**
2098	* Raw PCI device ring-0 context helpers.
2099	*/
2100	typedef struct PDMPCIRAWHLPR0
2101	{
2102	/** Structure version and magic number (PDM_PCIRAWHLPR0_VERSION). */
2103	uint32_t u32Version;
2104	/** Just a safety precaution. */
2105	uint32_t u32TheEnd;
2106	} PDMPCIRAWHLPR0;
2107	/** Pointer to a raw PCI deviec ring-0 context helper structure. */
2108	typedef R0PTRTYPE(PDMPCIRAWHLPR0 *) PPDMPCIRAWHLPR0;
2109	/** Pointer to a const raw PCI deviec ring-0 context helper structure. */
2110	typedef R0PTRTYPE(const PDMPCIRAWHLPR0 *) PCPDMPCIRAWHLPR0;
2111
2112	/** Current PDMPCIRAWHLPR0 version number. */
2113	#define PDM_PCIRAWHLPR0_VERSION PDM_VERSION_MAKE(0xffdf, 1, 0)
2114
2115
2116	/**
2117	* Raw PCI device ring-3 context helpers.
2118	*/
2119	typedef struct PDMPCIRAWHLPR3
2120	{
2121	/** Undefined structure version and magic number. */
2122	uint32_t u32Version;
2123
2124	/**
2125	* Gets the address of the RC raw PCI device helpers.
2126	*
2127	* This should be called at both construction and relocation time to obtain
2128	* the correct address of the RC helpers.
2129	*
2130	* @returns RC pointer to the raw PCI device helpers.
2131	* @param pDevIns Device instance of the raw PCI device.
2132	*/
2133	DECLR3CALLBACKMEMBER(PCPDMPCIRAWHLPRC, pfnGetRCHelpers,(PPDMDEVINS pDevIns));
2134
2135	/**
2136	* Gets the address of the R0 raw PCI device helpers.
2137	*
2138	* This should be called at both construction and relocation time to obtain
2139	* the correct address of the R0 helpers.
2140	*
2141	* @returns R0 pointer to the raw PCI device helpers.
2142	* @param pDevIns Device instance of the raw PCI device.
2143	*/
2144	DECLR3CALLBACKMEMBER(PCPDMPCIRAWHLPR0, pfnGetR0Helpers,(PPDMDEVINS pDevIns));
2145
2146	/** Just a safety precaution. */
2147	uint32_t u32TheEnd;
2148	} PDMPCIRAWHLPR3;
2149	/** Pointer to raw PCI R3 helpers. */
2150	typedef R3PTRTYPE(PDMPCIRAWHLPR3 *) PPDMPCIRAWHLPR3;
2151	/** Pointer to const raw PCI R3 helpers. */
2152	typedef R3PTRTYPE(const PDMPCIRAWHLPR3 *) PCPDMPCIRAWHLPR3;
2153
2154	/** Current PDMPCIRAWHLPR3 version number. */
2155	#define PDM_PCIRAWHLPR3_VERSION PDM_VERSION_MAKE(0xffde, 1, 0)
2156
2157
2158	#ifdef IN_RING3
2159
2160	/**
2161	* DMA Transfer Handler.
2162	*
2163	* @returns Number of bytes transferred.
2164	* @param pDevIns The device instance that registered the handler.
2165	* @param pvUser User pointer.
2166	* @param uChannel Channel number.
2167	* @param off DMA position.
2168	* @param cb Block size.
2169	* @remarks The device lock is take before the callback (in fact, the locks of
2170	* DMA devices and the DMA controller itself are taken).
2171	*/
2172	typedef DECLCALLBACKTYPE(uint32_t, FNDMATRANSFERHANDLER,(PPDMDEVINS pDevIns, void *pvUser, unsigned uChannel,
2173	uint32_t off, uint32_t cb));
2174	/** Pointer to a FNDMATRANSFERHANDLER(). */
2175	typedef FNDMATRANSFERHANDLER *PFNDMATRANSFERHANDLER;
2176
2177	/**
2178	* DMA Controller registration structure.
2179	*/
2180	typedef struct PDMDMAREG
2181	{
2182	/** Structure version number. PDM_DMACREG_VERSION defines the current version. */
2183	uint32_t u32Version;
2184
2185	/**
2186	* Execute pending transfers.
2187	*
2188	* @returns A more work indiciator. I.e. 'true' if there is more to be done, and 'false' if all is done.
2189	* @param pDevIns Device instance of the DMAC.
2190	* @remarks No locks held, called on EMT(0) as a form of serialization.
2191	*/
2192	DECLR3CALLBACKMEMBER(bool, pfnRun,(PPDMDEVINS pDevIns));
2193
2194	/**
2195	* Register transfer function for DMA channel.
2196	*
2197	* @param pDevIns Device instance of the DMAC.
2198	* @param uChannel Channel number.
2199	* @param pDevInsHandler The device instance of the device making the
2200	* regstration (will be passed to the callback).
2201	* @param pfnTransferHandler Device specific transfer function.
2202	* @param pvUser User pointer to be passed to the callback.
2203	* @remarks No locks held, called on an EMT.
2204	*/
2205	DECLR3CALLBACKMEMBER(void, pfnRegister,(PPDMDEVINS pDevIns, unsigned uChannel, PPDMDEVINS pDevInsHandler,
2206	PFNDMATRANSFERHANDLER pfnTransferHandler, void *pvUser));
2207
2208	/**
2209	* Read memory
2210	*
2211	* @returns Number of bytes read.
2212	* @param pDevIns Device instance of the DMAC.
2213	* @param uChannel Channel number.
2214	* @param pvBuffer Pointer to target buffer.
2215	* @param off DMA position.
2216	* @param cbBlock Block size.
2217	* @remarks No locks held, called on an EMT.
2218	*/
2219	DECLR3CALLBACKMEMBER(uint32_t, pfnReadMemory,(PPDMDEVINS pDevIns, unsigned uChannel, void *pvBuffer, uint32_t off, uint32_t cbBlock));
2220
2221	/**
2222	* Write memory
2223	*
2224	* @returns Number of bytes written.
2225	* @param pDevIns Device instance of the DMAC.
2226	* @param uChannel Channel number.
2227	* @param pvBuffer Memory to write.
2228	* @param off DMA position.
2229	* @param cbBlock Block size.
2230	* @remarks No locks held, called on an EMT.
2231	*/
2232	DECLR3CALLBACKMEMBER(uint32_t, pfnWriteMemory,(PPDMDEVINS pDevIns, unsigned uChannel, const void *pvBuffer, uint32_t off, uint32_t cbBlock));
2233
2234	/**
2235	* Set the DREQ line.
2236	*
2237	* @param pDevIns Device instance of the DMAC.
2238	* @param uChannel Channel number.
2239	* @param uLevel Level of the line.
2240	* @remarks No locks held, called on an EMT.
2241	*/
2242	DECLR3CALLBACKMEMBER(void, pfnSetDREQ,(PPDMDEVINS pDevIns, unsigned uChannel, unsigned uLevel));
2243
2244	/**
2245	* Get channel mode
2246	*
2247	* @returns Channel mode.
2248	* @param pDevIns Device instance of the DMAC.
2249	* @param uChannel Channel number.
2250	* @remarks No locks held, called on an EMT.
2251	*/
2252	DECLR3CALLBACKMEMBER(uint8_t, pfnGetChannelMode,(PPDMDEVINS pDevIns, unsigned uChannel));
2253
2254	} PDMDMACREG;
2255	/** Pointer to a DMAC registration structure. */
2256	typedef PDMDMACREG *PPDMDMACREG;
2257
2258	/** Current PDMDMACREG version number. */
2259	#define PDM_DMACREG_VERSION PDM_VERSION_MAKE(0xffeb, 2, 0)
2260
2261
2262	/**
2263	* DMA Controller device helpers.
2264	*/
2265	typedef struct PDMDMACHLP
2266	{
2267	/** Structure version. PDM_DMACHLP_VERSION defines the current version. */
2268	uint32_t u32Version;
2269
2270	/* to-be-defined */
2271
2272	} PDMDMACHLP;
2273	/** Pointer to DMAC helpers. */
2274	typedef PDMDMACHLP *PPDMDMACHLP;
2275	/** Pointer to const DMAC helpers. */
2276	typedef const PDMDMACHLP *PCPDMDMACHLP;
2277
2278	/** Current PDMDMACHLP version number. */
2279	#define PDM_DMACHLP_VERSION PDM_VERSION_MAKE(0xffea, 1, 0)
2280
2281	#endif /* IN_RING3 */
2282
2283
2284
2285	/**
2286	* RTC registration structure.
2287	*/
2288	typedef struct PDMRTCREG
2289	{
2290	/** Structure version number. PDM_RTCREG_VERSION defines the current version. */
2291	uint32_t u32Version;
2292	uint32_t u32Alignment; /*< structure size alignment. /
2293
2294	/**
2295	* Write to a CMOS register and update the checksum if necessary.
2296	*
2297	* @returns VBox status code.
2298	* @param pDevIns Device instance of the RTC.
2299	* @param iReg The CMOS register index.
2300	* @param u8Value The CMOS register value.
2301	* @remarks Caller enters the device critical section.
2302	*/
2303	DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMDEVINS pDevIns, unsigned iReg, uint8_t u8Value));
2304
2305	/**
2306	* Read a CMOS register.
2307	*
2308	* @returns VBox status code.
2309	* @param pDevIns Device instance of the RTC.
2310	* @param iReg The CMOS register index.
2311	* @param pu8Value Where to store the CMOS register value.
2312	* @remarks Caller enters the device critical section.
2313	*/
2314	DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMDEVINS pDevIns, unsigned iReg, uint8_t *pu8Value));
2315
2316	} PDMRTCREG;
2317	/** Pointer to a RTC registration structure. */
2318	typedef PDMRTCREG *PPDMRTCREG;
2319	/** Pointer to a const RTC registration structure. */
2320	typedef const PDMRTCREG *PCPDMRTCREG;
2321
2322	/** Current PDMRTCREG version number. */
2323	#define PDM_RTCREG_VERSION PDM_VERSION_MAKE(0xffe9, 2, 0)
2324
2325
2326	/**
2327	* RTC device helpers.
2328	*/
2329	typedef struct PDMRTCHLP
2330	{
2331	/** Structure version. PDM_RTCHLP_VERSION defines the current version. */
2332	uint32_t u32Version;
2333
2334	/* to-be-defined */
2335
2336	} PDMRTCHLP;
2337	/** Pointer to RTC helpers. */
2338	typedef PDMRTCHLP *PPDMRTCHLP;
2339	/** Pointer to const RTC helpers. */
2340	typedef const PDMRTCHLP *PCPDMRTCHLP;
2341
2342	/** Current PDMRTCHLP version number. */
2343	#define PDM_RTCHLP_VERSION PDM_VERSION_MAKE(0xffe8, 1, 0)
2344
2345
2346
2347	/** @name Flags for PCI I/O region registration
2348	* @{ */
2349	/** No handle is passed. */
2350	#define PDMPCIDEV_IORGN_F_NO_HANDLE UINT32_C(0x00000000)
2351	/** An I/O port handle is passed. */
2352	#define PDMPCIDEV_IORGN_F_IOPORT_HANDLE UINT32_C(0x00000001)
2353	/** An MMIO range handle is passed. */
2354	#define PDMPCIDEV_IORGN_F_MMIO_HANDLE UINT32_C(0x00000002)
2355	/** An MMIO2 handle is passed. */
2356	#define PDMPCIDEV_IORGN_F_MMIO2_HANDLE UINT32_C(0x00000003)
2357	/** Handle type mask. */
2358	#define PDMPCIDEV_IORGN_F_HANDLE_MASK UINT32_C(0x00000003)
2359	/** New-style (mostly wrt callbacks). */
2360	#define PDMPCIDEV_IORGN_F_NEW_STYLE UINT32_C(0x00000004)
2361	/** Mask of valid flags. */
2362	#define PDMPCIDEV_IORGN_F_VALID_MASK UINT32_C(0x00000007)
2363	/** @} */
2364
2365
2366	/** @name Flags for the guest physical read/write helpers
2367	* @{ */
2368	/** Default flag with no indication whether the data is processed by the device or just passed through. */
2369	#define PDM_DEVHLP_PHYS_RW_F_DEFAULT UINT32_C(0x00000000)
2370	/** The data is user data which is just passed through between the guest and the source or destination and not processed
2371	* by the device in any way. */
2372	#define PDM_DEVHLP_PHYS_RW_F_DATA_USER RT_BIT_32(0)
2373	/** The data is metadata and being processed by the device in some way. */
2374	#define PDM_DEVHLP_PHYS_RW_F_DATA_META RT_BIT_32(1)
2375	/** @} */
2376
2377
2378	#ifdef IN_RING3
2379
2380	/** @name Special values for PDMDEVHLPR3::pfnPCIRegister parameters.
2381	* @{ */
2382	/** Same device number (and bus) as the previous PCI device registered with the PDM device.
2383	* This is handy when registering multiple PCI device functions and the device
2384	* number is left up to the PCI bus. In order to facilitate one PDM device
2385	* instance for each PCI function, this searches earlier PDM device
2386	* instances as well. */
2387	# define PDMPCIDEVREG_DEV_NO_SAME_AS_PREV UINT8_C(0xfd)
2388	/** Use the first unused device number (all functions must be unused). */
2389	# define PDMPCIDEVREG_DEV_NO_FIRST_UNUSED UINT8_C(0xfe)
2390	/** Use the first unused device function. */
2391	# define PDMPCIDEVREG_FUN_NO_FIRST_UNUSED UINT8_C(0xff)
2392
2393	/** The device and function numbers are not mandatory, just suggestions. */
2394	# define PDMPCIDEVREG_F_NOT_MANDATORY_NO RT_BIT_32(0)
2395	/** Registering a PCI bridge device. */
2396	# define PDMPCIDEVREG_F_PCI_BRIDGE RT_BIT_32(1)
2397	/** Valid flag mask. */
2398	# define PDMPCIDEVREG_F_VALID_MASK UINT32_C(0x00000003)
2399	/** @} */
2400
2401	/** Current PDMDEVHLPR3 version number. */
2402	#define PDM_DEVHLPR3_VERSION PDM_VERSION_MAKE_PP(0xffe7, 67, 0)
2403
2404	/**
2405	* PDM Device API.
2406	*/
2407	typedef struct PDMDEVHLPR3
2408	{
2409	/** Structure version. PDM_DEVHLPR3_VERSION defines the current version. */
2410	uint32_t u32Version;
2411
2412	/** @name I/O ports
2413	* @{ */
2414	/**
2415	* Creates a range of I/O ports for a device.
2416	*
2417	* The I/O port range must be mapped in a separately call. Any ring-0 and
2418	* raw-mode context callback handlers needs to be set up in the respective
2419	* contexts.
2420	*
2421	* @returns VBox status.
2422	* @param pDevIns The device instance to register the ports with.
2423	* @param cPorts Number of ports to register.
2424	* @param fFlags IOM_IOPORT_F_XXX.
2425	* @param pPciDev The PCI device the range is associated with, if
2426	* applicable.
2427	* @param iPciRegion The PCI device region in the high 16-bit word and
2428	* sub-region in the low 16-bit word. UINT32_MAX if NA.
2429	* @param pfnOut Pointer to function which is gonna handle OUT
2430	* operations. Optional.
2431	* @param pfnIn Pointer to function which is gonna handle IN operations.
2432	* Optional.
2433	* @param pfnOutStr Pointer to function which is gonna handle string OUT
2434	* operations. Optional.
2435	* @param pfnInStr Pointer to function which is gonna handle string IN
2436	* operations. Optional.
2437	* @param pvUser User argument to pass to the callbacks.
2438	* @param pszDesc Pointer to description string. This must not be freed.
2439	* @param paExtDescs Extended per-port descriptions, optional. Partial range
2440	* coverage is allowed. This must not be freed.
2441	* @param phIoPorts Where to return the I/O port range handle.
2442	*
2443	* @remarks Caller enters the device critical section prior to invoking the
2444	* registered callback methods.
2445	*
2446	* @sa PDMDevHlpIoPortSetUpContext, PDMDevHlpIoPortMap,
2447	* PDMDevHlpIoPortUnmap.
2448	*/
2449	DECLR3CALLBACKMEMBER(int, pfnIoPortCreateEx,(PPDMDEVINS pDevIns, RTIOPORT cPorts, uint32_t fFlags, PPDMPCIDEV pPciDev,
2450	uint32_t iPciRegion, PFNIOMIOPORTNEWOUT pfnOut, PFNIOMIOPORTNEWIN pfnIn,
2451	PFNIOMIOPORTNEWOUTSTRING pfnOutStr, PFNIOMIOPORTNEWINSTRING pfnInStr, RTR3PTR pvUser,
2452	const char *pszDesc, PCIOMIOPORTDESC paExtDescs, PIOMIOPORTHANDLE phIoPorts));
2453
2454	/**
2455	* Maps an I/O port range.
2456	*
2457	* @returns VBox status.
2458	* @param pDevIns The device instance to register the ports with.
2459	* @param hIoPorts The I/O port range handle.
2460	* @param Port Where to map the range.
2461	* @sa PDMDevHlpIoPortUnmap, PDMDevHlpIoPortSetUpContext,
2462	* PDMDevHlpIoPortCreate, PDMDevHlpIoPortCreateEx.
2463	*/
2464	DECLR3CALLBACKMEMBER(int, pfnIoPortMap,(PPDMDEVINS pDevIns, IOMIOPORTHANDLE hIoPorts, RTIOPORT Port));
2465
2466	/**
2467	* Unmaps an I/O port range.
2468	*
2469	* @returns VBox status.
2470	* @param pDevIns The device instance to register the ports with.
2471	* @param hIoPorts The I/O port range handle.
2472	* @sa PDMDevHlpIoPortMap, PDMDevHlpIoPortSetUpContext,
2473	* PDMDevHlpIoPortCreate, PDMDevHlpIoPortCreateEx.
2474	*/
2475	DECLR3CALLBACKMEMBER(int, pfnIoPortUnmap,(PPDMDEVINS pDevIns, IOMIOPORTHANDLE hIoPorts));
2476
2477	/**
2478	* Gets the mapping address of the I/O port range @a hIoPorts.
2479	*
2480	* @returns Mapping address (0..65535) or UINT32_MAX if not mapped (or invalid
2481	* parameters).
2482	* @param pDevIns The device instance to register the ports with.
2483	* @param hIoPorts The I/O port range handle.
2484	*/
2485	DECLR3CALLBACKMEMBER(uint32_t, pfnIoPortGetMappingAddress,(PPDMDEVINS pDevIns, IOMIOPORTHANDLE hIoPorts));
2486
2487	/**
2488	* Reads from an I/O port register.
2489	*
2490	* @returns Strict VBox status code. Informational status codes other than the one documented
2491	* here are to be treated as internal failure. Use IOM_SUCCESS() to check for success.
2492	* @retval VINF_SUCCESS Success.
2493	* @retval VINF_EM_FIRST-VINF_EM_LAST Success with some exceptions (see IOM_SUCCESS()), the
2494	* status code must be passed on to EM.
2495	*
2496	* @param pDevIns The device instance to register the ports with.
2497	* @param Port The port to read from.
2498	* @param pu32Value Where to store the read value.
2499	* @param cbValue The size of the register to read in bytes. 1, 2 or 4 bytes.
2500	*
2501	* @thread EMT
2502	*
2503	* @note This is required for the ARM platform in order to emulate PIO accesses through a dedicated MMIO region.
2504	*/
2505	DECLR3CALLBACKMEMBER(VBOXSTRICTRC, pfnIoPortRead,(PPDMDEVINS pDevIns, RTIOPORT Port, uint32_t *pu32Value, size_t cbValue));
2506
2507	/**
2508	* Writes to an I/O port register.
2509	*
2510	* @returns Strict VBox status code. Informational status codes other than the one documented
2511	* here are to be treated as internal failure. Use IOM_SUCCESS() to check for success.
2512	* @retval VINF_SUCCESS Success.
2513	* @retval VINF_EM_FIRST-VINF_EM_LAST Success with some exceptions (see IOM_SUCCESS()), the
2514	* status code must be passed on to EM.
2515	*
2516	* @param pDevIns The device instance to register the ports with.
2517	* @param Port The port to write to.
2518	* @param u32Value The value to write.
2519	* @param cbValue The size of the register to write in bytes. 1, 2 or 4 bytes.
2520	*
2521	* @thread EMT
2522	*
2523	* @note This is required for the ARM platform in order to emulate PIO accesses through a dedicated MMIO region.
2524	*/
2525	DECLR3CALLBACKMEMBER(VBOXSTRICTRC, pfnIoPortWrite,(PPDMDEVINS pDevIns, RTIOPORT Port, uint32_t u32Value, size_t cbValue));
2526	/** @} */
2527
2528	/** @name MMIO
2529	* @{ */
2530	/**
2531	* Creates a memory mapped I/O (MMIO) region for a device.
2532	*
2533	* The MMIO region must be mapped in a separately call. Any ring-0 and
2534	* raw-mode context callback handlers needs to be set up in the respective
2535	* contexts.
2536	*
2537	* @returns VBox status.
2538	* @param pDevIns The device instance to register the ports with.
2539	* @param cbRegion The size of the region in bytes.
2540	* @param fFlags Flags, IOMMMIO_FLAGS_XXX.
2541	* @param pPciDev The PCI device the range is associated with, if
2542	* applicable.
2543	* @param iPciRegion The PCI device region in the high 16-bit word and
2544	* sub-region in the low 16-bit word. UINT32_MAX if NA.
2545	* @param pfnWrite Pointer to function which is gonna handle Write
2546	* operations.
2547	* @param pfnRead Pointer to function which is gonna handle Read
2548	* operations.
2549	* @param pfnFill Pointer to function which is gonna handle Fill/memset
2550	* operations. (optional)
2551	* @param pvUser User argument to pass to the callbacks.
2552	* @param pszDesc Pointer to description string. This must not be freed.
2553	* @param phRegion Where to return the MMIO region handle.
2554	*
2555	* @remarks Caller enters the device critical section prior to invoking the
2556	* registered callback methods.
2557	*
2558	* @sa PDMDevHlpMmioSetUpContext, PDMDevHlpMmioMap, PDMDevHlpMmioUnmap.
2559	*/
2560	DECLR3CALLBACKMEMBER(int, pfnMmioCreateEx,(PPDMDEVINS pDevIns, RTGCPHYS cbRegion,
2561	uint32_t fFlags, PPDMPCIDEV pPciDev, uint32_t iPciRegion,
2562	PFNIOMMMIONEWWRITE pfnWrite, PFNIOMMMIONEWREAD pfnRead, PFNIOMMMIONEWFILL pfnFill,
2563	void pvUser, const char pszDesc, PIOMMMIOHANDLE phRegion));
2564
2565	/**
2566	* Maps a memory mapped I/O (MMIO) region (into the guest physical address space).
2567	*
2568	* @returns VBox status.
2569	* @param pDevIns The device instance the region is associated with.
2570	* @param hRegion The MMIO region handle.
2571	* @param GCPhys Where to map the region.
2572	* @note An MMIO range may overlap with base memory if a lot of RAM is
2573	* configured for the VM, in which case we'll drop the base memory
2574	* pages. Presently we will make no attempt to preserve anything that
2575	* happens to be present in the base memory that is replaced, this is
2576	* technically incorrect but it's just not worth the effort to do
2577	* right, at least not at this point.
2578	* @sa PDMDevHlpMmioUnmap, PDMDevHlpMmioCreate, PDMDevHlpMmioCreateEx,
2579	* PDMDevHlpMmioSetUpContext
2580	*/
2581	DECLR3CALLBACKMEMBER(int, pfnMmioMap,(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion, RTGCPHYS GCPhys));
2582
2583	/**
2584	* Unmaps a memory mapped I/O (MMIO) region.
2585	*
2586	* @returns VBox status.
2587	* @param pDevIns The device instance the region is associated with.
2588	* @param hRegion The MMIO region handle.
2589	* @sa PDMDevHlpMmioMap, PDMDevHlpMmioCreate, PDMDevHlpMmioCreateEx,
2590	* PDMDevHlpMmioSetUpContext
2591	*/
2592	DECLR3CALLBACKMEMBER(int, pfnMmioUnmap,(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion));
2593
2594	/**
2595	* Reduces the length of a MMIO range.
2596	*
2597	* This is for implementations of PDMPCIDEV::pfnRegionLoadChangeHookR3 and will
2598	* only work during saved state restore. It will not call the PCI bus code, as
2599	* that is expected to restore the saved resource configuration.
2600	*
2601	* It just adjusts the mapping length of the region so that when pfnMmioMap is
2602	* called it will only map @a cbRegion bytes and not the value set during
2603	* registration.
2604	*
2605	* @return VBox status code.
2606	* @param pDevIns The device owning the range.
2607	* @param hRegion The MMIO region handle.
2608	* @param cbRegion The new size, must be smaller.
2609	*/
2610	DECLR3CALLBACKMEMBER(int, pfnMmioReduce,(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion, RTGCPHYS cbRegion));
2611
2612	/**
2613	* Gets the mapping address of the MMIO region @a hRegion.
2614	*
2615	* @returns Mapping address, NIL_RTGCPHYS if not mapped (or invalid parameters).
2616	* @param pDevIns The device instance to register the ports with.
2617	* @param hRegion The MMIO region handle.
2618	*/
2619	DECLR3CALLBACKMEMBER(RTGCPHYS, pfnMmioGetMappingAddress,(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion));
2620	/** @} */
2621
2622	/** @name MMIO2
2623	* @{ */
2624	/**
2625	* Creates a MMIO2 region.
2626	*
2627	* As mentioned elsewhere, MMIO2 is just RAM spelled differently. It's RAM
2628	* associated with a device. It is also non-shared memory with a permanent
2629	* ring-3 mapping and page backing (presently).
2630	*
2631	* @returns VBox status.
2632	* @param pDevIns The device instance.
2633	* @param pPciDev The PCI device the region is associated with, or
2634	* NULL if no PCI device association.
2635	* @param iPciRegion The region number. Use the PCI region number as
2636	* this must be known to the PCI bus device too. If
2637	* it's not associated with the PCI device, then
2638	* any number up to UINT8_MAX is fine.
2639	* @param cbRegion The size (in bytes) of the region.
2640	* @param fFlags PGMPHYS_MMIO2_FLAGS_XXX (see pgm.h).
2641	* @param pszDesc Pointer to description string. This must not be
2642	* freed.
2643	* @param ppvMapping Where to store the address of the ring-3 mapping
2644	* of the memory.
2645	* @param phRegion Where to return the MMIO2 region handle.
2646	*
2647	* @thread EMT(0)
2648	*/
2649	DECLR3CALLBACKMEMBER(int, pfnMmio2Create,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t iPciRegion, RTGCPHYS cbRegion,
2650	uint32_t fFlags, const char pszDesc, void *ppvMapping, PPGMMMIO2HANDLE phRegion));
2651
2652	/**
2653	* Destroys a MMIO2 region, unmapping it and freeing the memory.
2654	*
2655	* Any physical access handlers registered for the region must be deregistered
2656	* before calling this function.
2657	*
2658	* @returns VBox status code.
2659	* @param pDevIns The device instance.
2660	* @param hRegion The MMIO2 region handle.
2661	* @thread EMT.
2662	*/
2663	DECLR3CALLBACKMEMBER(int, pfnMmio2Destroy,(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion));
2664
2665	/**
2666	* Maps a MMIO2 region (into the guest physical address space).
2667	*
2668	* @returns VBox status.
2669	* @param pDevIns The device instance the region is associated with.
2670	* @param hRegion The MMIO2 region handle.
2671	* @param GCPhys Where to map the region.
2672	* @note A MMIO2 region overlap with base memory if a lot of RAM is
2673	* configured for the VM, in which case we'll drop the base memory
2674	* pages. Presently we will make no attempt to preserve anything that
2675	* happens to be present in the base memory that is replaced, this is
2676	* technically incorrect but it's just not worth the effort to do
2677	* right, at least not at this point.
2678	* @sa PDMDevHlpMmio2Unmap, PDMDevHlpMmio2Create, PDMDevHlpMmio2SetUpContext
2679	*/
2680	DECLR3CALLBACKMEMBER(int, pfnMmio2Map,(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion, RTGCPHYS GCPhys));
2681
2682	/**
2683	* Unmaps a MMIO2 region.
2684	*
2685	* @returns VBox status.
2686	* @param pDevIns The device instance the region is associated with.
2687	* @param hRegion The MMIO2 region handle.
2688	* @sa PDMDevHlpMmio2Map, PDMDevHlpMmio2Create, PDMDevHlpMmio2SetUpContext
2689	*/
2690	DECLR3CALLBACKMEMBER(int, pfnMmio2Unmap,(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion));
2691
2692	/**
2693	* Reduces the length of a MMIO range.
2694	*
2695	* This is for implementations of PDMPCIDEV::pfnRegionLoadChangeHookR3 and will
2696	* only work during saved state restore. It will not call the PCI bus code, as
2697	* that is expected to restore the saved resource configuration.
2698	*
2699	* It just adjusts the mapping length of the region so that when pfnMmioMap is
2700	* called it will only map @a cbRegion bytes and not the value set during
2701	* registration.
2702	*
2703	* @return VBox status code.
2704	* @param pDevIns The device owning the range.
2705	* @param hRegion The MMIO2 region handle.
2706	* @param cbRegion The new size, must be smaller.
2707	*/
2708	DECLR3CALLBACKMEMBER(int, pfnMmio2Reduce,(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion, RTGCPHYS cbRegion));
2709
2710	/**
2711	* Gets the mapping address of the MMIO region @a hRegion.
2712	*
2713	* @returns Mapping address, NIL_RTGCPHYS if not mapped (or invalid parameters).
2714	* @param pDevIns The device instance to register the ports with.
2715	* @param hRegion The MMIO2 region handle.
2716	*/
2717	DECLR3CALLBACKMEMBER(RTGCPHYS, pfnMmio2GetMappingAddress,(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion));
2718
2719	/**
2720	* Queries and resets the dirty bitmap for an MMIO2 region.
2721	*
2722	* The MMIO2 region must have been created with the
2723	* PGMPHYS_MMIO2_FLAGS_TRACK_DIRTY_PAGES flag for this to work.
2724	*
2725	* @returns VBox status code.
2726	* @param pDevIns The device instance.
2727	* @param hRegion The MMIO2 region handle.
2728	* @param pvBitmap Where to return the bitmap. Must be 8-byte aligned.
2729	* Can be NULL if only resetting the tracking is desired.
2730	* @param cbBitmap The bitmap size. One bit per page in the region,
2731	* rounded up to 8-bytes. If pvBitmap is NULL this must
2732	* also be zero.
2733	*/
2734	DECLR3CALLBACKMEMBER(int, pfnMmio2QueryAndResetDirtyBitmap, (PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion,
2735	void *pvBitmap, size_t cbBitmap));
2736
2737	/**
2738	* Controls the dirty page tracking for an MMIO2 region.
2739	*
2740	* The MMIO2 region must have been created with the
2741	* PGMPHYS_MMIO2_FLAGS_TRACK_DIRTY_PAGES flag for this to work.
2742	*
2743	* @returns VBox status code.
2744	* @param pDevIns The device instance.
2745	* @param hRegion The MMIO2 region handle.
2746	* @param fEnabled When set to @c true the dirty page tracking will be
2747	* enabled if currently disabled (bitmap is reset). When
2748	* set to @c false the dirty page tracking will be
2749	* disabled.
2750	*/
2751	DECLR3CALLBACKMEMBER(int, pfnMmio2ControlDirtyPageTracking, (PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion, bool fEnabled));
2752
2753	/**
2754	* Changes the number of an MMIO2 or pre-registered MMIO region.
2755	*
2756	* This should only be used to deal with saved state problems, so there is no
2757	* convenience inline wrapper for this method.
2758	*
2759	* @returns VBox status code.
2760	* @param pDevIns The device instance.
2761	* @param hRegion The MMIO2 region handle.
2762	* @param iNewRegion The new region index.
2763	*
2764	* @sa @bugref{9359}
2765	*/
2766	DECLR3CALLBACKMEMBER(int, pfnMmio2ChangeRegionNo,(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion, uint32_t iNewRegion));
2767
2768	/**
2769	* Mapping an MMIO2 page in place of an MMIO page for direct access.
2770	*
2771	* This is a special optimization used by the VGA device. Call
2772	* PDMDevHlpMmioResetRegion() to undo the mapping.
2773	*
2774	* @returns VBox status code. This API may return VINF_SUCCESS even if no
2775	* remapping is made.
2776	* @retval VERR_SEM_BUSY in ring-0 if we cannot get the IOM lock.
2777	*
2778	* @param pDevIns The device instance @a hRegion and @a hMmio2 are
2779	* associated with.
2780	* @param hRegion The handle to the MMIO region.
2781	* @param offRegion The offset into @a hRegion of the page to be
2782	* remapped.
2783	* @param hMmio2 The MMIO2 handle.
2784	* @param offMmio2 Offset into @a hMmio2 of the page to be use for the
2785	* mapping.
2786	* @param fPageFlags Page flags to set. Must be (X86_PTE_RW \| X86_PTE_P)
2787	* for the time being.
2788	*/
2789	DECLR3CALLBACKMEMBER(int, pfnMmioMapMmio2Page,(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion, RTGCPHYS offRegion,
2790	uint64_t hMmio2, RTGCPHYS offMmio2, uint64_t fPageFlags));
2791
2792	/**
2793	* Reset a previously modified MMIO region; restore the access flags.
2794	*
2795	* This undoes the effects of PDMDevHlpMmioMapMmio2Page() and is currently only
2796	* intended for some ancient VGA hack. However, it would be great to extend it
2797	* beyond VT-x and/or nested-paging.
2798	*
2799	* @returns VBox status code.
2800	*
2801	* @param pDevIns The device instance @a hRegion is associated with.
2802	* @param hRegion The handle to the MMIO region.
2803	*/
2804	DECLR3CALLBACKMEMBER(int, pfnMmioResetRegion, (PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion));
2805	/** @} */
2806
2807	/**
2808	* Register a ROM (BIOS) region.
2809	*
2810	* It goes without saying that this is read-only memory. The memory region must be
2811	* in unassigned memory. I.e. from the top of the address space or on the PC in
2812	* the 0xa0000-0xfffff range.
2813	*
2814	* @returns VBox status.
2815	* @param pDevIns The device instance owning the ROM region.
2816	* @param GCPhysStart First physical address in the range.
2817	* Must be page aligned!
2818	* @param cbRange The size of the range (in bytes).
2819	* Must be page aligned!
2820	* @param pvBinary Pointer to the binary data backing the ROM image.
2821	* @param cbBinary The size of the binary pointer. This must
2822	* be equal or smaller than @a cbRange.
2823	* @param fFlags PGMPHYS_ROM_FLAGS_XXX (see pgm.h).
2824	* @param pszDesc Pointer to description string. This must not be freed.
2825	*
2826	* @remark There is no way to remove the rom, automatically on device cleanup or
2827	* manually from the device yet. At present I doubt we need such features...
2828	*/
2829	DECLR3CALLBACKMEMBER(int, pfnROMRegister,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, uint32_t cbRange,
2830	const void pvBinary, uint32_t cbBinary, uint32_t fFlags, const char pszDesc));
2831
2832	/**
2833	* Changes the protection of shadowed ROM mapping.
2834	*
2835	* This is intented for use by the system BIOS, chipset or device in question to
2836	* change the protection of shadowed ROM code after init and on reset.
2837	*
2838	* @param pDevIns The device instance.
2839	* @param GCPhysStart Where the mapping starts.
2840	* @param cbRange The size of the mapping.
2841	* @param enmProt The new protection type.
2842	*/
2843	DECLR3CALLBACKMEMBER(int, pfnROMProtectShadow,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, uint32_t cbRange, PGMROMPROT enmProt));
2844
2845	/**
2846	* Register a save state data unit.
2847	*
2848	* @returns VBox status.
2849	* @param pDevIns The device instance.
2850	* @param uVersion Data layout version number.
2851	* @param cbGuess The approximate amount of data in the unit.
2852	* Only for progress indicators.
2853	* @param pszBefore Name of data unit which we should be put in
2854	* front of. Optional (NULL).
2855	*
2856	* @param pfnLivePrep Prepare live save callback, optional.
2857	* @param pfnLiveExec Execute live save callback, optional.
2858	* @param pfnLiveVote Vote live save callback, optional.
2859	*
2860	* @param pfnSavePrep Prepare save callback, optional.
2861	* @param pfnSaveExec Execute save callback, optional.
2862	* @param pfnSaveDone Done save callback, optional.
2863	*
2864	* @param pfnLoadPrep Prepare load callback, optional.
2865	* @param pfnLoadExec Execute load callback, optional.
2866	* @param pfnLoadDone Done load callback, optional.
2867	* @remarks Caller enters the device critical section prior to invoking the
2868	* registered callback methods.
2869	*/
2870	DECLR3CALLBACKMEMBER(int, pfnSSMRegister,(PPDMDEVINS pDevIns, uint32_t uVersion, size_t cbGuess, const char *pszBefore,
2871	PFNSSMDEVLIVEPREP pfnLivePrep, PFNSSMDEVLIVEEXEC pfnLiveExec, PFNSSMDEVLIVEVOTE pfnLiveVote,
2872	PFNSSMDEVSAVEPREP pfnSavePrep, PFNSSMDEVSAVEEXEC pfnSaveExec, PFNSSMDEVSAVEDONE pfnSaveDone,
2873	PFNSSMDEVLOADPREP pfnLoadPrep, PFNSSMDEVLOADEXEC pfnLoadExec, PFNSSMDEVLOADDONE pfnLoadDone));
2874
2875	/**
2876	* Register a save state data unit for backward compatibility.
2877	*
2878	* This is for migrating from an old device name to a new one or for merging
2879	* devices. It will only help loading old saved states.
2880	*
2881	* @returns VBox status.
2882	* @param pDevIns The device instance.
2883	* @param pszOldName The old unit name.
2884	* @param pfnLoadPrep Prepare load callback, optional.
2885	* @param pfnLoadExec Execute load callback, optional.
2886	* @param pfnLoadDone Done load callback, optional.
2887	* @remarks Caller enters the device critical section prior to invoking the
2888	* registered callback methods.
2889	*/
2890	DECLR3CALLBACKMEMBER(int, pfnSSMRegisterLegacy,(PPDMDEVINS pDevIns, const char *pszOldName, PFNSSMDEVLOADPREP pfnLoadPrep,
2891	PFNSSMDEVLOADEXEC pfnLoadExec, PFNSSMDEVLOADDONE pfnLoadDone));
2892
2893	/** @name Exported SSM Functions
2894	* @{ */
2895	DECLR3CALLBACKMEMBER(int, pfnSSMPutStruct,(PSSMHANDLE pSSM, const void *pvStruct, PCSSMFIELD paFields));
2896	DECLR3CALLBACKMEMBER(int, pfnSSMPutStructEx,(PSSMHANDLE pSSM, const void pvStruct, size_t cbStruct, uint32_t fFlags, PCSSMFIELD paFields, void pvUser));
2897	DECLR3CALLBACKMEMBER(int, pfnSSMPutBool,(PSSMHANDLE pSSM, bool fBool));
2898	DECLR3CALLBACKMEMBER(int, pfnSSMPutU8,(PSSMHANDLE pSSM, uint8_t u8));
2899	DECLR3CALLBACKMEMBER(int, pfnSSMPutS8,(PSSMHANDLE pSSM, int8_t i8));
2900	DECLR3CALLBACKMEMBER(int, pfnSSMPutU16,(PSSMHANDLE pSSM, uint16_t u16));
2901	DECLR3CALLBACKMEMBER(int, pfnSSMPutS16,(PSSMHANDLE pSSM, int16_t i16));
2902	DECLR3CALLBACKMEMBER(int, pfnSSMPutU32,(PSSMHANDLE pSSM, uint32_t u32));
2903	DECLR3CALLBACKMEMBER(int, pfnSSMPutS32,(PSSMHANDLE pSSM, int32_t i32));
2904	DECLR3CALLBACKMEMBER(int, pfnSSMPutU64,(PSSMHANDLE pSSM, uint64_t u64));
2905	DECLR3CALLBACKMEMBER(int, pfnSSMPutS64,(PSSMHANDLE pSSM, int64_t i64));
2906	DECLR3CALLBACKMEMBER(int, pfnSSMPutU128,(PSSMHANDLE pSSM, uint128_t u128));
2907	DECLR3CALLBACKMEMBER(int, pfnSSMPutS128,(PSSMHANDLE pSSM, int128_t i128));
2908	DECLR3CALLBACKMEMBER(int, pfnSSMPutUInt,(PSSMHANDLE pSSM, RTUINT u));
2909	DECLR3CALLBACKMEMBER(int, pfnSSMPutSInt,(PSSMHANDLE pSSM, RTINT i));
2910	DECLR3CALLBACKMEMBER(int, pfnSSMPutGCUInt,(PSSMHANDLE pSSM, RTGCUINT u));
2911	DECLR3CALLBACKMEMBER(int, pfnSSMPutGCUIntReg,(PSSMHANDLE pSSM, RTGCUINTREG u));
2912	DECLR3CALLBACKMEMBER(int, pfnSSMPutGCPhys32,(PSSMHANDLE pSSM, RTGCPHYS32 GCPhys));
2913	DECLR3CALLBACKMEMBER(int, pfnSSMPutGCPhys64,(PSSMHANDLE pSSM, RTGCPHYS64 GCPhys));
2914	DECLR3CALLBACKMEMBER(int, pfnSSMPutGCPhys,(PSSMHANDLE pSSM, RTGCPHYS GCPhys));
2915	DECLR3CALLBACKMEMBER(int, pfnSSMPutGCPtr,(PSSMHANDLE pSSM, RTGCPTR GCPtr));
2916	DECLR3CALLBACKMEMBER(int, pfnSSMPutGCUIntPtr,(PSSMHANDLE pSSM, RTGCUINTPTR GCPtr));
2917	DECLR3CALLBACKMEMBER(int, pfnSSMPutRCPtr,(PSSMHANDLE pSSM, RTRCPTR RCPtr));
2918	DECLR3CALLBACKMEMBER(int, pfnSSMPutIOPort,(PSSMHANDLE pSSM, RTIOPORT IOPort));
2919	DECLR3CALLBACKMEMBER(int, pfnSSMPutSel,(PSSMHANDLE pSSM, RTSEL Sel));
2920	DECLR3CALLBACKMEMBER(int, pfnSSMPutMem,(PSSMHANDLE pSSM, const void *pv, size_t cb));
2921	DECLR3CALLBACKMEMBER(int, pfnSSMPutStrZ,(PSSMHANDLE pSSM, const char *psz));
2922	DECLR3CALLBACKMEMBER(int, pfnSSMGetStruct,(PSSMHANDLE pSSM, void *pvStruct, PCSSMFIELD paFields));
2923	DECLR3CALLBACKMEMBER(int, pfnSSMGetStructEx,(PSSMHANDLE pSSM, void pvStruct, size_t cbStruct, uint32_t fFlags, PCSSMFIELD paFields, void pvUser));
2924	DECLR3CALLBACKMEMBER(int, pfnSSMGetBool,(PSSMHANDLE pSSM, bool *pfBool));
2925	DECLR3CALLBACKMEMBER(int, pfnSSMGetBoolV,(PSSMHANDLE pSSM, bool volatile *pfBool));
2926	DECLR3CALLBACKMEMBER(int, pfnSSMGetU8,(PSSMHANDLE pSSM, uint8_t *pu8));
2927	DECLR3CALLBACKMEMBER(int, pfnSSMGetU8V,(PSSMHANDLE pSSM, uint8_t volatile *pu8));
2928	DECLR3CALLBACKMEMBER(int, pfnSSMGetS8,(PSSMHANDLE pSSM, int8_t *pi8));
2929	DECLR3CALLBACKMEMBER(int, pfnSSMGetS8V,(PSSMHANDLE pSSM, int8_t volatile *pi8));
2930	DECLR3CALLBACKMEMBER(int, pfnSSMGetU16,(PSSMHANDLE pSSM, uint16_t *pu16));
2931	DECLR3CALLBACKMEMBER(int, pfnSSMGetU16V,(PSSMHANDLE pSSM, uint16_t volatile *pu16));
2932	DECLR3CALLBACKMEMBER(int, pfnSSMGetS16,(PSSMHANDLE pSSM, int16_t *pi16));
2933	DECLR3CALLBACKMEMBER(int, pfnSSMGetS16V,(PSSMHANDLE pSSM, int16_t volatile *pi16));
2934	DECLR3CALLBACKMEMBER(int, pfnSSMGetU32,(PSSMHANDLE pSSM, uint32_t *pu32));
2935	DECLR3CALLBACKMEMBER(int, pfnSSMGetU32V,(PSSMHANDLE pSSM, uint32_t volatile *pu32));
2936	DECLR3CALLBACKMEMBER(int, pfnSSMGetS32,(PSSMHANDLE pSSM, int32_t *pi32));
2937	DECLR3CALLBACKMEMBER(int, pfnSSMGetS32V,(PSSMHANDLE pSSM, int32_t volatile *pi32));
2938	DECLR3CALLBACKMEMBER(int, pfnSSMGetU64,(PSSMHANDLE pSSM, uint64_t *pu64));
2939	DECLR3CALLBACKMEMBER(int, pfnSSMGetU64V,(PSSMHANDLE pSSM, uint64_t volatile *pu64));
2940	DECLR3CALLBACKMEMBER(int, pfnSSMGetS64,(PSSMHANDLE pSSM, int64_t *pi64));
2941	DECLR3CALLBACKMEMBER(int, pfnSSMGetS64V,(PSSMHANDLE pSSM, int64_t volatile *pi64));
2942	DECLR3CALLBACKMEMBER(int, pfnSSMGetU128,(PSSMHANDLE pSSM, uint128_t *pu128));
2943	DECLR3CALLBACKMEMBER(int, pfnSSMGetU128V,(PSSMHANDLE pSSM, uint128_t volatile *pu128));
2944	DECLR3CALLBACKMEMBER(int, pfnSSMGetS128,(PSSMHANDLE pSSM, int128_t *pi128));
2945	DECLR3CALLBACKMEMBER(int, pfnSSMGetS128V,(PSSMHANDLE pSSM, int128_t volatile *pi128));
2946	DECLR3CALLBACKMEMBER(int, pfnSSMGetGCPhys32,(PSSMHANDLE pSSM, PRTGCPHYS32 pGCPhys));
2947	DECLR3CALLBACKMEMBER(int, pfnSSMGetGCPhys32V,(PSSMHANDLE pSSM, RTGCPHYS32 volatile *pGCPhys));
2948	DECLR3CALLBACKMEMBER(int, pfnSSMGetGCPhys64,(PSSMHANDLE pSSM, PRTGCPHYS64 pGCPhys));
2949	DECLR3CALLBACKMEMBER(int, pfnSSMGetGCPhys64V,(PSSMHANDLE pSSM, RTGCPHYS64 volatile *pGCPhys));
2950	DECLR3CALLBACKMEMBER(int, pfnSSMGetGCPhys,(PSSMHANDLE pSSM, PRTGCPHYS pGCPhys));
2951	DECLR3CALLBACKMEMBER(int, pfnSSMGetGCPhysV,(PSSMHANDLE pSSM, RTGCPHYS volatile *pGCPhys));
2952	DECLR3CALLBACKMEMBER(int, pfnSSMGetUInt,(PSSMHANDLE pSSM, PRTUINT pu));
2953	DECLR3CALLBACKMEMBER(int, pfnSSMGetSInt,(PSSMHANDLE pSSM, PRTINT pi));
2954	DECLR3CALLBACKMEMBER(int, pfnSSMGetGCUInt,(PSSMHANDLE pSSM, PRTGCUINT pu));
2955	DECLR3CALLBACKMEMBER(int, pfnSSMGetGCUIntReg,(PSSMHANDLE pSSM, PRTGCUINTREG pu));
2956	DECLR3CALLBACKMEMBER(int, pfnSSMGetGCPtr,(PSSMHANDLE pSSM, PRTGCPTR pGCPtr));
2957	DECLR3CALLBACKMEMBER(int, pfnSSMGetGCUIntPtr,(PSSMHANDLE pSSM, PRTGCUINTPTR pGCPtr));
2958	DECLR3CALLBACKMEMBER(int, pfnSSMGetRCPtr,(PSSMHANDLE pSSM, PRTRCPTR pRCPtr));
2959	DECLR3CALLBACKMEMBER(int, pfnSSMGetIOPort,(PSSMHANDLE pSSM, PRTIOPORT pIOPort));
2960	DECLR3CALLBACKMEMBER(int, pfnSSMGetSel,(PSSMHANDLE pSSM, PRTSEL pSel));
2961	DECLR3CALLBACKMEMBER(int, pfnSSMGetMem,(PSSMHANDLE pSSM, void *pv, size_t cb));
2962	DECLR3CALLBACKMEMBER(int, pfnSSMGetStrZ,(PSSMHANDLE pSSM, char *psz, size_t cbMax));
2963	DECLR3CALLBACKMEMBER(int, pfnSSMGetStrZEx,(PSSMHANDLE pSSM, char psz, size_t cbMax, size_t pcbStr));
2964	DECLR3CALLBACKMEMBER(int, pfnSSMSkip,(PSSMHANDLE pSSM, size_t cb));
2965	DECLR3CALLBACKMEMBER(int, pfnSSMSkipToEndOfUnit,(PSSMHANDLE pSSM));
2966	DECLR3CALLBACKMEMBER(int, pfnSSMSetLoadError,(PSSMHANDLE pSSM, int rc, RT_SRC_POS_DECL, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(6, 7));
2967	DECLR3CALLBACKMEMBER(int, pfnSSMSetLoadErrorV,(PSSMHANDLE pSSM, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(6, 0));
2968	DECLR3CALLBACKMEMBER(int, pfnSSMSetCfgError,(PSSMHANDLE pSSM, RT_SRC_POS_DECL, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(5, 6));
2969	DECLR3CALLBACKMEMBER(int, pfnSSMSetCfgErrorV,(PSSMHANDLE pSSM, RT_SRC_POS_DECL, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(5, 0));
2970	DECLR3CALLBACKMEMBER(int, pfnSSMHandleGetStatus,(PSSMHANDLE pSSM));
2971	DECLR3CALLBACKMEMBER(SSMAFTER, pfnSSMHandleGetAfter,(PSSMHANDLE pSSM));
2972	DECLR3CALLBACKMEMBER(bool, pfnSSMHandleIsLiveSave,(PSSMHANDLE pSSM));
2973	DECLR3CALLBACKMEMBER(uint32_t, pfnSSMHandleMaxDowntime,(PSSMHANDLE pSSM));
2974	DECLR3CALLBACKMEMBER(uint32_t, pfnSSMHandleHostBits,(PSSMHANDLE pSSM));
2975	DECLR3CALLBACKMEMBER(uint32_t, pfnSSMHandleRevision,(PSSMHANDLE pSSM));
2976	DECLR3CALLBACKMEMBER(uint32_t, pfnSSMHandleVersion,(PSSMHANDLE pSSM));
2977	DECLR3CALLBACKMEMBER(const char *, pfnSSMHandleHostOSAndArch,(PSSMHANDLE pSSM));
2978	/** @} */
2979
2980	/**
2981	* Creates a timer w/ a cross context handle.
2982	*
2983	* @returns VBox status.
2984	* @param pDevIns The device instance.
2985	* @param enmClock The clock to use on this timer.
2986	* @param pfnCallback Callback function.
2987	* @param pvUser User argument for the callback.
2988	* @param fFlags Flags, see TMTIMER_FLAGS_*.
2989	* @param pszDesc Pointer to description string which must stay around
2990	* until the timer is fully destroyed (i.e. a bit after TMTimerDestroy()).
2991	* @param phTimer Where to store the timer handle on success.
2992	* @remarks Caller enters the device critical section prior to invoking the
2993	* callback.
2994	*/
2995	DECLR3CALLBACKMEMBER(int, pfnTimerCreate,(PPDMDEVINS pDevIns, TMCLOCK enmClock, PFNTMTIMERDEV pfnCallback,
2996	void pvUser, uint32_t fFlags, const char pszDesc, PTMTIMERHANDLE phTimer));
2997
2998	/** @name Timer handle method wrappers
2999	* @{ */
3000	DECLR3CALLBACKMEMBER(uint64_t, pfnTimerFromMicro,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMicroSecs));
3001	DECLR3CALLBACKMEMBER(uint64_t, pfnTimerFromMilli,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMilliSecs));
3002	DECLR3CALLBACKMEMBER(uint64_t, pfnTimerFromNano,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cNanoSecs));
3003	DECLR3CALLBACKMEMBER(uint64_t, pfnTimerGet,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
3004	DECLR3CALLBACKMEMBER(uint64_t, pfnTimerGetFreq,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
3005	DECLR3CALLBACKMEMBER(uint64_t, pfnTimerGetNano,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
3006	DECLR3CALLBACKMEMBER(bool, pfnTimerIsActive,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
3007	DECLR3CALLBACKMEMBER(bool, pfnTimerIsLockOwner,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
3008	DECLR3CALLBACKMEMBER(VBOXSTRICTRC, pfnTimerLockClock,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, int rcBusy));
3009	/** Takes the clock lock then enters the specified critical section. */
3010	DECLR3CALLBACKMEMBER(VBOXSTRICTRC, pfnTimerLockClock2,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, PPDMCRITSECT pCritSect, int rcBusy));
3011	DECLR3CALLBACKMEMBER(int, pfnTimerSet,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t uExpire));
3012	DECLR3CALLBACKMEMBER(int, pfnTimerSetFrequencyHint,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint32_t uHz));
3013	DECLR3CALLBACKMEMBER(int, pfnTimerSetMicro,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMicrosToNext));
3014	DECLR3CALLBACKMEMBER(int, pfnTimerSetMillies,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMilliesToNext));
3015	DECLR3CALLBACKMEMBER(int, pfnTimerSetNano,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cNanosToNext));
3016	DECLR3CALLBACKMEMBER(int, pfnTimerSetRelative,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cTicksToNext, uint64_t *pu64Now));
3017	DECLR3CALLBACKMEMBER(int, pfnTimerStop,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
3018	DECLR3CALLBACKMEMBER(void, pfnTimerUnlockClock,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
3019	DECLR3CALLBACKMEMBER(void, pfnTimerUnlockClock2,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, PPDMCRITSECT pCritSect));
3020	DECLR3CALLBACKMEMBER(int, pfnTimerSetCritSect,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, PPDMCRITSECT pCritSect));
3021	DECLR3CALLBACKMEMBER(int, pfnTimerSave,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, PSSMHANDLE pSSM));
3022	DECLR3CALLBACKMEMBER(int, pfnTimerLoad,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, PSSMHANDLE pSSM));
3023	DECLR3CALLBACKMEMBER(int, pfnTimerDestroy,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
3024	/** @sa TMR3TimerSkip */
3025	DECLR3CALLBACKMEMBER(int, pfnTimerSkipLoad,(PSSMHANDLE pSSM, bool *pfActive));
3026	/** @} */
3027
3028	/**
3029	* Get the real world UTC time adjusted for VM lag, user offset and warpdrive.
3030	*
3031	* @returns pTime.
3032	* @param pDevIns The device instance.
3033	* @param pTime Where to store the time.
3034	*/
3035	DECLR3CALLBACKMEMBER(PRTTIMESPEC, pfnTMUtcNow,(PPDMDEVINS pDevIns, PRTTIMESPEC pTime));
3036
3037	/** @name Exported CFGM Functions.
3038	* @{ */
3039	DECLR3CALLBACKMEMBER(bool, pfnCFGMExists,( PCFGMNODE pNode, const char *pszName));
3040	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryType,( PCFGMNODE pNode, const char *pszName, PCFGMVALUETYPE penmType));
3041	DECLR3CALLBACKMEMBER(int, pfnCFGMQuerySize,( PCFGMNODE pNode, const char pszName, size_t pcb));
3042	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryInteger,( PCFGMNODE pNode, const char pszName, uint64_t pu64));
3043	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryIntegerDef,( PCFGMNODE pNode, const char pszName, uint64_t pu64, uint64_t u64Def));
3044	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryString,( PCFGMNODE pNode, const char pszName, char pszString, size_t cchString));
3045	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryStringDef,( PCFGMNODE pNode, const char pszName, char pszString, size_t cchString, const char *pszDef));
3046	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryPassword,( PCFGMNODE pNode, const char pszName, char pszString, size_t cchString));
3047	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryPasswordDef,( PCFGMNODE pNode, const char pszName, char pszString, size_t cchString, const char *pszDef));
3048	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryBytes,( PCFGMNODE pNode, const char pszName, void pvData, size_t cbData));
3049	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryU64,( PCFGMNODE pNode, const char pszName, uint64_t pu64));
3050	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryU64Def,( PCFGMNODE pNode, const char pszName, uint64_t pu64, uint64_t u64Def));
3051	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryS64,( PCFGMNODE pNode, const char pszName, int64_t pi64));
3052	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryS64Def,( PCFGMNODE pNode, const char pszName, int64_t pi64, int64_t i64Def));
3053	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryU32,( PCFGMNODE pNode, const char pszName, uint32_t pu32));
3054	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryU32Def,( PCFGMNODE pNode, const char pszName, uint32_t pu32, uint32_t u32Def));
3055	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryS32,( PCFGMNODE pNode, const char pszName, int32_t pi32));
3056	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryS32Def,( PCFGMNODE pNode, const char pszName, int32_t pi32, int32_t i32Def));
3057	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryU16,( PCFGMNODE pNode, const char pszName, uint16_t pu16));
3058	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryU16Def,( PCFGMNODE pNode, const char pszName, uint16_t pu16, uint16_t u16Def));
3059	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryS16,( PCFGMNODE pNode, const char pszName, int16_t pi16));
3060	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryS16Def,( PCFGMNODE pNode, const char pszName, int16_t pi16, int16_t i16Def));
3061	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryU8,( PCFGMNODE pNode, const char pszName, uint8_t pu8));
3062	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryU8Def,( PCFGMNODE pNode, const char pszName, uint8_t pu8, uint8_t u8Def));
3063	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryS8,( PCFGMNODE pNode, const char pszName, int8_t pi8));
3064	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryS8Def,( PCFGMNODE pNode, const char pszName, int8_t pi8, int8_t i8Def));
3065	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryBool,( PCFGMNODE pNode, const char pszName, bool pf));
3066	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryBoolDef,( PCFGMNODE pNode, const char pszName, bool pf, bool fDef));
3067	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryPort,( PCFGMNODE pNode, const char *pszName, PRTIOPORT pPort));
3068	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryPortDef,( PCFGMNODE pNode, const char *pszName, PRTIOPORT pPort, RTIOPORT PortDef));
3069	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryUInt,( PCFGMNODE pNode, const char pszName, unsigned int pu));
3070	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryUIntDef,( PCFGMNODE pNode, const char pszName, unsigned int pu, unsigned int uDef));
3071	DECLR3CALLBACKMEMBER(int, pfnCFGMQuerySInt,( PCFGMNODE pNode, const char pszName, signed int pi));
3072	DECLR3CALLBACKMEMBER(int, pfnCFGMQuerySIntDef,( PCFGMNODE pNode, const char pszName, signed int pi, signed int iDef));
3073	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryGCPtr,( PCFGMNODE pNode, const char *pszName, PRTGCPTR pGCPtr));
3074	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryGCPtrDef,( PCFGMNODE pNode, const char *pszName, PRTGCPTR pGCPtr, RTGCPTR GCPtrDef));
3075	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryGCPtrU,( PCFGMNODE pNode, const char *pszName, PRTGCUINTPTR pGCPtr));
3076	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryGCPtrUDef,( PCFGMNODE pNode, const char *pszName, PRTGCUINTPTR pGCPtr, RTGCUINTPTR GCPtrDef));
3077	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryGCPtrS,( PCFGMNODE pNode, const char *pszName, PRTGCINTPTR pGCPtr));
3078	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryGCPtrSDef,( PCFGMNODE pNode, const char *pszName, PRTGCINTPTR pGCPtr, RTGCINTPTR GCPtrDef));
3079	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryStringAlloc,( PCFGMNODE pNode, const char pszName, char *ppszString));
3080	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryStringAllocDef,(PCFGMNODE pNode, const char pszName, char ppszString, const char pszDef));
3081	DECLR3CALLBACKMEMBER(PCFGMNODE, pfnCFGMGetParent,(PCFGMNODE pNode));
3082	DECLR3CALLBACKMEMBER(PCFGMNODE, pfnCFGMGetChild,(PCFGMNODE pNode, const char *pszPath));
3083	DECLR3CALLBACKMEMBER(PCFGMNODE, pfnCFGMGetChildF,(PCFGMNODE pNode, const char *pszPathFormat, ...) RT_IPRT_FORMAT_ATTR(2, 3));
3084	DECLR3CALLBACKMEMBER(PCFGMNODE, pfnCFGMGetChildFV,(PCFGMNODE pNode, const char *pszPathFormat, va_list Args) RT_IPRT_FORMAT_ATTR(3, 0));
3085	DECLR3CALLBACKMEMBER(PCFGMNODE, pfnCFGMGetFirstChild,(PCFGMNODE pNode));
3086	DECLR3CALLBACKMEMBER(PCFGMNODE, pfnCFGMGetNextChild,(PCFGMNODE pCur));
3087	DECLR3CALLBACKMEMBER(int, pfnCFGMGetName,(PCFGMNODE pCur, char *pszName, size_t cchName));
3088	DECLR3CALLBACKMEMBER(size_t, pfnCFGMGetNameLen,(PCFGMNODE pCur));
3089	DECLR3CALLBACKMEMBER(bool, pfnCFGMAreChildrenValid,(PCFGMNODE pNode, const char *pszzValid));
3090	DECLR3CALLBACKMEMBER(PCFGMLEAF, pfnCFGMGetFirstValue,(PCFGMNODE pCur));
3091	DECLR3CALLBACKMEMBER(PCFGMLEAF, pfnCFGMGetNextValue,(PCFGMLEAF pCur));
3092	DECLR3CALLBACKMEMBER(int, pfnCFGMGetValueName,(PCFGMLEAF pCur, char *pszName, size_t cchName));
3093	DECLR3CALLBACKMEMBER(size_t, pfnCFGMGetValueNameLen,(PCFGMLEAF pCur));
3094	DECLR3CALLBACKMEMBER(CFGMVALUETYPE, pfnCFGMGetValueType,(PCFGMLEAF pCur));
3095	DECLR3CALLBACKMEMBER(bool, pfnCFGMAreValuesValid,(PCFGMNODE pNode, const char *pszzValid));
3096	DECLR3CALLBACKMEMBER(int, pfnCFGMValidateConfig,(PCFGMNODE pNode, const char *pszNode,
3097	const char pszValidValues, const char pszValidNodes,
3098	const char *pszWho, uint32_t uInstance));
3099	/** @} */
3100
3101	/**
3102	* Read physical memory.
3103	*
3104	* @returns VINF_SUCCESS (for now).
3105	* @param pDevIns The device instance.
3106	* @param GCPhys Physical address start reading from.
3107	* @param pvBuf Where to put the read bits.
3108	* @param cbRead How many bytes to read.
3109	* @param fFlags Combination of PDM_DEVHLP_PHYS_RW_F_XXX.
3110	* @thread Any thread, but the call may involve the emulation thread.
3111	*/
3112	DECLR3CALLBACKMEMBER(int, pfnPhysRead,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead, uint32_t fFlags));
3113
3114	/**
3115	* Write to physical memory.
3116	*
3117	* @returns VINF_SUCCESS for now, and later maybe VERR_EM_MEMORY.
3118	* @param pDevIns The device instance.
3119	* @param GCPhys Physical address to write to.
3120	* @param pvBuf What to write.
3121	* @param cbWrite How many bytes to write.
3122	* @param fFlags Combination of PDM_DEVHLP_PHYS_RW_F_XXX.
3123	* @thread Any thread, but the call may involve the emulation thread.
3124	*/
3125	DECLR3CALLBACKMEMBER(int, pfnPhysWrite,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite, uint32_t fFlags));
3126
3127	/**
3128	* Requests the mapping of a guest page into ring-3.
3129	*
3130	* When you're done with the page, call pfnPhysReleasePageMappingLock() ASAP to
3131	* release it.
3132	*
3133	* This API will assume your intention is to write to the page, and will
3134	* therefore replace shared and zero pages. If you do not intend to modify the
3135	* page, use the pfnPhysGCPhys2CCPtrReadOnly() API.
3136	*
3137	* @returns VBox status code.
3138	* @retval VINF_SUCCESS on success.
3139	* @retval VERR_PGM_PHYS_PAGE_RESERVED it it's a valid page but has no physical
3140	* backing or if the page has any active access handlers. The caller
3141	* must fall back on using PGMR3PhysWriteExternal.
3142	* @retval VERR_PGM_INVALID_GC_PHYSICAL_ADDRESS if it's not a valid physical address.
3143	*
3144	* @param pDevIns The device instance.
3145	* @param GCPhys The guest physical address of the page that
3146	* should be mapped.
3147	* @param fFlags Flags reserved for future use, MBZ.
3148	* @param ppv Where to store the address corresponding to
3149	* GCPhys.
3150	* @param pLock Where to store the lock information that
3151	* pfnPhysReleasePageMappingLock needs.
3152	*
3153	* @remark Avoid calling this API from within critical sections (other than the
3154	* PGM one) because of the deadlock risk when we have to delegating the
3155	* task to an EMT.
3156	* @thread Any.
3157	*/
3158	DECLR3CALLBACKMEMBER(int, pfnPhysGCPhys2CCPtr,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, uint32_t fFlags, void **ppv,
3159	PPGMPAGEMAPLOCK pLock));
3160
3161	/**
3162	* Requests the mapping of a guest page into ring-3, external threads.
3163	*
3164	* When you're done with the page, call pfnPhysReleasePageMappingLock() ASAP to
3165	* release it.
3166	*
3167	* @returns VBox status code.
3168	* @retval VINF_SUCCESS on success.
3169	* @retval VERR_PGM_PHYS_PAGE_RESERVED it it's a valid page but has no physical
3170	* backing or if the page as an active ALL access handler. The caller
3171	* must fall back on using PGMPhysRead.
3172	* @retval VERR_PGM_INVALID_GC_PHYSICAL_ADDRESS if it's not a valid physical address.
3173	*
3174	* @param pDevIns The device instance.
3175	* @param GCPhys The guest physical address of the page that
3176	* should be mapped.
3177	* @param fFlags Flags reserved for future use, MBZ.
3178	* @param ppv Where to store the address corresponding to
3179	* GCPhys.
3180	* @param pLock Where to store the lock information that
3181	* pfnPhysReleasePageMappingLock needs.
3182	*
3183	* @remark Avoid calling this API from within critical sections.
3184	* @thread Any.
3185	*/
3186	DECLR3CALLBACKMEMBER(int, pfnPhysGCPhys2CCPtrReadOnly,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, uint32_t fFlags,
3187	void const **ppv, PPGMPAGEMAPLOCK pLock));
3188
3189	/**
3190	* Release the mapping of a guest page.
3191	*
3192	* This is the counter part of pfnPhysGCPhys2CCPtr and
3193	* pfnPhysGCPhys2CCPtrReadOnly.
3194	*
3195	* @param pDevIns The device instance.
3196	* @param pLock The lock structure initialized by the mapping
3197	* function.
3198	*/
3199	DECLR3CALLBACKMEMBER(void, pfnPhysReleasePageMappingLock,(PPDMDEVINS pDevIns, PPGMPAGEMAPLOCK pLock));
3200
3201	/**
3202	* Read guest physical memory by virtual address.
3203	*
3204	* @param pDevIns The device instance.
3205	* @param pvDst Where to put the read bits.
3206	* @param GCVirtSrc Guest virtual address to start reading from.
3207	* @param cb How many bytes to read.
3208	* @thread The emulation thread.
3209	*/
3210	DECLR3CALLBACKMEMBER(int, pfnPhysReadGCVirt,(PPDMDEVINS pDevIns, void *pvDst, RTGCPTR GCVirtSrc, size_t cb));
3211
3212	/**
3213	* Write to guest physical memory by virtual address.
3214	*
3215	* @param pDevIns The device instance.
3216	* @param GCVirtDst Guest virtual address to write to.
3217	* @param pvSrc What to write.
3218	* @param cb How many bytes to write.
3219	* @thread The emulation thread.
3220	*/
3221	DECLR3CALLBACKMEMBER(int, pfnPhysWriteGCVirt,(PPDMDEVINS pDevIns, RTGCPTR GCVirtDst, const void *pvSrc, size_t cb));
3222
3223	/**
3224	* Convert a guest virtual address to a guest physical address.
3225	*
3226	* @returns VBox status code.
3227	* @param pDevIns The device instance.
3228	* @param GCPtr Guest virtual address.
3229	* @param pGCPhys Where to store the GC physical address
3230	* corresponding to GCPtr.
3231	* @thread The emulation thread.
3232	* @remark Careful with page boundaries.
3233	*/
3234	DECLR3CALLBACKMEMBER(int, pfnPhysGCPtr2GCPhys, (PPDMDEVINS pDevIns, RTGCPTR GCPtr, PRTGCPHYS pGCPhys));
3235
3236	/**
3237	* Checks if a GC physical address is a normal page,
3238	* i.e. not ROM, MMIO or reserved.
3239	*
3240	* @returns true if normal.
3241	* @returns false if invalid, ROM, MMIO or reserved page.
3242	* @param pDevIns The device instance.
3243	* @param GCPhys The physical address to check.
3244	*/
3245	DECLR3CALLBACKMEMBER(bool, pfnPhysIsGCPhysNormal,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys));
3246
3247	/**
3248	* Inflate or deflate a memory balloon
3249	*
3250	* @returns VBox status code.
3251	* @param pDevIns The device instance.
3252	* @param fInflate Inflate or deflate memory balloon
3253	* @param cPages Number of pages to free
3254	* @param paPhysPage Array of guest physical addresses
3255	*/
3256	DECLR3CALLBACKMEMBER(int, pfnPhysChangeMemBalloon,(PPDMDEVINS pDevIns, bool fInflate, unsigned cPages, RTGCPHYS *paPhysPage));
3257
3258	/**
3259	* Allocate memory which is associated with current VM instance
3260	* and automatically freed on it's destruction.
3261	*
3262	* @returns Pointer to allocated memory. The memory is NOT zero-ed.
3263	* @param pDevIns The device instance.
3264	* @param cb Number of bytes to allocate.
3265	*/
3266	DECLR3CALLBACKMEMBER(void *, pfnMMHeapAlloc,(PPDMDEVINS pDevIns, size_t cb));
3267
3268	/**
3269	* Allocate memory which is associated with current VM instance
3270	* and automatically freed on it's destruction. The memory is ZEROed.
3271	*
3272	* @returns Pointer to allocated memory. The memory is NOT zero-ed.
3273	* @param pDevIns The device instance.
3274	* @param cb Number of bytes to allocate.
3275	*/
3276	DECLR3CALLBACKMEMBER(void *, pfnMMHeapAllocZ,(PPDMDEVINS pDevIns, size_t cb));
3277
3278	/**
3279	* Allocating string printf.
3280	*
3281	* @returns Pointer to the string.
3282	* @param pDevIns The device instance.
3283	* @param enmTag The statistics tag.
3284	* @param pszFormat The format string.
3285	* @param va Format arguments.
3286	*/
3287	DECLR3CALLBACKMEMBER(char , pfnMMHeapAPrintfV,(PPDMDEVINS pDevIns, MMTAG enmTag, const char pszFormat, va_list va));
3288
3289	/**
3290	* Free memory allocated with pfnMMHeapAlloc() and pfnMMHeapAllocZ().
3291	*
3292	* @param pDevIns The device instance.
3293	* @param pv Pointer to the memory to free.
3294	*/
3295	DECLR3CALLBACKMEMBER(void, pfnMMHeapFree,(PPDMDEVINS pDevIns, void *pv));
3296
3297	/**
3298	* Returns the physical RAM size of the VM.
3299	*
3300	* @returns RAM size in bytes.
3301	* @param pDevIns The device instance.
3302	*/
3303	DECLR3CALLBACKMEMBER(uint64_t, pfnMMPhysGetRamSize,(PPDMDEVINS pDevIns));
3304
3305	/**
3306	* Returns the physical RAM size of the VM below the 4GB boundary.
3307	*
3308	* @returns RAM size in bytes.
3309	* @param pDevIns The device instance.
3310	*/
3311	DECLR3CALLBACKMEMBER(uint32_t, pfnMMPhysGetRamSizeBelow4GB,(PPDMDEVINS pDevIns));
3312
3313	/**
3314	* Returns the physical RAM size of the VM above the 4GB boundary.
3315	*
3316	* @returns RAM size in bytes.
3317	* @param pDevIns The device instance.
3318	*/
3319	DECLR3CALLBACKMEMBER(uint64_t, pfnMMPhysGetRamSizeAbove4GB,(PPDMDEVINS pDevIns));
3320
3321	/**
3322	* Gets the VM state.
3323	*
3324	* @returns VM state.
3325	* @param pDevIns The device instance.
3326	* @thread Any thread (just keep in mind that it's volatile info).
3327	*/
3328	DECLR3CALLBACKMEMBER(VMSTATE, pfnVMState, (PPDMDEVINS pDevIns));
3329
3330	/**
3331	* Checks if the VM was teleported and hasn't been fully resumed yet.
3332	*
3333	* @returns true / false.
3334	* @param pDevIns The device instance.
3335	* @thread Any thread.
3336	*/
3337	DECLR3CALLBACKMEMBER(bool, pfnVMTeleportedAndNotFullyResumedYet,(PPDMDEVINS pDevIns));
3338
3339	/**
3340	* Set the VM error message
3341	*
3342	* @returns rc.
3343	* @param pDevIns The device instance.
3344	* @param rc VBox status code.
3345	* @param SRC_POS Use RT_SRC_POS.
3346	* @param pszFormat Error message format string.
3347	* @param va Error message arguments.
3348	*/
3349	DECLR3CALLBACKMEMBER(int, pfnVMSetErrorV,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL,
3350	const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(6, 0));
3351
3352	/**
3353	* Set the VM runtime error message
3354	*
3355	* @returns VBox status code.
3356	* @param pDevIns The device instance.
3357	* @param fFlags The action flags. See VMSETRTERR_FLAGS_*.
3358	* @param pszErrorId Error ID string.
3359	* @param pszFormat Error message format string.
3360	* @param va Error message arguments.
3361	*/
3362	DECLR3CALLBACKMEMBER(int, pfnVMSetRuntimeErrorV,(PPDMDEVINS pDevIns, uint32_t fFlags, const char *pszErrorId,
3363	const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(4, 0));
3364
3365	/**
3366	* Special interface for implementing a HLT-like port on a device.
3367	*
3368	* This can be called directly from device code, provide the device is trusted
3369	* to access the VMM directly. Since we may not have an accurate register set
3370	* and the caller certainly shouldn't (device code does not access CPU
3371	* registers), this function will return when interrupts are pending regardless
3372	* of the actual EFLAGS.IF state.
3373	*
3374	* @returns VBox error status (never informational statuses).
3375	* @param pDevIns The device instance.
3376	* @param idCpu The id of the calling EMT.
3377	*/
3378	DECLR3CALLBACKMEMBER(int, pfnVMWaitForDeviceReady,(PPDMDEVINS pDevIns, VMCPUID idCpu));
3379
3380	/**
3381	* Wakes up a CPU that has called PDMDEVHLPR3::pfnVMWaitForDeviceReady.
3382	*
3383	* @returns VBox error status (never informational statuses).
3384	* @param pDevIns The device instance.
3385	* @param idCpu The id of the calling EMT.
3386	*/
3387	DECLR3CALLBACKMEMBER(int, pfnVMNotifyCpuDeviceReady,(PPDMDEVINS pDevIns, VMCPUID idCpu));
3388
3389	/**
3390	* Convenience wrapper for VMR3ReqCallU.
3391	*
3392	* This assumes (1) you're calling a function that returns an VBox status code
3393	* and that you do not wish to wait for it to complete.
3394	*
3395	* @returns VBox status code returned by VMR3ReqCallVU.
3396	*
3397	* @param pDevIns The device instance.
3398	* @param idDstCpu The destination CPU(s). Either a specific CPU ID or
3399	* one of the following special values:
3400	* VMCPUID_ANY, VMCPUID_ANY_QUEUE, VMCPUID_ALL or VMCPUID_ALL_REVERSE.
3401	* @param pfnFunction Pointer to the function to call.
3402	* @param cArgs Number of arguments following in the ellipsis.
3403	* @param Args Argument vector.
3404	*
3405	* @remarks See remarks on VMR3ReqCallVU.
3406	*/
3407	DECLR3CALLBACKMEMBER(int, pfnVMReqCallNoWaitV,(PPDMDEVINS pDevIns, VMCPUID idDstCpu, PFNRT pfnFunction, unsigned cArgs,
3408	va_list Args)) RT_IPRT_CALLREQ_ATTR(3, 4, 0);
3409
3410	/**
3411	* Convenience wrapper for VMR3ReqCallU.
3412	*
3413	* This assumes (1) you're calling a function that returns void, (2) that you
3414	* wish to wait for ever for it to return, and (3) that it's priority request
3415	* that can be safely be handled during async suspend and power off.
3416	*
3417	* @returns VBox status code of VMR3ReqCallVU.
3418	*
3419	* @param pDevIns The device instance.
3420	* @param idDstCpu The destination CPU(s). Either a specific CPU ID or
3421	* one of the following special values:
3422	* VMCPUID_ANY, VMCPUID_ANY_QUEUE, VMCPUID_ALL or VMCPUID_ALL_REVERSE.
3423	* @param pfnFunction Pointer to the function to call.
3424	* @param cArgs Number of arguments following in the ellipsis.
3425	* @param Args Argument vector.
3426	*
3427	* @remarks See remarks on VMR3ReqCallVU.
3428	*/
3429	DECLR3CALLBACKMEMBER(int, pfnVMReqPriorityCallWaitV,(PPDMDEVINS pDevIns, VMCPUID idDstCpu, PFNRT pfnFunction, unsigned cArgs,
3430	va_list Args)) RT_IPRT_CALLREQ_ATTR(3, 4, 0);
3431
3432	/**
3433	* Stops the VM and enters the debugger to look at the guest state.
3434	*
3435	* Use the PDMDeviceDBGFStop() inline function with the RT_SRC_POS macro instead of
3436	* invoking this function directly.
3437	*
3438	* @returns VBox status code which must be passed up to the VMM.
3439	* @param pDevIns The device instance.
3440	* @param pszFile Filename of the assertion location.
3441	* @param iLine The linenumber of the assertion location.
3442	* @param pszFunction Function of the assertion location.
3443	* @param pszFormat Message. (optional)
3444	* @param args Message parameters.
3445	*/
3446	DECLR3CALLBACKMEMBER(int, pfnDBGFStopV,(PPDMDEVINS pDevIns, const char pszFile, unsigned iLine, const char pszFunction,
3447	const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(5, 0));
3448
3449	/**
3450	* Register a info handler with DBGF.
3451	*
3452	* @returns VBox status code.
3453	* @param pDevIns The device instance.
3454	* @param pszName The identifier of the info.
3455	* @param pszDesc The description of the info and any arguments
3456	* the handler may take.
3457	* @param pfnHandler The handler function to be called to display the
3458	* info.
3459	*/
3460	DECLR3CALLBACKMEMBER(int, pfnDBGFInfoRegister,(PPDMDEVINS pDevIns, const char pszName, const char pszDesc, PFNDBGFHANDLERDEV pfnHandler));
3461
3462	/**
3463	* Register a info handler with DBGF, argv style.
3464	*
3465	* @returns VBox status code.
3466	* @param pDevIns The device instance.
3467	* @param pszName The identifier of the info.
3468	* @param pszDesc The description of the info and any arguments
3469	* the handler may take.
3470	* @param pfnHandler The handler function to be called to display the
3471	* info.
3472	*/
3473	DECLR3CALLBACKMEMBER(int, pfnDBGFInfoRegisterArgv,(PPDMDEVINS pDevIns, const char pszName, const char pszDesc, PFNDBGFINFOARGVDEV pfnHandler));
3474
3475	/**
3476	* Registers a set of registers for a device.
3477	*
3478	* The @a pvUser argument of the getter and setter callbacks will be
3479	* @a pDevIns. The register names will be prefixed by the device name followed
3480	* immediately by the instance number.
3481	*
3482	* @returns VBox status code.
3483	* @param pDevIns The device instance.
3484	* @param paRegisters The register descriptors.
3485	*
3486	* @remarks The device critical section is NOT entered prior to working the
3487	* callbacks registered via this helper!
3488	*/
3489	DECLR3CALLBACKMEMBER(int, pfnDBGFRegRegister,(PPDMDEVINS pDevIns, PCDBGFREGDESC paRegisters));
3490
3491	/**
3492	* Gets the trace buffer handle.
3493	*
3494	* This is used by the macros found in VBox/vmm/dbgftrace.h and is not
3495	* really inteded for direct usage, thus no inline wrapper function.
3496	*
3497	* @returns Trace buffer handle or NIL_RTTRACEBUF.
3498	* @param pDevIns The device instance.
3499	*/
3500	DECLR3CALLBACKMEMBER(RTTRACEBUF, pfnDBGFTraceBuf,(PPDMDEVINS pDevIns));
3501
3502	/**
3503	* Report a bug check.
3504	*
3505	* @returns
3506	* @param pDevIns The device instance.
3507	* @param enmEvent The kind of BSOD event this is.
3508	* @param uBugCheck The bug check number.
3509	* @param uP1 The bug check parameter \#1.
3510	* @param uP2 The bug check parameter \#2.
3511	* @param uP3 The bug check parameter \#3.
3512	* @param uP4 The bug check parameter \#4.
3513	*
3514	* @thread EMT
3515	*/
3516	DECLR3CALLBACKMEMBER(VBOXSTRICTRC, pfnDBGFReportBugCheck,(PPDMDEVINS pDevIns, DBGFEVENTTYPE enmEvent, uint64_t uBugCheck,
3517	uint64_t uP1, uint64_t uP2, uint64_t uP3, uint64_t uP4));
3518
3519	/**
3520	* Write core dump of the guest.
3521	*
3522	* @returns VBox status code.
3523	* @param pDevIns The device instance.
3524	* @param pszFilename The name of the file to which the guest core
3525	* dump should be written.
3526	* @param fReplaceFile Whether to replace the file or not.
3527	*
3528	* @remarks The VM may need to be suspended before calling this function in
3529	* order to truly stop all device threads and drivers. This function
3530	* only synchronizes EMTs.
3531	*/
3532	DECLR3CALLBACKMEMBER(int, pfnDBGFCoreWrite,(PPDMDEVINS pDevIns, const char *pszFilename, bool fReplaceFile));
3533
3534	/**
3535	* Gets the logger info helper.
3536	* The returned info helper will unconditionally write all output to the log.
3537	*
3538	* @returns Pointer to the logger info helper.
3539	* @param pDevIns The device instance.
3540	*/
3541	DECLR3CALLBACKMEMBER(PCDBGFINFOHLP, pfnDBGFInfoLogHlp,(PPDMDEVINS pDevIns));
3542
3543	/**
3544	* Queries a 64-bit register value.
3545	*
3546	* @retval VINF_SUCCESS
3547	* @retval VERR_INVALID_VM_HANDLE
3548	* @retval VERR_INVALID_CPU_ID
3549	* @retval VERR_DBGF_REGISTER_NOT_FOUND
3550	* @retval VERR_DBGF_UNSUPPORTED_CAST
3551	* @retval VINF_DBGF_TRUNCATED_REGISTER
3552	* @retval VINF_DBGF_ZERO_EXTENDED_REGISTER
3553	*
3554	* @param pDevIns The device instance.
3555	* @param idDefCpu The default target CPU ID, VMCPUID_ANY if not
3556	* applicable. Can be OR'ed with
3557	* DBGFREG_HYPER_VMCPUID.
3558	* @param pszReg The register that's being queried. Except for
3559	* CPU registers, this must be on the form
3560	* "set.reg[.sub]".
3561	* @param pu64 Where to store the register value.
3562	*/
3563	DECLR3CALLBACKMEMBER(int, pfnDBGFRegNmQueryU64,(PPDMDEVINS pDevIns, VMCPUID idDefCpu, const char pszReg, uint64_t pu64));
3564
3565	/**
3566	* Format a set of registers.
3567	*
3568	* This is restricted to registers from one CPU, that specified by @a idCpu.
3569	*
3570	* @returns VBox status code.
3571	* @param pDevIns The device instance.
3572	* @param idCpu The CPU ID of any CPU registers that may be
3573	* printed, pass VMCPUID_ANY if not applicable.
3574	* @param pszBuf The output buffer.
3575	* @param cbBuf The size of the output buffer.
3576	* @param pszFormat The format string. Register names are given by
3577	* %VR{name}, they take no arguments.
3578	* @param va Other format arguments.
3579	*/
3580	DECLR3CALLBACKMEMBER(int, pfnDBGFRegPrintfV,(PPDMDEVINS pDevIns, VMCPUID idCpu, char *pszBuf, size_t cbBuf,
3581	const char *pszFormat, va_list va));
3582
3583	/**
3584	* Registers a statistics sample.
3585	*
3586	* @param pDevIns Device instance of the DMA.
3587	* @param pvSample Pointer to the sample.
3588	* @param enmType Sample type. This indicates what pvSample is
3589	* pointing at.
3590	* @param pszName Sample name, unix path style. If this does not
3591	* start with a '/', the default prefix will be
3592	* prepended, otherwise it will be used as-is.
3593	* @param enmUnit Sample unit.
3594	* @param pszDesc Sample description.
3595	*/
3596	DECLR3CALLBACKMEMBER(void, pfnSTAMRegister,(PPDMDEVINS pDevIns, void pvSample, STAMTYPE enmType, const char pszName, STAMUNIT enmUnit, const char *pszDesc));
3597
3598	/**
3599	* Same as pfnSTAMRegister except that the name is specified in a
3600	* RTStrPrintfV like fashion.
3601	*
3602	* @param pDevIns Device instance of the DMA.
3603	* @param pvSample Pointer to the sample.
3604	* @param enmType Sample type. This indicates what pvSample is
3605	* pointing at.
3606	* @param enmVisibility Visibility type specifying whether unused
3607	* statistics should be visible or not.
3608	* @param enmUnit Sample unit.
3609	* @param pszDesc Sample description.
3610	* @param pszName Sample name format string, unix path style. If
3611	* this does not start with a '/', the default
3612	* prefix will be prepended, otherwise it will be
3613	* used as-is.
3614	* @param args Arguments to the format string.
3615	*/
3616	DECLR3CALLBACKMEMBER(void, pfnSTAMRegisterV,(PPDMDEVINS pDevIns, void *pvSample, STAMTYPE enmType,
3617	STAMVISIBILITY enmVisibility, STAMUNIT enmUnit, const char *pszDesc,
3618	const char *pszName, va_list args) RT_IPRT_FORMAT_ATTR(7, 0));
3619
3620	/**
3621	* Deregister zero or more samples given their name prefix.
3622	*
3623	* @returns VBox status code.
3624	* @param pDevIns The device instance.
3625	* @param pszPrefix The name prefix of the samples to remove. If this does
3626	* not start with a '/', the default prefix will be
3627	* prepended, otherwise it will be used as-is.
3628	*/
3629	DECLR3CALLBACKMEMBER(int, pfnSTAMDeregisterByPrefix,(PPDMDEVINS pDevIns, const char *pszPrefix));
3630
3631	/**
3632	* Registers a PCI device with the default PCI bus.
3633	*
3634	* If a PDM device has more than one PCI device, they must be registered in the
3635	* order of PDMDEVINSR3::apPciDevs.
3636	*
3637	* @returns VBox status code.
3638	* @param pDevIns The device instance.
3639	* @param pPciDev The PCI device structure.
3640	* This must be kept in the instance data.
3641	* The PCI configuration must be initialized before registration.
3642	* @param fFlags 0, PDMPCIDEVREG_F_PCI_BRIDGE or
3643	* PDMPCIDEVREG_F_NOT_MANDATORY_NO.
3644	* @param uPciDevNo PDMPCIDEVREG_DEV_NO_FIRST_UNUSED,
3645	* PDMPCIDEVREG_DEV_NO_SAME_AS_PREV, or a specific
3646	* device number (0-31). This will be ignored if
3647	* the CFGM configuration contains a PCIDeviceNo
3648	* value.
3649	* @param uPciFunNo PDMPCIDEVREG_FUN_NO_FIRST_UNUSED, or a specific
3650	* function number (0-7). This will be ignored if
3651	* the CFGM configuration contains a PCIFunctionNo
3652	* value.
3653	* @param pszName Device name, if NULL PDMDEVREG::szName is used.
3654	* The pointer is saved, so don't free or changed.
3655	* @note The PCI device configuration is now implicit from the apPciDevs
3656	* index, meaning that the zero'th entry is the primary one and
3657	* subsequent uses CFGM subkeys "PciDev1", "PciDev2" and so on.
3658	*/
3659	DECLR3CALLBACKMEMBER(int, pfnPCIRegister,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t fFlags,
3660	uint8_t uPciDevNo, uint8_t uPciFunNo, const char *pszName));
3661
3662	/**
3663	* Initialize MSI or MSI-X emulation support for the given PCI device.
3664	*
3665	* @see PDMPCIBUSREG::pfnRegisterMsiR3 for details.
3666	*
3667	* @returns VBox status code.
3668	* @param pDevIns The device instance.
3669	* @param pPciDev The PCI device. NULL is an alias for the first
3670	* one registered.
3671	* @param pMsiReg MSI emulation registration structure.
3672	*/
3673	DECLR3CALLBACKMEMBER(int, pfnPCIRegisterMsi,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, PPDMMSIREG pMsiReg));
3674
3675	/**
3676	* Registers a I/O region (memory mapped or I/O ports) for a PCI device.
3677	*
3678	* @returns VBox status code.
3679	* @param pDevIns The device instance.
3680	* @param pPciDev The PCI device structure. If NULL the default
3681	* PCI device for this device instance is used.
3682	* @param iRegion The region number.
3683	* @param cbRegion Size of the region.
3684	* @param enmType PCI_ADDRESS_SPACE_MEM, PCI_ADDRESS_SPACE_IO or PCI_ADDRESS_SPACE_MEM_PREFETCH.
3685	* @param fFlags PDMPCIDEV_IORGN_F_XXX.
3686	* @param hHandle An I/O port, MMIO or MMIO2 handle according to
3687	* @a fFlags, UINT64_MAX if no handle is passed
3688	* (old style).
3689	* @param pfnMapUnmap Callback for doing the mapping, optional when a
3690	* handle is specified. The callback will be
3691	* invoked holding only the PDM lock. The device
3692	* lock will _not_ be taken (due to lock order).
3693	*/
3694	DECLR3CALLBACKMEMBER(int, pfnPCIIORegionRegister,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t iRegion,
3695	RTGCPHYS cbRegion, PCIADDRESSSPACE enmType, uint32_t fFlags,
3696	uint64_t hHandle, PFNPCIIOREGIONMAP pfnMapUnmap));
3697
3698	/**
3699	* Register PCI configuration space read/write callbacks.
3700	*
3701	* @returns VBox status code.
3702	* @param pDevIns The device instance.
3703	* @param pPciDev The PCI device structure. If NULL the default
3704	* PCI device for this device instance is used.
3705	* @param pfnRead Pointer to the user defined PCI config read function.
3706	* to call default PCI config read function. Can be NULL.
3707	* @param pfnWrite Pointer to the user defined PCI config write function.
3708	* @remarks The callbacks will be invoked holding the PDM lock. The device lock
3709	* is NOT take because that is very likely be a lock order violation.
3710	* @thread EMT(0)
3711	* @note Only callable during VM creation.
3712	* @sa PDMDevHlpPCIConfigRead, PDMDevHlpPCIConfigWrite
3713	*/
3714	DECLR3CALLBACKMEMBER(int, pfnPCIInterceptConfigAccesses,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev,
3715	PFNPCICONFIGREAD pfnRead, PFNPCICONFIGWRITE pfnWrite));
3716
3717	/**
3718	* Perform a PCI configuration space write.
3719	*
3720	* This is for devices that make use of PDMDevHlpPCIInterceptConfigAccesses().
3721	*
3722	* @returns Strict VBox status code (mainly DBGFSTOP).
3723	* @param pDevIns The device instance.
3724	* @param pPciDev The PCI device which config space is being read.
3725	* @param uAddress The config space address.
3726	* @param cb The size of the read: 1, 2 or 4 bytes.
3727	* @param u32Value The value to write.
3728	*/
3729	DECLR3CALLBACKMEMBER(VBOXSTRICTRC, pfnPCIConfigWrite,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev,
3730	uint32_t uAddress, unsigned cb, uint32_t u32Value));
3731
3732	/**
3733	* Perform a PCI configuration space read.
3734	*
3735	* This is for devices that make use of PDMDevHlpPCIInterceptConfigAccesses().
3736	*
3737	* @returns Strict VBox status code (mainly DBGFSTOP).
3738	* @param pDevIns The device instance.
3739	* @param pPciDev The PCI device which config space is being read.
3740	* @param uAddress The config space address.
3741	* @param cb The size of the read: 1, 2 or 4 bytes.
3742	* @param pu32Value Where to return the value.
3743	*/
3744	DECLR3CALLBACKMEMBER(VBOXSTRICTRC, pfnPCIConfigRead,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev,
3745	uint32_t uAddress, unsigned cb, uint32_t *pu32Value));
3746
3747	/**
3748	* Bus master physical memory read.
3749	*
3750	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_READ_BM_DISABLED, later maybe
3751	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
3752	* @param pDevIns The device instance.
3753	* @param pPciDev The PCI device structure. If NULL the default
3754	* PCI device for this device instance is used.
3755	* @param GCPhys Physical address start reading from.
3756	* @param pvBuf Where to put the read bits.
3757	* @param cbRead How many bytes to read.
3758	* @param fFlags Combination of PDM_DEVHLP_PHYS_RW_F_XXX.
3759	* @thread Any thread, but the call may involve the emulation thread.
3760	*/
3761	DECLR3CALLBACKMEMBER(int, pfnPCIPhysRead,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead, uint32_t fFlags));
3762
3763	/**
3764	* Bus master physical memory write.
3765	*
3766	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_WRITE_BM_DISABLED, later maybe
3767	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
3768	* @param pDevIns The device instance.
3769	* @param pPciDev The PCI device structure. If NULL the default
3770	* PCI device for this device instance is used.
3771	* @param GCPhys Physical address to write to.
3772	* @param pvBuf What to write.
3773	* @param cbWrite How many bytes to write.
3774	* @param fFlags Combination of PDM_DEVHLP_PHYS_RW_F_XXX.
3775	* @thread Any thread, but the call may involve the emulation thread.
3776	*/
3777	DECLR3CALLBACKMEMBER(int, pfnPCIPhysWrite,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite, uint32_t fFlags));
3778
3779	/**
3780	* Requests the mapping of a guest page into ring-3 in preparation for a bus master
3781	* physical memory write operation.
3782	*
3783	* Refer pfnPhysGCPhys2CCPtr() for further details.
3784	*
3785	* @returns VBox status code.
3786	* @param pDevIns The device instance.
3787	* @param pPciDev The PCI device structure. If NULL the default
3788	* PCI device for this device instance is used.
3789	* @param GCPhys The guest physical address of the page that should be
3790	* mapped.
3791	* @param fFlags Flags reserved for future use, MBZ.
3792	* @param ppv Where to store the address corresponding to GCPhys.
3793	* @param pLock Where to store the lock information that
3794	* pfnPhysReleasePageMappingLock needs.
3795	*
3796	* @remarks Avoid calling this API from within critical sections (other than the PGM
3797	* one) because of the deadlock risk when we have to delegating the task to
3798	* an EMT.
3799	* @thread Any.
3800	*/
3801	DECLR3CALLBACKMEMBER(int, pfnPCIPhysGCPhys2CCPtr,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys, uint32_t fFlags,
3802	void **ppv, PPGMPAGEMAPLOCK pLock));
3803
3804	/**
3805	* Requests the mapping of a guest page into ring-3, external threads, in prepartion
3806	* for a bus master physical memory read operation.
3807	*
3808	* Refer pfnPhysGCPhys2CCPtrReadOnly() for further details.
3809	*
3810	* @returns VBox status code.
3811	* @param pDevIns The device instance.
3812	* @param pPciDev The PCI device structure. If NULL the default
3813	* PCI device for this device instance is used.
3814	* @param GCPhys The guest physical address of the page that
3815	* should be mapped.
3816	* @param fFlags Flags reserved for future use, MBZ.
3817	* @param ppv Where to store the address corresponding to
3818	* GCPhys.
3819	* @param pLock Where to store the lock information that
3820	* pfnPhysReleasePageMappingLock needs.
3821	*
3822	* @remarks Avoid calling this API from within critical sections.
3823	* @thread Any.
3824	*/
3825	DECLR3CALLBACKMEMBER(int, pfnPCIPhysGCPhys2CCPtrReadOnly,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys,
3826	uint32_t fFlags, void const **ppv, PPGMPAGEMAPLOCK pLock));
3827
3828	/**
3829	* Requests the mapping of multiple guest pages into ring-3 in prepartion for a bus
3830	* master physical memory write operation.
3831	*
3832	* When you're done with the pages, call pfnPhysBulkReleasePageMappingLocks()
3833	* ASAP to release them.
3834	*
3835	* Refer pfnPhysBulkGCPhys2CCPtr() for further details.
3836	*
3837	* @returns VBox status code.
3838	* @param pDevIns The device instance.
3839	* @param pPciDev The PCI device structure. If NULL the default
3840	* PCI device for this device instance is used.
3841	* @param cPages Number of pages to lock.
3842	* @param paGCPhysPages The guest physical address of the pages that
3843	* should be mapped (@a cPages entries).
3844	* @param fFlags Flags reserved for future use, MBZ.
3845	* @param papvPages Where to store the ring-3 mapping addresses
3846	* corresponding to @a paGCPhysPages.
3847	* @param paLocks Where to store the locking information that
3848	* pfnPhysBulkReleasePageMappingLock needs (@a cPages
3849	* in length).
3850	*/
3851	DECLR3CALLBACKMEMBER(int, pfnPCIPhysBulkGCPhys2CCPtr,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t cPages,
3852	PCRTGCPHYS paGCPhysPages, uint32_t fFlags, void **papvPages,
3853	PPGMPAGEMAPLOCK paLocks));
3854
3855	/**
3856	* Requests the mapping of multiple guest pages into ring-3 in preparation for a bus
3857	* master physical memory read operation.
3858	*
3859	* When you're done with the pages, call pfnPhysBulkReleasePageMappingLocks()
3860	* ASAP to release them.
3861	*
3862	* Refer pfnPhysBulkGCPhys2CCPtrReadOnly() for further details.
3863	*
3864	* @returns VBox status code.
3865	* @param pDevIns The device instance.
3866	* @param pPciDev The PCI device structure. If NULL the default
3867	* PCI device for this device instance is used.
3868	* @param cPages Number of pages to lock.
3869	* @param paGCPhysPages The guest physical address of the pages that
3870	* should be mapped (@a cPages entries).
3871	* @param fFlags Flags reserved for future use, MBZ.
3872	* @param papvPages Where to store the ring-3 mapping addresses
3873	* corresponding to @a paGCPhysPages.
3874	* @param paLocks Where to store the lock information that
3875	* pfnPhysReleasePageMappingLock needs (@a cPages
3876	* in length).
3877	*/
3878	DECLR3CALLBACKMEMBER(int, pfnPCIPhysBulkGCPhys2CCPtrReadOnly,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t cPages,
3879	PCRTGCPHYS paGCPhysPages, uint32_t fFlags,
3880	void const **papvPages, PPGMPAGEMAPLOCK paLocks));
3881
3882	/**
3883	* Sets the IRQ for the given PCI device.
3884	*
3885	* @param pDevIns The device instance.
3886	* @param pPciDev The PCI device structure. If NULL the default
3887	* PCI device for this device instance is used.
3888	* @param iIrq IRQ number to set.
3889	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
3890	* @thread Any thread, but will involve the emulation thread.
3891	*/
3892	DECLR3CALLBACKMEMBER(void, pfnPCISetIrq,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, int iIrq, int iLevel));
3893
3894	/**
3895	* Sets the IRQ for the given PCI device, but doesn't wait for EMT to process
3896	* the request when not called from EMT.
3897	*
3898	* @param pDevIns The device instance.
3899	* @param pPciDev The PCI device structure. If NULL the default
3900	* PCI device for this device instance is used.
3901	* @param iIrq IRQ number to set.
3902	* @param iLevel IRQ level.
3903	* @thread Any thread, but will involve the emulation thread.
3904	*/
3905	DECLR3CALLBACKMEMBER(void, pfnPCISetIrqNoWait,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, int iIrq, int iLevel));
3906
3907	/**
3908	* Set ISA IRQ for a device.
3909	*
3910	* @param pDevIns The device instance.
3911	* @param iIrq IRQ number to set.
3912	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
3913	* @thread Any thread, but will involve the emulation thread.
3914	*/
3915	DECLR3CALLBACKMEMBER(void, pfnISASetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
3916
3917	/**
3918	* Set the ISA IRQ for a device, but don't wait for EMT to process
3919	* the request when not called from EMT.
3920	*
3921	* @param pDevIns The device instance.
3922	* @param iIrq IRQ number to set.
3923	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
3924	* @thread Any thread, but will involve the emulation thread.
3925	*/
3926	DECLR3CALLBACKMEMBER(void, pfnISASetIrqNoWait,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
3927
3928	/**
3929	* Attaches a driver (chain) to the device.
3930	*
3931	* The first call for a LUN this will serve as a registration of the LUN. The pBaseInterface and
3932	* the pszDesc string will be registered with that LUN and kept around for PDMR3QueryDeviceLun().
3933	*
3934	* @returns VBox status code.
3935	* @param pDevIns The device instance.
3936	* @param iLun The logical unit to attach.
3937	* @param pBaseInterface Pointer to the base interface for that LUN. (device side / down)
3938	* @param ppBaseInterface Where to store the pointer to the base interface. (driver side / up)
3939	* @param pszDesc Pointer to a string describing the LUN. This string must remain valid
3940	* for the live of the device instance.
3941	*/
3942	DECLR3CALLBACKMEMBER(int, pfnDriverAttach,(PPDMDEVINS pDevIns, uint32_t iLun, PPDMIBASE pBaseInterface,
3943	PPDMIBASE ppBaseInterface, const char pszDesc));
3944
3945	/**
3946	* Detaches an attached driver (chain) from the device again.
3947	*
3948	* @returns VBox status code.
3949	* @param pDevIns The device instance.
3950	* @param pDrvIns The driver instance to detach.
3951	* @param fFlags Flags, combination of the PDMDEVATT_FLAGS_* \#defines.
3952	*/
3953	DECLR3CALLBACKMEMBER(int, pfnDriverDetach,(PPDMDEVINS pDevIns, PPDMDRVINS pDrvIns, uint32_t fFlags));
3954
3955	/**
3956	* Reconfigures the driver chain for a LUN, detaching any driver currently
3957	* present there.
3958	*
3959	* Caller will have attach it, of course.
3960	*
3961	* @returns VBox status code.
3962	* @param pDevIns The device instance.
3963	* @param iLun The logical unit to reconfigure.
3964	* @param cDepth The depth of the driver chain. Determins the
3965	* size of @a papszDrivers and @a papConfigs.
3966	* @param papszDrivers The names of the drivers to configure in the
3967	* chain, first entry is the one immediately
3968	* below the device/LUN
3969	* @param papConfigs The configurations for each of the drivers
3970	* in @a papszDrivers array. NULL entries
3971	* corresponds to empty 'Config' nodes. This
3972	* function will take ownership of non-NULL
3973	* CFGM sub-trees and set the array member to
3974	* NULL, so the caller can do cleanups on
3975	* failure. This parameter is optional.
3976	* @param fFlags Reserved, MBZ.
3977	*/
3978	DECLR3CALLBACKMEMBER(int, pfnDriverReconfigure,(PPDMDEVINS pDevIns, uint32_t iLun, uint32_t cDepth,
3979	const char * const papszDrivers, PCFGMNODE papConfigs, uint32_t fFlags));
3980
3981	/** @name Exported PDM Queue Functions
3982	* @{ */
3983	/**
3984	* Create a queue.
3985	*
3986	* @returns VBox status code.
3987	* @param pDevIns The device instance.
3988	* @param cbItem The size of a queue item.
3989	* @param cItems The number of items in the queue.
3990	* @param cMilliesInterval The number of milliseconds between polling the queue.
3991	* If 0 then the emulation thread will be notified whenever an item arrives.
3992	* @param pfnCallback The consumer function.
3993	* @param fRZEnabled Set if the queue should work in RC and R0.
3994	* @param pszName The queue base name. The instance number will be
3995	* appended automatically.
3996	* @param phQueue Where to store the queue handle on success.
3997	* @thread EMT(0)
3998	* @remarks The device critical section will NOT be entered before calling the
3999	* callback. No locks will be held, but for now it's safe to assume
4000	* that only one EMT will do queue callbacks at any one time.
4001	*/
4002	DECLR3CALLBACKMEMBER(int, pfnQueueCreate,(PPDMDEVINS pDevIns, size_t cbItem, uint32_t cItems, uint32_t cMilliesInterval,
4003	PFNPDMQUEUEDEV pfnCallback, bool fRZEnabled, const char *pszName,
4004	PDMQUEUEHANDLE *phQueue));
4005
4006	DECLR3CALLBACKMEMBER(PPDMQUEUEITEMCORE, pfnQueueAlloc,(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue));
4007	DECLR3CALLBACKMEMBER(int, pfnQueueInsert,(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue, PPDMQUEUEITEMCORE pItem));
4008	DECLR3CALLBACKMEMBER(bool, pfnQueueFlushIfNecessary,(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue));
4009	/** @} */
4010
4011	/** @name PDM Task
4012	* @{ */
4013	/**
4014	* Create an asynchronous ring-3 task.
4015	*
4016	* @returns VBox status code.
4017	* @param pDevIns The device instance.
4018	* @param fFlags PDMTASK_F_XXX
4019	* @param pszName The function name or similar. Used for statistics,
4020	* so no slashes.
4021	* @param pfnCallback The task function.
4022	* @param pvUser User argument for the task function.
4023	* @param phTask Where to return the task handle.
4024	* @thread EMT(0)
4025	*/
4026	DECLR3CALLBACKMEMBER(int, pfnTaskCreate,(PPDMDEVINS pDevIns, uint32_t fFlags, const char *pszName,
4027	PFNPDMTASKDEV pfnCallback, void pvUser, PDMTASKHANDLE phTask));
4028	/**
4029	* Triggers the running the given task.
4030	*
4031	* @returns VBox status code.
4032	* @retval VINF_ALREADY_POSTED is the task is already pending.
4033	* @param pDevIns The device instance.
4034	* @param hTask The task to trigger.
4035	* @thread Any thread.
4036	*/
4037	DECLR3CALLBACKMEMBER(int, pfnTaskTrigger,(PPDMDEVINS pDevIns, PDMTASKHANDLE hTask));
4038	/** @} */
4039
4040	/** @name SUP Event Semaphore Wrappers (single release / auto reset)
4041	* These semaphores can be signalled from ring-0.
4042	* @{ */
4043	/** @sa SUPSemEventCreate */
4044	DECLR3CALLBACKMEMBER(int, pfnSUPSemEventCreate,(PPDMDEVINS pDevIns, PSUPSEMEVENT phEvent));
4045	/** @sa SUPSemEventClose */
4046	DECLR3CALLBACKMEMBER(int, pfnSUPSemEventClose,(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent));
4047	/** @sa SUPSemEventSignal */
4048	DECLR3CALLBACKMEMBER(int, pfnSUPSemEventSignal,(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent));
4049	/** @sa SUPSemEventWaitNoResume */
4050	DECLR3CALLBACKMEMBER(int, pfnSUPSemEventWaitNoResume,(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent, uint32_t cMillies));
4051	/** @sa SUPSemEventWaitNsAbsIntr */
4052	DECLR3CALLBACKMEMBER(int, pfnSUPSemEventWaitNsAbsIntr,(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent, uint64_t uNsTimeout));
4053	/** @sa SUPSemEventWaitNsRelIntr */
4054	DECLR3CALLBACKMEMBER(int, pfnSUPSemEventWaitNsRelIntr,(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent, uint64_t cNsTimeout));
4055	/** @sa SUPSemEventGetResolution */
4056	DECLR3CALLBACKMEMBER(uint32_t, pfnSUPSemEventGetResolution,(PPDMDEVINS pDevIns));
4057	/** @} */
4058
4059	/** @name SUP Multi Event Semaphore Wrappers (multiple release / manual reset)
4060	* These semaphores can be signalled from ring-0.
4061	* @{ */
4062	/** @sa SUPSemEventMultiCreate */
4063	DECLR3CALLBACKMEMBER(int, pfnSUPSemEventMultiCreate,(PPDMDEVINS pDevIns, PSUPSEMEVENTMULTI phEventMulti));
4064	/** @sa SUPSemEventMultiClose */
4065	DECLR3CALLBACKMEMBER(int, pfnSUPSemEventMultiClose,(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti));
4066	/** @sa SUPSemEventMultiSignal */
4067	DECLR3CALLBACKMEMBER(int, pfnSUPSemEventMultiSignal,(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti));
4068	/** @sa SUPSemEventMultiReset */
4069	DECLR3CALLBACKMEMBER(int, pfnSUPSemEventMultiReset,(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti));
4070	/** @sa SUPSemEventMultiWaitNoResume */
4071	DECLR3CALLBACKMEMBER(int, pfnSUPSemEventMultiWaitNoResume,(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti, uint32_t cMillies));
4072	/** @sa SUPSemEventMultiWaitNsAbsIntr */
4073	DECLR3CALLBACKMEMBER(int, pfnSUPSemEventMultiWaitNsAbsIntr,(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti, uint64_t uNsTimeout));
4074	/** @sa SUPSemEventMultiWaitNsRelIntr */
4075	DECLR3CALLBACKMEMBER(int, pfnSUPSemEventMultiWaitNsRelIntr,(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti, uint64_t cNsTimeout));
4076	/** @sa SUPSemEventMultiGetResolution */
4077	DECLR3CALLBACKMEMBER(uint32_t, pfnSUPSemEventMultiGetResolution,(PPDMDEVINS pDevIns));
4078	/** @} */
4079
4080	/**
4081	* Initializes a PDM critical section.
4082	*
4083	* The PDM critical sections are derived from the IPRT critical sections, but
4084	* works in RC and R0 as well.
4085	*
4086	* @returns VBox status code.
4087	* @param pDevIns The device instance.
4088	* @param pCritSect Pointer to the critical section.
4089	* @param SRC_POS Use RT_SRC_POS.
4090	* @param pszNameFmt Format string for naming the critical section.
4091	* For statistics and lock validation.
4092	* @param va Arguments for the format string.
4093	*/
4094	DECLR3CALLBACKMEMBER(int, pfnCritSectInit,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, RT_SRC_POS_DECL,
4095	const char *pszNameFmt, va_list va) RT_IPRT_FORMAT_ATTR(6, 0));
4096
4097	/**
4098	* Gets the NOP critical section.
4099	*
4100	* @returns The ring-3 address of the NOP critical section.
4101	* @param pDevIns The device instance.
4102	*/
4103	DECLR3CALLBACKMEMBER(PPDMCRITSECT, pfnCritSectGetNop,(PPDMDEVINS pDevIns));
4104
4105	/**
4106	* Changes the device level critical section from the automatically created
4107	* default to one desired by the device constructor.
4108	*
4109	* For ring-0 and raw-mode capable devices, the call must be repeated in each of
4110	* the additional contexts.
4111	*
4112	* @returns VBox status code.
4113	* @param pDevIns The device instance.
4114	* @param pCritSect The critical section to use. NULL is not
4115	* valid, instead use the NOP critical
4116	* section.
4117	*/
4118	DECLR3CALLBACKMEMBER(int, pfnSetDeviceCritSect,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect));
4119
4120	/** @name Exported PDM Critical Section Functions
4121	* @{ */
4122	DECLR3CALLBACKMEMBER(bool, pfnCritSectYield,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect));
4123	DECLR3CALLBACKMEMBER(int, pfnCritSectEnter,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, int rcBusy));
4124	DECLR3CALLBACKMEMBER(int, pfnCritSectEnterDebug,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, int rcBusy, RTHCUINTPTR uId, RT_SRC_POS_DECL));
4125	DECLR3CALLBACKMEMBER(int, pfnCritSectTryEnter,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect));
4126	DECLR3CALLBACKMEMBER(int, pfnCritSectTryEnterDebug,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, RTHCUINTPTR uId, RT_SRC_POS_DECL));
4127	DECLR3CALLBACKMEMBER(int, pfnCritSectLeave,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect));
4128	DECLR3CALLBACKMEMBER(bool, pfnCritSectIsOwner,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
4129	DECLR3CALLBACKMEMBER(bool, pfnCritSectIsInitialized,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
4130	DECLR3CALLBACKMEMBER(bool, pfnCritSectHasWaiters,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
4131	DECLR3CALLBACKMEMBER(uint32_t, pfnCritSectGetRecursion,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
4132	DECLR3CALLBACKMEMBER(int, pfnCritSectScheduleExitEvent,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, SUPSEMEVENT hEventToSignal));
4133	DECLR3CALLBACKMEMBER(int, pfnCritSectDelete,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect));
4134	/** @} */
4135
4136	/** @name Exported PDM Read/Write Critical Section Functions
4137	* @{ */
4138	DECLR3CALLBACKMEMBER(int, pfnCritSectRwInit,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect, RT_SRC_POS_DECL,
4139	const char *pszNameFmt, va_list va) RT_IPRT_FORMAT_ATTR(6, 0));
4140	DECLR3CALLBACKMEMBER(int, pfnCritSectRwDelete,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect));
4141
4142	DECLR3CALLBACKMEMBER(int, pfnCritSectRwEnterShared,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect, int rcBusy));
4143	DECLR3CALLBACKMEMBER(int, pfnCritSectRwEnterSharedDebug,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect, int rcBusy, RTHCUINTPTR uId, RT_SRC_POS_DECL));
4144	DECLR3CALLBACKMEMBER(int, pfnCritSectRwTryEnterShared,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect));
4145	DECLR3CALLBACKMEMBER(int, pfnCritSectRwTryEnterSharedDebug,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect, RTHCUINTPTR uId, RT_SRC_POS_DECL));
4146	DECLR3CALLBACKMEMBER(int, pfnCritSectRwLeaveShared,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect));
4147
4148	DECLR3CALLBACKMEMBER(int, pfnCritSectRwEnterExcl,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect, int rcBusy));
4149	DECLR3CALLBACKMEMBER(int, pfnCritSectRwEnterExclDebug,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect, int rcBusy, RTHCUINTPTR uId, RT_SRC_POS_DECL));
4150	DECLR3CALLBACKMEMBER(int, pfnCritSectRwTryEnterExcl,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect));
4151	DECLR3CALLBACKMEMBER(int, pfnCritSectRwTryEnterExclDebug,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect, RTHCUINTPTR uId, RT_SRC_POS_DECL));
4152	DECLR3CALLBACKMEMBER(int, pfnCritSectRwLeaveExcl,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect));
4153
4154	DECLR3CALLBACKMEMBER(bool, pfnCritSectRwIsWriteOwner,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect));
4155	DECLR3CALLBACKMEMBER(bool, pfnCritSectRwIsReadOwner,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect, bool fWannaHear));
4156	DECLR3CALLBACKMEMBER(uint32_t, pfnCritSectRwGetWriteRecursion,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect));
4157	DECLR3CALLBACKMEMBER(uint32_t, pfnCritSectRwGetWriterReadRecursion,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect));
4158	DECLR3CALLBACKMEMBER(uint32_t, pfnCritSectRwGetReadCount,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect));
4159	DECLR3CALLBACKMEMBER(bool, pfnCritSectRwIsInitialized,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect));
4160	/** @} */
4161
4162	/**
4163	* Creates a PDM thread.
4164	*
4165	* This differs from the RTThreadCreate() API in that PDM takes care of suspending,
4166	* resuming, and destroying the thread as the VM state changes.
4167	*
4168	* @returns VBox status code.
4169	* @param pDevIns The device instance.
4170	* @param ppThread Where to store the thread 'handle'.
4171	* @param pvUser The user argument to the thread function.
4172	* @param pfnThread The thread function.
4173	* @param pfnWakeup The wakup callback. This is called on the EMT
4174	* thread when a state change is pending.
4175	* @param cbStack See RTThreadCreate.
4176	* @param enmType See RTThreadCreate.
4177	* @param pszName See RTThreadCreate.
4178	* @remarks The device critical section will NOT be entered prior to invoking
4179	* the function pointers.
4180	*/
4181	DECLR3CALLBACKMEMBER(int, pfnThreadCreate,(PPDMDEVINS pDevIns, PPPDMTHREAD ppThread, void *pvUser, PFNPDMTHREADDEV pfnThread,
4182	PFNPDMTHREADWAKEUPDEV pfnWakeup, size_t cbStack, RTTHREADTYPE enmType, const char *pszName));
4183
4184	/** @name Exported PDM Thread Functions
4185	* @{ */
4186	DECLR3CALLBACKMEMBER(int, pfnThreadDestroy,(PPDMTHREAD pThread, int *pRcThread));
4187	DECLR3CALLBACKMEMBER(int, pfnThreadIAmSuspending,(PPDMTHREAD pThread));
4188	DECLR3CALLBACKMEMBER(int, pfnThreadIAmRunning,(PPDMTHREAD pThread));
4189	DECLR3CALLBACKMEMBER(int, pfnThreadSleep,(PPDMTHREAD pThread, RTMSINTERVAL cMillies));
4190	DECLR3CALLBACKMEMBER(int, pfnThreadSuspend,(PPDMTHREAD pThread));
4191	DECLR3CALLBACKMEMBER(int, pfnThreadResume,(PPDMTHREAD pThread));
4192	/** @} */
4193
4194	/**
4195	* Set up asynchronous handling of a suspend, reset or power off notification.
4196	*
4197	* This shall only be called when getting the notification. It must be called
4198	* for each one.
4199	*
4200	* @returns VBox status code.
4201	* @param pDevIns The device instance.
4202	* @param pfnAsyncNotify The callback.
4203	* @thread EMT(0)
4204	* @remarks The caller will enter the device critical section prior to invoking
4205	* the callback.
4206	*/
4207	DECLR3CALLBACKMEMBER(int, pfnSetAsyncNotification, (PPDMDEVINS pDevIns, PFNPDMDEVASYNCNOTIFY pfnAsyncNotify));
4208
4209	/**
4210	* Notify EMT(0) that the device has completed the asynchronous notification
4211	* handling.
4212	*
4213	* This can be called at any time, spurious calls will simply be ignored.
4214	*
4215	* @param pDevIns The device instance.
4216	* @thread Any
4217	*/
4218	DECLR3CALLBACKMEMBER(void, pfnAsyncNotificationCompleted, (PPDMDEVINS pDevIns));
4219
4220	/**
4221	* Register the RTC device.
4222	*
4223	* @returns VBox status code.
4224	* @param pDevIns The device instance.
4225	* @param pRtcReg Pointer to a RTC registration structure.
4226	* @param ppRtcHlp Where to store the pointer to the helper
4227	* functions.
4228	*/
4229	DECLR3CALLBACKMEMBER(int, pfnRTCRegister,(PPDMDEVINS pDevIns, PCPDMRTCREG pRtcReg, PCPDMRTCHLP *ppRtcHlp));
4230
4231	/**
4232	* Register a PCI Bus.
4233	*
4234	* @returns VBox status code, but the positive values 0..31 are used to indicate
4235	* bus number rather than informational status codes.
4236	* @param pDevIns The device instance.
4237	* @param pPciBusReg Pointer to PCI bus registration structure.
4238	* @param ppPciHlp Where to store the pointer to the PCI Bus
4239	* helpers.
4240	* @param piBus Where to return the PDM bus number. Optional.
4241	*/
4242	DECLR3CALLBACKMEMBER(int, pfnPCIBusRegister,(PPDMDEVINS pDevIns, PPDMPCIBUSREGR3 pPciBusReg,
4243	PCPDMPCIHLPR3 ppPciHlp, uint32_t piBus));
4244
4245	/**
4246	* Register the IOMMU device.
4247	*
4248	* @returns VBox status code.
4249	* @param pDevIns The device instance.
4250	* @param pIommuReg Pointer to a IOMMU registration structure.
4251	* @param ppIommuHlp Where to store the pointer to the ring-3 IOMMU
4252	* helpers.
4253	* @param pidxIommu Where to return the IOMMU index. Optional.
4254	*/
4255	DECLR3CALLBACKMEMBER(int, pfnIommuRegister,(PPDMDEVINS pDevIns, PPDMIOMMUREGR3 pIommuReg, PCPDMIOMMUHLPR3 *ppIommuHlp,
4256	uint32_t *pidxIommu));
4257
4258	/**
4259	* Register the PIC device.
4260	*
4261	* @returns VBox status code.
4262	* @param pDevIns The device instance.
4263	* @param pPicReg Pointer to a PIC registration structure.
4264	* @param ppPicHlp Where to store the pointer to the ring-3 PIC
4265	* helpers.
4266	* @sa PDMDevHlpPICSetUpContext
4267	*/
4268	DECLR3CALLBACKMEMBER(int, pfnPICRegister,(PPDMDEVINS pDevIns, PPDMPICREG pPicReg, PCPDMPICHLP *ppPicHlp));
4269
4270	/**
4271	* Register the Interrupt Controller device.
4272	*
4273	* @returns VBox status code.
4274	* @param pDevIns The device instance.
4275	*/
4276	DECLR3CALLBACKMEMBER(int, pfnIcRegister,(PPDMDEVINS pDevIns));
4277
4278	/**
4279	* Register the I/O APIC device.
4280	*
4281	* @returns VBox status code.
4282	* @param pDevIns The device instance.
4283	* @param pIoApicReg Pointer to a I/O APIC registration structure.
4284	* @param ppIoApicHlp Where to store the pointer to the IOAPIC
4285	* helpers.
4286	*/
4287	DECLR3CALLBACKMEMBER(int, pfnIoApicRegister,(PPDMDEVINS pDevIns, PPDMIOAPICREG pIoApicReg, PCPDMIOAPICHLP *ppIoApicHlp));
4288
4289	/**
4290	* Register the HPET device.
4291	*
4292	* @returns VBox status code.
4293	* @param pDevIns The device instance.
4294	* @param pHpetReg Pointer to a HPET registration structure.
4295	* @param ppHpetHlpR3 Where to store the pointer to the HPET
4296	* helpers.
4297	*/
4298	DECLR3CALLBACKMEMBER(int, pfnHpetRegister,(PPDMDEVINS pDevIns, PPDMHPETREG pHpetReg, PCPDMHPETHLPR3 *ppHpetHlpR3));
4299
4300	/**
4301	* Register a raw PCI device.
4302	*
4303	* @returns VBox status code.
4304	* @param pDevIns The device instance.
4305	* @param pPciRawReg Pointer to a raw PCI registration structure.
4306	* @param ppPciRawHlpR3 Where to store the pointer to the raw PCI
4307	* device helpers.
4308	*/
4309	DECLR3CALLBACKMEMBER(int, pfnPciRawRegister,(PPDMDEVINS pDevIns, PPDMPCIRAWREG pPciRawReg, PCPDMPCIRAWHLPR3 *ppPciRawHlpR3));
4310
4311	/**
4312	* Register the DMA device.
4313	*
4314	* @returns VBox status code.
4315	* @param pDevIns The device instance.
4316	* @param pDmacReg Pointer to a DMAC registration structure.
4317	* @param ppDmacHlp Where to store the pointer to the DMA helpers.
4318	*/
4319	DECLR3CALLBACKMEMBER(int, pfnDMACRegister,(PPDMDEVINS pDevIns, PPDMDMACREG pDmacReg, PCPDMDMACHLP *ppDmacHlp));
4320
4321	/**
4322	* Register transfer function for DMA channel.
4323	*
4324	* @returns VBox status code.
4325	* @param pDevIns The device instance.
4326	* @param uChannel Channel number.
4327	* @param pfnTransferHandler Device specific transfer callback function.
4328	* @param pvUser User pointer to pass to the callback.
4329	* @thread EMT
4330	*/
4331	DECLR3CALLBACKMEMBER(int, pfnDMARegister,(PPDMDEVINS pDevIns, unsigned uChannel, PFNDMATRANSFERHANDLER pfnTransferHandler, void *pvUser));
4332
4333	/**
4334	* Read memory.
4335	*
4336	* @returns VBox status code.
4337	* @param pDevIns The device instance.
4338	* @param uChannel Channel number.
4339	* @param pvBuffer Pointer to target buffer.
4340	* @param off DMA position.
4341	* @param cbBlock Block size.
4342	* @param pcbRead Where to store the number of bytes which was
4343	* read. optional.
4344	* @thread EMT
4345	*/
4346	DECLR3CALLBACKMEMBER(int, pfnDMAReadMemory,(PPDMDEVINS pDevIns, unsigned uChannel, void pvBuffer, uint32_t off, uint32_t cbBlock, uint32_t pcbRead));
4347
4348	/**
4349	* Write memory.
4350	*
4351	* @returns VBox status code.
4352	* @param pDevIns The device instance.
4353	* @param uChannel Channel number.
4354	* @param pvBuffer Memory to write.
4355	* @param off DMA position.
4356	* @param cbBlock Block size.
4357	* @param pcbWritten Where to store the number of bytes which was
4358	* written. optional.
4359	* @thread EMT
4360	*/
4361	DECLR3CALLBACKMEMBER(int, pfnDMAWriteMemory,(PPDMDEVINS pDevIns, unsigned uChannel, const void pvBuffer, uint32_t off, uint32_t cbBlock, uint32_t pcbWritten));
4362
4363	/**
4364	* Set the DREQ line.
4365	*
4366	* @returns VBox status code.
4367	* @param pDevIns Device instance.
4368	* @param uChannel Channel number.
4369	* @param uLevel Level of the line.
4370	* @thread EMT
4371	*/
4372	DECLR3CALLBACKMEMBER(int, pfnDMASetDREQ,(PPDMDEVINS pDevIns, unsigned uChannel, unsigned uLevel));
4373
4374	/**
4375	* Get channel mode.
4376	*
4377	* @returns Channel mode. See specs.
4378	* @param pDevIns The device instance.
4379	* @param uChannel Channel number.
4380	* @thread EMT
4381	*/
4382	DECLR3CALLBACKMEMBER(uint8_t, pfnDMAGetChannelMode,(PPDMDEVINS pDevIns, unsigned uChannel));
4383
4384	/**
4385	* Schedule DMA execution.
4386	*
4387	* @param pDevIns The device instance.
4388	* @thread Any thread.
4389	*/
4390	DECLR3CALLBACKMEMBER(void, pfnDMASchedule,(PPDMDEVINS pDevIns));
4391
4392	/**
4393	* Write CMOS value and update the checksum(s).
4394	*
4395	* @returns VBox status code.
4396	* @param pDevIns The device instance.
4397	* @param iReg The CMOS register index.
4398	* @param u8Value The CMOS register value.
4399	* @thread EMT
4400	*/
4401	DECLR3CALLBACKMEMBER(int, pfnCMOSWrite,(PPDMDEVINS pDevIns, unsigned iReg, uint8_t u8Value));
4402
4403	/**
4404	* Read CMOS value.
4405	*
4406	* @returns VBox status code.
4407	* @param pDevIns The device instance.
4408	* @param iReg The CMOS register index.
4409	* @param pu8Value Where to store the CMOS register value.
4410	* @thread EMT
4411	*/
4412	DECLR3CALLBACKMEMBER(int, pfnCMOSRead,(PPDMDEVINS pDevIns, unsigned iReg, uint8_t *pu8Value));
4413
4414	/**
4415	* Assert that the current thread is the emulation thread.
4416	*
4417	* @returns True if correct.
4418	* @returns False if wrong.
4419	* @param pDevIns The device instance.
4420	* @param pszFile Filename of the assertion location.
4421	* @param iLine The linenumber of the assertion location.
4422	* @param pszFunction Function of the assertion location.
4423	*/
4424	DECLR3CALLBACKMEMBER(bool, pfnAssertEMT,(PPDMDEVINS pDevIns, const char pszFile, unsigned iLine, const char pszFunction));
4425
4426	/**
4427	* Assert that the current thread is NOT the emulation thread.
4428	*
4429	* @returns True if correct.
4430	* @returns False if wrong.
4431	* @param pDevIns The device instance.
4432	* @param pszFile Filename of the assertion location.
4433	* @param iLine The linenumber of the assertion location.
4434	* @param pszFunction Function of the assertion location.
4435	*/
4436	DECLR3CALLBACKMEMBER(bool, pfnAssertOther,(PPDMDEVINS pDevIns, const char pszFile, unsigned iLine, const char pszFunction));
4437
4438	/**
4439	* Resolves the symbol for a raw-mode context interface.
4440	*
4441	* @returns VBox status code.
4442	* @param pDevIns The device instance.
4443	* @param pvInterface The interface structure.
4444	* @param cbInterface The size of the interface structure.
4445	* @param pszSymPrefix What to prefix the symbols in the list with
4446	* before resolving them. This must start with
4447	* 'dev' and contain the driver name.
4448	* @param pszSymList List of symbols corresponding to the interface.
4449	* There is generally a there is generally a define
4450	* holding this list associated with the interface
4451	* definition (INTERFACE_SYM_LIST). For more
4452	* details see PDMR3LdrGetInterfaceSymbols.
4453	* @thread EMT
4454	*/
4455	DECLR3CALLBACKMEMBER(int, pfnLdrGetRCInterfaceSymbols,(PPDMDEVINS pDevIns, void *pvInterface, size_t cbInterface,
4456	const char pszSymPrefix, const char pszSymList));
4457
4458	/**
4459	* Resolves the symbol for a ring-0 context interface.
4460	*
4461	* @returns VBox status code.
4462	* @param pDevIns The device instance.
4463	* @param pvInterface The interface structure.
4464	* @param cbInterface The size of the interface structure.
4465	* @param pszSymPrefix What to prefix the symbols in the list with
4466	* before resolving them. This must start with
4467	* 'dev' and contain the driver name.
4468	* @param pszSymList List of symbols corresponding to the interface.
4469	* There is generally a there is generally a define
4470	* holding this list associated with the interface
4471	* definition (INTERFACE_SYM_LIST). For more
4472	* details see PDMR3LdrGetInterfaceSymbols.
4473	* @thread EMT
4474	*/
4475	DECLR3CALLBACKMEMBER(int, pfnLdrGetR0InterfaceSymbols,(PPDMDEVINS pDevIns, void *pvInterface, size_t cbInterface,
4476	const char pszSymPrefix, const char pszSymList));
4477
4478	/**
4479	* Calls the PDMDEVREGR0::pfnRequest callback (in ring-0 context).
4480	*
4481	* @returns VBox status code.
4482	* @retval VERR_INVALID_FUNCTION if the callback member is NULL.
4483	* @retval VERR_ACCESS_DENIED if the device isn't ring-0 capable.
4484	*
4485	* @param pDevIns The device instance.
4486	* @param uOperation The operation to perform.
4487	* @param u64Arg 64-bit integer argument.
4488	* @thread EMT
4489	*/
4490	DECLR3CALLBACKMEMBER(int, pfnCallR0,(PPDMDEVINS pDevIns, uint32_t uOperation, uint64_t u64Arg));
4491
4492	/**
4493	* Gets the reason for the most recent VM suspend.
4494	*
4495	* @returns The suspend reason. VMSUSPENDREASON_INVALID is returned if no
4496	* suspend has been made or if the pDevIns is invalid.
4497	* @param pDevIns The device instance.
4498	*/
4499	DECLR3CALLBACKMEMBER(VMSUSPENDREASON, pfnVMGetSuspendReason,(PPDMDEVINS pDevIns));
4500
4501	/**
4502	* Gets the reason for the most recent VM resume.
4503	*
4504	* @returns The resume reason. VMRESUMEREASON_INVALID is returned if no
4505	* resume has been made or if the pDevIns is invalid.
4506	* @param pDevIns The device instance.
4507	*/
4508	DECLR3CALLBACKMEMBER(VMRESUMEREASON, pfnVMGetResumeReason,(PPDMDEVINS pDevIns));
4509
4510	/**
4511	* Requests the mapping of multiple guest page into ring-3.
4512	*
4513	* When you're done with the pages, call pfnPhysBulkReleasePageMappingLocks()
4514	* ASAP to release them.
4515	*
4516	* This API will assume your intention is to write to the pages, and will
4517	* therefore replace shared and zero pages. If you do not intend to modify the
4518	* pages, use the pfnPhysBulkGCPhys2CCPtrReadOnly() API.
4519	*
4520	* @returns VBox status code.
4521	* @retval VINF_SUCCESS on success.
4522	* @retval VERR_PGM_PHYS_PAGE_RESERVED if any of the pages has no physical
4523	* backing or if any of the pages the page has any active access
4524	* handlers. The caller must fall back on using PGMR3PhysWriteExternal.
4525	* @retval VERR_PGM_INVALID_GC_PHYSICAL_ADDRESS if @a paGCPhysPages contains
4526	* an invalid physical address.
4527	*
4528	* @param pDevIns The device instance.
4529	* @param cPages Number of pages to lock.
4530	* @param paGCPhysPages The guest physical address of the pages that
4531	* should be mapped (@a cPages entries).
4532	* @param fFlags Flags reserved for future use, MBZ.
4533	* @param papvPages Where to store the ring-3 mapping addresses
4534	* corresponding to @a paGCPhysPages.
4535	* @param paLocks Where to store the locking information that
4536	* pfnPhysBulkReleasePageMappingLock needs (@a cPages
4537	* in length).
4538	*
4539	* @remark Avoid calling this API from within critical sections (other than the
4540	* PGM one) because of the deadlock risk when we have to delegating the
4541	* task to an EMT.
4542	* @thread Any.
4543	* @since 6.0.6
4544	*/
4545	DECLR3CALLBACKMEMBER(int, pfnPhysBulkGCPhys2CCPtr,(PPDMDEVINS pDevIns, uint32_t cPages, PCRTGCPHYS paGCPhysPages,
4546	uint32_t fFlags, void **papvPages, PPGMPAGEMAPLOCK paLocks));
4547
4548	/**
4549	* Requests the mapping of multiple guest page into ring-3, for reading only.
4550	*
4551	* When you're done with the pages, call pfnPhysBulkReleasePageMappingLocks()
4552	* ASAP to release them.
4553	*
4554	* @returns VBox status code.
4555	* @retval VINF_SUCCESS on success.
4556	* @retval VERR_PGM_PHYS_PAGE_RESERVED if any of the pages has no physical
4557	* backing or if any of the pages the page has an active ALL access
4558	* handler. The caller must fall back on using PGMR3PhysWriteExternal.
4559	* @retval VERR_PGM_INVALID_GC_PHYSICAL_ADDRESS if @a paGCPhysPages contains
4560	* an invalid physical address.
4561	*
4562	* @param pDevIns The device instance.
4563	* @param cPages Number of pages to lock.
4564	* @param paGCPhysPages The guest physical address of the pages that
4565	* should be mapped (@a cPages entries).
4566	* @param fFlags Flags reserved for future use, MBZ.
4567	* @param papvPages Where to store the ring-3 mapping addresses
4568	* corresponding to @a paGCPhysPages.
4569	* @param paLocks Where to store the lock information that
4570	* pfnPhysReleasePageMappingLock needs (@a cPages
4571	* in length).
4572	*
4573	* @remark Avoid calling this API from within critical sections.
4574	* @thread Any.
4575	* @since 6.0.6
4576	*/
4577	DECLR3CALLBACKMEMBER(int, pfnPhysBulkGCPhys2CCPtrReadOnly,(PPDMDEVINS pDevIns, uint32_t cPages, PCRTGCPHYS paGCPhysPages,
4578	uint32_t fFlags, void const **papvPages, PPGMPAGEMAPLOCK paLocks));
4579
4580	/**
4581	* Release the mappings of multiple guest pages.
4582	*
4583	* This is the counter part of pfnPhysBulkGCPhys2CCPtr and
4584	* pfnPhysBulkGCPhys2CCPtrReadOnly.
4585	*
4586	* @param pDevIns The device instance.
4587	* @param cPages Number of pages to unlock.
4588	* @param paLocks The lock structures initialized by the mapping
4589	* function (@a cPages in length).
4590	* @thread Any.
4591	* @since 6.0.6
4592	*/
4593	DECLR3CALLBACKMEMBER(void, pfnPhysBulkReleasePageMappingLocks,(PPDMDEVINS pDevIns, uint32_t cPages, PPGMPAGEMAPLOCK paLocks));
4594
4595	/**
4596	* Returns the architecture used for the guest.
4597	*
4598	* @returns CPU architecture enum.
4599	* @param pDevIns The device instance.
4600	*/
4601	DECLR3CALLBACKMEMBER(CPUMARCH, pfnCpuGetGuestArch,(PPDMDEVINS pDevIns));
4602
4603	/**
4604	* Returns the micro architecture used for the guest.
4605	*
4606	* @returns CPU micro architecture enum.
4607	* @param pDevIns The device instance.
4608	*/
4609	DECLR3CALLBACKMEMBER(CPUMMICROARCH, pfnCpuGetGuestMicroarch,(PPDMDEVINS pDevIns));
4610
4611	/**
4612	* Get the number of physical and linear address bits supported by the guest.
4613	*
4614	* @param pDevIns The device instance.
4615	* @param pcPhysAddrWidth Where to store the number of physical address bits
4616	* supported by the guest.
4617	* @param pcLinearAddrWidth Where to store the number of linear address bits
4618	* supported by the guest.
4619	*/
4620	DECLR3CALLBACKMEMBER(void, pfnCpuGetGuestAddrWidths,(PPDMDEVINS pDevIns, uint8_t *pcPhysAddrWidth,
4621	uint8_t *pcLinearAddrWidth));
4622
4623	/**
4624	* Gets the scalable bus frequency.
4625	*
4626	* The bus frequency is used as a base in several MSRs that gives the CPU and
4627	* other frequency ratios.
4628	*
4629	* @returns Scalable bus frequency in Hz. Will not return CPUM_SBUSFREQ_UNKNOWN.
4630	* @param pDevIns The device instance.
4631	*/
4632	DECLR3CALLBACKMEMBER(uint64_t, pfnCpuGetGuestScalableBusFrequency,(PPDMDEVINS pDevIns));
4633
4634	/** Space reserved for future members.
4635	* @{ */
4636	DECLR3CALLBACKMEMBER(void, pfnReserved1,(void));
4637	DECLR3CALLBACKMEMBER(void, pfnReserved2,(void));
4638	DECLR3CALLBACKMEMBER(void, pfnReserved3,(void));
4639	DECLR3CALLBACKMEMBER(void, pfnReserved4,(void));
4640	DECLR3CALLBACKMEMBER(void, pfnReserved5,(void));
4641	DECLR3CALLBACKMEMBER(void, pfnReserved6,(void));
4642	DECLR3CALLBACKMEMBER(void, pfnReserved7,(void));
4643	DECLR3CALLBACKMEMBER(void, pfnReserved8,(void));
4644	DECLR3CALLBACKMEMBER(void, pfnReserved9,(void));
4645	DECLR3CALLBACKMEMBER(void, pfnReserved10,(void));
4646	/** @} */
4647
4648
4649	/** API available to trusted devices only.
4650	*
4651	* These APIs are providing unrestricted access to the guest and the VM,
4652	* or they are interacting intimately with PDM.
4653	*
4654	* @{
4655	*/
4656
4657	/**
4658	* Gets the user mode VM handle. Restricted API.
4659	*
4660	* @returns User mode VM Handle.
4661	* @param pDevIns The device instance.
4662	*/
4663	DECLR3CALLBACKMEMBER(PUVM, pfnGetUVM,(PPDMDEVINS pDevIns));
4664
4665	/**
4666	* Gets the global VM handle. Restricted API.
4667	*
4668	* @returns VM Handle.
4669	* @param pDevIns The device instance.
4670	*/
4671	DECLR3CALLBACKMEMBER(PVMCC, pfnGetVM,(PPDMDEVINS pDevIns));
4672
4673	/**
4674	* Gets the VMCPU handle. Restricted API.
4675	*
4676	* @returns VMCPU Handle.
4677	* @param pDevIns The device instance.
4678	*/
4679	DECLR3CALLBACKMEMBER(PVMCPU, pfnGetVMCPU,(PPDMDEVINS pDevIns));
4680
4681	/**
4682	* The the VM CPU ID of the current thread (restricted API).
4683	*
4684	* @returns The VMCPUID of the calling thread, NIL_VMCPUID if not EMT.
4685	* @param pDevIns The device instance.
4686	*/
4687	DECLR3CALLBACKMEMBER(VMCPUID, pfnGetCurrentCpuId,(PPDMDEVINS pDevIns));
4688
4689	/**
4690	* Pokes all the EMTs.
4691	*
4692	* This is only really for VMMDevTesting.
4693	*
4694	* @param pDevIns The device instance.
4695	*/
4696	DECLR3CALLBACKMEMBER(void, pfnPokeAllEmts,(PPDMDEVINS pDevIns));
4697
4698	/**
4699	* Registers the VMM device heap or notifies about mapping/unmapping.
4700	*
4701	* This interface serves three purposes:
4702	*
4703	* -# Register the VMM device heap during device construction
4704	* for the HM to use.
4705	* -# Notify PDM/HM that it's mapped into guest address
4706	* space (i.e. usable).
4707	* -# Notify PDM/HM that it is being unmapped from the guest
4708	* address space (i.e. not usable).
4709	*
4710	* @returns VBox status code.
4711	* @param pDevIns The device instance.
4712	* @param GCPhys The physical address if mapped, NIL_RTGCPHYS if
4713	* not mapped.
4714	* @param pvHeap Ring 3 heap pointer.
4715	* @param cbHeap Size of the heap.
4716	* @thread EMT.
4717	*/
4718	DECLR3CALLBACKMEMBER(int, pfnRegisterVMMDevHeap,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTR3PTR pvHeap, unsigned cbHeap));
4719
4720	/**
4721	* Registers the firmware (BIOS, EFI) device with PDM.
4722	*
4723	* The firmware provides a callback table and gets a special PDM helper table.
4724	* There can only be one firmware device for a VM.
4725	*
4726	* @returns VBox status code.
4727	* @param pDevIns The device instance.
4728	* @param pFwReg Firmware registration structure.
4729	* @param ppFwHlp Where to return the firmware helper structure.
4730	* @remarks Only valid during device construction.
4731	* @thread EMT(0)
4732	*/
4733	DECLR3CALLBACKMEMBER(int, pfnFirmwareRegister,(PPDMDEVINS pDevIns, PCPDMFWREG pFwReg, PCPDMFWHLPR3 *ppFwHlp));
4734
4735	/**
4736	* Resets the VM.
4737	*
4738	* @returns The appropriate VBox status code to pass around on reset.
4739	* @param pDevIns The device instance.
4740	* @param fFlags PDMVMRESET_F_XXX flags.
4741	* @thread The emulation thread.
4742	*/
4743	DECLR3CALLBACKMEMBER(int, pfnVMReset,(PPDMDEVINS pDevIns, uint32_t fFlags));
4744
4745	/**
4746	* Suspends the VM.
4747	*
4748	* @returns The appropriate VBox status code to pass around on suspend.
4749	* @param pDevIns The device instance.
4750	* @thread The emulation thread.
4751	*/
4752	DECLR3CALLBACKMEMBER(int, pfnVMSuspend,(PPDMDEVINS pDevIns));
4753
4754	/**
4755	* Suspends, saves and powers off the VM.
4756	*
4757	* @returns The appropriate VBox status code to pass around.
4758	* @param pDevIns The device instance.
4759	* @thread An emulation thread.
4760	*/
4761	DECLR3CALLBACKMEMBER(int, pfnVMSuspendSaveAndPowerOff,(PPDMDEVINS pDevIns));
4762
4763	/**
4764	* Power off the VM.
4765	*
4766	* @returns The appropriate VBox status code to pass around on power off.
4767	* @param pDevIns The device instance.
4768	* @thread The emulation thread.
4769	*/
4770	DECLR3CALLBACKMEMBER(int, pfnVMPowerOff,(PPDMDEVINS pDevIns));
4771
4772	/**
4773	* Checks if the Gate A20 is enabled or not.
4774	*
4775	* @returns true if A20 is enabled.
4776	* @returns false if A20 is disabled.
4777	* @param pDevIns The device instance.
4778	* @thread The emulation thread.
4779	*/
4780	DECLR3CALLBACKMEMBER(bool, pfnA20IsEnabled,(PPDMDEVINS pDevIns));
4781
4782	/**
4783	* Enables or disables the Gate A20.
4784	*
4785	* @param pDevIns The device instance.
4786	* @param fEnable Set this flag to enable the Gate A20; clear it
4787	* to disable.
4788	* @thread The emulation thread.
4789	*/
4790	DECLR3CALLBACKMEMBER(void, pfnA20Set,(PPDMDEVINS pDevIns, bool fEnable));
4791
4792	/**
4793	* Get the specified CPUID leaf for the virtual CPU associated with the calling
4794	* thread.
4795	*
4796	* @param pDevIns The device instance.
4797	* @param iLeaf The CPUID leaf to get.
4798	* @param pEax Where to store the EAX value.
4799	* @param pEbx Where to store the EBX value.
4800	* @param pEcx Where to store the ECX value.
4801	* @param pEdx Where to store the EDX value.
4802	* @thread EMT.
4803	*/
4804	DECLR3CALLBACKMEMBER(void, pfnGetCpuId,(PPDMDEVINS pDevIns, uint32_t iLeaf, uint32_t pEax, uint32_t pEbx, uint32_t pEcx, uint32_t pEdx));
4805
4806	/**
4807	* Gets the main execution engine for the VM.
4808	*
4809	* @returns VM_EXEC_ENGINE_XXX
4810	* @param pDevIns The device instance.
4811	*/
4812	DECLR3CALLBACKMEMBER(uint8_t, pfnGetMainExecutionEngine,(PPDMDEVINS pDevIns));
4813
4814	/**
4815	* Get the current virtual clock time in a VM. The clock frequency must be
4816	* queried separately.
4817	*
4818	* @returns Current clock time.
4819	* @param pDevIns The device instance.
4820	*/
4821	DECLR3CALLBACKMEMBER(uint64_t, pfnTMTimeVirtGet,(PPDMDEVINS pDevIns));
4822
4823	/**
4824	* Get the frequency of the virtual clock.
4825	*
4826	* @returns The clock frequency (not variable at run-time).
4827	* @param pDevIns The device instance.
4828	*/
4829	DECLR3CALLBACKMEMBER(uint64_t, pfnTMTimeVirtGetFreq,(PPDMDEVINS pDevIns));
4830
4831	/**
4832	* Get the current virtual clock time in a VM, in nanoseconds.
4833	*
4834	* @returns Current clock time (in ns).
4835	* @param pDevIns The device instance.
4836	*/
4837	DECLR3CALLBACKMEMBER(uint64_t, pfnTMTimeVirtGetNano,(PPDMDEVINS pDevIns));
4838
4839	/**
4840	* Get the timestamp frequency.
4841	*
4842	* @returns Number of ticks per second.
4843	* @param pDevIns The device instance.
4844	*/
4845	DECLR3CALLBACKMEMBER(uint64_t, pfnTMCpuTicksPerSecond,(PPDMDEVINS pDevIns));
4846
4847	/**
4848	* Gets the support driver session.
4849	*
4850	* This is intended for working with the semaphore API.
4851	*
4852	* @returns Support driver session handle.
4853	* @param pDevIns The device instance.
4854	*/
4855	DECLR3CALLBACKMEMBER(PSUPDRVSESSION, pfnGetSupDrvSession,(PPDMDEVINS pDevIns));
4856
4857	/**
4858	* Queries a generic object from the VMM user.
4859	*
4860	* @returns Pointer to the object if found, NULL if not.
4861	* @param pDevIns The device instance.
4862	* @param pUuid The UUID of what's being queried. The UUIDs and
4863	* the usage conventions are defined by the user.
4864	*
4865	* @note It is strictly forbidden to call this internally in VBox! This
4866	* interface is exclusively for hacks in externally developed devices.
4867	*/
4868	DECLR3CALLBACKMEMBER(void *, pfnQueryGenericUserObject,(PPDMDEVINS pDevIns, PCRTUUID pUuid));
4869
4870	/**
4871	* Register a physical page access handler type.
4872	*
4873	* @returns VBox status code.
4874	* @param pDevIns The device instance.
4875	* @param enmKind The kind of access handler.
4876	* @param pfnHandler Pointer to the ring-3 handler callback.
4877	* @param pszDesc The type description.
4878	* @param phType Where to return the type handle (cross context safe).
4879	* @sa PDMDevHlpPGMHandlerPhysicalTypeSetUpContext
4880	*/
4881	DECLR3CALLBACKMEMBER(int, pfnPGMHandlerPhysicalTypeRegister, (PPDMDEVINS pDevIns, PGMPHYSHANDLERKIND enmKind,
4882	PFNPGMPHYSHANDLER pfnHandler,
4883	const char *pszDesc, PPGMPHYSHANDLERTYPE phType));
4884
4885	/**
4886	* Register a access handler for a physical range.
4887	*
4888	* @returns VBox status code.
4889	* @retval VINF_SUCCESS when successfully installed.
4890	* @retval VINF_PGM_GCPHYS_ALIASED when the shadow PTs could be updated because
4891	* the guest page aliased or/and mapped by multiple PTs. A CR3 sync has been
4892	* flagged together with a pool clearing.
4893	* @retval VERR_PGM_HANDLER_PHYSICAL_CONFLICT if the range conflicts with an existing
4894	* one. A debug assertion is raised.
4895	*
4896	* @param pDevIns The device instance.
4897	* @param GCPhys Start physical address.
4898	* @param GCPhysLast Last physical address. (inclusive)
4899	* @param hType The handler type registration handle.
4900	* @param pszDesc Description of this handler. If NULL, the type
4901	* description will be used instead.
4902	* @note There is no @a uUser argument, because it will be set to the pDevIns
4903	* in the context the handler is called.
4904	*/
4905	DECLR3CALLBACKMEMBER(int, pfnPGMHandlerPhysicalRegister, (PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTGCPHYS GCPhysLast,
4906	PGMPHYSHANDLERTYPE hType, R3PTRTYPE(const char *) pszDesc));
4907
4908	/**
4909	* Deregister a physical page access handler.
4910	*
4911	* @returns VBox status code.
4912	* @param pDevIns The device instance.
4913	* @param GCPhys Start physical address.
4914	*/
4915	DECLR3CALLBACKMEMBER(int, pfnPGMHandlerPhysicalDeregister,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys));
4916
4917	/**
4918	* Temporarily turns off the access monitoring of a page within a monitored
4919	* physical write/all page access handler region.
4920	*
4921	* Use this when no further \#PFs are required for that page. Be aware that
4922	* a page directory sync might reset the flags, and turn on access monitoring
4923	* for the page.
4924	*
4925	* The caller must do required page table modifications.
4926	*
4927	* @returns VBox status code.
4928	* @param pDevIns The device instance.
4929	* @param GCPhys The start address of the access handler. This
4930	* must be a fully page aligned range or we risk
4931	* messing up other handlers installed for the
4932	* start and end pages.
4933	* @param GCPhysPage The physical address of the page to turn off
4934	* access monitoring for.
4935	*/
4936	DECLR3CALLBACKMEMBER(int, pfnPGMHandlerPhysicalPageTempOff,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTGCPHYS GCPhysPage));
4937
4938	/**
4939	* Resets any modifications to individual pages in a physical page access
4940	* handler region.
4941	*
4942	* This is used in pair with PGMHandlerPhysicalPageTempOff(),
4943	* PGMHandlerPhysicalPageAliasMmio2() or PGMHandlerPhysicalPageAliasHC().
4944	*
4945	* @returns VBox status code.
4946	* @param pDevIns The device instance.
4947	* @param GCPhys The start address of the handler regions, i.e. what you
4948	* passed to PGMR3HandlerPhysicalRegister(),
4949	* PGMHandlerPhysicalRegisterEx() or
4950	* PGMHandlerPhysicalModify().
4951	*/
4952	DECLR3CALLBACKMEMBER(int, pfnPGMHandlerPhysicalReset,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys));
4953
4954	/**
4955	* Registers the guest memory range that can be used for patching.
4956	*
4957	* @returns VBox status code.
4958	* @param pDevIns The device instance.
4959	* @param GCPtrPatchMem Patch memory range.
4960	* @param cbPatchMem Size of the memory range.
4961	*/
4962	DECLR3CALLBACKMEMBER(int, pfnVMMRegisterPatchMemory, (PPDMDEVINS pDevIns, RTGCPTR GCPtrPatchMem, uint32_t cbPatchMem));
4963
4964	/**
4965	* Deregisters the guest memory range that can be used for patching.
4966	*
4967	* @returns VBox status code.
4968	* @param pDevIns The device instance.
4969	* @param GCPtrPatchMem Patch memory range.
4970	* @param cbPatchMem Size of the memory range.
4971	*/
4972	DECLR3CALLBACKMEMBER(int, pfnVMMDeregisterPatchMemory, (PPDMDEVINS pDevIns, RTGCPTR GCPtrPatchMem, uint32_t cbPatchMem));
4973
4974	/**
4975	* Registers a new shared module for the VM
4976	*
4977	* @returns VBox status code.
4978	* @param pDevIns The device instance.
4979	* @param enmGuestOS Guest OS type.
4980	* @param pszModuleName Module name.
4981	* @param pszVersion Module version.
4982	* @param GCBaseAddr Module base address.
4983	* @param cbModule Module size.
4984	* @param cRegions Number of shared region descriptors.
4985	* @param paRegions Shared region(s).
4986	*/
4987	DECLR3CALLBACKMEMBER(int, pfnSharedModuleRegister,(PPDMDEVINS pDevIns, VBOXOSFAMILY enmGuestOS, char pszModuleName, char pszVersion,
4988	RTGCPTR GCBaseAddr, uint32_t cbModule,
4989	uint32_t cRegions, VMMDEVSHAREDREGIONDESC const *paRegions));
4990
4991	/**
4992	* Unregisters a shared module for the VM
4993	*
4994	* @returns VBox status code.
4995	* @param pDevIns The device instance.
4996	* @param pszModuleName Module name.
4997	* @param pszVersion Module version.
4998	* @param GCBaseAddr Module base address.
4999	* @param cbModule Module size.
5000	*/
5001	DECLR3CALLBACKMEMBER(int, pfnSharedModuleUnregister,(PPDMDEVINS pDevIns, char pszModuleName, char pszVersion,
5002	RTGCPTR GCBaseAddr, uint32_t cbModule));
5003
5004	/**
5005	* Query the state of a page in a shared module
5006	*
5007	* @returns VBox status code.
5008	* @param pDevIns The device instance.
5009	* @param GCPtrPage Page address.
5010	* @param pfShared Shared status (out).
5011	* @param pfPageFlags Page flags (out).
5012	*/
5013	DECLR3CALLBACKMEMBER(int, pfnSharedModuleGetPageState, (PPDMDEVINS pDevIns, RTGCPTR GCPtrPage, bool pfShared, uint64_t pfPageFlags));
5014
5015	/**
5016	* Check all registered modules for changes.
5017	*
5018	* @returns VBox status code.
5019	* @param pDevIns The device instance.
5020	*/
5021	DECLR3CALLBACKMEMBER(int, pfnSharedModuleCheckAll,(PPDMDEVINS pDevIns));
5022
5023	/**
5024	* Query the interface of the top level driver on a LUN.
5025	*
5026	* @returns VBox status code.
5027	* @param pDevIns The device instance.
5028	* @param pszDevice Device name.
5029	* @param iInstance Device instance.
5030	* @param iLun The Logical Unit to obtain the interface of.
5031	* @param ppBase Where to store the base interface pointer.
5032	*
5033	* @remark We're not doing any locking ATM, so don't try call this at times when the
5034	* device chain is known to be updated.
5035	*/
5036	DECLR3CALLBACKMEMBER(int, pfnQueryLun,(PPDMDEVINS pDevIns, const char *pszDevice, unsigned iInstance, unsigned iLun, PPPDMIBASE ppBase));
5037
5038	/**
5039	* Registers the GIM device with VMM.
5040	*
5041	* @param pDevIns Pointer to the GIM device instance.
5042	* @param pDbg Pointer to the GIM device debug structure, can be
5043	* NULL.
5044	*/
5045	DECLR3CALLBACKMEMBER(void, pfnGIMDeviceRegister,(PPDMDEVINS pDevIns, PGIMDEBUG pDbg));
5046
5047	/**
5048	* Gets debug setup specified by the provider.
5049	*
5050	* @returns VBox status code.
5051	* @param pDevIns Pointer to the GIM device instance.
5052	* @param pDbgSetup Where to store the debug setup details.
5053	*/
5054	DECLR3CALLBACKMEMBER(int, pfnGIMGetDebugSetup,(PPDMDEVINS pDevIns, PGIMDEBUGSETUP pDbgSetup));
5055
5056	/**
5057	* Returns the array of MMIO2 regions that are expected to be registered and
5058	* later mapped into the guest-physical address space for the GIM provider
5059	* configured for the VM.
5060	*
5061	* @returns Pointer to an array of GIM MMIO2 regions, may return NULL.
5062	* @param pDevIns Pointer to the GIM device instance.
5063	* @param pcRegions Where to store the number of items in the array.
5064	*
5065	* @remarks The caller does not own and therefore must -NOT- try to free the
5066	* returned pointer.
5067	*/
5068	DECLR3CALLBACKMEMBER(PGIMMMIO2REGION, pfnGIMGetMmio2Regions,(PPDMDEVINS pDevIns, uint32_t *pcRegions));
5069
5070	/** @} */
5071
5072	/** Just a safety precaution. (PDM_DEVHLPR3_VERSION) */
5073	uint32_t u32TheEnd;
5074	} PDMDEVHLPR3;
5075	#endif /* !IN_RING3 \|\| DOXYGEN_RUNNING */
5076	/** Pointer to the R3 PDM Device API. */
5077	typedef R3PTRTYPE(struct PDMDEVHLPR3 *) PPDMDEVHLPR3;
5078	/** Pointer to the R3 PDM Device API, const variant. */
5079	typedef R3PTRTYPE(const struct PDMDEVHLPR3 *) PCPDMDEVHLPR3;
5080
5081
5082	/**
5083	* PDM Device API - RC Variant.
5084	*/
5085	typedef struct PDMDEVHLPRC
5086	{
5087	/** Structure version. PDM_DEVHLPRC_VERSION defines the current version. */
5088	uint32_t u32Version;
5089
5090	/**
5091	* Sets up raw-mode context callback handlers for an I/O port range.
5092	*
5093	* The range must have been registered in ring-3 first using
5094	* PDMDevHlpIoPortCreate() or PDMDevHlpIoPortCreateEx().
5095	*
5096	* @returns VBox status.
5097	* @param pDevIns The device instance to register the ports with.
5098	* @param hIoPorts The I/O port range handle.
5099	* @param pfnOut Pointer to function which is gonna handle OUT
5100	* operations. Optional.
5101	* @param pfnIn Pointer to function which is gonna handle IN operations.
5102	* Optional.
5103	* @param pfnOutStr Pointer to function which is gonna handle string OUT
5104	* operations. Optional.
5105	* @param pfnInStr Pointer to function which is gonna handle string IN
5106	* operations. Optional.
5107	* @param pvUser User argument to pass to the callbacks.
5108	*
5109	* @remarks Caller enters the device critical section prior to invoking the
5110	* registered callback methods.
5111	*
5112	* @sa PDMDevHlpIoPortCreate, PDMDevHlpIoPortCreateEx, PDMDevHlpIoPortMap,
5113	* PDMDevHlpIoPortUnmap.
5114	*/
5115	DECLRCCALLBACKMEMBER(int, pfnIoPortSetUpContextEx,(PPDMDEVINS pDevIns, IOMIOPORTHANDLE hIoPorts,
5116	PFNIOMIOPORTNEWOUT pfnOut, PFNIOMIOPORTNEWIN pfnIn,
5117	PFNIOMIOPORTNEWOUTSTRING pfnOutStr, PFNIOMIOPORTNEWINSTRING pfnInStr,
5118	void *pvUser));
5119
5120	/**
5121	* Sets up raw-mode context callback handlers for an MMIO region.
5122	*
5123	* The region must have been registered in ring-3 first using
5124	* PDMDevHlpMmioCreate() or PDMDevHlpMmioCreateEx().
5125	*
5126	* @returns VBox status.
5127	* @param pDevIns The device instance to register the ports with.
5128	* @param hRegion The MMIO region handle.
5129	* @param pfnWrite Pointer to function which is gonna handle Write
5130	* operations.
5131	* @param pfnRead Pointer to function which is gonna handle Read
5132	* operations.
5133	* @param pfnFill Pointer to function which is gonna handle Fill/memset
5134	* operations. (optional)
5135	* @param pvUser User argument to pass to the callbacks.
5136	*
5137	* @remarks Caller enters the device critical section prior to invoking the
5138	* registered callback methods.
5139	*
5140	* @sa PDMDevHlpMmioCreate, PDMDevHlpMmioCreateEx, PDMDevHlpMmioMap,
5141	* PDMDevHlpMmioUnmap.
5142	*/
5143	DECLRCCALLBACKMEMBER(int, pfnMmioSetUpContextEx,(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion, PFNIOMMMIONEWWRITE pfnWrite,
5144	PFNIOMMMIONEWREAD pfnRead, PFNIOMMMIONEWFILL pfnFill, void *pvUser));
5145
5146	/**
5147	* Sets up a raw-mode mapping for an MMIO2 region.
5148	*
5149	* The region must have been created in ring-3 first using
5150	* PDMDevHlpMmio2Create().
5151	*
5152	* @returns VBox status.
5153	* @param pDevIns The device instance to register the ports with.
5154	* @param hRegion The MMIO2 region handle.
5155	* @param offSub Start of what to map into raw-mode. Must be page aligned.
5156	* @param cbSub Number of bytes to map into raw-mode. Must be page
5157	* aligned. Zero is an alias for everything.
5158	* @param ppvMapping Where to return the mapping corresponding to @a offSub.
5159	* @thread EMT(0)
5160	* @note Only available at VM creation time.
5161	*
5162	* @sa PDMDevHlpMmio2Create().
5163	*/
5164	DECLRCCALLBACKMEMBER(int, pfnMmio2SetUpContext,(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion,
5165	size_t offSub, size_t cbSub, void **ppvMapping));
5166
5167	/**
5168	* Bus master physical memory read from the given PCI device.
5169	*
5170	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_READ_BM_DISABLED, later maybe
5171	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
5172	* @param pDevIns The device instance.
5173	* @param pPciDev The PCI device structure. If NULL the default
5174	* PCI device for this device instance is used.
5175	* @param GCPhys Physical address start reading from.
5176	* @param pvBuf Where to put the read bits.
5177	* @param cbRead How many bytes to read.
5178	* @param fFlags Combination of PDM_DEVHLP_PHYS_RW_F_XXX.
5179	* @thread Any thread, but the call may involve the emulation thread.
5180	*/
5181	DECLRCCALLBACKMEMBER(int, pfnPCIPhysRead,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys,
5182	void *pvBuf, size_t cbRead, uint32_t fFlags));
5183
5184	/**
5185	* Bus master physical memory write from the given PCI device.
5186	*
5187	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_WRITE_BM_DISABLED, later maybe
5188	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
5189	* @param pDevIns The device instance.
5190	* @param pPciDev The PCI device structure. If NULL the default
5191	* PCI device for this device instance is used.
5192	* @param GCPhys Physical address to write to.
5193	* @param pvBuf What to write.
5194	* @param cbWrite How many bytes to write.
5195	* @param fFlags Combination of PDM_DEVHLP_PHYS_RW_F_XXX.
5196	* @thread Any thread, but the call may involve the emulation thread.
5197	*/
5198	DECLRCCALLBACKMEMBER(int, pfnPCIPhysWrite,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys,
5199	const void *pvBuf, size_t cbWrite, uint32_t fFlags));
5200
5201	/**
5202	* Set the IRQ for the given PCI device.
5203	*
5204	* @param pDevIns Device instance.
5205	* @param pPciDev The PCI device structure. If NULL the default
5206	* PCI device for this device instance is used.
5207	* @param iIrq IRQ number to set.
5208	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
5209	* @thread Any thread, but will involve the emulation thread.
5210	*/
5211	DECLRCCALLBACKMEMBER(void, pfnPCISetIrq,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, int iIrq, int iLevel));
5212
5213	/**
5214	* Set ISA IRQ for a device.
5215	*
5216	* @param pDevIns Device instance.
5217	* @param iIrq IRQ number to set.
5218	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
5219	* @thread Any thread, but will involve the emulation thread.
5220	*/
5221	DECLRCCALLBACKMEMBER(void, pfnISASetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
5222
5223	/**
5224	* Read physical memory.
5225	*
5226	* @returns VINF_SUCCESS (for now).
5227	* @param pDevIns Device instance.
5228	* @param GCPhys Physical address start reading from.
5229	* @param pvBuf Where to put the read bits.
5230	* @param cbRead How many bytes to read.
5231	* @param fFlags Combination of PDM_DEVHLP_PHYS_RW_F_XXX.
5232	*/
5233	DECLRCCALLBACKMEMBER(int, pfnPhysRead,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead, uint32_t fFlags));
5234
5235	/**
5236	* Write to physical memory.
5237	*
5238	* @returns VINF_SUCCESS for now, and later maybe VERR_EM_MEMORY.
5239	* @param pDevIns Device instance.
5240	* @param GCPhys Physical address to write to.
5241	* @param pvBuf What to write.
5242	* @param cbWrite How many bytes to write.
5243	* @param fFlags Combination of PDM_DEVHLP_PHYS_RW_F_XXX.
5244	*/
5245	DECLRCCALLBACKMEMBER(int, pfnPhysWrite,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite, uint32_t fFlags));
5246
5247	/**
5248	* Checks if the Gate A20 is enabled or not.
5249	*
5250	* @returns true if A20 is enabled.
5251	* @returns false if A20 is disabled.
5252	* @param pDevIns Device instance.
5253	* @thread The emulation thread.
5254	*/
5255	DECLRCCALLBACKMEMBER(bool, pfnA20IsEnabled,(PPDMDEVINS pDevIns));
5256
5257	/**
5258	* Gets the VM state.
5259	*
5260	* @returns VM state.
5261	* @param pDevIns The device instance.
5262	* @thread Any thread (just keep in mind that it's volatile info).
5263	*/
5264	DECLRCCALLBACKMEMBER(VMSTATE, pfnVMState, (PPDMDEVINS pDevIns));
5265
5266	/**
5267	* Gets the VM handle. Restricted API.
5268	*
5269	* @returns VM Handle.
5270	* @param pDevIns Device instance.
5271	*/
5272	DECLRCCALLBACKMEMBER(PVMCC, pfnGetVM,(PPDMDEVINS pDevIns));
5273
5274	/**
5275	* Gets the VMCPU handle. Restricted API.
5276	*
5277	* @returns VMCPU Handle.
5278	* @param pDevIns The device instance.
5279	*/
5280	DECLRCCALLBACKMEMBER(PVMCPUCC, pfnGetVMCPU,(PPDMDEVINS pDevIns));
5281
5282	/**
5283	* The the VM CPU ID of the current thread (restricted API).
5284	*
5285	* @returns The VMCPUID of the calling thread, NIL_VMCPUID if not EMT.
5286	* @param pDevIns The device instance.
5287	*/
5288	DECLRCCALLBACKMEMBER(VMCPUID, pfnGetCurrentCpuId,(PPDMDEVINS pDevIns));
5289
5290	/**
5291	* Gets the main execution engine for the VM.
5292	*
5293	* @returns VM_EXEC_ENGINE_XXX
5294	* @param pDevIns The device instance.
5295	*/
5296	DECLRCCALLBACKMEMBER(uint8_t, pfnGetMainExecutionEngine,(PPDMDEVINS pDevIns));
5297
5298	/**
5299	* Get the current virtual clock time in a VM. The clock frequency must be
5300	* queried separately.
5301	*
5302	* @returns Current clock time.
5303	* @param pDevIns The device instance.
5304	*/
5305	DECLRCCALLBACKMEMBER(uint64_t, pfnTMTimeVirtGet,(PPDMDEVINS pDevIns));
5306
5307	/**
5308	* Get the frequency of the virtual clock.
5309	*
5310	* @returns The clock frequency (not variable at run-time).
5311	* @param pDevIns The device instance.
5312	*/
5313	DECLRCCALLBACKMEMBER(uint64_t, pfnTMTimeVirtGetFreq,(PPDMDEVINS pDevIns));
5314
5315	/**
5316	* Get the current virtual clock time in a VM, in nanoseconds.
5317	*
5318	* @returns Current clock time (in ns).
5319	* @param pDevIns The device instance.
5320	*/
5321	DECLRCCALLBACKMEMBER(uint64_t, pfnTMTimeVirtGetNano,(PPDMDEVINS pDevIns));
5322
5323	/**
5324	* Gets the NOP critical section.
5325	*
5326	* @returns The ring-3 address of the NOP critical section.
5327	* @param pDevIns The device instance.
5328	*/
5329	DECLRCCALLBACKMEMBER(PPDMCRITSECT, pfnCritSectGetNop,(PPDMDEVINS pDevIns));
5330
5331	/**
5332	* Changes the device level critical section from the automatically created
5333	* default to one desired by the device constructor.
5334	*
5335	* Must first be done in ring-3.
5336	*
5337	* @returns VBox status code.
5338	* @param pDevIns The device instance.
5339	* @param pCritSect The critical section to use. NULL is not
5340	* valid, instead use the NOP critical
5341	* section.
5342	*/
5343	DECLRCCALLBACKMEMBER(int, pfnSetDeviceCritSect,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect));
5344
5345	/** @name Exported PDM Critical Section Functions
5346	* @{ */
5347	DECLRCCALLBACKMEMBER(int, pfnCritSectEnter,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, int rcBusy));
5348	DECLRCCALLBACKMEMBER(int, pfnCritSectEnterDebug,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, int rcBusy, RTHCUINTPTR uId, RT_SRC_POS_DECL));
5349	DECLRCCALLBACKMEMBER(int, pfnCritSectTryEnter,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect));
5350	DECLRCCALLBACKMEMBER(int, pfnCritSectTryEnterDebug,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, RTHCUINTPTR uId, RT_SRC_POS_DECL));
5351	DECLRCCALLBACKMEMBER(int, pfnCritSectLeave,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect));
5352	DECLRCCALLBACKMEMBER(bool, pfnCritSectIsOwner,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
5353	DECLRCCALLBACKMEMBER(bool, pfnCritSectIsInitialized,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
5354	DECLRCCALLBACKMEMBER(bool, pfnCritSectHasWaiters,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
5355	DECLRCCALLBACKMEMBER(uint32_t, pfnCritSectGetRecursion,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
5356	/** @} */
5357
5358	/** @name Exported PDM Read/Write Critical Section Functions
5359	* @{ */
5360	DECLRCCALLBACKMEMBER(int, pfnCritSectRwEnterShared,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect, int rcBusy));
5361	DECLRCCALLBACKMEMBER(int, pfnCritSectRwEnterSharedDebug,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect, int rcBusy, RTHCUINTPTR uId, RT_SRC_POS_DECL));
5362	DECLRCCALLBACKMEMBER(int, pfnCritSectRwTryEnterShared,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect));
5363	DECLRCCALLBACKMEMBER(int, pfnCritSectRwTryEnterSharedDebug,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect, RTHCUINTPTR uId, RT_SRC_POS_DECL));
5364	DECLRCCALLBACKMEMBER(int, pfnCritSectRwLeaveShared,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect));
5365
5366	DECLRCCALLBACKMEMBER(int, pfnCritSectRwEnterExcl,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect, int rcBusy));
5367	DECLRCCALLBACKMEMBER(int, pfnCritSectRwEnterExclDebug,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect, int rcBusy, RTHCUINTPTR uId, RT_SRC_POS_DECL));
5368	DECLRCCALLBACKMEMBER(int, pfnCritSectRwTryEnterExcl,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect));
5369	DECLRCCALLBACKMEMBER(int, pfnCritSectRwTryEnterExclDebug,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect, RTHCUINTPTR uId, RT_SRC_POS_DECL));
5370	DECLRCCALLBACKMEMBER(int, pfnCritSectRwLeaveExcl,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect));
5371
5372	DECLRCCALLBACKMEMBER(bool, pfnCritSectRwIsWriteOwner,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect));
5373	DECLRCCALLBACKMEMBER(bool, pfnCritSectRwIsReadOwner,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect, bool fWannaHear));
5374	DECLRCCALLBACKMEMBER(uint32_t, pfnCritSectRwGetWriteRecursion,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect));
5375	DECLRCCALLBACKMEMBER(uint32_t, pfnCritSectRwGetWriterReadRecursion,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect));
5376	DECLRCCALLBACKMEMBER(uint32_t, pfnCritSectRwGetReadCount,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect));
5377	DECLRCCALLBACKMEMBER(bool, pfnCritSectRwIsInitialized,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect));
5378	/** @} */
5379
5380	/**
5381	* Gets the trace buffer handle.
5382	*
5383	* This is used by the macros found in VBox/vmm/dbgftrace.h and is not
5384	* really inteded for direct usage, thus no inline wrapper function.
5385	*
5386	* @returns Trace buffer handle or NIL_RTTRACEBUF.
5387	* @param pDevIns The device instance.
5388	*/
5389	DECLRCCALLBACKMEMBER(RTTRACEBUF, pfnDBGFTraceBuf,(PPDMDEVINS pDevIns));
5390
5391	/**
5392	* Sets up the PCI bus for the raw-mode context.
5393	*
5394	* This must be called after ring-3 has registered the PCI bus using
5395	* PDMDevHlpPCIBusRegister().
5396	*
5397	* @returns VBox status code.
5398	* @param pDevIns The device instance.
5399	* @param pPciBusReg The PCI bus registration information for raw-mode,
5400	* considered volatile.
5401	* @param ppPciHlp Where to return the raw-mode PCI bus helpers.
5402	*/
5403	DECLRCCALLBACKMEMBER(int, pfnPCIBusSetUpContext,(PPDMDEVINS pDevIns, PPDMPCIBUSREGRC pPciBusReg, PCPDMPCIHLPRC *ppPciHlp));
5404
5405	/**
5406	* Sets up the IOMMU for the raw-mode context.
5407	*
5408	* This must be called after ring-3 has registered the IOMMU using
5409	* PDMDevHlpIommuRegister().
5410	*
5411	* @returns VBox status code.
5412	* @param pDevIns The device instance.
5413	* @param pIommuReg The IOMMU registration information for raw-mode,
5414	* considered volatile.
5415	* @param ppIommuHlp Where to return the raw-mode IOMMU helpers.
5416	*/
5417	DECLRCCALLBACKMEMBER(int, pfnIommuSetUpContext,(PPDMDEVINS pDevIns, PPDMIOMMUREGRC pIommuReg, PCPDMIOMMUHLPRC *ppIommuHlp));
5418
5419	/**
5420	* Sets up the PIC for the ring-0 context.
5421	*
5422	* This must be called after ring-3 has registered the PIC using
5423	* PDMDevHlpPICRegister().
5424	*
5425	* @returns VBox status code.
5426	* @param pDevIns The device instance.
5427	* @param pPicReg The PIC registration information for ring-0,
5428	* considered volatile and copied.
5429	* @param ppPicHlp Where to return the ring-0 PIC helpers.
5430	*/
5431	DECLRCCALLBACKMEMBER(int, pfnPICSetUpContext,(PPDMDEVINS pDevIns, PPDMPICREG pPicReg, PCPDMPICHLP *ppPicHlp));
5432
5433	/**
5434	* Sets up the APIC for the raw-mode context.
5435	*
5436	* This must be called after ring-3 has registered the APIC using
5437	* PDMDevHlpIcRegister().
5438	*
5439	* @returns VBox status code.
5440	* @param pDevIns The device instance.
5441	*/
5442	DECLRCCALLBACKMEMBER(int, pfnIcSetUpContext,(PPDMDEVINS pDevIns));
5443
5444	/**
5445	* Sets up the IOAPIC for the ring-0 context.
5446	*
5447	* This must be called after ring-3 has registered the PIC using
5448	* PDMDevHlpIoApicRegister().
5449	*
5450	* @returns VBox status code.
5451	* @param pDevIns The device instance.
5452	* @param pIoApicReg The PIC registration information for ring-0,
5453	* considered volatile and copied.
5454	* @param ppIoApicHlp Where to return the ring-0 IOAPIC helpers.
5455	*/
5456	DECLRCCALLBACKMEMBER(int, pfnIoApicSetUpContext,(PPDMDEVINS pDevIns, PPDMIOAPICREG pIoApicReg, PCPDMIOAPICHLP *ppIoApicHlp));
5457
5458	/**
5459	* Sets up the HPET for the raw-mode context.
5460	*
5461	* This must be called after ring-3 has registered the PIC using
5462	* PDMDevHlpHpetRegister().
5463	*
5464	* @returns VBox status code.
5465	* @param pDevIns The device instance.
5466	* @param pHpetReg The PIC registration information for raw-mode,
5467	* considered volatile and copied.
5468	* @param ppHpetHlp Where to return the raw-mode HPET helpers.
5469	*/
5470	DECLRCCALLBACKMEMBER(int, pfnHpetSetUpContext,(PPDMDEVINS pDevIns, PPDMHPETREG pHpetReg, PCPDMHPETHLPRC *ppHpetHlp));
5471
5472	/** Space reserved for future members.
5473	* @{ */
5474	DECLRCCALLBACKMEMBER(void, pfnReserved1,(void));
5475	DECLRCCALLBACKMEMBER(void, pfnReserved2,(void));
5476	DECLRCCALLBACKMEMBER(void, pfnReserved3,(void));
5477	DECLRCCALLBACKMEMBER(void, pfnReserved4,(void));
5478	DECLRCCALLBACKMEMBER(void, pfnReserved5,(void));
5479	DECLRCCALLBACKMEMBER(void, pfnReserved6,(void));
5480	DECLRCCALLBACKMEMBER(void, pfnReserved7,(void));
5481	DECLRCCALLBACKMEMBER(void, pfnReserved8,(void));
5482	DECLRCCALLBACKMEMBER(void, pfnReserved9,(void));
5483	DECLRCCALLBACKMEMBER(void, pfnReserved10,(void));
5484	/** @} */
5485
5486	/** Just a safety precaution. */
5487	uint32_t u32TheEnd;
5488	} PDMDEVHLPRC;
5489	/** Pointer PDM Device RC API. */
5490	typedef RGPTRTYPE(struct PDMDEVHLPRC *) PPDMDEVHLPRC;
5491	/** Pointer PDM Device RC API. */
5492	typedef RGPTRTYPE(const struct PDMDEVHLPRC *) PCPDMDEVHLPRC;
5493
5494	/** Current PDMDEVHLP version number. */
5495	#define PDM_DEVHLPRC_VERSION PDM_VERSION_MAKE(0xffe6, 19, 0)
5496
5497
5498	/**
5499	* PDM Device API - R0 Variant.
5500	*/
5501	typedef struct PDMDEVHLPR0
5502	{
5503	/** Structure version. PDM_DEVHLPR0_VERSION defines the current version. */
5504	uint32_t u32Version;
5505
5506	/**
5507	* Sets up ring-0 callback handlers for an I/O port range.
5508	*
5509	* The range must have been created in ring-3 first using
5510	* PDMDevHlpIoPortCreate() or PDMDevHlpIoPortCreateEx().
5511	*
5512	* @returns VBox status.
5513	* @param pDevIns The device instance to register the ports with.
5514	* @param hIoPorts The I/O port range handle.
5515	* @param pfnOut Pointer to function which is gonna handle OUT
5516	* operations. Optional.
5517	* @param pfnIn Pointer to function which is gonna handle IN operations.
5518	* Optional.
5519	* @param pfnOutStr Pointer to function which is gonna handle string OUT
5520	* operations. Optional.
5521	* @param pfnInStr Pointer to function which is gonna handle string IN
5522	* operations. Optional.
5523	* @param pvUser User argument to pass to the callbacks.
5524	*
5525	* @remarks Caller enters the device critical section prior to invoking the
5526	* registered callback methods.
5527	*
5528	* @sa PDMDevHlpIoPortCreate(), PDMDevHlpIoPortCreateEx(),
5529	* PDMDevHlpIoPortMap(), PDMDevHlpIoPortUnmap().
5530	*/
5531	DECLR0CALLBACKMEMBER(int, pfnIoPortSetUpContextEx,(PPDMDEVINS pDevIns, IOMIOPORTHANDLE hIoPorts,
5532	PFNIOMIOPORTNEWOUT pfnOut, PFNIOMIOPORTNEWIN pfnIn,
5533	PFNIOMIOPORTNEWOUTSTRING pfnOutStr, PFNIOMIOPORTNEWINSTRING pfnInStr,
5534	void *pvUser));
5535
5536	/**
5537	* Sets up ring-0 callback handlers for an MMIO region.
5538	*
5539	* The region must have been created in ring-3 first using
5540	* PDMDevHlpMmioCreate(), PDMDevHlpMmioCreateEx(), PDMDevHlpMmioCreateAndMap(),
5541	* PDMDevHlpMmioCreateExAndMap() or PDMDevHlpPCIIORegionCreateMmio().
5542	*
5543	* @returns VBox status.
5544	* @param pDevIns The device instance to register the ports with.
5545	* @param hRegion The MMIO region handle.
5546	* @param pfnWrite Pointer to function which is gonna handle Write
5547	* operations.
5548	* @param pfnRead Pointer to function which is gonna handle Read
5549	* operations.
5550	* @param pfnFill Pointer to function which is gonna handle Fill/memset
5551	* operations. (optional)
5552	* @param pvUser User argument to pass to the callbacks.
5553	*
5554	* @remarks Caller enters the device critical section prior to invoking the
5555	* registered callback methods.
5556	*
5557	* @sa PDMDevHlpMmioCreate(), PDMDevHlpMmioCreateEx(), PDMDevHlpMmioMap(),
5558	* PDMDevHlpMmioUnmap().
5559	*/
5560	DECLR0CALLBACKMEMBER(int, pfnMmioSetUpContextEx,(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion, PFNIOMMMIONEWWRITE pfnWrite,
5561	PFNIOMMMIONEWREAD pfnRead, PFNIOMMMIONEWFILL pfnFill, void *pvUser));
5562
5563	/**
5564	* Sets up a ring-0 mapping for an MMIO2 region.
5565	*
5566	* The region must have been created in ring-3 first using
5567	* PDMDevHlpMmio2Create().
5568	*
5569	* @returns VBox status.
5570	* @param pDevIns The device instance to register the ports with.
5571	* @param hRegion The MMIO2 region handle.
5572	* @param offSub Start of what to map into ring-0. Must be page aligned.
5573	* @param cbSub Number of bytes to map into ring-0. Must be page
5574	* aligned. Zero is an alias for everything.
5575	* @param ppvMapping Where to return the mapping corresponding to @a offSub.
5576	*
5577	* @thread EMT(0)
5578	* @note Only available at VM creation time.
5579	*
5580	* @sa PDMDevHlpMmio2Create().
5581	*/
5582	DECLR0CALLBACKMEMBER(int, pfnMmio2SetUpContext,(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion, size_t offSub, size_t cbSub,
5583	void **ppvMapping));
5584
5585	/**
5586	* Bus master physical memory read from the given PCI device.
5587	*
5588	* @returns VINF_SUCCESS or VERR_PDM_NOT_PCI_BUS_MASTER, later maybe
5589	* VERR_EM_MEMORY.
5590	* @param pDevIns The device instance.
5591	* @param pPciDev The PCI device structure. If NULL the default
5592	* PCI device for this device instance is used.
5593	* @param GCPhys Physical address start reading from.
5594	* @param pvBuf Where to put the read bits.
5595	* @param cbRead How many bytes to read.
5596	* @param fFlags Combination of PDM_DEVHLP_PHYS_RW_F_XXX.
5597	* @thread Any thread, but the call may involve the emulation thread.
5598	*/
5599	DECLR0CALLBACKMEMBER(int, pfnPCIPhysRead,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys,
5600	void *pvBuf, size_t cbRead, uint32_t fFlags));
5601
5602	/**
5603	* Bus master physical memory write from the given PCI device.
5604	*
5605	* @returns VINF_SUCCESS or VERR_PDM_NOT_PCI_BUS_MASTER, later maybe
5606	* VERR_EM_MEMORY.
5607	* @param pDevIns The device instance.
5608	* @param pPciDev The PCI device structure. If NULL the default
5609	* PCI device for this device instance is used.
5610	* @param GCPhys Physical address to write to.
5611	* @param pvBuf What to write.
5612	* @param cbWrite How many bytes to write.
5613	* @param fFlags Combination of PDM_DEVHLP_PHYS_RW_F_XXX.
5614	* @thread Any thread, but the call may involve the emulation thread.
5615	*/
5616	DECLR0CALLBACKMEMBER(int, pfnPCIPhysWrite,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys,
5617	const void *pvBuf, size_t cbWrite, uint32_t fFlags));
5618
5619	/**
5620	* Set the IRQ for the given PCI device.
5621	*
5622	* @param pDevIns Device instance.
5623	* @param pPciDev The PCI device structure. If NULL the default
5624	* PCI device for this device instance is used.
5625	* @param iIrq IRQ number to set.
5626	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
5627	* @thread Any thread, but will involve the emulation thread.
5628	*/
5629	DECLR0CALLBACKMEMBER(void, pfnPCISetIrq,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, int iIrq, int iLevel));
5630
5631	/**
5632	* Set ISA IRQ for a device.
5633	*
5634	* @param pDevIns Device instance.
5635	* @param iIrq IRQ number to set.
5636	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
5637	* @thread Any thread, but will involve the emulation thread.
5638	*/
5639	DECLR0CALLBACKMEMBER(void, pfnISASetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
5640
5641	/**
5642	* Read physical memory.
5643	*
5644	* @returns VINF_SUCCESS (for now).
5645	* @param pDevIns Device instance.
5646	* @param GCPhys Physical address start reading from.
5647	* @param pvBuf Where to put the read bits.
5648	* @param cbRead How many bytes to read.
5649	* @param fFlags Combination of PDM_DEVHLP_PHYS_RW_F_XXX.
5650	*/
5651	DECLR0CALLBACKMEMBER(int, pfnPhysRead,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead, uint32_t fFlags));
5652
5653	/**
5654	* Write to physical memory.
5655	*
5656	* @returns VINF_SUCCESS for now, and later maybe VERR_EM_MEMORY.
5657	* @param pDevIns Device instance.
5658	* @param GCPhys Physical address to write to.
5659	* @param pvBuf What to write.
5660	* @param cbWrite How many bytes to write.
5661	* @param fFlags Combination of PDM_DEVHLP_PHYS_RW_F_XXX.
5662	*/
5663	DECLR0CALLBACKMEMBER(int, pfnPhysWrite,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite, uint32_t fFlags));
5664
5665	/**
5666	* Checks if the Gate A20 is enabled or not.
5667	*
5668	* @returns true if A20 is enabled.
5669	* @returns false if A20 is disabled.
5670	* @param pDevIns Device instance.
5671	* @thread The emulation thread.
5672	*/
5673	DECLR0CALLBACKMEMBER(bool, pfnA20IsEnabled,(PPDMDEVINS pDevIns));
5674
5675	/**
5676	* Gets the VM state.
5677	*
5678	* @returns VM state.
5679	* @param pDevIns The device instance.
5680	* @thread Any thread (just keep in mind that it's volatile info).
5681	*/
5682	DECLR0CALLBACKMEMBER(VMSTATE, pfnVMState, (PPDMDEVINS pDevIns));
5683
5684	/**
5685	* Gets the VM handle. Restricted API.
5686	*
5687	* @returns VM Handle.
5688	* @param pDevIns Device instance.
5689	*/
5690	DECLR0CALLBACKMEMBER(PVMCC, pfnGetVM,(PPDMDEVINS pDevIns));
5691
5692	/**
5693	* Gets the VMCPU handle. Restricted API.
5694	*
5695	* @returns VMCPU Handle.
5696	* @param pDevIns The device instance.
5697	*/
5698	DECLR0CALLBACKMEMBER(PVMCPUCC, pfnGetVMCPU,(PPDMDEVINS pDevIns));
5699
5700	/**
5701	* The the VM CPU ID of the current thread (restricted API).
5702	*
5703	* @returns The VMCPUID of the calling thread, NIL_VMCPUID if not EMT.
5704	* @param pDevIns The device instance.
5705	*/
5706	DECLR0CALLBACKMEMBER(VMCPUID, pfnGetCurrentCpuId,(PPDMDEVINS pDevIns));
5707
5708	/**
5709	* Gets the main execution engine for the VM.
5710	*
5711	* @returns VM_EXEC_ENGINE_XXX
5712	* @param pDevIns The device instance.
5713	*/
5714	DECLR0CALLBACKMEMBER(uint8_t, pfnGetMainExecutionEngine,(PPDMDEVINS pDevIns));
5715
5716	/** @name Timer handle method wrappers
5717	* @{ */
5718	DECLR0CALLBACKMEMBER(uint64_t, pfnTimerFromMicro,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMicroSecs));
5719	DECLR0CALLBACKMEMBER(uint64_t, pfnTimerFromMilli,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMilliSecs));
5720	DECLR0CALLBACKMEMBER(uint64_t, pfnTimerFromNano,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cNanoSecs));
5721	DECLR0CALLBACKMEMBER(uint64_t, pfnTimerGet,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
5722	DECLR0CALLBACKMEMBER(uint64_t, pfnTimerGetFreq,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
5723	DECLR0CALLBACKMEMBER(uint64_t, pfnTimerGetNano,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
5724	DECLR0CALLBACKMEMBER(bool, pfnTimerIsActive,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
5725	DECLR0CALLBACKMEMBER(bool, pfnTimerIsLockOwner,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
5726	DECLR0CALLBACKMEMBER(VBOXSTRICTRC, pfnTimerLockClock,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, int rcBusy));
5727	/** Takes the clock lock then enters the specified critical section. */
5728	DECLR0CALLBACKMEMBER(VBOXSTRICTRC, pfnTimerLockClock2,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, PPDMCRITSECT pCritSect, int rcBusy));
5729	DECLR0CALLBACKMEMBER(int, pfnTimerSet,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t uExpire));
5730	DECLR0CALLBACKMEMBER(int, pfnTimerSetFrequencyHint,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint32_t uHz));
5731	DECLR0CALLBACKMEMBER(int, pfnTimerSetMicro,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMicrosToNext));
5732	DECLR0CALLBACKMEMBER(int, pfnTimerSetMillies,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMilliesToNext));
5733	DECLR0CALLBACKMEMBER(int, pfnTimerSetNano,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cNanosToNext));
5734	DECLR0CALLBACKMEMBER(int, pfnTimerSetRelative,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cTicksToNext, uint64_t *pu64Now));
5735	DECLR0CALLBACKMEMBER(int, pfnTimerStop,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
5736	DECLR0CALLBACKMEMBER(void, pfnTimerUnlockClock,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
5737	DECLR0CALLBACKMEMBER(void, pfnTimerUnlockClock2,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, PPDMCRITSECT pCritSect));
5738	/** @} */
5739
5740	/**
5741	* Get the current virtual clock time in a VM. The clock frequency must be
5742	* queried separately.
5743	*
5744	* @returns Current clock time.
5745	* @param pDevIns The device instance.
5746	*/
5747	DECLR0CALLBACKMEMBER(uint64_t, pfnTMTimeVirtGet,(PPDMDEVINS pDevIns));
5748
5749	/**
5750	* Get the frequency of the virtual clock.
5751	*
5752	* @returns The clock frequency (not variable at run-time).
5753	* @param pDevIns The device instance.
5754	*/
5755	DECLR0CALLBACKMEMBER(uint64_t, pfnTMTimeVirtGetFreq,(PPDMDEVINS pDevIns));
5756
5757	/**
5758	* Get the current virtual clock time in a VM, in nanoseconds.
5759	*
5760	* @returns Current clock time (in ns).
5761	* @param pDevIns The device instance.
5762	*/
5763	DECLR0CALLBACKMEMBER(uint64_t, pfnTMTimeVirtGetNano,(PPDMDEVINS pDevIns));
5764
5765	/** @name Exported PDM Queue Functions
5766	* @{ */
5767	DECLR0CALLBACKMEMBER(PPDMQUEUEITEMCORE, pfnQueueAlloc,(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue));
5768	DECLR0CALLBACKMEMBER(int, pfnQueueInsert,(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue, PPDMQUEUEITEMCORE pItem));
5769	DECLR0CALLBACKMEMBER(bool, pfnQueueFlushIfNecessary,(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue));
5770	/** @} */
5771
5772	/** @name PDM Task
5773	* @{ */
5774	/**
5775	* Triggers the running the given task.
5776	*
5777	* @returns VBox status code.
5778	* @retval VINF_ALREADY_POSTED is the task is already pending.
5779	* @param pDevIns The device instance.
5780	* @param hTask The task to trigger.
5781	* @thread Any thread.
5782	*/
5783	DECLR0CALLBACKMEMBER(int, pfnTaskTrigger,(PPDMDEVINS pDevIns, PDMTASKHANDLE hTask));
5784	/** @} */
5785
5786	/** @name SUP Event Semaphore Wrappers (single release / auto reset)
5787	* These semaphores can be signalled from ring-0.
5788	* @{ */
5789	/** @sa SUPSemEventSignal */
5790	DECLR0CALLBACKMEMBER(int, pfnSUPSemEventSignal,(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent));
5791	/** @sa SUPSemEventWaitNoResume */
5792	DECLR0CALLBACKMEMBER(int, pfnSUPSemEventWaitNoResume,(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent, uint32_t cMillies));
5793	/** @sa SUPSemEventWaitNsAbsIntr */
5794	DECLR0CALLBACKMEMBER(int, pfnSUPSemEventWaitNsAbsIntr,(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent, uint64_t uNsTimeout));
5795	/** @sa SUPSemEventWaitNsRelIntr */
5796	DECLR0CALLBACKMEMBER(int, pfnSUPSemEventWaitNsRelIntr,(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent, uint64_t cNsTimeout));
5797	/** @sa SUPSemEventGetResolution */
5798	DECLR0CALLBACKMEMBER(uint32_t, pfnSUPSemEventGetResolution,(PPDMDEVINS pDevIns));
5799	/** @} */
5800
5801	/** @name SUP Multi Event Semaphore Wrappers (multiple release / manual reset)
5802	* These semaphores can be signalled from ring-0.
5803	* @{ */
5804	/** @sa SUPSemEventMultiSignal */
5805	DECLR0CALLBACKMEMBER(int, pfnSUPSemEventMultiSignal,(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti));
5806	/** @sa SUPSemEventMultiReset */
5807	DECLR0CALLBACKMEMBER(int, pfnSUPSemEventMultiReset,(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti));
5808	/** @sa SUPSemEventMultiWaitNoResume */
5809	DECLR0CALLBACKMEMBER(int, pfnSUPSemEventMultiWaitNoResume,(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti, uint32_t cMillies));
5810	/** @sa SUPSemEventMultiWaitNsAbsIntr */
5811	DECLR0CALLBACKMEMBER(int, pfnSUPSemEventMultiWaitNsAbsIntr,(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti, uint64_t uNsTimeout));
5812	/** @sa SUPSemEventMultiWaitNsRelIntr */
5813	DECLR0CALLBACKMEMBER(int, pfnSUPSemEventMultiWaitNsRelIntr,(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti, uint64_t cNsTimeout));
5814	/** @sa SUPSemEventMultiGetResolution */
5815	DECLR0CALLBACKMEMBER(uint32_t, pfnSUPSemEventMultiGetResolution,(PPDMDEVINS pDevIns));
5816	/** @} */
5817
5818	/**
5819	* Gets the NOP critical section.
5820	*
5821	* @returns The ring-3 address of the NOP critical section.
5822	* @param pDevIns The device instance.
5823	*/
5824	DECLR0CALLBACKMEMBER(PPDMCRITSECT, pfnCritSectGetNop,(PPDMDEVINS pDevIns));
5825
5826	/**
5827	* Changes the device level critical section from the automatically created
5828	* default to one desired by the device constructor.
5829	*
5830	* Must first be done in ring-3.
5831	*
5832	* @returns VBox status code.
5833	* @param pDevIns The device instance.
5834	* @param pCritSect The critical section to use. NULL is not
5835	* valid, instead use the NOP critical
5836	* section.
5837	*/
5838	DECLR0CALLBACKMEMBER(int, pfnSetDeviceCritSect,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect));
5839
5840	/** @name Exported PDM Critical Section Functions
5841	* @{ */
5842	DECLR0CALLBACKMEMBER(int, pfnCritSectEnter,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, int rcBusy));
5843	DECLR0CALLBACKMEMBER(int, pfnCritSectEnterDebug,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, int rcBusy, RTHCUINTPTR uId, RT_SRC_POS_DECL));
5844	DECLR0CALLBACKMEMBER(int, pfnCritSectTryEnter,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect));
5845	DECLR0CALLBACKMEMBER(int, pfnCritSectTryEnterDebug,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, RTHCUINTPTR uId, RT_SRC_POS_DECL));
5846	DECLR0CALLBACKMEMBER(int, pfnCritSectLeave,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect));
5847	DECLR0CALLBACKMEMBER(bool, pfnCritSectIsOwner,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
5848	DECLR0CALLBACKMEMBER(bool, pfnCritSectIsInitialized,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
5849	DECLR0CALLBACKMEMBER(bool, pfnCritSectHasWaiters,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
5850	DECLR0CALLBACKMEMBER(uint32_t, pfnCritSectGetRecursion,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
5851	DECLR0CALLBACKMEMBER(int, pfnCritSectScheduleExitEvent,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, SUPSEMEVENT hEventToSignal));
5852	/** @} */
5853
5854	/** @name Exported PDM Read/Write Critical Section Functions
5855	* @{ */
5856	DECLR0CALLBACKMEMBER(int, pfnCritSectRwEnterShared,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect, int rcBusy));
5857	DECLR0CALLBACKMEMBER(int, pfnCritSectRwEnterSharedDebug,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect, int rcBusy, RTHCUINTPTR uId, RT_SRC_POS_DECL));
5858	DECLR0CALLBACKMEMBER(int, pfnCritSectRwTryEnterShared,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect));
5859	DECLR0CALLBACKMEMBER(int, pfnCritSectRwTryEnterSharedDebug,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect, RTHCUINTPTR uId, RT_SRC_POS_DECL));
5860	DECLR0CALLBACKMEMBER(int, pfnCritSectRwLeaveShared,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect));
5861
5862	DECLR0CALLBACKMEMBER(int, pfnCritSectRwEnterExcl,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect, int rcBusy));
5863	DECLR0CALLBACKMEMBER(int, pfnCritSectRwEnterExclDebug,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect, int rcBusy, RTHCUINTPTR uId, RT_SRC_POS_DECL));
5864	DECLR0CALLBACKMEMBER(int, pfnCritSectRwTryEnterExcl,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect));
5865	DECLR0CALLBACKMEMBER(int, pfnCritSectRwTryEnterExclDebug,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect, RTHCUINTPTR uId, RT_SRC_POS_DECL));
5866	DECLR0CALLBACKMEMBER(int, pfnCritSectRwLeaveExcl,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect));
5867
5868	DECLR0CALLBACKMEMBER(bool, pfnCritSectRwIsWriteOwner,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect));
5869	DECLR0CALLBACKMEMBER(bool, pfnCritSectRwIsReadOwner,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect, bool fWannaHear));
5870	DECLR0CALLBACKMEMBER(uint32_t, pfnCritSectRwGetWriteRecursion,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect));
5871	DECLR0CALLBACKMEMBER(uint32_t, pfnCritSectRwGetWriterReadRecursion,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect));
5872	DECLR0CALLBACKMEMBER(uint32_t, pfnCritSectRwGetReadCount,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect));
5873	DECLR0CALLBACKMEMBER(bool, pfnCritSectRwIsInitialized,(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect));
5874	/** @} */
5875
5876	/**
5877	* Gets the trace buffer handle.
5878	*
5879	* This is used by the macros found in VBox/vmm/dbgftrace.h and is not
5880	* really inteded for direct usage, thus no inline wrapper function.
5881	*
5882	* @returns Trace buffer handle or NIL_RTTRACEBUF.
5883	* @param pDevIns The device instance.
5884	*/
5885	DECLR0CALLBACKMEMBER(RTTRACEBUF, pfnDBGFTraceBuf,(PPDMDEVINS pDevIns));
5886
5887	/**
5888	* Sets up the PCI bus for the ring-0 context.
5889	*
5890	* This must be called after ring-3 has registered the PCI bus using
5891	* PDMDevHlpPCIBusRegister().
5892	*
5893	* @returns VBox status code.
5894	* @param pDevIns The device instance.
5895	* @param pPciBusReg The PCI bus registration information for ring-0,
5896	* considered volatile and copied.
5897	* @param ppPciHlp Where to return the ring-0 PCI bus helpers.
5898	*/
5899	DECLR0CALLBACKMEMBER(int, pfnPCIBusSetUpContext,(PPDMDEVINS pDevIns, PPDMPCIBUSREGR0 pPciBusReg, PCPDMPCIHLPR0 *ppPciHlp));
5900
5901	/**
5902	* Sets up the IOMMU for the ring-0 context.
5903	*
5904	* This must be called after ring-3 has registered the IOMMU using
5905	* PDMDevHlpIommuRegister().
5906	*
5907	* @returns VBox status code.
5908	* @param pDevIns The device instance.
5909	* @param pIommuReg The IOMMU registration information for ring-0,
5910	* considered volatile and copied.
5911	* @param ppIommuHlp Where to return the ring-0 IOMMU helpers.
5912	*/
5913	DECLR0CALLBACKMEMBER(int, pfnIommuSetUpContext,(PPDMDEVINS pDevIns, PPDMIOMMUREGR0 pIommuReg, PCPDMIOMMUHLPR0 *ppIommuHlp));
5914
5915	/**
5916	* Sets up the PIC for the ring-0 context.
5917	*
5918	* This must be called after ring-3 has registered the PIC using
5919	* PDMDevHlpPICRegister().
5920	*
5921	* @returns VBox status code.
5922	* @param pDevIns The device instance.
5923	* @param pPicReg The PIC registration information for ring-0,
5924	* considered volatile and copied.
5925	* @param ppPicHlp Where to return the ring-0 PIC helpers.
5926	*/
5927	DECLR0CALLBACKMEMBER(int, pfnPICSetUpContext,(PPDMDEVINS pDevIns, PPDMPICREG pPicReg, PCPDMPICHLP *ppPicHlp));
5928
5929	/**
5930	* Sets up the APIC for the ring-0 context.
5931	*
5932	* This must be called after ring-3 has registered the APIC using
5933	* PDMDevHlpIcRegister().
5934	*
5935	* @returns VBox status code.
5936	* @param pDevIns The device instance.
5937	*/
5938	DECLR0CALLBACKMEMBER(int, pfnIcSetUpContext,(PPDMDEVINS pDevIns));
5939
5940	/**
5941	* Sets up the IOAPIC for the ring-0 context.
5942	*
5943	* This must be called after ring-3 has registered the PIC using
5944	* PDMDevHlpIoApicRegister().
5945	*
5946	* @returns VBox status code.
5947	* @param pDevIns The device instance.
5948	* @param pIoApicReg The PIC registration information for ring-0,
5949	* considered volatile and copied.
5950	* @param ppIoApicHlp Where to return the ring-0 IOAPIC helpers.
5951	*/
5952	DECLR0CALLBACKMEMBER(int, pfnIoApicSetUpContext,(PPDMDEVINS pDevIns, PPDMIOAPICREG pIoApicReg, PCPDMIOAPICHLP *ppIoApicHlp));
5953
5954	/**
5955	* Sets up the HPET for the ring-0 context.
5956	*
5957	* This must be called after ring-3 has registered the PIC using
5958	* PDMDevHlpHpetRegister().
5959	*
5960	* @returns VBox status code.
5961	* @param pDevIns The device instance.
5962	* @param pHpetReg The PIC registration information for ring-0,
5963	* considered volatile and copied.
5964	* @param ppHpetHlp Where to return the ring-0 HPET helpers.
5965	*/
5966	DECLR0CALLBACKMEMBER(int, pfnHpetSetUpContext,(PPDMDEVINS pDevIns, PPDMHPETREG pHpetReg, PCPDMHPETHLPR0 *ppHpetHlp));
5967
5968	/**
5969	* Sets up a physical page access handler type for ring-0 callbacks.
5970	*
5971	* @returns VBox status code.
5972	* @param pDevIns The device instance.
5973	* @param enmKind The kind of access handler.
5974	* @param pfnHandler Pointer to the ring-0 handler callback. NULL if
5975	* the ring-3 handler should be called.
5976	* @param pfnPfHandler The name of the ring-0 \#PF handler, NULL if the
5977	* ring-3 handler should be called.
5978	* @param pszDesc The type description.
5979	* @param hType The type handle registered in ring-3 already.
5980	* @sa PDMDevHlpPGMHandlerPhysicalTypeRegister
5981	*/
5982	DECLR0CALLBACKMEMBER(int, pfnPGMHandlerPhysicalTypeSetUpContext, (PPDMDEVINS pDevIns, PGMPHYSHANDLERKIND enmKind,
5983	PFNPGMPHYSHANDLER pfnHandler,
5984	PFNPGMRZPHYSPFHANDLER pfnPfHandler,
5985	const char *pszDesc, PGMPHYSHANDLERTYPE hType));
5986
5987	/**
5988	* Temporarily turns off the access monitoring of a page within a monitored
5989	* physical write/all page access handler region.
5990	*
5991	* Use this when no further \#PFs are required for that page. Be aware that
5992	* a page directory sync might reset the flags, and turn on access monitoring
5993	* for the page.
5994	*
5995	* The caller must do required page table modifications.
5996	*
5997	* @returns VBox status code.
5998	* @param pDevIns The device instance.
5999	* @param GCPhys The start address of the access handler. This
6000	* must be a fully page aligned range or we risk
6001	* messing up other handlers installed for the
6002	* start and end pages.
6003	* @param GCPhysPage The physical address of the page to turn off
6004	* access monitoring for.
6005	*/
6006	DECLR0CALLBACKMEMBER(int, pfnPGMHandlerPhysicalPageTempOff,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTGCPHYS GCPhysPage));
6007
6008	/**
6009	* Mapping an MMIO2 page in place of an MMIO page for direct access.
6010	*
6011	* This is a special optimization used by the VGA device. Call
6012	* PDMDevHlpMmioResetRegion() to undo the mapping.
6013	*
6014	* @returns VBox status code. This API may return VINF_SUCCESS even if no
6015	* remapping is made.
6016	* @retval VERR_SEM_BUSY in ring-0 if we cannot get the IOM lock.
6017	*
6018	* @param pDevIns The device instance @a hRegion and @a hMmio2 are
6019	* associated with.
6020	* @param hRegion The handle to the MMIO region.
6021	* @param offRegion The offset into @a hRegion of the page to be
6022	* remapped.
6023	* @param hMmio2 The MMIO2 handle.
6024	* @param offMmio2 Offset into @a hMmio2 of the page to be use for the
6025	* mapping.
6026	* @param fPageFlags Page flags to set. Must be (X86_PTE_RW \| X86_PTE_P)
6027	* for the time being.
6028	*/
6029	DECLR0CALLBACKMEMBER(int, pfnMmioMapMmio2Page,(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion, RTGCPHYS offRegion,
6030	uint64_t hMmio2, RTGCPHYS offMmio2, uint64_t fPageFlags));
6031
6032	/**
6033	* Reset a previously modified MMIO region; restore the access flags.
6034	*
6035	* This undoes the effects of PDMDevHlpMmioMapMmio2Page() and is currently only
6036	* intended for some ancient VGA hack. However, it would be great to extend it
6037	* beyond VT-x and/or nested-paging.
6038	*
6039	* @returns VBox status code.
6040	*
6041	* @param pDevIns The device instance @a hRegion is associated with.
6042	* @param hRegion The handle to the MMIO region.
6043	*/
6044	DECLR0CALLBACKMEMBER(int, pfnMmioResetRegion, (PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion));
6045
6046	/**
6047	* Returns the array of MMIO2 regions that are expected to be registered and
6048	* later mapped into the guest-physical address space for the GIM provider
6049	* configured for the VM.
6050	*
6051	* @returns Pointer to an array of GIM MMIO2 regions, may return NULL.
6052	* @param pDevIns Pointer to the GIM device instance.
6053	* @param pcRegions Where to store the number of items in the array.
6054	*
6055	* @remarks The caller does not own and therefore must -NOT- try to free the
6056	* returned pointer.
6057	*/
6058	DECLR0CALLBACKMEMBER(PGIMMMIO2REGION, pfnGIMGetMmio2Regions,(PPDMDEVINS pDevIns, uint32_t *pcRegions));
6059
6060	/** Space reserved for future members.
6061	* @{ */
6062	DECLR0CALLBACKMEMBER(void, pfnReserved1,(void));
6063	DECLR0CALLBACKMEMBER(void, pfnReserved2,(void));
6064	DECLR0CALLBACKMEMBER(void, pfnReserved3,(void));
6065	DECLR0CALLBACKMEMBER(void, pfnReserved4,(void));
6066	DECLR0CALLBACKMEMBER(void, pfnReserved5,(void));
6067	DECLR0CALLBACKMEMBER(void, pfnReserved6,(void));
6068	DECLR0CALLBACKMEMBER(void, pfnReserved7,(void));
6069	DECLR0CALLBACKMEMBER(void, pfnReserved8,(void));
6070	DECLR0CALLBACKMEMBER(void, pfnReserved9,(void));
6071	DECLR0CALLBACKMEMBER(void, pfnReserved10,(void));
6072	/** @} */
6073
6074	/** Just a safety precaution. */
6075	uint32_t u32TheEnd;
6076	} PDMDEVHLPR0;
6077	/** Pointer PDM Device R0 API. */
6078	typedef R0PTRTYPE(struct PDMDEVHLPR0 *) PPDMDEVHLPR0;
6079	/** Pointer PDM Device GC API. */
6080	typedef R0PTRTYPE(const struct PDMDEVHLPR0 *) PCPDMDEVHLPR0;
6081
6082	/** Current PDMDEVHLP version number. */
6083	#define PDM_DEVHLPR0_VERSION PDM_VERSION_MAKE(0xffe5, 27, 0)
6084
6085
6086	/**
6087	* PDM Device Instance.
6088	*/
6089	typedef struct PDMDEVINSR3
6090	{
6091	/** Structure version. PDM_DEVINSR3_VERSION defines the current version. */
6092	uint32_t u32Version;
6093	/** Device instance number. */
6094	uint32_t iInstance;
6095	/** Size of the ring-3, raw-mode and shared bits. */
6096	uint32_t cbRing3;
6097	/** Set if ring-0 context is enabled. */
6098	bool fR0Enabled;
6099	/** Set if raw-mode context is enabled. */
6100	bool fRCEnabled;
6101	/** Alignment padding. */
6102	bool afReserved[2];
6103	/** Pointer the HC PDM Device API. */
6104	PCPDMDEVHLPR3 pHlpR3;
6105	/** Pointer to the shared device instance data. */
6106	RTR3PTR pvInstanceDataR3;
6107	/** Pointer to the device instance data for ring-3. */
6108	RTR3PTR pvInstanceDataForR3;
6109	/** The critical section for the device.
6110	*
6111	* TM and IOM will enter this critical section before calling into the device
6112	* code. PDM will when doing power on, power off, reset, suspend and resume
6113	* notifications. SSM will currently not, but this will be changed later on.
6114	*
6115	* The device gets a critical section automatically assigned to it before
6116	* the constructor is called. If the constructor wishes to use a different
6117	* critical section, it calls PDMDevHlpSetDeviceCritSect() to change it
6118	* very early on.
6119	*/
6120	R3PTRTYPE(PPDMCRITSECT) pCritSectRoR3;
6121	/** Pointer to device registration structure. */
6122	R3PTRTYPE(PCPDMDEVREG) pReg;
6123	/** Configuration handle. */
6124	R3PTRTYPE(PCFGMNODE) pCfg;
6125	/** The base interface of the device.
6126	*
6127	* The device constructor initializes this if it has any
6128	* device level interfaces to export. To obtain this interface
6129	* call PDMR3QueryDevice(). */
6130	PDMIBASE IBase;
6131
6132	/** Tracing indicator. */
6133	uint32_t fTracing;
6134	/** The tracing ID of this device. */
6135	uint32_t idTracing;
6136
6137	/** Ring-3 pointer to the raw-mode device instance. */
6138	R3PTRTYPE(struct PDMDEVINSRC *) pDevInsForRCR3;
6139	/** Raw-mode address of the raw-mode device instance. */
6140	RTRGPTR pDevInsForRC;
6141	/** Ring-3 pointer to the raw-mode instance data. */
6142	RTR3PTR pvInstanceDataForRCR3;
6143
6144	/** PCI device structure size. */
6145	uint32_t cbPciDev;
6146	/** Number of PCI devices in apPciDevs. */
6147	uint32_t cPciDevs;
6148	/** Pointer to the PCI devices for this device.
6149	* (Allocated after the shared instance data.)
6150	* @note If we want to extend this beyond 8 sub-functions/devices, those 1 or
6151	* two devices ever needing it can use cbPciDev and do the address
6152	* calculations that for entries 8+. */
6153	R3PTRTYPE(struct PDMPCIDEV *) apPciDevs[8];
6154
6155	/** Temporarily. */
6156	R0PTRTYPE(struct PDMDEVINSR0 *) pDevInsR0RemoveMe;
6157	/** Temporarily. */
6158	RTR0PTR pvInstanceDataR0;
6159	/** Temporarily. */
6160	RTRCPTR pvInstanceDataRC;
6161	/** Align the internal data more naturally. */
6162	uint32_t au32Padding[HC_ARCH_BITS == 32 ? 13 : 11];
6163
6164	/** Internal data. */
6165	union
6166	{
6167	#ifdef PDMDEVINSINT_DECLARED
6168	PDMDEVINSINTR3 s;
6169	#endif
6170	uint8_t padding[HC_ARCH_BITS == 32 ? 0x40 : 0x90];
6171	} Internal;
6172
6173	/** Device instance data for ring-3. The size of this area is defined
6174	* in the PDMDEVREG::cbInstanceR3 field. */
6175	char achInstanceData[8];
6176	} PDMDEVINSR3;
6177
6178	/** Current PDMDEVINSR3 version number. */
6179	#define PDM_DEVINSR3_VERSION PDM_VERSION_MAKE(0xff82, 4, 0)
6180
6181	/** Converts a pointer to the PDMDEVINSR3::IBase to a pointer to PDMDEVINS. */
6182	#define PDMIBASE_2_PDMDEV(pInterface) ( (PPDMDEVINS)((char *)(pInterface) - RT_UOFFSETOF(PDMDEVINS, IBase)) )
6183
6184
6185	/**
6186	* PDM ring-0 device instance.
6187	*/
6188	typedef struct PDMDEVINSR0
6189	{
6190	/** Structure version. PDM_DEVINSR0_VERSION defines the current version. */
6191	uint32_t u32Version;
6192	/** Device instance number. */
6193	uint32_t iInstance;
6194
6195	/** Pointer the HC PDM Device API. */
6196	PCPDMDEVHLPR0 pHlpR0;
6197	/** Pointer to the shared device instance data. */
6198	RTR0PTR pvInstanceDataR0;
6199	/** Pointer to the device instance data for ring-0. */
6200	RTR0PTR pvInstanceDataForR0;
6201	/** The critical section for the device.
6202	*
6203	* TM and IOM will enter this critical section before calling into the device
6204	* code. PDM will when doing power on, power off, reset, suspend and resume
6205	* notifications. SSM will currently not, but this will be changed later on.
6206	*
6207	* The device gets a critical section automatically assigned to it before
6208	* the constructor is called. If the constructor wishes to use a different
6209	* critical section, it calls PDMDevHlpSetDeviceCritSect() to change it
6210	* very early on.
6211	*/
6212	R0PTRTYPE(PPDMCRITSECT) pCritSectRoR0;
6213	/** Pointer to the ring-0 device registration structure. */
6214	R0PTRTYPE(PCPDMDEVREGR0) pReg;
6215	/** Ring-3 address of the ring-3 device instance. */
6216	R3PTRTYPE(struct PDMDEVINSR3 *) pDevInsForR3;
6217	/** Ring-0 pointer to the ring-3 device instance. */
6218	R0PTRTYPE(struct PDMDEVINSR3 *) pDevInsForR3R0;
6219	/** Ring-0 pointer to the ring-3 instance data. */
6220	RTR0PTR pvInstanceDataForR3R0;
6221	/** Raw-mode address of the raw-mode device instance. */
6222	RGPTRTYPE(struct PDMDEVINSRC *) pDevInsForRC;
6223	/** Ring-0 pointer to the raw-mode device instance. */
6224	R0PTRTYPE(struct PDMDEVINSRC *) pDevInsForRCR0;
6225	/** Ring-0 pointer to the raw-mode instance data. */
6226	RTR0PTR pvInstanceDataForRCR0;
6227
6228	/** PCI device structure size. */
6229	uint32_t cbPciDev;
6230	/** Number of PCI devices in apPciDevs. */
6231	uint32_t cPciDevs;
6232	/** Pointer to the PCI devices for this device.
6233	* (Allocated after the shared instance data.)
6234	* @note If we want to extend this beyond 8 sub-functions/devices, those 1 or
6235	* two devices ever needing it can use cbPciDev and do the address
6236	* calculations that for entries 8+. */
6237	R0PTRTYPE(struct PDMPCIDEV *) apPciDevs[8];
6238
6239	/** Align the internal data more naturally. */
6240	uint32_t au32Padding[HC_ARCH_BITS == 32 ? 3 : 2 + 4];
6241
6242	/** Internal data. */
6243	union
6244	{
6245	#ifdef PDMDEVINSINT_DECLARED
6246	PDMDEVINSINTR0 s;
6247	#endif
6248	uint8_t padding[HC_ARCH_BITS == 32 ? 0x40 : 0x80];
6249	} Internal;
6250
6251	/** Device instance data for ring-0. The size of this area is defined
6252	* in the PDMDEVREG::cbInstanceR0 field. */
6253	char achInstanceData[8];
6254	} PDMDEVINSR0;
6255
6256	/** Current PDMDEVINSR0 version number. */
6257	#define PDM_DEVINSR0_VERSION PDM_VERSION_MAKE(0xff83, 4, 0)
6258
6259
6260	/**
6261	* PDM raw-mode device instance.
6262	*/
6263	typedef struct PDMDEVINSRC
6264	{
6265	/** Structure version. PDM_DEVINSRC_VERSION defines the current version. */
6266	uint32_t u32Version;
6267	/** Device instance number. */
6268	uint32_t iInstance;
6269
6270	/** Pointer the HC PDM Device API. */
6271	PCPDMDEVHLPRC pHlpRC;
6272	/** Pointer to the shared device instance data. */
6273	RTRGPTR pvInstanceDataRC;
6274	/** Pointer to the device instance data for raw-mode. */
6275	RTRGPTR pvInstanceDataForRC;
6276	/** The critical section for the device.
6277	*
6278	* TM and IOM will enter this critical section before calling into the device
6279	* code. PDM will when doing power on, power off, reset, suspend and resume
6280	* notifications. SSM will currently not, but this will be changed later on.
6281	*
6282	* The device gets a critical section automatically assigned to it before
6283	* the constructor is called. If the constructor wishes to use a different
6284	* critical section, it calls PDMDevHlpSetDeviceCritSect() to change it
6285	* very early on.
6286	*/
6287	RGPTRTYPE(PPDMCRITSECT) pCritSectRoRC;
6288	/** Pointer to the raw-mode device registration structure. */
6289	RGPTRTYPE(PCPDMDEVREGRC) pReg;
6290
6291	/** PCI device structure size. */
6292	uint32_t cbPciDev;
6293	/** Number of PCI devices in apPciDevs. */
6294	uint32_t cPciDevs;
6295	/** Pointer to the PCI devices for this device.
6296	* (Allocated after the shared instance data.) */
6297	RGPTRTYPE(struct PDMPCIDEV *) apPciDevs[8];
6298
6299	/** Align the internal data more naturally. */
6300	uint32_t au32Padding[14];
6301
6302	/** Internal data. */
6303	union
6304	{
6305	#ifdef PDMDEVINSINT_DECLARED
6306	PDMDEVINSINTRC s;
6307	#endif
6308	uint8_t padding[0x10];
6309	} Internal;
6310
6311	/** Device instance data for ring-0. The size of this area is defined
6312	* in the PDMDEVREG::cbInstanceR0 field. */
6313	char achInstanceData[8];
6314	} PDMDEVINSRC;
6315
6316	/** Current PDMDEVINSR0 version number. */
6317	#define PDM_DEVINSRC_VERSION PDM_VERSION_MAKE(0xff84, 4, 0)
6318
6319
6320	/** @def PDM_DEVINS_VERSION
6321	* Current PDMDEVINS version number. */
6322	/** @typedef PDMDEVINS
6323	* The device instance structure for the current context. */
6324	#ifdef IN_RING3
6325	# define PDM_DEVINS_VERSION PDM_DEVINSR3_VERSION
6326	typedef PDMDEVINSR3 PDMDEVINS;
6327	#elif defined(IN_RING0)
6328	# define PDM_DEVINS_VERSION PDM_DEVINSR0_VERSION
6329	typedef PDMDEVINSR0 PDMDEVINS;
6330	#elif defined(IN_RC)
6331	# define PDM_DEVINS_VERSION PDM_DEVINSRC_VERSION
6332	typedef PDMDEVINSRC PDMDEVINS;
6333	#else
6334	# error "Missing context defines: IN_RING0, IN_RING3, IN_RC"
6335	#endif
6336
6337	/**
6338	* Get the pointer to an PCI device.
6339	* @note Returns NULL if @a a_idxPciDev is out of bounds.
6340	*/
6341	#define PDMDEV_GET_PPCIDEV(a_pDevIns, a_idxPciDev) \
6342	( (uintptr_t)(a_idxPciDev) < RT_ELEMENTS((a_pDevIns)->apPciDevs) ? (a_pDevIns)->apPciDevs[(uintptr_t)(a_idxPciDev)] \
6343	: PDMDEV_CALC_PPCIDEV(a_pDevIns, a_idxPciDev) )
6344
6345	/**
6346	* Calc the pointer to of a given PCI device.
6347	* @note Returns NULL if @a a_idxPciDev is out of bounds.
6348	*/
6349	#define PDMDEV_CALC_PPCIDEV(a_pDevIns, a_idxPciDev) \
6350	( (uintptr_t)(a_idxPciDev) < (a_pDevIns)->cPciDevs \
6351	? (PPDMPCIDEV)((uint8_t )((a_pDevIns)->apPciDevs[0]) + (a_pDevIns->cbPciDev) (uintptr_t)(a_idxPciDev)) \
6352	: (PPDMPCIDEV)NULL )
6353
6354
6355	/**
6356	* Checks the structure versions of the device instance and device helpers,
6357	* returning if they are incompatible.
6358	*
6359	* This is for use in the constructor.
6360	*
6361	* @param pDevIns The device instance pointer.
6362	*/
6363	#define PDMDEV_CHECK_VERSIONS_RETURN(pDevIns) \
6364	do \
6365	{ \
6366	PPDMDEVINS pDevInsTypeCheck = (pDevIns); NOREF(pDevInsTypeCheck); \
6367	AssertLogRelMsgReturn(PDM_VERSION_ARE_COMPATIBLE((pDevIns)->u32Version, PDM_DEVINS_VERSION), \
6368	("DevIns=%#x mine=%#x\n", (pDevIns)->u32Version, PDM_DEVINS_VERSION), \
6369	VERR_PDM_DEVINS_VERSION_MISMATCH); \
6370	AssertLogRelMsgReturn(PDM_VERSION_ARE_COMPATIBLE((pDevIns)->CTX_SUFF(pHlp)->u32Version, CTX_MID(PDM_DEVHLP,_VERSION)), \
6371	("DevHlp=%#x mine=%#x\n", (pDevIns)->CTX_SUFF(pHlp)->u32Version, CTX_MID(PDM_DEVHLP,_VERSION)), \
6372	VERR_PDM_DEVHLP_VERSION_MISMATCH); \
6373	} while (0)
6374
6375	/**
6376	* Quietly checks the structure versions of the device instance and device
6377	* helpers, returning if they are incompatible.
6378	*
6379	* This is for use in the destructor.
6380	*
6381	* @param pDevIns The device instance pointer.
6382	*/
6383	#define PDMDEV_CHECK_VERSIONS_RETURN_QUIET(pDevIns) \
6384	do \
6385	{ \
6386	PPDMDEVINS pDevInsTypeCheck = (pDevIns); NOREF(pDevInsTypeCheck); \
6387	if (RT_LIKELY(PDM_VERSION_ARE_COMPATIBLE((pDevIns)->u32Version, PDM_DEVINS_VERSION) )) \
6388	{ /* likely */ } else return VERR_PDM_DEVINS_VERSION_MISMATCH; \
6389	if (RT_LIKELY(PDM_VERSION_ARE_COMPATIBLE((pDevIns)->CTX_SUFF(pHlp)->u32Version, CTX_MID(PDM_DEVHLP,_VERSION)) )) \
6390	{ /* likely */ } else return VERR_PDM_DEVHLP_VERSION_MISMATCH; \
6391	} while (0)
6392
6393	/**
6394	* Wrapper around CFGMR3ValidateConfig for the root config for use in the
6395	* constructor - returns on failure.
6396	*
6397	* This should be invoked after having initialized the instance data
6398	* sufficiently for the correct operation of the destructor. The destructor is
6399	* always called!
6400	*
6401	* @param pDevIns Pointer to the PDM device instance.
6402	* @param pszValidValues Patterns describing the valid value names. See
6403	* RTStrSimplePatternMultiMatch for details on the
6404	* pattern syntax.
6405	* @param pszValidNodes Patterns describing the valid node (key) names.
6406	* Pass empty string if no valid nodes.
6407	*/
6408	#define PDMDEV_VALIDATE_CONFIG_RETURN(pDevIns, pszValidValues, pszValidNodes) \
6409	do \
6410	{ \
6411	int rcValCfg = pDevIns->pHlpR3->pfnCFGMValidateConfig((pDevIns)->pCfg, "/", pszValidValues, pszValidNodes, \
6412	(pDevIns)->pReg->szName, (pDevIns)->iInstance); \
6413	if (RT_SUCCESS(rcValCfg)) \
6414	{ /* likely */ } else return rcValCfg; \
6415	} while (0)
6416
6417	/** @def PDMDEV_ASSERT_EMT
6418	* Assert that the current thread is the emulation thread.
6419	*/
6420	#ifdef VBOX_STRICT
6421	# define PDMDEV_ASSERT_EMT(pDevIns) pDevIns->pHlpR3->pfnAssertEMT(pDevIns, __FILE__, __LINE__, __FUNCTION__)
6422	#else
6423	# define PDMDEV_ASSERT_EMT(pDevIns) do { } while (0)
6424	#endif
6425
6426	/** @def PDMDEV_ASSERT_OTHER
6427	* Assert that the current thread is NOT the emulation thread.
6428	*/
6429	#ifdef VBOX_STRICT
6430	# define PDMDEV_ASSERT_OTHER(pDevIns) pDevIns->pHlpR3->pfnAssertOther(pDevIns, __FILE__, __LINE__, __FUNCTION__)
6431	#else
6432	# define PDMDEV_ASSERT_OTHER(pDevIns) do { } while (0)
6433	#endif
6434
6435	/** @def PDMDEV_ASSERT_VMLOCK_OWNER
6436	* Assert that the current thread is owner of the VM lock.
6437	*/
6438	#ifdef VBOX_STRICT
6439	# define PDMDEV_ASSERT_VMLOCK_OWNER(pDevIns) pDevIns->pHlpR3->pfnAssertVMLock(pDevIns, __FILE__, __LINE__, __FUNCTION__)
6440	#else
6441	# define PDMDEV_ASSERT_VMLOCK_OWNER(pDevIns) do { } while (0)
6442	#endif
6443
6444	/** @def PDMDEV_SET_ERROR
6445	* Set the VM error. See PDMDevHlpVMSetError() for printf like message formatting.
6446	*/
6447	#define PDMDEV_SET_ERROR(pDevIns, rc, pszError) \
6448	PDMDevHlpVMSetError(pDevIns, rc, RT_SRC_POS, "%s", pszError)
6449
6450	/** @def PDMDEV_SET_RUNTIME_ERROR
6451	* Set the VM runtime error. See PDMDevHlpVMSetRuntimeError() for printf like message formatting.
6452	*/
6453	#define PDMDEV_SET_RUNTIME_ERROR(pDevIns, fFlags, pszErrorId, pszError) \
6454	PDMDevHlpVMSetRuntimeError(pDevIns, fFlags, pszErrorId, "%s", pszError)
6455
6456	/** @def PDMDEVINS_2_RCPTR
6457	* Converts a PDM Device instance pointer to a RC PDM Device instance pointer.
6458	*/
6459	#ifdef IN_RC
6460	# define PDMDEVINS_2_RCPTR(pDevIns) (pDevIns)
6461	#else
6462	# define PDMDEVINS_2_RCPTR(pDevIns) ( (pDevIns)->pDevInsForRC )
6463	#endif
6464
6465	/** @def PDMDEVINS_2_R3PTR
6466	* Converts a PDM Device instance pointer to a R3 PDM Device instance pointer.
6467	*/
6468	#ifdef IN_RING3
6469	# define PDMDEVINS_2_R3PTR(pDevIns) (pDevIns)
6470	#else
6471	# define PDMDEVINS_2_R3PTR(pDevIns) ( (pDevIns)->pDevInsForR3 )
6472	#endif
6473
6474	/** @def PDMDEVINS_2_R0PTR
6475	* Converts a PDM Device instance pointer to a R0 PDM Device instance pointer.
6476	*/
6477	#ifdef IN_RING0
6478	# define PDMDEVINS_2_R0PTR(pDevIns) (pDevIns)
6479	#else
6480	# define PDMDEVINS_2_R0PTR(pDevIns) ( (pDevIns)->pDevInsR0RemoveMe )
6481	#endif
6482
6483	/** @def PDMDEVINS_DATA_2_R0_REMOVE_ME
6484	* Converts a PDM device instance data pointer to a ring-0 one.
6485	* @deprecated
6486	*/
6487	#ifdef IN_RING0
6488	# define PDMDEVINS_DATA_2_R0_REMOVE_ME(pDevIns, pvCC) (pvCC)
6489	#else
6490	# define PDMDEVINS_DATA_2_R0_REMOVE_ME(pDevIns, pvCC) ( (pDevIns)->pvInstanceDataR0 + (uintptr_t)(pvCC) - (uintptr_t)(pDevIns)->CTX_SUFF(pvInstanceData) )
6491	#endif
6492
6493
6494	/** @def PDMDEVINS_2_DATA
6495	* This is a safer edition of PDMINS_2_DATA that checks that the size of the
6496	* target type is same as PDMDEVREG::cbInstanceShared in strict builds.
6497	*
6498	* @note Do no use this macro in common code working on a core structure which
6499	* device specific code has expanded.
6500	*/
6501	#if defined(VBOX_STRICT) && defined(RT_COMPILER_SUPPORTS_LAMBDA)
6502	# define PDMDEVINS_2_DATA(a_pDevIns, a_PtrType) \
6503	([](PPDMDEVINS a_pLambdaDevIns) -> a_PtrType \
6504	{ \
6505	a_PtrType pLambdaRet = (a_PtrType)(a_pLambdaDevIns)->CTX_SUFF(pvInstanceData); \
6506	Assert(sizeof(*pLambdaRet) == a_pLambdaDevIns->pReg->cbInstanceShared); \
6507	return pLambdaRet; \
6508	}(a_pDevIns))
6509	#else
6510	# define PDMDEVINS_2_DATA(a_pDevIns, a_PtrType) ( (a_PtrType)(a_pDevIns)->CTX_SUFF(pvInstanceData) )
6511	#endif
6512
6513	/** @def PDMDEVINS_2_DATA_CC
6514	* This is a safer edition of PDMINS_2_DATA_CC that checks that the size of the
6515	* target type is same as PDMDEVREG::cbInstanceCC in strict builds.
6516	*
6517	* @note Do no use this macro in common code working on a core structure which
6518	* device specific code has expanded.
6519	*/
6520	#if defined(VBOX_STRICT) && defined(RT_COMPILER_SUPPORTS_LAMBDA)
6521	# define PDMDEVINS_2_DATA_CC(a_pDevIns, a_PtrType) \
6522	([](PPDMDEVINS a_pLambdaDevIns) -> a_PtrType \
6523	{ \
6524	a_PtrType pLambdaRet = (a_PtrType)&(a_pLambdaDevIns)->achInstanceData[0]; \
6525	Assert(sizeof(*pLambdaRet) == a_pLambdaDevIns->pReg->cbInstanceCC); \
6526	return pLambdaRet; \
6527	}(a_pDevIns))
6528	#else
6529	# define PDMDEVINS_2_DATA_CC(a_pDevIns, a_PtrType) ( (a_PtrType)(void *)&(a_pDevIns)->achInstanceData[0] )
6530	#endif
6531
6532
6533	#ifdef IN_RING3
6534
6535	/**
6536	* Combines PDMDevHlpIoPortCreate() & PDMDevHlpIoPortMap().
6537	*/
6538	DECLINLINE(int) PDMDevHlpIoPortCreateAndMap(PPDMDEVINS pDevIns, RTIOPORT Port, RTIOPORT cPorts, PFNIOMIOPORTNEWOUT pfnOut,
6539	PFNIOMIOPORTNEWIN pfnIn, const char *pszDesc, PCIOMIOPORTDESC paExtDescs,
6540	PIOMIOPORTHANDLE phIoPorts)
6541	{
6542	int rc = pDevIns->pHlpR3->pfnIoPortCreateEx(pDevIns, cPorts, 0, NULL, UINT32_MAX,
6543	pfnOut, pfnIn, NULL, NULL, NULL, pszDesc, paExtDescs, phIoPorts);
6544	if (RT_SUCCESS(rc))
6545	rc = pDevIns->pHlpR3->pfnIoPortMap(pDevIns, *phIoPorts, Port);
6546	return rc;
6547	}
6548
6549	/**
6550	* Combines PDMDevHlpIoPortCreate() & PDMDevHlpIoPortMap(), but with pvUser.
6551	*/
6552	DECLINLINE(int) PDMDevHlpIoPortCreateUAndMap(PPDMDEVINS pDevIns, RTIOPORT Port, RTIOPORT cPorts, PFNIOMIOPORTNEWOUT pfnOut,
6553	PFNIOMIOPORTNEWIN pfnIn, void *pvUser,
6554	const char *pszDesc, PCIOMIOPORTDESC paExtDescs, PIOMIOPORTHANDLE phIoPorts)
6555	{
6556	int rc = pDevIns->pHlpR3->pfnIoPortCreateEx(pDevIns, cPorts, 0, NULL, UINT32_MAX,
6557	pfnOut, pfnIn, NULL, NULL, pvUser, pszDesc, paExtDescs, phIoPorts);
6558	if (RT_SUCCESS(rc))
6559	rc = pDevIns->pHlpR3->pfnIoPortMap(pDevIns, *phIoPorts, Port);
6560	return rc;
6561	}
6562
6563	/**
6564	* Combines PDMDevHlpIoPortCreate() & PDMDevHlpIoPortMap(), but with flags.
6565	*/
6566	DECLINLINE(int) PDMDevHlpIoPortCreateFlagsAndMap(PPDMDEVINS pDevIns, RTIOPORT Port, RTIOPORT cPorts, uint32_t fFlags,
6567	PFNIOMIOPORTNEWOUT pfnOut, PFNIOMIOPORTNEWIN pfnIn,
6568	const char *pszDesc, PCIOMIOPORTDESC paExtDescs, PIOMIOPORTHANDLE phIoPorts)
6569	{
6570	int rc = pDevIns->pHlpR3->pfnIoPortCreateEx(pDevIns, cPorts, fFlags, NULL, UINT32_MAX,
6571	pfnOut, pfnIn, NULL, NULL, NULL, pszDesc, paExtDescs, phIoPorts);
6572	if (RT_SUCCESS(rc))
6573	rc = pDevIns->pHlpR3->pfnIoPortMap(pDevIns, *phIoPorts, Port);
6574	return rc;
6575	}
6576
6577	/**
6578	* Combines PDMDevHlpIoPortCreateEx() & PDMDevHlpIoPortMap().
6579	*/
6580	DECLINLINE(int) PDMDevHlpIoPortCreateExAndMap(PPDMDEVINS pDevIns, RTIOPORT Port, RTIOPORT cPorts, uint32_t fFlags,
6581	PFNIOMIOPORTNEWOUT pfnOut, PFNIOMIOPORTNEWIN pfnIn,
6582	PFNIOMIOPORTNEWOUTSTRING pfnOutStr, PFNIOMIOPORTNEWINSTRING pfnInStr, void *pvUser,
6583	const char *pszDesc, PCIOMIOPORTDESC paExtDescs, PIOMIOPORTHANDLE phIoPorts)
6584	{
6585	int rc = pDevIns->pHlpR3->pfnIoPortCreateEx(pDevIns, cPorts, fFlags, NULL, UINT32_MAX,
6586	pfnOut, pfnIn, pfnOutStr, pfnInStr, pvUser, pszDesc, paExtDescs, phIoPorts);
6587	if (RT_SUCCESS(rc))
6588	rc = pDevIns->pHlpR3->pfnIoPortMap(pDevIns, *phIoPorts, Port);
6589	return rc;
6590	}
6591
6592	/**
6593	* @sa PDMDevHlpIoPortCreateEx
6594	*/
6595	DECLINLINE(int) PDMDevHlpIoPortCreate(PPDMDEVINS pDevIns, RTIOPORT cPorts, PPDMPCIDEV pPciDev, uint32_t iPciRegion,
6596	PFNIOMIOPORTNEWOUT pfnOut, PFNIOMIOPORTNEWIN pfnIn, void pvUser, const char pszDesc,
6597	PCIOMIOPORTDESC paExtDescs, PIOMIOPORTHANDLE phIoPorts)
6598	{
6599	return pDevIns->pHlpR3->pfnIoPortCreateEx(pDevIns, cPorts, 0, pPciDev, iPciRegion,
6600	pfnOut, pfnIn, NULL, NULL, pvUser, pszDesc, paExtDescs, phIoPorts);
6601	}
6602
6603
6604	/**
6605	* @sa PDMDevHlpIoPortCreateEx
6606	*/
6607	DECLINLINE(int) PDMDevHlpIoPortCreateIsa(PPDMDEVINS pDevIns, RTIOPORT cPorts, PFNIOMIOPORTNEWOUT pfnOut,
6608	PFNIOMIOPORTNEWIN pfnIn, void pvUser, const char pszDesc,
6609	PCIOMIOPORTDESC paExtDescs, PIOMIOPORTHANDLE phIoPorts)
6610	{
6611	return pDevIns->pHlpR3->pfnIoPortCreateEx(pDevIns, cPorts, 0, NULL, UINT32_MAX,
6612	pfnOut, pfnIn, NULL, NULL, pvUser, pszDesc, paExtDescs, phIoPorts);
6613	}
6614
6615	/**
6616	* @copydoc PDMDEVHLPR3::pfnIoPortCreateEx
6617	*/
6618	DECLINLINE(int) PDMDevHlpIoPortCreateEx(PPDMDEVINS pDevIns, RTIOPORT cPorts, uint32_t fFlags, PPDMPCIDEV pPciDev,
6619	uint32_t iPciRegion, PFNIOMIOPORTNEWOUT pfnOut, PFNIOMIOPORTNEWIN pfnIn,
6620	PFNIOMIOPORTNEWOUTSTRING pfnOutStr, PFNIOMIOPORTNEWINSTRING pfnInStr, void *pvUser,
6621	const char *pszDesc, PCIOMIOPORTDESC paExtDescs, PIOMIOPORTHANDLE phIoPorts)
6622	{
6623	return pDevIns->pHlpR3->pfnIoPortCreateEx(pDevIns, cPorts, fFlags, pPciDev, iPciRegion,
6624	pfnOut, pfnIn, pfnOutStr, pfnInStr, pvUser, pszDesc, paExtDescs, phIoPorts);
6625	}
6626
6627	/**
6628	* @copydoc PDMDEVHLPR3::pfnIoPortMap
6629	*/
6630	DECLINLINE(int) PDMDevHlpIoPortMap(PPDMDEVINS pDevIns, IOMIOPORTHANDLE hIoPorts, RTIOPORT Port)
6631	{
6632	return pDevIns->pHlpR3->pfnIoPortMap(pDevIns, hIoPorts, Port);
6633	}
6634
6635	/**
6636	* @copydoc PDMDEVHLPR3::pfnIoPortUnmap
6637	*/
6638	DECLINLINE(int) PDMDevHlpIoPortUnmap(PPDMDEVINS pDevIns, IOMIOPORTHANDLE hIoPorts)
6639	{
6640	return pDevIns->pHlpR3->pfnIoPortUnmap(pDevIns, hIoPorts);
6641	}
6642
6643	/**
6644	* @copydoc PDMDEVHLPR3::pfnIoPortGetMappingAddress
6645	*/
6646	DECLINLINE(uint32_t) PDMDevHlpIoPortGetMappingAddress(PPDMDEVINS pDevIns, IOMIOPORTHANDLE hIoPorts)
6647	{
6648	return pDevIns->pHlpR3->pfnIoPortGetMappingAddress(pDevIns, hIoPorts);
6649	}
6650
6651	/**
6652	* @copydoc PDMDEVHLPR3::pfnIoPortRead
6653	*/
6654	DECLINLINE(VBOXSTRICTRC) PDMDevHlpIoPortRead(PPDMDEVINS pDevIns, RTIOPORT Port, uint32_t *pu32Value, size_t cbValue)
6655	{
6656	return pDevIns->pHlpR3->pfnIoPortRead(pDevIns, Port, pu32Value, cbValue);
6657	}
6658
6659	/**
6660	* @copydoc PDMDEVHLPR3::pfnIoPortWrite
6661	*/
6662	DECLINLINE(VBOXSTRICTRC) PDMDevHlpIoPortWrite(PPDMDEVINS pDevIns, RTIOPORT Port, uint32_t u32Value, size_t cbValue)
6663	{
6664	return pDevIns->pHlpR3->pfnIoPortWrite(pDevIns, Port, u32Value, cbValue);
6665	}
6666
6667
6668	#endif /* IN_RING3 */
6669	#if !defined(IN_RING3) \|\| defined(DOXYGEN_RUNNING)
6670
6671	/**
6672	* @sa PDMDevHlpIoPortSetUpContextEx
6673	*/
6674	DECLINLINE(int) PDMDevHlpIoPortSetUpContext(PPDMDEVINS pDevIns, IOMIOPORTHANDLE hIoPorts,
6675	PFNIOMIOPORTNEWOUT pfnOut, PFNIOMIOPORTNEWIN pfnIn, void *pvUser)
6676	{
6677	return pDevIns->CTX_SUFF(pHlp)->pfnIoPortSetUpContextEx(pDevIns, hIoPorts, pfnOut, pfnIn, NULL, NULL, pvUser);
6678	}
6679
6680	/**
6681	* @copydoc PDMDEVHLPR0::pfnIoPortSetUpContextEx
6682	*/
6683	DECLINLINE(int) PDMDevHlpIoPortSetUpContextEx(PPDMDEVINS pDevIns, IOMIOPORTHANDLE hIoPorts,
6684	PFNIOMIOPORTNEWOUT pfnOut, PFNIOMIOPORTNEWIN pfnIn,
6685	PFNIOMIOPORTNEWOUTSTRING pfnOutStr, PFNIOMIOPORTNEWINSTRING pfnInStr, void *pvUser)
6686	{
6687	return pDevIns->CTX_SUFF(pHlp)->pfnIoPortSetUpContextEx(pDevIns, hIoPorts, pfnOut, pfnIn, pfnOutStr, pfnInStr, pvUser);
6688	}
6689
6690	#endif /* !IN_RING3 \|\| DOXYGEN_RUNNING */
6691	#ifdef IN_RING3
6692
6693	/**
6694	* @sa PDMDevHlpMmioCreateEx
6695	*/
6696	DECLINLINE(int) PDMDevHlpMmioCreate(PPDMDEVINS pDevIns, RTGCPHYS cbRegion, PPDMPCIDEV pPciDev, uint32_t iPciRegion,
6697	PFNIOMMMIONEWWRITE pfnWrite, PFNIOMMMIONEWREAD pfnRead, void *pvUser,
6698	uint32_t fFlags, const char *pszDesc, PIOMMMIOHANDLE phRegion)
6699	{
6700	return pDevIns->pHlpR3->pfnMmioCreateEx(pDevIns, cbRegion, fFlags, pPciDev, iPciRegion,
6701	pfnWrite, pfnRead, NULL, pvUser, pszDesc, phRegion);
6702	}
6703
6704	/**
6705	* @copydoc PDMDEVHLPR3::pfnMmioCreateEx
6706	*/
6707	DECLINLINE(int) PDMDevHlpMmioCreateEx(PPDMDEVINS pDevIns, RTGCPHYS cbRegion,
6708	uint32_t fFlags, PPDMPCIDEV pPciDev, uint32_t iPciRegion,
6709	PFNIOMMMIONEWWRITE pfnWrite, PFNIOMMMIONEWREAD pfnRead, PFNIOMMMIONEWFILL pfnFill,
6710	void pvUser, const char pszDesc, PIOMMMIOHANDLE phRegion)
6711	{
6712	return pDevIns->pHlpR3->pfnMmioCreateEx(pDevIns, cbRegion, fFlags, pPciDev, iPciRegion,
6713	pfnWrite, pfnRead, pfnFill, pvUser, pszDesc, phRegion);
6714	}
6715
6716	/**
6717	* @sa PDMDevHlpMmioCreate and PDMDevHlpMmioMap
6718	*/
6719	DECLINLINE(int) PDMDevHlpMmioCreateAndMap(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTGCPHYS cbRegion,
6720	PFNIOMMMIONEWWRITE pfnWrite, PFNIOMMMIONEWREAD pfnRead,
6721	uint32_t fFlags, const char *pszDesc, PIOMMMIOHANDLE phRegion)
6722	{
6723	int rc = pDevIns->pHlpR3->pfnMmioCreateEx(pDevIns, cbRegion, fFlags, NULL /pPciDev/, UINT32_MAX /iPciRegion/,
6724	pfnWrite, pfnRead, NULL /pfnFill/, NULL /pvUser/, pszDesc, phRegion);
6725	if (RT_SUCCESS(rc))
6726	rc = pDevIns->pHlpR3->pfnMmioMap(pDevIns, *phRegion, GCPhys);
6727	return rc;
6728	}
6729
6730	/**
6731	* @sa PDMDevHlpMmioCreateEx and PDMDevHlpMmioMap
6732	*/
6733	DECLINLINE(int) PDMDevHlpMmioCreateExAndMap(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTGCPHYS cbRegion, uint32_t fFlags,
6734	PPDMPCIDEV pPciDev, uint32_t iPciRegion, PFNIOMMMIONEWWRITE pfnWrite,
6735	PFNIOMMMIONEWREAD pfnRead, PFNIOMMMIONEWFILL pfnFill, void *pvUser,
6736	const char *pszDesc, PIOMMMIOHANDLE phRegion)
6737	{
6738	int rc = pDevIns->pHlpR3->pfnMmioCreateEx(pDevIns, cbRegion, fFlags, pPciDev, iPciRegion,
6739	pfnWrite, pfnRead, pfnFill, pvUser, pszDesc, phRegion);
6740	if (RT_SUCCESS(rc))
6741	rc = pDevIns->pHlpR3->pfnMmioMap(pDevIns, *phRegion, GCPhys);
6742	return rc;
6743	}
6744
6745	/**
6746	* @copydoc PDMDEVHLPR3::pfnMmioMap
6747	*/
6748	DECLINLINE(int) PDMDevHlpMmioMap(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion, RTGCPHYS GCPhys)
6749	{
6750	return pDevIns->pHlpR3->pfnMmioMap(pDevIns, hRegion, GCPhys);
6751	}
6752
6753	/**
6754	* @copydoc PDMDEVHLPR3::pfnMmioUnmap
6755	*/
6756	DECLINLINE(int) PDMDevHlpMmioUnmap(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion)
6757	{
6758	return pDevIns->pHlpR3->pfnMmioUnmap(pDevIns, hRegion);
6759	}
6760
6761	/**
6762	* @copydoc PDMDEVHLPR3::pfnMmioReduce
6763	*/
6764	DECLINLINE(int) PDMDevHlpMmioReduce(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion, RTGCPHYS cbRegion)
6765	{
6766	return pDevIns->pHlpR3->pfnMmioReduce(pDevIns, hRegion, cbRegion);
6767	}
6768
6769	/**
6770	* @copydoc PDMDEVHLPR3::pfnMmioGetMappingAddress
6771	*/
6772	DECLINLINE(RTGCPHYS) PDMDevHlpMmioGetMappingAddress(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion)
6773	{
6774	return pDevIns->pHlpR3->pfnMmioGetMappingAddress(pDevIns, hRegion);
6775	}
6776
6777	#endif /* IN_RING3 */
6778	#if !defined(IN_RING3) \|\| defined(DOXYGEN_RUNNING)
6779
6780	/**
6781	* @sa PDMDevHlpMmioSetUpContextEx
6782	*/
6783	DECLINLINE(int) PDMDevHlpMmioSetUpContext(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion,
6784	PFNIOMMMIONEWWRITE pfnWrite, PFNIOMMMIONEWREAD pfnRead, void *pvUser)
6785	{
6786	return pDevIns->CTX_SUFF(pHlp)->pfnMmioSetUpContextEx(pDevIns, hRegion, pfnWrite, pfnRead, NULL, pvUser);
6787	}
6788
6789	/**
6790	* @copydoc PDMDEVHLPR0::pfnMmioSetUpContextEx
6791	*/
6792	DECLINLINE(int) PDMDevHlpMmioSetUpContextEx(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion, PFNIOMMMIONEWWRITE pfnWrite,
6793	PFNIOMMMIONEWREAD pfnRead, PFNIOMMMIONEWFILL pfnFill, void *pvUser)
6794	{
6795	return pDevIns->CTX_SUFF(pHlp)->pfnMmioSetUpContextEx(pDevIns, hRegion, pfnWrite, pfnRead, pfnFill, pvUser);
6796	}
6797
6798	#endif /* !IN_RING3 \|\| DOXYGEN_RUNNING */
6799	#ifdef IN_RING3
6800
6801	/**
6802	* @copydoc PDMDEVHLPR3::pfnMmio2Create
6803	*/
6804	DECLINLINE(int) PDMDevHlpMmio2Create(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t iPciRegion, RTGCPHYS cbRegion,
6805	uint32_t fFlags, const char pszDesc, void *ppvMapping, PPGMMMIO2HANDLE phRegion)
6806	{
6807	return pDevIns->pHlpR3->pfnMmio2Create(pDevIns, pPciDev, iPciRegion, cbRegion, fFlags, pszDesc, ppvMapping, phRegion);
6808	}
6809
6810	/**
6811	* @copydoc PDMDEVHLPR3::pfnMmio2Map
6812	*/
6813	DECLINLINE(int) PDMDevHlpMmio2Map(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion, RTGCPHYS GCPhys)
6814	{
6815	return pDevIns->pHlpR3->pfnMmio2Map(pDevIns, hRegion, GCPhys);
6816	}
6817
6818	/**
6819	* @copydoc PDMDEVHLPR3::pfnMmio2Unmap
6820	*/
6821	DECLINLINE(int) PDMDevHlpMmio2Unmap(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion)
6822	{
6823	return pDevIns->pHlpR3->pfnMmio2Unmap(pDevIns, hRegion);
6824	}
6825
6826	/**
6827	* @copydoc PDMDEVHLPR3::pfnMmio2Reduce
6828	*/
6829	DECLINLINE(int) PDMDevHlpMmio2Reduce(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion, RTGCPHYS cbRegion)
6830	{
6831	return pDevIns->pHlpR3->pfnMmio2Reduce(pDevIns, hRegion, cbRegion);
6832	}
6833
6834	/**
6835	* @copydoc PDMDEVHLPR3::pfnMmio2GetMappingAddress
6836	*/
6837	DECLINLINE(RTGCPHYS) PDMDevHlpMmio2GetMappingAddress(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion)
6838	{
6839	return pDevIns->pHlpR3->pfnMmio2GetMappingAddress(pDevIns, hRegion);
6840	}
6841
6842	/**
6843	* @copydoc PDMDEVHLPR3::pfnMmio2QueryAndResetDirtyBitmap
6844	*/
6845	DECLINLINE(int) PDMDevHlpMmio2QueryAndResetDirtyBitmap(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion,
6846	void *pvBitmap, size_t cbBitmap)
6847	{
6848	return pDevIns->pHlpR3->pfnMmio2QueryAndResetDirtyBitmap(pDevIns, hRegion, pvBitmap, cbBitmap);
6849	}
6850
6851	/**
6852	* Reset the dirty bitmap tracking for an MMIO2 region.
6853	*
6854	* The MMIO2 region must have been created with the
6855	* PGMPHYS_MMIO2_FLAGS_TRACK_DIRTY_PAGES flag for this to work.
6856	*
6857	* @returns VBox status code.
6858	* @param pDevIns The device instance.
6859	* @param hRegion The MMIO2 region handle.
6860	*/
6861	DECLINLINE(int) PDMDevHlpMmio2ResetDirtyBitmap(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion)
6862	{
6863	return pDevIns->pHlpR3->pfnMmio2QueryAndResetDirtyBitmap(pDevIns, hRegion, NULL, 0);
6864	}
6865
6866	/**
6867	* @copydoc PDMDEVHLPR3::pfnMmio2ControlDirtyPageTracking
6868	*/
6869	DECLINLINE(int) PDMDevHlpMmio2ControlDirtyPageTracking(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion, bool fEnabled)
6870	{
6871	return pDevIns->pHlpR3->pfnMmio2ControlDirtyPageTracking(pDevIns, hRegion, fEnabled);
6872	}
6873
6874	#endif /* IN_RING3 */
6875
6876	/**
6877	* @copydoc PDMDEVHLPR3::pfnMmioMapMmio2Page
6878	*/
6879	DECLINLINE(int) PDMDevHlpMmioMapMmio2Page(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion, RTGCPHYS offRegion,
6880	uint64_t hMmio2, RTGCPHYS offMmio2, uint64_t fPageFlags)
6881	{
6882	return pDevIns->CTX_SUFF(pHlp)->pfnMmioMapMmio2Page(pDevIns, hRegion, offRegion, hMmio2, offMmio2, fPageFlags);
6883	}
6884
6885	/**
6886	* @copydoc PDMDEVHLPR3::pfnMmioResetRegion
6887	*/
6888	DECLINLINE(int) PDMDevHlpMmioResetRegion(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion)
6889	{
6890	return pDevIns->CTX_SUFF(pHlp)->pfnMmioResetRegion(pDevIns, hRegion);
6891	}
6892
6893	#if !defined(IN_RING3) \|\| defined(DOXYGEN_RUNNING)
6894
6895	/**
6896	* @copydoc PDMDEVHLPR0::pfnMmio2SetUpContext
6897	*/
6898	DECLINLINE(int) PDMDevHlpMmio2SetUpContext(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion,
6899	size_t offSub, size_t cbSub, void **ppvMapping)
6900	{
6901	return pDevIns->CTX_SUFF(pHlp)->pfnMmio2SetUpContext(pDevIns, hRegion, offSub, cbSub, ppvMapping);
6902	}
6903
6904	#endif /* !IN_RING3 \|\| DOXYGEN_RUNNING */
6905	#ifdef IN_RING3
6906
6907	/**
6908	* @copydoc PDMDEVHLPR3::pfnROMRegister
6909	*/
6910	DECLINLINE(int) PDMDevHlpROMRegister(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, uint32_t cbRange,
6911	const void pvBinary, uint32_t cbBinary, uint32_t fFlags, const char pszDesc)
6912	{
6913	return pDevIns->pHlpR3->pfnROMRegister(pDevIns, GCPhysStart, cbRange, pvBinary, cbBinary, fFlags, pszDesc);
6914	}
6915
6916	/**
6917	* @copydoc PDMDEVHLPR3::pfnROMProtectShadow
6918	*/
6919	DECLINLINE(int) PDMDevHlpROMProtectShadow(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, uint32_t cbRange, PGMROMPROT enmProt)
6920	{
6921	return pDevIns->pHlpR3->pfnROMProtectShadow(pDevIns, GCPhysStart, cbRange, enmProt);
6922	}
6923
6924	/**
6925	* Register a save state data unit.
6926	*
6927	* @returns VBox status.
6928	* @param pDevIns The device instance.
6929	* @param uVersion Data layout version number.
6930	* @param cbGuess The approximate amount of data in the unit.
6931	* Only for progress indicators.
6932	* @param pfnSaveExec Execute save callback, optional.
6933	* @param pfnLoadExec Execute load callback, optional.
6934	*/
6935	DECLINLINE(int) PDMDevHlpSSMRegister(PPDMDEVINS pDevIns, uint32_t uVersion, size_t cbGuess,
6936	PFNSSMDEVSAVEEXEC pfnSaveExec, PFNSSMDEVLOADEXEC pfnLoadExec)
6937	{
6938	return pDevIns->pHlpR3->pfnSSMRegister(pDevIns, uVersion, cbGuess, NULL /pszBefore/,
6939	NULL /pfnLivePrep/, NULL /pfnLiveExec/, NULL /pfnLiveDone/,
6940	NULL /pfnSavePrep/, pfnSaveExec, NULL /pfnSaveDone/,
6941	NULL /pfnLoadPrep/, pfnLoadExec, NULL /pfnLoadDone/);
6942	}
6943
6944	/**
6945	* Register a save state data unit with a live save callback as well.
6946	*
6947	* @returns VBox status.
6948	* @param pDevIns The device instance.
6949	* @param uVersion Data layout version number.
6950	* @param cbGuess The approximate amount of data in the unit.
6951	* Only for progress indicators.
6952	* @param pfnLiveExec Execute live callback, optional.
6953	* @param pfnSaveExec Execute save callback, optional.
6954	* @param pfnLoadExec Execute load callback, optional.
6955	*/
6956	DECLINLINE(int) PDMDevHlpSSMRegister3(PPDMDEVINS pDevIns, uint32_t uVersion, size_t cbGuess,
6957	PFNSSMDEVLIVEEXEC pfnLiveExec, PFNSSMDEVSAVEEXEC pfnSaveExec, PFNSSMDEVLOADEXEC pfnLoadExec)
6958	{
6959	return pDevIns->pHlpR3->pfnSSMRegister(pDevIns, uVersion, cbGuess, NULL /pszBefore/,
6960	NULL /pfnLivePrep/, pfnLiveExec, NULL /pfnLiveDone/,
6961	NULL /pfnSavePrep/, pfnSaveExec, NULL /pfnSaveDone/,
6962	NULL /pfnLoadPrep/, pfnLoadExec, NULL /pfnLoadDone/);
6963	}
6964
6965	/**
6966	* @copydoc PDMDEVHLPR3::pfnSSMRegister
6967	*/
6968	DECLINLINE(int) PDMDevHlpSSMRegisterEx(PPDMDEVINS pDevIns, uint32_t uVersion, size_t cbGuess, const char *pszBefore,
6969	PFNSSMDEVLIVEPREP pfnLivePrep, PFNSSMDEVLIVEEXEC pfnLiveExec, PFNSSMDEVLIVEVOTE pfnLiveVote,
6970	PFNSSMDEVSAVEPREP pfnSavePrep, PFNSSMDEVSAVEEXEC pfnSaveExec, PFNSSMDEVSAVEDONE pfnSaveDone,
6971	PFNSSMDEVLOADPREP pfnLoadPrep, PFNSSMDEVLOADEXEC pfnLoadExec, PFNSSMDEVLOADDONE pfnLoadDone)
6972	{
6973	return pDevIns->pHlpR3->pfnSSMRegister(pDevIns, uVersion, cbGuess, pszBefore,
6974	pfnLivePrep, pfnLiveExec, pfnLiveVote,
6975	pfnSavePrep, pfnSaveExec, pfnSaveDone,
6976	pfnLoadPrep, pfnLoadExec, pfnLoadDone);
6977	}
6978
6979	/**
6980	* @copydoc PDMDEVHLPR3::pfnSSMRegisterLegacy
6981	*/
6982	DECLINLINE(int) PDMDevHlpSSMRegisterLegacy(PPDMDEVINS pDevIns, const char *pszOldName, PFNSSMDEVLOADPREP pfnLoadPrep,
6983	PFNSSMDEVLOADEXEC pfnLoadExec, PFNSSMDEVLOADDONE pfnLoadDone)
6984	{
6985	return pDevIns->pHlpR3->pfnSSMRegisterLegacy(pDevIns, pszOldName, pfnLoadPrep, pfnLoadExec, pfnLoadDone);
6986	}
6987
6988	/**
6989	* @copydoc PDMDEVHLPR3::pfnTimerCreate
6990	*/
6991	DECLINLINE(int) PDMDevHlpTimerCreate(PPDMDEVINS pDevIns, TMCLOCK enmClock, PFNTMTIMERDEV pfnCallback, void *pvUser,
6992	uint32_t fFlags, const char *pszDesc, PTMTIMERHANDLE phTimer)
6993	{
6994	return pDevIns->pHlpR3->pfnTimerCreate(pDevIns, enmClock, pfnCallback, pvUser, fFlags, pszDesc, phTimer);
6995	}
6996
6997	#endif /* IN_RING3 */
6998
6999	/**
7000	* @copydoc PDMDEVHLPR3::pfnTimerFromMicro
7001	*/
7002	DECLINLINE(uint64_t) PDMDevHlpTimerFromMicro(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMicroSecs)
7003	{
7004	return pDevIns->CTX_SUFF(pHlp)->pfnTimerFromMicro(pDevIns, hTimer, cMicroSecs);
7005	}
7006
7007	/**
7008	* @copydoc PDMDEVHLPR3::pfnTimerFromMilli
7009	*/
7010	DECLINLINE(uint64_t) PDMDevHlpTimerFromMilli(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMilliSecs)
7011	{
7012	return pDevIns->CTX_SUFF(pHlp)->pfnTimerFromMilli(pDevIns, hTimer, cMilliSecs);
7013	}
7014
7015	/**
7016	* @copydoc PDMDEVHLPR3::pfnTimerFromNano
7017	*/
7018	DECLINLINE(uint64_t) PDMDevHlpTimerFromNano(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cNanoSecs)
7019	{
7020	return pDevIns->CTX_SUFF(pHlp)->pfnTimerFromNano(pDevIns, hTimer, cNanoSecs);
7021	}
7022
7023	/**
7024	* @copydoc PDMDEVHLPR3::pfnTimerGet
7025	*/
7026	DECLINLINE(uint64_t) PDMDevHlpTimerGet(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer)
7027	{
7028	return pDevIns->CTX_SUFF(pHlp)->pfnTimerGet(pDevIns, hTimer);
7029	}
7030
7031	/**
7032	* @copydoc PDMDEVHLPR3::pfnTimerGetFreq
7033	*/
7034	DECLINLINE(uint64_t) PDMDevHlpTimerGetFreq(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer)
7035	{
7036	return pDevIns->CTX_SUFF(pHlp)->pfnTimerGetFreq(pDevIns, hTimer);
7037	}
7038
7039	/**
7040	* @copydoc PDMDEVHLPR3::pfnTimerGetNano
7041	*/
7042	DECLINLINE(uint64_t) PDMDevHlpTimerGetNano(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer)
7043	{
7044	return pDevIns->CTX_SUFF(pHlp)->pfnTimerGetNano(pDevIns, hTimer);
7045	}
7046
7047	/**
7048	* @copydoc PDMDEVHLPR3::pfnTimerIsActive
7049	*/
7050	DECLINLINE(bool) PDMDevHlpTimerIsActive(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer)
7051	{
7052	return pDevIns->CTX_SUFF(pHlp)->pfnTimerIsActive(pDevIns, hTimer);
7053	}
7054
7055	/**
7056	* @copydoc PDMDEVHLPR3::pfnTimerIsLockOwner
7057	*/
7058	DECLINLINE(bool) PDMDevHlpTimerIsLockOwner(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer)
7059	{
7060	return pDevIns->CTX_SUFF(pHlp)->pfnTimerIsLockOwner(pDevIns, hTimer);
7061	}
7062
7063	/**
7064	* @copydoc PDMDEVHLPR3::pfnTimerLockClock
7065	*/
7066	DECLINLINE(VBOXSTRICTRC) PDMDevHlpTimerLockClock(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, int rcBusy)
7067	{
7068	return pDevIns->CTX_SUFF(pHlp)->pfnTimerLockClock(pDevIns, hTimer, rcBusy);
7069	}
7070
7071	/**
7072	* @copydoc PDMDEVHLPR3::pfnTimerLockClock2
7073	*/
7074	DECLINLINE(VBOXSTRICTRC) PDMDevHlpTimerLockClock2(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, PPDMCRITSECT pCritSect, int rcBusy)
7075	{
7076	return pDevIns->CTX_SUFF(pHlp)->pfnTimerLockClock2(pDevIns, hTimer, pCritSect, rcBusy);
7077	}
7078
7079	/**
7080	* @copydoc PDMDEVHLPR3::pfnTimerSet
7081	*/
7082	DECLINLINE(int) PDMDevHlpTimerSet(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t uExpire)
7083	{
7084	return pDevIns->CTX_SUFF(pHlp)->pfnTimerSet(pDevIns, hTimer, uExpire);
7085	}
7086
7087	/**
7088	* @copydoc PDMDEVHLPR3::pfnTimerSetFrequencyHint
7089	*/
7090	DECLINLINE(int) PDMDevHlpTimerSetFrequencyHint(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint32_t uHz)
7091	{
7092	return pDevIns->CTX_SUFF(pHlp)->pfnTimerSetFrequencyHint(pDevIns, hTimer, uHz);
7093	}
7094
7095	/**
7096	* @copydoc PDMDEVHLPR3::pfnTimerSetMicro
7097	*/
7098	DECLINLINE(int) PDMDevHlpTimerSetMicro(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMicrosToNext)
7099	{
7100	return pDevIns->CTX_SUFF(pHlp)->pfnTimerSetMicro(pDevIns, hTimer, cMicrosToNext);
7101	}
7102
7103	/**
7104	* @copydoc PDMDEVHLPR3::pfnTimerSetMillies
7105	*/
7106	DECLINLINE(int) PDMDevHlpTimerSetMillies(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMilliesToNext)
7107	{
7108	return pDevIns->CTX_SUFF(pHlp)->pfnTimerSetMillies(pDevIns, hTimer, cMilliesToNext);
7109	}
7110
7111	/**
7112	* @copydoc PDMDEVHLPR3::pfnTimerSetNano
7113	*/
7114	DECLINLINE(int) PDMDevHlpTimerSetNano(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cNanosToNext)
7115	{
7116	return pDevIns->CTX_SUFF(pHlp)->pfnTimerSetNano(pDevIns, hTimer, cNanosToNext);
7117	}
7118
7119	/**
7120	* @copydoc PDMDEVHLPR3::pfnTimerSetRelative
7121	*/
7122	DECLINLINE(int) PDMDevHlpTimerSetRelative(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cTicksToNext, uint64_t *pu64Now)
7123	{
7124	return pDevIns->CTX_SUFF(pHlp)->pfnTimerSetRelative(pDevIns, hTimer, cTicksToNext, pu64Now);
7125	}
7126
7127	/**
7128	* @copydoc PDMDEVHLPR3::pfnTimerStop
7129	*/
7130	DECLINLINE(int) PDMDevHlpTimerStop(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer)
7131	{
7132	return pDevIns->CTX_SUFF(pHlp)->pfnTimerStop(pDevIns, hTimer);
7133	}
7134
7135	/**
7136	* @copydoc PDMDEVHLPR3::pfnTimerUnlockClock
7137	*/
7138	DECLINLINE(void) PDMDevHlpTimerUnlockClock(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer)
7139	{
7140	pDevIns->CTX_SUFF(pHlp)->pfnTimerUnlockClock(pDevIns, hTimer);
7141	}
7142
7143	/**
7144	* @copydoc PDMDEVHLPR3::pfnTimerUnlockClock2
7145	*/
7146	DECLINLINE(void) PDMDevHlpTimerUnlockClock2(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, PPDMCRITSECT pCritSect)
7147	{
7148	pDevIns->CTX_SUFF(pHlp)->pfnTimerUnlockClock2(pDevIns, hTimer, pCritSect);
7149	}
7150
7151	#ifdef IN_RING3
7152
7153	/**
7154	* @copydoc PDMDEVHLPR3::pfnTimerSetCritSect
7155	*/
7156	DECLINLINE(int) PDMDevHlpTimerSetCritSect(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, PPDMCRITSECT pCritSect)
7157	{
7158	return pDevIns->pHlpR3->pfnTimerSetCritSect(pDevIns, hTimer, pCritSect);
7159	}
7160
7161	/**
7162	* @copydoc PDMDEVHLPR3::pfnTimerSave
7163	*/
7164	DECLINLINE(int) PDMDevHlpTimerSave(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, PSSMHANDLE pSSM)
7165	{
7166	return pDevIns->pHlpR3->pfnTimerSave(pDevIns, hTimer, pSSM);
7167	}
7168
7169	/**
7170	* @copydoc PDMDEVHLPR3::pfnTimerLoad
7171	*/
7172	DECLINLINE(int) PDMDevHlpTimerLoad(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, PSSMHANDLE pSSM)
7173	{
7174	return pDevIns->pHlpR3->pfnTimerLoad(pDevIns, hTimer, pSSM);
7175	}
7176
7177	/**
7178	* @copydoc PDMDEVHLPR3::pfnTimerDestroy
7179	*/
7180	DECLINLINE(int) PDMDevHlpTimerDestroy(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer)
7181	{
7182	return pDevIns->pHlpR3->pfnTimerDestroy(pDevIns, hTimer);
7183	}
7184
7185	/**
7186	* @copydoc PDMDEVHLPR3::pfnTMUtcNow
7187	*/
7188	DECLINLINE(PRTTIMESPEC) PDMDevHlpTMUtcNow(PPDMDEVINS pDevIns, PRTTIMESPEC pTime)
7189	{
7190	return pDevIns->pHlpR3->pfnTMUtcNow(pDevIns, pTime);
7191	}
7192
7193	#endif
7194
7195	/**
7196	* Read physical memory - unknown data usage.
7197	*
7198	* @returns VINF_SUCCESS (for now).
7199	* @param pDevIns The device instance.
7200	* @param GCPhys Physical address start reading from.
7201	* @param pvBuf Where to put the read bits.
7202	* @param cbRead How many bytes to read.
7203	* @thread Any thread, but the call may involve the emulation thread.
7204	*/
7205	DECLINLINE(int) PDMDevHlpPhysRead(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead)
7206	{
7207	return pDevIns->CTX_SUFF(pHlp)->pfnPhysRead(pDevIns, GCPhys, pvBuf, cbRead, PDM_DEVHLP_PHYS_RW_F_DEFAULT);
7208	}
7209
7210	/**
7211	* Write to physical memory - unknown data usage.
7212	*
7213	* @returns VINF_SUCCESS for now, and later maybe VERR_EM_MEMORY.
7214	* @param pDevIns The device instance.
7215	* @param GCPhys Physical address to write to.
7216	* @param pvBuf What to write.
7217	* @param cbWrite How many bytes to write.
7218	* @thread Any thread, but the call may involve the emulation thread.
7219	*/
7220	DECLINLINE(int) PDMDevHlpPhysWrite(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite)
7221	{
7222	return pDevIns->CTX_SUFF(pHlp)->pfnPhysWrite(pDevIns, GCPhys, pvBuf, cbWrite, PDM_DEVHLP_PHYS_RW_F_DEFAULT);
7223	}
7224
7225	/**
7226	* Read physical memory - reads meta data processed by the device.
7227	*
7228	* @returns VINF_SUCCESS (for now).
7229	* @param pDevIns The device instance.
7230	* @param GCPhys Physical address start reading from.
7231	* @param pvBuf Where to put the read bits.
7232	* @param cbRead How many bytes to read.
7233	* @thread Any thread, but the call may involve the emulation thread.
7234	*/
7235	DECLINLINE(int) PDMDevHlpPhysReadMeta(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead)
7236	{
7237	return pDevIns->CTX_SUFF(pHlp)->pfnPhysRead(pDevIns, GCPhys, pvBuf, cbRead, PDM_DEVHLP_PHYS_RW_F_DATA_META);
7238	}
7239
7240	/**
7241	* Write to physical memory - written data was created/altered by the device.
7242	*
7243	* @returns VINF_SUCCESS for now, and later maybe VERR_EM_MEMORY.
7244	* @param pDevIns The device instance.
7245	* @param GCPhys Physical address to write to.
7246	* @param pvBuf What to write.
7247	* @param cbWrite How many bytes to write.
7248	* @thread Any thread, but the call may involve the emulation thread.
7249	*/
7250	DECLINLINE(int) PDMDevHlpPhysWriteMeta(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite)
7251	{
7252	return pDevIns->CTX_SUFF(pHlp)->pfnPhysWrite(pDevIns, GCPhys, pvBuf, cbWrite, PDM_DEVHLP_PHYS_RW_F_DATA_META);
7253	}
7254
7255	/**
7256	* Read physical memory - read data will not be touched by the device.
7257	*
7258	* @returns VINF_SUCCESS (for now).
7259	* @param pDevIns The device instance.
7260	* @param GCPhys Physical address start reading from.
7261	* @param pvBuf Where to put the read bits.
7262	* @param cbRead How many bytes to read.
7263	* @thread Any thread, but the call may involve the emulation thread.
7264	*/
7265	DECLINLINE(int) PDMDevHlpPhysReadUser(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead)
7266	{
7267	return pDevIns->CTX_SUFF(pHlp)->pfnPhysRead(pDevIns, GCPhys, pvBuf, cbRead, PDM_DEVHLP_PHYS_RW_F_DATA_USER);
7268	}
7269
7270	/**
7271	* Write to physical memory - written data was not touched/created by the device.
7272	*
7273	* @returns VINF_SUCCESS for now, and later maybe VERR_EM_MEMORY.
7274	* @param pDevIns The device instance.
7275	* @param GCPhys Physical address to write to.
7276	* @param pvBuf What to write.
7277	* @param cbWrite How many bytes to write.
7278	* @thread Any thread, but the call may involve the emulation thread.
7279	*/
7280	DECLINLINE(int) PDMDevHlpPhysWriteUser(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite)
7281	{
7282	return pDevIns->CTX_SUFF(pHlp)->pfnPhysWrite(pDevIns, GCPhys, pvBuf, cbWrite, PDM_DEVHLP_PHYS_RW_F_DATA_USER);
7283	}
7284
7285	#ifdef IN_RING3
7286
7287	/**
7288	* @copydoc PDMDEVHLPR3::pfnPhysGCPhys2CCPtr
7289	*/
7290	DECLINLINE(int) PDMDevHlpPhysGCPhys2CCPtr(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, uint32_t fFlags, void **ppv, PPGMPAGEMAPLOCK pLock)
7291	{
7292	return pDevIns->CTX_SUFF(pHlp)->pfnPhysGCPhys2CCPtr(pDevIns, GCPhys, fFlags, ppv, pLock);
7293	}
7294
7295	/**
7296	* @copydoc PDMDEVHLPR3::pfnPhysGCPhys2CCPtrReadOnly
7297	*/
7298	DECLINLINE(int) PDMDevHlpPhysGCPhys2CCPtrReadOnly(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, uint32_t fFlags, void const **ppv,
7299	PPGMPAGEMAPLOCK pLock)
7300	{
7301	return pDevIns->CTX_SUFF(pHlp)->pfnPhysGCPhys2CCPtrReadOnly(pDevIns, GCPhys, fFlags, ppv, pLock);
7302	}
7303
7304	/**
7305	* @copydoc PDMDEVHLPR3::pfnPhysReleasePageMappingLock
7306	*/
7307	DECLINLINE(void) PDMDevHlpPhysReleasePageMappingLock(PPDMDEVINS pDevIns, PPGMPAGEMAPLOCK pLock)
7308	{
7309	pDevIns->CTX_SUFF(pHlp)->pfnPhysReleasePageMappingLock(pDevIns, pLock);
7310	}
7311
7312	/**
7313	* @copydoc PDMDEVHLPR3::pfnPhysBulkGCPhys2CCPtr
7314	*/
7315	DECLINLINE(int) PDMDevHlpPhysBulkGCPhys2CCPtr(PPDMDEVINS pDevIns, uint32_t cPages, PCRTGCPHYS paGCPhysPages,
7316	uint32_t fFlags, void **papvPages, PPGMPAGEMAPLOCK paLocks)
7317	{
7318	return pDevIns->CTX_SUFF(pHlp)->pfnPhysBulkGCPhys2CCPtr(pDevIns, cPages, paGCPhysPages, fFlags, papvPages, paLocks);
7319	}
7320
7321	/**
7322	* @copydoc PDMDEVHLPR3::pfnPhysBulkGCPhys2CCPtrReadOnly
7323	*/
7324	DECLINLINE(int) PDMDevHlpPhysBulkGCPhys2CCPtrReadOnly(PPDMDEVINS pDevIns, uint32_t cPages, PCRTGCPHYS paGCPhysPages,
7325	uint32_t fFlags, void const **papvPages, PPGMPAGEMAPLOCK paLocks)
7326	{
7327	return pDevIns->CTX_SUFF(pHlp)->pfnPhysBulkGCPhys2CCPtrReadOnly(pDevIns, cPages, paGCPhysPages, fFlags, papvPages, paLocks);
7328	}
7329
7330	/**
7331	* @copydoc PDMDEVHLPR3::pfnPhysBulkReleasePageMappingLocks
7332	*/
7333	DECLINLINE(void) PDMDevHlpPhysBulkReleasePageMappingLocks(PPDMDEVINS pDevIns, uint32_t cPages, PPGMPAGEMAPLOCK paLocks)
7334	{
7335	pDevIns->CTX_SUFF(pHlp)->pfnPhysBulkReleasePageMappingLocks(pDevIns, cPages, paLocks);
7336	}
7337
7338	/**
7339	* @copydoc PDMDEVHLPR3::pfnPhysIsGCPhysNormal
7340	*/
7341	DECLINLINE(bool) PDMDevHlpPhysIsGCPhysNormal(PPDMDEVINS pDevIns, RTGCPHYS GCPhys)
7342	{
7343	return pDevIns->CTX_SUFF(pHlp)->pfnPhysIsGCPhysNormal(pDevIns, GCPhys);
7344	}
7345
7346	/**
7347	* @copydoc PDMDEVHLPR3::pfnPhysChangeMemBalloon
7348	*/
7349	DECLINLINE(int) PDMDevHlpPhysChangeMemBalloon(PPDMDEVINS pDevIns, bool fInflate, unsigned cPages, RTGCPHYS *paPhysPage)
7350	{
7351	return pDevIns->CTX_SUFF(pHlp)->pfnPhysChangeMemBalloon(pDevIns, fInflate, cPages, paPhysPage);
7352	}
7353
7354	/**
7355	* @copydoc PDMDEVHLPR3::pfnCpuGetGuestArch
7356	*/
7357	DECLINLINE(CPUMARCH) PDMDevHlpCpuGetGuestArch(PPDMDEVINS pDevIns)
7358	{
7359	return pDevIns->CTX_SUFF(pHlp)->pfnCpuGetGuestArch(pDevIns);
7360	}
7361
7362	/**
7363	* Returns a flag whether the current guest CPU architecture is x86.
7364	*
7365	* @returns Flag whether the current guest architecture is x86.
7366	* @param pDevIns The device instance.
7367	*/
7368	DECLINLINE(bool) PDMDevHlpCpuIsGuestArchX86(PPDMDEVINS pDevIns)
7369	{
7370	return pDevIns->CTX_SUFF(pHlp)->pfnCpuGetGuestArch(pDevIns) == kCpumArch_X86;
7371	}
7372
7373	/**
7374	* Returns a flag whether the current guest CPU architecture is ARM.
7375	*
7376	* @returns Flag whether the current guest architecture is ARM.
7377	* @param pDevIns The device instance.
7378	*/
7379	DECLINLINE(bool) PDMDevHlpCpuIsGuestArchArm(PPDMDEVINS pDevIns)
7380	{
7381	return pDevIns->CTX_SUFF(pHlp)->pfnCpuGetGuestArch(pDevIns) == kCpumArch_Arm;
7382	}
7383
7384	/**
7385	* @copydoc PDMDEVHLPR3::pfnCpuGetGuestMicroarch
7386	*/
7387	DECLINLINE(CPUMMICROARCH) PDMDevHlpCpuGetGuestMicroarch(PPDMDEVINS pDevIns)
7388	{
7389	return pDevIns->CTX_SUFF(pHlp)->pfnCpuGetGuestMicroarch(pDevIns);
7390	}
7391
7392	/**
7393	* @copydoc PDMDEVHLPR3::pfnCpuGetGuestScalableBusFrequency
7394	*/
7395	DECLINLINE(uint64_t) PDMDevHlpCpuGetGuestScalableBusFrequency(PPDMDEVINS pDevIns)
7396	{
7397	return pDevIns->CTX_SUFF(pHlp)->pfnCpuGetGuestScalableBusFrequency(pDevIns);
7398	}
7399
7400	/**
7401	* @copydoc PDMDEVHLPR3::pfnCpuGetGuestAddrWidths
7402	*/
7403	DECLINLINE(void) PDMDevHlpCpuGetGuestAddrWidths(PPDMDEVINS pDevIns, uint8_t pcPhysAddrWidth, uint8_t pcLinearAddrWidth)
7404	{
7405	pDevIns->CTX_SUFF(pHlp)->pfnCpuGetGuestAddrWidths(pDevIns, pcPhysAddrWidth, pcLinearAddrWidth);
7406	}
7407
7408	/**
7409	* @copydoc PDMDEVHLPR3::pfnPhysReadGCVirt
7410	*/
7411	DECLINLINE(int) PDMDevHlpPhysReadGCVirt(PPDMDEVINS pDevIns, void *pvDst, RTGCPTR GCVirtSrc, size_t cb)
7412	{
7413	return pDevIns->pHlpR3->pfnPhysReadGCVirt(pDevIns, pvDst, GCVirtSrc, cb);
7414	}
7415
7416	/**
7417	* @copydoc PDMDEVHLPR3::pfnPhysWriteGCVirt
7418	*/
7419	DECLINLINE(int) PDMDevHlpPhysWriteGCVirt(PPDMDEVINS pDevIns, RTGCPTR GCVirtDst, const void *pvSrc, size_t cb)
7420	{
7421	return pDevIns->pHlpR3->pfnPhysWriteGCVirt(pDevIns, GCVirtDst, pvSrc, cb);
7422	}
7423
7424	/**
7425	* @copydoc PDMDEVHLPR3::pfnPhysGCPtr2GCPhys
7426	*/
7427	DECLINLINE(int) PDMDevHlpPhysGCPtr2GCPhys(PPDMDEVINS pDevIns, RTGCPTR GCPtr, PRTGCPHYS pGCPhys)
7428	{
7429	return pDevIns->pHlpR3->pfnPhysGCPtr2GCPhys(pDevIns, GCPtr, pGCPhys);
7430	}
7431
7432	/**
7433	* @copydoc PDMDEVHLPR3::pfnMMHeapAlloc
7434	*/
7435	DECLINLINE(void *) PDMDevHlpMMHeapAlloc(PPDMDEVINS pDevIns, size_t cb)
7436	{
7437	return pDevIns->pHlpR3->pfnMMHeapAlloc(pDevIns, cb);
7438	}
7439
7440	/**
7441	* @copydoc PDMDEVHLPR3::pfnMMHeapAllocZ
7442	*/
7443	DECLINLINE(void *) PDMDevHlpMMHeapAllocZ(PPDMDEVINS pDevIns, size_t cb)
7444	{
7445	return pDevIns->pHlpR3->pfnMMHeapAllocZ(pDevIns, cb);
7446	}
7447
7448	/**
7449	* Allocating string printf.
7450	*
7451	* @returns Pointer to the string.
7452	* @param pDevIns The device instance.
7453	* @param enmTag The statistics tag.
7454	* @param pszFormat The format string.
7455	* @param ... Format arguments.
7456	*/
7457	DECLINLINE(char ) RT_IPRT_FORMAT_ATTR(2, 3) PDMDevHlpMMHeapAPrintf(PPDMDEVINS pDevIns, MMTAG enmTag, const char pszFormat, ...)
7458	{
7459	va_list va;
7460	va_start(va, pszFormat);
7461	char *psz = pDevIns->pHlpR3->pfnMMHeapAPrintfV(pDevIns, enmTag, pszFormat, va);
7462	va_end(va);
7463
7464	return psz;
7465	}
7466
7467	/**
7468	* @copydoc PDMDEVHLPR3::pfnMMHeapFree
7469	*/
7470	DECLINLINE(void) PDMDevHlpMMHeapFree(PPDMDEVINS pDevIns, void *pv)
7471	{
7472	pDevIns->pHlpR3->pfnMMHeapFree(pDevIns, pv);
7473	}
7474
7475	/**
7476	* @copydoc PDMDEVHLPR3::pfnMMPhysGetRamSize
7477	*/
7478	DECLINLINE(uint64_t) PDMDevHlpMMPhysGetRamSize(PPDMDEVINS pDevIns)
7479	{
7480	return pDevIns->pHlpR3->pfnMMPhysGetRamSize(pDevIns);
7481	}
7482
7483	/**
7484	* @copydoc PDMDEVHLPR3::pfnMMPhysGetRamSizeBelow4GB
7485	*/
7486	DECLINLINE(uint32_t) PDMDevHlpMMPhysGetRamSizeBelow4GB(PPDMDEVINS pDevIns)
7487	{
7488	return pDevIns->pHlpR3->pfnMMPhysGetRamSizeBelow4GB(pDevIns);
7489	}
7490
7491	/**
7492	* @copydoc PDMDEVHLPR3::pfnMMPhysGetRamSizeAbove4GB
7493	*/
7494	DECLINLINE(uint64_t) PDMDevHlpMMPhysGetRamSizeAbove4GB(PPDMDEVINS pDevIns)
7495	{
7496	return pDevIns->pHlpR3->pfnMMPhysGetRamSizeAbove4GB(pDevIns);
7497	}
7498	#endif /* IN_RING3 */
7499
7500	/**
7501	* @copydoc PDMDEVHLPR3::pfnVMState
7502	*/
7503	DECLINLINE(VMSTATE) PDMDevHlpVMState(PPDMDEVINS pDevIns)
7504	{
7505	return pDevIns->CTX_SUFF(pHlp)->pfnVMState(pDevIns);
7506	}
7507
7508	#ifdef IN_RING3
7509
7510	/**
7511	* @copydoc PDMDEVHLPR3::pfnVMTeleportedAndNotFullyResumedYet
7512	*/
7513	DECLINLINE(bool) PDMDevHlpVMTeleportedAndNotFullyResumedYet(PPDMDEVINS pDevIns)
7514	{
7515	return pDevIns->pHlpR3->pfnVMTeleportedAndNotFullyResumedYet(pDevIns);
7516	}
7517
7518	/**
7519	* Set the VM error message
7520	*
7521	* @returns rc.
7522	* @param pDevIns The device instance.
7523	* @param rc VBox status code.
7524	* @param SRC_POS Use RT_SRC_POS.
7525	* @param pszFormat Error message format string.
7526	* @param ... Error message arguments.
7527	* @sa VMSetError
7528	*/
7529	DECLINLINE(int) RT_IPRT_FORMAT_ATTR(6, 7) PDMDevHlpVMSetError(PPDMDEVINS pDevIns, const int rc, RT_SRC_POS_DECL,
7530	const char *pszFormat, ...)
7531	{
7532	va_list va;
7533	va_start(va, pszFormat);
7534	pDevIns->CTX_SUFF(pHlp)->pfnVMSetErrorV(pDevIns, rc, RT_SRC_POS_ARGS, pszFormat, va);
7535	va_end(va);
7536	return rc;
7537	}
7538
7539	/**
7540	* Set the VM runtime error message
7541	*
7542	* @returns VBox status code.
7543	* @param pDevIns The device instance.
7544	* @param fFlags The action flags. See VMSETRTERR_FLAGS_*.
7545	* @param pszErrorId Error ID string.
7546	* @param pszFormat Error message format string.
7547	* @param ... Error message arguments.
7548	* @sa VMSetRuntimeError
7549	*/
7550	DECLINLINE(int) RT_IPRT_FORMAT_ATTR(4, 5) PDMDevHlpVMSetRuntimeError(PPDMDEVINS pDevIns, uint32_t fFlags, const char *pszErrorId,
7551	const char *pszFormat, ...)
7552	{
7553	va_list va;
7554	int rc;
7555	va_start(va, pszFormat);
7556	rc = pDevIns->CTX_SUFF(pHlp)->pfnVMSetRuntimeErrorV(pDevIns, fFlags, pszErrorId, pszFormat, va);
7557	va_end(va);
7558	return rc;
7559	}
7560
7561	/**
7562	* @copydoc PDMDEVHLPR3::pfnVMWaitForDeviceReady
7563	*/
7564	DECLINLINE(int) PDMDevHlpVMWaitForDeviceReady(PPDMDEVINS pDevIns, VMCPUID idCpu)
7565	{
7566	return pDevIns->CTX_SUFF(pHlp)->pfnVMWaitForDeviceReady(pDevIns, idCpu);
7567	}
7568
7569	/**
7570	* @copydoc PDMDEVHLPR3::pfnVMNotifyCpuDeviceReady
7571	*/
7572	DECLINLINE(int) PDMDevHlpVMNotifyCpuDeviceReady(PPDMDEVINS pDevIns, VMCPUID idCpu)
7573	{
7574	return pDevIns->CTX_SUFF(pHlp)->pfnVMNotifyCpuDeviceReady(pDevIns, idCpu);
7575	}
7576
7577	/**
7578	* Convenience wrapper for VMR3ReqCallU.
7579	*
7580	* This assumes (1) you're calling a function that returns an VBox status code
7581	* and that you do not wish to wait for it to complete.
7582	*
7583	* @returns VBox status code returned by VMR3ReqCallVU.
7584	*
7585	* @param pDevIns The device instance.
7586	* @param idDstCpu The destination CPU(s). Either a specific CPU ID or
7587	* one of the following special values:
7588	* VMCPUID_ANY, VMCPUID_ANY_QUEUE, VMCPUID_ALL or VMCPUID_ALL_REVERSE.
7589	* @param pfnFunction Pointer to the function to call.
7590	* @param cArgs Number of arguments following in the ellipsis.
7591	* @param ... Argument list.
7592	*
7593	* @remarks See remarks on VMR3ReqCallVU.
7594	*/
7595	DECLINLINE(int) RT_IPRT_CALLREQ_ATTR(3, 4, 5)
7596	PDMDevHlpVMReqCallNoWait(PPDMDEVINS pDevIns, VMCPUID idDstCpu, PFNRT pfnFunction, unsigned cArgs, ...)
7597	{
7598	va_list Args;
7599	va_start(Args, cArgs);
7600	int rc = pDevIns->CTX_SUFF(pHlp)->pfnVMReqCallNoWaitV(pDevIns, idDstCpu, pfnFunction, cArgs, Args);
7601	va_end(Args);
7602	return rc;
7603	}
7604
7605	/**
7606	* Convenience wrapper for VMR3ReqCallU.
7607	*
7608	* This assumes (1) you're calling a function that returns void, (2) that you
7609	* wish to wait for ever for it to return, and (3) that it's priority request
7610	* that can be safely be handled during async suspend and power off.
7611	*
7612	* @returns VBox status code of VMR3ReqCallVU.
7613	*
7614	* @param pDevIns The device instance.
7615	* @param idDstCpu The destination CPU(s). Either a specific CPU ID or
7616	* one of the following special values:
7617	* VMCPUID_ANY, VMCPUID_ANY_QUEUE, VMCPUID_ALL or VMCPUID_ALL_REVERSE.
7618	* @param pfnFunction Pointer to the function to call.
7619	* @param cArgs Number of arguments following in the ellipsis.
7620	* @param ... Argument list.
7621	*
7622	* @remarks See remarks on VMR3ReqCallVU.
7623	*/
7624	DECLINLINE(int) RT_IPRT_CALLREQ_ATTR(3, 4, 5)
7625	PDMDevHlpVMReqPriorityCallWait(PPDMDEVINS pDevIns, VMCPUID idDstCpu, PFNRT pfnFunction, unsigned cArgs, ...)
7626	{
7627	va_list Args;
7628	va_start(Args, cArgs);
7629	int rc = pDevIns->CTX_SUFF(pHlp)->pfnVMReqPriorityCallWaitV(pDevIns, idDstCpu, pfnFunction, cArgs, Args);
7630	va_end(Args);
7631	return rc;
7632	}
7633
7634	#endif /* IN_RING3 */
7635
7636	/**
7637	* VBOX_STRICT wrapper for pHlp->pfnDBGFStopV.
7638	*
7639	* @returns VBox status code which must be passed up to the VMM. This will be
7640	* VINF_SUCCESS in non-strict builds.
7641	* @param pDevIns The device instance.
7642	* @param SRC_POS Use RT_SRC_POS.
7643	* @param pszFormat Message. (optional)
7644	* @param ... Message parameters.
7645	*/
7646	DECLINLINE(int) RT_IPRT_FORMAT_ATTR(5, 6) PDMDevHlpDBGFStop(PPDMDEVINS pDevIns, RT_SRC_POS_DECL, const char *pszFormat, ...)
7647	{
7648	#ifdef VBOX_STRICT
7649	# ifdef IN_RING3
7650	int rc;
7651	va_list args;
7652	va_start(args, pszFormat);
7653	rc = pDevIns->pHlpR3->pfnDBGFStopV(pDevIns, RT_SRC_POS_ARGS, pszFormat, args);
7654	va_end(args);
7655	return rc;
7656	# else
7657	NOREF(pDevIns);
7658	NOREF(pszFile);
7659	NOREF(iLine);
7660	NOREF(pszFunction);
7661	NOREF(pszFormat);
7662	return VINF_EM_DBG_STOP;
7663	# endif
7664	#else
7665	NOREF(pDevIns);
7666	NOREF(pszFile);
7667	NOREF(iLine);
7668	NOREF(pszFunction);
7669	NOREF(pszFormat);
7670	return VINF_SUCCESS;
7671	#endif
7672	}
7673
7674	#ifdef IN_RING3
7675
7676	/**
7677	* @copydoc PDMDEVHLPR3::pfnDBGFInfoRegister
7678	*/
7679	DECLINLINE(int) PDMDevHlpDBGFInfoRegister(PPDMDEVINS pDevIns, const char pszName, const char pszDesc, PFNDBGFHANDLERDEV pfnHandler)
7680	{
7681	return pDevIns->pHlpR3->pfnDBGFInfoRegister(pDevIns, pszName, pszDesc, pfnHandler);
7682	}
7683
7684	/**
7685	* @copydoc PDMDEVHLPR3::pfnDBGFInfoRegisterArgv
7686	*/
7687	DECLINLINE(int) PDMDevHlpDBGFInfoRegisterArgv(PPDMDEVINS pDevIns, const char pszName, const char pszDesc, PFNDBGFINFOARGVDEV pfnHandler)
7688	{
7689	return pDevIns->pHlpR3->pfnDBGFInfoRegisterArgv(pDevIns, pszName, pszDesc, pfnHandler);
7690	}
7691
7692	/**
7693	* @copydoc PDMDEVHLPR3::pfnDBGFRegRegister
7694	*/
7695	DECLINLINE(int) PDMDevHlpDBGFRegRegister(PPDMDEVINS pDevIns, PCDBGFREGDESC paRegisters)
7696	{
7697	return pDevIns->pHlpR3->pfnDBGFRegRegister(pDevIns, paRegisters);
7698	}
7699
7700	/**
7701	* @copydoc PDMDEVHLPR3::pfnDBGFReportBugCheck
7702	*/
7703	DECLINLINE(VBOXSTRICTRC) PDMDevHlpDBGFReportBugCheck(PPDMDEVINS pDevIns, DBGFEVENTTYPE enmEvent, uint64_t uBugCheck,
7704	uint64_t uP1, uint64_t uP2, uint64_t uP3, uint64_t uP4)
7705	{
7706	return pDevIns->pHlpR3->pfnDBGFReportBugCheck(pDevIns, enmEvent, uBugCheck, uP1, uP2, uP3, uP4);
7707	}
7708
7709	/**
7710	* @copydoc PDMDEVHLPR3::pfnDBGFCoreWrite
7711	*/
7712	DECLINLINE(int) PDMDevHlpDBGFCoreWrite(PPDMDEVINS pDevIns, const char *pszFilename, bool fReplaceFile)
7713	{
7714	return pDevIns->pHlpR3->pfnDBGFCoreWrite(pDevIns, pszFilename, fReplaceFile);
7715	}
7716
7717	/**
7718	* @copydoc PDMDEVHLPR3::pfnDBGFInfoLogHlp
7719	*/
7720	DECLINLINE(PCDBGFINFOHLP) PDMDevHlpDBGFInfoLogHlp(PPDMDEVINS pDevIns)
7721	{
7722	return pDevIns->pHlpR3->pfnDBGFInfoLogHlp(pDevIns);
7723	}
7724
7725	/**
7726	* @copydoc PDMDEVHLPR3::pfnDBGFRegNmQueryU64
7727	*/
7728	DECLINLINE(int) PDMDevHlpDBGFRegNmQueryU64(PPDMDEVINS pDevIns, VMCPUID idDefCpu, const char pszReg, uint64_t pu64)
7729	{
7730	return pDevIns->pHlpR3->pfnDBGFRegNmQueryU64(pDevIns, idDefCpu, pszReg, pu64);
7731	}
7732
7733	/**
7734	* Format a set of registers.
7735	*
7736	* This is restricted to registers from one CPU, that specified by @a idCpu.
7737	*
7738	* @returns VBox status code.
7739	* @param pDevIns The device instance.
7740	* @param idCpu The CPU ID of any CPU registers that may be
7741	* printed, pass VMCPUID_ANY if not applicable.
7742	* @param pszBuf The output buffer.
7743	* @param cbBuf The size of the output buffer.
7744	* @param pszFormat The format string. Register names are given by
7745	* %VR{name}, they take no arguments.
7746	* @param ... Argument list.
7747	*/
7748	DECLINLINE(int) RT_IPRT_FORMAT_ATTR(4, 5) PDMDevHlpDBGFRegPrintf(PPDMDEVINS pDevIns, VMCPUID idCpu, char *pszBuf, size_t cbBuf,
7749	const char *pszFormat, ...)
7750	{
7751	va_list Args;
7752	va_start(Args, pszFormat);
7753	int rc = pDevIns->pHlpR3->pfnDBGFRegPrintfV(pDevIns, idCpu, pszBuf, cbBuf, pszFormat, Args);
7754	va_end(Args);
7755	return rc;
7756	}
7757
7758	/**
7759	* @copydoc PDMDEVHLPR3::pfnSTAMRegister
7760	*/
7761	DECLINLINE(void) PDMDevHlpSTAMRegister(PPDMDEVINS pDevIns, void pvSample, STAMTYPE enmType, const char pszName, STAMUNIT enmUnit, const char *pszDesc)
7762	{
7763	pDevIns->pHlpR3->pfnSTAMRegister(pDevIns, pvSample, enmType, pszName, enmUnit, pszDesc);
7764	}
7765
7766	/**
7767	* Same as pfnSTAMRegister except that the name is specified in a
7768	* RTStrPrintf like fashion.
7769	*
7770	* @param pDevIns Device instance of the DMA.
7771	* @param pvSample Pointer to the sample.
7772	* @param enmType Sample type. This indicates what pvSample is
7773	* pointing at.
7774	* @param enmVisibility Visibility type specifying whether unused
7775	* statistics should be visible or not.
7776	* @param enmUnit Sample unit.
7777	* @param pszDesc Sample description.
7778	* @param pszName Sample name format string, unix path style. If
7779	* this does not start with a '/', the default
7780	* prefix will be prepended, otherwise it will be
7781	* used as-is.
7782	* @param ... Arguments to the format string.
7783	*/
7784	DECLINLINE(void) RT_IPRT_FORMAT_ATTR(7, 8) PDMDevHlpSTAMRegisterF(PPDMDEVINS pDevIns, void *pvSample, STAMTYPE enmType,
7785	STAMVISIBILITY enmVisibility, STAMUNIT enmUnit,
7786	const char pszDesc, const char pszName, ...)
7787	{
7788	va_list va;
7789	va_start(va, pszName);
7790	pDevIns->pHlpR3->pfnSTAMRegisterV(pDevIns, pvSample, enmType, enmVisibility, enmUnit, pszDesc, pszName, va);
7791	va_end(va);
7792	}
7793
7794	/**
7795	* @copydoc PDMDEVHLPR3::pfnSTAMDeregisterByPrefix
7796	*/
7797	DECLINLINE(int) PDMDevHlpSTAMDeregisterByPrefix(PPDMDEVINS pDevIns, const char *pszPrefix)
7798	{
7799	return pDevIns->pHlpR3->pfnSTAMDeregisterByPrefix(pDevIns, pszPrefix);
7800	}
7801
7802	/**
7803	* Registers the device with the default PCI bus.
7804	*
7805	* @returns VBox status code.
7806	* @param pDevIns The device instance.
7807	* @param pPciDev The PCI device structure.
7808	* This must be kept in the instance data.
7809	* The PCI configuration must be initialized before registration.
7810	*/
7811	DECLINLINE(int) PDMDevHlpPCIRegister(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev)
7812	{
7813	return pDevIns->pHlpR3->pfnPCIRegister(pDevIns, pPciDev, 0 /fFlags/,
7814	PDMPCIDEVREG_DEV_NO_FIRST_UNUSED, PDMPCIDEVREG_FUN_NO_FIRST_UNUSED, NULL);
7815	}
7816
7817	/**
7818	* @copydoc PDMDEVHLPR3::pfnPCIRegister
7819	*/
7820	DECLINLINE(int) PDMDevHlpPCIRegisterEx(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t fFlags,
7821	uint8_t uPciDevNo, uint8_t uPciFunNo, const char *pszName)
7822	{
7823	return pDevIns->pHlpR3->pfnPCIRegister(pDevIns, pPciDev, fFlags, uPciDevNo, uPciFunNo, pszName);
7824	}
7825
7826	/**
7827	* Initialize MSI emulation support for the first PCI device.
7828	*
7829	* @returns VBox status code.
7830	* @param pDevIns The device instance.
7831	* @param pMsiReg MSI emulation registration structure.
7832	*/
7833	DECLINLINE(int) PDMDevHlpPCIRegisterMsi(PPDMDEVINS pDevIns, PPDMMSIREG pMsiReg)
7834	{
7835	return pDevIns->pHlpR3->pfnPCIRegisterMsi(pDevIns, NULL, pMsiReg);
7836	}
7837
7838	/**
7839	* @copydoc PDMDEVHLPR3::pfnPCIRegisterMsi
7840	*/
7841	DECLINLINE(int) PDMDevHlpPCIRegisterMsiEx(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, PPDMMSIREG pMsiReg)
7842	{
7843	return pDevIns->pHlpR3->pfnPCIRegisterMsi(pDevIns, pPciDev, pMsiReg);
7844	}
7845
7846	/**
7847	* Registers a I/O port region for the default PCI device.
7848	*
7849	* @returns VBox status code.
7850	* @param pDevIns The device instance.
7851	* @param iRegion The region number.
7852	* @param cbRegion Size of the region.
7853	* @param hIoPorts Handle to the I/O port region.
7854	*/
7855	DECLINLINE(int) PDMDevHlpPCIIORegionRegisterIo(PPDMDEVINS pDevIns, uint32_t iRegion, RTGCPHYS cbRegion, IOMIOPORTHANDLE hIoPorts)
7856	{
7857	return pDevIns->pHlpR3->pfnPCIIORegionRegister(pDevIns, NULL, iRegion, cbRegion, PCI_ADDRESS_SPACE_IO,
7858	PDMPCIDEV_IORGN_F_IOPORT_HANDLE \| PDMPCIDEV_IORGN_F_NEW_STYLE, hIoPorts, NULL);
7859	}
7860
7861	/**
7862	* Registers a I/O port region for the default PCI device, custom map/unmap.
7863	*
7864	* @returns VBox status code.
7865	* @param pDevIns The device instance.
7866	* @param iRegion The region number.
7867	* @param cbRegion Size of the region.
7868	* @param pfnMapUnmap Callback for doing the mapping, optional. The
7869	* callback will be invoked holding only the PDM lock.
7870	* The device lock will _not_ be taken (due to lock
7871	* order).
7872	*/
7873	DECLINLINE(int) PDMDevHlpPCIIORegionRegisterIoCustom(PPDMDEVINS pDevIns, uint32_t iRegion, RTGCPHYS cbRegion,
7874	PFNPCIIOREGIONMAP pfnMapUnmap)
7875	{
7876	return pDevIns->pHlpR3->pfnPCIIORegionRegister(pDevIns, NULL, iRegion, cbRegion, PCI_ADDRESS_SPACE_IO,
7877	PDMPCIDEV_IORGN_F_NO_HANDLE \| PDMPCIDEV_IORGN_F_NEW_STYLE,
7878	UINT64_MAX, pfnMapUnmap);
7879	}
7880
7881	/**
7882	* Combines PDMDevHlpIoPortCreate and PDMDevHlpPCIIORegionRegisterIo, creating
7883	* and registering an I/O port region for the default PCI device.
7884	*
7885	* @returns VBox status code.
7886	* @param pDevIns The device instance to register the ports with.
7887	* @param cPorts The count of I/O ports in the region (the size).
7888	* @param iPciRegion The PCI device region.
7889	* @param pfnOut Pointer to function which is gonna handle OUT
7890	* operations. Optional.
7891	* @param pfnIn Pointer to function which is gonna handle IN operations.
7892	* Optional.
7893	* @param pvUser User argument to pass to the callbacks.
7894	* @param pszDesc Pointer to description string. This must not be freed.
7895	* @param paExtDescs Extended per-port descriptions, optional. Partial range
7896	* coverage is allowed. This must not be freed.
7897	* @param phIoPorts Where to return the I/O port range handle.
7898	*
7899	*/
7900	DECLINLINE(int) PDMDevHlpPCIIORegionCreateIo(PPDMDEVINS pDevIns, uint32_t iPciRegion, RTIOPORT cPorts,
7901	PFNIOMIOPORTNEWOUT pfnOut, PFNIOMIOPORTNEWIN pfnIn, void *pvUser,
7902	const char *pszDesc, PCIOMIOPORTDESC paExtDescs, PIOMIOPORTHANDLE phIoPorts)
7903
7904	{
7905	int rc = pDevIns->pHlpR3->pfnIoPortCreateEx(pDevIns, cPorts, 0 /fFlags/, pDevIns->apPciDevs[0], iPciRegion << 16,
7906	pfnOut, pfnIn, NULL, NULL, pvUser, pszDesc, paExtDescs, phIoPorts);
7907	if (RT_SUCCESS(rc))
7908	rc = pDevIns->pHlpR3->pfnPCIIORegionRegister(pDevIns, pDevIns->apPciDevs[0], iPciRegion, cPorts, PCI_ADDRESS_SPACE_IO,
7909	PDMPCIDEV_IORGN_F_IOPORT_HANDLE \| PDMPCIDEV_IORGN_F_NEW_STYLE,
7910	phIoPorts, NULL /pfnMapUnmap*/);
7911	return rc;
7912	}
7913
7914	/**
7915	* Registers an MMIO region for the default PCI device.
7916	*
7917	* @returns VBox status code.
7918	* @param pDevIns The device instance.
7919	* @param iRegion The region number.
7920	* @param cbRegion Size of the region.
7921	* @param enmType PCI_ADDRESS_SPACE_MEM or
7922	* PCI_ADDRESS_SPACE_MEM_PREFETCH, optionally or-ing in
7923	* PCI_ADDRESS_SPACE_BAR64 or PCI_ADDRESS_SPACE_BAR32.
7924	* @param hMmioRegion Handle to the MMIO region.
7925	* @param pfnMapUnmap Callback for doing the mapping, optional. The
7926	* callback will be invoked holding only the PDM lock.
7927	* The device lock will _not_ be taken (due to lock
7928	* order).
7929	*/
7930	DECLINLINE(int) PDMDevHlpPCIIORegionRegisterMmio(PPDMDEVINS pDevIns, uint32_t iRegion, RTGCPHYS cbRegion, PCIADDRESSSPACE enmType,
7931	IOMMMIOHANDLE hMmioRegion, PFNPCIIOREGIONMAP pfnMapUnmap)
7932	{
7933	return pDevIns->pHlpR3->pfnPCIIORegionRegister(pDevIns, NULL, iRegion, cbRegion, enmType,
7934	PDMPCIDEV_IORGN_F_MMIO_HANDLE \| PDMPCIDEV_IORGN_F_NEW_STYLE,
7935	hMmioRegion, pfnMapUnmap);
7936	}
7937
7938	/**
7939	* Registers an MMIO region for the default PCI device, extended version.
7940	*
7941	* @returns VBox status code.
7942	* @param pDevIns The device instance.
7943	* @param pPciDev The PCI device structure.
7944	* @param iRegion The region number.
7945	* @param cbRegion Size of the region.
7946	* @param enmType PCI_ADDRESS_SPACE_MEM or
7947	* PCI_ADDRESS_SPACE_MEM_PREFETCH, optionally or-ing in
7948	* PCI_ADDRESS_SPACE_BAR64 or PCI_ADDRESS_SPACE_BAR32.
7949	* @param hMmioRegion Handle to the MMIO region.
7950	* @param pfnMapUnmap Callback for doing the mapping, optional. The
7951	* callback will be invoked holding only the PDM lock.
7952	* The device lock will _not_ be taken (due to lock
7953	* order).
7954	*/
7955	DECLINLINE(int) PDMDevHlpPCIIORegionRegisterMmioEx(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t iRegion,
7956	RTGCPHYS cbRegion, PCIADDRESSSPACE enmType, IOMMMIOHANDLE hMmioRegion,
7957	PFNPCIIOREGIONMAP pfnMapUnmap)
7958	{
7959	return pDevIns->pHlpR3->pfnPCIIORegionRegister(pDevIns, pPciDev, iRegion, cbRegion, enmType,
7960	PDMPCIDEV_IORGN_F_MMIO_HANDLE \| PDMPCIDEV_IORGN_F_NEW_STYLE,
7961	hMmioRegion, pfnMapUnmap);
7962	}
7963
7964	/**
7965	* Combines PDMDevHlpMmioCreate and PDMDevHlpPCIIORegionRegisterMmio, creating
7966	* and registering an MMIO region for the default PCI device.
7967	*
7968	* @returns VBox status code.
7969	* @param pDevIns The device instance to register the ports with.
7970	* @param cbRegion The size of the region in bytes.
7971	* @param iPciRegion The PCI device region.
7972	* @param enmType PCI_ADDRESS_SPACE_MEM or
7973	* PCI_ADDRESS_SPACE_MEM_PREFETCH, optionally or-ing in
7974	* PCI_ADDRESS_SPACE_BAR64 or PCI_ADDRESS_SPACE_BAR32.
7975	* @param fFlags Flags, IOMMMIO_FLAGS_XXX.
7976	* @param pfnWrite Pointer to function which is gonna handle Write
7977	* operations.
7978	* @param pfnRead Pointer to function which is gonna handle Read
7979	* operations.
7980	* @param pvUser User argument to pass to the callbacks.
7981	* @param pszDesc Pointer to description string. This must not be freed.
7982	* @param phRegion Where to return the MMIO region handle.
7983	*
7984	*/
7985	DECLINLINE(int) PDMDevHlpPCIIORegionCreateMmio(PPDMDEVINS pDevIns, uint32_t iPciRegion, RTGCPHYS cbRegion, PCIADDRESSSPACE enmType,
7986	PFNIOMMMIONEWWRITE pfnWrite, PFNIOMMMIONEWREAD pfnRead, void *pvUser,
7987	uint32_t fFlags, const char *pszDesc, PIOMMMIOHANDLE phRegion)
7988
7989	{
7990	int rc = pDevIns->pHlpR3->pfnMmioCreateEx(pDevIns, cbRegion, fFlags, pDevIns->apPciDevs[0], iPciRegion << 16,
7991	pfnWrite, pfnRead, NULL /pfnFill/, pvUser, pszDesc, phRegion);
7992	if (RT_SUCCESS(rc))
7993	rc = pDevIns->pHlpR3->pfnPCIIORegionRegister(pDevIns, pDevIns->apPciDevs[0], iPciRegion, cbRegion, enmType,
7994	PDMPCIDEV_IORGN_F_MMIO_HANDLE \| PDMPCIDEV_IORGN_F_NEW_STYLE,
7995	phRegion, NULL /pfnMapUnmap*/);
7996	return rc;
7997	}
7998
7999
8000	/**
8001	* Registers an MMIO2 region for the default PCI device.
8002	*
8003	* @returns VBox status code.
8004	* @param pDevIns The device instance.
8005	* @param iRegion The region number.
8006	* @param cbRegion Size of the region.
8007	* @param enmType PCI_ADDRESS_SPACE_MEM or
8008	* PCI_ADDRESS_SPACE_MEM_PREFETCH, optionally or-ing in
8009	* PCI_ADDRESS_SPACE_BAR64 or PCI_ADDRESS_SPACE_BAR32.
8010	* @param hMmio2Region Handle to the MMIO2 region.
8011	*/
8012	DECLINLINE(int) PDMDevHlpPCIIORegionRegisterMmio2(PPDMDEVINS pDevIns, uint32_t iRegion, RTGCPHYS cbRegion,
8013	PCIADDRESSSPACE enmType, PGMMMIO2HANDLE hMmio2Region)
8014	{
8015	return pDevIns->pHlpR3->pfnPCIIORegionRegister(pDevIns, NULL, iRegion, cbRegion, enmType,
8016	PDMPCIDEV_IORGN_F_MMIO2_HANDLE \| PDMPCIDEV_IORGN_F_NEW_STYLE,
8017	hMmio2Region, NULL);
8018	}
8019
8020	/**
8021	* Combines PDMDevHlpMmio2Create and PDMDevHlpPCIIORegionRegisterMmio2, creating
8022	* and registering an MMIO2 region for the default PCI device, extended edition.
8023	*
8024	* @returns VBox status code.
8025	* @param pDevIns The device instance to register the ports with.
8026	* @param cbRegion The size of the region in bytes.
8027	* @param iPciRegion The PCI device region.
8028	* @param enmType PCI_ADDRESS_SPACE_MEM or
8029	* PCI_ADDRESS_SPACE_MEM_PREFETCH, optionally or-ing in
8030	* PCI_ADDRESS_SPACE_BAR64 or PCI_ADDRESS_SPACE_BAR32.
8031	* @param pszDesc Pointer to description string. This must not be freed.
8032	* @param ppvMapping Where to store the address of the ring-3 mapping of
8033	* the memory.
8034	* @param phRegion Where to return the MMIO2 region handle.
8035	*
8036	*/
8037	DECLINLINE(int) PDMDevHlpPCIIORegionCreateMmio2(PPDMDEVINS pDevIns, uint32_t iPciRegion, RTGCPHYS cbRegion,
8038	PCIADDRESSSPACE enmType, const char *pszDesc,
8039	void **ppvMapping, PPGMMMIO2HANDLE phRegion)
8040
8041	{
8042	int rc = pDevIns->pHlpR3->pfnMmio2Create(pDevIns, pDevIns->apPciDevs[0], iPciRegion << 16, cbRegion, 0 /fFlags/,
8043	pszDesc, ppvMapping, phRegion);
8044	if (RT_SUCCESS(rc))
8045	rc = pDevIns->pHlpR3->pfnPCIIORegionRegister(pDevIns, pDevIns->apPciDevs[0], iPciRegion, cbRegion, enmType,
8046	PDMPCIDEV_IORGN_F_MMIO2_HANDLE \| PDMPCIDEV_IORGN_F_NEW_STYLE,
8047	phRegion, NULL /pfnCallback*/);
8048	return rc;
8049	}
8050
8051	/**
8052	* Combines PDMDevHlpMmio2Create and PDMDevHlpPCIIORegionRegisterMmio2, creating
8053	* and registering an MMIO2 region for the default PCI device.
8054	*
8055	* @returns VBox status code.
8056	* @param pDevIns The device instance to register the ports with.
8057	* @param cbRegion The size of the region in bytes.
8058	* @param iPciRegion The PCI device region.
8059	* @param enmType PCI_ADDRESS_SPACE_MEM or
8060	* PCI_ADDRESS_SPACE_MEM_PREFETCH, optionally or-ing in
8061	* PCI_ADDRESS_SPACE_BAR64 or PCI_ADDRESS_SPACE_BAR32.
8062	* @param fMmio2Flags PGMPHYS_MMIO2_FLAGS_XXX (see pgm.h).
8063	* @param pfnMapUnmap Callback for doing the mapping, optional. The
8064	* callback will be invoked holding only the PDM lock.
8065	* The device lock will _not_ be taken (due to lock
8066	* order).
8067	* @param pszDesc Pointer to description string. This must not be freed.
8068	* @param ppvMapping Where to store the address of the ring-3 mapping of
8069	* the memory.
8070	* @param phRegion Where to return the MMIO2 region handle.
8071	*
8072	*/
8073	DECLINLINE(int) PDMDevHlpPCIIORegionCreateMmio2Ex(PPDMDEVINS pDevIns, uint32_t iPciRegion, RTGCPHYS cbRegion,
8074	PCIADDRESSSPACE enmType, uint32_t fMmio2Flags, PFNPCIIOREGIONMAP pfnMapUnmap,
8075	const char pszDesc, void *ppvMapping, PPGMMMIO2HANDLE phRegion)
8076
8077	{
8078	int rc = pDevIns->pHlpR3->pfnMmio2Create(pDevIns, pDevIns->apPciDevs[0], iPciRegion << 16, cbRegion, fMmio2Flags,
8079	pszDesc, ppvMapping, phRegion);
8080	if (RT_SUCCESS(rc))
8081	rc = pDevIns->pHlpR3->pfnPCIIORegionRegister(pDevIns, pDevIns->apPciDevs[0], iPciRegion, cbRegion, enmType,
8082	PDMPCIDEV_IORGN_F_MMIO2_HANDLE \| PDMPCIDEV_IORGN_F_NEW_STYLE,
8083	*phRegion, pfnMapUnmap);
8084	return rc;
8085	}
8086
8087	/**
8088	* @copydoc PDMDEVHLPR3::pfnPCIInterceptConfigAccesses
8089	*/
8090	DECLINLINE(int) PDMDevHlpPCIInterceptConfigAccesses(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev,
8091	PFNPCICONFIGREAD pfnRead, PFNPCICONFIGWRITE pfnWrite)
8092	{
8093	return pDevIns->pHlpR3->pfnPCIInterceptConfigAccesses(pDevIns, pPciDev, pfnRead, pfnWrite);
8094	}
8095
8096	/**
8097	* @copydoc PDMDEVHLPR3::pfnPCIConfigRead
8098	*/
8099	DECLINLINE(VBOXSTRICTRC) PDMDevHlpPCIConfigRead(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t uAddress,
8100	unsigned cb, uint32_t *pu32Value)
8101	{
8102	return pDevIns->pHlpR3->pfnPCIConfigRead(pDevIns, pPciDev, uAddress, cb, pu32Value);
8103	}
8104
8105	/**
8106	* @copydoc PDMDEVHLPR3::pfnPCIConfigWrite
8107	*/
8108	DECLINLINE(VBOXSTRICTRC) PDMDevHlpPCIConfigWrite(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t uAddress,
8109	unsigned cb, uint32_t u32Value)
8110	{
8111	return pDevIns->pHlpR3->pfnPCIConfigWrite(pDevIns, pPciDev, uAddress, cb, u32Value);
8112	}
8113
8114	#endif /* IN_RING3 */
8115
8116	/**
8117	* Bus master physical memory read from the default PCI device.
8118	*
8119	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_READ_BM_DISABLED, later maybe
8120	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
8121	* @param pDevIns The device instance.
8122	* @param GCPhys Physical address start reading from.
8123	* @param pvBuf Where to put the read bits.
8124	* @param cbRead How many bytes to read.
8125	* @thread Any thread, but the call may involve the emulation thread.
8126	*/
8127	DECLINLINE(int) PDMDevHlpPCIPhysRead(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead)
8128	{
8129	return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysRead(pDevIns, NULL, GCPhys, pvBuf, cbRead, PDM_DEVHLP_PHYS_RW_F_DEFAULT);
8130	}
8131
8132	/**
8133	* Bus master physical memory read - unknown data usage.
8134	*
8135	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_READ_BM_DISABLED, later maybe
8136	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
8137	* @param pDevIns The device instance.
8138	* @param pPciDev The PCI device structure. If NULL the default
8139	* PCI device for this device instance is used.
8140	* @param GCPhys Physical address start reading from.
8141	* @param pvBuf Where to put the read bits.
8142	* @param cbRead How many bytes to read.
8143	* @thread Any thread, but the call may involve the emulation thread.
8144	*/
8145	DECLINLINE(int) PDMDevHlpPCIPhysReadEx(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead)
8146	{
8147	return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysRead(pDevIns, pPciDev, GCPhys, pvBuf, cbRead, PDM_DEVHLP_PHYS_RW_F_DEFAULT);
8148	}
8149
8150	/**
8151	* Bus master physical memory read from the default PCI device.
8152	*
8153	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_READ_BM_DISABLED, later maybe
8154	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
8155	* @param pDevIns The device instance.
8156	* @param GCPhys Physical address start reading from.
8157	* @param pvBuf Where to put the read bits.
8158	* @param cbRead How many bytes to read.
8159	* @thread Any thread, but the call may involve the emulation thread.
8160	*/
8161	DECLINLINE(int) PDMDevHlpPCIPhysReadMeta(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead)
8162	{
8163	return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysRead(pDevIns, NULL, GCPhys, pvBuf, cbRead, PDM_DEVHLP_PHYS_RW_F_DATA_META);
8164	}
8165
8166	/**
8167	* Bus master physical memory read - reads meta data processed by the device.
8168	*
8169	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_READ_BM_DISABLED, later maybe
8170	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
8171	* @param pDevIns The device instance.
8172	* @param pPciDev The PCI device structure. If NULL the default
8173	* PCI device for this device instance is used.
8174	* @param GCPhys Physical address start reading from.
8175	* @param pvBuf Where to put the read bits.
8176	* @param cbRead How many bytes to read.
8177	* @thread Any thread, but the call may involve the emulation thread.
8178	*/
8179	DECLINLINE(int) PDMDevHlpPCIPhysReadMetaEx(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead)
8180	{
8181	return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysRead(pDevIns, pPciDev, GCPhys, pvBuf, cbRead, PDM_DEVHLP_PHYS_RW_F_DATA_META);
8182	}
8183
8184	/**
8185	* Bus master physical memory read from the default PCI device - read data will not be touched by the device.
8186	*
8187	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_READ_BM_DISABLED, later maybe
8188	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
8189	* @param pDevIns The device instance.
8190	* @param GCPhys Physical address start reading from.
8191	* @param pvBuf Where to put the read bits.
8192	* @param cbRead How many bytes to read.
8193	* @thread Any thread, but the call may involve the emulation thread.
8194	*/
8195	DECLINLINE(int) PDMDevHlpPCIPhysReadUser(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead)
8196	{
8197	return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysRead(pDevIns, NULL, GCPhys, pvBuf, cbRead, PDM_DEVHLP_PHYS_RW_F_DATA_USER);
8198	}
8199
8200	/**
8201	* Bus master physical memory read - read data will not be touched by the device.
8202	*
8203	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_READ_BM_DISABLED, later maybe
8204	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
8205	* @param pDevIns The device instance.
8206	* @param pPciDev The PCI device structure. If NULL the default
8207	* PCI device for this device instance is used.
8208	* @param GCPhys Physical address start reading from.
8209	* @param pvBuf Where to put the read bits.
8210	* @param cbRead How many bytes to read.
8211	* @thread Any thread, but the call may involve the emulation thread.
8212	*/
8213	DECLINLINE(int) PDMDevHlpPCIPhysReadUserEx(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead)
8214	{
8215	return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysRead(pDevIns, pPciDev, GCPhys, pvBuf, cbRead, PDM_DEVHLP_PHYS_RW_F_DATA_USER);
8216	}
8217
8218	/**
8219	* Bus master physical memory write from the default PCI device - unknown data usage.
8220	*
8221	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_WRITE_BM_DISABLED, later maybe
8222	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
8223	* @param pDevIns The device instance.
8224	* @param GCPhys Physical address to write to.
8225	* @param pvBuf What to write.
8226	* @param cbWrite How many bytes to write.
8227	* @thread Any thread, but the call may involve the emulation thread.
8228	*/
8229	DECLINLINE(int) PDMDevHlpPCIPhysWrite(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite)
8230	{
8231	return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysWrite(pDevIns, NULL, GCPhys, pvBuf, cbWrite, PDM_DEVHLP_PHYS_RW_F_DEFAULT);
8232	}
8233
8234	/**
8235	* Bus master physical memory write - unknown data usage.
8236	*
8237	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_WRITE_BM_DISABLED, later maybe
8238	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
8239	* @param pDevIns The device instance.
8240	* @param pPciDev The PCI device structure. If NULL the default
8241	* PCI device for this device instance is used.
8242	* @param GCPhys Physical address to write to.
8243	* @param pvBuf What to write.
8244	* @param cbWrite How many bytes to write.
8245	* @thread Any thread, but the call may involve the emulation thread.
8246	*/
8247	DECLINLINE(int) PDMDevHlpPCIPhysWriteEx(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite)
8248	{
8249	return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysWrite(pDevIns, pPciDev, GCPhys, pvBuf, cbWrite, PDM_DEVHLP_PHYS_RW_F_DEFAULT);
8250	}
8251
8252	/**
8253	* Bus master physical memory write from the default PCI device.
8254	*
8255	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_WRITE_BM_DISABLED, later maybe
8256	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
8257	* @param pDevIns The device instance.
8258	* @param GCPhys Physical address to write to.
8259	* @param pvBuf What to write.
8260	* @param cbWrite How many bytes to write.
8261	* @thread Any thread, but the call may involve the emulation thread.
8262	*/
8263	DECLINLINE(int) PDMDevHlpPCIPhysWriteMeta(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite)
8264	{
8265	return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysWrite(pDevIns, NULL, GCPhys, pvBuf, cbWrite, PDM_DEVHLP_PHYS_RW_F_DATA_META);
8266	}
8267
8268	/**
8269	* Bus master physical memory write - written data was created/altered by the device.
8270	*
8271	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_WRITE_BM_DISABLED, later maybe
8272	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
8273	* @param pDevIns The device instance.
8274	* @param pPciDev The PCI device structure. If NULL the default
8275	* PCI device for this device instance is used.
8276	* @param GCPhys Physical address to write to.
8277	* @param pvBuf What to write.
8278	* @param cbWrite How many bytes to write.
8279	* @thread Any thread, but the call may involve the emulation thread.
8280	*/
8281	DECLINLINE(int) PDMDevHlpPCIPhysWriteMetaEx(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite)
8282	{
8283	return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysWrite(pDevIns, pPciDev, GCPhys, pvBuf, cbWrite, PDM_DEVHLP_PHYS_RW_F_DATA_META);
8284	}
8285
8286	/**
8287	* Bus master physical memory write from the default PCI device.
8288	*
8289	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_WRITE_BM_DISABLED, later maybe
8290	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
8291	* @param pDevIns The device instance.
8292	* @param GCPhys Physical address to write to.
8293	* @param pvBuf What to write.
8294	* @param cbWrite How many bytes to write.
8295	* @thread Any thread, but the call may involve the emulation thread.
8296	*/
8297	DECLINLINE(int) PDMDevHlpPCIPhysWriteUser(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite)
8298	{
8299	return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysWrite(pDevIns, NULL, GCPhys, pvBuf, cbWrite, PDM_DEVHLP_PHYS_RW_F_DATA_USER);
8300	}
8301
8302	/**
8303	* Bus master physical memory write - written data was not touched/created by the device.
8304	*
8305	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_WRITE_BM_DISABLED, later maybe
8306	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
8307	* @param pDevIns The device instance.
8308	* @param pPciDev The PCI device structure. If NULL the default
8309	* PCI device for this device instance is used.
8310	* @param GCPhys Physical address to write to.
8311	* @param pvBuf What to write.
8312	* @param cbWrite How many bytes to write.
8313	* @thread Any thread, but the call may involve the emulation thread.
8314	*/
8315	DECLINLINE(int) PDMDevHlpPCIPhysWriteUserEx(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite)
8316	{
8317	return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysWrite(pDevIns, pPciDev, GCPhys, pvBuf, cbWrite, PDM_DEVHLP_PHYS_RW_F_DATA_USER);
8318	}
8319
8320	#ifdef IN_RING3
8321	/**
8322	* @copydoc PDMDEVHLPR3::pfnPCIPhysGCPhys2CCPtr
8323	*/
8324	DECLINLINE(int) PDMDevHlpPCIPhysGCPhys2CCPtr(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys, uint32_t fFlags,
8325	void **ppv, PPGMPAGEMAPLOCK pLock)
8326	{
8327	return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysGCPhys2CCPtr(pDevIns, pPciDev, GCPhys, fFlags, ppv, pLock);
8328	}
8329
8330	/**
8331	* @copydoc PDMDEVHLPR3::pfnPCIPhysGCPhys2CCPtrReadOnly
8332	*/
8333	DECLINLINE(int) PDMDevHlpPCIPhysGCPhys2CCPtrReadOnly(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys, uint32_t fFlags,
8334	void const **ppv, PPGMPAGEMAPLOCK pLock)
8335	{
8336	return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysGCPhys2CCPtrReadOnly(pDevIns, pPciDev, GCPhys, fFlags, ppv, pLock);
8337	}
8338
8339	/**
8340	* @copydoc PDMDEVHLPR3::pfnPCIPhysBulkGCPhys2CCPtr
8341	*/
8342	DECLINLINE(int) PDMDevHlpPCIPhysBulkGCPhys2CCPtr(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t cPages,
8343	PCRTGCPHYS paGCPhysPages, uint32_t fFlags, void **papvPages,
8344	PPGMPAGEMAPLOCK paLocks)
8345	{
8346	return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysBulkGCPhys2CCPtr(pDevIns, pPciDev, cPages, paGCPhysPages, fFlags, papvPages,
8347	paLocks);
8348	}
8349
8350	/**
8351	* @copydoc PDMDEVHLPR3::pfnPCIPhysBulkGCPhys2CCPtrReadOnly
8352	*/
8353	DECLINLINE(int) PDMDevHlpPCIPhysBulkGCPhys2CCPtrReadOnly(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t cPages,
8354	PCRTGCPHYS paGCPhysPages, uint32_t fFlags, void const **papvPages,
8355	PPGMPAGEMAPLOCK paLocks)
8356	{
8357	return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysBulkGCPhys2CCPtrReadOnly(pDevIns, pPciDev, cPages, paGCPhysPages, fFlags,
8358	papvPages, paLocks);
8359	}
8360	#endif /* IN_RING3 */
8361
8362	/**
8363	* Sets the IRQ for the default PCI device.
8364	*
8365	* @param pDevIns The device instance.
8366	* @param iIrq IRQ number to set.
8367	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
8368	* @thread Any thread, but will involve the emulation thread.
8369	*/
8370	DECLINLINE(void) PDMDevHlpPCISetIrq(PPDMDEVINS pDevIns, int iIrq, int iLevel)
8371	{
8372	pDevIns->CTX_SUFF(pHlp)->pfnPCISetIrq(pDevIns, NULL, iIrq, iLevel);
8373	}
8374
8375	/**
8376	* @copydoc PDMDEVHLPR3::pfnPCISetIrq
8377	*/
8378	DECLINLINE(void) PDMDevHlpPCISetIrqEx(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, int iIrq, int iLevel)
8379	{
8380	pDevIns->CTX_SUFF(pHlp)->pfnPCISetIrq(pDevIns, pPciDev, iIrq, iLevel);
8381	}
8382
8383	/**
8384	* Sets the IRQ for the given PCI device, but doesn't wait for EMT to process
8385	* the request when not called from EMT.
8386	*
8387	* @param pDevIns The device instance.
8388	* @param iIrq IRQ number to set.
8389	* @param iLevel IRQ level.
8390	* @thread Any thread, but will involve the emulation thread.
8391	*/
8392	DECLINLINE(void) PDMDevHlpPCISetIrqNoWait(PPDMDEVINS pDevIns, int iIrq, int iLevel)
8393	{
8394	pDevIns->CTX_SUFF(pHlp)->pfnPCISetIrq(pDevIns, NULL, iIrq, iLevel);
8395	}
8396
8397	/**
8398	* @copydoc PDMDEVHLPR3::pfnPCISetIrqNoWait
8399	*/
8400	DECLINLINE(void) PDMDevHlpPCISetIrqNoWaitEx(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, int iIrq, int iLevel)
8401	{
8402	pDevIns->CTX_SUFF(pHlp)->pfnPCISetIrq(pDevIns, pPciDev, iIrq, iLevel);
8403	}
8404
8405	/**
8406	* @copydoc PDMDEVHLPR3::pfnISASetIrq
8407	*/
8408	DECLINLINE(void) PDMDevHlpISASetIrq(PPDMDEVINS pDevIns, int iIrq, int iLevel)
8409	{
8410	pDevIns->CTX_SUFF(pHlp)->pfnISASetIrq(pDevIns, iIrq, iLevel);
8411	}
8412
8413	/**
8414	* @copydoc PDMDEVHLPR3::pfnISASetIrqNoWait
8415	*/
8416	DECLINLINE(void) PDMDevHlpISASetIrqNoWait(PPDMDEVINS pDevIns, int iIrq, int iLevel)
8417	{
8418	pDevIns->CTX_SUFF(pHlp)->pfnISASetIrq(pDevIns, iIrq, iLevel);
8419	}
8420
8421	#ifdef IN_RING3
8422
8423	/**
8424	* @copydoc PDMDEVHLPR3::pfnDriverAttach
8425	*/
8426	DECLINLINE(int) PDMDevHlpDriverAttach(PPDMDEVINS pDevIns, uint32_t iLun, PPDMIBASE pBaseInterface, PPDMIBASE ppBaseInterface, const char pszDesc)
8427	{
8428	return pDevIns->pHlpR3->pfnDriverAttach(pDevIns, iLun, pBaseInterface, ppBaseInterface, pszDesc);
8429	}
8430
8431	/**
8432	* @copydoc PDMDEVHLPR3::pfnDriverDetach
8433	*/
8434	DECLINLINE(int) PDMDevHlpDriverDetach(PPDMDEVINS pDevIns, PPDMDRVINS pDrvIns, uint32_t fFlags)
8435	{
8436	return pDevIns->pHlpR3->pfnDriverDetach(pDevIns, pDrvIns, fFlags);
8437	}
8438
8439	/**
8440	* @copydoc PDMDEVHLPR3::pfnDriverReconfigure
8441	*/
8442	DECLINLINE(int) PDMDevHlpDriverReconfigure(PPDMDEVINS pDevIns, uint32_t iLun, uint32_t cDepth,
8443	const char * const papszDrivers, PCFGMNODE papConfigs, uint32_t fFlags)
8444	{
8445	return pDevIns->pHlpR3->pfnDriverReconfigure(pDevIns, iLun, cDepth, papszDrivers, papConfigs, fFlags);
8446	}
8447
8448	/**
8449	* Reconfigures with a single driver reattachement, no config, noflags.
8450	* @sa PDMDevHlpDriverReconfigure
8451	*/
8452	DECLINLINE(int) PDMDevHlpDriverReconfigure1(PPDMDEVINS pDevIns, uint32_t iLun, const char *pszDriver0)
8453	{
8454	return pDevIns->pHlpR3->pfnDriverReconfigure(pDevIns, iLun, 1, &pszDriver0, NULL, 0);
8455	}
8456
8457	/**
8458	* Reconfigures with a two drivers reattachement, no config, noflags.
8459	* @sa PDMDevHlpDriverReconfigure
8460	*/
8461	DECLINLINE(int) PDMDevHlpDriverReconfigure2(PPDMDEVINS pDevIns, uint32_t iLun, const char pszDriver0, const char pszDriver1)
8462	{
8463	char const * apszDrivers[2];
8464	apszDrivers[0] = pszDriver0;
8465	apszDrivers[1] = pszDriver1;
8466	return pDevIns->pHlpR3->pfnDriverReconfigure(pDevIns, iLun, 2, apszDrivers, NULL, 0);
8467	}
8468
8469	/**
8470	* @copydoc PDMDEVHLPR3::pfnQueueCreate
8471	*/
8472	DECLINLINE(int) PDMDevHlpQueueCreate(PPDMDEVINS pDevIns, size_t cbItem, uint32_t cItems, uint32_t cMilliesInterval,
8473	PFNPDMQUEUEDEV pfnCallback, bool fRZEnabled, const char pszName, PDMQUEUEHANDLE phQueue)
8474	{
8475	return pDevIns->pHlpR3->pfnQueueCreate(pDevIns, cbItem, cItems, cMilliesInterval, pfnCallback, fRZEnabled, pszName, phQueue);
8476	}
8477
8478	#endif /* IN_RING3 */
8479
8480	/**
8481	* @copydoc PDMDEVHLPR3::pfnQueueAlloc
8482	*/
8483	DECLINLINE(PPDMQUEUEITEMCORE) PDMDevHlpQueueAlloc(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue)
8484	{
8485	return pDevIns->CTX_SUFF(pHlp)->pfnQueueAlloc(pDevIns, hQueue);
8486	}
8487
8488	/**
8489	* @copydoc PDMDEVHLPR3::pfnQueueInsert
8490	*/
8491	DECLINLINE(int) PDMDevHlpQueueInsert(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue, PPDMQUEUEITEMCORE pItem)
8492	{
8493	return pDevIns->CTX_SUFF(pHlp)->pfnQueueInsert(pDevIns, hQueue, pItem);
8494	}
8495
8496	/**
8497	* @copydoc PDMDEVHLPR3::pfnQueueFlushIfNecessary
8498	*/
8499	DECLINLINE(bool) PDMDevHlpQueueFlushIfNecessary(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue)
8500	{
8501	return pDevIns->CTX_SUFF(pHlp)->pfnQueueFlushIfNecessary(pDevIns, hQueue);
8502	}
8503
8504	#ifdef IN_RING3
8505	/**
8506	* @copydoc PDMDEVHLPR3::pfnTaskCreate
8507	*/
8508	DECLINLINE(int) PDMDevHlpTaskCreate(PPDMDEVINS pDevIns, uint32_t fFlags, const char *pszName,
8509	PFNPDMTASKDEV pfnCallback, void pvUser, PDMTASKHANDLE phTask)
8510	{
8511	return pDevIns->pHlpR3->pfnTaskCreate(pDevIns, fFlags, pszName, pfnCallback, pvUser, phTask);
8512	}
8513	#endif
8514
8515	/**
8516	* @copydoc PDMDEVHLPR3::pfnTaskTrigger
8517	*/
8518	DECLINLINE(int) PDMDevHlpTaskTrigger(PPDMDEVINS pDevIns, PDMTASKHANDLE hTask)
8519	{
8520	return pDevIns->CTX_SUFF(pHlp)->pfnTaskTrigger(pDevIns, hTask);
8521	}
8522
8523	#ifdef IN_RING3
8524
8525	/**
8526	* @copydoc PDMDEVHLPR3::pfnSUPSemEventCreate
8527	*/
8528	DECLINLINE(int) PDMDevHlpSUPSemEventCreate(PPDMDEVINS pDevIns, PSUPSEMEVENT phEvent)
8529	{
8530	return pDevIns->pHlpR3->pfnSUPSemEventCreate(pDevIns, phEvent);
8531	}
8532
8533	/**
8534	* @copydoc PDMDEVHLPR3::pfnSUPSemEventClose
8535	*/
8536	DECLINLINE(int) PDMDevHlpSUPSemEventClose(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent)
8537	{
8538	return pDevIns->pHlpR3->pfnSUPSemEventClose(pDevIns, hEvent);
8539	}
8540
8541	#endif /* IN_RING3 */
8542
8543	/**
8544	* @copydoc PDMDEVHLPR3::pfnSUPSemEventSignal
8545	*/
8546	DECLINLINE(int) PDMDevHlpSUPSemEventSignal(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent)
8547	{
8548	return pDevIns->CTX_SUFF(pHlp)->pfnSUPSemEventSignal(pDevIns, hEvent);
8549	}
8550
8551	/**
8552	* @copydoc PDMDEVHLPR3::pfnSUPSemEventWaitNoResume
8553	*/
8554	DECLINLINE(int) PDMDevHlpSUPSemEventWaitNoResume(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent, uint32_t cMillies)
8555	{
8556	return pDevIns->CTX_SUFF(pHlp)->pfnSUPSemEventWaitNoResume(pDevIns, hEvent, cMillies);
8557	}
8558
8559	/**
8560	* @copydoc PDMDEVHLPR3::pfnSUPSemEventWaitNsAbsIntr
8561	*/
8562	DECLINLINE(int) PDMDevHlpSUPSemEventWaitNsAbsIntr(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent, uint64_t uNsTimeout)
8563	{
8564	return pDevIns->CTX_SUFF(pHlp)->pfnSUPSemEventWaitNsAbsIntr(pDevIns, hEvent, uNsTimeout);
8565	}
8566
8567	/**
8568	* @copydoc PDMDEVHLPR3::pfnSUPSemEventWaitNsRelIntr
8569	*/
8570	DECLINLINE(int) PDMDevHlpSUPSemEventWaitNsRelIntr(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent, uint64_t cNsTimeout)
8571	{
8572	return pDevIns->CTX_SUFF(pHlp)->pfnSUPSemEventWaitNsRelIntr(pDevIns, hEvent, cNsTimeout);
8573	}
8574
8575	/**
8576	* @copydoc PDMDEVHLPR3::pfnSUPSemEventGetResolution
8577	*/
8578	DECLINLINE(uint32_t) PDMDevHlpSUPSemEventGetResolution(PPDMDEVINS pDevIns)
8579	{
8580	return pDevIns->CTX_SUFF(pHlp)->pfnSUPSemEventGetResolution(pDevIns);
8581	}
8582
8583	#ifdef IN_RING3
8584
8585	/**
8586	* @copydoc PDMDEVHLPR3::pfnSUPSemEventMultiCreate
8587	*/
8588	DECLINLINE(int) PDMDevHlpSUPSemEventMultiCreate(PPDMDEVINS pDevIns, PSUPSEMEVENTMULTI phEventMulti)
8589	{
8590	return pDevIns->pHlpR3->pfnSUPSemEventMultiCreate(pDevIns, phEventMulti);
8591	}
8592
8593	/**
8594	* @copydoc PDMDEVHLPR3::pfnSUPSemEventMultiClose
8595	*/
8596	DECLINLINE(int) PDMDevHlpSUPSemEventMultiClose(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti)
8597	{
8598	return pDevIns->pHlpR3->pfnSUPSemEventMultiClose(pDevIns, hEventMulti);
8599	}
8600
8601	#endif /* IN_RING3 */
8602
8603	/**
8604	* @copydoc PDMDEVHLPR3::pfnSUPSemEventMultiSignal
8605	*/
8606	DECLINLINE(int) PDMDevHlpSUPSemEventMultiSignal(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti)
8607	{
8608	return pDevIns->CTX_SUFF(pHlp)->pfnSUPSemEventMultiSignal(pDevIns, hEventMulti);
8609	}
8610
8611	/**
8612	* @copydoc PDMDEVHLPR3::pfnSUPSemEventMultiReset
8613	*/
8614	DECLINLINE(int) PDMDevHlpSUPSemEventMultiReset(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti)
8615	{
8616	return pDevIns->CTX_SUFF(pHlp)->pfnSUPSemEventMultiReset(pDevIns, hEventMulti);
8617	}
8618
8619	/**
8620	* @copydoc PDMDEVHLPR3::pfnSUPSemEventMultiWaitNoResume
8621	*/
8622	DECLINLINE(int) PDMDevHlpSUPSemEventMultiWaitNoResume(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti, uint32_t cMillies)
8623	{
8624	return pDevIns->CTX_SUFF(pHlp)->pfnSUPSemEventMultiWaitNsRelIntr(pDevIns, hEventMulti, cMillies);
8625	}
8626
8627	/**
8628	* @copydoc PDMDEVHLPR3::pfnSUPSemEventMultiWaitNsAbsIntr
8629	*/
8630	DECLINLINE(int) PDMDevHlpSUPSemEventMultiWaitNsAbsIntr(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti, uint64_t uNsTimeout)
8631	{
8632	return pDevIns->CTX_SUFF(pHlp)->pfnSUPSemEventMultiWaitNsAbsIntr(pDevIns, hEventMulti, uNsTimeout);
8633	}
8634
8635	/**
8636	* @copydoc PDMDEVHLPR3::pfnSUPSemEventMultiWaitNsRelIntr
8637	*/
8638	DECLINLINE(int) PDMDevHlpSUPSemEventMultiWaitNsRelIntr(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti, uint64_t cNsTimeout)
8639	{
8640	return pDevIns->CTX_SUFF(pHlp)->pfnSUPSemEventMultiWaitNsRelIntr(pDevIns, hEventMulti, cNsTimeout);
8641	}
8642
8643	/**
8644	* @copydoc PDMDEVHLPR3::pfnSUPSemEventMultiGetResolution
8645	*/
8646	DECLINLINE(uint32_t) PDMDevHlpSUPSemEventMultiGetResolution(PPDMDEVINS pDevIns)
8647	{
8648	return pDevIns->CTX_SUFF(pHlp)->pfnSUPSemEventMultiGetResolution(pDevIns);
8649	}
8650
8651	#ifdef IN_RING3
8652
8653	/**
8654	* Initializes a PDM critical section.
8655	*
8656	* The PDM critical sections are derived from the IPRT critical sections, but
8657	* works in RC and R0 as well.
8658	*
8659	* @returns VBox status code.
8660	* @param pDevIns The device instance.
8661	* @param pCritSect Pointer to the critical section.
8662	* @param SRC_POS Use RT_SRC_POS.
8663	* @param pszNameFmt Format string for naming the critical section.
8664	* For statistics and lock validation.
8665	* @param ... Arguments for the format string.
8666	*/
8667	DECLINLINE(int) RT_IPRT_FORMAT_ATTR(6, 7) PDMDevHlpCritSectInit(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, RT_SRC_POS_DECL,
8668	const char *pszNameFmt, ...)
8669	{
8670	int rc;
8671	va_list va;
8672	va_start(va, pszNameFmt);
8673	rc = pDevIns->pHlpR3->pfnCritSectInit(pDevIns, pCritSect, RT_SRC_POS_ARGS, pszNameFmt, va);
8674	va_end(va);
8675	return rc;
8676	}
8677
8678	#endif /* IN_RING3 */
8679
8680	/**
8681	* @copydoc PDMDEVHLPR3::pfnCritSectGetNop
8682	*/
8683	DECLINLINE(PPDMCRITSECT) PDMDevHlpCritSectGetNop(PPDMDEVINS pDevIns)
8684	{
8685	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectGetNop(pDevIns);
8686	}
8687
8688	/**
8689	* @copydoc PDMDEVHLPR3::pfnSetDeviceCritSect
8690	*/
8691	DECLINLINE(int) PDMDevHlpSetDeviceCritSect(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect)
8692	{
8693	return pDevIns->CTX_SUFF(pHlp)->pfnSetDeviceCritSect(pDevIns, pCritSect);
8694	}
8695
8696	/**
8697	* Enters a PDM critical section.
8698	*
8699	* @returns VINF_SUCCESS if entered successfully.
8700	* @returns rcBusy when encountering a busy critical section in RC/R0.
8701	* @retval VERR_SEM_DESTROYED if the critical section is delete before or
8702	* during the operation.
8703	*
8704	* @param pDevIns The device instance.
8705	* @param pCritSect The PDM critical section to enter.
8706	* @param rcBusy The status code to return when we're in RC or R0
8707	* and the section is busy. Pass VINF_SUCCESS to
8708	* acquired the critical section thru a ring-3
8709	* call if necessary.
8710	*
8711	* @note Even callers setting @a rcBusy to VINF_SUCCESS must either handle
8712	* possible failures in ring-0 or at least apply
8713	* PDM_CRITSECT_RELEASE_ASSERT_RC_DEV() to the return value of this
8714	* function.
8715	*
8716	* @sa PDMCritSectEnter
8717	*/
8718	DECLINLINE(DECL_CHECK_RETURN(int)) PDMDevHlpCritSectEnter(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, int rcBusy)
8719	{
8720	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectEnter(pDevIns, pCritSect, rcBusy);
8721	}
8722
8723	/**
8724	* Enters a PDM critical section, with location information for debugging.
8725	*
8726	* @returns VINF_SUCCESS if entered successfully.
8727	* @returns rcBusy when encountering a busy critical section in RC/R0.
8728	* @retval VERR_SEM_DESTROYED if the critical section is delete before or
8729	* during the operation.
8730	*
8731	* @param pDevIns The device instance.
8732	* @param pCritSect The PDM critical section to enter.
8733	* @param rcBusy The status code to return when we're in RC or R0
8734	* and the section is busy. Pass VINF_SUCCESS to
8735	* acquired the critical section thru a ring-3
8736	* call if necessary.
8737	* @param uId Some kind of locking location ID. Typically a
8738	* return address up the stack. Optional (0).
8739	* @param SRC_POS The source position where to lock is being
8740	* acquired from. Optional.
8741	* @sa PDMCritSectEnterDebug
8742	*/
8743	DECLINLINE(DECL_CHECK_RETURN(int))
8744	PDMDevHlpCritSectEnterDebug(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, int rcBusy, RTHCUINTPTR uId, RT_SRC_POS_DECL)
8745	{
8746	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectEnterDebug(pDevIns, pCritSect, rcBusy, uId, RT_SRC_POS_ARGS);
8747	}
8748
8749	/**
8750	* Try enter a critical section.
8751	*
8752	* @retval VINF_SUCCESS on success.
8753	* @retval VERR_SEM_BUSY if the critsect was owned.
8754	* @retval VERR_SEM_NESTED if nested enter on a no nesting section. (Asserted.)
8755	* @retval VERR_SEM_DESTROYED if the critical section is delete before or
8756	* during the operation.
8757	*
8758	* @param pDevIns The device instance.
8759	* @param pCritSect The critical section.
8760	* @sa PDMCritSectTryEnter
8761	*/
8762	DECLINLINE(DECL_CHECK_RETURN(int))
8763	PDMDevHlpCritSectTryEnter(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect)
8764	{
8765	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectTryEnter(pDevIns, pCritSect);
8766	}
8767
8768	/**
8769	* Try enter a critical section, with location information for debugging.
8770	*
8771	* @retval VINF_SUCCESS on success.
8772	* @retval VERR_SEM_BUSY if the critsect was owned.
8773	* @retval VERR_SEM_NESTED if nested enter on a no nesting section. (Asserted.)
8774	* @retval VERR_SEM_DESTROYED if the critical section is delete before or
8775	* during the operation.
8776	*
8777	* @param pDevIns The device instance.
8778	* @param pCritSect The critical section.
8779	* @param uId Some kind of locking location ID. Typically a
8780	* return address up the stack. Optional (0).
8781	* @param SRC_POS The source position where to lock is being
8782	* acquired from. Optional.
8783	* @sa PDMCritSectTryEnterDebug
8784	*/
8785	DECLINLINE(DECL_CHECK_RETURN(int))
8786	PDMDevHlpCritSectTryEnterDebug(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, RTHCUINTPTR uId, RT_SRC_POS_DECL)
8787	{
8788	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectTryEnterDebug(pDevIns, pCritSect, uId, RT_SRC_POS_ARGS);
8789	}
8790
8791	/**
8792	* Leaves a critical section entered with PDMCritSectEnter().
8793	*
8794	* @returns Indication whether we really exited the critical section.
8795	* @retval VINF_SUCCESS if we really exited.
8796	* @retval VINF_SEM_NESTED if we only reduced the nesting count.
8797	* @retval VERR_NOT_OWNER if you somehow ignore release assertions.
8798	*
8799	* @param pDevIns The device instance.
8800	* @param pCritSect The PDM critical section to leave.
8801	* @sa PDMCritSectLeave
8802	*/
8803	DECLINLINE(int) PDMDevHlpCritSectLeave(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect)
8804	{
8805	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectLeave(pDevIns, pCritSect);
8806	}
8807
8808	/**
8809	* @see PDMCritSectIsOwner
8810	*/
8811	DECLINLINE(bool) PDMDevHlpCritSectIsOwner(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect)
8812	{
8813	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectIsOwner(pDevIns, pCritSect);
8814	}
8815
8816	/**
8817	* @see PDMCritSectIsInitialized
8818	*/
8819	DECLINLINE(bool) PDMDevHlpCritSectIsInitialized(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect)
8820	{
8821	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectIsInitialized(pDevIns, pCritSect);
8822	}
8823
8824	/**
8825	* @see PDMCritSectHasWaiters
8826	*/
8827	DECLINLINE(bool) PDMDevHlpCritSectHasWaiters(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect)
8828	{
8829	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectHasWaiters(pDevIns, pCritSect);
8830	}
8831
8832	/**
8833	* @see PDMCritSectGetRecursion
8834	*/
8835	DECLINLINE(uint32_t) PDMDevHlpCritSectGetRecursion(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect)
8836	{
8837	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectGetRecursion(pDevIns, pCritSect);
8838	}
8839
8840	#if defined(IN_RING3) \|\| defined(IN_RING0)
8841	/**
8842	* @see PDMHCCritSectScheduleExitEvent
8843	*/
8844	DECLINLINE(int) PDMDevHlpCritSectScheduleExitEvent(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, SUPSEMEVENT hEventToSignal)
8845	{
8846	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectScheduleExitEvent(pDevIns, pCritSect, hEventToSignal);
8847	}
8848	#endif
8849
8850	/* Strict build: Remap the two enter calls to the debug versions. */
8851	#ifdef VBOX_STRICT
8852	# ifdef IPRT_INCLUDED_asm_h
8853	# define PDMDevHlpCritSectEnter(pDevIns, pCritSect, rcBusy) PDMDevHlpCritSectEnterDebug((pDevIns), (pCritSect), (rcBusy), (uintptr_t)ASMReturnAddress(), RT_SRC_POS)
8854	# define PDMDevHlpCritSectTryEnter(pDevIns, pCritSect) PDMDevHlpCritSectTryEnterDebug((pDevIns), (pCritSect), (uintptr_t)ASMReturnAddress(), RT_SRC_POS)
8855	# else
8856	# define PDMDevHlpCritSectEnter(pDevIns, pCritSect, rcBusy) PDMDevHlpCritSectEnterDebug((pDevIns), (pCritSect), (rcBusy), 0, RT_SRC_POS)
8857	# define PDMDevHlpCritSectTryEnter(pDevIns, pCritSect) PDMDevHlpCritSectTryEnterDebug((pDevIns), (pCritSect), 0, RT_SRC_POS)
8858	# endif
8859	#endif
8860
8861	#if defined(IN_RING3) \|\| defined(DOXYGEN_RUNNING)
8862
8863	/**
8864	* Deletes the critical section.
8865	*
8866	* @returns VBox status code.
8867	* @param pDevIns The device instance.
8868	* @param pCritSect The PDM critical section to destroy.
8869	* @sa PDMR3CritSectDelete
8870	*/
8871	DECLINLINE(int) PDMDevHlpCritSectDelete(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect)
8872	{
8873	return pDevIns->pHlpR3->pfnCritSectDelete(pDevIns, pCritSect);
8874	}
8875
8876	/**
8877	* Initializes a PDM read/write critical section.
8878	*
8879	* The PDM read/write critical sections are derived from the IPRT critical
8880	* sections, but works in RC and R0 as well.
8881	*
8882	* @returns VBox status code.
8883	* @param pDevIns The device instance.
8884	* @param pCritSect Pointer to the read/write critical section.
8885	* @param SRC_POS Use RT_SRC_POS.
8886	* @param pszNameFmt Format string for naming the critical section.
8887	* For statistics and lock validation.
8888	* @param ... Arguments for the format string.
8889	*/
8890	DECLINLINE(int) RT_IPRT_FORMAT_ATTR(6, 7) PDMDevHlpCritSectRwInit(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect, RT_SRC_POS_DECL,
8891	const char *pszNameFmt, ...)
8892	{
8893	int rc;
8894	va_list va;
8895	va_start(va, pszNameFmt);
8896	rc = pDevIns->pHlpR3->pfnCritSectRwInit(pDevIns, pCritSect, RT_SRC_POS_ARGS, pszNameFmt, va);
8897	va_end(va);
8898	return rc;
8899	}
8900
8901	/**
8902	* Deletes the read/write critical section.
8903	*
8904	* @returns VBox status code.
8905	* @param pDevIns The device instance.
8906	* @param pCritSect The PDM read/write critical section to destroy.
8907	* @sa PDMR3CritSectRwDelete
8908	*/
8909	DECLINLINE(int) PDMDevHlpCritSectRwDelete(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect)
8910	{
8911	return pDevIns->pHlpR3->pfnCritSectRwDelete(pDevIns, pCritSect);
8912	}
8913
8914	#endif /* IN_RING3 */
8915
8916	/**
8917	* @sa PDMCritSectRwEnterShared, PDM_CRITSECT_RELEASE_ASSERT_RC_DEV
8918	*/
8919	DECLINLINE(DECL_CHECK_RETURN(int)) PDMDevHlpCritSectRwEnterShared(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect, int rcBusy)
8920	{
8921	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectRwEnterShared(pDevIns, pCritSect, rcBusy);
8922	}
8923
8924	/**
8925	* @sa PDMCritSectRwEnterSharedDebug, PDM_CRITSECT_RELEASE_ASSERT_RC_DEV
8926	*/
8927	DECLINLINE(DECL_CHECK_RETURN(int))
8928	PDMDevHlpCritSectRwEnterSharedDebug(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect, int rcBusy, RTHCUINTPTR uId, RT_SRC_POS_DECL)
8929	{
8930	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectRwEnterSharedDebug(pDevIns, pCritSect, rcBusy, uId, RT_SRC_POS_ARGS);
8931	}
8932
8933	/**
8934	* @sa PDMCritSectRwTryEnterShared
8935	*/
8936	DECLINLINE(DECL_CHECK_RETURN(int))
8937	PDMDevHlpCritSectRwTryEnterShared(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect)
8938	{
8939	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectRwTryEnterShared(pDevIns, pCritSect);
8940	}
8941
8942	/**
8943	* @sa PDMCritSectRwTryEnterSharedDebug
8944	*/
8945	DECLINLINE(DECL_CHECK_RETURN(int))
8946	PDMDevHlpCritSectRwTryEnterSharedDebug(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect, RTHCUINTPTR uId, RT_SRC_POS_DECL)
8947	{
8948	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectRwTryEnterSharedDebug(pDevIns, pCritSect, uId, RT_SRC_POS_ARGS);
8949	}
8950
8951	/**
8952	* @sa PDMCritSectRwLeaveShared
8953	*/
8954	DECLINLINE(int) PDMDevHlpCritSectRwLeaveShared(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect)
8955	{
8956	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectRwLeaveShared(pDevIns, pCritSect);
8957	}
8958
8959	/**
8960	* @sa PDMCritSectRwEnterExcl, PDM_CRITSECT_RELEASE_ASSERT_RC_DEV
8961	*/
8962	DECLINLINE(DECL_CHECK_RETURN(int)) PDMDevHlpCritSectRwEnterExcl(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect, int rcBusy)
8963	{
8964	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectRwEnterExcl(pDevIns, pCritSect, rcBusy);
8965	}
8966
8967	/**
8968	* @sa PDMCritSectRwEnterExclDebug, PDM_CRITSECT_RELEASE_ASSERT_RC_DEV
8969	*/
8970	DECLINLINE(DECL_CHECK_RETURN(int))
8971	PDMDevHlpCritSectRwEnterExclDebug(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect, int rcBusy, RTHCUINTPTR uId, RT_SRC_POS_DECL)
8972	{
8973	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectRwEnterExclDebug(pDevIns, pCritSect, rcBusy, uId, RT_SRC_POS_ARGS);
8974	}
8975
8976	/**
8977	* @sa PDMCritSectRwTryEnterExcl
8978	*/
8979	DECLINLINE(DECL_CHECK_RETURN(int))
8980	PDMDevHlpCritSectRwTryEnterExcl(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect)
8981	{
8982	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectRwTryEnterExcl(pDevIns, pCritSect);
8983	}
8984
8985	/**
8986	* @sa PDMCritSectRwTryEnterExclDebug
8987	*/
8988	DECLINLINE(DECL_CHECK_RETURN(int))
8989	PDMDevHlpCritSectRwTryEnterExclDebug(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect, RTHCUINTPTR uId, RT_SRC_POS_DECL)
8990	{
8991	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectRwTryEnterExclDebug(pDevIns, pCritSect, uId, RT_SRC_POS_ARGS);
8992	}
8993
8994	/**
8995	* @sa PDMCritSectRwLeaveExcl
8996	*/
8997	DECLINLINE(int) PDMDevHlpCritSectRwLeaveExcl(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect)
8998	{
8999	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectRwLeaveExcl(pDevIns, pCritSect);
9000	}
9001
9002	/**
9003	* @see PDMCritSectRwIsWriteOwner
9004	*/
9005	DECLINLINE(bool) PDMDevHlpCritSectRwIsWriteOwner(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect)
9006	{
9007	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectRwIsWriteOwner(pDevIns, pCritSect);
9008	}
9009
9010	/**
9011	* @see PDMCritSectRwIsReadOwner
9012	*/
9013	DECLINLINE(bool) PDMDevHlpCritSectRwIsReadOwner(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect, bool fWannaHear)
9014	{
9015	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectRwIsReadOwner(pDevIns, pCritSect, fWannaHear);
9016	}
9017
9018	/**
9019	* @see PDMCritSectRwGetWriteRecursion
9020	*/
9021	DECLINLINE(uint32_t) PDMDevHlpCritSectRwGetWriteRecursion(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect)
9022	{
9023	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectRwGetWriteRecursion(pDevIns, pCritSect);
9024	}
9025
9026	/**
9027	* @see PDMCritSectRwGetWriterReadRecursion
9028	*/
9029	DECLINLINE(uint32_t) PDMDevHlpCritSectRwGetWriterReadRecursion(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect)
9030	{
9031	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectRwGetWriterReadRecursion(pDevIns, pCritSect);
9032	}
9033
9034	/**
9035	* @see PDMCritSectRwGetReadCount
9036	*/
9037	DECLINLINE(uint32_t) PDMDevHlpCritSectRwGetReadCount(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect)
9038	{
9039	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectRwGetReadCount(pDevIns, pCritSect);
9040	}
9041
9042	/**
9043	* @see PDMCritSectRwIsInitialized
9044	*/
9045	DECLINLINE(bool) PDMDevHlpCritSectRwIsInitialized(PPDMDEVINS pDevIns, PPDMCRITSECTRW pCritSect)
9046	{
9047	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectRwIsInitialized(pDevIns, pCritSect);
9048	}
9049
9050	/* Strict build: Remap the two enter calls to the debug versions. */
9051	#ifdef VBOX_STRICT
9052	# ifdef IPRT_INCLUDED_asm_h
9053	# define PDMDevHlpCritSectRwEnterShared(pDevIns, pCritSect, rcBusy) PDMDevHlpCritSectRwEnterSharedDebug((pDevIns), (pCritSect), (rcBusy), (uintptr_t)ASMReturnAddress(), RT_SRC_POS)
9054	# define PDMDevHlpCritSectRwTryEnterShared(pDevIns, pCritSect) PDMDevHlpCritSectRwTryEnterSharedDebug((pDevIns), (pCritSect), (uintptr_t)ASMReturnAddress(), RT_SRC_POS)
9055	# define PDMDevHlpCritSectRwEnterExcl(pDevIns, pCritSect, rcBusy) PDMDevHlpCritSectRwEnterExclDebug((pDevIns), (pCritSect), (rcBusy), (uintptr_t)ASMReturnAddress(), RT_SRC_POS)
9056	# define PDMDevHlpCritSectRwTryEnterExcl(pDevIns, pCritSect) PDMDevHlpCritSectRwTryEnterExclDebug((pDevIns), (pCritSect), (uintptr_t)ASMReturnAddress(), RT_SRC_POS)
9057	# else
9058	# define PDMDevHlpCritSectRwEnterShared(pDevIns, pCritSect, rcBusy) PDMDevHlpCritSectRwEnterSharedDebug((pDevIns), (pCritSect), (rcBusy), 0, RT_SRC_POS)
9059	# define PDMDevHlpCritSectRwTryEnterShared(pDevIns, pCritSect) PDMDevHlpCritSectRwTryEnterSharedDebug((pDevIns), (pCritSect), 0, RT_SRC_POS)
9060	# define PDMDevHlpCritSectRwEnterExcl(pDevIns, pCritSect, rcBusy) PDMDevHlpCritSectRwEnterExclDebug((pDevIns), (pCritSect), (rcBusy), 0, RT_SRC_POS)
9061	# define PDMDevHlpCritSectRwTryEnterExcl(pDevIns, pCritSect) PDMDevHlpCritSectRwTryEnterExclDebug((pDevIns), (pCritSect), 0, RT_SRC_POS)
9062	# endif
9063	#endif
9064
9065	#if defined(IN_RING3) \|\| defined(DOXYGEN_RUNNING)
9066
9067	/**
9068	* @copydoc PDMDEVHLPR3::pfnThreadCreate
9069	*/
9070	DECLINLINE(int) PDMDevHlpThreadCreate(PPDMDEVINS pDevIns, PPPDMTHREAD ppThread, void *pvUser, PFNPDMTHREADDEV pfnThread,
9071	PFNPDMTHREADWAKEUPDEV pfnWakeup, size_t cbStack, RTTHREADTYPE enmType, const char *pszName)
9072	{
9073	return pDevIns->pHlpR3->pfnThreadCreate(pDevIns, ppThread, pvUser, pfnThread, pfnWakeup, cbStack, enmType, pszName);
9074	}
9075
9076	/**
9077	* @copydoc PDMR3ThreadDestroy
9078	* @param pDevIns The device instance.
9079	*/
9080	DECLINLINE(int) PDMDevHlpThreadDestroy(PPDMDEVINS pDevIns, PPDMTHREAD pThread, int *pRcThread)
9081	{
9082	return pDevIns->pHlpR3->pfnThreadDestroy(pThread, pRcThread);
9083	}
9084
9085	/**
9086	* @copydoc PDMR3ThreadIAmSuspending
9087	* @param pDevIns The device instance.
9088	*/
9089	DECLINLINE(int) PDMDevHlpThreadIAmSuspending(PPDMDEVINS pDevIns, PPDMTHREAD pThread)
9090	{
9091	return pDevIns->pHlpR3->pfnThreadIAmSuspending(pThread);
9092	}
9093
9094	/**
9095	* @copydoc PDMR3ThreadIAmRunning
9096	* @param pDevIns The device instance.
9097	*/
9098	DECLINLINE(int) PDMDevHlpThreadIAmRunning(PPDMDEVINS pDevIns, PPDMTHREAD pThread)
9099	{
9100	return pDevIns->pHlpR3->pfnThreadIAmRunning(pThread);
9101	}
9102
9103	/**
9104	* @copydoc PDMR3ThreadSleep
9105	* @param pDevIns The device instance.
9106	*/
9107	DECLINLINE(int) PDMDevHlpThreadSleep(PPDMDEVINS pDevIns, PPDMTHREAD pThread, RTMSINTERVAL cMillies)
9108	{
9109	return pDevIns->pHlpR3->pfnThreadSleep(pThread, cMillies);
9110	}
9111
9112	/**
9113	* @copydoc PDMR3ThreadSuspend
9114	* @param pDevIns The device instance.
9115	*/
9116	DECLINLINE(int) PDMDevHlpThreadSuspend(PPDMDEVINS pDevIns, PPDMTHREAD pThread)
9117	{
9118	return pDevIns->pHlpR3->pfnThreadSuspend(pThread);
9119	}
9120
9121	/**
9122	* @copydoc PDMR3ThreadResume
9123	* @param pDevIns The device instance.
9124	*/
9125	DECLINLINE(int) PDMDevHlpThreadResume(PPDMDEVINS pDevIns, PPDMTHREAD pThread)
9126	{
9127	return pDevIns->pHlpR3->pfnThreadResume(pThread);
9128	}
9129
9130	/**
9131	* @copydoc PDMDEVHLPR3::pfnSetAsyncNotification
9132	*/
9133	DECLINLINE(int) PDMDevHlpSetAsyncNotification(PPDMDEVINS pDevIns, PFNPDMDEVASYNCNOTIFY pfnAsyncNotify)
9134	{
9135	return pDevIns->pHlpR3->pfnSetAsyncNotification(pDevIns, pfnAsyncNotify);
9136	}
9137
9138	/**
9139	* @copydoc PDMDEVHLPR3::pfnAsyncNotificationCompleted
9140	*/
9141	DECLINLINE(void) PDMDevHlpAsyncNotificationCompleted(PPDMDEVINS pDevIns)
9142	{
9143	pDevIns->pHlpR3->pfnAsyncNotificationCompleted(pDevIns);
9144	}
9145
9146	/**
9147	* @copydoc PDMDEVHLPR3::pfnA20Set
9148	*/
9149	DECLINLINE(void) PDMDevHlpA20Set(PPDMDEVINS pDevIns, bool fEnable)
9150	{
9151	pDevIns->pHlpR3->pfnA20Set(pDevIns, fEnable);
9152	}
9153
9154	/**
9155	* @copydoc PDMDEVHLPR3::pfnRTCRegister
9156	*/
9157	DECLINLINE(int) PDMDevHlpRTCRegister(PPDMDEVINS pDevIns, PCPDMRTCREG pRtcReg, PCPDMRTCHLP *ppRtcHlp)
9158	{
9159	return pDevIns->pHlpR3->pfnRTCRegister(pDevIns, pRtcReg, ppRtcHlp);
9160	}
9161
9162	/**
9163	* @copydoc PDMDEVHLPR3::pfnPCIBusRegister
9164	*/
9165	DECLINLINE(int) PDMDevHlpPCIBusRegister(PPDMDEVINS pDevIns, PPDMPCIBUSREGR3 pPciBusReg, PCPDMPCIHLPR3 ppPciHlp, uint32_t piBus)
9166	{
9167	return pDevIns->pHlpR3->pfnPCIBusRegister(pDevIns, pPciBusReg, ppPciHlp, piBus);
9168	}
9169
9170	/**
9171	* @copydoc PDMDEVHLPR3::pfnIommuRegister
9172	*/
9173	DECLINLINE(int) PDMDevHlpIommuRegister(PPDMDEVINS pDevIns, PPDMIOMMUREGR3 pIommuReg, PCPDMIOMMUHLPR3 ppIommuHlp, uint32_t pidxIommu)
9174	{
9175	return pDevIns->pHlpR3->pfnIommuRegister(pDevIns, pIommuReg, ppIommuHlp, pidxIommu);
9176	}
9177
9178	/**
9179	* @copydoc PDMDEVHLPR3::pfnPICRegister
9180	*/
9181	DECLINLINE(int) PDMDevHlpPICRegister(PPDMDEVINS pDevIns, PPDMPICREG pPicReg, PCPDMPICHLP *ppPicHlp)
9182	{
9183	return pDevIns->pHlpR3->pfnPICRegister(pDevIns, pPicReg, ppPicHlp);
9184	}
9185
9186	/**
9187	* @copydoc PDMDEVHLPR3::pfnIcRegister
9188	*/
9189	DECLINLINE(int) PDMDevHlpIcRegister(PPDMDEVINS pDevIns)
9190	{
9191	return pDevIns->pHlpR3->pfnIcRegister(pDevIns);
9192	}
9193
9194	/**
9195	* @copydoc PDMDEVHLPR3::pfnIoApicRegister
9196	*/
9197	DECLINLINE(int) PDMDevHlpIoApicRegister(PPDMDEVINS pDevIns, PPDMIOAPICREG pIoApicReg, PCPDMIOAPICHLP *ppIoApicHlp)
9198	{
9199	return pDevIns->pHlpR3->pfnIoApicRegister(pDevIns, pIoApicReg, ppIoApicHlp);
9200	}
9201
9202	/**
9203	* @copydoc PDMDEVHLPR3::pfnHpetRegister
9204	*/
9205	DECLINLINE(int) PDMDevHlpHpetRegister(PPDMDEVINS pDevIns, PPDMHPETREG pHpetReg, PCPDMHPETHLPR3 *ppHpetHlpR3)
9206	{
9207	return pDevIns->pHlpR3->pfnHpetRegister(pDevIns, pHpetReg, ppHpetHlpR3);
9208	}
9209
9210	/**
9211	* @copydoc PDMDEVHLPR3::pfnPciRawRegister
9212	*/
9213	DECLINLINE(int) PDMDevHlpPciRawRegister(PPDMDEVINS pDevIns, PPDMPCIRAWREG pPciRawReg, PCPDMPCIRAWHLPR3 *ppPciRawHlpR3)
9214	{
9215	return pDevIns->pHlpR3->pfnPciRawRegister(pDevIns, pPciRawReg, ppPciRawHlpR3);
9216	}
9217
9218	/**
9219	* @copydoc PDMDEVHLPR3::pfnDMACRegister
9220	*/
9221	DECLINLINE(int) PDMDevHlpDMACRegister(PPDMDEVINS pDevIns, PPDMDMACREG pDmacReg, PCPDMDMACHLP *ppDmacHlp)
9222	{
9223	return pDevIns->pHlpR3->pfnDMACRegister(pDevIns, pDmacReg, ppDmacHlp);
9224	}
9225
9226	/**
9227	* @copydoc PDMDEVHLPR3::pfnDMARegister
9228	*/
9229	DECLINLINE(int) PDMDevHlpDMARegister(PPDMDEVINS pDevIns, unsigned uChannel, PFNDMATRANSFERHANDLER pfnTransferHandler, void *pvUser)
9230	{
9231	return pDevIns->pHlpR3->pfnDMARegister(pDevIns, uChannel, pfnTransferHandler, pvUser);
9232	}
9233
9234	/**
9235	* @copydoc PDMDEVHLPR3::pfnDMAReadMemory
9236	*/
9237	DECLINLINE(int) PDMDevHlpDMAReadMemory(PPDMDEVINS pDevIns, unsigned uChannel, void pvBuffer, uint32_t off, uint32_t cbBlock, uint32_t pcbRead)
9238	{
9239	return pDevIns->pHlpR3->pfnDMAReadMemory(pDevIns, uChannel, pvBuffer, off, cbBlock, pcbRead);
9240	}
9241
9242	/**
9243	* @copydoc PDMDEVHLPR3::pfnDMAWriteMemory
9244	*/
9245	DECLINLINE(int) PDMDevHlpDMAWriteMemory(PPDMDEVINS pDevIns, unsigned uChannel, const void pvBuffer, uint32_t off, uint32_t cbBlock, uint32_t pcbWritten)
9246	{
9247	return pDevIns->pHlpR3->pfnDMAWriteMemory(pDevIns, uChannel, pvBuffer, off, cbBlock, pcbWritten);
9248	}
9249
9250	/**
9251	* @copydoc PDMDEVHLPR3::pfnDMASetDREQ
9252	*/
9253	DECLINLINE(int) PDMDevHlpDMASetDREQ(PPDMDEVINS pDevIns, unsigned uChannel, unsigned uLevel)
9254	{
9255	return pDevIns->pHlpR3->pfnDMASetDREQ(pDevIns, uChannel, uLevel);
9256	}
9257
9258	/**
9259	* @copydoc PDMDEVHLPR3::pfnDMAGetChannelMode
9260	*/
9261	DECLINLINE(uint8_t) PDMDevHlpDMAGetChannelMode(PPDMDEVINS pDevIns, unsigned uChannel)
9262	{
9263	return pDevIns->pHlpR3->pfnDMAGetChannelMode(pDevIns, uChannel);
9264	}
9265
9266	/**
9267	* @copydoc PDMDEVHLPR3::pfnDMASchedule
9268	*/
9269	DECLINLINE(void) PDMDevHlpDMASchedule(PPDMDEVINS pDevIns)
9270	{
9271	pDevIns->pHlpR3->pfnDMASchedule(pDevIns);
9272	}
9273
9274	/**
9275	* @copydoc PDMDEVHLPR3::pfnCMOSWrite
9276	*/
9277	DECLINLINE(int) PDMDevHlpCMOSWrite(PPDMDEVINS pDevIns, unsigned iReg, uint8_t u8Value)
9278	{
9279	return pDevIns->pHlpR3->pfnCMOSWrite(pDevIns, iReg, u8Value);
9280	}
9281
9282	/**
9283	* @copydoc PDMDEVHLPR3::pfnCMOSRead
9284	*/
9285	DECLINLINE(int) PDMDevHlpCMOSRead(PPDMDEVINS pDevIns, unsigned iReg, uint8_t *pu8Value)
9286	{
9287	return pDevIns->pHlpR3->pfnCMOSRead(pDevIns, iReg, pu8Value);
9288	}
9289
9290	/**
9291	* @copydoc PDMDEVHLPR3::pfnCallR0
9292	*/
9293	DECLINLINE(int) PDMDevHlpCallR0(PPDMDEVINS pDevIns, uint32_t uOperation, uint64_t u64Arg)
9294	{
9295	return pDevIns->pHlpR3->pfnCallR0(pDevIns, uOperation, u64Arg);
9296	}
9297
9298	/**
9299	* @copydoc PDMDEVHLPR3::pfnVMGetSuspendReason
9300	*/
9301	DECLINLINE(VMSUSPENDREASON) PDMDevHlpVMGetSuspendReason(PPDMDEVINS pDevIns)
9302	{
9303	return pDevIns->pHlpR3->pfnVMGetSuspendReason(pDevIns);
9304	}
9305
9306	/**
9307	* @copydoc PDMDEVHLPR3::pfnVMGetResumeReason
9308	*/
9309	DECLINLINE(VMRESUMEREASON) PDMDevHlpVMGetResumeReason(PPDMDEVINS pDevIns)
9310	{
9311	return pDevIns->pHlpR3->pfnVMGetResumeReason(pDevIns);
9312	}
9313
9314	/**
9315	* @copydoc PDMDEVHLPR3::pfnGetUVM
9316	*/
9317	DECLINLINE(PUVM) PDMDevHlpGetUVM(PPDMDEVINS pDevIns)
9318	{
9319	return pDevIns->CTX_SUFF(pHlp)->pfnGetUVM(pDevIns);
9320	}
9321
9322	#endif /* IN_RING3 \|\| DOXYGEN_RUNNING */
9323
9324	#if !defined(IN_RING3) \|\| defined(DOXYGEN_RUNNING)
9325
9326	/**
9327	* @copydoc PDMDEVHLPR0::pfnPCIBusSetUpContext
9328	*/
9329	DECLINLINE(int) PDMDevHlpPCIBusSetUpContext(PPDMDEVINS pDevIns, CTX_SUFF(PPDMPCIBUSREG) pPciBusReg, CTX_SUFF(PCPDMPCIHLP) *ppPciHlp)
9330	{
9331	return pDevIns->CTX_SUFF(pHlp)->pfnPCIBusSetUpContext(pDevIns, pPciBusReg, ppPciHlp);
9332	}
9333
9334	/**
9335	* @copydoc PDMDEVHLPR0::pfnIommuSetUpContext
9336	*/
9337	DECLINLINE(int) PDMDevHlpIommuSetUpContext(PPDMDEVINS pDevIns, CTX_SUFF(PPDMIOMMUREG) pIommuReg, CTX_SUFF(PCPDMIOMMUHLP) *ppIommuHlp)
9338	{
9339	return pDevIns->CTX_SUFF(pHlp)->pfnIommuSetUpContext(pDevIns, pIommuReg, ppIommuHlp);
9340	}
9341
9342	/**
9343	* @copydoc PDMDEVHLPR0::pfnPICSetUpContext
9344	*/
9345	DECLINLINE(int) PDMDevHlpPICSetUpContext(PPDMDEVINS pDevIns, PPDMPICREG pPicReg, PCPDMPICHLP *ppPicHlp)
9346	{
9347	return pDevIns->CTX_SUFF(pHlp)->pfnPICSetUpContext(pDevIns, pPicReg, ppPicHlp);
9348	}
9349
9350	/**
9351	* @copydoc PDMDEVHLPR0::pfnIcSetUpContext
9352	*/
9353	DECLINLINE(int) PDMDevHlpIcSetUpContext(PPDMDEVINS pDevIns)
9354	{
9355	return pDevIns->CTX_SUFF(pHlp)->pfnIcSetUpContext(pDevIns);
9356	}
9357
9358	/**
9359	* @copydoc PDMDEVHLPR0::pfnIoApicSetUpContext
9360	*/
9361	DECLINLINE(int) PDMDevHlpIoApicSetUpContext(PPDMDEVINS pDevIns, PPDMIOAPICREG pIoApicReg, PCPDMIOAPICHLP *ppIoApicHlp)
9362	{
9363	return pDevIns->CTX_SUFF(pHlp)->pfnIoApicSetUpContext(pDevIns, pIoApicReg, ppIoApicHlp);
9364	}
9365
9366	/**
9367	* @copydoc PDMDEVHLPR0::pfnHpetSetUpContext
9368	*/
9369	DECLINLINE(int) PDMDevHlpHpetSetUpContext(PPDMDEVINS pDevIns, PPDMHPETREG pHpetReg, CTX_SUFF(PCPDMHPETHLP) *ppHpetHlp)
9370	{
9371	return pDevIns->CTX_SUFF(pHlp)->pfnHpetSetUpContext(pDevIns, pHpetReg, ppHpetHlp);
9372	}
9373
9374	#endif /* !IN_RING3 \|\| DOXYGEN_RUNNING */
9375
9376	/**
9377	* @copydoc PDMDEVHLPR3::pfnGetVM
9378	*/
9379	DECLINLINE(PVMCC) PDMDevHlpGetVM(PPDMDEVINS pDevIns)
9380	{
9381	return pDevIns->CTX_SUFF(pHlp)->pfnGetVM(pDevIns);
9382	}
9383
9384	/**
9385	* @copydoc PDMDEVHLPR3::pfnGetVMCPU
9386	*/
9387	DECLINLINE(PVMCPUCC) PDMDevHlpGetVMCPU(PPDMDEVINS pDevIns)
9388	{
9389	return pDevIns->CTX_SUFF(pHlp)->pfnGetVMCPU(pDevIns);
9390	}
9391
9392	/**
9393	* @copydoc PDMDEVHLPR3::pfnGetCurrentCpuId
9394	*/
9395	DECLINLINE(VMCPUID) PDMDevHlpGetCurrentCpuId(PPDMDEVINS pDevIns)
9396	{
9397	return pDevIns->CTX_SUFF(pHlp)->pfnGetCurrentCpuId(pDevIns);
9398	}
9399
9400	/**
9401	* @copydoc PDMDEVHLPR3::pfnTMTimeVirtGet
9402	*/
9403	DECLINLINE(uint64_t) PDMDevHlpTMTimeVirtGet(PPDMDEVINS pDevIns)
9404	{
9405	return pDevIns->CTX_SUFF(pHlp)->pfnTMTimeVirtGet(pDevIns);
9406	}
9407
9408	/**
9409	* @copydoc PDMDEVHLPR3::pfnTMTimeVirtGetFreq
9410	*/
9411	DECLINLINE(uint64_t) PDMDevHlpTMTimeVirtGetFreq(PPDMDEVINS pDevIns)
9412	{
9413	return pDevIns->CTX_SUFF(pHlp)->pfnTMTimeVirtGetFreq(pDevIns);
9414	}
9415
9416	/**
9417	* @copydoc PDMDEVHLPR3::pfnTMTimeVirtGetFreq
9418	*/
9419	DECLINLINE(uint64_t) PDMDevHlpTMTimeVirtGetNano(PPDMDEVINS pDevIns)
9420	{
9421	return pDevIns->CTX_SUFF(pHlp)->pfnTMTimeVirtGetNano(pDevIns);
9422	}
9423
9424	#ifdef IN_RING3
9425	/**
9426	* @copydoc PDMDEVHLPR3::pfnTMCpuTicksPerSecond
9427	*/
9428	DECLINLINE(uint64_t) PDMDevHlpTMCpuTicksPerSecond(PPDMDEVINS pDevIns)
9429	{
9430	return pDevIns->CTX_SUFF(pHlp)->pfnTMCpuTicksPerSecond(pDevIns);
9431	}
9432
9433	/**
9434	* @copydoc PDMDEVHLPR3::pfnRegisterVMMDevHeap
9435	*/
9436	DECLINLINE(int) PDMDevHlpRegisterVMMDevHeap(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTR3PTR pvHeap, unsigned cbHeap)
9437	{
9438	return pDevIns->pHlpR3->pfnRegisterVMMDevHeap(pDevIns, GCPhys, pvHeap, cbHeap);
9439	}
9440
9441	/**
9442	* @copydoc PDMDEVHLPR3::pfnFirmwareRegister
9443	*/
9444	DECLINLINE(int) PDMDevHlpFirmwareRegister(PPDMDEVINS pDevIns, PCPDMFWREG pFwReg, PCPDMFWHLPR3 *ppFwHlp)
9445	{
9446	return pDevIns->pHlpR3->pfnFirmwareRegister(pDevIns, pFwReg, ppFwHlp);
9447	}
9448
9449	/**
9450	* @copydoc PDMDEVHLPR3::pfnVMReset
9451	*/
9452	DECLINLINE(int) PDMDevHlpVMReset(PPDMDEVINS pDevIns, uint32_t fFlags)
9453	{
9454	return pDevIns->pHlpR3->pfnVMReset(pDevIns, fFlags);
9455	}
9456
9457	/**
9458	* @copydoc PDMDEVHLPR3::pfnVMSuspend
9459	*/
9460	DECLINLINE(int) PDMDevHlpVMSuspend(PPDMDEVINS pDevIns)
9461	{
9462	return pDevIns->pHlpR3->pfnVMSuspend(pDevIns);
9463	}
9464
9465	/**
9466	* @copydoc PDMDEVHLPR3::pfnVMSuspendSaveAndPowerOff
9467	*/
9468	DECLINLINE(int) PDMDevHlpVMSuspendSaveAndPowerOff(PPDMDEVINS pDevIns)
9469	{
9470	return pDevIns->pHlpR3->pfnVMSuspendSaveAndPowerOff(pDevIns);
9471	}
9472
9473	/**
9474	* @copydoc PDMDEVHLPR3::pfnVMPowerOff
9475	*/
9476	DECLINLINE(int) PDMDevHlpVMPowerOff(PPDMDEVINS pDevIns)
9477	{
9478	return pDevIns->pHlpR3->pfnVMPowerOff(pDevIns);
9479	}
9480
9481	#endif /* IN_RING3 */
9482
9483	/**
9484	* @copydoc PDMDEVHLPR3::pfnA20IsEnabled
9485	*/
9486	DECLINLINE(bool) PDMDevHlpA20IsEnabled(PPDMDEVINS pDevIns)
9487	{
9488	return pDevIns->CTX_SUFF(pHlp)->pfnA20IsEnabled(pDevIns);
9489	}
9490
9491	#ifdef IN_RING3
9492	/**
9493	* @copydoc PDMDEVHLPR3::pfnGetCpuId
9494	*/
9495	DECLINLINE(void) PDMDevHlpGetCpuId(PPDMDEVINS pDevIns, uint32_t iLeaf, uint32_t pEax, uint32_t pEbx, uint32_t pEcx, uint32_t pEdx)
9496	{
9497	pDevIns->pHlpR3->pfnGetCpuId(pDevIns, iLeaf, pEax, pEbx, pEcx, pEdx);
9498	}
9499	#endif
9500
9501	/**
9502	* @copydoc PDMDEVHLPR3::pfnGetMainExecutionEngine
9503	*/
9504	DECLINLINE(uint8_t) PDMDevHlpGetMainExecutionEngine(PPDMDEVINS pDevIns)
9505	{
9506	return pDevIns->CTX_SUFF(pHlp)->pfnGetMainExecutionEngine(pDevIns);
9507	}
9508
9509	#ifdef IN_RING3
9510
9511	/**
9512	* @copydoc PDMDEVHLPR3::pfnGetSupDrvSession
9513	*/
9514	DECLINLINE(PSUPDRVSESSION) PDMDevHlpGetSupDrvSession(PPDMDEVINS pDevIns)
9515	{
9516	return pDevIns->pHlpR3->pfnGetSupDrvSession(pDevIns);
9517	}
9518
9519	/**
9520	* @copydoc PDMDEVHLPR3::pfnQueryGenericUserObject
9521	*/
9522	DECLINLINE(void *) PDMDevHlpQueryGenericUserObject(PPDMDEVINS pDevIns, PCRTUUID pUuid)
9523	{
9524	return pDevIns->pHlpR3->pfnQueryGenericUserObject(pDevIns, pUuid);
9525	}
9526
9527	/**
9528	* @copydoc PDMDEVHLPR3::pfnPGMHandlerPhysicalTypeRegister
9529	*/
9530	DECLINLINE(int) PDMDevHlpPGMHandlerPhysicalTypeRegister(PPDMDEVINS pDevIns, PGMPHYSHANDLERKIND enmKind,
9531	PFNPGMPHYSHANDLER pfnHandler, const char *pszDesc,
9532	PPGMPHYSHANDLERTYPE phType)
9533	{
9534	return pDevIns->pHlpR3->pfnPGMHandlerPhysicalTypeRegister(pDevIns, enmKind, pfnHandler, pszDesc, phType);
9535	}
9536
9537	#elif defined(IN_RING0)
9538
9539	/**
9540	* @copydoc PDMDEVHLPR0::pfnPGMHandlerPhysicalTypeSetUpContext
9541	*/
9542	DECLINLINE(int) PDMDevHlpPGMHandlerPhysicalTypeSetUpContext(PPDMDEVINS pDevIns, PGMPHYSHANDLERKIND enmKind,
9543	PFNPGMPHYSHANDLER pfnHandler, PFNPGMRZPHYSPFHANDLER pfnPfHandler,
9544	const char *pszDesc, PGMPHYSHANDLERTYPE hType)
9545	{
9546	return pDevIns->pHlpR0->pfnPGMHandlerPhysicalTypeSetUpContext(pDevIns, enmKind, pfnHandler, pfnPfHandler, pszDesc, hType);
9547	}
9548
9549	#endif
9550	#ifdef IN_RING3
9551
9552	/**
9553	* @copydoc PDMDEVHLPR3::pfnPGMHandlerPhysicalRegister
9554	*/
9555	DECLINLINE(int) PDMDevHlpPGMHandlerPhysicalRegister(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTGCPHYS GCPhysLast,
9556	PGMPHYSHANDLERTYPE hType, R3PTRTYPE(const char *) pszDesc)
9557	{
9558	return pDevIns->pHlpR3->pfnPGMHandlerPhysicalRegister(pDevIns, GCPhys, GCPhysLast, hType, pszDesc);
9559	}
9560
9561	/**
9562	* @copydoc PDMDEVHLPR3::pfnPGMHandlerPhysicalDeregister
9563	*/
9564	DECLINLINE(int) PDMDevHlpPGMHandlerPhysicalDeregister(PPDMDEVINS pDevIns, RTGCPHYS GCPhys)
9565	{
9566	return pDevIns->pHlpR3->pfnPGMHandlerPhysicalDeregister(pDevIns, GCPhys);
9567	}
9568
9569	#endif /* IN_RING3 */
9570
9571	/**
9572	* @copydoc PDMDEVHLPR3::pfnPGMHandlerPhysicalPageTempOff
9573	*/
9574	DECLINLINE(int) PDMDevHlpPGMHandlerPhysicalPageTempOff(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTGCPHYS GCPhysPage)
9575	{
9576	return pDevIns->CTX_SUFF(pHlp)->pfnPGMHandlerPhysicalPageTempOff(pDevIns, GCPhys, GCPhysPage);
9577	}
9578
9579	#ifdef IN_RING3
9580
9581	/**
9582	* @copydoc PDMDEVHLPR3::pfnPGMHandlerPhysicalReset
9583	*/
9584	DECLINLINE(int) PDMDevHlpPGMHandlerPhysicalReset(PPDMDEVINS pDevIns, RTGCPHYS GCPhys)
9585	{
9586	return pDevIns->pHlpR3->pfnPGMHandlerPhysicalReset(pDevIns, GCPhys);
9587	}
9588
9589	/**
9590	* @copydoc PDMDEVHLPR3::pfnVMMRegisterPatchMemory
9591	*/
9592	DECLINLINE(int) PDMDevHlpVMMRegisterPatchMemory(PPDMDEVINS pDevIns, RTGCPTR GCPtrPatchMem, uint32_t cbPatchMem)
9593	{
9594	return pDevIns->pHlpR3->pfnVMMRegisterPatchMemory(pDevIns, GCPtrPatchMem, cbPatchMem);
9595	}
9596
9597	/**
9598	* @copydoc PDMDEVHLPR3::pfnVMMDeregisterPatchMemory
9599	*/
9600	DECLINLINE(int) PDMDevHlpVMMDeregisterPatchMemory(PPDMDEVINS pDevIns, RTGCPTR GCPtrPatchMem, uint32_t cbPatchMem)
9601	{
9602	return pDevIns->pHlpR3->pfnVMMDeregisterPatchMemory(pDevIns, GCPtrPatchMem, cbPatchMem);
9603	}
9604
9605	/**
9606	* @copydoc PDMDEVHLPR3::pfnSharedModuleRegister
9607	*/
9608	DECLINLINE(int) PDMDevHlpSharedModuleRegister(PPDMDEVINS pDevIns, VBOXOSFAMILY enmGuestOS, char pszModuleName, char pszVersion,
9609	RTGCPTR GCBaseAddr, uint32_t cbModule,
9610	uint32_t cRegions, VMMDEVSHAREDREGIONDESC const *paRegions)
9611	{
9612	return pDevIns->pHlpR3->pfnSharedModuleRegister(pDevIns, enmGuestOS, pszModuleName, pszVersion,
9613	GCBaseAddr, cbModule, cRegions, paRegions);
9614	}
9615
9616	/**
9617	* @copydoc PDMDEVHLPR3::pfnSharedModuleUnregister
9618	*/
9619	DECLINLINE(int) PDMDevHlpSharedModuleUnregister(PPDMDEVINS pDevIns, char pszModuleName, char pszVersion,
9620	RTGCPTR GCBaseAddr, uint32_t cbModule)
9621	{
9622	return pDevIns->pHlpR3->pfnSharedModuleUnregister(pDevIns, pszModuleName, pszVersion, GCBaseAddr, cbModule);
9623	}
9624
9625	/**
9626	* @copydoc PDMDEVHLPR3::pfnSharedModuleGetPageState
9627	*/
9628	DECLINLINE(int) PDMDevHlpSharedModuleGetPageState(PPDMDEVINS pDevIns, RTGCPTR GCPtrPage, bool *pfShared,
9629	uint64_t *pfPageFlags)
9630	{
9631	return pDevIns->pHlpR3->pfnSharedModuleGetPageState(pDevIns, GCPtrPage, pfShared, pfPageFlags);
9632	}
9633
9634	/**
9635	* @copydoc PDMDEVHLPR3::pfnSharedModuleCheckAll
9636	*/
9637	DECLINLINE(int) PDMDevHlpSharedModuleCheckAll(PPDMDEVINS pDevIns)
9638	{
9639	return pDevIns->pHlpR3->pfnSharedModuleCheckAll(pDevIns);
9640	}
9641
9642	/**
9643	* @copydoc PDMDEVHLPR3::pfnQueryLun
9644	*/
9645	DECLINLINE(int) PDMDevHlpQueryLun(PPDMDEVINS pDevIns, const char pszDevice, unsigned iInstance, unsigned iLun, PPDMIBASE ppBase)
9646	{
9647	return pDevIns->pHlpR3->pfnQueryLun(pDevIns, pszDevice, iInstance, iLun, ppBase);
9648	}
9649
9650	/**
9651	* @copydoc PDMDEVHLPR3::pfnGIMDeviceRegister
9652	*/
9653	DECLINLINE(void) PDMDevHlpGIMDeviceRegister(PPDMDEVINS pDevIns, PGIMDEBUG pDbg)
9654	{
9655	pDevIns->pHlpR3->pfnGIMDeviceRegister(pDevIns, pDbg);
9656	}
9657
9658	/**
9659	* @copydoc PDMDEVHLPR3::pfnGIMGetDebugSetup
9660	*/
9661	DECLINLINE(int) PDMDevHlpGIMGetDebugSetup(PPDMDEVINS pDevIns, PGIMDEBUGSETUP pDbgSetup)
9662	{
9663	return pDevIns->pHlpR3->pfnGIMGetDebugSetup(pDevIns, pDbgSetup);
9664	}
9665
9666	#endif /* IN_RING3 */
9667
9668	/**
9669	* @copydoc PDMDEVHLPR3::pfnGIMGetMmio2Regions
9670	*/
9671	DECLINLINE(PGIMMMIO2REGION) PDMDevHlpGIMGetMmio2Regions(PPDMDEVINS pDevIns, uint32_t *pcRegions)
9672	{
9673	return pDevIns->CTX_SUFF(pHlp)->pfnGIMGetMmio2Regions(pDevIns, pcRegions);
9674	}
9675
9676	#ifdef IN_RING3
9677
9678	/** Wrapper around SSMR3GetU32 for simplifying getting enum values saved as uint32_t. */
9679	# define PDMDEVHLP_SSM_GET_ENUM32_RET(a_pHlp, a_pSSM, a_enmDst, a_EnumType) \
9680	do { \
9681	uint32_t u32GetEnumTmp = 0; \
9682	int rcGetEnum32Tmp = (a_pHlp)->pfnSSMGetU32((a_pSSM), &u32GetEnumTmp); \
9683	AssertRCReturn(rcGetEnum32Tmp, rcGetEnum32Tmp); \
9684	(a_enmDst) = (a_EnumType)u32GetEnumTmp; \
9685	AssertCompile(sizeof(a_EnumType) == sizeof(u32GetEnumTmp)); \
9686	} while (0)
9687
9688	/** Wrapper around SSMR3GetU8 for simplifying getting enum values saved as uint8_t. */
9689	# define PDMDEVHLP_SSM_GET_ENUM8_RET(a_pHlp, a_pSSM, a_enmDst, a_EnumType) \
9690	do { \
9691	uint8_t bGetEnumTmp = 0; \
9692	int rcGetEnum32Tmp = (a_pHlp)->pfnSSMGetU8((a_pSSM), &bGetEnumTmp); \
9693	AssertRCReturn(rcGetEnum32Tmp, rcGetEnum32Tmp); \
9694	(a_enmDst) = (a_EnumType)bGetEnumTmp; \
9695	} while (0)
9696
9697	#endif /* IN_RING3 */
9698
9699	/** Pointer to callbacks provided to the VBoxDeviceRegister() call. */
9700	typedef struct PDMDEVREGCB *PPDMDEVREGCB;
9701
9702	/**
9703	* Callbacks for VBoxDeviceRegister().
9704	*/
9705	typedef struct PDMDEVREGCB
9706	{
9707	/** Interface version.
9708	* This is set to PDM_DEVREG_CB_VERSION. */
9709	uint32_t u32Version;
9710
9711	/**
9712	* Registers a device with the current VM instance.
9713	*
9714	* @returns VBox status code.
9715	* @param pCallbacks Pointer to the callback table.
9716	* @param pReg Pointer to the device registration record.
9717	* This data must be permanent and readonly.
9718	*/
9719	DECLR3CALLBACKMEMBER(int, pfnRegister,(PPDMDEVREGCB pCallbacks, PCPDMDEVREG pReg));
9720	} PDMDEVREGCB;
9721
9722	/** Current version of the PDMDEVREGCB structure. */
9723	#define PDM_DEVREG_CB_VERSION PDM_VERSION_MAKE(0xffe3, 1, 0)
9724
9725
9726	/**
9727	* The VBoxDevicesRegister callback function.
9728	*
9729	* PDM will invoke this function after loading a device module and letting
9730	* the module decide which devices to register and how to handle conflicts.
9731	*
9732	* @returns VBox status code.
9733	* @param pCallbacks Pointer to the callback table.
9734	* @param u32Version VBox version number.
9735	*/
9736	typedef DECLCALLBACKTYPE(int, FNPDMVBOXDEVICESREGISTER,(PPDMDEVREGCB pCallbacks, uint32_t u32Version));
9737
9738	/** @} */
9739
9740	RT_C_DECLS_END
9741
9742	#endif /* !VBOX_INCLUDED_vmm_pdmdev_h */

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

source: vbox/trunk/include/VBox/vmm/pdmdev.h@ 107308

Download in other formats: