pdmdev.h@ 100251

Last change on this file since 100251 was 100184, checked in by vboxsync, 20 months ago
VMM: Add a CPUMGetGuestArch() method and PDM device helper to make it easier to determine the guest architecture and not having to deal with the massive CPUMMICROARCH enum, bugref:10385
Property svn:eol-style set to `native` Property svn:keywords set to `Id Revision`
File size: 407.3 KB

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

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

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

Download in other formats: