pdmdev.h

最後變更在這個檔案是 108434,由 vboxsync 提交於 11 天前
VMM/NEM/Hyper-V: Started implementing a NEM/Hyper-V specific APIC emulation utilizing the LocalApicEmulation feature of Hyper-V, bugref:9993
屬性 svn:eol-style 設為 `native` 屬性 svn:keywords 設為 `Id Revision`
檔案大小: 407.4 KB

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

注意: 瀏覽 TracBrowser 來幫助您使用儲存庫瀏覽器

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

以其他格式下載: