pdmdev.h@ 107215

Last change on this file since 107215 was 107215, checked in by vboxsync, 6 months ago
VMM/PDM,VMMDevTesting: Don't include vm.h in VMMDevTesting, replacing it by a new devhlp function for poking the EMTs. jiraref:VBP-1466
Property svn:eol-style set to `native` Property svn:keywords set to `Id Revision`
File size: 407.0 KB

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

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

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

Download in other formats: