pdmdev.h@ 89924

Last change on this file since 89924 was 89620, checked in by vboxsync, 4 years ago
Intel IOMMU: bugref:9967 Allow PDMIoApicSetEoi operation to be queued to ring-3 if I/O APIC isn't available in R0. This key change is taking the PDM lock such that it doesn't fail (VINF_SUCCESS instead of VINF_IOM_R3_MMIO_WRITE for rcBusy, which wouldn't have worked anyway when called via APICHvSetEoi for instance). Also cleaned up the prototype of PDMIoApicSendMsi a bit (use PVMCC instead of PPDMDEVINS).
Property svn:eol-style set to `native` Property svn:keywords set to `Id Revision`
File size: 354.6 KB

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

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

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

Download in other formats: