pdmdev.h@ 89213

Last change on this file since 89213 was 89200, checked in by vboxsync, 4 years ago
Intel IOMMU: bugref:9967 Add ring-3 MSI queuing for the IOMMU send MSI interface as well. Added a todo for later.
Property svn:eol-style set to `native` Property svn:keywords set to `Id Revision`
File size: 354.8 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	* @returns Strict VBox status code - only the following informational status codes:
1872	* @retval VINF_IOM_R3_MMIO_WRITE if the I/O APIC lock is contenteded and we're in R0 or RC.
1873	* @retval VINF_SUCCESS
1874	*
1875	* @param pDevIns Device instance of the I/O APIC.
1876	* @param u8Vector The vector.
1877	*
1878	* @remarks Caller enters the PDM critical section
1879	* Actually, as per 2018-07-21 this isn't true (bird).
1880	*/
1881	DECLCALLBACKMEMBER(VBOXSTRICTRC, pfnSetEoi,(PPDMDEVINS pDevIns, uint8_t u8Vector));
1882
1883	/** Just a safety precaution. */
1884	uint32_t u32TheEnd;
1885	} PDMIOAPICREG;
1886	/** Pointer to an APIC registration structure. */
1887	typedef PDMIOAPICREG *PPDMIOAPICREG;
1888
1889	/** Current PDMAPICREG version number. */
1890	#define PDM_IOAPICREG_VERSION PDM_VERSION_MAKE(0xfff2, 7, 0)
1891
1892
1893	/**
1894	* IOAPIC helpers, same in all contexts.
1895	*/
1896	typedef struct PDMIOAPICHLP
1897	{
1898	/** Structure version. PDM_IOAPICHLP_VERSION defines the current version. */
1899	uint32_t u32Version;
1900
1901	/**
1902	* Private interface between the IOAPIC and APIC.
1903	*
1904	* @returns status code.
1905	* @param pDevIns Device instance of the IOAPIC.
1906	* @param u8Dest See APIC implementation.
1907	* @param u8DestMode See APIC implementation.
1908	* @param u8DeliveryMode See APIC implementation.
1909	* @param uVector See APIC implementation.
1910	* @param u8Polarity See APIC implementation.
1911	* @param u8TriggerMode See APIC implementation.
1912	* @param uTagSrc The IRQ tag and source (for tracing).
1913	*
1914	* @sa APICBusDeliver()
1915	*/
1916	DECLCALLBACKMEMBER(int, pfnApicBusDeliver,(PPDMDEVINS pDevIns, uint8_t u8Dest, uint8_t u8DestMode, uint8_t u8DeliveryMode,
1917	uint8_t uVector, uint8_t u8Polarity, uint8_t u8TriggerMode, uint32_t uTagSrc));
1918
1919	/**
1920	* Acquires the PDM lock.
1921	*
1922	* @returns VINF_SUCCESS on success.
1923	* @returns rc if we failed to acquire the lock.
1924	* @param pDevIns The IOAPIC device instance.
1925	* @param rc What to return if we fail to acquire the lock.
1926	*/
1927	DECLCALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
1928
1929	/**
1930	* Releases the PDM lock.
1931	*
1932	* @param pDevIns The IOAPIC device instance.
1933	*/
1934	DECLCALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
1935
1936	/**
1937	* Checks if the calling thread owns the PDM lock.
1938	*
1939	* @param pDevIns The IOAPIC device instance.
1940	*/
1941	DECLCALLBACKMEMBER(bool, pfnLockIsOwner,(PPDMDEVINS pDevIns));
1942
1943	/**
1944	* Private interface between the IOAPIC and IOMMU.
1945	*
1946	* @returns status code.
1947	* @param pDevIns Device instance of the IOAPIC.
1948	* @param idDevice The device identifier (bus, device, function).
1949	* @param pMsiIn The source MSI.
1950	* @param pMsiOut Where to store the remapped MSI (only updated when
1951	* VINF_SUCCESS is returned).
1952	*/
1953	DECLCALLBACKMEMBER(int, pfnIommuMsiRemap,(PPDMDEVINS pDevIns, uint16_t idDevice, PCMSIMSG pMsiIn, PMSIMSG pMsiOut));
1954
1955	/** Just a safety precaution. */
1956	uint32_t u32TheEnd;
1957	} PDMIOAPICHLP;
1958	/** Pointer to IOAPIC helpers. */
1959	typedef PDMIOAPICHLP * PPDMIOAPICHLP;
1960	/** Pointer to const IOAPIC helpers. */
1961	typedef const PDMIOAPICHLP * PCPDMIOAPICHLP;
1962
1963	/** Current PDMIOAPICHLP version number. */
1964	#define PDM_IOAPICHLP_VERSION PDM_VERSION_MAKE(0xfff0, 3, 1)
1965
1966
1967	/**
1968	* HPET registration structure.
1969	*/
1970	typedef struct PDMHPETREG
1971	{
1972	/** Struct version+magic number (PDM_HPETREG_VERSION). */
1973	uint32_t u32Version;
1974	} PDMHPETREG;
1975	/** Pointer to an HPET registration structure. */
1976	typedef PDMHPETREG *PPDMHPETREG;
1977
1978	/** Current PDMHPETREG version number. */
1979	#define PDM_HPETREG_VERSION PDM_VERSION_MAKE(0xffe2, 1, 0)
1980
1981	/**
1982	* HPET RC helpers.
1983	*
1984	* @remarks Keep this around in case HPET will need PDM interaction in again RC
1985	* at some later point.
1986	*/
1987	typedef struct PDMHPETHLPRC
1988	{
1989	/** Structure version. PDM_HPETHLPRC_VERSION defines the current version. */
1990	uint32_t u32Version;
1991
1992	/** Just a safety precaution. */
1993	uint32_t u32TheEnd;
1994	} PDMHPETHLPRC;
1995
1996	/** Pointer to HPET RC helpers. */
1997	typedef RCPTRTYPE(PDMHPETHLPRC *) PPDMHPETHLPRC;
1998	/** Pointer to const HPET RC helpers. */
1999	typedef RCPTRTYPE(const PDMHPETHLPRC *) PCPDMHPETHLPRC;
2000
2001	/** Current PDMHPETHLPRC version number. */
2002	#define PDM_HPETHLPRC_VERSION PDM_VERSION_MAKE(0xffee, 2, 0)
2003
2004
2005	/**
2006	* HPET R0 helpers.
2007	*
2008	* @remarks Keep this around in case HPET will need PDM interaction in again R0
2009	* at some later point.
2010	*/
2011	typedef struct PDMHPETHLPR0
2012	{
2013	/** Structure version. PDM_HPETHLPR0_VERSION defines the current version. */
2014	uint32_t u32Version;
2015
2016	/** Just a safety precaution. */
2017	uint32_t u32TheEnd;
2018	} PDMHPETHLPR0;
2019
2020	/** Pointer to HPET R0 helpers. */
2021	typedef R0PTRTYPE(PDMHPETHLPR0 *) PPDMHPETHLPR0;
2022	/** Pointer to const HPET R0 helpers. */
2023	typedef R0PTRTYPE(const PDMHPETHLPR0 *) PCPDMHPETHLPR0;
2024
2025	/** Current PDMHPETHLPR0 version number. */
2026	#define PDM_HPETHLPR0_VERSION PDM_VERSION_MAKE(0xffed, 2, 0)
2027
2028	/**
2029	* HPET R3 helpers.
2030	*/
2031	typedef struct PDMHPETHLPR3
2032	{
2033	/** Structure version. PDM_HPETHLP_VERSION defines the current version. */
2034	uint32_t u32Version;
2035
2036	/**
2037	* Set legacy mode on PIT and RTC.
2038	*
2039	* @returns VINF_SUCCESS on success.
2040	* @returns rc if we failed to set legacy mode.
2041	* @param pDevIns Device instance of the HPET.
2042	* @param fActivated Whether legacy mode is activated or deactivated.
2043	*/
2044	DECLR3CALLBACKMEMBER(int, pfnSetLegacyMode,(PPDMDEVINS pDevIns, bool fActivated));
2045
2046
2047	/**
2048	* Set IRQ, bypassing ISA bus override rules.
2049	*
2050	* @returns VINF_SUCCESS on success.
2051	* @returns rc if we failed to set legacy mode.
2052	* @param pDevIns Device instance of the HPET.
2053	* @param iIrq IRQ number to set.
2054	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
2055	*/
2056	DECLR3CALLBACKMEMBER(int, pfnSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
2057
2058	/** Just a safety precaution. */
2059	uint32_t u32TheEnd;
2060	} PDMHPETHLPR3;
2061
2062	/** Pointer to HPET R3 helpers. */
2063	typedef R3PTRTYPE(PDMHPETHLPR3 *) PPDMHPETHLPR3;
2064	/** Pointer to const HPET R3 helpers. */
2065	typedef R3PTRTYPE(const PDMHPETHLPR3 *) PCPDMHPETHLPR3;
2066
2067	/** Current PDMHPETHLPR3 version number. */
2068	#define PDM_HPETHLPR3_VERSION PDM_VERSION_MAKE(0xffec, 3, 0)
2069
2070
2071	/**
2072	* Raw PCI device registration structure.
2073	*/
2074	typedef struct PDMPCIRAWREG
2075	{
2076	/** Struct version+magic number (PDM_PCIRAWREG_VERSION). */
2077	uint32_t u32Version;
2078	/** Just a safety precaution. */
2079	uint32_t u32TheEnd;
2080	} PDMPCIRAWREG;
2081	/** Pointer to a raw PCI registration structure. */
2082	typedef PDMPCIRAWREG *PPDMPCIRAWREG;
2083
2084	/** Current PDMPCIRAWREG version number. */
2085	#define PDM_PCIRAWREG_VERSION PDM_VERSION_MAKE(0xffe1, 1, 0)
2086
2087	/**
2088	* Raw PCI device raw-mode context helpers.
2089	*/
2090	typedef struct PDMPCIRAWHLPRC
2091	{
2092	/** Structure version and magic number (PDM_PCIRAWHLPRC_VERSION). */
2093	uint32_t u32Version;
2094	/** Just a safety precaution. */
2095	uint32_t u32TheEnd;
2096	} PDMPCIRAWHLPRC;
2097	/** Pointer to a raw PCI deviec raw-mode context helper structure. */
2098	typedef RCPTRTYPE(PDMPCIRAWHLPRC *) PPDMPCIRAWHLPRC;
2099	/** Pointer to a const raw PCI deviec raw-mode context helper structure. */
2100	typedef RCPTRTYPE(const PDMPCIRAWHLPRC *) PCPDMPCIRAWHLPRC;
2101
2102	/** Current PDMPCIRAWHLPRC version number. */
2103	#define PDM_PCIRAWHLPRC_VERSION PDM_VERSION_MAKE(0xffe0, 1, 0)
2104
2105	/**
2106	* Raw PCI device ring-0 context helpers.
2107	*/
2108	typedef struct PDMPCIRAWHLPR0
2109	{
2110	/** Structure version and magic number (PDM_PCIRAWHLPR0_VERSION). */
2111	uint32_t u32Version;
2112	/** Just a safety precaution. */
2113	uint32_t u32TheEnd;
2114	} PDMPCIRAWHLPR0;
2115	/** Pointer to a raw PCI deviec ring-0 context helper structure. */
2116	typedef R0PTRTYPE(PDMPCIRAWHLPR0 *) PPDMPCIRAWHLPR0;
2117	/** Pointer to a const raw PCI deviec ring-0 context helper structure. */
2118	typedef R0PTRTYPE(const PDMPCIRAWHLPR0 *) PCPDMPCIRAWHLPR0;
2119
2120	/** Current PDMPCIRAWHLPR0 version number. */
2121	#define PDM_PCIRAWHLPR0_VERSION PDM_VERSION_MAKE(0xffdf, 1, 0)
2122
2123
2124	/**
2125	* Raw PCI device ring-3 context helpers.
2126	*/
2127	typedef struct PDMPCIRAWHLPR3
2128	{
2129	/** Undefined structure version and magic number. */
2130	uint32_t u32Version;
2131
2132	/**
2133	* Gets the address of the RC raw PCI device helpers.
2134	*
2135	* This should be called at both construction and relocation time to obtain
2136	* the correct address of the RC helpers.
2137	*
2138	* @returns RC pointer to the raw PCI device helpers.
2139	* @param pDevIns Device instance of the raw PCI device.
2140	*/
2141	DECLR3CALLBACKMEMBER(PCPDMPCIRAWHLPRC, pfnGetRCHelpers,(PPDMDEVINS pDevIns));
2142
2143	/**
2144	* Gets the address of the R0 raw PCI device helpers.
2145	*
2146	* This should be called at both construction and relocation time to obtain
2147	* the correct address of the R0 helpers.
2148	*
2149	* @returns R0 pointer to the raw PCI device helpers.
2150	* @param pDevIns Device instance of the raw PCI device.
2151	*/
2152	DECLR3CALLBACKMEMBER(PCPDMPCIRAWHLPR0, pfnGetR0Helpers,(PPDMDEVINS pDevIns));
2153
2154	/** Just a safety precaution. */
2155	uint32_t u32TheEnd;
2156	} PDMPCIRAWHLPR3;
2157	/** Pointer to raw PCI R3 helpers. */
2158	typedef R3PTRTYPE(PDMPCIRAWHLPR3 *) PPDMPCIRAWHLPR3;
2159	/** Pointer to const raw PCI R3 helpers. */
2160	typedef R3PTRTYPE(const PDMPCIRAWHLPR3 *) PCPDMPCIRAWHLPR3;
2161
2162	/** Current PDMPCIRAWHLPR3 version number. */
2163	#define PDM_PCIRAWHLPR3_VERSION PDM_VERSION_MAKE(0xffde, 1, 0)
2164
2165
2166	#ifdef IN_RING3
2167
2168	/**
2169	* DMA Transfer Handler.
2170	*
2171	* @returns Number of bytes transferred.
2172	* @param pDevIns The device instance that registered the handler.
2173	* @param pvUser User pointer.
2174	* @param uChannel Channel number.
2175	* @param off DMA position.
2176	* @param cb Block size.
2177	* @remarks The device lock is take before the callback (in fact, the locks of
2178	* DMA devices and the DMA controller itself are taken).
2179	*/
2180	typedef DECLCALLBACKTYPE(uint32_t, FNDMATRANSFERHANDLER,(PPDMDEVINS pDevIns, void *pvUser, unsigned uChannel,
2181	uint32_t off, uint32_t cb));
2182	/** Pointer to a FNDMATRANSFERHANDLER(). */
2183	typedef FNDMATRANSFERHANDLER *PFNDMATRANSFERHANDLER;
2184
2185	/**
2186	* DMA Controller registration structure.
2187	*/
2188	typedef struct PDMDMAREG
2189	{
2190	/** Structure version number. PDM_DMACREG_VERSION defines the current version. */
2191	uint32_t u32Version;
2192
2193	/**
2194	* Execute pending transfers.
2195	*
2196	* @returns A more work indiciator. I.e. 'true' if there is more to be done, and 'false' if all is done.
2197	* @param pDevIns Device instance of the DMAC.
2198	* @remarks No locks held, called on EMT(0) as a form of serialization.
2199	*/
2200	DECLR3CALLBACKMEMBER(bool, pfnRun,(PPDMDEVINS pDevIns));
2201
2202	/**
2203	* Register transfer function for DMA channel.
2204	*
2205	* @param pDevIns Device instance of the DMAC.
2206	* @param uChannel Channel number.
2207	* @param pDevInsHandler The device instance of the device making the
2208	* regstration (will be passed to the callback).
2209	* @param pfnTransferHandler Device specific transfer function.
2210	* @param pvUser User pointer to be passed to the callback.
2211	* @remarks No locks held, called on an EMT.
2212	*/
2213	DECLR3CALLBACKMEMBER(void, pfnRegister,(PPDMDEVINS pDevIns, unsigned uChannel, PPDMDEVINS pDevInsHandler,
2214	PFNDMATRANSFERHANDLER pfnTransferHandler, void *pvUser));
2215
2216	/**
2217	* Read memory
2218	*
2219	* @returns Number of bytes read.
2220	* @param pDevIns Device instance of the DMAC.
2221	* @param uChannel Channel number.
2222	* @param pvBuffer Pointer to target buffer.
2223	* @param off DMA position.
2224	* @param cbBlock Block size.
2225	* @remarks No locks held, called on an EMT.
2226	*/
2227	DECLR3CALLBACKMEMBER(uint32_t, pfnReadMemory,(PPDMDEVINS pDevIns, unsigned uChannel, void *pvBuffer, uint32_t off, uint32_t cbBlock));
2228
2229	/**
2230	* Write memory
2231	*
2232	* @returns Number of bytes written.
2233	* @param pDevIns Device instance of the DMAC.
2234	* @param uChannel Channel number.
2235	* @param pvBuffer Memory to write.
2236	* @param off DMA position.
2237	* @param cbBlock Block size.
2238	* @remarks No locks held, called on an EMT.
2239	*/
2240	DECLR3CALLBACKMEMBER(uint32_t, pfnWriteMemory,(PPDMDEVINS pDevIns, unsigned uChannel, const void *pvBuffer, uint32_t off, uint32_t cbBlock));
2241
2242	/**
2243	* Set the DREQ line.
2244	*
2245	* @param pDevIns Device instance of the DMAC.
2246	* @param uChannel Channel number.
2247	* @param uLevel Level of the line.
2248	* @remarks No locks held, called on an EMT.
2249	*/
2250	DECLR3CALLBACKMEMBER(void, pfnSetDREQ,(PPDMDEVINS pDevIns, unsigned uChannel, unsigned uLevel));
2251
2252	/**
2253	* Get channel mode
2254	*
2255	* @returns Channel mode.
2256	* @param pDevIns Device instance of the DMAC.
2257	* @param uChannel Channel number.
2258	* @remarks No locks held, called on an EMT.
2259	*/
2260	DECLR3CALLBACKMEMBER(uint8_t, pfnGetChannelMode,(PPDMDEVINS pDevIns, unsigned uChannel));
2261
2262	} PDMDMACREG;
2263	/** Pointer to a DMAC registration structure. */
2264	typedef PDMDMACREG *PPDMDMACREG;
2265
2266	/** Current PDMDMACREG version number. */
2267	#define PDM_DMACREG_VERSION PDM_VERSION_MAKE(0xffeb, 2, 0)
2268
2269
2270	/**
2271	* DMA Controller device helpers.
2272	*/
2273	typedef struct PDMDMACHLP
2274	{
2275	/** Structure version. PDM_DMACHLP_VERSION defines the current version. */
2276	uint32_t u32Version;
2277
2278	/* to-be-defined */
2279
2280	} PDMDMACHLP;
2281	/** Pointer to DMAC helpers. */
2282	typedef PDMDMACHLP *PPDMDMACHLP;
2283	/** Pointer to const DMAC helpers. */
2284	typedef const PDMDMACHLP *PCPDMDMACHLP;
2285
2286	/** Current PDMDMACHLP version number. */
2287	#define PDM_DMACHLP_VERSION PDM_VERSION_MAKE(0xffea, 1, 0)
2288
2289	#endif /* IN_RING3 */
2290
2291
2292
2293	/**
2294	* RTC registration structure.
2295	*/
2296	typedef struct PDMRTCREG
2297	{
2298	/** Structure version number. PDM_RTCREG_VERSION defines the current version. */
2299	uint32_t u32Version;
2300	uint32_t u32Alignment; /*< structure size alignment. /
2301
2302	/**
2303	* Write to a CMOS register and update the checksum if necessary.
2304	*
2305	* @returns VBox status code.
2306	* @param pDevIns Device instance of the RTC.
2307	* @param iReg The CMOS register index.
2308	* @param u8Value The CMOS register value.
2309	* @remarks Caller enters the device critical section.
2310	*/
2311	DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMDEVINS pDevIns, unsigned iReg, uint8_t u8Value));
2312
2313	/**
2314	* Read a CMOS register.
2315	*
2316	* @returns VBox status code.
2317	* @param pDevIns Device instance of the RTC.
2318	* @param iReg The CMOS register index.
2319	* @param pu8Value Where to store the CMOS register value.
2320	* @remarks Caller enters the device critical section.
2321	*/
2322	DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMDEVINS pDevIns, unsigned iReg, uint8_t *pu8Value));
2323
2324	} PDMRTCREG;
2325	/** Pointer to a RTC registration structure. */
2326	typedef PDMRTCREG *PPDMRTCREG;
2327	/** Pointer to a const RTC registration structure. */
2328	typedef const PDMRTCREG *PCPDMRTCREG;
2329
2330	/** Current PDMRTCREG version number. */
2331	#define PDM_RTCREG_VERSION PDM_VERSION_MAKE(0xffe9, 2, 0)
2332
2333
2334	/**
2335	* RTC device helpers.
2336	*/
2337	typedef struct PDMRTCHLP
2338	{
2339	/** Structure version. PDM_RTCHLP_VERSION defines the current version. */
2340	uint32_t u32Version;
2341
2342	/* to-be-defined */
2343
2344	} PDMRTCHLP;
2345	/** Pointer to RTC helpers. */
2346	typedef PDMRTCHLP *PPDMRTCHLP;
2347	/** Pointer to const RTC helpers. */
2348	typedef const PDMRTCHLP *PCPDMRTCHLP;
2349
2350	/** Current PDMRTCHLP version number. */
2351	#define PDM_RTCHLP_VERSION PDM_VERSION_MAKE(0xffe8, 1, 0)
2352
2353
2354
2355	/** @name Flags for PCI I/O region registration
2356	* @{ */
2357	/** No handle is passed. */
2358	#define PDMPCIDEV_IORGN_F_NO_HANDLE UINT32_C(0x00000000)
2359	/** An I/O port handle is passed. */
2360	#define PDMPCIDEV_IORGN_F_IOPORT_HANDLE UINT32_C(0x00000001)
2361	/** An MMIO range handle is passed. */
2362	#define PDMPCIDEV_IORGN_F_MMIO_HANDLE UINT32_C(0x00000002)
2363	/** An MMIO2 handle is passed. */
2364	#define PDMPCIDEV_IORGN_F_MMIO2_HANDLE UINT32_C(0x00000003)
2365	/** Handle type mask. */
2366	#define PDMPCIDEV_IORGN_F_HANDLE_MASK UINT32_C(0x00000003)
2367	/** New-style (mostly wrt callbacks). */
2368	#define PDMPCIDEV_IORGN_F_NEW_STYLE UINT32_C(0x00000004)
2369	/** Mask of valid flags. */
2370	#define PDMPCIDEV_IORGN_F_VALID_MASK UINT32_C(0x00000007)
2371	/** @} */
2372
2373
2374	/** @name Flags for the guest physical read/write helpers
2375	* @{ */
2376	/** Default flag with no indication whether the data is processed by the device or just passed through. */
2377	#define PDM_DEVHLP_PHYS_RW_F_DEFAULT UINT32_C(0x00000000)
2378	/** The data is user data which is just passed through between the guest and the source or destination and not processed
2379	* by the device in any way. */
2380	#define PDM_DEVHLP_PHYS_RW_F_DATA_USER RT_BIT_32(0)
2381	/** The data is metadata and being processed by the device in some way. */
2382	#define PDM_DEVHLP_PHYS_RW_F_DATA_META RT_BIT_32(1)
2383	/** @} */
2384
2385
2386	#ifdef IN_RING3
2387
2388	/** @name Special values for PDMDEVHLPR3::pfnPCIRegister parameters.
2389	* @{ */
2390	/** Same device number (and bus) as the previous PCI device registered with the PDM device.
2391	* This is handy when registering multiple PCI device functions and the device
2392	* number is left up to the PCI bus. In order to facilitate one PDM device
2393	* instance for each PCI function, this searches earlier PDM device
2394	* instances as well. */
2395	# define PDMPCIDEVREG_DEV_NO_SAME_AS_PREV UINT8_C(0xfd)
2396	/** Use the first unused device number (all functions must be unused). */
2397	# define PDMPCIDEVREG_DEV_NO_FIRST_UNUSED UINT8_C(0xfe)
2398	/** Use the first unused device function. */
2399	# define PDMPCIDEVREG_FUN_NO_FIRST_UNUSED UINT8_C(0xff)
2400
2401	/** The device and function numbers are not mandatory, just suggestions. */
2402	# define PDMPCIDEVREG_F_NOT_MANDATORY_NO RT_BIT_32(0)
2403	/** Registering a PCI bridge device. */
2404	# define PDMPCIDEVREG_F_PCI_BRIDGE RT_BIT_32(1)
2405	/** Valid flag mask. */
2406	# define PDMPCIDEVREG_F_VALID_MASK UINT32_C(0x00000003)
2407	/** @} */
2408
2409	/** Current PDMDEVHLPR3 version number. */
2410	#define PDM_DEVHLPR3_VERSION PDM_VERSION_MAKE_PP(0xffe7, 47, 1)
2411
2412	/**
2413	* PDM Device API.
2414	*/
2415	typedef struct PDMDEVHLPR3
2416	{
2417	/** Structure version. PDM_DEVHLPR3_VERSION defines the current version. */
2418	uint32_t u32Version;
2419
2420	/** @name I/O ports
2421	* @{ */
2422	/**
2423	* Creates a range of I/O ports for a device.
2424	*
2425	* The I/O port range must be mapped in a separately call. Any ring-0 and
2426	* raw-mode context callback handlers needs to be set up in the respective
2427	* contexts.
2428	*
2429	* @returns VBox status.
2430	* @param pDevIns The device instance to register the ports with.
2431	* @param cPorts Number of ports to register.
2432	* @param fFlags IOM_IOPORT_F_XXX.
2433	* @param pPciDev The PCI device the range is associated with, if
2434	* applicable.
2435	* @param iPciRegion The PCI device region in the high 16-bit word and
2436	* sub-region in the low 16-bit word. UINT32_MAX if NA.
2437	* @param pfnOut Pointer to function which is gonna handle OUT
2438	* operations. Optional.
2439	* @param pfnIn Pointer to function which is gonna handle IN operations.
2440	* Optional.
2441	* @param pfnOutStr Pointer to function which is gonna handle string OUT
2442	* operations. Optional.
2443	* @param pfnInStr Pointer to function which is gonna handle string IN
2444	* operations. Optional.
2445	* @param pvUser User argument to pass to the callbacks.
2446	* @param pszDesc Pointer to description string. This must not be freed.
2447	* @param paExtDescs Extended per-port descriptions, optional. Partial range
2448	* coverage is allowed. This must not be freed.
2449	* @param phIoPorts Where to return the I/O port range handle.
2450	*
2451	* @remarks Caller enters the device critical section prior to invoking the
2452	* registered callback methods.
2453	*
2454	* @sa PDMDevHlpIoPortSetUpContext, PDMDevHlpIoPortMap,
2455	* PDMDevHlpIoPortUnmap.
2456	*/
2457	DECLR3CALLBACKMEMBER(int, pfnIoPortCreateEx,(PPDMDEVINS pDevIns, RTIOPORT cPorts, uint32_t fFlags, PPDMPCIDEV pPciDev,
2458	uint32_t iPciRegion, PFNIOMIOPORTNEWOUT pfnOut, PFNIOMIOPORTNEWIN pfnIn,
2459	PFNIOMIOPORTNEWOUTSTRING pfnOutStr, PFNIOMIOPORTNEWINSTRING pfnInStr, RTR3PTR pvUser,
2460	const char *pszDesc, PCIOMIOPORTDESC paExtDescs, PIOMIOPORTHANDLE phIoPorts));
2461
2462	/**
2463	* Maps an I/O port range.
2464	*
2465	* @returns VBox status.
2466	* @param pDevIns The device instance to register the ports with.
2467	* @param hIoPorts The I/O port range handle.
2468	* @param Port Where to map the range.
2469	* @sa PDMDevHlpIoPortUnmap, PDMDevHlpIoPortSetUpContext,
2470	* PDMDevHlpIoPortCreate, PDMDevHlpIoPortCreateEx.
2471	*/
2472	DECLR3CALLBACKMEMBER(int, pfnIoPortMap,(PPDMDEVINS pDevIns, IOMIOPORTHANDLE hIoPorts, RTIOPORT Port));
2473
2474	/**
2475	* Unmaps an I/O port range.
2476	*
2477	* @returns VBox status.
2478	* @param pDevIns The device instance to register the ports with.
2479	* @param hIoPorts The I/O port range handle.
2480	* @sa PDMDevHlpIoPortMap, PDMDevHlpIoPortSetUpContext,
2481	* PDMDevHlpIoPortCreate, PDMDevHlpIoPortCreateEx.
2482	*/
2483	DECLR3CALLBACKMEMBER(int, pfnIoPortUnmap,(PPDMDEVINS pDevIns, IOMIOPORTHANDLE hIoPorts));
2484
2485	/**
2486	* Gets the mapping address of the I/O port range @a hIoPorts.
2487	*
2488	* @returns Mapping address (0..65535) or UINT32_MAX if not mapped (or invalid
2489	* parameters).
2490	* @param pDevIns The device instance to register the ports with.
2491	* @param hIoPorts The I/O port range handle.
2492	*/
2493	DECLR3CALLBACKMEMBER(uint32_t, pfnIoPortGetMappingAddress,(PPDMDEVINS pDevIns, IOMIOPORTHANDLE hIoPorts));
2494	/** @} */
2495
2496	/** @name MMIO
2497	* @{ */
2498	/**
2499	* Creates a memory mapped I/O (MMIO) region for a device.
2500	*
2501	* The MMIO region must be mapped in a separately call. Any ring-0 and
2502	* raw-mode context callback handlers needs to be set up in the respective
2503	* contexts.
2504	*
2505	* @returns VBox status.
2506	* @param pDevIns The device instance to register the ports with.
2507	* @param cbRegion The size of the region in bytes.
2508	* @param fFlags Flags, IOMMMIO_FLAGS_XXX.
2509	* @param pPciDev The PCI device the range is associated with, if
2510	* applicable.
2511	* @param iPciRegion The PCI device region in the high 16-bit word and
2512	* sub-region in the low 16-bit word. UINT32_MAX if NA.
2513	* @param pfnWrite Pointer to function which is gonna handle Write
2514	* operations.
2515	* @param pfnRead Pointer to function which is gonna handle Read
2516	* operations.
2517	* @param pfnFill Pointer to function which is gonna handle Fill/memset
2518	* operations. (optional)
2519	* @param pvUser User argument to pass to the callbacks.
2520	* @param pszDesc Pointer to description string. This must not be freed.
2521	* @param phRegion Where to return the MMIO region handle.
2522	*
2523	* @remarks Caller enters the device critical section prior to invoking the
2524	* registered callback methods.
2525	*
2526	* @sa PDMDevHlpMmioSetUpContext, PDMDevHlpMmioMap, PDMDevHlpMmioUnmap.
2527	*/
2528	DECLR3CALLBACKMEMBER(int, pfnMmioCreateEx,(PPDMDEVINS pDevIns, RTGCPHYS cbRegion,
2529	uint32_t fFlags, PPDMPCIDEV pPciDev, uint32_t iPciRegion,
2530	PFNIOMMMIONEWWRITE pfnWrite, PFNIOMMMIONEWREAD pfnRead, PFNIOMMMIONEWFILL pfnFill,
2531	void pvUser, const char pszDesc, PIOMMMIOHANDLE phRegion));
2532
2533	/**
2534	* Maps a memory mapped I/O (MMIO) region (into the guest physical address space).
2535	*
2536	* @returns VBox status.
2537	* @param pDevIns The device instance the region is associated with.
2538	* @param hRegion The MMIO region handle.
2539	* @param GCPhys Where to map the region.
2540	* @note An MMIO range may overlap with base memory if a lot of RAM is
2541	* configured for the VM, in which case we'll drop the base memory
2542	* pages. Presently we will make no attempt to preserve anything that
2543	* happens to be present in the base memory that is replaced, this is
2544	* technically incorrect but it's just not worth the effort to do
2545	* right, at least not at this point.
2546	* @sa PDMDevHlpMmioUnmap, PDMDevHlpMmioCreate, PDMDevHlpMmioCreateEx,
2547	* PDMDevHlpMmioSetUpContext
2548	*/
2549	DECLR3CALLBACKMEMBER(int, pfnMmioMap,(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion, RTGCPHYS GCPhys));
2550
2551	/**
2552	* Unmaps a memory mapped I/O (MMIO) region.
2553	*
2554	* @returns VBox status.
2555	* @param pDevIns The device instance the region is associated with.
2556	* @param hRegion The MMIO region handle.
2557	* @sa PDMDevHlpMmioMap, PDMDevHlpMmioCreate, PDMDevHlpMmioCreateEx,
2558	* PDMDevHlpMmioSetUpContext
2559	*/
2560	DECLR3CALLBACKMEMBER(int, pfnMmioUnmap,(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion));
2561
2562	/**
2563	* Reduces the length of a MMIO range.
2564	*
2565	* This is for implementations of PDMPCIDEV::pfnRegionLoadChangeHookR3 and will
2566	* only work during saved state restore. It will not call the PCI bus code, as
2567	* that is expected to restore the saved resource configuration.
2568	*
2569	* It just adjusts the mapping length of the region so that when pfnMmioMap is
2570	* called it will only map @a cbRegion bytes and not the value set during
2571	* registration.
2572	*
2573	* @return VBox status code.
2574	* @param pDevIns The device owning the range.
2575	* @param hRegion The MMIO region handle.
2576	* @param cbRegion The new size, must be smaller.
2577	*/
2578	DECLR3CALLBACKMEMBER(int, pfnMmioReduce,(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion, RTGCPHYS cbRegion));
2579
2580	/**
2581	* Gets the mapping address of the MMIO region @a hRegion.
2582	*
2583	* @returns Mapping address, NIL_RTGCPHYS if not mapped (or invalid parameters).
2584	* @param pDevIns The device instance to register the ports with.
2585	* @param hRegion The MMIO region handle.
2586	*/
2587	DECLR3CALLBACKMEMBER(RTGCPHYS, pfnMmioGetMappingAddress,(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion));
2588	/** @} */
2589
2590	/** @name MMIO2
2591	* @{ */
2592	/**
2593	* Creates a MMIO2 region.
2594	*
2595	* As mentioned elsewhere, MMIO2 is just RAM spelled differently. It's RAM
2596	* associated with a device. It is also non-shared memory with a permanent
2597	* ring-3 mapping and page backing (presently).
2598	*
2599	* @returns VBox status.
2600	* @param pDevIns The device instance.
2601	* @param pPciDev The PCI device the region is associated with, or
2602	* NULL if no PCI device association.
2603	* @param iPciRegion The region number. Use the PCI region number as
2604	* this must be known to the PCI bus device too. If
2605	* it's not associated with the PCI device, then
2606	* any number up to UINT8_MAX is fine.
2607	* @param cbRegion The size (in bytes) of the region.
2608	* @param fFlags Reserved for future use, must be zero.
2609	* @param pszDesc Pointer to description string. This must not be
2610	* freed.
2611	* @param ppvMapping Where to store the address of the ring-3 mapping
2612	* of the memory.
2613	* @param phRegion Where to return the MMIO2 region handle.
2614	*
2615	* @thread EMT(0)
2616	*/
2617	DECLR3CALLBACKMEMBER(int, pfnMmio2Create,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t iPciRegion, RTGCPHYS cbRegion,
2618	uint32_t fFlags, const char pszDesc, void *ppvMapping, PPGMMMIO2HANDLE phRegion));
2619
2620	/**
2621	* Destroys a MMIO2 region, unmapping it and freeing the memory.
2622	*
2623	* Any physical access handlers registered for the region must be deregistered
2624	* before calling this function.
2625	*
2626	* @returns VBox status code.
2627	* @param pDevIns The device instance.
2628	* @param hRegion The MMIO2 region handle.
2629	* @thread EMT.
2630	*/
2631	DECLR3CALLBACKMEMBER(int, pfnMmio2Destroy,(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion));
2632
2633	/**
2634	* Maps a MMIO2 region (into the guest physical address space).
2635	*
2636	* @returns VBox status.
2637	* @param pDevIns The device instance the region is associated with.
2638	* @param hRegion The MMIO2 region handle.
2639	* @param GCPhys Where to map the region.
2640	* @note A MMIO2 region overlap with base memory if a lot of RAM is
2641	* configured for the VM, in which case we'll drop the base memory
2642	* pages. Presently we will make no attempt to preserve anything that
2643	* happens to be present in the base memory that is replaced, this is
2644	* technically incorrect but it's just not worth the effort to do
2645	* right, at least not at this point.
2646	* @sa PDMDevHlpMmio2Unmap, PDMDevHlpMmio2Create, PDMDevHlpMmio2SetUpContext
2647	*/
2648	DECLR3CALLBACKMEMBER(int, pfnMmio2Map,(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion, RTGCPHYS GCPhys));
2649
2650	/**
2651	* Unmaps a MMIO2 region.
2652	*
2653	* @returns VBox status.
2654	* @param pDevIns The device instance the region is associated with.
2655	* @param hRegion The MMIO2 region handle.
2656	* @sa PDMDevHlpMmio2Map, PDMDevHlpMmio2Create, PDMDevHlpMmio2SetUpContext
2657	*/
2658	DECLR3CALLBACKMEMBER(int, pfnMmio2Unmap,(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion));
2659
2660	/**
2661	* Reduces the length of a MMIO range.
2662	*
2663	* This is for implementations of PDMPCIDEV::pfnRegionLoadChangeHookR3 and will
2664	* only work during saved state restore. It will not call the PCI bus code, as
2665	* that is expected to restore the saved resource configuration.
2666	*
2667	* It just adjusts the mapping length of the region so that when pfnMmioMap is
2668	* called it will only map @a cbRegion bytes and not the value set during
2669	* registration.
2670	*
2671	* @return VBox status code.
2672	* @param pDevIns The device owning the range.
2673	* @param hRegion The MMIO2 region handle.
2674	* @param cbRegion The new size, must be smaller.
2675	*/
2676	DECLR3CALLBACKMEMBER(int, pfnMmio2Reduce,(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion, RTGCPHYS cbRegion));
2677
2678	/**
2679	* Gets the mapping address of the MMIO region @a hRegion.
2680	*
2681	* @returns Mapping address, NIL_RTGCPHYS if not mapped (or invalid parameters).
2682	* @param pDevIns The device instance to register the ports with.
2683	* @param hRegion The MMIO2 region handle.
2684	*/
2685	DECLR3CALLBACKMEMBER(RTGCPHYS, pfnMmio2GetMappingAddress,(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion));
2686
2687	/**
2688	* Changes the number of an MMIO2 or pre-registered MMIO region.
2689	*
2690	* This should only be used to deal with saved state problems, so there is no
2691	* convenience inline wrapper for this method.
2692	*
2693	* @returns VBox status code.
2694	* @param pDevIns The device instance.
2695	* @param hRegion The MMIO2 region handle.
2696	* @param iNewRegion The new region index.
2697	*
2698	* @sa @bugref{9359}
2699	*/
2700	DECLR3CALLBACKMEMBER(int, pfnMmio2ChangeRegionNo,(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion, uint32_t iNewRegion));
2701	/** @} */
2702
2703	/**
2704	* Register a ROM (BIOS) region.
2705	*
2706	* It goes without saying that this is read-only memory. The memory region must be
2707	* in unassigned memory. I.e. from the top of the address space or on the PC in
2708	* the 0xa0000-0xfffff range.
2709	*
2710	* @returns VBox status.
2711	* @param pDevIns The device instance owning the ROM region.
2712	* @param GCPhysStart First physical address in the range.
2713	* Must be page aligned!
2714	* @param cbRange The size of the range (in bytes).
2715	* Must be page aligned!
2716	* @param pvBinary Pointer to the binary data backing the ROM image.
2717	* @param cbBinary The size of the binary pointer. This must
2718	* be equal or smaller than @a cbRange.
2719	* @param fFlags Shadow ROM flags, PGMPHYS_ROM_FLAGS_* in pgm.h.
2720	* @param pszDesc Pointer to description string. This must not be freed.
2721	*
2722	* @remark There is no way to remove the rom, automatically on device cleanup or
2723	* manually from the device yet. At present I doubt we need such features...
2724	*/
2725	DECLR3CALLBACKMEMBER(int, pfnROMRegister,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, uint32_t cbRange,
2726	const void pvBinary, uint32_t cbBinary, uint32_t fFlags, const char pszDesc));
2727
2728	/**
2729	* Changes the protection of shadowed ROM mapping.
2730	*
2731	* This is intented for use by the system BIOS, chipset or device in question to
2732	* change the protection of shadowed ROM code after init and on reset.
2733	*
2734	* @param pDevIns The device instance.
2735	* @param GCPhysStart Where the mapping starts.
2736	* @param cbRange The size of the mapping.
2737	* @param enmProt The new protection type.
2738	*/
2739	DECLR3CALLBACKMEMBER(int, pfnROMProtectShadow,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, uint32_t cbRange, PGMROMPROT enmProt));
2740
2741	/**
2742	* Register a save state data unit.
2743	*
2744	* @returns VBox status.
2745	* @param pDevIns The device instance.
2746	* @param uVersion Data layout version number.
2747	* @param cbGuess The approximate amount of data in the unit.
2748	* Only for progress indicators.
2749	* @param pszBefore Name of data unit which we should be put in
2750	* front of. Optional (NULL).
2751	*
2752	* @param pfnLivePrep Prepare live save callback, optional.
2753	* @param pfnLiveExec Execute live save callback, optional.
2754	* @param pfnLiveVote Vote live save callback, optional.
2755	*
2756	* @param pfnSavePrep Prepare save callback, optional.
2757	* @param pfnSaveExec Execute save callback, optional.
2758	* @param pfnSaveDone Done save callback, optional.
2759	*
2760	* @param pfnLoadPrep Prepare load callback, optional.
2761	* @param pfnLoadExec Execute load callback, optional.
2762	* @param pfnLoadDone Done load callback, optional.
2763	* @remarks Caller enters the device critical section prior to invoking the
2764	* registered callback methods.
2765	*/
2766	DECLR3CALLBACKMEMBER(int, pfnSSMRegister,(PPDMDEVINS pDevIns, uint32_t uVersion, size_t cbGuess, const char *pszBefore,
2767	PFNSSMDEVLIVEPREP pfnLivePrep, PFNSSMDEVLIVEEXEC pfnLiveExec, PFNSSMDEVLIVEVOTE pfnLiveVote,
2768	PFNSSMDEVSAVEPREP pfnSavePrep, PFNSSMDEVSAVEEXEC pfnSaveExec, PFNSSMDEVSAVEDONE pfnSaveDone,
2769	PFNSSMDEVLOADPREP pfnLoadPrep, PFNSSMDEVLOADEXEC pfnLoadExec, PFNSSMDEVLOADDONE pfnLoadDone));
2770
2771	/** @name Exported SSM Functions
2772	* @{ */
2773	DECLR3CALLBACKMEMBER(int, pfnSSMPutStruct,(PSSMHANDLE pSSM, const void *pvStruct, PCSSMFIELD paFields));
2774	DECLR3CALLBACKMEMBER(int, pfnSSMPutStructEx,(PSSMHANDLE pSSM, const void pvStruct, size_t cbStruct, uint32_t fFlags, PCSSMFIELD paFields, void pvUser));
2775	DECLR3CALLBACKMEMBER(int, pfnSSMPutBool,(PSSMHANDLE pSSM, bool fBool));
2776	DECLR3CALLBACKMEMBER(int, pfnSSMPutU8,(PSSMHANDLE pSSM, uint8_t u8));
2777	DECLR3CALLBACKMEMBER(int, pfnSSMPutS8,(PSSMHANDLE pSSM, int8_t i8));
2778	DECLR3CALLBACKMEMBER(int, pfnSSMPutU16,(PSSMHANDLE pSSM, uint16_t u16));
2779	DECLR3CALLBACKMEMBER(int, pfnSSMPutS16,(PSSMHANDLE pSSM, int16_t i16));
2780	DECLR3CALLBACKMEMBER(int, pfnSSMPutU32,(PSSMHANDLE pSSM, uint32_t u32));
2781	DECLR3CALLBACKMEMBER(int, pfnSSMPutS32,(PSSMHANDLE pSSM, int32_t i32));
2782	DECLR3CALLBACKMEMBER(int, pfnSSMPutU64,(PSSMHANDLE pSSM, uint64_t u64));
2783	DECLR3CALLBACKMEMBER(int, pfnSSMPutS64,(PSSMHANDLE pSSM, int64_t i64));
2784	DECLR3CALLBACKMEMBER(int, pfnSSMPutU128,(PSSMHANDLE pSSM, uint128_t u128));
2785	DECLR3CALLBACKMEMBER(int, pfnSSMPutS128,(PSSMHANDLE pSSM, int128_t i128));
2786	DECLR3CALLBACKMEMBER(int, pfnSSMPutUInt,(PSSMHANDLE pSSM, RTUINT u));
2787	DECLR3CALLBACKMEMBER(int, pfnSSMPutSInt,(PSSMHANDLE pSSM, RTINT i));
2788	DECLR3CALLBACKMEMBER(int, pfnSSMPutGCUInt,(PSSMHANDLE pSSM, RTGCUINT u));
2789	DECLR3CALLBACKMEMBER(int, pfnSSMPutGCUIntReg,(PSSMHANDLE pSSM, RTGCUINTREG u));
2790	DECLR3CALLBACKMEMBER(int, pfnSSMPutGCPhys32,(PSSMHANDLE pSSM, RTGCPHYS32 GCPhys));
2791	DECLR3CALLBACKMEMBER(int, pfnSSMPutGCPhys64,(PSSMHANDLE pSSM, RTGCPHYS64 GCPhys));
2792	DECLR3CALLBACKMEMBER(int, pfnSSMPutGCPhys,(PSSMHANDLE pSSM, RTGCPHYS GCPhys));
2793	DECLR3CALLBACKMEMBER(int, pfnSSMPutGCPtr,(PSSMHANDLE pSSM, RTGCPTR GCPtr));
2794	DECLR3CALLBACKMEMBER(int, pfnSSMPutGCUIntPtr,(PSSMHANDLE pSSM, RTGCUINTPTR GCPtr));
2795	DECLR3CALLBACKMEMBER(int, pfnSSMPutRCPtr,(PSSMHANDLE pSSM, RTRCPTR RCPtr));
2796	DECLR3CALLBACKMEMBER(int, pfnSSMPutIOPort,(PSSMHANDLE pSSM, RTIOPORT IOPort));
2797	DECLR3CALLBACKMEMBER(int, pfnSSMPutSel,(PSSMHANDLE pSSM, RTSEL Sel));
2798	DECLR3CALLBACKMEMBER(int, pfnSSMPutMem,(PSSMHANDLE pSSM, const void *pv, size_t cb));
2799	DECLR3CALLBACKMEMBER(int, pfnSSMPutStrZ,(PSSMHANDLE pSSM, const char *psz));
2800	DECLR3CALLBACKMEMBER(int, pfnSSMGetStruct,(PSSMHANDLE pSSM, void *pvStruct, PCSSMFIELD paFields));
2801	DECLR3CALLBACKMEMBER(int, pfnSSMGetStructEx,(PSSMHANDLE pSSM, void pvStruct, size_t cbStruct, uint32_t fFlags, PCSSMFIELD paFields, void pvUser));
2802	DECLR3CALLBACKMEMBER(int, pfnSSMGetBool,(PSSMHANDLE pSSM, bool *pfBool));
2803	DECLR3CALLBACKMEMBER(int, pfnSSMGetBoolV,(PSSMHANDLE pSSM, bool volatile *pfBool));
2804	DECLR3CALLBACKMEMBER(int, pfnSSMGetU8,(PSSMHANDLE pSSM, uint8_t *pu8));
2805	DECLR3CALLBACKMEMBER(int, pfnSSMGetU8V,(PSSMHANDLE pSSM, uint8_t volatile *pu8));
2806	DECLR3CALLBACKMEMBER(int, pfnSSMGetS8,(PSSMHANDLE pSSM, int8_t *pi8));
2807	DECLR3CALLBACKMEMBER(int, pfnSSMGetS8V,(PSSMHANDLE pSSM, int8_t volatile *pi8));
2808	DECLR3CALLBACKMEMBER(int, pfnSSMGetU16,(PSSMHANDLE pSSM, uint16_t *pu16));
2809	DECLR3CALLBACKMEMBER(int, pfnSSMGetU16V,(PSSMHANDLE pSSM, uint16_t volatile *pu16));
2810	DECLR3CALLBACKMEMBER(int, pfnSSMGetS16,(PSSMHANDLE pSSM, int16_t *pi16));
2811	DECLR3CALLBACKMEMBER(int, pfnSSMGetS16V,(PSSMHANDLE pSSM, int16_t volatile *pi16));
2812	DECLR3CALLBACKMEMBER(int, pfnSSMGetU32,(PSSMHANDLE pSSM, uint32_t *pu32));
2813	DECLR3CALLBACKMEMBER(int, pfnSSMGetU32V,(PSSMHANDLE pSSM, uint32_t volatile *pu32));
2814	DECLR3CALLBACKMEMBER(int, pfnSSMGetS32,(PSSMHANDLE pSSM, int32_t *pi32));
2815	DECLR3CALLBACKMEMBER(int, pfnSSMGetS32V,(PSSMHANDLE pSSM, int32_t volatile *pi32));
2816	DECLR3CALLBACKMEMBER(int, pfnSSMGetU64,(PSSMHANDLE pSSM, uint64_t *pu64));
2817	DECLR3CALLBACKMEMBER(int, pfnSSMGetU64V,(PSSMHANDLE pSSM, uint64_t volatile *pu64));
2818	DECLR3CALLBACKMEMBER(int, pfnSSMGetS64,(PSSMHANDLE pSSM, int64_t *pi64));
2819	DECLR3CALLBACKMEMBER(int, pfnSSMGetS64V,(PSSMHANDLE pSSM, int64_t volatile *pi64));
2820	DECLR3CALLBACKMEMBER(int, pfnSSMGetU128,(PSSMHANDLE pSSM, uint128_t *pu128));
2821	DECLR3CALLBACKMEMBER(int, pfnSSMGetU128V,(PSSMHANDLE pSSM, uint128_t volatile *pu128));
2822	DECLR3CALLBACKMEMBER(int, pfnSSMGetS128,(PSSMHANDLE pSSM, int128_t *pi128));
2823	DECLR3CALLBACKMEMBER(int, pfnSSMGetS128V,(PSSMHANDLE pSSM, int128_t volatile *pi128));
2824	DECLR3CALLBACKMEMBER(int, pfnSSMGetGCPhys32,(PSSMHANDLE pSSM, PRTGCPHYS32 pGCPhys));
2825	DECLR3CALLBACKMEMBER(int, pfnSSMGetGCPhys32V,(PSSMHANDLE pSSM, RTGCPHYS32 volatile *pGCPhys));
2826	DECLR3CALLBACKMEMBER(int, pfnSSMGetGCPhys64,(PSSMHANDLE pSSM, PRTGCPHYS64 pGCPhys));
2827	DECLR3CALLBACKMEMBER(int, pfnSSMGetGCPhys64V,(PSSMHANDLE pSSM, RTGCPHYS64 volatile *pGCPhys));
2828	DECLR3CALLBACKMEMBER(int, pfnSSMGetGCPhys,(PSSMHANDLE pSSM, PRTGCPHYS pGCPhys));
2829	DECLR3CALLBACKMEMBER(int, pfnSSMGetGCPhysV,(PSSMHANDLE pSSM, RTGCPHYS volatile *pGCPhys));
2830	DECLR3CALLBACKMEMBER(int, pfnSSMGetUInt,(PSSMHANDLE pSSM, PRTUINT pu));
2831	DECLR3CALLBACKMEMBER(int, pfnSSMGetSInt,(PSSMHANDLE pSSM, PRTINT pi));
2832	DECLR3CALLBACKMEMBER(int, pfnSSMGetGCUInt,(PSSMHANDLE pSSM, PRTGCUINT pu));
2833	DECLR3CALLBACKMEMBER(int, pfnSSMGetGCUIntReg,(PSSMHANDLE pSSM, PRTGCUINTREG pu));
2834	DECLR3CALLBACKMEMBER(int, pfnSSMGetGCPtr,(PSSMHANDLE pSSM, PRTGCPTR pGCPtr));
2835	DECLR3CALLBACKMEMBER(int, pfnSSMGetGCUIntPtr,(PSSMHANDLE pSSM, PRTGCUINTPTR pGCPtr));
2836	DECLR3CALLBACKMEMBER(int, pfnSSMGetRCPtr,(PSSMHANDLE pSSM, PRTRCPTR pRCPtr));
2837	DECLR3CALLBACKMEMBER(int, pfnSSMGetIOPort,(PSSMHANDLE pSSM, PRTIOPORT pIOPort));
2838	DECLR3CALLBACKMEMBER(int, pfnSSMGetSel,(PSSMHANDLE pSSM, PRTSEL pSel));
2839	DECLR3CALLBACKMEMBER(int, pfnSSMGetMem,(PSSMHANDLE pSSM, void *pv, size_t cb));
2840	DECLR3CALLBACKMEMBER(int, pfnSSMGetStrZ,(PSSMHANDLE pSSM, char *psz, size_t cbMax));
2841	DECLR3CALLBACKMEMBER(int, pfnSSMGetStrZEx,(PSSMHANDLE pSSM, char psz, size_t cbMax, size_t pcbStr));
2842	DECLR3CALLBACKMEMBER(int, pfnSSMSkip,(PSSMHANDLE pSSM, size_t cb));
2843	DECLR3CALLBACKMEMBER(int, pfnSSMSkipToEndOfUnit,(PSSMHANDLE pSSM));
2844	DECLR3CALLBACKMEMBER(int, pfnSSMSetLoadError,(PSSMHANDLE pSSM, int rc, RT_SRC_POS_DECL, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(6, 7));
2845	DECLR3CALLBACKMEMBER(int, pfnSSMSetLoadErrorV,(PSSMHANDLE pSSM, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(6, 0));
2846	DECLR3CALLBACKMEMBER(int, pfnSSMSetCfgError,(PSSMHANDLE pSSM, RT_SRC_POS_DECL, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(5, 6));
2847	DECLR3CALLBACKMEMBER(int, pfnSSMSetCfgErrorV,(PSSMHANDLE pSSM, RT_SRC_POS_DECL, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(5, 0));
2848	DECLR3CALLBACKMEMBER(int, pfnSSMHandleGetStatus,(PSSMHANDLE pSSM));
2849	DECLR3CALLBACKMEMBER(SSMAFTER, pfnSSMHandleGetAfter,(PSSMHANDLE pSSM));
2850	DECLR3CALLBACKMEMBER(bool, pfnSSMHandleIsLiveSave,(PSSMHANDLE pSSM));
2851	DECLR3CALLBACKMEMBER(uint32_t, pfnSSMHandleMaxDowntime,(PSSMHANDLE pSSM));
2852	DECLR3CALLBACKMEMBER(uint32_t, pfnSSMHandleHostBits,(PSSMHANDLE pSSM));
2853	DECLR3CALLBACKMEMBER(uint32_t, pfnSSMHandleRevision,(PSSMHANDLE pSSM));
2854	DECLR3CALLBACKMEMBER(uint32_t, pfnSSMHandleVersion,(PSSMHANDLE pSSM));
2855	DECLR3CALLBACKMEMBER(const char *, pfnSSMHandleHostOSAndArch,(PSSMHANDLE pSSM));
2856	/** @} */
2857
2858	/**
2859	* Creates a timer w/ a cross context handle.
2860	*
2861	* @returns VBox status.
2862	* @param pDevIns The device instance.
2863	* @param enmClock The clock to use on this timer.
2864	* @param pfnCallback Callback function.
2865	* @param pvUser User argument for the callback.
2866	* @param fFlags Flags, see TMTIMER_FLAGS_*.
2867	* @param pszDesc Pointer to description string which must stay around
2868	* until the timer is fully destroyed (i.e. a bit after TMTimerDestroy()).
2869	* @param phTimer Where to store the timer handle on success.
2870	* @remarks Caller enters the device critical section prior to invoking the
2871	* callback.
2872	*/
2873	DECLR3CALLBACKMEMBER(int, pfnTimerCreate,(PPDMDEVINS pDevIns, TMCLOCK enmClock, PFNTMTIMERDEV pfnCallback,
2874	void pvUser, uint32_t fFlags, const char pszDesc, PTMTIMERHANDLE phTimer));
2875
2876	/** @name Timer handle method wrappers
2877	* @{ */
2878	DECLR3CALLBACKMEMBER(uint64_t, pfnTimerFromMicro,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMicroSecs));
2879	DECLR3CALLBACKMEMBER(uint64_t, pfnTimerFromMilli,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMilliSecs));
2880	DECLR3CALLBACKMEMBER(uint64_t, pfnTimerFromNano,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cNanoSecs));
2881	DECLR3CALLBACKMEMBER(uint64_t, pfnTimerGet,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
2882	DECLR3CALLBACKMEMBER(uint64_t, pfnTimerGetFreq,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
2883	DECLR3CALLBACKMEMBER(uint64_t, pfnTimerGetNano,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
2884	DECLR3CALLBACKMEMBER(bool, pfnTimerIsActive,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
2885	DECLR3CALLBACKMEMBER(bool, pfnTimerIsLockOwner,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
2886	DECLR3CALLBACKMEMBER(VBOXSTRICTRC, pfnTimerLockClock,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, int rcBusy));
2887	/** Takes the clock lock then enters the specified critical section. */
2888	DECLR3CALLBACKMEMBER(VBOXSTRICTRC, pfnTimerLockClock2,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, PPDMCRITSECT pCritSect, int rcBusy));
2889	DECLR3CALLBACKMEMBER(int, pfnTimerSet,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t uExpire));
2890	DECLR3CALLBACKMEMBER(int, pfnTimerSetFrequencyHint,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint32_t uHz));
2891	DECLR3CALLBACKMEMBER(int, pfnTimerSetMicro,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMicrosToNext));
2892	DECLR3CALLBACKMEMBER(int, pfnTimerSetMillies,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMilliesToNext));
2893	DECLR3CALLBACKMEMBER(int, pfnTimerSetNano,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cNanosToNext));
2894	DECLR3CALLBACKMEMBER(int, pfnTimerSetRelative,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cTicksToNext, uint64_t *pu64Now));
2895	DECLR3CALLBACKMEMBER(int, pfnTimerStop,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
2896	DECLR3CALLBACKMEMBER(void, pfnTimerUnlockClock,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
2897	DECLR3CALLBACKMEMBER(void, pfnTimerUnlockClock2,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, PPDMCRITSECT pCritSect));
2898	DECLR3CALLBACKMEMBER(int, pfnTimerSetCritSect,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, PPDMCRITSECT pCritSect));
2899	DECLR3CALLBACKMEMBER(int, pfnTimerSave,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, PSSMHANDLE pSSM));
2900	DECLR3CALLBACKMEMBER(int, pfnTimerLoad,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, PSSMHANDLE pSSM));
2901	DECLR3CALLBACKMEMBER(int, pfnTimerDestroy,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
2902	/** @sa TMR3TimerSkip */
2903	DECLR3CALLBACKMEMBER(int, pfnTimerSkipLoad,(PSSMHANDLE pSSM, bool *pfActive));
2904	/** @} */
2905
2906	/**
2907	* Get the real world UTC time adjusted for VM lag, user offset and warpdrive.
2908	*
2909	* @returns pTime.
2910	* @param pDevIns The device instance.
2911	* @param pTime Where to store the time.
2912	*/
2913	DECLR3CALLBACKMEMBER(PRTTIMESPEC, pfnTMUtcNow,(PPDMDEVINS pDevIns, PRTTIMESPEC pTime));
2914
2915	/** @name Exported CFGM Functions.
2916	* @{ */
2917	DECLR3CALLBACKMEMBER(bool, pfnCFGMExists,( PCFGMNODE pNode, const char *pszName));
2918	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryType,( PCFGMNODE pNode, const char *pszName, PCFGMVALUETYPE penmType));
2919	DECLR3CALLBACKMEMBER(int, pfnCFGMQuerySize,( PCFGMNODE pNode, const char pszName, size_t pcb));
2920	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryInteger,( PCFGMNODE pNode, const char pszName, uint64_t pu64));
2921	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryIntegerDef,( PCFGMNODE pNode, const char pszName, uint64_t pu64, uint64_t u64Def));
2922	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryString,( PCFGMNODE pNode, const char pszName, char pszString, size_t cchString));
2923	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryStringDef,( PCFGMNODE pNode, const char pszName, char pszString, size_t cchString, const char *pszDef));
2924	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryBytes,( PCFGMNODE pNode, const char pszName, void pvData, size_t cbData));
2925	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryU64,( PCFGMNODE pNode, const char pszName, uint64_t pu64));
2926	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryU64Def,( PCFGMNODE pNode, const char pszName, uint64_t pu64, uint64_t u64Def));
2927	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryS64,( PCFGMNODE pNode, const char pszName, int64_t pi64));
2928	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryS64Def,( PCFGMNODE pNode, const char pszName, int64_t pi64, int64_t i64Def));
2929	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryU32,( PCFGMNODE pNode, const char pszName, uint32_t pu32));
2930	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryU32Def,( PCFGMNODE pNode, const char pszName, uint32_t pu32, uint32_t u32Def));
2931	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryS32,( PCFGMNODE pNode, const char pszName, int32_t pi32));
2932	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryS32Def,( PCFGMNODE pNode, const char pszName, int32_t pi32, int32_t i32Def));
2933	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryU16,( PCFGMNODE pNode, const char pszName, uint16_t pu16));
2934	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryU16Def,( PCFGMNODE pNode, const char pszName, uint16_t pu16, uint16_t u16Def));
2935	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryS16,( PCFGMNODE pNode, const char pszName, int16_t pi16));
2936	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryS16Def,( PCFGMNODE pNode, const char pszName, int16_t pi16, int16_t i16Def));
2937	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryU8,( PCFGMNODE pNode, const char pszName, uint8_t pu8));
2938	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryU8Def,( PCFGMNODE pNode, const char pszName, uint8_t pu8, uint8_t u8Def));
2939	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryS8,( PCFGMNODE pNode, const char pszName, int8_t pi8));
2940	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryS8Def,( PCFGMNODE pNode, const char pszName, int8_t pi8, int8_t i8Def));
2941	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryBool,( PCFGMNODE pNode, const char pszName, bool pf));
2942	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryBoolDef,( PCFGMNODE pNode, const char pszName, bool pf, bool fDef));
2943	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryPort,( PCFGMNODE pNode, const char *pszName, PRTIOPORT pPort));
2944	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryPortDef,( PCFGMNODE pNode, const char *pszName, PRTIOPORT pPort, RTIOPORT PortDef));
2945	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryUInt,( PCFGMNODE pNode, const char pszName, unsigned int pu));
2946	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryUIntDef,( PCFGMNODE pNode, const char pszName, unsigned int pu, unsigned int uDef));
2947	DECLR3CALLBACKMEMBER(int, pfnCFGMQuerySInt,( PCFGMNODE pNode, const char pszName, signed int pi));
2948	DECLR3CALLBACKMEMBER(int, pfnCFGMQuerySIntDef,( PCFGMNODE pNode, const char pszName, signed int pi, signed int iDef));
2949	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryPtr,( PCFGMNODE pNode, const char pszName, void *ppv));
2950	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryPtrDef,( PCFGMNODE pNode, const char pszName, void ppv, void pvDef));
2951	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryGCPtr,( PCFGMNODE pNode, const char *pszName, PRTGCPTR pGCPtr));
2952	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryGCPtrDef,( PCFGMNODE pNode, const char *pszName, PRTGCPTR pGCPtr, RTGCPTR GCPtrDef));
2953	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryGCPtrU,( PCFGMNODE pNode, const char *pszName, PRTGCUINTPTR pGCPtr));
2954	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryGCPtrUDef,( PCFGMNODE pNode, const char *pszName, PRTGCUINTPTR pGCPtr, RTGCUINTPTR GCPtrDef));
2955	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryGCPtrS,( PCFGMNODE pNode, const char *pszName, PRTGCINTPTR pGCPtr));
2956	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryGCPtrSDef,( PCFGMNODE pNode, const char *pszName, PRTGCINTPTR pGCPtr, RTGCINTPTR GCPtrDef));
2957	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryStringAlloc,( PCFGMNODE pNode, const char pszName, char *ppszString));
2958	DECLR3CALLBACKMEMBER(int, pfnCFGMQueryStringAllocDef,(PCFGMNODE pNode, const char pszName, char ppszString, const char pszDef));
2959	DECLR3CALLBACKMEMBER(PCFGMNODE, pfnCFGMGetParent,(PCFGMNODE pNode));
2960	DECLR3CALLBACKMEMBER(PCFGMNODE, pfnCFGMGetChild,(PCFGMNODE pNode, const char *pszPath));
2961	DECLR3CALLBACKMEMBER(PCFGMNODE, pfnCFGMGetChildF,(PCFGMNODE pNode, const char *pszPathFormat, ...) RT_IPRT_FORMAT_ATTR(2, 3));
2962	DECLR3CALLBACKMEMBER(PCFGMNODE, pfnCFGMGetChildFV,(PCFGMNODE pNode, const char *pszPathFormat, va_list Args) RT_IPRT_FORMAT_ATTR(3, 0));
2963	DECLR3CALLBACKMEMBER(PCFGMNODE, pfnCFGMGetFirstChild,(PCFGMNODE pNode));
2964	DECLR3CALLBACKMEMBER(PCFGMNODE, pfnCFGMGetNextChild,(PCFGMNODE pCur));
2965	DECLR3CALLBACKMEMBER(int, pfnCFGMGetName,(PCFGMNODE pCur, char *pszName, size_t cchName));
2966	DECLR3CALLBACKMEMBER(size_t, pfnCFGMGetNameLen,(PCFGMNODE pCur));
2967	DECLR3CALLBACKMEMBER(bool, pfnCFGMAreChildrenValid,(PCFGMNODE pNode, const char *pszzValid));
2968	DECLR3CALLBACKMEMBER(PCFGMLEAF, pfnCFGMGetFirstValue,(PCFGMNODE pCur));
2969	DECLR3CALLBACKMEMBER(PCFGMLEAF, pfnCFGMGetNextValue,(PCFGMLEAF pCur));
2970	DECLR3CALLBACKMEMBER(int, pfnCFGMGetValueName,(PCFGMLEAF pCur, char *pszName, size_t cchName));
2971	DECLR3CALLBACKMEMBER(size_t, pfnCFGMGetValueNameLen,(PCFGMLEAF pCur));
2972	DECLR3CALLBACKMEMBER(CFGMVALUETYPE, pfnCFGMGetValueType,(PCFGMLEAF pCur));
2973	DECLR3CALLBACKMEMBER(bool, pfnCFGMAreValuesValid,(PCFGMNODE pNode, const char *pszzValid));
2974	DECLR3CALLBACKMEMBER(int, pfnCFGMValidateConfig,(PCFGMNODE pNode, const char *pszNode,
2975	const char pszValidValues, const char pszValidNodes,
2976	const char *pszWho, uint32_t uInstance));
2977	/** @} */
2978
2979	/**
2980	* Read physical memory.
2981	*
2982	* @returns VINF_SUCCESS (for now).
2983	* @param pDevIns The device instance.
2984	* @param GCPhys Physical address start reading from.
2985	* @param pvBuf Where to put the read bits.
2986	* @param cbRead How many bytes to read.
2987	* @param fFlags Combination of PDM_DEVHLP_PHYS_RW_F_XXX.
2988	* @thread Any thread, but the call may involve the emulation thread.
2989	*/
2990	DECLR3CALLBACKMEMBER(int, pfnPhysRead,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead, uint32_t fFlags));
2991
2992	/**
2993	* Write to physical memory.
2994	*
2995	* @returns VINF_SUCCESS for now, and later maybe VERR_EM_MEMORY.
2996	* @param pDevIns The device instance.
2997	* @param GCPhys Physical address to write to.
2998	* @param pvBuf What to write.
2999	* @param cbWrite How many bytes to write.
3000	* @param fFlags Combination of PDM_DEVHLP_PHYS_RW_F_XXX.
3001	* @thread Any thread, but the call may involve the emulation thread.
3002	*/
3003	DECLR3CALLBACKMEMBER(int, pfnPhysWrite,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite, uint32_t fFlags));
3004
3005	/**
3006	* Requests the mapping of a guest page into ring-3.
3007	*
3008	* When you're done with the page, call pfnPhysReleasePageMappingLock() ASAP to
3009	* release it.
3010	*
3011	* This API will assume your intention is to write to the page, and will
3012	* therefore replace shared and zero pages. If you do not intend to modify the
3013	* page, use the pfnPhysGCPhys2CCPtrReadOnly() API.
3014	*
3015	* @returns VBox status code.
3016	* @retval VINF_SUCCESS on success.
3017	* @retval VERR_PGM_PHYS_PAGE_RESERVED it it's a valid page but has no physical
3018	* backing or if the page has any active access handlers. The caller
3019	* must fall back on using PGMR3PhysWriteExternal.
3020	* @retval VERR_PGM_INVALID_GC_PHYSICAL_ADDRESS if it's not a valid physical address.
3021	*
3022	* @param pDevIns The device instance.
3023	* @param GCPhys The guest physical address of the page that
3024	* should be mapped.
3025	* @param fFlags Flags reserved for future use, MBZ.
3026	* @param ppv Where to store the address corresponding to
3027	* GCPhys.
3028	* @param pLock Where to store the lock information that
3029	* pfnPhysReleasePageMappingLock needs.
3030	*
3031	* @remark Avoid calling this API from within critical sections (other than the
3032	* PGM one) because of the deadlock risk when we have to delegating the
3033	* task to an EMT.
3034	* @thread Any.
3035	*/
3036	DECLR3CALLBACKMEMBER(int, pfnPhysGCPhys2CCPtr,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, uint32_t fFlags, void **ppv,
3037	PPGMPAGEMAPLOCK pLock));
3038
3039	/**
3040	* Requests the mapping of a guest page into ring-3, external threads.
3041	*
3042	* When you're done with the page, call pfnPhysReleasePageMappingLock() ASAP to
3043	* release it.
3044	*
3045	* @returns VBox status code.
3046	* @retval VINF_SUCCESS on success.
3047	* @retval VERR_PGM_PHYS_PAGE_RESERVED it it's a valid page but has no physical
3048	* backing or if the page as an active ALL access handler. The caller
3049	* must fall back on using PGMPhysRead.
3050	* @retval VERR_PGM_INVALID_GC_PHYSICAL_ADDRESS if it's not a valid physical address.
3051	*
3052	* @param pDevIns The device instance.
3053	* @param GCPhys The guest physical address of the page that
3054	* should be mapped.
3055	* @param fFlags Flags reserved for future use, MBZ.
3056	* @param ppv Where to store the address corresponding to
3057	* GCPhys.
3058	* @param pLock Where to store the lock information that
3059	* pfnPhysReleasePageMappingLock needs.
3060	*
3061	* @remark Avoid calling this API from within critical sections.
3062	* @thread Any.
3063	*/
3064	DECLR3CALLBACKMEMBER(int, pfnPhysGCPhys2CCPtrReadOnly,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, uint32_t fFlags,
3065	void const **ppv, PPGMPAGEMAPLOCK pLock));
3066
3067	/**
3068	* Release the mapping of a guest page.
3069	*
3070	* This is the counter part of pfnPhysGCPhys2CCPtr and
3071	* pfnPhysGCPhys2CCPtrReadOnly.
3072	*
3073	* @param pDevIns The device instance.
3074	* @param pLock The lock structure initialized by the mapping
3075	* function.
3076	*/
3077	DECLR3CALLBACKMEMBER(void, pfnPhysReleasePageMappingLock,(PPDMDEVINS pDevIns, PPGMPAGEMAPLOCK pLock));
3078
3079	/**
3080	* Read guest physical memory by virtual address.
3081	*
3082	* @param pDevIns The device instance.
3083	* @param pvDst Where to put the read bits.
3084	* @param GCVirtSrc Guest virtual address to start reading from.
3085	* @param cb How many bytes to read.
3086	* @thread The emulation thread.
3087	*/
3088	DECLR3CALLBACKMEMBER(int, pfnPhysReadGCVirt,(PPDMDEVINS pDevIns, void *pvDst, RTGCPTR GCVirtSrc, size_t cb));
3089
3090	/**
3091	* Write to guest physical memory by virtual address.
3092	*
3093	* @param pDevIns The device instance.
3094	* @param GCVirtDst Guest virtual address to write to.
3095	* @param pvSrc What to write.
3096	* @param cb How many bytes to write.
3097	* @thread The emulation thread.
3098	*/
3099	DECLR3CALLBACKMEMBER(int, pfnPhysWriteGCVirt,(PPDMDEVINS pDevIns, RTGCPTR GCVirtDst, const void *pvSrc, size_t cb));
3100
3101	/**
3102	* Convert a guest virtual address to a guest physical address.
3103	*
3104	* @returns VBox status code.
3105	* @param pDevIns The device instance.
3106	* @param GCPtr Guest virtual address.
3107	* @param pGCPhys Where to store the GC physical address
3108	* corresponding to GCPtr.
3109	* @thread The emulation thread.
3110	* @remark Careful with page boundaries.
3111	*/
3112	DECLR3CALLBACKMEMBER(int, pfnPhysGCPtr2GCPhys, (PPDMDEVINS pDevIns, RTGCPTR GCPtr, PRTGCPHYS pGCPhys));
3113
3114	/**
3115	* Allocate memory which is associated with current VM instance
3116	* and automatically freed on it's destruction.
3117	*
3118	* @returns Pointer to allocated memory. The memory is NOT zero-ed.
3119	* @param pDevIns The device instance.
3120	* @param cb Number of bytes to allocate.
3121	*/
3122	DECLR3CALLBACKMEMBER(void *, pfnMMHeapAlloc,(PPDMDEVINS pDevIns, size_t cb));
3123
3124	/**
3125	* Allocate memory which is associated with current VM instance
3126	* and automatically freed on it's destruction. The memory is ZEROed.
3127	*
3128	* @returns Pointer to allocated memory. The memory is NOT zero-ed.
3129	* @param pDevIns The device instance.
3130	* @param cb Number of bytes to allocate.
3131	*/
3132	DECLR3CALLBACKMEMBER(void *, pfnMMHeapAllocZ,(PPDMDEVINS pDevIns, size_t cb));
3133
3134	/**
3135	* Free memory allocated with pfnMMHeapAlloc() and pfnMMHeapAllocZ().
3136	*
3137	* @param pDevIns The device instance.
3138	* @param pv Pointer to the memory to free.
3139	*/
3140	DECLR3CALLBACKMEMBER(void, pfnMMHeapFree,(PPDMDEVINS pDevIns, void *pv));
3141
3142	/**
3143	* Gets the VM state.
3144	*
3145	* @returns VM state.
3146	* @param pDevIns The device instance.
3147	* @thread Any thread (just keep in mind that it's volatile info).
3148	*/
3149	DECLR3CALLBACKMEMBER(VMSTATE, pfnVMState, (PPDMDEVINS pDevIns));
3150
3151	/**
3152	* Checks if the VM was teleported and hasn't been fully resumed yet.
3153	*
3154	* @returns true / false.
3155	* @param pDevIns The device instance.
3156	* @thread Any thread.
3157	*/
3158	DECLR3CALLBACKMEMBER(bool, pfnVMTeleportedAndNotFullyResumedYet,(PPDMDEVINS pDevIns));
3159
3160	/**
3161	* Set the VM error message
3162	*
3163	* @returns rc.
3164	* @param pDevIns The device instance.
3165	* @param rc VBox status code.
3166	* @param SRC_POS Use RT_SRC_POS.
3167	* @param pszFormat Error message format string.
3168	* @param ... Error message arguments.
3169	*/
3170	DECLR3CALLBACKMEMBER(int, pfnVMSetError,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL,
3171	const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(6, 7));
3172
3173	/**
3174	* Set the VM error message
3175	*
3176	* @returns rc.
3177	* @param pDevIns The device instance.
3178	* @param rc VBox status code.
3179	* @param SRC_POS Use RT_SRC_POS.
3180	* @param pszFormat Error message format string.
3181	* @param va Error message arguments.
3182	*/
3183	DECLR3CALLBACKMEMBER(int, pfnVMSetErrorV,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL,
3184	const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(6, 0));
3185
3186	/**
3187	* Set the VM runtime error message
3188	*
3189	* @returns VBox status code.
3190	* @param pDevIns The device instance.
3191	* @param fFlags The action flags. See VMSETRTERR_FLAGS_*.
3192	* @param pszErrorId Error ID string.
3193	* @param pszFormat Error message format string.
3194	* @param ... Error message arguments.
3195	*/
3196	DECLR3CALLBACKMEMBER(int, pfnVMSetRuntimeError,(PPDMDEVINS pDevIns, uint32_t fFlags, const char *pszErrorId,
3197	const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(4, 5));
3198
3199	/**
3200	* Set the VM runtime error message
3201	*
3202	* @returns VBox status code.
3203	* @param pDevIns The device instance.
3204	* @param fFlags The action flags. See VMSETRTERR_FLAGS_*.
3205	* @param pszErrorId Error ID string.
3206	* @param pszFormat Error message format string.
3207	* @param va Error message arguments.
3208	*/
3209	DECLR3CALLBACKMEMBER(int, pfnVMSetRuntimeErrorV,(PPDMDEVINS pDevIns, uint32_t fFlags, const char *pszErrorId,
3210	const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(4, 0));
3211
3212	/**
3213	* Stops the VM and enters the debugger to look at the guest state.
3214	*
3215	* Use the PDMDeviceDBGFStop() inline function with the RT_SRC_POS macro instead of
3216	* invoking this function directly.
3217	*
3218	* @returns VBox status code which must be passed up to the VMM.
3219	* @param pDevIns The device instance.
3220	* @param pszFile Filename of the assertion location.
3221	* @param iLine The linenumber of the assertion location.
3222	* @param pszFunction Function of the assertion location.
3223	* @param pszFormat Message. (optional)
3224	* @param args Message parameters.
3225	*/
3226	DECLR3CALLBACKMEMBER(int, pfnDBGFStopV,(PPDMDEVINS pDevIns, const char pszFile, unsigned iLine, const char pszFunction,
3227	const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(5, 0));
3228
3229	/**
3230	* Register a info handler with DBGF.
3231	*
3232	* @returns VBox status code.
3233	* @param pDevIns The device instance.
3234	* @param pszName The identifier of the info.
3235	* @param pszDesc The description of the info and any arguments
3236	* the handler may take.
3237	* @param pfnHandler The handler function to be called to display the
3238	* info.
3239	*/
3240	DECLR3CALLBACKMEMBER(int, pfnDBGFInfoRegister,(PPDMDEVINS pDevIns, const char pszName, const char pszDesc, PFNDBGFHANDLERDEV pfnHandler));
3241
3242	/**
3243	* Register a info handler with DBGF, argv style.
3244	*
3245	* @returns VBox status code.
3246	* @param pDevIns The device instance.
3247	* @param pszName The identifier of the info.
3248	* @param pszDesc The description of the info and any arguments
3249	* the handler may take.
3250	* @param pfnHandler The handler function to be called to display the
3251	* info.
3252	*/
3253	DECLR3CALLBACKMEMBER(int, pfnDBGFInfoRegisterArgv,(PPDMDEVINS pDevIns, const char pszName, const char pszDesc, PFNDBGFINFOARGVDEV pfnHandler));
3254
3255	/**
3256	* Registers a set of registers for a device.
3257	*
3258	* The @a pvUser argument of the getter and setter callbacks will be
3259	* @a pDevIns. The register names will be prefixed by the device name followed
3260	* immediately by the instance number.
3261	*
3262	* @returns VBox status code.
3263	* @param pDevIns The device instance.
3264	* @param paRegisters The register descriptors.
3265	*
3266	* @remarks The device critical section is NOT entered prior to working the
3267	* callbacks registered via this helper!
3268	*/
3269	DECLR3CALLBACKMEMBER(int, pfnDBGFRegRegister,(PPDMDEVINS pDevIns, PCDBGFREGDESC paRegisters));
3270
3271	/**
3272	* Gets the trace buffer handle.
3273	*
3274	* This is used by the macros found in VBox/vmm/dbgftrace.h and is not
3275	* really inteded for direct usage, thus no inline wrapper function.
3276	*
3277	* @returns Trace buffer handle or NIL_RTTRACEBUF.
3278	* @param pDevIns The device instance.
3279	*/
3280	DECLR3CALLBACKMEMBER(RTTRACEBUF, pfnDBGFTraceBuf,(PPDMDEVINS pDevIns));
3281
3282	/**
3283	* Registers a statistics sample.
3284	*
3285	* @param pDevIns Device instance of the DMA.
3286	* @param pvSample Pointer to the sample.
3287	* @param enmType Sample type. This indicates what pvSample is
3288	* pointing at.
3289	* @param pszName Sample name, unix path style. If this does not
3290	* start with a '/', the default prefix will be
3291	* prepended, otherwise it will be used as-is.
3292	* @param enmUnit Sample unit.
3293	* @param pszDesc Sample description.
3294	*/
3295	DECLR3CALLBACKMEMBER(void, pfnSTAMRegister,(PPDMDEVINS pDevIns, void pvSample, STAMTYPE enmType, const char pszName, STAMUNIT enmUnit, const char *pszDesc));
3296
3297	/**
3298	* Same as pfnSTAMRegister except that the name is specified in a
3299	* RTStrPrintfV like fashion.
3300	*
3301	* @returns VBox status.
3302	* @param pDevIns Device instance of the DMA.
3303	* @param pvSample Pointer to the sample.
3304	* @param enmType Sample type. This indicates what pvSample is
3305	* pointing at.
3306	* @param enmVisibility Visibility type specifying whether unused
3307	* statistics should be visible or not.
3308	* @param enmUnit Sample unit.
3309	* @param pszDesc Sample description.
3310	* @param pszName Sample name format string, unix path style. If
3311	* this does not start with a '/', the default
3312	* prefix will be prepended, otherwise it will be
3313	* used as-is.
3314	* @param args Arguments to the format string.
3315	*/
3316	DECLR3CALLBACKMEMBER(void, pfnSTAMRegisterV,(PPDMDEVINS pDevIns, void *pvSample, STAMTYPE enmType,
3317	STAMVISIBILITY enmVisibility, STAMUNIT enmUnit, const char *pszDesc,
3318	const char *pszName, va_list args) RT_IPRT_FORMAT_ATTR(7, 0));
3319
3320	/**
3321	* Registers a PCI device with the default PCI bus.
3322	*
3323	* If a PDM device has more than one PCI device, they must be registered in the
3324	* order of PDMDEVINSR3::apPciDevs.
3325	*
3326	* @returns VBox status code.
3327	* @param pDevIns The device instance.
3328	* @param pPciDev The PCI device structure.
3329	* This must be kept in the instance data.
3330	* The PCI configuration must be initialized before registration.
3331	* @param fFlags 0, PDMPCIDEVREG_F_PCI_BRIDGE or
3332	* PDMPCIDEVREG_F_NOT_MANDATORY_NO.
3333	* @param uPciDevNo PDMPCIDEVREG_DEV_NO_FIRST_UNUSED,
3334	* PDMPCIDEVREG_DEV_NO_SAME_AS_PREV, or a specific
3335	* device number (0-31). This will be ignored if
3336	* the CFGM configuration contains a PCIDeviceNo
3337	* value.
3338	* @param uPciFunNo PDMPCIDEVREG_FUN_NO_FIRST_UNUSED, or a specific
3339	* function number (0-7). This will be ignored if
3340	* the CFGM configuration contains a PCIFunctionNo
3341	* value.
3342	* @param pszName Device name, if NULL PDMDEVREG::szName is used.
3343	* The pointer is saved, so don't free or changed.
3344	* @note The PCI device configuration is now implicit from the apPciDevs
3345	* index, meaning that the zero'th entry is the primary one and
3346	* subsequent uses CFGM subkeys "PciDev1", "PciDev2" and so on.
3347	*/
3348	DECLR3CALLBACKMEMBER(int, pfnPCIRegister,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t fFlags,
3349	uint8_t uPciDevNo, uint8_t uPciFunNo, const char *pszName));
3350
3351	/**
3352	* Initialize MSI or MSI-X emulation support for the given PCI device.
3353	*
3354	* @see PDMPCIBUSREG::pfnRegisterMsiR3 for details.
3355	*
3356	* @returns VBox status code.
3357	* @param pDevIns The device instance.
3358	* @param pPciDev The PCI device. NULL is an alias for the first
3359	* one registered.
3360	* @param pMsiReg MSI emulation registration structure.
3361	*/
3362	DECLR3CALLBACKMEMBER(int, pfnPCIRegisterMsi,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, PPDMMSIREG pMsiReg));
3363
3364	/**
3365	* Registers a I/O region (memory mapped or I/O ports) for a PCI device.
3366	*
3367	* @returns VBox status code.
3368	* @param pDevIns The device instance.
3369	* @param pPciDev The PCI device structure. If NULL the default
3370	* PCI device for this device instance is used.
3371	* @param iRegion The region number.
3372	* @param cbRegion Size of the region.
3373	* @param enmType PCI_ADDRESS_SPACE_MEM, PCI_ADDRESS_SPACE_IO or PCI_ADDRESS_SPACE_MEM_PREFETCH.
3374	* @param fFlags PDMPCIDEV_IORGN_F_XXX.
3375	* @param hHandle An I/O port, MMIO or MMIO2 handle according to
3376	* @a fFlags, UINT64_MAX if no handle is passed
3377	* (old style).
3378	* @param pfnMapUnmap Callback for doing the mapping, optional when a
3379	* handle is specified. The callback will be
3380	* invoked holding only the PDM lock. The device
3381	* lock will _not_ be taken (due to lock order).
3382	*/
3383	DECLR3CALLBACKMEMBER(int, pfnPCIIORegionRegister,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t iRegion,
3384	RTGCPHYS cbRegion, PCIADDRESSSPACE enmType, uint32_t fFlags,
3385	uint64_t hHandle, PFNPCIIOREGIONMAP pfnMapUnmap));
3386
3387	/**
3388	* Register PCI configuration space read/write callbacks.
3389	*
3390	* @returns VBox status code.
3391	* @param pDevIns The device instance.
3392	* @param pPciDev The PCI device structure. If NULL the default
3393	* PCI device for this device instance is used.
3394	* @param pfnRead Pointer to the user defined PCI config read function.
3395	* to call default PCI config read function. Can be NULL.
3396	* @param pfnWrite Pointer to the user defined PCI config write function.
3397	* @remarks The callbacks will be invoked holding the PDM lock. The device lock
3398	* is NOT take because that is very likely be a lock order violation.
3399	* @thread EMT(0)
3400	* @note Only callable during VM creation.
3401	* @sa PDMDevHlpPCIConfigRead, PDMDevHlpPCIConfigWrite
3402	*/
3403	DECLR3CALLBACKMEMBER(int, pfnPCIInterceptConfigAccesses,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev,
3404	PFNPCICONFIGREAD pfnRead, PFNPCICONFIGWRITE pfnWrite));
3405
3406	/**
3407	* Perform a PCI configuration space write.
3408	*
3409	* This is for devices that make use of PDMDevHlpPCIInterceptConfigAccesses().
3410	*
3411	* @returns Strict VBox status code (mainly DBGFSTOP).
3412	* @param pDevIns The device instance.
3413	* @param pPciDev The PCI device which config space is being read.
3414	* @param uAddress The config space address.
3415	* @param cb The size of the read: 1, 2 or 4 bytes.
3416	* @param u32Value The value to write.
3417	*/
3418	DECLR3CALLBACKMEMBER(VBOXSTRICTRC, pfnPCIConfigWrite,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev,
3419	uint32_t uAddress, unsigned cb, uint32_t u32Value));
3420
3421	/**
3422	* Perform a PCI configuration space read.
3423	*
3424	* This is for devices that make use of PDMDevHlpPCIInterceptConfigAccesses().
3425	*
3426	* @returns Strict VBox status code (mainly DBGFSTOP).
3427	* @param pDevIns The device instance.
3428	* @param pPciDev The PCI device which config space is being read.
3429	* @param uAddress The config space address.
3430	* @param cb The size of the read: 1, 2 or 4 bytes.
3431	* @param pu32Value Where to return the value.
3432	*/
3433	DECLR3CALLBACKMEMBER(VBOXSTRICTRC, pfnPCIConfigRead,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev,
3434	uint32_t uAddress, unsigned cb, uint32_t *pu32Value));
3435
3436	/**
3437	* Bus master physical memory read.
3438	*
3439	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_READ_BM_DISABLED, later maybe
3440	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
3441	* @param pDevIns The device instance.
3442	* @param pPciDev The PCI device structure. If NULL the default
3443	* PCI device for this device instance is used.
3444	* @param GCPhys Physical address start reading from.
3445	* @param pvBuf Where to put the read bits.
3446	* @param cbRead How many bytes to read.
3447	* @param fFlags Combination of PDM_DEVHLP_PHYS_RW_F_XXX.
3448	* @thread Any thread, but the call may involve the emulation thread.
3449	*/
3450	DECLR3CALLBACKMEMBER(int, pfnPCIPhysRead,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead, uint32_t fFlags));
3451
3452	/**
3453	* Bus master physical memory write.
3454	*
3455	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_WRITE_BM_DISABLED, later maybe
3456	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
3457	* @param pDevIns The device instance.
3458	* @param pPciDev The PCI device structure. If NULL the default
3459	* PCI device for this device instance is used.
3460	* @param GCPhys Physical address to write to.
3461	* @param pvBuf What to write.
3462	* @param cbWrite How many bytes to write.
3463	* @param fFlags Combination of PDM_DEVHLP_PHYS_RW_F_XXX.
3464	* @thread Any thread, but the call may involve the emulation thread.
3465	*/
3466	DECLR3CALLBACKMEMBER(int, pfnPCIPhysWrite,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite, uint32_t fFlags));
3467
3468	/**
3469	* Requests the mapping of a guest page into ring-3 in preparation for a bus master
3470	* physical memory write operation.
3471	*
3472	* Refer pfnPhysGCPhys2CCPtr() for further details.
3473	*
3474	* @returns VBox status code.
3475	* @param pDevIns The device instance.
3476	* @param pPciDev The PCI device structure. If NULL the default
3477	* PCI device for this device instance is used.
3478	* @param GCPhys The guest physical address of the page that should be
3479	* mapped.
3480	* @param fFlags Flags reserved for future use, MBZ.
3481	* @param ppv Where to store the address corresponding to GCPhys.
3482	* @param pLock Where to store the lock information that
3483	* pfnPhysReleasePageMappingLock needs.
3484	*
3485	* @remarks Avoid calling this API from within critical sections (other than the PGM
3486	* one) because of the deadlock risk when we have to delegating the task to
3487	* an EMT.
3488	* @thread Any.
3489	*/
3490	DECLR3CALLBACKMEMBER(int, pfnPCIPhysGCPhys2CCPtr,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys, uint32_t fFlags,
3491	void **ppv, PPGMPAGEMAPLOCK pLock));
3492
3493	/**
3494	* Requests the mapping of a guest page into ring-3, external threads, in prepartion
3495	* for a bus master physical memory read operation.
3496	*
3497	* Refer pfnPhysGCPhys2CCPtrReadOnly() for further details.
3498	*
3499	* @returns VBox status code.
3500	* @param pDevIns The device instance.
3501	* @param pPciDev The PCI device structure. If NULL the default
3502	* PCI device for this device instance is used.
3503	* @param GCPhys The guest physical address of the page that
3504	* should be mapped.
3505	* @param fFlags Flags reserved for future use, MBZ.
3506	* @param ppv Where to store the address corresponding to
3507	* GCPhys.
3508	* @param pLock Where to store the lock information that
3509	* pfnPhysReleasePageMappingLock needs.
3510	*
3511	* @remarks Avoid calling this API from within critical sections.
3512	* @thread Any.
3513	*/
3514	DECLR3CALLBACKMEMBER(int, pfnPCIPhysGCPhys2CCPtrReadOnly,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys,
3515	uint32_t fFlags, void const **ppv, PPGMPAGEMAPLOCK pLock));
3516
3517	/**
3518	* Requests the mapping of multiple guest pages into ring-3 in prepartion for a bus
3519	* master physical memory write operation.
3520	*
3521	* When you're done with the pages, call pfnPhysBulkReleasePageMappingLocks()
3522	* ASAP to release them.
3523	*
3524	* Refer pfnPhysBulkGCPhys2CCPtr() for further details.
3525	*
3526	* @returns VBox status code.
3527	* @param pDevIns The device instance.
3528	* @param pPciDev The PCI device structure. If NULL the default
3529	* PCI device for this device instance is used.
3530	* @param cPages Number of pages to lock.
3531	* @param paGCPhysPages The guest physical address of the pages that
3532	* should be mapped (@a cPages entries).
3533	* @param fFlags Flags reserved for future use, MBZ.
3534	* @param papvPages Where to store the ring-3 mapping addresses
3535	* corresponding to @a paGCPhysPages.
3536	* @param paLocks Where to store the locking information that
3537	* pfnPhysBulkReleasePageMappingLock needs (@a cPages
3538	* in length).
3539	*/
3540	DECLR3CALLBACKMEMBER(int, pfnPCIPhysBulkGCPhys2CCPtr,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t cPages,
3541	PCRTGCPHYS paGCPhysPages, uint32_t fFlags, void **papvPages,
3542	PPGMPAGEMAPLOCK paLocks));
3543
3544	/**
3545	* Requests the mapping of multiple guest pages into ring-3 in preparation for a bus
3546	* master physical memory read operation.
3547	*
3548	* When you're done with the pages, call pfnPhysBulkReleasePageMappingLocks()
3549	* ASAP to release them.
3550	*
3551	* Refer pfnPhysBulkGCPhys2CCPtrReadOnly() for further details.
3552	*
3553	* @returns VBox status code.
3554	* @param pDevIns The device instance.
3555	* @param pPciDev The PCI device structure. If NULL the default
3556	* PCI device for this device instance is used.
3557	* @param cPages Number of pages to lock.
3558	* @param paGCPhysPages The guest physical address of the pages that
3559	* should be mapped (@a cPages entries).
3560	* @param fFlags Flags reserved for future use, MBZ.
3561	* @param papvPages Where to store the ring-3 mapping addresses
3562	* corresponding to @a paGCPhysPages.
3563	* @param paLocks Where to store the lock information that
3564	* pfnPhysReleasePageMappingLock needs (@a cPages
3565	* in length).
3566	*/
3567	DECLR3CALLBACKMEMBER(int, pfnPCIPhysBulkGCPhys2CCPtrReadOnly,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t cPages,
3568	PCRTGCPHYS paGCPhysPages, uint32_t fFlags,
3569	void const **papvPages, PPGMPAGEMAPLOCK paLocks));
3570
3571	/**
3572	* Sets the IRQ for the given PCI device.
3573	*
3574	* @param pDevIns The device instance.
3575	* @param pPciDev The PCI device structure. If NULL the default
3576	* PCI device for this device instance is used.
3577	* @param iIrq IRQ number to set.
3578	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
3579	* @thread Any thread, but will involve the emulation thread.
3580	*/
3581	DECLR3CALLBACKMEMBER(void, pfnPCISetIrq,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, int iIrq, int iLevel));
3582
3583	/**
3584	* Sets the IRQ for the given PCI device, but doesn't wait for EMT to process
3585	* the request when not called from EMT.
3586	*
3587	* @param pDevIns The device instance.
3588	* @param pPciDev The PCI device structure. If NULL the default
3589	* PCI device for this device instance is used.
3590	* @param iIrq IRQ number to set.
3591	* @param iLevel IRQ level.
3592	* @thread Any thread, but will involve the emulation thread.
3593	*/
3594	DECLR3CALLBACKMEMBER(void, pfnPCISetIrqNoWait,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, int iIrq, int iLevel));
3595
3596	/**
3597	* Set ISA IRQ for a device.
3598	*
3599	* @param pDevIns The device instance.
3600	* @param iIrq IRQ number to set.
3601	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
3602	* @thread Any thread, but will involve the emulation thread.
3603	*/
3604	DECLR3CALLBACKMEMBER(void, pfnISASetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
3605
3606	/**
3607	* Set the ISA IRQ for a device, but don't wait for EMT to process
3608	* the request when not called from EMT.
3609	*
3610	* @param pDevIns The device instance.
3611	* @param iIrq IRQ number to set.
3612	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
3613	* @thread Any thread, but will involve the emulation thread.
3614	*/
3615	DECLR3CALLBACKMEMBER(void, pfnISASetIrqNoWait,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
3616
3617	/**
3618	* Attaches a driver (chain) to the device.
3619	*
3620	* The first call for a LUN this will serve as a registration of the LUN. The pBaseInterface and
3621	* the pszDesc string will be registered with that LUN and kept around for PDMR3QueryDeviceLun().
3622	*
3623	* @returns VBox status code.
3624	* @param pDevIns The device instance.
3625	* @param iLun The logical unit to attach.
3626	* @param pBaseInterface Pointer to the base interface for that LUN. (device side / down)
3627	* @param ppBaseInterface Where to store the pointer to the base interface. (driver side / up)
3628	* @param pszDesc Pointer to a string describing the LUN. This string must remain valid
3629	* for the live of the device instance.
3630	*/
3631	DECLR3CALLBACKMEMBER(int, pfnDriverAttach,(PPDMDEVINS pDevIns, uint32_t iLun, PPDMIBASE pBaseInterface,
3632	PPDMIBASE ppBaseInterface, const char pszDesc));
3633
3634	/**
3635	* Detaches an attached driver (chain) from the device again.
3636	*
3637	* @returns VBox status code.
3638	* @param pDevIns The device instance.
3639	* @param pDrvIns The driver instance to detach.
3640	* @param fFlags Flags, combination of the PDMDEVATT_FLAGS_* \#defines.
3641	*/
3642	DECLR3CALLBACKMEMBER(int, pfnDriverDetach,(PPDMDEVINS pDevIns, PPDMDRVINS pDrvIns, uint32_t fFlags));
3643
3644	/**
3645	* Reconfigures the driver chain for a LUN, detaching any driver currently
3646	* present there.
3647	*
3648	* Caller will have attach it, of course.
3649	*
3650	* @returns VBox status code.
3651	* @param pDevIns The device instance.
3652	* @param iLun The logical unit to reconfigure.
3653	* @param cDepth The depth of the driver chain. Determins the
3654	* size of @a papszDrivers and @a papConfigs.
3655	* @param papszDrivers The names of the drivers to configure in the
3656	* chain, first entry is the one immediately
3657	* below the device/LUN
3658	* @param papConfigs The configurations for each of the drivers
3659	* in @a papszDrivers array. NULL entries
3660	* corresponds to empty 'Config' nodes. This
3661	* function will take ownership of non-NULL
3662	* CFGM sub-trees and set the array member to
3663	* NULL, so the caller can do cleanups on
3664	* failure. This parameter is optional.
3665	* @param fFlags Reserved, MBZ.
3666	*/
3667	DECLR3CALLBACKMEMBER(int, pfnDriverReconfigure,(PPDMDEVINS pDevIns, uint32_t iLun, uint32_t cDepth,
3668	const char * const papszDrivers, PCFGMNODE papConfigs, uint32_t fFlags));
3669
3670	/** @name Exported PDM Queue Functions
3671	* @{ */
3672	/**
3673	* Create a queue.
3674	*
3675	* @returns VBox status code.
3676	* @param pDevIns The device instance.
3677	* @param cbItem The size of a queue item.
3678	* @param cItems The number of items in the queue.
3679	* @param cMilliesInterval The number of milliseconds between polling the queue.
3680	* If 0 then the emulation thread will be notified whenever an item arrives.
3681	* @param pfnCallback The consumer function.
3682	* @param fRZEnabled Set if the queue should work in RC and R0.
3683	* @param pszName The queue base name. The instance number will be
3684	* appended automatically.
3685	* @param ppQueue Where to store the queue pointer on success.
3686	* @thread The emulation thread.
3687	* @remarks The device critical section will NOT be entered before calling the
3688	* callback. No locks will be held, but for now it's safe to assume
3689	* that only one EMT will do queue callbacks at any one time.
3690	*/
3691	DECLR3CALLBACKMEMBER(int, pfnQueueCreatePtr,(PPDMDEVINS pDevIns, size_t cbItem, uint32_t cItems, uint32_t cMilliesInterval,
3692	PFNPDMQUEUEDEV pfnCallback, bool fRZEnabled, const char *pszName,
3693	PPDMQUEUE *ppQueue));
3694
3695	/**
3696	* Create a queue.
3697	*
3698	* @returns VBox status code.
3699	* @param pDevIns The device instance.
3700	* @param cbItem The size of a queue item.
3701	* @param cItems The number of items in the queue.
3702	* @param cMilliesInterval The number of milliseconds between polling the queue.
3703	* If 0 then the emulation thread will be notified whenever an item arrives.
3704	* @param pfnCallback The consumer function.
3705	* @param fRZEnabled Set if the queue should work in RC and R0.
3706	* @param pszName The queue base name. The instance number will be
3707	* appended automatically.
3708	* @param phQueue Where to store the queue handle on success.
3709	* @thread EMT(0)
3710	* @remarks The device critical section will NOT be entered before calling the
3711	* callback. No locks will be held, but for now it's safe to assume
3712	* that only one EMT will do queue callbacks at any one time.
3713	*/
3714	DECLR3CALLBACKMEMBER(int, pfnQueueCreate,(PPDMDEVINS pDevIns, size_t cbItem, uint32_t cItems, uint32_t cMilliesInterval,
3715	PFNPDMQUEUEDEV pfnCallback, bool fRZEnabled, const char *pszName,
3716	PDMQUEUEHANDLE *phQueue));
3717
3718	DECLR3CALLBACKMEMBER(PPDMQUEUE, pfnQueueToPtr,(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue));
3719	DECLR3CALLBACKMEMBER(PPDMQUEUEITEMCORE, pfnQueueAlloc,(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue));
3720	DECLR3CALLBACKMEMBER(void, pfnQueueInsert,(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue, PPDMQUEUEITEMCORE pItem));
3721	DECLR3CALLBACKMEMBER(void, pfnQueueInsertEx,(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue, PPDMQUEUEITEMCORE pItem, uint64_t cNanoMaxDelay));
3722	DECLR3CALLBACKMEMBER(bool, pfnQueueFlushIfNecessary,(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue));
3723	/** @} */
3724
3725	/** @name PDM Task
3726	* @{ */
3727	/**
3728	* Create an asynchronous ring-3 task.
3729	*
3730	* @returns VBox status code.
3731	* @param pDevIns The device instance.
3732	* @param fFlags PDMTASK_F_XXX
3733	* @param pszName The function name or similar. Used for statistics,
3734	* so no slashes.
3735	* @param pfnCallback The task function.
3736	* @param pvUser User argument for the task function.
3737	* @param phTask Where to return the task handle.
3738	* @thread EMT(0)
3739	*/
3740	DECLR3CALLBACKMEMBER(int, pfnTaskCreate,(PPDMDEVINS pDevIns, uint32_t fFlags, const char *pszName,
3741	PFNPDMTASKDEV pfnCallback, void pvUser, PDMTASKHANDLE phTask));
3742	/**
3743	* Triggers the running the given task.
3744	*
3745	* @returns VBox status code.
3746	* @retval VINF_ALREADY_POSTED is the task is already pending.
3747	* @param pDevIns The device instance.
3748	* @param hTask The task to trigger.
3749	* @thread Any thread.
3750	*/
3751	DECLR3CALLBACKMEMBER(int, pfnTaskTrigger,(PPDMDEVINS pDevIns, PDMTASKHANDLE hTask));
3752	/** @} */
3753
3754	/** @name SUP Event Semaphore Wrappers (single release / auto reset)
3755	* These semaphores can be signalled from ring-0.
3756	* @{ */
3757	/** @sa SUPSemEventCreate */
3758	DECLR3CALLBACKMEMBER(int, pfnSUPSemEventCreate,(PPDMDEVINS pDevIns, PSUPSEMEVENT phEvent));
3759	/** @sa SUPSemEventClose */
3760	DECLR3CALLBACKMEMBER(int, pfnSUPSemEventClose,(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent));
3761	/** @sa SUPSemEventSignal */
3762	DECLR3CALLBACKMEMBER(int, pfnSUPSemEventSignal,(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent));
3763	/** @sa SUPSemEventWaitNoResume */
3764	DECLR3CALLBACKMEMBER(int, pfnSUPSemEventWaitNoResume,(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent, uint32_t cMillies));
3765	/** @sa SUPSemEventWaitNsAbsIntr */
3766	DECLR3CALLBACKMEMBER(int, pfnSUPSemEventWaitNsAbsIntr,(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent, uint64_t uNsTimeout));
3767	/** @sa SUPSemEventWaitNsRelIntr */
3768	DECLR3CALLBACKMEMBER(int, pfnSUPSemEventWaitNsRelIntr,(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent, uint64_t cNsTimeout));
3769	/** @sa SUPSemEventGetResolution */
3770	DECLR3CALLBACKMEMBER(uint32_t, pfnSUPSemEventGetResolution,(PPDMDEVINS pDevIns));
3771	/** @} */
3772
3773	/** @name SUP Multi Event Semaphore Wrappers (multiple release / manual reset)
3774	* These semaphores can be signalled from ring-0.
3775	* @{ */
3776	/** @sa SUPSemEventMultiCreate */
3777	DECLR3CALLBACKMEMBER(int, pfnSUPSemEventMultiCreate,(PPDMDEVINS pDevIns, PSUPSEMEVENTMULTI phEventMulti));
3778	/** @sa SUPSemEventMultiClose */
3779	DECLR3CALLBACKMEMBER(int, pfnSUPSemEventMultiClose,(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti));
3780	/** @sa SUPSemEventMultiSignal */
3781	DECLR3CALLBACKMEMBER(int, pfnSUPSemEventMultiSignal,(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti));
3782	/** @sa SUPSemEventMultiReset */
3783	DECLR3CALLBACKMEMBER(int, pfnSUPSemEventMultiReset,(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti));
3784	/** @sa SUPSemEventMultiWaitNoResume */
3785	DECLR3CALLBACKMEMBER(int, pfnSUPSemEventMultiWaitNoResume,(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti, uint32_t cMillies));
3786	/** @sa SUPSemEventMultiWaitNsAbsIntr */
3787	DECLR3CALLBACKMEMBER(int, pfnSUPSemEventMultiWaitNsAbsIntr,(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti, uint64_t uNsTimeout));
3788	/** @sa SUPSemEventMultiWaitNsRelIntr */
3789	DECLR3CALLBACKMEMBER(int, pfnSUPSemEventMultiWaitNsRelIntr,(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti, uint64_t cNsTimeout));
3790	/** @sa SUPSemEventMultiGetResolution */
3791	DECLR3CALLBACKMEMBER(uint32_t, pfnSUPSemEventMultiGetResolution,(PPDMDEVINS pDevIns));
3792	/** @} */
3793
3794	/**
3795	* Initializes a PDM critical section.
3796	*
3797	* The PDM critical sections are derived from the IPRT critical sections, but
3798	* works in RC and R0 as well.
3799	*
3800	* @returns VBox status code.
3801	* @param pDevIns The device instance.
3802	* @param pCritSect Pointer to the critical section.
3803	* @param SRC_POS Use RT_SRC_POS.
3804	* @param pszNameFmt Format string for naming the critical section.
3805	* For statistics and lock validation.
3806	* @param va Arguments for the format string.
3807	*/
3808	DECLR3CALLBACKMEMBER(int, pfnCritSectInit,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, RT_SRC_POS_DECL,
3809	const char *pszNameFmt, va_list va) RT_IPRT_FORMAT_ATTR(6, 0));
3810
3811	/**
3812	* Gets the NOP critical section.
3813	*
3814	* @returns The ring-3 address of the NOP critical section.
3815	* @param pDevIns The device instance.
3816	*/
3817	DECLR3CALLBACKMEMBER(PPDMCRITSECT, pfnCritSectGetNop,(PPDMDEVINS pDevIns));
3818
3819	/**
3820	* Gets the NOP critical section.
3821	*
3822	* @returns The ring-0 address of the NOP critical section.
3823	* @param pDevIns The device instance.
3824	* @deprecated
3825	*/
3826	DECLR3CALLBACKMEMBER(R0PTRTYPE(PPDMCRITSECT), pfnCritSectGetNopR0,(PPDMDEVINS pDevIns));
3827
3828	/**
3829	* Gets the NOP critical section.
3830	*
3831	* @returns The raw-mode context address of the NOP critical section.
3832	* @param pDevIns The device instance.
3833	* @deprecated
3834	*/
3835	DECLR3CALLBACKMEMBER(RCPTRTYPE(PPDMCRITSECT), pfnCritSectGetNopRC,(PPDMDEVINS pDevIns));
3836
3837	/**
3838	* Changes the device level critical section from the automatically created
3839	* default to one desired by the device constructor.
3840	*
3841	* For ring-0 and raw-mode capable devices, the call must be repeated in each of
3842	* the additional contexts.
3843	*
3844	* @returns VBox status code.
3845	* @param pDevIns The device instance.
3846	* @param pCritSect The critical section to use. NULL is not
3847	* valid, instead use the NOP critical
3848	* section.
3849	*/
3850	DECLR3CALLBACKMEMBER(int, pfnSetDeviceCritSect,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect));
3851
3852	/** @name Exported PDM Critical Section Functions
3853	* @{ */
3854	DECLR3CALLBACKMEMBER(bool, pfnCritSectYield,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect));
3855	DECLR3CALLBACKMEMBER(int, pfnCritSectEnter,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, int rcBusy));
3856	DECLR3CALLBACKMEMBER(int, pfnCritSectEnterDebug,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, int rcBusy, RTHCUINTPTR uId, RT_SRC_POS_DECL));
3857	DECLR3CALLBACKMEMBER(int, pfnCritSectTryEnter,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect));
3858	DECLR3CALLBACKMEMBER(int, pfnCritSectTryEnterDebug,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, RTHCUINTPTR uId, RT_SRC_POS_DECL));
3859	DECLR3CALLBACKMEMBER(int, pfnCritSectLeave,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect));
3860	DECLR3CALLBACKMEMBER(bool, pfnCritSectIsOwner,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
3861	DECLR3CALLBACKMEMBER(bool, pfnCritSectIsInitialized,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
3862	DECLR3CALLBACKMEMBER(bool, pfnCritSectHasWaiters,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
3863	DECLR3CALLBACKMEMBER(uint32_t, pfnCritSectGetRecursion,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
3864	DECLR3CALLBACKMEMBER(int, pfnCritSectScheduleExitEvent,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, SUPSEMEVENT hEventToSignal));
3865	DECLR3CALLBACKMEMBER(int, pfnCritSectDelete,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect));
3866	/** @} */
3867
3868	/**
3869	* Creates a PDM thread.
3870	*
3871	* This differs from the RTThreadCreate() API in that PDM takes care of suspending,
3872	* resuming, and destroying the thread as the VM state changes.
3873	*
3874	* @returns VBox status code.
3875	* @param pDevIns The device instance.
3876	* @param ppThread Where to store the thread 'handle'.
3877	* @param pvUser The user argument to the thread function.
3878	* @param pfnThread The thread function.
3879	* @param pfnWakeup The wakup callback. This is called on the EMT
3880	* thread when a state change is pending.
3881	* @param cbStack See RTThreadCreate.
3882	* @param enmType See RTThreadCreate.
3883	* @param pszName See RTThreadCreate.
3884	* @remarks The device critical section will NOT be entered prior to invoking
3885	* the function pointers.
3886	*/
3887	DECLR3CALLBACKMEMBER(int, pfnThreadCreate,(PPDMDEVINS pDevIns, PPPDMTHREAD ppThread, void *pvUser, PFNPDMTHREADDEV pfnThread,
3888	PFNPDMTHREADWAKEUPDEV pfnWakeup, size_t cbStack, RTTHREADTYPE enmType, const char *pszName));
3889
3890	/** @name Exported PDM Thread Functions
3891	* @{ */
3892	DECLR3CALLBACKMEMBER(int, pfnThreadDestroy,(PPDMTHREAD pThread, int *pRcThread));
3893	DECLR3CALLBACKMEMBER(int, pfnThreadIAmSuspending,(PPDMTHREAD pThread));
3894	DECLR3CALLBACKMEMBER(int, pfnThreadIAmRunning,(PPDMTHREAD pThread));
3895	DECLR3CALLBACKMEMBER(int, pfnThreadSleep,(PPDMTHREAD pThread, RTMSINTERVAL cMillies));
3896	DECLR3CALLBACKMEMBER(int, pfnThreadSuspend,(PPDMTHREAD pThread));
3897	DECLR3CALLBACKMEMBER(int, pfnThreadResume,(PPDMTHREAD pThread));
3898	/** @} */
3899
3900	/**
3901	* Set up asynchronous handling of a suspend, reset or power off notification.
3902	*
3903	* This shall only be called when getting the notification. It must be called
3904	* for each one.
3905	*
3906	* @returns VBox status code.
3907	* @param pDevIns The device instance.
3908	* @param pfnAsyncNotify The callback.
3909	* @thread EMT(0)
3910	* @remarks The caller will enter the device critical section prior to invoking
3911	* the callback.
3912	*/
3913	DECLR3CALLBACKMEMBER(int, pfnSetAsyncNotification, (PPDMDEVINS pDevIns, PFNPDMDEVASYNCNOTIFY pfnAsyncNotify));
3914
3915	/**
3916	* Notify EMT(0) that the device has completed the asynchronous notification
3917	* handling.
3918	*
3919	* This can be called at any time, spurious calls will simply be ignored.
3920	*
3921	* @param pDevIns The device instance.
3922	* @thread Any
3923	*/
3924	DECLR3CALLBACKMEMBER(void, pfnAsyncNotificationCompleted, (PPDMDEVINS pDevIns));
3925
3926	/**
3927	* Register the RTC device.
3928	*
3929	* @returns VBox status code.
3930	* @param pDevIns The device instance.
3931	* @param pRtcReg Pointer to a RTC registration structure.
3932	* @param ppRtcHlp Where to store the pointer to the helper
3933	* functions.
3934	*/
3935	DECLR3CALLBACKMEMBER(int, pfnRTCRegister,(PPDMDEVINS pDevIns, PCPDMRTCREG pRtcReg, PCPDMRTCHLP *ppRtcHlp));
3936
3937	/**
3938	* Register a PCI Bus.
3939	*
3940	* @returns VBox status code, but the positive values 0..31 are used to indicate
3941	* bus number rather than informational status codes.
3942	* @param pDevIns The device instance.
3943	* @param pPciBusReg Pointer to PCI bus registration structure.
3944	* @param ppPciHlp Where to store the pointer to the PCI Bus
3945	* helpers.
3946	* @param piBus Where to return the PDM bus number. Optional.
3947	*/
3948	DECLR3CALLBACKMEMBER(int, pfnPCIBusRegister,(PPDMDEVINS pDevIns, PPDMPCIBUSREGR3 pPciBusReg,
3949	PCPDMPCIHLPR3 ppPciHlp, uint32_t piBus));
3950
3951	/**
3952	* Register the IOMMU device.
3953	*
3954	* @returns VBox status code.
3955	* @param pDevIns The device instance.
3956	* @param pIommuReg Pointer to a IOMMU registration structure.
3957	* @param ppIommuHlp Where to store the pointer to the ring-3 IOMMU
3958	* helpers.
3959	* @param pidxIommu Where to return the IOMMU index. Optional.
3960	*/
3961	DECLR3CALLBACKMEMBER(int, pfnIommuRegister,(PPDMDEVINS pDevIns, PPDMIOMMUREGR3 pIommuReg, PCPDMIOMMUHLPR3 *ppIommuHlp,
3962	uint32_t *pidxIommu));
3963
3964	/**
3965	* Register the PIC device.
3966	*
3967	* @returns VBox status code.
3968	* @param pDevIns The device instance.
3969	* @param pPicReg Pointer to a PIC registration structure.
3970	* @param ppPicHlp Where to store the pointer to the ring-3 PIC
3971	* helpers.
3972	* @sa PDMDevHlpPICSetUpContext
3973	*/
3974	DECLR3CALLBACKMEMBER(int, pfnPICRegister,(PPDMDEVINS pDevIns, PPDMPICREG pPicReg, PCPDMPICHLP *ppPicHlp));
3975
3976	/**
3977	* Register the APIC device.
3978	*
3979	* @returns VBox status code.
3980	* @param pDevIns The device instance.
3981	*/
3982	DECLR3CALLBACKMEMBER(int, pfnApicRegister,(PPDMDEVINS pDevIns));
3983
3984	/**
3985	* Register the I/O APIC device.
3986	*
3987	* @returns VBox status code.
3988	* @param pDevIns The device instance.
3989	* @param pIoApicReg Pointer to a I/O APIC registration structure.
3990	* @param ppIoApicHlp Where to store the pointer to the IOAPIC
3991	* helpers.
3992	*/
3993	DECLR3CALLBACKMEMBER(int, pfnIoApicRegister,(PPDMDEVINS pDevIns, PPDMIOAPICREG pIoApicReg, PCPDMIOAPICHLP *ppIoApicHlp));
3994
3995	/**
3996	* Register the HPET device.
3997	*
3998	* @returns VBox status code.
3999	* @param pDevIns The device instance.
4000	* @param pHpetReg Pointer to a HPET registration structure.
4001	* @param ppHpetHlpR3 Where to store the pointer to the HPET
4002	* helpers.
4003	*/
4004	DECLR3CALLBACKMEMBER(int, pfnHpetRegister,(PPDMDEVINS pDevIns, PPDMHPETREG pHpetReg, PCPDMHPETHLPR3 *ppHpetHlpR3));
4005
4006	/**
4007	* Register a raw PCI device.
4008	*
4009	* @returns VBox status code.
4010	* @param pDevIns The device instance.
4011	* @param pPciRawReg Pointer to a raw PCI registration structure.
4012	* @param ppPciRawHlpR3 Where to store the pointer to the raw PCI
4013	* device helpers.
4014	*/
4015	DECLR3CALLBACKMEMBER(int, pfnPciRawRegister,(PPDMDEVINS pDevIns, PPDMPCIRAWREG pPciRawReg, PCPDMPCIRAWHLPR3 *ppPciRawHlpR3));
4016
4017	/**
4018	* Register the DMA device.
4019	*
4020	* @returns VBox status code.
4021	* @param pDevIns The device instance.
4022	* @param pDmacReg Pointer to a DMAC registration structure.
4023	* @param ppDmacHlp Where to store the pointer to the DMA helpers.
4024	*/
4025	DECLR3CALLBACKMEMBER(int, pfnDMACRegister,(PPDMDEVINS pDevIns, PPDMDMACREG pDmacReg, PCPDMDMACHLP *ppDmacHlp));
4026
4027	/**
4028	* Register transfer function for DMA channel.
4029	*
4030	* @returns VBox status code.
4031	* @param pDevIns The device instance.
4032	* @param uChannel Channel number.
4033	* @param pfnTransferHandler Device specific transfer callback function.
4034	* @param pvUser User pointer to pass to the callback.
4035	* @thread EMT
4036	*/
4037	DECLR3CALLBACKMEMBER(int, pfnDMARegister,(PPDMDEVINS pDevIns, unsigned uChannel, PFNDMATRANSFERHANDLER pfnTransferHandler, void *pvUser));
4038
4039	/**
4040	* Read memory.
4041	*
4042	* @returns VBox status code.
4043	* @param pDevIns The device instance.
4044	* @param uChannel Channel number.
4045	* @param pvBuffer Pointer to target buffer.
4046	* @param off DMA position.
4047	* @param cbBlock Block size.
4048	* @param pcbRead Where to store the number of bytes which was
4049	* read. optional.
4050	* @thread EMT
4051	*/
4052	DECLR3CALLBACKMEMBER(int, pfnDMAReadMemory,(PPDMDEVINS pDevIns, unsigned uChannel, void pvBuffer, uint32_t off, uint32_t cbBlock, uint32_t pcbRead));
4053
4054	/**
4055	* Write memory.
4056	*
4057	* @returns VBox status code.
4058	* @param pDevIns The device instance.
4059	* @param uChannel Channel number.
4060	* @param pvBuffer Memory to write.
4061	* @param off DMA position.
4062	* @param cbBlock Block size.
4063	* @param pcbWritten Where to store the number of bytes which was
4064	* written. optional.
4065	* @thread EMT
4066	*/
4067	DECLR3CALLBACKMEMBER(int, pfnDMAWriteMemory,(PPDMDEVINS pDevIns, unsigned uChannel, const void pvBuffer, uint32_t off, uint32_t cbBlock, uint32_t pcbWritten));
4068
4069	/**
4070	* Set the DREQ line.
4071	*
4072	* @returns VBox status code.
4073	* @param pDevIns Device instance.
4074	* @param uChannel Channel number.
4075	* @param uLevel Level of the line.
4076	* @thread EMT
4077	*/
4078	DECLR3CALLBACKMEMBER(int, pfnDMASetDREQ,(PPDMDEVINS pDevIns, unsigned uChannel, unsigned uLevel));
4079
4080	/**
4081	* Get channel mode.
4082	*
4083	* @returns Channel mode. See specs.
4084	* @param pDevIns The device instance.
4085	* @param uChannel Channel number.
4086	* @thread EMT
4087	*/
4088	DECLR3CALLBACKMEMBER(uint8_t, pfnDMAGetChannelMode,(PPDMDEVINS pDevIns, unsigned uChannel));
4089
4090	/**
4091	* Schedule DMA execution.
4092	*
4093	* @param pDevIns The device instance.
4094	* @thread Any thread.
4095	*/
4096	DECLR3CALLBACKMEMBER(void, pfnDMASchedule,(PPDMDEVINS pDevIns));
4097
4098	/**
4099	* Write CMOS value and update the checksum(s).
4100	*
4101	* @returns VBox status code.
4102	* @param pDevIns The device instance.
4103	* @param iReg The CMOS register index.
4104	* @param u8Value The CMOS register value.
4105	* @thread EMT
4106	*/
4107	DECLR3CALLBACKMEMBER(int, pfnCMOSWrite,(PPDMDEVINS pDevIns, unsigned iReg, uint8_t u8Value));
4108
4109	/**
4110	* Read CMOS value.
4111	*
4112	* @returns VBox status code.
4113	* @param pDevIns The device instance.
4114	* @param iReg The CMOS register index.
4115	* @param pu8Value Where to store the CMOS register value.
4116	* @thread EMT
4117	*/
4118	DECLR3CALLBACKMEMBER(int, pfnCMOSRead,(PPDMDEVINS pDevIns, unsigned iReg, uint8_t *pu8Value));
4119
4120	/**
4121	* Assert that the current thread is the emulation thread.
4122	*
4123	* @returns True if correct.
4124	* @returns False if wrong.
4125	* @param pDevIns The device instance.
4126	* @param pszFile Filename of the assertion location.
4127	* @param iLine The linenumber of the assertion location.
4128	* @param pszFunction Function of the assertion location.
4129	*/
4130	DECLR3CALLBACKMEMBER(bool, pfnAssertEMT,(PPDMDEVINS pDevIns, const char pszFile, unsigned iLine, const char pszFunction));
4131
4132	/**
4133	* Assert that the current thread is NOT the emulation thread.
4134	*
4135	* @returns True if correct.
4136	* @returns False if wrong.
4137	* @param pDevIns The device instance.
4138	* @param pszFile Filename of the assertion location.
4139	* @param iLine The linenumber of the assertion location.
4140	* @param pszFunction Function of the assertion location.
4141	*/
4142	DECLR3CALLBACKMEMBER(bool, pfnAssertOther,(PPDMDEVINS pDevIns, const char pszFile, unsigned iLine, const char pszFunction));
4143
4144	/**
4145	* Resolves the symbol for a raw-mode context interface.
4146	*
4147	* @returns VBox status code.
4148	* @param pDevIns The device instance.
4149	* @param pvInterface The interface structure.
4150	* @param cbInterface The size of the interface structure.
4151	* @param pszSymPrefix What to prefix the symbols in the list with
4152	* before resolving them. This must start with
4153	* 'dev' and contain the driver name.
4154	* @param pszSymList List of symbols corresponding to the interface.
4155	* There is generally a there is generally a define
4156	* holding this list associated with the interface
4157	* definition (INTERFACE_SYM_LIST). For more
4158	* details see PDMR3LdrGetInterfaceSymbols.
4159	* @thread EMT
4160	*/
4161	DECLR3CALLBACKMEMBER(int, pfnLdrGetRCInterfaceSymbols,(PPDMDEVINS pDevIns, void *pvInterface, size_t cbInterface,
4162	const char pszSymPrefix, const char pszSymList));
4163
4164	/**
4165	* Resolves the symbol for a ring-0 context interface.
4166	*
4167	* @returns VBox status code.
4168	* @param pDevIns The device instance.
4169	* @param pvInterface The interface structure.
4170	* @param cbInterface The size of the interface structure.
4171	* @param pszSymPrefix What to prefix the symbols in the list with
4172	* before resolving them. This must start with
4173	* 'dev' and contain the driver name.
4174	* @param pszSymList List of symbols corresponding to the interface.
4175	* There is generally a there is generally a define
4176	* holding this list associated with the interface
4177	* definition (INTERFACE_SYM_LIST). For more
4178	* details see PDMR3LdrGetInterfaceSymbols.
4179	* @thread EMT
4180	*/
4181	DECLR3CALLBACKMEMBER(int, pfnLdrGetR0InterfaceSymbols,(PPDMDEVINS pDevIns, void *pvInterface, size_t cbInterface,
4182	const char pszSymPrefix, const char pszSymList));
4183
4184	/**
4185	* Calls the PDMDEVREGR0::pfnRequest callback (in ring-0 context).
4186	*
4187	* @returns VBox status code.
4188	* @retval VERR_INVALID_FUNCTION if the callback member is NULL.
4189	* @retval VERR_ACCESS_DENIED if the device isn't ring-0 capable.
4190	*
4191	* @param pDevIns The device instance.
4192	* @param uOperation The operation to perform.
4193	* @param u64Arg 64-bit integer argument.
4194	* @thread EMT
4195	*/
4196	DECLR3CALLBACKMEMBER(int, pfnCallR0,(PPDMDEVINS pDevIns, uint32_t uOperation, uint64_t u64Arg));
4197
4198	/**
4199	* Gets the reason for the most recent VM suspend.
4200	*
4201	* @returns The suspend reason. VMSUSPENDREASON_INVALID is returned if no
4202	* suspend has been made or if the pDevIns is invalid.
4203	* @param pDevIns The device instance.
4204	*/
4205	DECLR3CALLBACKMEMBER(VMSUSPENDREASON, pfnVMGetSuspendReason,(PPDMDEVINS pDevIns));
4206
4207	/**
4208	* Gets the reason for the most recent VM resume.
4209	*
4210	* @returns The resume reason. VMRESUMEREASON_INVALID is returned if no
4211	* resume has been made or if the pDevIns is invalid.
4212	* @param pDevIns The device instance.
4213	*/
4214	DECLR3CALLBACKMEMBER(VMRESUMEREASON, pfnVMGetResumeReason,(PPDMDEVINS pDevIns));
4215
4216	/**
4217	* Requests the mapping of multiple guest page into ring-3.
4218	*
4219	* When you're done with the pages, call pfnPhysBulkReleasePageMappingLocks()
4220	* ASAP to release them.
4221	*
4222	* This API will assume your intention is to write to the pages, and will
4223	* therefore replace shared and zero pages. If you do not intend to modify the
4224	* pages, use the pfnPhysBulkGCPhys2CCPtrReadOnly() API.
4225	*
4226	* @returns VBox status code.
4227	* @retval VINF_SUCCESS on success.
4228	* @retval VERR_PGM_PHYS_PAGE_RESERVED if any of the pages has no physical
4229	* backing or if any of the pages the page has any active access
4230	* handlers. The caller must fall back on using PGMR3PhysWriteExternal.
4231	* @retval VERR_PGM_INVALID_GC_PHYSICAL_ADDRESS if @a paGCPhysPages contains
4232	* an invalid physical address.
4233	*
4234	* @param pDevIns The device instance.
4235	* @param cPages Number of pages to lock.
4236	* @param paGCPhysPages The guest physical address of the pages that
4237	* should be mapped (@a cPages entries).
4238	* @param fFlags Flags reserved for future use, MBZ.
4239	* @param papvPages Where to store the ring-3 mapping addresses
4240	* corresponding to @a paGCPhysPages.
4241	* @param paLocks Where to store the locking information that
4242	* pfnPhysBulkReleasePageMappingLock needs (@a cPages
4243	* in length).
4244	*
4245	* @remark Avoid calling this API from within critical sections (other than the
4246	* PGM one) because of the deadlock risk when we have to delegating the
4247	* task to an EMT.
4248	* @thread Any.
4249	* @since 6.0.6
4250	*/
4251	DECLR3CALLBACKMEMBER(int, pfnPhysBulkGCPhys2CCPtr,(PPDMDEVINS pDevIns, uint32_t cPages, PCRTGCPHYS paGCPhysPages,
4252	uint32_t fFlags, void **papvPages, PPGMPAGEMAPLOCK paLocks));
4253
4254	/**
4255	* Requests the mapping of multiple guest page into ring-3, for reading only.
4256	*
4257	* When you're done with the pages, call pfnPhysBulkReleasePageMappingLocks()
4258	* ASAP to release them.
4259	*
4260	* @returns VBox status code.
4261	* @retval VINF_SUCCESS on success.
4262	* @retval VERR_PGM_PHYS_PAGE_RESERVED if any of the pages has no physical
4263	* backing or if any of the pages the page has an active ALL access
4264	* handler. The caller must fall back on using PGMR3PhysWriteExternal.
4265	* @retval VERR_PGM_INVALID_GC_PHYSICAL_ADDRESS if @a paGCPhysPages contains
4266	* an invalid physical address.
4267	*
4268	* @param pDevIns The device instance.
4269	* @param cPages Number of pages to lock.
4270	* @param paGCPhysPages The guest physical address of the pages that
4271	* should be mapped (@a cPages entries).
4272	* @param fFlags Flags reserved for future use, MBZ.
4273	* @param papvPages Where to store the ring-3 mapping addresses
4274	* corresponding to @a paGCPhysPages.
4275	* @param paLocks Where to store the lock information that
4276	* pfnPhysReleasePageMappingLock needs (@a cPages
4277	* in length).
4278	*
4279	* @remark Avoid calling this API from within critical sections.
4280	* @thread Any.
4281	* @since 6.0.6
4282	*/
4283	DECLR3CALLBACKMEMBER(int, pfnPhysBulkGCPhys2CCPtrReadOnly,(PPDMDEVINS pDevIns, uint32_t cPages, PCRTGCPHYS paGCPhysPages,
4284	uint32_t fFlags, void const **papvPages, PPGMPAGEMAPLOCK paLocks));
4285
4286	/**
4287	* Release the mappings of multiple guest pages.
4288	*
4289	* This is the counter part of pfnPhysBulkGCPhys2CCPtr and
4290	* pfnPhysBulkGCPhys2CCPtrReadOnly.
4291	*
4292	* @param pDevIns The device instance.
4293	* @param cPages Number of pages to unlock.
4294	* @param paLocks The lock structures initialized by the mapping
4295	* function (@a cPages in length).
4296	* @thread Any.
4297	* @since 6.0.6
4298	*/
4299	DECLR3CALLBACKMEMBER(void, pfnPhysBulkReleasePageMappingLocks,(PPDMDEVINS pDevIns, uint32_t cPages, PPGMPAGEMAPLOCK paLocks));
4300
4301	/**
4302	* Returns the micro architecture used for the guest.
4303	*
4304	* @returns CPU micro architecture enum.
4305	* @param pDevIns The device instance.
4306	*/
4307	DECLR3CALLBACKMEMBER(CPUMMICROARCH, pfnCpuGetGuestMicroarch,(PPDMDEVINS pDevIns));
4308
4309	/**
4310	* Get the number of physical and linear address bits supported by the guest.
4311	*
4312	* @param pDevIns The device instance.
4313	* @param pcPhysAddrWidth Where to store the number of physical address bits
4314	* supported by the guest.
4315	* @param pcLinearAddrWidth Where to store the number of linear address bits
4316	* supported by the guest.
4317	*/
4318	DECLR3CALLBACKMEMBER(void, pfnCpuGetGuestAddrWidths,(PPDMDEVINS pDevIns, uint8_t *pcPhysAddrWidth,
4319	uint8_t *pcLinearAddrWidth));
4320
4321	/** Space reserved for future members.
4322	* @{ */
4323	/**
4324	* Deregister zero or more samples given their name prefix.
4325	*
4326	* @returns VBox status code.
4327	* @param pDevIns The device instance.
4328	* @param pszPrefix The name prefix of the samples to remove. If this does
4329	* not start with a '/', the default prefix will be
4330	* prepended, otherwise it will be used as-is.
4331	*/
4332	DECLR3CALLBACKMEMBER(int, pfnSTAMDeregisterByPrefix,(PPDMDEVINS pDevIns, const char *pszPrefix));
4333	DECLR3CALLBACKMEMBER(void, pfnReserved2,(void));
4334	DECLR3CALLBACKMEMBER(void, pfnReserved3,(void));
4335	DECLR3CALLBACKMEMBER(void, pfnReserved4,(void));
4336	DECLR3CALLBACKMEMBER(void, pfnReserved5,(void));
4337	DECLR3CALLBACKMEMBER(void, pfnReserved6,(void));
4338	DECLR3CALLBACKMEMBER(void, pfnReserved7,(void));
4339	DECLR3CALLBACKMEMBER(void, pfnReserved8,(void));
4340	DECLR3CALLBACKMEMBER(void, pfnReserved9,(void));
4341	DECLR3CALLBACKMEMBER(void, pfnReserved10,(void));
4342	/** @} */
4343
4344
4345	/** API available to trusted devices only.
4346	*
4347	* These APIs are providing unrestricted access to the guest and the VM,
4348	* or they are interacting intimately with PDM.
4349	*
4350	* @{
4351	*/
4352
4353	/**
4354	* Gets the user mode VM handle. Restricted API.
4355	*
4356	* @returns User mode VM Handle.
4357	* @param pDevIns The device instance.
4358	*/
4359	DECLR3CALLBACKMEMBER(PUVM, pfnGetUVM,(PPDMDEVINS pDevIns));
4360
4361	/**
4362	* Gets the global VM handle. Restricted API.
4363	*
4364	* @returns VM Handle.
4365	* @param pDevIns The device instance.
4366	*/
4367	DECLR3CALLBACKMEMBER(PVMCC, pfnGetVM,(PPDMDEVINS pDevIns));
4368
4369	/**
4370	* Gets the VMCPU handle. Restricted API.
4371	*
4372	* @returns VMCPU Handle.
4373	* @param pDevIns The device instance.
4374	*/
4375	DECLR3CALLBACKMEMBER(PVMCPU, pfnGetVMCPU,(PPDMDEVINS pDevIns));
4376
4377	/**
4378	* The the VM CPU ID of the current thread (restricted API).
4379	*
4380	* @returns The VMCPUID of the calling thread, NIL_VMCPUID if not EMT.
4381	* @param pDevIns The device instance.
4382	*/
4383	DECLR3CALLBACKMEMBER(VMCPUID, pfnGetCurrentCpuId,(PPDMDEVINS pDevIns));
4384
4385	/**
4386	* Registers the VMM device heap or notifies about mapping/unmapping.
4387	*
4388	* This interface serves three purposes:
4389	*
4390	* -# Register the VMM device heap during device construction
4391	* for the HM to use.
4392	* -# Notify PDM/HM that it's mapped into guest address
4393	* space (i.e. usable).
4394	* -# Notify PDM/HM that it is being unmapped from the guest
4395	* address space (i.e. not usable).
4396	*
4397	* @returns VBox status code.
4398	* @param pDevIns The device instance.
4399	* @param GCPhys The physical address if mapped, NIL_RTGCPHYS if
4400	* not mapped.
4401	* @param pvHeap Ring 3 heap pointer.
4402	* @param cbHeap Size of the heap.
4403	* @thread EMT.
4404	*/
4405	DECLR3CALLBACKMEMBER(int, pfnRegisterVMMDevHeap,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTR3PTR pvHeap, unsigned cbHeap));
4406
4407	/**
4408	* Registers the firmware (BIOS, EFI) device with PDM.
4409	*
4410	* The firmware provides a callback table and gets a special PDM helper table.
4411	* There can only be one firmware device for a VM.
4412	*
4413	* @returns VBox status code.
4414	* @param pDevIns The device instance.
4415	* @param pFwReg Firmware registration structure.
4416	* @param ppFwHlp Where to return the firmware helper structure.
4417	* @remarks Only valid during device construction.
4418	* @thread EMT(0)
4419	*/
4420	DECLR3CALLBACKMEMBER(int, pfnFirmwareRegister,(PPDMDEVINS pDevIns, PCPDMFWREG pFwReg, PCPDMFWHLPR3 *ppFwHlp));
4421
4422	/**
4423	* Resets the VM.
4424	*
4425	* @returns The appropriate VBox status code to pass around on reset.
4426	* @param pDevIns The device instance.
4427	* @param fFlags PDMVMRESET_F_XXX flags.
4428	* @thread The emulation thread.
4429	*/
4430	DECLR3CALLBACKMEMBER(int, pfnVMReset,(PPDMDEVINS pDevIns, uint32_t fFlags));
4431
4432	/**
4433	* Suspends the VM.
4434	*
4435	* @returns The appropriate VBox status code to pass around on suspend.
4436	* @param pDevIns The device instance.
4437	* @thread The emulation thread.
4438	*/
4439	DECLR3CALLBACKMEMBER(int, pfnVMSuspend,(PPDMDEVINS pDevIns));
4440
4441	/**
4442	* Suspends, saves and powers off the VM.
4443	*
4444	* @returns The appropriate VBox status code to pass around.
4445	* @param pDevIns The device instance.
4446	* @thread An emulation thread.
4447	*/
4448	DECLR3CALLBACKMEMBER(int, pfnVMSuspendSaveAndPowerOff,(PPDMDEVINS pDevIns));
4449
4450	/**
4451	* Power off the VM.
4452	*
4453	* @returns The appropriate VBox status code to pass around on power off.
4454	* @param pDevIns The device instance.
4455	* @thread The emulation thread.
4456	*/
4457	DECLR3CALLBACKMEMBER(int, pfnVMPowerOff,(PPDMDEVINS pDevIns));
4458
4459	/**
4460	* Checks if the Gate A20 is enabled or not.
4461	*
4462	* @returns true if A20 is enabled.
4463	* @returns false if A20 is disabled.
4464	* @param pDevIns The device instance.
4465	* @thread The emulation thread.
4466	*/
4467	DECLR3CALLBACKMEMBER(bool, pfnA20IsEnabled,(PPDMDEVINS pDevIns));
4468
4469	/**
4470	* Enables or disables the Gate A20.
4471	*
4472	* @param pDevIns The device instance.
4473	* @param fEnable Set this flag to enable the Gate A20; clear it
4474	* to disable.
4475	* @thread The emulation thread.
4476	*/
4477	DECLR3CALLBACKMEMBER(void, pfnA20Set,(PPDMDEVINS pDevIns, bool fEnable));
4478
4479	/**
4480	* Get the specified CPUID leaf for the virtual CPU associated with the calling
4481	* thread.
4482	*
4483	* @param pDevIns The device instance.
4484	* @param iLeaf The CPUID leaf to get.
4485	* @param pEax Where to store the EAX value.
4486	* @param pEbx Where to store the EBX value.
4487	* @param pEcx Where to store the ECX value.
4488	* @param pEdx Where to store the EDX value.
4489	* @thread EMT.
4490	*/
4491	DECLR3CALLBACKMEMBER(void, pfnGetCpuId,(PPDMDEVINS pDevIns, uint32_t iLeaf, uint32_t pEax, uint32_t pEbx, uint32_t pEcx, uint32_t pEdx));
4492
4493	/**
4494	* Get the current virtual clock time in a VM. The clock frequency must be
4495	* queried separately.
4496	*
4497	* @returns Current clock time.
4498	* @param pDevIns The device instance.
4499	*/
4500	DECLR3CALLBACKMEMBER(uint64_t, pfnTMTimeVirtGet,(PPDMDEVINS pDevIns));
4501
4502	/**
4503	* Get the frequency of the virtual clock.
4504	*
4505	* @returns The clock frequency (not variable at run-time).
4506	* @param pDevIns The device instance.
4507	*/
4508	DECLR3CALLBACKMEMBER(uint64_t, pfnTMTimeVirtGetFreq,(PPDMDEVINS pDevIns));
4509
4510	/**
4511	* Get the current virtual clock time in a VM, in nanoseconds.
4512	*
4513	* @returns Current clock time (in ns).
4514	* @param pDevIns The device instance.
4515	*/
4516	DECLR3CALLBACKMEMBER(uint64_t, pfnTMTimeVirtGetNano,(PPDMDEVINS pDevIns));
4517
4518	/**
4519	* Gets the support driver session.
4520	*
4521	* This is intended for working with the semaphore API.
4522	*
4523	* @returns Support driver session handle.
4524	* @param pDevIns The device instance.
4525	*/
4526	DECLR3CALLBACKMEMBER(PSUPDRVSESSION, pfnGetSupDrvSession,(PPDMDEVINS pDevIns));
4527
4528	/**
4529	* Queries a generic object from the VMM user.
4530	*
4531	* @returns Pointer to the object if found, NULL if not.
4532	* @param pDevIns The device instance.
4533	* @param pUuid The UUID of what's being queried. The UUIDs and
4534	* the usage conventions are defined by the user.
4535	*
4536	* @note It is strictly forbidden to call this internally in VBox! This
4537	* interface is exclusively for hacks in externally developed devices.
4538	*/
4539	DECLR3CALLBACKMEMBER(void *, pfnQueryGenericUserObject,(PPDMDEVINS pDevIns, PCRTUUID pUuid));
4540
4541	/**
4542	* Register a physical page access handler type.
4543	*
4544	* @returns VBox status code.
4545	* @param pDevIns The device instance.
4546	* @param enmKind The kind of access handler.
4547	* @param pfnHandlerR3 Pointer to the ring-3 handler callback.
4548	* @param pszHandlerR0 The name of the ring-0 handler, NULL if the ring-3
4549	* handler should be called.
4550	* @param pszPfHandlerR0 The name of the ring-0 \#PF handler, NULL if the
4551	* ring-3 handler should be called.
4552	* @param pszHandlerRC The name of the raw-mode context handler, NULL if
4553	* the ring-3 handler should be called.
4554	* @param pszPfHandlerRC The name of the raw-mode context \#PF handler, NULL
4555	* if the ring-3 handler should be called.
4556	* @param pszDesc The type description.
4557	* @param phType Where to return the type handle (cross context
4558	* safe).
4559	*/
4560	DECLR3CALLBACKMEMBER(int, pfnPGMHandlerPhysicalTypeRegister, (PPDMDEVINS pDevIns, PGMPHYSHANDLERKIND enmKind,
4561	R3PTRTYPE(PFNPGMPHYSHANDLER) pfnHandlerR3,
4562	const char pszHandlerR0, const char pszPfHandlerR0,
4563	const char pszHandlerRC, const char pszPfHandlerRC,
4564	const char *pszDesc, PPGMPHYSHANDLERTYPE phType));
4565
4566	/** @} */
4567
4568	/** Just a safety precaution. (PDM_DEVHLPR3_VERSION) */
4569	uint32_t u32TheEnd;
4570	} PDMDEVHLPR3;
4571	#endif /* !IN_RING3 \|\| DOXYGEN_RUNNING */
4572	/** Pointer to the R3 PDM Device API. */
4573	typedef R3PTRTYPE(struct PDMDEVHLPR3 *) PPDMDEVHLPR3;
4574	/** Pointer to the R3 PDM Device API, const variant. */
4575	typedef R3PTRTYPE(const struct PDMDEVHLPR3 *) PCPDMDEVHLPR3;
4576
4577
4578	/**
4579	* PDM Device API - RC Variant.
4580	*/
4581	typedef struct PDMDEVHLPRC
4582	{
4583	/** Structure version. PDM_DEVHLPRC_VERSION defines the current version. */
4584	uint32_t u32Version;
4585
4586	/**
4587	* Sets up raw-mode context callback handlers for an I/O port range.
4588	*
4589	* The range must have been registered in ring-3 first using
4590	* PDMDevHlpIoPortCreate() or PDMDevHlpIoPortCreateEx().
4591	*
4592	* @returns VBox status.
4593	* @param pDevIns The device instance to register the ports with.
4594	* @param hIoPorts The I/O port range handle.
4595	* @param pfnOut Pointer to function which is gonna handle OUT
4596	* operations. Optional.
4597	* @param pfnIn Pointer to function which is gonna handle IN operations.
4598	* Optional.
4599	* @param pfnOutStr Pointer to function which is gonna handle string OUT
4600	* operations. Optional.
4601	* @param pfnInStr Pointer to function which is gonna handle string IN
4602	* operations. Optional.
4603	* @param pvUser User argument to pass to the callbacks.
4604	*
4605	* @remarks Caller enters the device critical section prior to invoking the
4606	* registered callback methods.
4607	*
4608	* @sa PDMDevHlpIoPortCreate, PDMDevHlpIoPortCreateEx, PDMDevHlpIoPortMap,
4609	* PDMDevHlpIoPortUnmap.
4610	*/
4611	DECLRCCALLBACKMEMBER(int, pfnIoPortSetUpContextEx,(PPDMDEVINS pDevIns, IOMIOPORTHANDLE hIoPorts,
4612	PFNIOMIOPORTNEWOUT pfnOut, PFNIOMIOPORTNEWIN pfnIn,
4613	PFNIOMIOPORTNEWOUTSTRING pfnOutStr, PFNIOMIOPORTNEWINSTRING pfnInStr,
4614	void *pvUser));
4615
4616	/**
4617	* Sets up raw-mode context callback handlers for an MMIO region.
4618	*
4619	* The region must have been registered in ring-3 first using
4620	* PDMDevHlpMmioCreate() or PDMDevHlpMmioCreateEx().
4621	*
4622	* @returns VBox status.
4623	* @param pDevIns The device instance to register the ports with.
4624	* @param hRegion The MMIO region handle.
4625	* @param pfnWrite Pointer to function which is gonna handle Write
4626	* operations.
4627	* @param pfnRead Pointer to function which is gonna handle Read
4628	* operations.
4629	* @param pfnFill Pointer to function which is gonna handle Fill/memset
4630	* operations. (optional)
4631	* @param pvUser User argument to pass to the callbacks.
4632	*
4633	* @remarks Caller enters the device critical section prior to invoking the
4634	* registered callback methods.
4635	*
4636	* @sa PDMDevHlpMmioCreate, PDMDevHlpMmioCreateEx, PDMDevHlpMmioMap,
4637	* PDMDevHlpMmioUnmap.
4638	*/
4639	DECLRCCALLBACKMEMBER(int, pfnMmioSetUpContextEx,(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion, PFNIOMMMIONEWWRITE pfnWrite,
4640	PFNIOMMMIONEWREAD pfnRead, PFNIOMMMIONEWFILL pfnFill, void *pvUser));
4641
4642	/**
4643	* Sets up a raw-mode mapping for an MMIO2 region.
4644	*
4645	* The region must have been created in ring-3 first using
4646	* PDMDevHlpMmio2Create().
4647	*
4648	* @returns VBox status.
4649	* @param pDevIns The device instance to register the ports with.
4650	* @param hRegion The MMIO2 region handle.
4651	* @param offSub Start of what to map into raw-mode. Must be page aligned.
4652	* @param cbSub Number of bytes to map into raw-mode. Must be page
4653	* aligned. Zero is an alias for everything.
4654	* @param ppvMapping Where to return the mapping corresponding to @a offSub.
4655	* @thread EMT(0)
4656	* @note Only available at VM creation time.
4657	*
4658	* @sa PDMDevHlpMmio2Create().
4659	*/
4660	DECLRCCALLBACKMEMBER(int, pfnMmio2SetUpContext,(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion,
4661	size_t offSub, size_t cbSub, void **ppvMapping));
4662
4663	/**
4664	* Bus master physical memory read from the given PCI device.
4665	*
4666	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_READ_BM_DISABLED, later maybe
4667	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
4668	* @param pDevIns The device instance.
4669	* @param pPciDev The PCI device structure. If NULL the default
4670	* PCI device for this device instance is used.
4671	* @param GCPhys Physical address start reading from.
4672	* @param pvBuf Where to put the read bits.
4673	* @param cbRead How many bytes to read.
4674	* @param fFlags Combination of PDM_DEVHLP_PHYS_RW_F_XXX.
4675	* @thread Any thread, but the call may involve the emulation thread.
4676	*/
4677	DECLRCCALLBACKMEMBER(int, pfnPCIPhysRead,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys,
4678	void *pvBuf, size_t cbRead, uint32_t fFlags));
4679
4680	/**
4681	* Bus master physical memory write from the given PCI device.
4682	*
4683	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_WRITE_BM_DISABLED, later maybe
4684	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
4685	* @param pDevIns The device instance.
4686	* @param pPciDev The PCI device structure. If NULL the default
4687	* PCI device for this device instance is used.
4688	* @param GCPhys Physical address to write to.
4689	* @param pvBuf What to write.
4690	* @param cbWrite How many bytes to write.
4691	* @param fFlags Combination of PDM_DEVHLP_PHYS_RW_F_XXX.
4692	* @thread Any thread, but the call may involve the emulation thread.
4693	*/
4694	DECLRCCALLBACKMEMBER(int, pfnPCIPhysWrite,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys,
4695	const void *pvBuf, size_t cbWrite, uint32_t fFlags));
4696
4697	/**
4698	* Set the IRQ for the given PCI device.
4699	*
4700	* @param pDevIns Device instance.
4701	* @param pPciDev The PCI device structure. If NULL the default
4702	* PCI device for this device instance is used.
4703	* @param iIrq IRQ number to set.
4704	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
4705	* @thread Any thread, but will involve the emulation thread.
4706	*/
4707	DECLRCCALLBACKMEMBER(void, pfnPCISetIrq,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, int iIrq, int iLevel));
4708
4709	/**
4710	* Set ISA IRQ for a device.
4711	*
4712	* @param pDevIns Device instance.
4713	* @param iIrq IRQ number to set.
4714	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
4715	* @thread Any thread, but will involve the emulation thread.
4716	*/
4717	DECLRCCALLBACKMEMBER(void, pfnISASetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
4718
4719	/**
4720	* Read physical memory.
4721	*
4722	* @returns VINF_SUCCESS (for now).
4723	* @param pDevIns Device instance.
4724	* @param GCPhys Physical address start reading from.
4725	* @param pvBuf Where to put the read bits.
4726	* @param cbRead How many bytes to read.
4727	* @param fFlags Combination of PDM_DEVHLP_PHYS_RW_F_XXX.
4728	*/
4729	DECLRCCALLBACKMEMBER(int, pfnPhysRead,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead, uint32_t fFlags));
4730
4731	/**
4732	* Write to physical memory.
4733	*
4734	* @returns VINF_SUCCESS for now, and later maybe VERR_EM_MEMORY.
4735	* @param pDevIns Device instance.
4736	* @param GCPhys Physical address to write to.
4737	* @param pvBuf What to write.
4738	* @param cbWrite How many bytes to write.
4739	* @param fFlags Combination of PDM_DEVHLP_PHYS_RW_F_XXX.
4740	*/
4741	DECLRCCALLBACKMEMBER(int, pfnPhysWrite,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite, uint32_t fFlags));
4742
4743	/**
4744	* Checks if the Gate A20 is enabled or not.
4745	*
4746	* @returns true if A20 is enabled.
4747	* @returns false if A20 is disabled.
4748	* @param pDevIns Device instance.
4749	* @thread The emulation thread.
4750	*/
4751	DECLRCCALLBACKMEMBER(bool, pfnA20IsEnabled,(PPDMDEVINS pDevIns));
4752
4753	/**
4754	* Gets the VM state.
4755	*
4756	* @returns VM state.
4757	* @param pDevIns The device instance.
4758	* @thread Any thread (just keep in mind that it's volatile info).
4759	*/
4760	DECLRCCALLBACKMEMBER(VMSTATE, pfnVMState, (PPDMDEVINS pDevIns));
4761
4762	/**
4763	* Set the VM error message
4764	*
4765	* @returns rc.
4766	* @param pDevIns Driver instance.
4767	* @param rc VBox status code.
4768	* @param SRC_POS Use RT_SRC_POS.
4769	* @param pszFormat Error message format string.
4770	* @param ... Error message arguments.
4771	*/
4772	DECLRCCALLBACKMEMBER(int, pfnVMSetError,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL,
4773	const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(6, 7));
4774
4775	/**
4776	* Set the VM error message
4777	*
4778	* @returns rc.
4779	* @param pDevIns Driver instance.
4780	* @param rc VBox status code.
4781	* @param SRC_POS Use RT_SRC_POS.
4782	* @param pszFormat Error message format string.
4783	* @param va Error message arguments.
4784	*/
4785	DECLRCCALLBACKMEMBER(int, pfnVMSetErrorV,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL,
4786	const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(6, 0));
4787
4788	/**
4789	* Set the VM runtime error message
4790	*
4791	* @returns VBox status code.
4792	* @param pDevIns Device instance.
4793	* @param fFlags The action flags. See VMSETRTERR_FLAGS_*.
4794	* @param pszErrorId Error ID string.
4795	* @param pszFormat Error message format string.
4796	* @param ... Error message arguments.
4797	*/
4798	DECLRCCALLBACKMEMBER(int, pfnVMSetRuntimeError,(PPDMDEVINS pDevIns, uint32_t fFlags, const char *pszErrorId,
4799	const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(4, 5));
4800
4801	/**
4802	* Set the VM runtime error message
4803	*
4804	* @returns VBox status code.
4805	* @param pDevIns Device instance.
4806	* @param fFlags The action flags. See VMSETRTERR_FLAGS_*.
4807	* @param pszErrorId Error ID string.
4808	* @param pszFormat Error message format string.
4809	* @param va Error message arguments.
4810	*/
4811	DECLRCCALLBACKMEMBER(int, pfnVMSetRuntimeErrorV,(PPDMDEVINS pDevIns, uint32_t fFlags, const char *pszErrorId,
4812	const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(4, 0));
4813
4814	/**
4815	* Gets the VM handle. Restricted API.
4816	*
4817	* @returns VM Handle.
4818	* @param pDevIns Device instance.
4819	*/
4820	DECLRCCALLBACKMEMBER(PVMCC, pfnGetVM,(PPDMDEVINS pDevIns));
4821
4822	/**
4823	* Gets the VMCPU handle. Restricted API.
4824	*
4825	* @returns VMCPU Handle.
4826	* @param pDevIns The device instance.
4827	*/
4828	DECLRCCALLBACKMEMBER(PVMCPUCC, pfnGetVMCPU,(PPDMDEVINS pDevIns));
4829
4830	/**
4831	* The the VM CPU ID of the current thread (restricted API).
4832	*
4833	* @returns The VMCPUID of the calling thread, NIL_VMCPUID if not EMT.
4834	* @param pDevIns The device instance.
4835	*/
4836	DECLRCCALLBACKMEMBER(VMCPUID, pfnGetCurrentCpuId,(PPDMDEVINS pDevIns));
4837
4838	/**
4839	* Get the current virtual clock time in a VM. The clock frequency must be
4840	* queried separately.
4841	*
4842	* @returns Current clock time.
4843	* @param pDevIns The device instance.
4844	*/
4845	DECLRCCALLBACKMEMBER(uint64_t, pfnTMTimeVirtGet,(PPDMDEVINS pDevIns));
4846
4847	/**
4848	* Get the frequency of the virtual clock.
4849	*
4850	* @returns The clock frequency (not variable at run-time).
4851	* @param pDevIns The device instance.
4852	*/
4853	DECLRCCALLBACKMEMBER(uint64_t, pfnTMTimeVirtGetFreq,(PPDMDEVINS pDevIns));
4854
4855	/**
4856	* Get the current virtual clock time in a VM, in nanoseconds.
4857	*
4858	* @returns Current clock time (in ns).
4859	* @param pDevIns The device instance.
4860	*/
4861	DECLRCCALLBACKMEMBER(uint64_t, pfnTMTimeVirtGetNano,(PPDMDEVINS pDevIns));
4862
4863	/**
4864	* Gets the NOP critical section.
4865	*
4866	* @returns The ring-3 address of the NOP critical section.
4867	* @param pDevIns The device instance.
4868	*/
4869	DECLRCCALLBACKMEMBER(PPDMCRITSECT, pfnCritSectGetNop,(PPDMDEVINS pDevIns));
4870
4871	/**
4872	* Changes the device level critical section from the automatically created
4873	* default to one desired by the device constructor.
4874	*
4875	* Must first be done in ring-3.
4876	*
4877	* @returns VBox status code.
4878	* @param pDevIns The device instance.
4879	* @param pCritSect The critical section to use. NULL is not
4880	* valid, instead use the NOP critical
4881	* section.
4882	*/
4883	DECLRCCALLBACKMEMBER(int, pfnSetDeviceCritSect,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect));
4884
4885	/** @name Exported PDM Critical Section Functions
4886	* @{ */
4887	DECLRCCALLBACKMEMBER(int, pfnCritSectEnter,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, int rcBusy));
4888	DECLRCCALLBACKMEMBER(int, pfnCritSectEnterDebug,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, int rcBusy, RTHCUINTPTR uId, RT_SRC_POS_DECL));
4889	DECLRCCALLBACKMEMBER(int, pfnCritSectTryEnter,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect));
4890	DECLRCCALLBACKMEMBER(int, pfnCritSectTryEnterDebug,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, RTHCUINTPTR uId, RT_SRC_POS_DECL));
4891	DECLRCCALLBACKMEMBER(int, pfnCritSectLeave,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect));
4892	DECLRCCALLBACKMEMBER(bool, pfnCritSectIsOwner,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
4893	DECLRCCALLBACKMEMBER(bool, pfnCritSectIsInitialized,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
4894	DECLRCCALLBACKMEMBER(bool, pfnCritSectHasWaiters,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
4895	DECLRCCALLBACKMEMBER(uint32_t, pfnCritSectGetRecursion,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
4896	/** @} */
4897
4898	/**
4899	* Gets the trace buffer handle.
4900	*
4901	* This is used by the macros found in VBox/vmm/dbgftrace.h and is not
4902	* really inteded for direct usage, thus no inline wrapper function.
4903	*
4904	* @returns Trace buffer handle or NIL_RTTRACEBUF.
4905	* @param pDevIns The device instance.
4906	*/
4907	DECLRCCALLBACKMEMBER(RTTRACEBUF, pfnDBGFTraceBuf,(PPDMDEVINS pDevIns));
4908
4909	/**
4910	* Sets up the PCI bus for the raw-mode context.
4911	*
4912	* This must be called after ring-3 has registered the PCI bus using
4913	* PDMDevHlpPCIBusRegister().
4914	*
4915	* @returns VBox status code.
4916	* @param pDevIns The device instance.
4917	* @param pPciBusReg The PCI bus registration information for raw-mode,
4918	* considered volatile.
4919	* @param ppPciHlp Where to return the raw-mode PCI bus helpers.
4920	*/
4921	DECLRCCALLBACKMEMBER(int, pfnPCIBusSetUpContext,(PPDMDEVINS pDevIns, PPDMPCIBUSREGRC pPciBusReg, PCPDMPCIHLPRC *ppPciHlp));
4922
4923	/**
4924	* Sets up the IOMMU for the raw-mode context.
4925	*
4926	* This must be called after ring-3 has registered the IOMMU using
4927	* PDMDevHlpIommuRegister().
4928	*
4929	* @returns VBox status code.
4930	* @param pDevIns The device instance.
4931	* @param pIommuReg The IOMMU registration information for raw-mode,
4932	* considered volatile.
4933	* @param ppIommuHlp Where to return the raw-mode IOMMU helpers.
4934	*/
4935	DECLRCCALLBACKMEMBER(int, pfnIommuSetUpContext,(PPDMDEVINS pDevIns, PPDMIOMMUREGRC pIommuReg, PCPDMIOMMUHLPRC *ppIommuHlp));
4936
4937	/**
4938	* Sets up the PIC for the ring-0 context.
4939	*
4940	* This must be called after ring-3 has registered the PIC using
4941	* PDMDevHlpPICRegister().
4942	*
4943	* @returns VBox status code.
4944	* @param pDevIns The device instance.
4945	* @param pPicReg The PIC registration information for ring-0,
4946	* considered volatile and copied.
4947	* @param ppPicHlp Where to return the ring-0 PIC helpers.
4948	*/
4949	DECLRCCALLBACKMEMBER(int, pfnPICSetUpContext,(PPDMDEVINS pDevIns, PPDMPICREG pPicReg, PCPDMPICHLP *ppPicHlp));
4950
4951	/**
4952	* Sets up the APIC for the raw-mode context.
4953	*
4954	* This must be called after ring-3 has registered the APIC using
4955	* PDMDevHlpApicRegister().
4956	*
4957	* @returns VBox status code.
4958	* @param pDevIns The device instance.
4959	*/
4960	DECLRCCALLBACKMEMBER(int, pfnApicSetUpContext,(PPDMDEVINS pDevIns));
4961
4962	/**
4963	* Sets up the IOAPIC for the ring-0 context.
4964	*
4965	* This must be called after ring-3 has registered the PIC using
4966	* PDMDevHlpIoApicRegister().
4967	*
4968	* @returns VBox status code.
4969	* @param pDevIns The device instance.
4970	* @param pIoApicReg The PIC registration information for ring-0,
4971	* considered volatile and copied.
4972	* @param ppIoApicHlp Where to return the ring-0 IOAPIC helpers.
4973	*/
4974	DECLRCCALLBACKMEMBER(int, pfnIoApicSetUpContext,(PPDMDEVINS pDevIns, PPDMIOAPICREG pIoApicReg, PCPDMIOAPICHLP *ppIoApicHlp));
4975
4976	/**
4977	* Sets up the HPET for the raw-mode context.
4978	*
4979	* This must be called after ring-3 has registered the PIC using
4980	* PDMDevHlpHpetRegister().
4981	*
4982	* @returns VBox status code.
4983	* @param pDevIns The device instance.
4984	* @param pHpetReg The PIC registration information for raw-mode,
4985	* considered volatile and copied.
4986	* @param ppHpetHlp Where to return the raw-mode HPET helpers.
4987	*/
4988	DECLRCCALLBACKMEMBER(int, pfnHpetSetUpContext,(PPDMDEVINS pDevIns, PPDMHPETREG pHpetReg, PCPDMHPETHLPRC *ppHpetHlp));
4989
4990	/** Space reserved for future members.
4991	* @{ */
4992	DECLRCCALLBACKMEMBER(void, pfnReserved1,(void));
4993	DECLRCCALLBACKMEMBER(void, pfnReserved2,(void));
4994	DECLRCCALLBACKMEMBER(void, pfnReserved3,(void));
4995	DECLRCCALLBACKMEMBER(void, pfnReserved4,(void));
4996	DECLRCCALLBACKMEMBER(void, pfnReserved5,(void));
4997	DECLRCCALLBACKMEMBER(void, pfnReserved6,(void));
4998	DECLRCCALLBACKMEMBER(void, pfnReserved7,(void));
4999	DECLRCCALLBACKMEMBER(void, pfnReserved8,(void));
5000	DECLRCCALLBACKMEMBER(void, pfnReserved9,(void));
5001	DECLRCCALLBACKMEMBER(void, pfnReserved10,(void));
5002	/** @} */
5003
5004	/** Just a safety precaution. */
5005	uint32_t u32TheEnd;
5006	} PDMDEVHLPRC;
5007	/** Pointer PDM Device RC API. */
5008	typedef RGPTRTYPE(struct PDMDEVHLPRC *) PPDMDEVHLPRC;
5009	/** Pointer PDM Device RC API. */
5010	typedef RGPTRTYPE(const struct PDMDEVHLPRC *) PCPDMDEVHLPRC;
5011
5012	/** Current PDMDEVHLP version number. */
5013	#define PDM_DEVHLPRC_VERSION PDM_VERSION_MAKE(0xffe6, 16, 0)
5014
5015
5016	/**
5017	* PDM Device API - R0 Variant.
5018	*/
5019	typedef struct PDMDEVHLPR0
5020	{
5021	/** Structure version. PDM_DEVHLPR0_VERSION defines the current version. */
5022	uint32_t u32Version;
5023
5024	/**
5025	* Sets up ring-0 callback handlers for an I/O port range.
5026	*
5027	* The range must have been created in ring-3 first using
5028	* PDMDevHlpIoPortCreate() or PDMDevHlpIoPortCreateEx().
5029	*
5030	* @returns VBox status.
5031	* @param pDevIns The device instance to register the ports with.
5032	* @param hIoPorts The I/O port range handle.
5033	* @param pfnOut Pointer to function which is gonna handle OUT
5034	* operations. Optional.
5035	* @param pfnIn Pointer to function which is gonna handle IN operations.
5036	* Optional.
5037	* @param pfnOutStr Pointer to function which is gonna handle string OUT
5038	* operations. Optional.
5039	* @param pfnInStr Pointer to function which is gonna handle string IN
5040	* operations. Optional.
5041	* @param pvUser User argument to pass to the callbacks.
5042	*
5043	* @remarks Caller enters the device critical section prior to invoking the
5044	* registered callback methods.
5045	*
5046	* @sa PDMDevHlpIoPortCreate(), PDMDevHlpIoPortCreateEx(),
5047	* PDMDevHlpIoPortMap(), PDMDevHlpIoPortUnmap().
5048	*/
5049	DECLR0CALLBACKMEMBER(int, pfnIoPortSetUpContextEx,(PPDMDEVINS pDevIns, IOMIOPORTHANDLE hIoPorts,
5050	PFNIOMIOPORTNEWOUT pfnOut, PFNIOMIOPORTNEWIN pfnIn,
5051	PFNIOMIOPORTNEWOUTSTRING pfnOutStr, PFNIOMIOPORTNEWINSTRING pfnInStr,
5052	void *pvUser));
5053
5054	/**
5055	* Sets up ring-0 callback handlers for an MMIO region.
5056	*
5057	* The region must have been created in ring-3 first using
5058	* PDMDevHlpMmioCreate(), PDMDevHlpMmioCreateEx(), PDMDevHlpMmioCreateAndMap(),
5059	* PDMDevHlpMmioCreateExAndMap() or PDMDevHlpPCIIORegionCreateMmio().
5060	*
5061	* @returns VBox status.
5062	* @param pDevIns The device instance to register the ports with.
5063	* @param hRegion The MMIO region handle.
5064	* @param pfnWrite Pointer to function which is gonna handle Write
5065	* operations.
5066	* @param pfnRead Pointer to function which is gonna handle Read
5067	* operations.
5068	* @param pfnFill Pointer to function which is gonna handle Fill/memset
5069	* operations. (optional)
5070	* @param pvUser User argument to pass to the callbacks.
5071	*
5072	* @remarks Caller enters the device critical section prior to invoking the
5073	* registered callback methods.
5074	*
5075	* @sa PDMDevHlpMmioCreate(), PDMDevHlpMmioCreateEx(), PDMDevHlpMmioMap(),
5076	* PDMDevHlpMmioUnmap().
5077	*/
5078	DECLR0CALLBACKMEMBER(int, pfnMmioSetUpContextEx,(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion, PFNIOMMMIONEWWRITE pfnWrite,
5079	PFNIOMMMIONEWREAD pfnRead, PFNIOMMMIONEWFILL pfnFill, void *pvUser));
5080
5081	/**
5082	* Sets up a ring-0 mapping for an MMIO2 region.
5083	*
5084	* The region must have been created in ring-3 first using
5085	* PDMDevHlpMmio2Create().
5086	*
5087	* @returns VBox status.
5088	* @param pDevIns The device instance to register the ports with.
5089	* @param hRegion The MMIO2 region handle.
5090	* @param offSub Start of what to map into ring-0. Must be page aligned.
5091	* @param cbSub Number of bytes to map into ring-0. Must be page
5092	* aligned. Zero is an alias for everything.
5093	* @param ppvMapping Where to return the mapping corresponding to @a offSub.
5094	*
5095	* @thread EMT(0)
5096	* @note Only available at VM creation time.
5097	*
5098	* @sa PDMDevHlpMmio2Create().
5099	*/
5100	DECLR0CALLBACKMEMBER(int, pfnMmio2SetUpContext,(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion, size_t offSub, size_t cbSub,
5101	void **ppvMapping));
5102
5103	/**
5104	* Bus master physical memory read from the given PCI device.
5105	*
5106	* @returns VINF_SUCCESS or VERR_PDM_NOT_PCI_BUS_MASTER, later maybe
5107	* VERR_EM_MEMORY.
5108	* @param pDevIns The device instance.
5109	* @param pPciDev The PCI device structure. If NULL the default
5110	* PCI device for this device instance is used.
5111	* @param GCPhys Physical address start reading from.
5112	* @param pvBuf Where to put the read bits.
5113	* @param cbRead How many bytes to read.
5114	* @param fFlags Combination of PDM_DEVHLP_PHYS_RW_F_XXX.
5115	* @thread Any thread, but the call may involve the emulation thread.
5116	*/
5117	DECLR0CALLBACKMEMBER(int, pfnPCIPhysRead,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys,
5118	void *pvBuf, size_t cbRead, uint32_t fFlags));
5119
5120	/**
5121	* Bus master physical memory write from the given PCI device.
5122	*
5123	* @returns VINF_SUCCESS or VERR_PDM_NOT_PCI_BUS_MASTER, later maybe
5124	* VERR_EM_MEMORY.
5125	* @param pDevIns The device instance.
5126	* @param pPciDev The PCI device structure. If NULL the default
5127	* PCI device for this device instance is used.
5128	* @param GCPhys Physical address to write to.
5129	* @param pvBuf What to write.
5130	* @param cbWrite How many bytes to write.
5131	* @param fFlags Combination of PDM_DEVHLP_PHYS_RW_F_XXX.
5132	* @thread Any thread, but the call may involve the emulation thread.
5133	*/
5134	DECLR0CALLBACKMEMBER(int, pfnPCIPhysWrite,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys,
5135	const void *pvBuf, size_t cbWrite, uint32_t fFlags));
5136
5137	/**
5138	* Set the IRQ for the given PCI device.
5139	*
5140	* @param pDevIns Device instance.
5141	* @param pPciDev The PCI device structure. If NULL the default
5142	* PCI device for this device instance is used.
5143	* @param iIrq IRQ number to set.
5144	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
5145	* @thread Any thread, but will involve the emulation thread.
5146	*/
5147	DECLR0CALLBACKMEMBER(void, pfnPCISetIrq,(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, int iIrq, int iLevel));
5148
5149	/**
5150	* Set ISA IRQ for a device.
5151	*
5152	* @param pDevIns Device instance.
5153	* @param iIrq IRQ number to set.
5154	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
5155	* @thread Any thread, but will involve the emulation thread.
5156	*/
5157	DECLR0CALLBACKMEMBER(void, pfnISASetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
5158
5159	/**
5160	* Read physical memory.
5161	*
5162	* @returns VINF_SUCCESS (for now).
5163	* @param pDevIns Device instance.
5164	* @param GCPhys Physical address start reading from.
5165	* @param pvBuf Where to put the read bits.
5166	* @param cbRead How many bytes to read.
5167	* @param fFlags Combination of PDM_DEVHLP_PHYS_RW_F_XXX.
5168	*/
5169	DECLR0CALLBACKMEMBER(int, pfnPhysRead,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead, uint32_t fFlags));
5170
5171	/**
5172	* Write to physical memory.
5173	*
5174	* @returns VINF_SUCCESS for now, and later maybe VERR_EM_MEMORY.
5175	* @param pDevIns Device instance.
5176	* @param GCPhys Physical address to write to.
5177	* @param pvBuf What to write.
5178	* @param cbWrite How many bytes to write.
5179	* @param fFlags Combination of PDM_DEVHLP_PHYS_RW_F_XXX.
5180	*/
5181	DECLR0CALLBACKMEMBER(int, pfnPhysWrite,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite, uint32_t fFlags));
5182
5183	/**
5184	* Checks if the Gate A20 is enabled or not.
5185	*
5186	* @returns true if A20 is enabled.
5187	* @returns false if A20 is disabled.
5188	* @param pDevIns Device instance.
5189	* @thread The emulation thread.
5190	*/
5191	DECLR0CALLBACKMEMBER(bool, pfnA20IsEnabled,(PPDMDEVINS pDevIns));
5192
5193	/**
5194	* Gets the VM state.
5195	*
5196	* @returns VM state.
5197	* @param pDevIns The device instance.
5198	* @thread Any thread (just keep in mind that it's volatile info).
5199	*/
5200	DECLR0CALLBACKMEMBER(VMSTATE, pfnVMState, (PPDMDEVINS pDevIns));
5201
5202	/**
5203	* Set the VM error message
5204	*
5205	* @returns rc.
5206	* @param pDevIns Driver instance.
5207	* @param rc VBox status code.
5208	* @param SRC_POS Use RT_SRC_POS.
5209	* @param pszFormat Error message format string.
5210	* @param ... Error message arguments.
5211	*/
5212	DECLR0CALLBACKMEMBER(int, pfnVMSetError,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL,
5213	const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(6, 7));
5214
5215	/**
5216	* Set the VM error message
5217	*
5218	* @returns rc.
5219	* @param pDevIns Driver instance.
5220	* @param rc VBox status code.
5221	* @param SRC_POS Use RT_SRC_POS.
5222	* @param pszFormat Error message format string.
5223	* @param va Error message arguments.
5224	*/
5225	DECLR0CALLBACKMEMBER(int, pfnVMSetErrorV,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL,
5226	const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(6, 0));
5227
5228	/**
5229	* Set the VM runtime error message
5230	*
5231	* @returns VBox status code.
5232	* @param pDevIns Device instance.
5233	* @param fFlags The action flags. See VMSETRTERR_FLAGS_*.
5234	* @param pszErrorId Error ID string.
5235	* @param pszFormat Error message format string.
5236	* @param ... Error message arguments.
5237	*/
5238	DECLR0CALLBACKMEMBER(int, pfnVMSetRuntimeError,(PPDMDEVINS pDevIns, uint32_t fFlags, const char *pszErrorId,
5239	const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(4, 5));
5240
5241	/**
5242	* Set the VM runtime error message
5243	*
5244	* @returns VBox status code.
5245	* @param pDevIns Device instance.
5246	* @param fFlags The action flags. See VMSETRTERR_FLAGS_*.
5247	* @param pszErrorId Error ID string.
5248	* @param pszFormat Error message format string.
5249	* @param va Error message arguments.
5250	*/
5251	DECLR0CALLBACKMEMBER(int, pfnVMSetRuntimeErrorV,(PPDMDEVINS pDevIns, uint32_t fFlags, const char *pszErrorId,
5252	const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(4, 0));
5253
5254	/**
5255	* Gets the VM handle. Restricted API.
5256	*
5257	* @returns VM Handle.
5258	* @param pDevIns Device instance.
5259	*/
5260	DECLR0CALLBACKMEMBER(PVMCC, pfnGetVM,(PPDMDEVINS pDevIns));
5261
5262	/**
5263	* Gets the VMCPU handle. Restricted API.
5264	*
5265	* @returns VMCPU Handle.
5266	* @param pDevIns The device instance.
5267	*/
5268	DECLR0CALLBACKMEMBER(PVMCPUCC, pfnGetVMCPU,(PPDMDEVINS pDevIns));
5269
5270	/**
5271	* The the VM CPU ID of the current thread (restricted API).
5272	*
5273	* @returns The VMCPUID of the calling thread, NIL_VMCPUID if not EMT.
5274	* @param pDevIns The device instance.
5275	*/
5276	DECLR0CALLBACKMEMBER(VMCPUID, pfnGetCurrentCpuId,(PPDMDEVINS pDevIns));
5277
5278	/** @name Timer handle method wrappers
5279	* @{ */
5280	DECLR0CALLBACKMEMBER(uint64_t, pfnTimerFromMicro,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMicroSecs));
5281	DECLR0CALLBACKMEMBER(uint64_t, pfnTimerFromMilli,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMilliSecs));
5282	DECLR0CALLBACKMEMBER(uint64_t, pfnTimerFromNano,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cNanoSecs));
5283	DECLR0CALLBACKMEMBER(uint64_t, pfnTimerGet,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
5284	DECLR0CALLBACKMEMBER(uint64_t, pfnTimerGetFreq,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
5285	DECLR0CALLBACKMEMBER(uint64_t, pfnTimerGetNano,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
5286	DECLR0CALLBACKMEMBER(bool, pfnTimerIsActive,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
5287	DECLR0CALLBACKMEMBER(bool, pfnTimerIsLockOwner,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
5288	DECLR0CALLBACKMEMBER(VBOXSTRICTRC, pfnTimerLockClock,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, int rcBusy));
5289	/** Takes the clock lock then enters the specified critical section. */
5290	DECLR0CALLBACKMEMBER(VBOXSTRICTRC, pfnTimerLockClock2,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, PPDMCRITSECT pCritSect, int rcBusy));
5291	DECLR0CALLBACKMEMBER(int, pfnTimerSet,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t uExpire));
5292	DECLR0CALLBACKMEMBER(int, pfnTimerSetFrequencyHint,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint32_t uHz));
5293	DECLR0CALLBACKMEMBER(int, pfnTimerSetMicro,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMicrosToNext));
5294	DECLR0CALLBACKMEMBER(int, pfnTimerSetMillies,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMilliesToNext));
5295	DECLR0CALLBACKMEMBER(int, pfnTimerSetNano,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cNanosToNext));
5296	DECLR0CALLBACKMEMBER(int, pfnTimerSetRelative,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cTicksToNext, uint64_t *pu64Now));
5297	DECLR0CALLBACKMEMBER(int, pfnTimerStop,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
5298	DECLR0CALLBACKMEMBER(void, pfnTimerUnlockClock,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer));
5299	DECLR0CALLBACKMEMBER(void, pfnTimerUnlockClock2,(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, PPDMCRITSECT pCritSect));
5300	/** @} */
5301
5302	/**
5303	* Get the current virtual clock time in a VM. The clock frequency must be
5304	* queried separately.
5305	*
5306	* @returns Current clock time.
5307	* @param pDevIns The device instance.
5308	*/
5309	DECLR0CALLBACKMEMBER(uint64_t, pfnTMTimeVirtGet,(PPDMDEVINS pDevIns));
5310
5311	/**
5312	* Get the frequency of the virtual clock.
5313	*
5314	* @returns The clock frequency (not variable at run-time).
5315	* @param pDevIns The device instance.
5316	*/
5317	DECLR0CALLBACKMEMBER(uint64_t, pfnTMTimeVirtGetFreq,(PPDMDEVINS pDevIns));
5318
5319	/**
5320	* Get the current virtual clock time in a VM, in nanoseconds.
5321	*
5322	* @returns Current clock time (in ns).
5323	* @param pDevIns The device instance.
5324	*/
5325	DECLR0CALLBACKMEMBER(uint64_t, pfnTMTimeVirtGetNano,(PPDMDEVINS pDevIns));
5326
5327	/** @name Exported PDM Queue Functions
5328	* @{ */
5329	DECLR0CALLBACKMEMBER(PPDMQUEUE, pfnQueueToPtr,(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue));
5330	DECLR0CALLBACKMEMBER(PPDMQUEUEITEMCORE, pfnQueueAlloc,(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue));
5331	DECLR0CALLBACKMEMBER(void, pfnQueueInsert,(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue, PPDMQUEUEITEMCORE pItem));
5332	DECLR0CALLBACKMEMBER(void, pfnQueueInsertEx,(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue, PPDMQUEUEITEMCORE pItem, uint64_t cNanoMaxDelay));
5333	DECLR0CALLBACKMEMBER(bool, pfnQueueFlushIfNecessary,(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue));
5334	/** @} */
5335
5336	/** @name PDM Task
5337	* @{ */
5338	/**
5339	* Triggers the running the given task.
5340	*
5341	* @returns VBox status code.
5342	* @retval VINF_ALREADY_POSTED is the task is already pending.
5343	* @param pDevIns The device instance.
5344	* @param hTask The task to trigger.
5345	* @thread Any thread.
5346	*/
5347	DECLR0CALLBACKMEMBER(int, pfnTaskTrigger,(PPDMDEVINS pDevIns, PDMTASKHANDLE hTask));
5348	/** @} */
5349
5350	/** @name SUP Event Semaphore Wrappers (single release / auto reset)
5351	* These semaphores can be signalled from ring-0.
5352	* @{ */
5353	/** @sa SUPSemEventSignal */
5354	DECLR0CALLBACKMEMBER(int, pfnSUPSemEventSignal,(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent));
5355	/** @sa SUPSemEventWaitNoResume */
5356	DECLR0CALLBACKMEMBER(int, pfnSUPSemEventWaitNoResume,(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent, uint32_t cMillies));
5357	/** @sa SUPSemEventWaitNsAbsIntr */
5358	DECLR0CALLBACKMEMBER(int, pfnSUPSemEventWaitNsAbsIntr,(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent, uint64_t uNsTimeout));
5359	/** @sa SUPSemEventWaitNsRelIntr */
5360	DECLR0CALLBACKMEMBER(int, pfnSUPSemEventWaitNsRelIntr,(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent, uint64_t cNsTimeout));
5361	/** @sa SUPSemEventGetResolution */
5362	DECLR0CALLBACKMEMBER(uint32_t, pfnSUPSemEventGetResolution,(PPDMDEVINS pDevIns));
5363	/** @} */
5364
5365	/** @name SUP Multi Event Semaphore Wrappers (multiple release / manual reset)
5366	* These semaphores can be signalled from ring-0.
5367	* @{ */
5368	/** @sa SUPSemEventMultiSignal */
5369	DECLR0CALLBACKMEMBER(int, pfnSUPSemEventMultiSignal,(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti));
5370	/** @sa SUPSemEventMultiReset */
5371	DECLR0CALLBACKMEMBER(int, pfnSUPSemEventMultiReset,(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti));
5372	/** @sa SUPSemEventMultiWaitNoResume */
5373	DECLR0CALLBACKMEMBER(int, pfnSUPSemEventMultiWaitNoResume,(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti, uint32_t cMillies));
5374	/** @sa SUPSemEventMultiWaitNsAbsIntr */
5375	DECLR0CALLBACKMEMBER(int, pfnSUPSemEventMultiWaitNsAbsIntr,(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti, uint64_t uNsTimeout));
5376	/** @sa SUPSemEventMultiWaitNsRelIntr */
5377	DECLR0CALLBACKMEMBER(int, pfnSUPSemEventMultiWaitNsRelIntr,(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti, uint64_t cNsTimeout));
5378	/** @sa SUPSemEventMultiGetResolution */
5379	DECLR0CALLBACKMEMBER(uint32_t, pfnSUPSemEventMultiGetResolution,(PPDMDEVINS pDevIns));
5380	/** @} */
5381
5382	/**
5383	* Gets the NOP critical section.
5384	*
5385	* @returns The ring-3 address of the NOP critical section.
5386	* @param pDevIns The device instance.
5387	*/
5388	DECLR0CALLBACKMEMBER(PPDMCRITSECT, pfnCritSectGetNop,(PPDMDEVINS pDevIns));
5389
5390	/**
5391	* Changes the device level critical section from the automatically created
5392	* default to one desired by the device constructor.
5393	*
5394	* Must first be done in ring-3.
5395	*
5396	* @returns VBox status code.
5397	* @param pDevIns The device instance.
5398	* @param pCritSect The critical section to use. NULL is not
5399	* valid, instead use the NOP critical
5400	* section.
5401	*/
5402	DECLR0CALLBACKMEMBER(int, pfnSetDeviceCritSect,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect));
5403
5404	/** @name Exported PDM Critical Section Functions
5405	* @{ */
5406	DECLR0CALLBACKMEMBER(int, pfnCritSectEnter,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, int rcBusy));
5407	DECLR0CALLBACKMEMBER(int, pfnCritSectEnterDebug,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, int rcBusy, RTHCUINTPTR uId, RT_SRC_POS_DECL));
5408	DECLR0CALLBACKMEMBER(int, pfnCritSectTryEnter,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect));
5409	DECLR0CALLBACKMEMBER(int, pfnCritSectTryEnterDebug,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, RTHCUINTPTR uId, RT_SRC_POS_DECL));
5410	DECLR0CALLBACKMEMBER(int, pfnCritSectLeave,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect));
5411	DECLR0CALLBACKMEMBER(bool, pfnCritSectIsOwner,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
5412	DECLR0CALLBACKMEMBER(bool, pfnCritSectIsInitialized,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
5413	DECLR0CALLBACKMEMBER(bool, pfnCritSectHasWaiters,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
5414	DECLR0CALLBACKMEMBER(uint32_t, pfnCritSectGetRecursion,(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect));
5415	DECLR0CALLBACKMEMBER(int, pfnCritSectScheduleExitEvent,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, SUPSEMEVENT hEventToSignal));
5416	/** @} */
5417
5418	/**
5419	* Gets the trace buffer handle.
5420	*
5421	* This is used by the macros found in VBox/vmm/dbgftrace.h and is not
5422	* really inteded for direct usage, thus no inline wrapper function.
5423	*
5424	* @returns Trace buffer handle or NIL_RTTRACEBUF.
5425	* @param pDevIns The device instance.
5426	*/
5427	DECLR0CALLBACKMEMBER(RTTRACEBUF, pfnDBGFTraceBuf,(PPDMDEVINS pDevIns));
5428
5429	/**
5430	* Sets up the PCI bus for the ring-0 context.
5431	*
5432	* This must be called after ring-3 has registered the PCI bus using
5433	* PDMDevHlpPCIBusRegister().
5434	*
5435	* @returns VBox status code.
5436	* @param pDevIns The device instance.
5437	* @param pPciBusReg The PCI bus registration information for ring-0,
5438	* considered volatile and copied.
5439	* @param ppPciHlp Where to return the ring-0 PCI bus helpers.
5440	*/
5441	DECLR0CALLBACKMEMBER(int, pfnPCIBusSetUpContext,(PPDMDEVINS pDevIns, PPDMPCIBUSREGR0 pPciBusReg, PCPDMPCIHLPR0 *ppPciHlp));
5442
5443	/**
5444	* Sets up the IOMMU for the ring-0 context.
5445	*
5446	* This must be called after ring-3 has registered the IOMMU using
5447	* PDMDevHlpIommuRegister().
5448	*
5449	* @returns VBox status code.
5450	* @param pDevIns The device instance.
5451	* @param pIommuReg The IOMMU registration information for ring-0,
5452	* considered volatile and copied.
5453	* @param ppIommuHlp Where to return the ring-0 IOMMU helpers.
5454	*/
5455	DECLR0CALLBACKMEMBER(int, pfnIommuSetUpContext,(PPDMDEVINS pDevIns, PPDMIOMMUREGR0 pIommuReg, PCPDMIOMMUHLPR0 *ppIommuHlp));
5456
5457	/**
5458	* Sets up the PIC for the ring-0 context.
5459	*
5460	* This must be called after ring-3 has registered the PIC using
5461	* PDMDevHlpPICRegister().
5462	*
5463	* @returns VBox status code.
5464	* @param pDevIns The device instance.
5465	* @param pPicReg The PIC registration information for ring-0,
5466	* considered volatile and copied.
5467	* @param ppPicHlp Where to return the ring-0 PIC helpers.
5468	*/
5469	DECLR0CALLBACKMEMBER(int, pfnPICSetUpContext,(PPDMDEVINS pDevIns, PPDMPICREG pPicReg, PCPDMPICHLP *ppPicHlp));
5470
5471	/**
5472	* Sets up the APIC for the ring-0 context.
5473	*
5474	* This must be called after ring-3 has registered the APIC using
5475	* PDMDevHlpApicRegister().
5476	*
5477	* @returns VBox status code.
5478	* @param pDevIns The device instance.
5479	*/
5480	DECLR0CALLBACKMEMBER(int, pfnApicSetUpContext,(PPDMDEVINS pDevIns));
5481
5482	/**
5483	* Sets up the IOAPIC for the ring-0 context.
5484	*
5485	* This must be called after ring-3 has registered the PIC using
5486	* PDMDevHlpIoApicRegister().
5487	*
5488	* @returns VBox status code.
5489	* @param pDevIns The device instance.
5490	* @param pIoApicReg The PIC registration information for ring-0,
5491	* considered volatile and copied.
5492	* @param ppIoApicHlp Where to return the ring-0 IOAPIC helpers.
5493	*/
5494	DECLR0CALLBACKMEMBER(int, pfnIoApicSetUpContext,(PPDMDEVINS pDevIns, PPDMIOAPICREG pIoApicReg, PCPDMIOAPICHLP *ppIoApicHlp));
5495
5496	/**
5497	* Sets up the HPET for the ring-0 context.
5498	*
5499	* This must be called after ring-3 has registered the PIC using
5500	* PDMDevHlpHpetRegister().
5501	*
5502	* @returns VBox status code.
5503	* @param pDevIns The device instance.
5504	* @param pHpetReg The PIC registration information for ring-0,
5505	* considered volatile and copied.
5506	* @param ppHpetHlp Where to return the ring-0 HPET helpers.
5507	*/
5508	DECLR0CALLBACKMEMBER(int, pfnHpetSetUpContext,(PPDMDEVINS pDevIns, PPDMHPETREG pHpetReg, PCPDMHPETHLPR0 *ppHpetHlp));
5509
5510	/** Space reserved for future members.
5511	* @{ */
5512	DECLR0CALLBACKMEMBER(void, pfnReserved1,(void));
5513	DECLR0CALLBACKMEMBER(void, pfnReserved2,(void));
5514	DECLR0CALLBACKMEMBER(void, pfnReserved3,(void));
5515	DECLR0CALLBACKMEMBER(void, pfnReserved4,(void));
5516	DECLR0CALLBACKMEMBER(void, pfnReserved5,(void));
5517	DECLR0CALLBACKMEMBER(void, pfnReserved6,(void));
5518	DECLR0CALLBACKMEMBER(void, pfnReserved7,(void));
5519	DECLR0CALLBACKMEMBER(void, pfnReserved8,(void));
5520	DECLR0CALLBACKMEMBER(void, pfnReserved9,(void));
5521	DECLR0CALLBACKMEMBER(void, pfnReserved10,(void));
5522	/** @} */
5523
5524	/** Just a safety precaution. */
5525	uint32_t u32TheEnd;
5526	} PDMDEVHLPR0;
5527	/** Pointer PDM Device R0 API. */
5528	typedef R0PTRTYPE(struct PDMDEVHLPR0 *) PPDMDEVHLPR0;
5529	/** Pointer PDM Device GC API. */
5530	typedef R0PTRTYPE(const struct PDMDEVHLPR0 *) PCPDMDEVHLPR0;
5531
5532	/** Current PDMDEVHLP version number. */
5533	#define PDM_DEVHLPR0_VERSION PDM_VERSION_MAKE(0xffe5, 19, 0)
5534
5535
5536	/**
5537	* PDM Device Instance.
5538	*/
5539	typedef struct PDMDEVINSR3
5540	{
5541	/** Structure version. PDM_DEVINSR3_VERSION defines the current version. */
5542	uint32_t u32Version;
5543	/** Device instance number. */
5544	uint32_t iInstance;
5545	/** Size of the ring-3, raw-mode and shared bits. */
5546	uint32_t cbRing3;
5547	/** Set if ring-0 context is enabled. */
5548	bool fR0Enabled;
5549	/** Set if raw-mode context is enabled. */
5550	bool fRCEnabled;
5551	/** Alignment padding. */
5552	bool afReserved[2];
5553	/** Pointer the HC PDM Device API. */
5554	PCPDMDEVHLPR3 pHlpR3;
5555	/** Pointer to the shared device instance data. */
5556	RTR3PTR pvInstanceDataR3;
5557	/** Pointer to the device instance data for ring-3. */
5558	RTR3PTR pvInstanceDataForR3;
5559	/** The critical section for the device.
5560	*
5561	* TM and IOM will enter this critical section before calling into the device
5562	* code. PDM will when doing power on, power off, reset, suspend and resume
5563	* notifications. SSM will currently not, but this will be changed later on.
5564	*
5565	* The device gets a critical section automatically assigned to it before
5566	* the constructor is called. If the constructor wishes to use a different
5567	* critical section, it calls PDMDevHlpSetDeviceCritSect() to change it
5568	* very early on.
5569	*/
5570	R3PTRTYPE(PPDMCRITSECT) pCritSectRoR3;
5571	/** Pointer to device registration structure. */
5572	R3PTRTYPE(PCPDMDEVREG) pReg;
5573	/** Configuration handle. */
5574	R3PTRTYPE(PCFGMNODE) pCfg;
5575	/** The base interface of the device.
5576	*
5577	* The device constructor initializes this if it has any
5578	* device level interfaces to export. To obtain this interface
5579	* call PDMR3QueryDevice(). */
5580	PDMIBASE IBase;
5581
5582	/** Tracing indicator. */
5583	uint32_t fTracing;
5584	/** The tracing ID of this device. */
5585	uint32_t idTracing;
5586
5587	/** Ring-3 pointer to the raw-mode device instance. */
5588	R3PTRTYPE(struct PDMDEVINSRC *) pDevInsForRCR3;
5589	/** Raw-mode address of the raw-mode device instance. */
5590	RTRGPTR pDevInsForRC;
5591	/** Ring-3 pointer to the raw-mode instance data. */
5592	RTR3PTR pvInstanceDataForRCR3;
5593
5594	/** PCI device structure size. */
5595	uint32_t cbPciDev;
5596	/** Number of PCI devices in apPciDevs. */
5597	uint32_t cPciDevs;
5598	/** Pointer to the PCI devices for this device.
5599	* (Allocated after the shared instance data.)
5600	* @note If we want to extend this beyond 8 sub-functions/devices, those 1 or
5601	* two devices ever needing it can use cbPciDev and do the address
5602	* calculations that for entries 8+. */
5603	R3PTRTYPE(struct PDMPCIDEV *) apPciDevs[8];
5604
5605	/** Temporarily. */
5606	R0PTRTYPE(struct PDMDEVINSR0 *) pDevInsR0RemoveMe;
5607	/** Temporarily. */
5608	RTR0PTR pvInstanceDataR0;
5609	/** Temporarily. */
5610	RTRCPTR pvInstanceDataRC;
5611	/** Align the internal data more naturally. */
5612	uint32_t au32Padding[HC_ARCH_BITS == 32 ? 13 : 11];
5613
5614	/** Internal data. */
5615	union
5616	{
5617	#ifdef PDMDEVINSINT_DECLARED
5618	PDMDEVINSINTR3 s;
5619	#endif
5620	uint8_t padding[HC_ARCH_BITS == 32 ? 0x40 : 0x90];
5621	} Internal;
5622
5623	/** Device instance data for ring-3. The size of this area is defined
5624	* in the PDMDEVREG::cbInstanceR3 field. */
5625	char achInstanceData[8];
5626	} PDMDEVINSR3;
5627
5628	/** Current PDMDEVINSR3 version number. */
5629	#define PDM_DEVINSR3_VERSION PDM_VERSION_MAKE(0xff82, 4, 0)
5630
5631	/** Converts a pointer to the PDMDEVINSR3::IBase to a pointer to PDMDEVINS. */
5632	#define PDMIBASE_2_PDMDEV(pInterface) ( (PPDMDEVINS)((char *)(pInterface) - RT_UOFFSETOF(PDMDEVINS, IBase)) )
5633
5634
5635	/**
5636	* PDM ring-0 device instance.
5637	*/
5638	typedef struct PDMDEVINSR0
5639	{
5640	/** Structure version. PDM_DEVINSR0_VERSION defines the current version. */
5641	uint32_t u32Version;
5642	/** Device instance number. */
5643	uint32_t iInstance;
5644
5645	/** Pointer the HC PDM Device API. */
5646	PCPDMDEVHLPR0 pHlpR0;
5647	/** Pointer to the shared device instance data. */
5648	RTR0PTR pvInstanceDataR0;
5649	/** Pointer to the device instance data for ring-0. */
5650	RTR0PTR pvInstanceDataForR0;
5651	/** The critical section for the device.
5652	*
5653	* TM and IOM will enter this critical section before calling into the device
5654	* code. PDM will when doing power on, power off, reset, suspend and resume
5655	* notifications. SSM will currently not, but this will be changed later on.
5656	*
5657	* The device gets a critical section automatically assigned to it before
5658	* the constructor is called. If the constructor wishes to use a different
5659	* critical section, it calls PDMDevHlpSetDeviceCritSect() to change it
5660	* very early on.
5661	*/
5662	R0PTRTYPE(PPDMCRITSECT) pCritSectRoR0;
5663	/** Pointer to the ring-0 device registration structure. */
5664	R0PTRTYPE(PCPDMDEVREGR0) pReg;
5665	/** Ring-3 address of the ring-3 device instance. */
5666	R3PTRTYPE(struct PDMDEVINSR3 *) pDevInsForR3;
5667	/** Ring-0 pointer to the ring-3 device instance. */
5668	R0PTRTYPE(struct PDMDEVINSR3 *) pDevInsForR3R0;
5669	/** Ring-0 pointer to the ring-3 instance data. */
5670	RTR0PTR pvInstanceDataForR3R0;
5671	/** Raw-mode address of the raw-mode device instance. */
5672	RGPTRTYPE(struct PDMDEVINSRC *) pDevInsForRC;
5673	/** Ring-0 pointer to the raw-mode device instance. */
5674	R0PTRTYPE(struct PDMDEVINSRC *) pDevInsForRCR0;
5675	/** Ring-0 pointer to the raw-mode instance data. */
5676	RTR0PTR pvInstanceDataForRCR0;
5677
5678	/** PCI device structure size. */
5679	uint32_t cbPciDev;
5680	/** Number of PCI devices in apPciDevs. */
5681	uint32_t cPciDevs;
5682	/** Pointer to the PCI devices for this device.
5683	* (Allocated after the shared instance data.)
5684	* @note If we want to extend this beyond 8 sub-functions/devices, those 1 or
5685	* two devices ever needing it can use cbPciDev and do the address
5686	* calculations that for entries 8+. */
5687	R0PTRTYPE(struct PDMPCIDEV *) apPciDevs[8];
5688
5689	/** Align the internal data more naturally. */
5690	uint32_t au32Padding[HC_ARCH_BITS == 32 ? 3 : 2 + 4];
5691
5692	/** Internal data. */
5693	union
5694	{
5695	#ifdef PDMDEVINSINT_DECLARED
5696	PDMDEVINSINTR0 s;
5697	#endif
5698	uint8_t padding[HC_ARCH_BITS == 32 ? 0x40 : 0x80];
5699	} Internal;
5700
5701	/** Device instance data for ring-0. The size of this area is defined
5702	* in the PDMDEVREG::cbInstanceR0 field. */
5703	char achInstanceData[8];
5704	} PDMDEVINSR0;
5705
5706	/** Current PDMDEVINSR0 version number. */
5707	#define PDM_DEVINSR0_VERSION PDM_VERSION_MAKE(0xff83, 4, 0)
5708
5709
5710	/**
5711	* PDM raw-mode device instance.
5712	*/
5713	typedef struct PDMDEVINSRC
5714	{
5715	/** Structure version. PDM_DEVINSRC_VERSION defines the current version. */
5716	uint32_t u32Version;
5717	/** Device instance number. */
5718	uint32_t iInstance;
5719
5720	/** Pointer the HC PDM Device API. */
5721	PCPDMDEVHLPRC pHlpRC;
5722	/** Pointer to the shared device instance data. */
5723	RTRGPTR pvInstanceDataRC;
5724	/** Pointer to the device instance data for raw-mode. */
5725	RTRGPTR pvInstanceDataForRC;
5726	/** The critical section for the device.
5727	*
5728	* TM and IOM will enter this critical section before calling into the device
5729	* code. PDM will when doing power on, power off, reset, suspend and resume
5730	* notifications. SSM will currently not, but this will be changed later on.
5731	*
5732	* The device gets a critical section automatically assigned to it before
5733	* the constructor is called. If the constructor wishes to use a different
5734	* critical section, it calls PDMDevHlpSetDeviceCritSect() to change it
5735	* very early on.
5736	*/
5737	RGPTRTYPE(PPDMCRITSECT) pCritSectRoRC;
5738	/** Pointer to the raw-mode device registration structure. */
5739	RGPTRTYPE(PCPDMDEVREGRC) pReg;
5740
5741	/** PCI device structure size. */
5742	uint32_t cbPciDev;
5743	/** Number of PCI devices in apPciDevs. */
5744	uint32_t cPciDevs;
5745	/** Pointer to the PCI devices for this device.
5746	* (Allocated after the shared instance data.) */
5747	RGPTRTYPE(struct PDMPCIDEV *) apPciDevs[8];
5748
5749	/** Align the internal data more naturally. */
5750	uint32_t au32Padding[14];
5751
5752	/** Internal data. */
5753	union
5754	{
5755	#ifdef PDMDEVINSINT_DECLARED
5756	PDMDEVINSINTRC s;
5757	#endif
5758	uint8_t padding[0x10];
5759	} Internal;
5760
5761	/** Device instance data for ring-0. The size of this area is defined
5762	* in the PDMDEVREG::cbInstanceR0 field. */
5763	char achInstanceData[8];
5764	} PDMDEVINSRC;
5765
5766	/** Current PDMDEVINSR0 version number. */
5767	#define PDM_DEVINSRC_VERSION PDM_VERSION_MAKE(0xff84, 4, 0)
5768
5769
5770	/** @def PDM_DEVINS_VERSION
5771	* Current PDMDEVINS version number. */
5772	/** @typedef PDMDEVINS
5773	* The device instance structure for the current context. */
5774	#ifdef IN_RING3
5775	# define PDM_DEVINS_VERSION PDM_DEVINSR3_VERSION
5776	typedef PDMDEVINSR3 PDMDEVINS;
5777	#elif defined(IN_RING0)
5778	# define PDM_DEVINS_VERSION PDM_DEVINSR0_VERSION
5779	typedef PDMDEVINSR0 PDMDEVINS;
5780	#elif defined(IN_RC)
5781	# define PDM_DEVINS_VERSION PDM_DEVINSRC_VERSION
5782	typedef PDMDEVINSRC PDMDEVINS;
5783	#else
5784	# error "Missing context defines: IN_RING0, IN_RING3, IN_RC"
5785	#endif
5786
5787	/**
5788	* Get the pointer to an PCI device.
5789	* @note Returns NULL if @a a_idxPciDev is out of bounds.
5790	*/
5791	#define PDMDEV_GET_PPCIDEV(a_pDevIns, a_idxPciDev) \
5792	( (uintptr_t)(a_idxPciDev) < RT_ELEMENTS((a_pDevIns)->apPciDevs) ? (a_pDevIns)->apPciDevs[(uintptr_t)(a_idxPciDev)] \
5793	: PDMDEV_CALC_PPCIDEV(a_pDevIns, a_idxPciDev) )
5794
5795	/**
5796	* Calc the pointer to of a given PCI device.
5797	* @note Returns NULL if @a a_idxPciDev is out of bounds.
5798	*/
5799	#define PDMDEV_CALC_PPCIDEV(a_pDevIns, a_idxPciDev) \
5800	( (uintptr_t)(a_idxPciDev) < (a_pDevIns)->cPciDevs \
5801	? (PPDMPCIDEV)((uint8_t )((a_pDevIns)->apPciDevs[0]) + (a_pDevIns->cbPciDev) (uintptr_t)(a_idxPciDev)) \
5802	: (PPDMPCIDEV)NULL )
5803
5804
5805	/**
5806	* Checks the structure versions of the device instance and device helpers,
5807	* returning if they are incompatible.
5808	*
5809	* This is for use in the constructor.
5810	*
5811	* @param pDevIns The device instance pointer.
5812	*/
5813	#define PDMDEV_CHECK_VERSIONS_RETURN(pDevIns) \
5814	do \
5815	{ \
5816	PPDMDEVINS pDevInsTypeCheck = (pDevIns); NOREF(pDevInsTypeCheck); \
5817	AssertLogRelMsgReturn(PDM_VERSION_ARE_COMPATIBLE((pDevIns)->u32Version, PDM_DEVINS_VERSION), \
5818	("DevIns=%#x mine=%#x\n", (pDevIns)->u32Version, PDM_DEVINS_VERSION), \
5819	VERR_PDM_DEVINS_VERSION_MISMATCH); \
5820	AssertLogRelMsgReturn(PDM_VERSION_ARE_COMPATIBLE((pDevIns)->CTX_SUFF(pHlp)->u32Version, CTX_MID(PDM_DEVHLP,_VERSION)), \
5821	("DevHlp=%#x mine=%#x\n", (pDevIns)->CTX_SUFF(pHlp)->u32Version, CTX_MID(PDM_DEVHLP,_VERSION)), \
5822	VERR_PDM_DEVHLP_VERSION_MISMATCH); \
5823	} while (0)
5824
5825	/**
5826	* Quietly checks the structure versions of the device instance and device
5827	* helpers, returning if they are incompatible.
5828	*
5829	* This is for use in the destructor.
5830	*
5831	* @param pDevIns The device instance pointer.
5832	*/
5833	#define PDMDEV_CHECK_VERSIONS_RETURN_QUIET(pDevIns) \
5834	do \
5835	{ \
5836	PPDMDEVINS pDevInsTypeCheck = (pDevIns); NOREF(pDevInsTypeCheck); \
5837	if (RT_LIKELY(PDM_VERSION_ARE_COMPATIBLE((pDevIns)->u32Version, PDM_DEVINS_VERSION) )) \
5838	{ /* likely */ } else return VERR_PDM_DEVINS_VERSION_MISMATCH; \
5839	if (RT_LIKELY(PDM_VERSION_ARE_COMPATIBLE((pDevIns)->CTX_SUFF(pHlp)->u32Version, CTX_MID(PDM_DEVHLP,_VERSION)) )) \
5840	{ /* likely */ } else return VERR_PDM_DEVHLP_VERSION_MISMATCH; \
5841	} while (0)
5842
5843	/**
5844	* Wrapper around CFGMR3ValidateConfig for the root config for use in the
5845	* constructor - returns on failure.
5846	*
5847	* This should be invoked after having initialized the instance data
5848	* sufficiently for the correct operation of the destructor. The destructor is
5849	* always called!
5850	*
5851	* @param pDevIns Pointer to the PDM device instance.
5852	* @param pszValidValues Patterns describing the valid value names. See
5853	* RTStrSimplePatternMultiMatch for details on the
5854	* pattern syntax.
5855	* @param pszValidNodes Patterns describing the valid node (key) names.
5856	* Pass empty string if no valid nodes.
5857	*/
5858	#define PDMDEV_VALIDATE_CONFIG_RETURN(pDevIns, pszValidValues, pszValidNodes) \
5859	do \
5860	{ \
5861	int rcValCfg = pDevIns->pHlpR3->pfnCFGMValidateConfig((pDevIns)->pCfg, "/", pszValidValues, pszValidNodes, \
5862	(pDevIns)->pReg->szName, (pDevIns)->iInstance); \
5863	if (RT_SUCCESS(rcValCfg)) \
5864	{ /* likely */ } else return rcValCfg; \
5865	} while (0)
5866
5867	/** @def PDMDEV_ASSERT_EMT
5868	* Assert that the current thread is the emulation thread.
5869	*/
5870	#ifdef VBOX_STRICT
5871	# define PDMDEV_ASSERT_EMT(pDevIns) pDevIns->pHlpR3->pfnAssertEMT(pDevIns, __FILE__, __LINE__, __FUNCTION__)
5872	#else
5873	# define PDMDEV_ASSERT_EMT(pDevIns) do { } while (0)
5874	#endif
5875
5876	/** @def PDMDEV_ASSERT_OTHER
5877	* Assert that the current thread is NOT the emulation thread.
5878	*/
5879	#ifdef VBOX_STRICT
5880	# define PDMDEV_ASSERT_OTHER(pDevIns) pDevIns->pHlpR3->pfnAssertOther(pDevIns, __FILE__, __LINE__, __FUNCTION__)
5881	#else
5882	# define PDMDEV_ASSERT_OTHER(pDevIns) do { } while (0)
5883	#endif
5884
5885	/** @def PDMDEV_ASSERT_VMLOCK_OWNER
5886	* Assert that the current thread is owner of the VM lock.
5887	*/
5888	#ifdef VBOX_STRICT
5889	# define PDMDEV_ASSERT_VMLOCK_OWNER(pDevIns) pDevIns->pHlpR3->pfnAssertVMLock(pDevIns, __FILE__, __LINE__, __FUNCTION__)
5890	#else
5891	# define PDMDEV_ASSERT_VMLOCK_OWNER(pDevIns) do { } while (0)
5892	#endif
5893
5894	/** @def PDMDEV_SET_ERROR
5895	* Set the VM error. See PDMDevHlpVMSetError() for printf like message formatting.
5896	*/
5897	#define PDMDEV_SET_ERROR(pDevIns, rc, pszError) \
5898	PDMDevHlpVMSetError(pDevIns, rc, RT_SRC_POS, "%s", pszError)
5899
5900	/** @def PDMDEV_SET_RUNTIME_ERROR
5901	* Set the VM runtime error. See PDMDevHlpVMSetRuntimeError() for printf like message formatting.
5902	*/
5903	#define PDMDEV_SET_RUNTIME_ERROR(pDevIns, fFlags, pszErrorId, pszError) \
5904	PDMDevHlpVMSetRuntimeError(pDevIns, fFlags, pszErrorId, "%s", pszError)
5905
5906	/** @def PDMDEVINS_2_RCPTR
5907	* Converts a PDM Device instance pointer to a RC PDM Device instance pointer.
5908	*/
5909	#ifdef IN_RC
5910	# define PDMDEVINS_2_RCPTR(pDevIns) (pDevIns)
5911	#else
5912	# define PDMDEVINS_2_RCPTR(pDevIns) ( (pDevIns)->pDevInsForRC )
5913	#endif
5914
5915	/** @def PDMDEVINS_2_R3PTR
5916	* Converts a PDM Device instance pointer to a R3 PDM Device instance pointer.
5917	*/
5918	#ifdef IN_RING3
5919	# define PDMDEVINS_2_R3PTR(pDevIns) (pDevIns)
5920	#else
5921	# define PDMDEVINS_2_R3PTR(pDevIns) ( (pDevIns)->pDevInsForR3 )
5922	#endif
5923
5924	/** @def PDMDEVINS_2_R0PTR
5925	* Converts a PDM Device instance pointer to a R0 PDM Device instance pointer.
5926	*/
5927	#ifdef IN_RING0
5928	# define PDMDEVINS_2_R0PTR(pDevIns) (pDevIns)
5929	#else
5930	# define PDMDEVINS_2_R0PTR(pDevIns) ( (pDevIns)->pDevInsR0RemoveMe )
5931	#endif
5932
5933	/** @def PDMDEVINS_DATA_2_R0_REMOVE_ME
5934	* Converts a PDM device instance data pointer to a ring-0 one.
5935	* @deprecated
5936	*/
5937	#ifdef IN_RING0
5938	# define PDMDEVINS_DATA_2_R0_REMOVE_ME(pDevIns, pvCC) (pvCC)
5939	#else
5940	# define PDMDEVINS_DATA_2_R0_REMOVE_ME(pDevIns, pvCC) ( (pDevIns)->pvInstanceDataR0 + (uintptr_t)(pvCC) - (uintptr_t)(pDevIns)->CTX_SUFF(pvInstanceData) )
5941	#endif
5942
5943
5944	/** @def PDMDEVINS_2_DATA
5945	* This is a safer edition of PDMINS_2_DATA that checks that the size of the
5946	* target type is same as PDMDEVREG::cbInstanceShared in strict builds.
5947	*
5948	* @note Do no use this macro in common code working on a core structure which
5949	* device specific code has expanded.
5950	*/
5951	#if defined(VBOX_STRICT) && defined(RT_COMPILER_SUPPORTS_LAMBDA)
5952	# define PDMDEVINS_2_DATA(a_pDevIns, a_PtrType) \
5953	([](PPDMDEVINS a_pLambdaDevIns) -> a_PtrType \
5954	{ \
5955	a_PtrType pLambdaRet = (a_PtrType)(a_pLambdaDevIns)->CTX_SUFF(pvInstanceData); \
5956	Assert(sizeof(*pLambdaRet) == a_pLambdaDevIns->pReg->cbInstanceShared); \
5957	return pLambdaRet; \
5958	}(a_pDevIns))
5959	#else
5960	# define PDMDEVINS_2_DATA(a_pDevIns, a_PtrType) ( (a_PtrType)(a_pDevIns)->CTX_SUFF(pvInstanceData) )
5961	#endif
5962
5963	/** @def PDMDEVINS_2_DATA_CC
5964	* This is a safer edition of PDMINS_2_DATA_CC that checks that the size of the
5965	* target type is same as PDMDEVREG::cbInstanceCC in strict builds.
5966	*
5967	* @note Do no use this macro in common code working on a core structure which
5968	* device specific code has expanded.
5969	*/
5970	#if defined(VBOX_STRICT) && defined(RT_COMPILER_SUPPORTS_LAMBDA)
5971	# define PDMDEVINS_2_DATA_CC(a_pDevIns, a_PtrType) \
5972	([](PPDMDEVINS a_pLambdaDevIns) -> a_PtrType \
5973	{ \
5974	a_PtrType pLambdaRet = (a_PtrType)&(a_pLambdaDevIns)->achInstanceData[0]; \
5975	Assert(sizeof(*pLambdaRet) == a_pLambdaDevIns->pReg->cbInstanceCC); \
5976	return pLambdaRet; \
5977	}(a_pDevIns))
5978	#else
5979	# define PDMDEVINS_2_DATA_CC(a_pDevIns, a_PtrType) ( (a_PtrType)(void *)&(a_pDevIns)->achInstanceData[0] )
5980	#endif
5981
5982
5983	#ifdef IN_RING3
5984
5985	/**
5986	* Combines PDMDevHlpIoPortCreate() & PDMDevHlpIoPortMap().
5987	*/
5988	DECLINLINE(int) PDMDevHlpIoPortCreateAndMap(PPDMDEVINS pDevIns, RTIOPORT Port, RTIOPORT cPorts, PFNIOMIOPORTNEWOUT pfnOut,
5989	PFNIOMIOPORTNEWIN pfnIn, const char *pszDesc, PCIOMIOPORTDESC paExtDescs,
5990	PIOMIOPORTHANDLE phIoPorts)
5991	{
5992	int rc = pDevIns->pHlpR3->pfnIoPortCreateEx(pDevIns, cPorts, 0, NULL, UINT32_MAX,
5993	pfnOut, pfnIn, NULL, NULL, NULL, pszDesc, paExtDescs, phIoPorts);
5994	if (RT_SUCCESS(rc))
5995	rc = pDevIns->pHlpR3->pfnIoPortMap(pDevIns, *phIoPorts, Port);
5996	return rc;
5997	}
5998
5999	/**
6000	* Combines PDMDevHlpIoPortCreate() & PDMDevHlpIoPortMap(), but with pvUser.
6001	*/
6002	DECLINLINE(int) PDMDevHlpIoPortCreateUAndMap(PPDMDEVINS pDevIns, RTIOPORT Port, RTIOPORT cPorts, PFNIOMIOPORTNEWOUT pfnOut,
6003	PFNIOMIOPORTNEWIN pfnIn, void *pvUser,
6004	const char *pszDesc, PCIOMIOPORTDESC paExtDescs, PIOMIOPORTHANDLE phIoPorts)
6005	{
6006	int rc = pDevIns->pHlpR3->pfnIoPortCreateEx(pDevIns, cPorts, 0, NULL, UINT32_MAX,
6007	pfnOut, pfnIn, NULL, NULL, pvUser, pszDesc, paExtDescs, phIoPorts);
6008	if (RT_SUCCESS(rc))
6009	rc = pDevIns->pHlpR3->pfnIoPortMap(pDevIns, *phIoPorts, Port);
6010	return rc;
6011	}
6012
6013	/**
6014	* Combines PDMDevHlpIoPortCreate() & PDMDevHlpIoPortMap(), but with flags.
6015	*/
6016	DECLINLINE(int) PDMDevHlpIoPortCreateFlagsAndMap(PPDMDEVINS pDevIns, RTIOPORT Port, RTIOPORT cPorts, uint32_t fFlags,
6017	PFNIOMIOPORTNEWOUT pfnOut, PFNIOMIOPORTNEWIN pfnIn,
6018	const char *pszDesc, PCIOMIOPORTDESC paExtDescs, PIOMIOPORTHANDLE phIoPorts)
6019	{
6020	int rc = pDevIns->pHlpR3->pfnIoPortCreateEx(pDevIns, cPorts, fFlags, NULL, UINT32_MAX,
6021	pfnOut, pfnIn, NULL, NULL, NULL, pszDesc, paExtDescs, phIoPorts);
6022	if (RT_SUCCESS(rc))
6023	rc = pDevIns->pHlpR3->pfnIoPortMap(pDevIns, *phIoPorts, Port);
6024	return rc;
6025	}
6026
6027	/**
6028	* Combines PDMDevHlpIoPortCreateEx() & PDMDevHlpIoPortMap().
6029	*/
6030	DECLINLINE(int) PDMDevHlpIoPortCreateExAndMap(PPDMDEVINS pDevIns, RTIOPORT Port, RTIOPORT cPorts, uint32_t fFlags,
6031	PFNIOMIOPORTNEWOUT pfnOut, PFNIOMIOPORTNEWIN pfnIn,
6032	PFNIOMIOPORTNEWOUTSTRING pfnOutStr, PFNIOMIOPORTNEWINSTRING pfnInStr, void *pvUser,
6033	const char *pszDesc, PCIOMIOPORTDESC paExtDescs, PIOMIOPORTHANDLE phIoPorts)
6034	{
6035	int rc = pDevIns->pHlpR3->pfnIoPortCreateEx(pDevIns, cPorts, fFlags, NULL, UINT32_MAX,
6036	pfnOut, pfnIn, pfnOutStr, pfnInStr, pvUser, pszDesc, paExtDescs, phIoPorts);
6037	if (RT_SUCCESS(rc))
6038	rc = pDevIns->pHlpR3->pfnIoPortMap(pDevIns, *phIoPorts, Port);
6039	return rc;
6040	}
6041
6042	/**
6043	* @sa PDMDevHlpIoPortCreateEx
6044	*/
6045	DECLINLINE(int) PDMDevHlpIoPortCreate(PPDMDEVINS pDevIns, RTIOPORT cPorts, PPDMPCIDEV pPciDev, uint32_t iPciRegion,
6046	PFNIOMIOPORTNEWOUT pfnOut, PFNIOMIOPORTNEWIN pfnIn, void pvUser, const char pszDesc,
6047	PCIOMIOPORTDESC paExtDescs, PIOMIOPORTHANDLE phIoPorts)
6048	{
6049	return pDevIns->pHlpR3->pfnIoPortCreateEx(pDevIns, cPorts, 0, pPciDev, iPciRegion,
6050	pfnOut, pfnIn, NULL, NULL, pvUser, pszDesc, paExtDescs, phIoPorts);
6051	}
6052
6053
6054	/**
6055	* @sa PDMDevHlpIoPortCreateEx
6056	*/
6057	DECLINLINE(int) PDMDevHlpIoPortCreateIsa(PPDMDEVINS pDevIns, RTIOPORT cPorts, PFNIOMIOPORTNEWOUT pfnOut,
6058	PFNIOMIOPORTNEWIN pfnIn, void pvUser, const char pszDesc,
6059	PCIOMIOPORTDESC paExtDescs, PIOMIOPORTHANDLE phIoPorts)
6060	{
6061	return pDevIns->pHlpR3->pfnIoPortCreateEx(pDevIns, cPorts, 0, NULL, UINT32_MAX,
6062	pfnOut, pfnIn, NULL, NULL, pvUser, pszDesc, paExtDescs, phIoPorts);
6063	}
6064
6065	/**
6066	* @copydoc PDMDEVHLPR3::pfnIoPortCreateEx
6067	*/
6068	DECLINLINE(int) PDMDevHlpIoPortCreateEx(PPDMDEVINS pDevIns, RTIOPORT cPorts, uint32_t fFlags, PPDMPCIDEV pPciDev,
6069	uint32_t iPciRegion, PFNIOMIOPORTNEWOUT pfnOut, PFNIOMIOPORTNEWIN pfnIn,
6070	PFNIOMIOPORTNEWOUTSTRING pfnOutStr, PFNIOMIOPORTNEWINSTRING pfnInStr, void *pvUser,
6071	const char *pszDesc, PCIOMIOPORTDESC paExtDescs, PIOMIOPORTHANDLE phIoPorts)
6072	{
6073	return pDevIns->pHlpR3->pfnIoPortCreateEx(pDevIns, cPorts, fFlags, pPciDev, iPciRegion,
6074	pfnOut, pfnIn, pfnOutStr, pfnInStr, pvUser, pszDesc, paExtDescs, phIoPorts);
6075	}
6076
6077	/**
6078	* @copydoc PDMDEVHLPR3::pfnIoPortMap
6079	*/
6080	DECLINLINE(int) PDMDevHlpIoPortMap(PPDMDEVINS pDevIns, IOMIOPORTHANDLE hIoPorts, RTIOPORT Port)
6081	{
6082	return pDevIns->pHlpR3->pfnIoPortMap(pDevIns, hIoPorts, Port);
6083	}
6084
6085	/**
6086	* @copydoc PDMDEVHLPR3::pfnIoPortUnmap
6087	*/
6088	DECLINLINE(int) PDMDevHlpIoPortUnmap(PPDMDEVINS pDevIns, IOMIOPORTHANDLE hIoPorts)
6089	{
6090	return pDevIns->pHlpR3->pfnIoPortUnmap(pDevIns, hIoPorts);
6091	}
6092
6093	/**
6094	* @copydoc PDMDEVHLPR3::pfnIoPortGetMappingAddress
6095	*/
6096	DECLINLINE(uint32_t) PDMDevHlpIoPortGetMappingAddress(PPDMDEVINS pDevIns, IOMIOPORTHANDLE hIoPorts)
6097	{
6098	return pDevIns->pHlpR3->pfnIoPortGetMappingAddress(pDevIns, hIoPorts);
6099	}
6100
6101
6102	#endif /* IN_RING3 */
6103	#if !defined(IN_RING3) \|\| defined(DOXYGEN_RUNNING)
6104
6105	/**
6106	* @sa PDMDevHlpIoPortSetUpContextEx
6107	*/
6108	DECLINLINE(int) PDMDevHlpIoPortSetUpContext(PPDMDEVINS pDevIns, IOMIOPORTHANDLE hIoPorts,
6109	PFNIOMIOPORTNEWOUT pfnOut, PFNIOMIOPORTNEWIN pfnIn, void *pvUser)
6110	{
6111	return pDevIns->CTX_SUFF(pHlp)->pfnIoPortSetUpContextEx(pDevIns, hIoPorts, pfnOut, pfnIn, NULL, NULL, pvUser);
6112	}
6113
6114	/**
6115	* @copydoc PDMDEVHLPR0::pfnIoPortSetUpContextEx
6116	*/
6117	DECLINLINE(int) PDMDevHlpIoPortSetUpContextEx(PPDMDEVINS pDevIns, IOMIOPORTHANDLE hIoPorts,
6118	PFNIOMIOPORTNEWOUT pfnOut, PFNIOMIOPORTNEWIN pfnIn,
6119	PFNIOMIOPORTNEWOUTSTRING pfnOutStr, PFNIOMIOPORTNEWINSTRING pfnInStr, void *pvUser)
6120	{
6121	return pDevIns->CTX_SUFF(pHlp)->pfnIoPortSetUpContextEx(pDevIns, hIoPorts, pfnOut, pfnIn, pfnOutStr, pfnInStr, pvUser);
6122	}
6123
6124	#endif /* !IN_RING3 \|\| DOXYGEN_RUNNING */
6125	#ifdef IN_RING3
6126
6127	/**
6128	* @sa PDMDevHlpMmioCreateEx
6129	*/
6130	DECLINLINE(int) PDMDevHlpMmioCreate(PPDMDEVINS pDevIns, RTGCPHYS cbRegion, PPDMPCIDEV pPciDev, uint32_t iPciRegion,
6131	PFNIOMMMIONEWWRITE pfnWrite, PFNIOMMMIONEWREAD pfnRead, void *pvUser,
6132	uint32_t fFlags, const char *pszDesc, PIOMMMIOHANDLE phRegion)
6133	{
6134	return pDevIns->pHlpR3->pfnMmioCreateEx(pDevIns, cbRegion, fFlags, pPciDev, iPciRegion,
6135	pfnWrite, pfnRead, NULL, pvUser, pszDesc, phRegion);
6136	}
6137
6138	/**
6139	* @copydoc PDMDEVHLPR3::pfnMmioCreateEx
6140	*/
6141	DECLINLINE(int) PDMDevHlpMmioCreateEx(PPDMDEVINS pDevIns, RTGCPHYS cbRegion,
6142	uint32_t fFlags, PPDMPCIDEV pPciDev, uint32_t iPciRegion,
6143	PFNIOMMMIONEWWRITE pfnWrite, PFNIOMMMIONEWREAD pfnRead, PFNIOMMMIONEWFILL pfnFill,
6144	void pvUser, const char pszDesc, PIOMMMIOHANDLE phRegion)
6145	{
6146	return pDevIns->pHlpR3->pfnMmioCreateEx(pDevIns, cbRegion, fFlags, pPciDev, iPciRegion,
6147	pfnWrite, pfnRead, pfnFill, pvUser, pszDesc, phRegion);
6148	}
6149
6150	/**
6151	* @sa PDMDevHlpMmioCreate and PDMDevHlpMmioMap
6152	*/
6153	DECLINLINE(int) PDMDevHlpMmioCreateAndMap(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTGCPHYS cbRegion,
6154	PFNIOMMMIONEWWRITE pfnWrite, PFNIOMMMIONEWREAD pfnRead,
6155	uint32_t fFlags, const char *pszDesc, PIOMMMIOHANDLE phRegion)
6156	{
6157	int rc = pDevIns->pHlpR3->pfnMmioCreateEx(pDevIns, cbRegion, fFlags, NULL /pPciDev/, UINT32_MAX /iPciRegion/,
6158	pfnWrite, pfnRead, NULL /pfnFill/, NULL /pvUser/, pszDesc, phRegion);
6159	if (RT_SUCCESS(rc))
6160	rc = pDevIns->pHlpR3->pfnMmioMap(pDevIns, *phRegion, GCPhys);
6161	return rc;
6162	}
6163
6164	/**
6165	* @sa PDMDevHlpMmioCreateEx and PDMDevHlpMmioMap
6166	*/
6167	DECLINLINE(int) PDMDevHlpMmioCreateExAndMap(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTGCPHYS cbRegion, uint32_t fFlags,
6168	PPDMPCIDEV pPciDev, uint32_t iPciRegion, PFNIOMMMIONEWWRITE pfnWrite,
6169	PFNIOMMMIONEWREAD pfnRead, PFNIOMMMIONEWFILL pfnFill, void *pvUser,
6170	const char *pszDesc, PIOMMMIOHANDLE phRegion)
6171	{
6172	int rc = pDevIns->pHlpR3->pfnMmioCreateEx(pDevIns, cbRegion, fFlags, pPciDev, iPciRegion,
6173	pfnWrite, pfnRead, pfnFill, pvUser, pszDesc, phRegion);
6174	if (RT_SUCCESS(rc))
6175	rc = pDevIns->pHlpR3->pfnMmioMap(pDevIns, *phRegion, GCPhys);
6176	return rc;
6177	}
6178
6179	/**
6180	* @copydoc PDMDEVHLPR3::pfnMmioMap
6181	*/
6182	DECLINLINE(int) PDMDevHlpMmioMap(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion, RTGCPHYS GCPhys)
6183	{
6184	return pDevIns->pHlpR3->pfnMmioMap(pDevIns, hRegion, GCPhys);
6185	}
6186
6187	/**
6188	* @copydoc PDMDEVHLPR3::pfnMmioUnmap
6189	*/
6190	DECLINLINE(int) PDMDevHlpMmioUnmap(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion)
6191	{
6192	return pDevIns->pHlpR3->pfnMmioUnmap(pDevIns, hRegion);
6193	}
6194
6195	/**
6196	* @copydoc PDMDEVHLPR3::pfnMmioReduce
6197	*/
6198	DECLINLINE(int) PDMDevHlpMmioReduce(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion, RTGCPHYS cbRegion)
6199	{
6200	return pDevIns->pHlpR3->pfnMmioReduce(pDevIns, hRegion, cbRegion);
6201	}
6202
6203	/**
6204	* @copydoc PDMDEVHLPR3::pfnMmioGetMappingAddress
6205	*/
6206	DECLINLINE(RTGCPHYS) PDMDevHlpMmioGetMappingAddress(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion)
6207	{
6208	return pDevIns->pHlpR3->pfnMmioGetMappingAddress(pDevIns, hRegion);
6209	}
6210
6211	#endif /* IN_RING3 */
6212	#if !defined(IN_RING3) \|\| defined(DOXYGEN_RUNNING)
6213
6214	/**
6215	* @sa PDMDevHlpMmioSetUpContextEx
6216	*/
6217	DECLINLINE(int) PDMDevHlpMmioSetUpContext(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion,
6218	PFNIOMMMIONEWWRITE pfnWrite, PFNIOMMMIONEWREAD pfnRead, void *pvUser)
6219	{
6220	return pDevIns->CTX_SUFF(pHlp)->pfnMmioSetUpContextEx(pDevIns, hRegion, pfnWrite, pfnRead, NULL, pvUser);
6221	}
6222
6223	/**
6224	* @copydoc PDMDEVHLPR0::pfnMmioSetUpContextEx
6225	*/
6226	DECLINLINE(int) PDMDevHlpMmioSetUpContextEx(PPDMDEVINS pDevIns, IOMMMIOHANDLE hRegion, PFNIOMMMIONEWWRITE pfnWrite,
6227	PFNIOMMMIONEWREAD pfnRead, PFNIOMMMIONEWFILL pfnFill, void *pvUser)
6228	{
6229	return pDevIns->CTX_SUFF(pHlp)->pfnMmioSetUpContextEx(pDevIns, hRegion, pfnWrite, pfnRead, pfnFill, pvUser);
6230	}
6231
6232	#endif /* !IN_RING3 \|\| DOXYGEN_RUNNING */
6233	#ifdef IN_RING3
6234
6235	/**
6236	* @copydoc PDMDEVHLPR3::pfnMmio2Create
6237	*/
6238	DECLINLINE(int) PDMDevHlpMmio2Create(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t iPciRegion, RTGCPHYS cbRegion,
6239	uint32_t fFlags, const char pszDesc, void *ppvMapping, PPGMMMIO2HANDLE phRegion)
6240	{
6241	return pDevIns->pHlpR3->pfnMmio2Create(pDevIns, pPciDev, iPciRegion, cbRegion, fFlags, pszDesc, ppvMapping, phRegion);
6242	}
6243
6244	/**
6245	* @copydoc PDMDEVHLPR3::pfnMmio2Map
6246	*/
6247	DECLINLINE(int) PDMDevHlpMmio2Map(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion, RTGCPHYS GCPhys)
6248	{
6249	return pDevIns->pHlpR3->pfnMmio2Map(pDevIns, hRegion, GCPhys);
6250	}
6251
6252	/**
6253	* @copydoc PDMDEVHLPR3::pfnMmio2Unmap
6254	*/
6255	DECLINLINE(int) PDMDevHlpMmio2Unmap(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion)
6256	{
6257	return pDevIns->pHlpR3->pfnMmio2Unmap(pDevIns, hRegion);
6258	}
6259
6260	/**
6261	* @copydoc PDMDEVHLPR3::pfnMmio2Reduce
6262	*/
6263	DECLINLINE(int) PDMDevHlpMmio2Reduce(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion, RTGCPHYS cbRegion)
6264	{
6265	return pDevIns->pHlpR3->pfnMmio2Reduce(pDevIns, hRegion, cbRegion);
6266	}
6267
6268	/**
6269	* @copydoc PDMDEVHLPR3::pfnMmio2GetMappingAddress
6270	*/
6271	DECLINLINE(RTGCPHYS) PDMDevHlpMmio2GetMappingAddress(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion)
6272	{
6273	return pDevIns->pHlpR3->pfnMmio2GetMappingAddress(pDevIns, hRegion);
6274	}
6275
6276	#endif /* IN_RING3 */
6277	#if !defined(IN_RING3) \|\| defined(DOXYGEN_RUNNING)
6278
6279	/**
6280	* @copydoc PDMDEVHLPR0::pfnMmio2SetUpContext
6281	*/
6282	DECLINLINE(int) PDMDevHlpMmio2SetUpContext(PPDMDEVINS pDevIns, PGMMMIO2HANDLE hRegion,
6283	size_t offSub, size_t cbSub, void **ppvMapping)
6284	{
6285	return pDevIns->CTX_SUFF(pHlp)->pfnMmio2SetUpContext(pDevIns, hRegion, offSub, cbSub, ppvMapping);
6286	}
6287
6288	#endif /* !IN_RING3 \|\| DOXYGEN_RUNNING */
6289	#ifdef IN_RING3
6290
6291	/**
6292	* @copydoc PDMDEVHLPR3::pfnROMRegister
6293	*/
6294	DECLINLINE(int) PDMDevHlpROMRegister(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, uint32_t cbRange,
6295	const void pvBinary, uint32_t cbBinary, uint32_t fFlags, const char pszDesc)
6296	{
6297	return pDevIns->pHlpR3->pfnROMRegister(pDevIns, GCPhysStart, cbRange, pvBinary, cbBinary, fFlags, pszDesc);
6298	}
6299
6300	/**
6301	* @copydoc PDMDEVHLPR3::pfnROMProtectShadow
6302	*/
6303	DECLINLINE(int) PDMDevHlpROMProtectShadow(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, uint32_t cbRange, PGMROMPROT enmProt)
6304	{
6305	return pDevIns->pHlpR3->pfnROMProtectShadow(pDevIns, GCPhysStart, cbRange, enmProt);
6306	}
6307
6308	/**
6309	* Register a save state data unit.
6310	*
6311	* @returns VBox status.
6312	* @param pDevIns The device instance.
6313	* @param uVersion Data layout version number.
6314	* @param cbGuess The approximate amount of data in the unit.
6315	* Only for progress indicators.
6316	* @param pfnSaveExec Execute save callback, optional.
6317	* @param pfnLoadExec Execute load callback, optional.
6318	*/
6319	DECLINLINE(int) PDMDevHlpSSMRegister(PPDMDEVINS pDevIns, uint32_t uVersion, size_t cbGuess,
6320	PFNSSMDEVSAVEEXEC pfnSaveExec, PFNSSMDEVLOADEXEC pfnLoadExec)
6321	{
6322	return pDevIns->pHlpR3->pfnSSMRegister(pDevIns, uVersion, cbGuess, NULL /pszBefore/,
6323	NULL /pfnLivePrep/, NULL /pfnLiveExec/, NULL /pfnLiveDone/,
6324	NULL /pfnSavePrep/, pfnSaveExec, NULL /pfnSaveDone/,
6325	NULL /pfnLoadPrep/, pfnLoadExec, NULL /pfnLoadDone/);
6326	}
6327
6328	/**
6329	* Register a save state data unit with a live save callback as well.
6330	*
6331	* @returns VBox status.
6332	* @param pDevIns The device instance.
6333	* @param uVersion Data layout version number.
6334	* @param cbGuess The approximate amount of data in the unit.
6335	* Only for progress indicators.
6336	* @param pfnLiveExec Execute live callback, optional.
6337	* @param pfnSaveExec Execute save callback, optional.
6338	* @param pfnLoadExec Execute load callback, optional.
6339	*/
6340	DECLINLINE(int) PDMDevHlpSSMRegister3(PPDMDEVINS pDevIns, uint32_t uVersion, size_t cbGuess,
6341	PFNSSMDEVLIVEEXEC pfnLiveExec, PFNSSMDEVSAVEEXEC pfnSaveExec, PFNSSMDEVLOADEXEC pfnLoadExec)
6342	{
6343	return pDevIns->pHlpR3->pfnSSMRegister(pDevIns, uVersion, cbGuess, NULL /pszBefore/,
6344	NULL /pfnLivePrep/, pfnLiveExec, NULL /pfnLiveDone/,
6345	NULL /pfnSavePrep/, pfnSaveExec, NULL /pfnSaveDone/,
6346	NULL /pfnLoadPrep/, pfnLoadExec, NULL /pfnLoadDone/);
6347	}
6348
6349	/**
6350	* @copydoc PDMDEVHLPR3::pfnSSMRegister
6351	*/
6352	DECLINLINE(int) PDMDevHlpSSMRegisterEx(PPDMDEVINS pDevIns, uint32_t uVersion, size_t cbGuess, const char *pszBefore,
6353	PFNSSMDEVLIVEPREP pfnLivePrep, PFNSSMDEVLIVEEXEC pfnLiveExec, PFNSSMDEVLIVEVOTE pfnLiveVote,
6354	PFNSSMDEVSAVEPREP pfnSavePrep, PFNSSMDEVSAVEEXEC pfnSaveExec, PFNSSMDEVSAVEDONE pfnSaveDone,
6355	PFNSSMDEVLOADPREP pfnLoadPrep, PFNSSMDEVLOADEXEC pfnLoadExec, PFNSSMDEVLOADDONE pfnLoadDone)
6356	{
6357	return pDevIns->pHlpR3->pfnSSMRegister(pDevIns, uVersion, cbGuess, pszBefore,
6358	pfnLivePrep, pfnLiveExec, pfnLiveVote,
6359	pfnSavePrep, pfnSaveExec, pfnSaveDone,
6360	pfnLoadPrep, pfnLoadExec, pfnLoadDone);
6361	}
6362
6363	/**
6364	* @copydoc PDMDEVHLPR3::pfnTimerCreate
6365	*/
6366	DECLINLINE(int) PDMDevHlpTimerCreate(PPDMDEVINS pDevIns, TMCLOCK enmClock, PFNTMTIMERDEV pfnCallback, void *pvUser,
6367	uint32_t fFlags, const char *pszDesc, PTMTIMERHANDLE phTimer)
6368	{
6369	return pDevIns->pHlpR3->pfnTimerCreate(pDevIns, enmClock, pfnCallback, pvUser, fFlags, pszDesc, phTimer);
6370	}
6371
6372	#endif /* IN_RING3 */
6373
6374	/**
6375	* @copydoc PDMDEVHLPR3::pfnTimerFromMicro
6376	*/
6377	DECLINLINE(uint64_t) PDMDevHlpTimerFromMicro(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMicroSecs)
6378	{
6379	return pDevIns->CTX_SUFF(pHlp)->pfnTimerFromMicro(pDevIns, hTimer, cMicroSecs);
6380	}
6381
6382	/**
6383	* @copydoc PDMDEVHLPR3::pfnTimerFromMilli
6384	*/
6385	DECLINLINE(uint64_t) PDMDevHlpTimerFromMilli(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMilliSecs)
6386	{
6387	return pDevIns->CTX_SUFF(pHlp)->pfnTimerFromMilli(pDevIns, hTimer, cMilliSecs);
6388	}
6389
6390	/**
6391	* @copydoc PDMDEVHLPR3::pfnTimerFromNano
6392	*/
6393	DECLINLINE(uint64_t) PDMDevHlpTimerFromNano(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cNanoSecs)
6394	{
6395	return pDevIns->CTX_SUFF(pHlp)->pfnTimerFromNano(pDevIns, hTimer, cNanoSecs);
6396	}
6397
6398	/**
6399	* @copydoc PDMDEVHLPR3::pfnTimerGet
6400	*/
6401	DECLINLINE(uint64_t) PDMDevHlpTimerGet(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer)
6402	{
6403	return pDevIns->CTX_SUFF(pHlp)->pfnTimerGet(pDevIns, hTimer);
6404	}
6405
6406	/**
6407	* @copydoc PDMDEVHLPR3::pfnTimerGetFreq
6408	*/
6409	DECLINLINE(uint64_t) PDMDevHlpTimerGetFreq(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer)
6410	{
6411	return pDevIns->CTX_SUFF(pHlp)->pfnTimerGetFreq(pDevIns, hTimer);
6412	}
6413
6414	/**
6415	* @copydoc PDMDEVHLPR3::pfnTimerGetNano
6416	*/
6417	DECLINLINE(uint64_t) PDMDevHlpTimerGetNano(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer)
6418	{
6419	return pDevIns->CTX_SUFF(pHlp)->pfnTimerGetNano(pDevIns, hTimer);
6420	}
6421
6422	/**
6423	* @copydoc PDMDEVHLPR3::pfnTimerIsActive
6424	*/
6425	DECLINLINE(bool) PDMDevHlpTimerIsActive(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer)
6426	{
6427	return pDevIns->CTX_SUFF(pHlp)->pfnTimerIsActive(pDevIns, hTimer);
6428	}
6429
6430	/**
6431	* @copydoc PDMDEVHLPR3::pfnTimerIsLockOwner
6432	*/
6433	DECLINLINE(bool) PDMDevHlpTimerIsLockOwner(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer)
6434	{
6435	return pDevIns->CTX_SUFF(pHlp)->pfnTimerIsLockOwner(pDevIns, hTimer);
6436	}
6437
6438	/**
6439	* @copydoc PDMDEVHLPR3::pfnTimerLockClock
6440	*/
6441	DECLINLINE(VBOXSTRICTRC) PDMDevHlpTimerLockClock(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, int rcBusy)
6442	{
6443	return pDevIns->CTX_SUFF(pHlp)->pfnTimerLockClock(pDevIns, hTimer, rcBusy);
6444	}
6445
6446	/**
6447	* @copydoc PDMDEVHLPR3::pfnTimerLockClock2
6448	*/
6449	DECLINLINE(VBOXSTRICTRC) PDMDevHlpTimerLockClock2(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, PPDMCRITSECT pCritSect, int rcBusy)
6450	{
6451	return pDevIns->CTX_SUFF(pHlp)->pfnTimerLockClock2(pDevIns, hTimer, pCritSect, rcBusy);
6452	}
6453
6454	/**
6455	* @copydoc PDMDEVHLPR3::pfnTimerSet
6456	*/
6457	DECLINLINE(int) PDMDevHlpTimerSet(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t uExpire)
6458	{
6459	return pDevIns->CTX_SUFF(pHlp)->pfnTimerSet(pDevIns, hTimer, uExpire);
6460	}
6461
6462	/**
6463	* @copydoc PDMDEVHLPR3::pfnTimerSetFrequencyHint
6464	*/
6465	DECLINLINE(int) PDMDevHlpTimerSetFrequencyHint(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint32_t uHz)
6466	{
6467	return pDevIns->CTX_SUFF(pHlp)->pfnTimerSetFrequencyHint(pDevIns, hTimer, uHz);
6468	}
6469
6470	/**
6471	* @copydoc PDMDEVHLPR3::pfnTimerSetMicro
6472	*/
6473	DECLINLINE(int) PDMDevHlpTimerSetMicro(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMicrosToNext)
6474	{
6475	return pDevIns->CTX_SUFF(pHlp)->pfnTimerSetMicro(pDevIns, hTimer, cMicrosToNext);
6476	}
6477
6478	/**
6479	* @copydoc PDMDEVHLPR3::pfnTimerSetMillies
6480	*/
6481	DECLINLINE(int) PDMDevHlpTimerSetMillies(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cMilliesToNext)
6482	{
6483	return pDevIns->CTX_SUFF(pHlp)->pfnTimerSetMillies(pDevIns, hTimer, cMilliesToNext);
6484	}
6485
6486	/**
6487	* @copydoc PDMDEVHLPR3::pfnTimerSetNano
6488	*/
6489	DECLINLINE(int) PDMDevHlpTimerSetNano(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cNanosToNext)
6490	{
6491	return pDevIns->CTX_SUFF(pHlp)->pfnTimerSetNano(pDevIns, hTimer, cNanosToNext);
6492	}
6493
6494	/**
6495	* @copydoc PDMDEVHLPR3::pfnTimerSetRelative
6496	*/
6497	DECLINLINE(int) PDMDevHlpTimerSetRelative(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, uint64_t cTicksToNext, uint64_t *pu64Now)
6498	{
6499	return pDevIns->CTX_SUFF(pHlp)->pfnTimerSetRelative(pDevIns, hTimer, cTicksToNext, pu64Now);
6500	}
6501
6502	/**
6503	* @copydoc PDMDEVHLPR3::pfnTimerStop
6504	*/
6505	DECLINLINE(int) PDMDevHlpTimerStop(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer)
6506	{
6507	return pDevIns->CTX_SUFF(pHlp)->pfnTimerStop(pDevIns, hTimer);
6508	}
6509
6510	/**
6511	* @copydoc PDMDEVHLPR3::pfnTimerUnlockClock
6512	*/
6513	DECLINLINE(void) PDMDevHlpTimerUnlockClock(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer)
6514	{
6515	pDevIns->CTX_SUFF(pHlp)->pfnTimerUnlockClock(pDevIns, hTimer);
6516	}
6517
6518	/**
6519	* @copydoc PDMDEVHLPR3::pfnTimerUnlockClock2
6520	*/
6521	DECLINLINE(void) PDMDevHlpTimerUnlockClock2(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, PPDMCRITSECT pCritSect)
6522	{
6523	pDevIns->CTX_SUFF(pHlp)->pfnTimerUnlockClock2(pDevIns, hTimer, pCritSect);
6524	}
6525
6526	#ifdef IN_RING3
6527
6528	/**
6529	* @copydoc PDMDEVHLPR3::pfnTimerSetCritSect
6530	*/
6531	DECLINLINE(int) PDMDevHlpTimerSetCritSect(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, PPDMCRITSECT pCritSect)
6532	{
6533	return pDevIns->pHlpR3->pfnTimerSetCritSect(pDevIns, hTimer, pCritSect);
6534	}
6535
6536	/**
6537	* @copydoc PDMDEVHLPR3::pfnTimerSave
6538	*/
6539	DECLINLINE(int) PDMDevHlpTimerSave(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, PSSMHANDLE pSSM)
6540	{
6541	return pDevIns->pHlpR3->pfnTimerSave(pDevIns, hTimer, pSSM);
6542	}
6543
6544	/**
6545	* @copydoc PDMDEVHLPR3::pfnTimerLoad
6546	*/
6547	DECLINLINE(int) PDMDevHlpTimerLoad(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer, PSSMHANDLE pSSM)
6548	{
6549	return pDevIns->pHlpR3->pfnTimerLoad(pDevIns, hTimer, pSSM);
6550	}
6551
6552	/**
6553	* @copydoc PDMDEVHLPR3::pfnTimerDestroy
6554	*/
6555	DECLINLINE(int) PDMDevHlpTimerDestroy(PPDMDEVINS pDevIns, TMTIMERHANDLE hTimer)
6556	{
6557	return pDevIns->pHlpR3->pfnTimerDestroy(pDevIns, hTimer);
6558	}
6559
6560	/**
6561	* @copydoc PDMDEVHLPR3::pfnTMUtcNow
6562	*/
6563	DECLINLINE(PRTTIMESPEC) PDMDevHlpTMUtcNow(PPDMDEVINS pDevIns, PRTTIMESPEC pTime)
6564	{
6565	return pDevIns->pHlpR3->pfnTMUtcNow(pDevIns, pTime);
6566	}
6567
6568	#endif
6569
6570	/**
6571	* Read physical memory - unknown data usage.
6572	*
6573	* @returns VINF_SUCCESS (for now).
6574	* @param pDevIns The device instance.
6575	* @param GCPhys Physical address start reading from.
6576	* @param pvBuf Where to put the read bits.
6577	* @param cbRead How many bytes to read.
6578	* @thread Any thread, but the call may involve the emulation thread.
6579	*/
6580	DECLINLINE(int) PDMDevHlpPhysRead(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead)
6581	{
6582	return pDevIns->CTX_SUFF(pHlp)->pfnPhysRead(pDevIns, GCPhys, pvBuf, cbRead, PDM_DEVHLP_PHYS_RW_F_DEFAULT);
6583	}
6584
6585	/**
6586	* Write to physical memory - unknown data usage.
6587	*
6588	* @returns VINF_SUCCESS for now, and later maybe VERR_EM_MEMORY.
6589	* @param pDevIns The device instance.
6590	* @param GCPhys Physical address to write to.
6591	* @param pvBuf What to write.
6592	* @param cbWrite How many bytes to write.
6593	* @thread Any thread, but the call may involve the emulation thread.
6594	*/
6595	DECLINLINE(int) PDMDevHlpPhysWrite(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite)
6596	{
6597	return pDevIns->CTX_SUFF(pHlp)->pfnPhysWrite(pDevIns, GCPhys, pvBuf, cbWrite, PDM_DEVHLP_PHYS_RW_F_DEFAULT);
6598	}
6599
6600	/**
6601	* Read physical memory - reads meta data processed by the device.
6602	*
6603	* @returns VINF_SUCCESS (for now).
6604	* @param pDevIns The device instance.
6605	* @param GCPhys Physical address start reading from.
6606	* @param pvBuf Where to put the read bits.
6607	* @param cbRead How many bytes to read.
6608	* @thread Any thread, but the call may involve the emulation thread.
6609	*/
6610	DECLINLINE(int) PDMDevHlpPhysReadMeta(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead)
6611	{
6612	return pDevIns->CTX_SUFF(pHlp)->pfnPhysRead(pDevIns, GCPhys, pvBuf, cbRead, PDM_DEVHLP_PHYS_RW_F_DATA_META);
6613	}
6614
6615	/**
6616	* Write to physical memory - written data was created/altered by the device.
6617	*
6618	* @returns VINF_SUCCESS for now, and later maybe VERR_EM_MEMORY.
6619	* @param pDevIns The device instance.
6620	* @param GCPhys Physical address to write to.
6621	* @param pvBuf What to write.
6622	* @param cbWrite How many bytes to write.
6623	* @thread Any thread, but the call may involve the emulation thread.
6624	*/
6625	DECLINLINE(int) PDMDevHlpPhysWriteMeta(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite)
6626	{
6627	return pDevIns->CTX_SUFF(pHlp)->pfnPhysWrite(pDevIns, GCPhys, pvBuf, cbWrite, PDM_DEVHLP_PHYS_RW_F_DATA_META);
6628	}
6629
6630	/**
6631	* Read physical memory - read data will not be touched by the device.
6632	*
6633	* @returns VINF_SUCCESS (for now).
6634	* @param pDevIns The device instance.
6635	* @param GCPhys Physical address start reading from.
6636	* @param pvBuf Where to put the read bits.
6637	* @param cbRead How many bytes to read.
6638	* @thread Any thread, but the call may involve the emulation thread.
6639	*/
6640	DECLINLINE(int) PDMDevHlpPhysReadUser(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead)
6641	{
6642	return pDevIns->CTX_SUFF(pHlp)->pfnPhysRead(pDevIns, GCPhys, pvBuf, cbRead, PDM_DEVHLP_PHYS_RW_F_DATA_USER);
6643	}
6644
6645	/**
6646	* Write to physical memory - written data was not touched/created by the device.
6647	*
6648	* @returns VINF_SUCCESS for now, and later maybe VERR_EM_MEMORY.
6649	* @param pDevIns The device instance.
6650	* @param GCPhys Physical address to write to.
6651	* @param pvBuf What to write.
6652	* @param cbWrite How many bytes to write.
6653	* @thread Any thread, but the call may involve the emulation thread.
6654	*/
6655	DECLINLINE(int) PDMDevHlpPhysWriteUser(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite)
6656	{
6657	return pDevIns->CTX_SUFF(pHlp)->pfnPhysWrite(pDevIns, GCPhys, pvBuf, cbWrite, PDM_DEVHLP_PHYS_RW_F_DATA_USER);
6658	}
6659
6660	#ifdef IN_RING3
6661
6662	/**
6663	* @copydoc PDMDEVHLPR3::pfnPhysGCPhys2CCPtr
6664	*/
6665	DECLINLINE(int) PDMDevHlpPhysGCPhys2CCPtr(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, uint32_t fFlags, void **ppv, PPGMPAGEMAPLOCK pLock)
6666	{
6667	return pDevIns->CTX_SUFF(pHlp)->pfnPhysGCPhys2CCPtr(pDevIns, GCPhys, fFlags, ppv, pLock);
6668	}
6669
6670	/**
6671	* @copydoc PDMDEVHLPR3::pfnPhysGCPhys2CCPtrReadOnly
6672	*/
6673	DECLINLINE(int) PDMDevHlpPhysGCPhys2CCPtrReadOnly(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, uint32_t fFlags, void const **ppv,
6674	PPGMPAGEMAPLOCK pLock)
6675	{
6676	return pDevIns->CTX_SUFF(pHlp)->pfnPhysGCPhys2CCPtrReadOnly(pDevIns, GCPhys, fFlags, ppv, pLock);
6677	}
6678
6679	/**
6680	* @copydoc PDMDEVHLPR3::pfnPhysReleasePageMappingLock
6681	*/
6682	DECLINLINE(void) PDMDevHlpPhysReleasePageMappingLock(PPDMDEVINS pDevIns, PPGMPAGEMAPLOCK pLock)
6683	{
6684	pDevIns->CTX_SUFF(pHlp)->pfnPhysReleasePageMappingLock(pDevIns, pLock);
6685	}
6686
6687	/**
6688	* @copydoc PDMDEVHLPR3::pfnPhysBulkGCPhys2CCPtr
6689	*/
6690	DECLINLINE(int) PDMDevHlpPhysBulkGCPhys2CCPtr(PPDMDEVINS pDevIns, uint32_t cPages, PCRTGCPHYS paGCPhysPages,
6691	uint32_t fFlags, void **papvPages, PPGMPAGEMAPLOCK paLocks)
6692	{
6693	return pDevIns->CTX_SUFF(pHlp)->pfnPhysBulkGCPhys2CCPtr(pDevIns, cPages, paGCPhysPages, fFlags, papvPages, paLocks);
6694	}
6695
6696	/**
6697	* @copydoc PDMDEVHLPR3::pfnPhysBulkGCPhys2CCPtrReadOnly
6698	*/
6699	DECLINLINE(int) PDMDevHlpPhysBulkGCPhys2CCPtrReadOnly(PPDMDEVINS pDevIns, uint32_t cPages, PCRTGCPHYS paGCPhysPages,
6700	uint32_t fFlags, void const **papvPages, PPGMPAGEMAPLOCK paLocks)
6701	{
6702	return pDevIns->CTX_SUFF(pHlp)->pfnPhysBulkGCPhys2CCPtrReadOnly(pDevIns, cPages, paGCPhysPages, fFlags, papvPages, paLocks);
6703	}
6704
6705	/**
6706	* @copydoc PDMDEVHLPR3::pfnPhysBulkReleasePageMappingLocks
6707	*/
6708	DECLINLINE(void) PDMDevHlpPhysBulkReleasePageMappingLocks(PPDMDEVINS pDevIns, uint32_t cPages, PPGMPAGEMAPLOCK paLocks)
6709	{
6710	pDevIns->CTX_SUFF(pHlp)->pfnPhysBulkReleasePageMappingLocks(pDevIns, cPages, paLocks);
6711	}
6712
6713	/**
6714	* @copydoc PDMDEVHLPR3::pfnCpuGetGuestMicroarch
6715	*/
6716	DECLINLINE(CPUMMICROARCH) PDMDevHlpCpuGetGuestMicroarch(PPDMDEVINS pDevIns)
6717	{
6718	return pDevIns->CTX_SUFF(pHlp)->pfnCpuGetGuestMicroarch(pDevIns);
6719	}
6720
6721	/**
6722	* @copydoc PDMDEVHLPR3::pfnCpuGetGuestAddrWidths
6723	*/
6724	DECLINLINE(void) PDMDevHlpCpuGetGuestAddrWidths(PPDMDEVINS pDevIns, uint8_t pcPhysAddrWidth, uint8_t pcLinearAddrWidth)
6725	{
6726	pDevIns->CTX_SUFF(pHlp)->pfnCpuGetGuestAddrWidths(pDevIns, pcPhysAddrWidth, pcLinearAddrWidth);
6727	}
6728
6729	/**
6730	* @copydoc PDMDEVHLPR3::pfnPhysReadGCVirt
6731	*/
6732	DECLINLINE(int) PDMDevHlpPhysReadGCVirt(PPDMDEVINS pDevIns, void *pvDst, RTGCPTR GCVirtSrc, size_t cb)
6733	{
6734	return pDevIns->pHlpR3->pfnPhysReadGCVirt(pDevIns, pvDst, GCVirtSrc, cb);
6735	}
6736
6737	/**
6738	* @copydoc PDMDEVHLPR3::pfnPhysWriteGCVirt
6739	*/
6740	DECLINLINE(int) PDMDevHlpPhysWriteGCVirt(PPDMDEVINS pDevIns, RTGCPTR GCVirtDst, const void *pvSrc, size_t cb)
6741	{
6742	return pDevIns->pHlpR3->pfnPhysWriteGCVirt(pDevIns, GCVirtDst, pvSrc, cb);
6743	}
6744
6745	/**
6746	* @copydoc PDMDEVHLPR3::pfnPhysGCPtr2GCPhys
6747	*/
6748	DECLINLINE(int) PDMDevHlpPhysGCPtr2GCPhys(PPDMDEVINS pDevIns, RTGCPTR GCPtr, PRTGCPHYS pGCPhys)
6749	{
6750	return pDevIns->pHlpR3->pfnPhysGCPtr2GCPhys(pDevIns, GCPtr, pGCPhys);
6751	}
6752
6753	/**
6754	* @copydoc PDMDEVHLPR3::pfnMMHeapAlloc
6755	*/
6756	DECLINLINE(void *) PDMDevHlpMMHeapAlloc(PPDMDEVINS pDevIns, size_t cb)
6757	{
6758	return pDevIns->pHlpR3->pfnMMHeapAlloc(pDevIns, cb);
6759	}
6760
6761	/**
6762	* @copydoc PDMDEVHLPR3::pfnMMHeapAllocZ
6763	*/
6764	DECLINLINE(void *) PDMDevHlpMMHeapAllocZ(PPDMDEVINS pDevIns, size_t cb)
6765	{
6766	return pDevIns->pHlpR3->pfnMMHeapAllocZ(pDevIns, cb);
6767	}
6768
6769	/**
6770	* @copydoc PDMDEVHLPR3::pfnMMHeapFree
6771	*/
6772	DECLINLINE(void) PDMDevHlpMMHeapFree(PPDMDEVINS pDevIns, void *pv)
6773	{
6774	pDevIns->pHlpR3->pfnMMHeapFree(pDevIns, pv);
6775	}
6776	#endif /* IN_RING3 */
6777
6778	/**
6779	* @copydoc PDMDEVHLPR3::pfnVMState
6780	*/
6781	DECLINLINE(VMSTATE) PDMDevHlpVMState(PPDMDEVINS pDevIns)
6782	{
6783	return pDevIns->CTX_SUFF(pHlp)->pfnVMState(pDevIns);
6784	}
6785
6786	#ifdef IN_RING3
6787	/**
6788	* @copydoc PDMDEVHLPR3::pfnVMTeleportedAndNotFullyResumedYet
6789	*/
6790	DECLINLINE(bool) PDMDevHlpVMTeleportedAndNotFullyResumedYet(PPDMDEVINS pDevIns)
6791	{
6792	return pDevIns->pHlpR3->pfnVMTeleportedAndNotFullyResumedYet(pDevIns);
6793	}
6794	#endif /* IN_RING3 */
6795
6796	/**
6797	* @copydoc PDMDEVHLPR3::pfnVMSetError
6798	*/
6799	DECLINLINE(int) RT_IPRT_FORMAT_ATTR(6, 7) PDMDevHlpVMSetError(PPDMDEVINS pDevIns, const int rc, RT_SRC_POS_DECL,
6800	const char *pszFormat, ...)
6801	{
6802	va_list va;
6803	va_start(va, pszFormat);
6804	pDevIns->CTX_SUFF(pHlp)->pfnVMSetErrorV(pDevIns, rc, RT_SRC_POS_ARGS, pszFormat, va);
6805	va_end(va);
6806	return rc;
6807	}
6808
6809	/**
6810	* @copydoc PDMDEVHLPR3::pfnVMSetRuntimeError
6811	*/
6812	DECLINLINE(int) RT_IPRT_FORMAT_ATTR(4, 5) PDMDevHlpVMSetRuntimeError(PPDMDEVINS pDevIns, uint32_t fFlags, const char *pszErrorId,
6813	const char *pszFormat, ...)
6814	{
6815	va_list va;
6816	int rc;
6817	va_start(va, pszFormat);
6818	rc = pDevIns->CTX_SUFF(pHlp)->pfnVMSetRuntimeErrorV(pDevIns, fFlags, pszErrorId, pszFormat, va);
6819	va_end(va);
6820	return rc;
6821	}
6822
6823	/**
6824	* VBOX_STRICT wrapper for pHlp->pfnDBGFStopV.
6825	*
6826	* @returns VBox status code which must be passed up to the VMM. This will be
6827	* VINF_SUCCESS in non-strict builds.
6828	* @param pDevIns The device instance.
6829	* @param SRC_POS Use RT_SRC_POS.
6830	* @param pszFormat Message. (optional)
6831	* @param ... Message parameters.
6832	*/
6833	DECLINLINE(int) RT_IPRT_FORMAT_ATTR(5, 6) PDMDevHlpDBGFStop(PPDMDEVINS pDevIns, RT_SRC_POS_DECL, const char *pszFormat, ...)
6834	{
6835	#ifdef VBOX_STRICT
6836	# ifdef IN_RING3
6837	int rc;
6838	va_list args;
6839	va_start(args, pszFormat);
6840	rc = pDevIns->pHlpR3->pfnDBGFStopV(pDevIns, RT_SRC_POS_ARGS, pszFormat, args);
6841	va_end(args);
6842	return rc;
6843	# else
6844	NOREF(pDevIns);
6845	NOREF(pszFile);
6846	NOREF(iLine);
6847	NOREF(pszFunction);
6848	NOREF(pszFormat);
6849	return VINF_EM_DBG_STOP;
6850	# endif
6851	#else
6852	NOREF(pDevIns);
6853	NOREF(pszFile);
6854	NOREF(iLine);
6855	NOREF(pszFunction);
6856	NOREF(pszFormat);
6857	return VINF_SUCCESS;
6858	#endif
6859	}
6860
6861	#ifdef IN_RING3
6862
6863	/**
6864	* @copydoc PDMDEVHLPR3::pfnDBGFInfoRegister
6865	*/
6866	DECLINLINE(int) PDMDevHlpDBGFInfoRegister(PPDMDEVINS pDevIns, const char pszName, const char pszDesc, PFNDBGFHANDLERDEV pfnHandler)
6867	{
6868	return pDevIns->pHlpR3->pfnDBGFInfoRegister(pDevIns, pszName, pszDesc, pfnHandler);
6869	}
6870
6871	/**
6872	* @copydoc PDMDEVHLPR3::pfnDBGFInfoRegisterArgv
6873	*/
6874	DECLINLINE(int) PDMDevHlpDBGFInfoRegisterArgv(PPDMDEVINS pDevIns, const char pszName, const char pszDesc, PFNDBGFINFOARGVDEV pfnHandler)
6875	{
6876	return pDevIns->pHlpR3->pfnDBGFInfoRegisterArgv(pDevIns, pszName, pszDesc, pfnHandler);
6877	}
6878
6879	/**
6880	* @copydoc PDMDEVHLPR3::pfnDBGFRegRegister
6881	*/
6882	DECLINLINE(int) PDMDevHlpDBGFRegRegister(PPDMDEVINS pDevIns, PCDBGFREGDESC paRegisters)
6883	{
6884	return pDevIns->pHlpR3->pfnDBGFRegRegister(pDevIns, paRegisters);
6885	}
6886
6887	/**
6888	* @copydoc PDMDEVHLPR3::pfnSTAMRegister
6889	*/
6890	DECLINLINE(void) PDMDevHlpSTAMRegister(PPDMDEVINS pDevIns, void pvSample, STAMTYPE enmType, const char pszName, STAMUNIT enmUnit, const char *pszDesc)
6891	{
6892	pDevIns->pHlpR3->pfnSTAMRegister(pDevIns, pvSample, enmType, pszName, enmUnit, pszDesc);
6893	}
6894
6895	/**
6896	* Same as pfnSTAMRegister except that the name is specified in a
6897	* RTStrPrintf like fashion.
6898	*
6899	* @returns VBox status.
6900	* @param pDevIns Device instance of the DMA.
6901	* @param pvSample Pointer to the sample.
6902	* @param enmType Sample type. This indicates what pvSample is
6903	* pointing at.
6904	* @param enmVisibility Visibility type specifying whether unused
6905	* statistics should be visible or not.
6906	* @param enmUnit Sample unit.
6907	* @param pszDesc Sample description.
6908	* @param pszName Sample name format string, unix path style. If
6909	* this does not start with a '/', the default
6910	* prefix will be prepended, otherwise it will be
6911	* used as-is.
6912	* @param ... Arguments to the format string.
6913	*/
6914	DECLINLINE(void) RT_IPRT_FORMAT_ATTR(7, 8) PDMDevHlpSTAMRegisterF(PPDMDEVINS pDevIns, void *pvSample, STAMTYPE enmType,
6915	STAMVISIBILITY enmVisibility, STAMUNIT enmUnit,
6916	const char pszDesc, const char pszName, ...)
6917	{
6918	va_list va;
6919	va_start(va, pszName);
6920	pDevIns->pHlpR3->pfnSTAMRegisterV(pDevIns, pvSample, enmType, enmVisibility, enmUnit, pszDesc, pszName, va);
6921	va_end(va);
6922	}
6923
6924	/**
6925	* @copydoc PDMDEVHLPR3::pfnSTAMDeregisterByPrefix
6926	*/
6927	DECLINLINE(int) PDMDevHlpSTAMDeregisterByPrefix(PPDMDEVINS pDevIns, const char *pszPrefix)
6928	{
6929	return pDevIns->pHlpR3->pfnSTAMDeregisterByPrefix(pDevIns, pszPrefix);
6930	}
6931
6932	/**
6933	* Registers the device with the default PCI bus.
6934	*
6935	* @returns VBox status code.
6936	* @param pDevIns The device instance.
6937	* @param pPciDev The PCI device structure.
6938	* This must be kept in the instance data.
6939	* The PCI configuration must be initialized before registration.
6940	*/
6941	DECLINLINE(int) PDMDevHlpPCIRegister(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev)
6942	{
6943	return pDevIns->pHlpR3->pfnPCIRegister(pDevIns, pPciDev, 0 /fFlags/,
6944	PDMPCIDEVREG_DEV_NO_FIRST_UNUSED, PDMPCIDEVREG_FUN_NO_FIRST_UNUSED, NULL);
6945	}
6946
6947	/**
6948	* @copydoc PDMDEVHLPR3::pfnPCIRegister
6949	*/
6950	DECLINLINE(int) PDMDevHlpPCIRegisterEx(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t fFlags,
6951	uint8_t uPciDevNo, uint8_t uPciFunNo, const char *pszName)
6952	{
6953	return pDevIns->pHlpR3->pfnPCIRegister(pDevIns, pPciDev, fFlags, uPciDevNo, uPciFunNo, pszName);
6954	}
6955
6956	/**
6957	* Initialize MSI emulation support for the first PCI device.
6958	*
6959	* @returns VBox status code.
6960	* @param pDevIns The device instance.
6961	* @param pMsiReg MSI emulation registration structure.
6962	*/
6963	DECLINLINE(int) PDMDevHlpPCIRegisterMsi(PPDMDEVINS pDevIns, PPDMMSIREG pMsiReg)
6964	{
6965	return pDevIns->pHlpR3->pfnPCIRegisterMsi(pDevIns, NULL, pMsiReg);
6966	}
6967
6968	/**
6969	* @copydoc PDMDEVHLPR3::pfnPCIRegisterMsi
6970	*/
6971	DECLINLINE(int) PDMDevHlpPCIRegisterMsiEx(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, PPDMMSIREG pMsiReg)
6972	{
6973	return pDevIns->pHlpR3->pfnPCIRegisterMsi(pDevIns, pPciDev, pMsiReg);
6974	}
6975
6976	/**
6977	* Registers a I/O port region for the default PCI device.
6978	*
6979	* @returns VBox status code.
6980	* @param pDevIns The device instance.
6981	* @param iRegion The region number.
6982	* @param cbRegion Size of the region.
6983	* @param hIoPorts Handle to the I/O port region.
6984	*/
6985	DECLINLINE(int) PDMDevHlpPCIIORegionRegisterIo(PPDMDEVINS pDevIns, uint32_t iRegion, RTGCPHYS cbRegion, IOMIOPORTHANDLE hIoPorts)
6986	{
6987	return pDevIns->pHlpR3->pfnPCIIORegionRegister(pDevIns, NULL, iRegion, cbRegion, PCI_ADDRESS_SPACE_IO,
6988	PDMPCIDEV_IORGN_F_IOPORT_HANDLE \| PDMPCIDEV_IORGN_F_NEW_STYLE, hIoPorts, NULL);
6989	}
6990
6991	/**
6992	* Registers a I/O port region for the default PCI device, custom map/unmap.
6993	*
6994	* @returns VBox status code.
6995	* @param pDevIns The device instance.
6996	* @param iRegion The region number.
6997	* @param cbRegion Size of the region.
6998	* @param pfnMapUnmap Callback for doing the mapping, optional. The
6999	* callback will be invoked holding only the PDM lock.
7000	* The device lock will _not_ be taken (due to lock
7001	* order).
7002	*/
7003	DECLINLINE(int) PDMDevHlpPCIIORegionRegisterIoCustom(PPDMDEVINS pDevIns, uint32_t iRegion, RTGCPHYS cbRegion,
7004	PFNPCIIOREGIONMAP pfnMapUnmap)
7005	{
7006	return pDevIns->pHlpR3->pfnPCIIORegionRegister(pDevIns, NULL, iRegion, cbRegion, PCI_ADDRESS_SPACE_IO,
7007	PDMPCIDEV_IORGN_F_NO_HANDLE \| PDMPCIDEV_IORGN_F_NEW_STYLE,
7008	UINT64_MAX, pfnMapUnmap);
7009	}
7010
7011	/**
7012	* Combines PDMDevHlpIoPortCreate and PDMDevHlpPCIIORegionRegisterIo, creating
7013	* and registering an I/O port region for the default PCI device.
7014	*
7015	* @returns VBox status code.
7016	* @param pDevIns The device instance to register the ports with.
7017	* @param cPorts The count of I/O ports in the region (the size).
7018	* @param iPciRegion The PCI device region.
7019	* @param pfnOut Pointer to function which is gonna handle OUT
7020	* operations. Optional.
7021	* @param pfnIn Pointer to function which is gonna handle IN operations.
7022	* Optional.
7023	* @param pvUser User argument to pass to the callbacks.
7024	* @param pszDesc Pointer to description string. This must not be freed.
7025	* @param paExtDescs Extended per-port descriptions, optional. Partial range
7026	* coverage is allowed. This must not be freed.
7027	* @param phIoPorts Where to return the I/O port range handle.
7028	*
7029	*/
7030	DECLINLINE(int) PDMDevHlpPCIIORegionCreateIo(PPDMDEVINS pDevIns, uint32_t iPciRegion, RTIOPORT cPorts,
7031	PFNIOMIOPORTNEWOUT pfnOut, PFNIOMIOPORTNEWIN pfnIn, void *pvUser,
7032	const char *pszDesc, PCIOMIOPORTDESC paExtDescs, PIOMIOPORTHANDLE phIoPorts)
7033
7034	{
7035	int rc = pDevIns->pHlpR3->pfnIoPortCreateEx(pDevIns, cPorts, 0 /fFlags/, pDevIns->apPciDevs[0], iPciRegion << 16,
7036	pfnOut, pfnIn, NULL, NULL, pvUser, pszDesc, paExtDescs, phIoPorts);
7037	if (RT_SUCCESS(rc))
7038	rc = pDevIns->pHlpR3->pfnPCIIORegionRegister(pDevIns, pDevIns->apPciDevs[0], iPciRegion, cPorts, PCI_ADDRESS_SPACE_IO,
7039	PDMPCIDEV_IORGN_F_IOPORT_HANDLE \| PDMPCIDEV_IORGN_F_NEW_STYLE,
7040	phIoPorts, NULL /pfnMapUnmap*/);
7041	return rc;
7042	}
7043
7044	/**
7045	* Registers an MMIO region for the default PCI device.
7046	*
7047	* @returns VBox status code.
7048	* @param pDevIns The device instance.
7049	* @param iRegion The region number.
7050	* @param cbRegion Size of the region.
7051	* @param enmType PCI_ADDRESS_SPACE_MEM or
7052	* PCI_ADDRESS_SPACE_MEM_PREFETCH, optionally or-ing in
7053	* PCI_ADDRESS_SPACE_BAR64 or PCI_ADDRESS_SPACE_BAR32.
7054	* @param hMmioRegion Handle to the MMIO region.
7055	* @param pfnMapUnmap Callback for doing the mapping, optional. The
7056	* callback will be invoked holding only the PDM lock.
7057	* The device lock will _not_ be taken (due to lock
7058	* order).
7059	*/
7060	DECLINLINE(int) PDMDevHlpPCIIORegionRegisterMmio(PPDMDEVINS pDevIns, uint32_t iRegion, RTGCPHYS cbRegion, PCIADDRESSSPACE enmType,
7061	IOMMMIOHANDLE hMmioRegion, PFNPCIIOREGIONMAP pfnMapUnmap)
7062	{
7063	return pDevIns->pHlpR3->pfnPCIIORegionRegister(pDevIns, NULL, iRegion, cbRegion, enmType,
7064	PDMPCIDEV_IORGN_F_MMIO_HANDLE \| PDMPCIDEV_IORGN_F_NEW_STYLE,
7065	hMmioRegion, pfnMapUnmap);
7066	}
7067
7068	/**
7069	* Registers an MMIO region for the default PCI device, extended version.
7070	*
7071	* @returns VBox status code.
7072	* @param pDevIns The device instance.
7073	* @param pPciDev The PCI device structure.
7074	* @param iRegion The region number.
7075	* @param cbRegion Size of the region.
7076	* @param enmType PCI_ADDRESS_SPACE_MEM or
7077	* PCI_ADDRESS_SPACE_MEM_PREFETCH, optionally or-ing in
7078	* PCI_ADDRESS_SPACE_BAR64 or PCI_ADDRESS_SPACE_BAR32.
7079	* @param hMmioRegion Handle to the MMIO region.
7080	* @param pfnMapUnmap Callback for doing the mapping, optional. The
7081	* callback will be invoked holding only the PDM lock.
7082	* The device lock will _not_ be taken (due to lock
7083	* order).
7084	*/
7085	DECLINLINE(int) PDMDevHlpPCIIORegionRegisterMmioEx(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t iRegion,
7086	RTGCPHYS cbRegion, PCIADDRESSSPACE enmType, IOMMMIOHANDLE hMmioRegion,
7087	PFNPCIIOREGIONMAP pfnMapUnmap)
7088	{
7089	return pDevIns->pHlpR3->pfnPCIIORegionRegister(pDevIns, pPciDev, iRegion, cbRegion, enmType,
7090	PDMPCIDEV_IORGN_F_MMIO_HANDLE \| PDMPCIDEV_IORGN_F_NEW_STYLE,
7091	hMmioRegion, pfnMapUnmap);
7092	}
7093
7094	/**
7095	* Combines PDMDevHlpMmioCreate and PDMDevHlpPCIIORegionRegisterMmio, creating
7096	* and registering an MMIO region for the default PCI device.
7097	*
7098	* @returns VBox status code.
7099	* @param pDevIns The device instance to register the ports with.
7100	* @param cbRegion The size of the region in bytes.
7101	* @param iPciRegion The PCI device region.
7102	* @param enmType PCI_ADDRESS_SPACE_MEM or
7103	* PCI_ADDRESS_SPACE_MEM_PREFETCH, optionally or-ing in
7104	* PCI_ADDRESS_SPACE_BAR64 or PCI_ADDRESS_SPACE_BAR32.
7105	* @param fFlags Flags, IOMMMIO_FLAGS_XXX.
7106	* @param pfnWrite Pointer to function which is gonna handle Write
7107	* operations.
7108	* @param pfnRead Pointer to function which is gonna handle Read
7109	* operations.
7110	* @param pvUser User argument to pass to the callbacks.
7111	* @param pszDesc Pointer to description string. This must not be freed.
7112	* @param phRegion Where to return the MMIO region handle.
7113	*
7114	*/
7115	DECLINLINE(int) PDMDevHlpPCIIORegionCreateMmio(PPDMDEVINS pDevIns, uint32_t iPciRegion, RTGCPHYS cbRegion, PCIADDRESSSPACE enmType,
7116	PFNIOMMMIONEWWRITE pfnWrite, PFNIOMMMIONEWREAD pfnRead, void *pvUser,
7117	uint32_t fFlags, const char *pszDesc, PIOMMMIOHANDLE phRegion)
7118
7119	{
7120	int rc = pDevIns->pHlpR3->pfnMmioCreateEx(pDevIns, cbRegion, fFlags, pDevIns->apPciDevs[0], iPciRegion << 16,
7121	pfnWrite, pfnRead, NULL /pfnFill/, pvUser, pszDesc, phRegion);
7122	if (RT_SUCCESS(rc))
7123	rc = pDevIns->pHlpR3->pfnPCIIORegionRegister(pDevIns, pDevIns->apPciDevs[0], iPciRegion, cbRegion, enmType,
7124	PDMPCIDEV_IORGN_F_MMIO_HANDLE \| PDMPCIDEV_IORGN_F_NEW_STYLE,
7125	phRegion, NULL /pfnMapUnmap*/);
7126	return rc;
7127	}
7128
7129
7130	/**
7131	* Registers an MMIO2 region for the default PCI device.
7132	*
7133	* @returns VBox status code.
7134	* @param pDevIns The device instance.
7135	* @param iRegion The region number.
7136	* @param cbRegion Size of the region.
7137	* @param enmType PCI_ADDRESS_SPACE_MEM or
7138	* PCI_ADDRESS_SPACE_MEM_PREFETCH, optionally or-ing in
7139	* PCI_ADDRESS_SPACE_BAR64 or PCI_ADDRESS_SPACE_BAR32.
7140	* @param hMmio2Region Handle to the MMIO2 region.
7141	*/
7142	DECLINLINE(int) PDMDevHlpPCIIORegionRegisterMmio2(PPDMDEVINS pDevIns, uint32_t iRegion, RTGCPHYS cbRegion,
7143	PCIADDRESSSPACE enmType, PGMMMIO2HANDLE hMmio2Region)
7144	{
7145	return pDevIns->pHlpR3->pfnPCIIORegionRegister(pDevIns, NULL, iRegion, cbRegion, enmType,
7146	PDMPCIDEV_IORGN_F_MMIO2_HANDLE \| PDMPCIDEV_IORGN_F_NEW_STYLE,
7147	hMmio2Region, NULL);
7148	}
7149
7150	/**
7151	* Combines PDMDevHlpMmio2Create and PDMDevHlpPCIIORegionRegisterMmio2, creating
7152	* and registering an MMIO2 region for the default PCI device, extended edition.
7153	*
7154	* @returns VBox status code.
7155	* @param pDevIns The device instance to register the ports with.
7156	* @param cbRegion The size of the region in bytes.
7157	* @param iPciRegion The PCI device region.
7158	* @param enmType PCI_ADDRESS_SPACE_MEM or
7159	* PCI_ADDRESS_SPACE_MEM_PREFETCH, optionally or-ing in
7160	* PCI_ADDRESS_SPACE_BAR64 or PCI_ADDRESS_SPACE_BAR32.
7161	* @param pszDesc Pointer to description string. This must not be freed.
7162	* @param ppvMapping Where to store the address of the ring-3 mapping of
7163	* the memory.
7164	* @param phRegion Where to return the MMIO2 region handle.
7165	*
7166	*/
7167	DECLINLINE(int) PDMDevHlpPCIIORegionCreateMmio2(PPDMDEVINS pDevIns, uint32_t iPciRegion, RTGCPHYS cbRegion,
7168	PCIADDRESSSPACE enmType, const char *pszDesc,
7169	void **ppvMapping, PPGMMMIO2HANDLE phRegion)
7170
7171	{
7172	int rc = pDevIns->pHlpR3->pfnMmio2Create(pDevIns, pDevIns->apPciDevs[0], iPciRegion << 16, cbRegion, 0 /fFlags/,
7173	pszDesc, ppvMapping, phRegion);
7174	if (RT_SUCCESS(rc))
7175	rc = pDevIns->pHlpR3->pfnPCIIORegionRegister(pDevIns, pDevIns->apPciDevs[0], iPciRegion, cbRegion, enmType,
7176	PDMPCIDEV_IORGN_F_MMIO2_HANDLE \| PDMPCIDEV_IORGN_F_NEW_STYLE,
7177	phRegion, NULL /pfnCallback*/);
7178	return rc;
7179	}
7180
7181	/**
7182	* Combines PDMDevHlpMmio2Create and PDMDevHlpPCIIORegionRegisterMmio2, creating
7183	* and registering an MMIO2 region for the default PCI device.
7184	*
7185	* @returns VBox status code.
7186	* @param pDevIns The device instance to register the ports with.
7187	* @param cbRegion The size of the region in bytes.
7188	* @param iPciRegion The PCI device region.
7189	* @param enmType PCI_ADDRESS_SPACE_MEM or
7190	* PCI_ADDRESS_SPACE_MEM_PREFETCH, optionally or-ing in
7191	* PCI_ADDRESS_SPACE_BAR64 or PCI_ADDRESS_SPACE_BAR32.
7192	* @param fMmio2Flags To be defined, must be zero.
7193	* @param pfnMapUnmap Callback for doing the mapping, optional. The
7194	* callback will be invoked holding only the PDM lock.
7195	* The device lock will _not_ be taken (due to lock
7196	* order).
7197	* @param pszDesc Pointer to description string. This must not be freed.
7198	* @param ppvMapping Where to store the address of the ring-3 mapping of
7199	* the memory.
7200	* @param phRegion Where to return the MMIO2 region handle.
7201	*
7202	*/
7203	DECLINLINE(int) PDMDevHlpPCIIORegionCreateMmio2Ex(PPDMDEVINS pDevIns, uint32_t iPciRegion, RTGCPHYS cbRegion,
7204	PCIADDRESSSPACE enmType, uint32_t fMmio2Flags, PFNPCIIOREGIONMAP pfnMapUnmap,
7205	const char pszDesc, void *ppvMapping, PPGMMMIO2HANDLE phRegion)
7206
7207	{
7208	int rc = pDevIns->pHlpR3->pfnMmio2Create(pDevIns, pDevIns->apPciDevs[0], iPciRegion << 16, cbRegion, fMmio2Flags,
7209	pszDesc, ppvMapping, phRegion);
7210	if (RT_SUCCESS(rc))
7211	rc = pDevIns->pHlpR3->pfnPCIIORegionRegister(pDevIns, pDevIns->apPciDevs[0], iPciRegion, cbRegion, enmType,
7212	PDMPCIDEV_IORGN_F_MMIO2_HANDLE \| PDMPCIDEV_IORGN_F_NEW_STYLE,
7213	*phRegion, pfnMapUnmap);
7214	return rc;
7215	}
7216
7217	/**
7218	* @copydoc PDMDEVHLPR3::pfnPCIInterceptConfigAccesses
7219	*/
7220	DECLINLINE(int) PDMDevHlpPCIInterceptConfigAccesses(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev,
7221	PFNPCICONFIGREAD pfnRead, PFNPCICONFIGWRITE pfnWrite)
7222	{
7223	return pDevIns->pHlpR3->pfnPCIInterceptConfigAccesses(pDevIns, pPciDev, pfnRead, pfnWrite);
7224	}
7225
7226	/**
7227	* @copydoc PDMDEVHLPR3::pfnPCIConfigRead
7228	*/
7229	DECLINLINE(VBOXSTRICTRC) PDMDevHlpPCIConfigRead(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t uAddress,
7230	unsigned cb, uint32_t *pu32Value)
7231	{
7232	return pDevIns->pHlpR3->pfnPCIConfigRead(pDevIns, pPciDev, uAddress, cb, pu32Value);
7233	}
7234
7235	/**
7236	* @copydoc PDMDEVHLPR3::pfnPCIConfigWrite
7237	*/
7238	DECLINLINE(VBOXSTRICTRC) PDMDevHlpPCIConfigWrite(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t uAddress,
7239	unsigned cb, uint32_t u32Value)
7240	{
7241	return pDevIns->pHlpR3->pfnPCIConfigWrite(pDevIns, pPciDev, uAddress, cb, u32Value);
7242	}
7243
7244	#endif /* IN_RING3 */
7245
7246	/**
7247	* Bus master physical memory read from the default PCI device.
7248	*
7249	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_READ_BM_DISABLED, later maybe
7250	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
7251	* @param pDevIns The device instance.
7252	* @param GCPhys Physical address start reading from.
7253	* @param pvBuf Where to put the read bits.
7254	* @param cbRead How many bytes to read.
7255	* @thread Any thread, but the call may involve the emulation thread.
7256	*/
7257	DECLINLINE(int) PDMDevHlpPCIPhysRead(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead)
7258	{
7259	return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysRead(pDevIns, NULL, GCPhys, pvBuf, cbRead, PDM_DEVHLP_PHYS_RW_F_DEFAULT);
7260	}
7261
7262	/**
7263	* Bus master physical memory read - unknown data usage.
7264	*
7265	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_READ_BM_DISABLED, later maybe
7266	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
7267	* @param pDevIns The device instance.
7268	* @param pPciDev The PCI device structure. If NULL the default
7269	* PCI device for this device instance is used.
7270	* @param GCPhys Physical address start reading from.
7271	* @param pvBuf Where to put the read bits.
7272	* @param cbRead How many bytes to read.
7273	* @thread Any thread, but the call may involve the emulation thread.
7274	*/
7275	DECLINLINE(int) PDMDevHlpPCIPhysReadEx(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead)
7276	{
7277	return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysRead(pDevIns, pPciDev, GCPhys, pvBuf, cbRead, PDM_DEVHLP_PHYS_RW_F_DEFAULT);
7278	}
7279
7280	/**
7281	* Bus master physical memory read from the default PCI device.
7282	*
7283	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_READ_BM_DISABLED, later maybe
7284	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
7285	* @param pDevIns The device instance.
7286	* @param GCPhys Physical address start reading from.
7287	* @param pvBuf Where to put the read bits.
7288	* @param cbRead How many bytes to read.
7289	* @thread Any thread, but the call may involve the emulation thread.
7290	*/
7291	DECLINLINE(int) PDMDevHlpPCIPhysReadMeta(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead)
7292	{
7293	return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysRead(pDevIns, NULL, GCPhys, pvBuf, cbRead, PDM_DEVHLP_PHYS_RW_F_DATA_META);
7294	}
7295
7296	/**
7297	* Bus master physical memory read - reads meta data processed by the device.
7298	*
7299	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_READ_BM_DISABLED, later maybe
7300	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
7301	* @param pDevIns The device instance.
7302	* @param pPciDev The PCI device structure. If NULL the default
7303	* PCI device for this device instance is used.
7304	* @param GCPhys Physical address start reading from.
7305	* @param pvBuf Where to put the read bits.
7306	* @param cbRead How many bytes to read.
7307	* @thread Any thread, but the call may involve the emulation thread.
7308	*/
7309	DECLINLINE(int) PDMDevHlpPCIPhysReadMetaEx(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead)
7310	{
7311	return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysRead(pDevIns, pPciDev, GCPhys, pvBuf, cbRead, PDM_DEVHLP_PHYS_RW_F_DATA_META);
7312	}
7313
7314	/**
7315	* Bus master physical memory read from the default PCI device - read data will not be touched by the device.
7316	*
7317	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_READ_BM_DISABLED, later maybe
7318	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
7319	* @param pDevIns The device instance.
7320	* @param GCPhys Physical address start reading from.
7321	* @param pvBuf Where to put the read bits.
7322	* @param cbRead How many bytes to read.
7323	* @thread Any thread, but the call may involve the emulation thread.
7324	*/
7325	DECLINLINE(int) PDMDevHlpPCIPhysReadUser(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead)
7326	{
7327	return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysRead(pDevIns, NULL, GCPhys, pvBuf, cbRead, PDM_DEVHLP_PHYS_RW_F_DATA_USER);
7328	}
7329
7330	/**
7331	* Bus master physical memory read - read data will not be touched by the device.
7332	*
7333	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_READ_BM_DISABLED, later maybe
7334	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
7335	* @param pDevIns The device instance.
7336	* @param pPciDev The PCI device structure. If NULL the default
7337	* PCI device for this device instance is used.
7338	* @param GCPhys Physical address start reading from.
7339	* @param pvBuf Where to put the read bits.
7340	* @param cbRead How many bytes to read.
7341	* @thread Any thread, but the call may involve the emulation thread.
7342	*/
7343	DECLINLINE(int) PDMDevHlpPCIPhysReadUserEx(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead)
7344	{
7345	return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysRead(pDevIns, pPciDev, GCPhys, pvBuf, cbRead, PDM_DEVHLP_PHYS_RW_F_DATA_USER);
7346	}
7347
7348	/**
7349	* Bus master physical memory write from the default PCI device - unknown data usage.
7350	*
7351	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_WRITE_BM_DISABLED, later maybe
7352	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
7353	* @param pDevIns The device instance.
7354	* @param GCPhys Physical address to write to.
7355	* @param pvBuf What to write.
7356	* @param cbWrite How many bytes to write.
7357	* @thread Any thread, but the call may involve the emulation thread.
7358	*/
7359	DECLINLINE(int) PDMDevHlpPCIPhysWrite(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite)
7360	{
7361	return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysWrite(pDevIns, NULL, GCPhys, pvBuf, cbWrite, PDM_DEVHLP_PHYS_RW_F_DEFAULT);
7362	}
7363
7364	/**
7365	* Bus master physical memory write - unknown data usage.
7366	*
7367	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_WRITE_BM_DISABLED, later maybe
7368	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
7369	* @param pDevIns The device instance.
7370	* @param pPciDev The PCI device structure. If NULL the default
7371	* PCI device for this device instance is used.
7372	* @param GCPhys Physical address to write to.
7373	* @param pvBuf What to write.
7374	* @param cbWrite How many bytes to write.
7375	* @thread Any thread, but the call may involve the emulation thread.
7376	*/
7377	DECLINLINE(int) PDMDevHlpPCIPhysWriteEx(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite)
7378	{
7379	return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysWrite(pDevIns, pPciDev, GCPhys, pvBuf, cbWrite, PDM_DEVHLP_PHYS_RW_F_DEFAULT);
7380	}
7381
7382	/**
7383	* Bus master physical memory write from the default PCI device.
7384	*
7385	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_WRITE_BM_DISABLED, later maybe
7386	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
7387	* @param pDevIns The device instance.
7388	* @param GCPhys Physical address to write to.
7389	* @param pvBuf What to write.
7390	* @param cbWrite How many bytes to write.
7391	* @thread Any thread, but the call may involve the emulation thread.
7392	*/
7393	DECLINLINE(int) PDMDevHlpPCIPhysWriteMeta(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite)
7394	{
7395	return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysWrite(pDevIns, NULL, GCPhys, pvBuf, cbWrite, PDM_DEVHLP_PHYS_RW_F_DATA_META);
7396	}
7397
7398	/**
7399	* Bus master physical memory write - written data was created/altered by the device.
7400	*
7401	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_WRITE_BM_DISABLED, later maybe
7402	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
7403	* @param pDevIns The device instance.
7404	* @param pPciDev The PCI device structure. If NULL the default
7405	* PCI device for this device instance is used.
7406	* @param GCPhys Physical address to write to.
7407	* @param pvBuf What to write.
7408	* @param cbWrite How many bytes to write.
7409	* @thread Any thread, but the call may involve the emulation thread.
7410	*/
7411	DECLINLINE(int) PDMDevHlpPCIPhysWriteMetaEx(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite)
7412	{
7413	return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysWrite(pDevIns, pPciDev, GCPhys, pvBuf, cbWrite, PDM_DEVHLP_PHYS_RW_F_DATA_META);
7414	}
7415
7416	/**
7417	* Bus master physical memory write from the default PCI device.
7418	*
7419	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_WRITE_BM_DISABLED, later maybe
7420	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
7421	* @param pDevIns The device instance.
7422	* @param GCPhys Physical address to write to.
7423	* @param pvBuf What to write.
7424	* @param cbWrite How many bytes to write.
7425	* @thread Any thread, but the call may involve the emulation thread.
7426	*/
7427	DECLINLINE(int) PDMDevHlpPCIPhysWriteUser(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite)
7428	{
7429	return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysWrite(pDevIns, NULL, GCPhys, pvBuf, cbWrite, PDM_DEVHLP_PHYS_RW_F_DATA_USER);
7430	}
7431
7432	/**
7433	* Bus master physical memory write - written data was not touched/created by the device.
7434	*
7435	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_WRITE_BM_DISABLED, later maybe
7436	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
7437	* @param pDevIns The device instance.
7438	* @param pPciDev The PCI device structure. If NULL the default
7439	* PCI device for this device instance is used.
7440	* @param GCPhys Physical address to write to.
7441	* @param pvBuf What to write.
7442	* @param cbWrite How many bytes to write.
7443	* @thread Any thread, but the call may involve the emulation thread.
7444	*/
7445	DECLINLINE(int) PDMDevHlpPCIPhysWriteUserEx(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite)
7446	{
7447	return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysWrite(pDevIns, pPciDev, GCPhys, pvBuf, cbWrite, PDM_DEVHLP_PHYS_RW_F_DATA_USER);
7448	}
7449
7450	#ifdef IN_RING3
7451	/**
7452	* @copydoc PDMDEVHLPR3::pfnPCIPhysGCPhys2CCPtr
7453	*/
7454	DECLINLINE(int) PDMDevHlpPCIPhysGCPhys2CCPtr(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys, uint32_t fFlags,
7455	void **ppv, PPGMPAGEMAPLOCK pLock)
7456	{
7457	return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysGCPhys2CCPtr(pDevIns, pPciDev, GCPhys, fFlags, ppv, pLock);
7458	}
7459
7460	/**
7461	* @copydoc PDMDEVHLPR3::pfnPCIPhysGCPhys2CCPtrReadOnly
7462	*/
7463	DECLINLINE(int) PDMDevHlpPCIPhysGCPhys2CCPtrReadOnly(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, RTGCPHYS GCPhys, uint32_t fFlags,
7464	void const **ppv, PPGMPAGEMAPLOCK pLock)
7465	{
7466	return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysGCPhys2CCPtrReadOnly(pDevIns, pPciDev, GCPhys, fFlags, ppv, pLock);
7467	}
7468
7469	/**
7470	* @copydoc PDMDEVHLPR3::pfnPCIPhysBulkGCPhys2CCPtr
7471	*/
7472	DECLINLINE(int) PDMDevHlpPCIPhysBulkGCPhys2CCPtr(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t cPages,
7473	PCRTGCPHYS paGCPhysPages, uint32_t fFlags, void **papvPages,
7474	PPGMPAGEMAPLOCK paLocks)
7475	{
7476	return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysBulkGCPhys2CCPtr(pDevIns, pPciDev, cPages, paGCPhysPages, fFlags, papvPages,
7477	paLocks);
7478	}
7479
7480	/**
7481	* @copydoc PDMDEVHLPR3::pfnPCIPhysBulkGCPhys2CCPtrReadOnly
7482	*/
7483	DECLINLINE(int) PDMDevHlpPCIPhysBulkGCPhys2CCPtrReadOnly(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, uint32_t cPages,
7484	PCRTGCPHYS paGCPhysPages, uint32_t fFlags, void const **papvPages,
7485	PPGMPAGEMAPLOCK paLocks)
7486	{
7487	return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysBulkGCPhys2CCPtrReadOnly(pDevIns, pPciDev, cPages, paGCPhysPages, fFlags,
7488	papvPages, paLocks);
7489	}
7490	#endif /* IN_RING3 */
7491
7492	/**
7493	* Sets the IRQ for the default PCI device.
7494	*
7495	* @param pDevIns The device instance.
7496	* @param iIrq IRQ number to set.
7497	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
7498	* @thread Any thread, but will involve the emulation thread.
7499	*/
7500	DECLINLINE(void) PDMDevHlpPCISetIrq(PPDMDEVINS pDevIns, int iIrq, int iLevel)
7501	{
7502	pDevIns->CTX_SUFF(pHlp)->pfnPCISetIrq(pDevIns, NULL, iIrq, iLevel);
7503	}
7504
7505	/**
7506	* @copydoc PDMDEVHLPR3::pfnPCISetIrq
7507	*/
7508	DECLINLINE(void) PDMDevHlpPCISetIrqEx(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, int iIrq, int iLevel)
7509	{
7510	pDevIns->CTX_SUFF(pHlp)->pfnPCISetIrq(pDevIns, pPciDev, iIrq, iLevel);
7511	}
7512
7513	/**
7514	* Sets the IRQ for the given PCI device, but doesn't wait for EMT to process
7515	* the request when not called from EMT.
7516	*
7517	* @param pDevIns The device instance.
7518	* @param iIrq IRQ number to set.
7519	* @param iLevel IRQ level.
7520	* @thread Any thread, but will involve the emulation thread.
7521	*/
7522	DECLINLINE(void) PDMDevHlpPCISetIrqNoWait(PPDMDEVINS pDevIns, int iIrq, int iLevel)
7523	{
7524	pDevIns->CTX_SUFF(pHlp)->pfnPCISetIrq(pDevIns, NULL, iIrq, iLevel);
7525	}
7526
7527	/**
7528	* @copydoc PDMDEVHLPR3::pfnPCISetIrqNoWait
7529	*/
7530	DECLINLINE(void) PDMDevHlpPCISetIrqNoWaitEx(PPDMDEVINS pDevIns, PPDMPCIDEV pPciDev, int iIrq, int iLevel)
7531	{
7532	pDevIns->CTX_SUFF(pHlp)->pfnPCISetIrq(pDevIns, pPciDev, iIrq, iLevel);
7533	}
7534
7535	/**
7536	* @copydoc PDMDEVHLPR3::pfnISASetIrq
7537	*/
7538	DECLINLINE(void) PDMDevHlpISASetIrq(PPDMDEVINS pDevIns, int iIrq, int iLevel)
7539	{
7540	pDevIns->CTX_SUFF(pHlp)->pfnISASetIrq(pDevIns, iIrq, iLevel);
7541	}
7542
7543	/**
7544	* @copydoc PDMDEVHLPR3::pfnISASetIrqNoWait
7545	*/
7546	DECLINLINE(void) PDMDevHlpISASetIrqNoWait(PPDMDEVINS pDevIns, int iIrq, int iLevel)
7547	{
7548	pDevIns->CTX_SUFF(pHlp)->pfnISASetIrq(pDevIns, iIrq, iLevel);
7549	}
7550
7551	#ifdef IN_RING3
7552
7553	/**
7554	* @copydoc PDMDEVHLPR3::pfnDriverAttach
7555	*/
7556	DECLINLINE(int) PDMDevHlpDriverAttach(PPDMDEVINS pDevIns, uint32_t iLun, PPDMIBASE pBaseInterface, PPDMIBASE ppBaseInterface, const char pszDesc)
7557	{
7558	return pDevIns->pHlpR3->pfnDriverAttach(pDevIns, iLun, pBaseInterface, ppBaseInterface, pszDesc);
7559	}
7560
7561	/**
7562	* @copydoc PDMDEVHLPR3::pfnDriverDetach
7563	*/
7564	DECLINLINE(int) PDMDevHlpDriverDetach(PPDMDEVINS pDevIns, PPDMDRVINS pDrvIns, uint32_t fFlags)
7565	{
7566	return pDevIns->pHlpR3->pfnDriverDetach(pDevIns, pDrvIns, fFlags);
7567	}
7568
7569	/**
7570	* @copydoc PDMDEVHLPR3::pfnDriverReconfigure
7571	*/
7572	DECLINLINE(int) PDMDevHlpDriverReconfigure(PPDMDEVINS pDevIns, uint32_t iLun, uint32_t cDepth,
7573	const char * const papszDrivers, PCFGMNODE papConfigs, uint32_t fFlags)
7574	{
7575	return pDevIns->pHlpR3->pfnDriverReconfigure(pDevIns, iLun, cDepth, papszDrivers, papConfigs, fFlags);
7576	}
7577
7578	/**
7579	* Reconfigures with a single driver reattachement, no config, noflags.
7580	* @sa PDMDevHlpDriverReconfigure
7581	*/
7582	DECLINLINE(int) PDMDevHlpDriverReconfigure1(PPDMDEVINS pDevIns, uint32_t iLun, const char *pszDriver0)
7583	{
7584	return pDevIns->pHlpR3->pfnDriverReconfigure(pDevIns, iLun, 1, &pszDriver0, NULL, 0);
7585	}
7586
7587	/**
7588	* Reconfigures with a two drivers reattachement, no config, noflags.
7589	* @sa PDMDevHlpDriverReconfigure
7590	*/
7591	DECLINLINE(int) PDMDevHlpDriverReconfigure2(PPDMDEVINS pDevIns, uint32_t iLun, const char pszDriver0, const char pszDriver1)
7592	{
7593	char const * apszDrivers[2];
7594	apszDrivers[0] = pszDriver0;
7595	apszDrivers[1] = pszDriver1;
7596	return pDevIns->pHlpR3->pfnDriverReconfigure(pDevIns, iLun, 2, apszDrivers, NULL, 0);
7597	}
7598
7599	/**
7600	* @copydoc PDMDEVHLPR3::pfnQueueCreatePtr
7601	*/
7602	DECLINLINE(int) PDMDevHlpQueueCreate(PPDMDEVINS pDevIns, size_t cbItem, uint32_t cItems, uint32_t cMilliesInterval,
7603	PFNPDMQUEUEDEV pfnCallback, bool fRZEnabled, const char pszName, PPDMQUEUE ppQueue)
7604	{
7605	return pDevIns->pHlpR3->pfnQueueCreatePtr(pDevIns, cbItem, cItems, cMilliesInterval, pfnCallback, fRZEnabled, pszName, ppQueue);
7606	}
7607
7608	/**
7609	* @copydoc PDMDEVHLPR3::pfnQueueCreate
7610	*/
7611	DECLINLINE(int) PDMDevHlpQueueCreateNew(PPDMDEVINS pDevIns, size_t cbItem, uint32_t cItems, uint32_t cMilliesInterval,
7612	PFNPDMQUEUEDEV pfnCallback, bool fRZEnabled, const char pszName, PDMQUEUEHANDLE phQueue)
7613	{
7614	return pDevIns->pHlpR3->pfnQueueCreate(pDevIns, cbItem, cItems, cMilliesInterval, pfnCallback, fRZEnabled, pszName, phQueue);
7615	}
7616
7617	#endif /* IN_RING3 */
7618
7619	/**
7620	* @copydoc PDMDEVHLPR3::pfnQueueAlloc
7621	*/
7622	DECLINLINE(PPDMQUEUEITEMCORE) PDMDevHlpQueueAlloc(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue)
7623	{
7624	return pDevIns->CTX_SUFF(pHlp)->pfnQueueAlloc(pDevIns, hQueue);
7625	}
7626
7627	/**
7628	* @copydoc PDMDEVHLPR3::pfnQueueInsert
7629	*/
7630	DECLINLINE(void) PDMDevHlpQueueInsert(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue, PPDMQUEUEITEMCORE pItem)
7631	{
7632	pDevIns->CTX_SUFF(pHlp)->pfnQueueInsert(pDevIns, hQueue, pItem);
7633	}
7634
7635	/**
7636	* @copydoc PDMDEVHLPR3::pfnQueueInsertEx
7637	*/
7638	DECLINLINE(void) PDMDevHlpQueueInsertEx(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue, PPDMQUEUEITEMCORE pItem, uint64_t cNanoMaxDelay)
7639	{
7640	pDevIns->CTX_SUFF(pHlp)->pfnQueueInsertEx(pDevIns, hQueue, pItem, cNanoMaxDelay);
7641	}
7642
7643	/**
7644	* @copydoc PDMDEVHLPR3::pfnQueueFlushIfNecessary
7645	*/
7646	DECLINLINE(bool) PDMDevHlpQueueFlushIfNecessary(PPDMDEVINS pDevIns, PDMQUEUEHANDLE hQueue)
7647	{
7648	return pDevIns->CTX_SUFF(pHlp)->pfnQueueFlushIfNecessary(pDevIns, hQueue);
7649	}
7650
7651	#ifdef IN_RING3
7652	/**
7653	* @copydoc PDMDEVHLPR3::pfnTaskCreate
7654	*/
7655	DECLINLINE(int) PDMDevHlpTaskCreate(PPDMDEVINS pDevIns, uint32_t fFlags, const char *pszName,
7656	PFNPDMTASKDEV pfnCallback, void pvUser, PDMTASKHANDLE phTask)
7657	{
7658	return pDevIns->pHlpR3->pfnTaskCreate(pDevIns, fFlags, pszName, pfnCallback, pvUser, phTask);
7659	}
7660	#endif
7661
7662	/**
7663	* @copydoc PDMDEVHLPR3::pfnTaskTrigger
7664	*/
7665	DECLINLINE(int) PDMDevHlpTaskTrigger(PPDMDEVINS pDevIns, PDMTASKHANDLE hTask)
7666	{
7667	return pDevIns->CTX_SUFF(pHlp)->pfnTaskTrigger(pDevIns, hTask);
7668	}
7669
7670	#ifdef IN_RING3
7671
7672	/**
7673	* @copydoc PDMDEVHLPR3::pfnSUPSemEventCreate
7674	*/
7675	DECLINLINE(int) PDMDevHlpSUPSemEventCreate(PPDMDEVINS pDevIns, PSUPSEMEVENT phEvent)
7676	{
7677	return pDevIns->pHlpR3->pfnSUPSemEventCreate(pDevIns, phEvent);
7678	}
7679
7680	/**
7681	* @copydoc PDMDEVHLPR3::pfnSUPSemEventClose
7682	*/
7683	DECLINLINE(int) PDMDevHlpSUPSemEventClose(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent)
7684	{
7685	return pDevIns->pHlpR3->pfnSUPSemEventClose(pDevIns, hEvent);
7686	}
7687
7688	#endif /* IN_RING3 */
7689
7690	/**
7691	* @copydoc PDMDEVHLPR3::pfnSUPSemEventSignal
7692	*/
7693	DECLINLINE(int) PDMDevHlpSUPSemEventSignal(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent)
7694	{
7695	return pDevIns->CTX_SUFF(pHlp)->pfnSUPSemEventSignal(pDevIns, hEvent);
7696	}
7697
7698	/**
7699	* @copydoc PDMDEVHLPR3::pfnSUPSemEventWaitNoResume
7700	*/
7701	DECLINLINE(int) PDMDevHlpSUPSemEventWaitNoResume(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent, uint32_t cMillies)
7702	{
7703	return pDevIns->CTX_SUFF(pHlp)->pfnSUPSemEventWaitNoResume(pDevIns, hEvent, cMillies);
7704	}
7705
7706	/**
7707	* @copydoc PDMDEVHLPR3::pfnSUPSemEventWaitNsAbsIntr
7708	*/
7709	DECLINLINE(int) PDMDevHlpSUPSemEventWaitNsAbsIntr(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent, uint64_t uNsTimeout)
7710	{
7711	return pDevIns->CTX_SUFF(pHlp)->pfnSUPSemEventWaitNsAbsIntr(pDevIns, hEvent, uNsTimeout);
7712	}
7713
7714	/**
7715	* @copydoc PDMDEVHLPR3::pfnSUPSemEventWaitNsRelIntr
7716	*/
7717	DECLINLINE(int) PDMDevHlpSUPSemEventWaitNsRelIntr(PPDMDEVINS pDevIns, SUPSEMEVENT hEvent, uint64_t cNsTimeout)
7718	{
7719	return pDevIns->CTX_SUFF(pHlp)->pfnSUPSemEventWaitNsRelIntr(pDevIns, hEvent, cNsTimeout);
7720	}
7721
7722	/**
7723	* @copydoc PDMDEVHLPR3::pfnSUPSemEventGetResolution
7724	*/
7725	DECLINLINE(uint32_t) PDMDevHlpSUPSemEventGetResolution(PPDMDEVINS pDevIns)
7726	{
7727	return pDevIns->CTX_SUFF(pHlp)->pfnSUPSemEventGetResolution(pDevIns);
7728	}
7729
7730	#ifdef IN_RING3
7731
7732	/**
7733	* @copydoc PDMDEVHLPR3::pfnSUPSemEventMultiCreate
7734	*/
7735	DECLINLINE(int) PDMDevHlpSUPSemEventMultiCreate(PPDMDEVINS pDevIns, PSUPSEMEVENTMULTI phEventMulti)
7736	{
7737	return pDevIns->pHlpR3->pfnSUPSemEventMultiCreate(pDevIns, phEventMulti);
7738	}
7739
7740	/**
7741	* @copydoc PDMDEVHLPR3::pfnSUPSemEventMultiClose
7742	*/
7743	DECLINLINE(int) PDMDevHlpSUPSemEventMultiClose(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti)
7744	{
7745	return pDevIns->pHlpR3->pfnSUPSemEventMultiClose(pDevIns, hEventMulti);
7746	}
7747
7748	#endif /* IN_RING3 */
7749
7750	/**
7751	* @copydoc PDMDEVHLPR3::pfnSUPSemEventMultiSignal
7752	*/
7753	DECLINLINE(int) PDMDevHlpSUPSemEventMultiSignal(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti)
7754	{
7755	return pDevIns->CTX_SUFF(pHlp)->pfnSUPSemEventMultiSignal(pDevIns, hEventMulti);
7756	}
7757
7758	/**
7759	* @copydoc PDMDEVHLPR3::pfnSUPSemEventMultiReset
7760	*/
7761	DECLINLINE(int) PDMDevHlpSUPSemEventMultiReset(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti)
7762	{
7763	return pDevIns->CTX_SUFF(pHlp)->pfnSUPSemEventMultiReset(pDevIns, hEventMulti);
7764	}
7765
7766	/**
7767	* @copydoc PDMDEVHLPR3::pfnSUPSemEventMultiWaitNoResume
7768	*/
7769	DECLINLINE(int) PDMDevHlpSUPSemEventMultiWaitNoResume(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti, uint32_t cMillies)
7770	{
7771	return pDevIns->CTX_SUFF(pHlp)->pfnSUPSemEventMultiWaitNsRelIntr(pDevIns, hEventMulti, cMillies);
7772	}
7773
7774	/**
7775	* @copydoc PDMDEVHLPR3::pfnSUPSemEventMultiWaitNsAbsIntr
7776	*/
7777	DECLINLINE(int) PDMDevHlpSUPSemEventMultiWaitNsAbsIntr(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti, uint64_t uNsTimeout)
7778	{
7779	return pDevIns->CTX_SUFF(pHlp)->pfnSUPSemEventMultiWaitNsAbsIntr(pDevIns, hEventMulti, uNsTimeout);
7780	}
7781
7782	/**
7783	* @copydoc PDMDEVHLPR3::pfnSUPSemEventMultiWaitNsRelIntr
7784	*/
7785	DECLINLINE(int) PDMDevHlpSUPSemEventMultiWaitNsRelIntr(PPDMDEVINS pDevIns, SUPSEMEVENTMULTI hEventMulti, uint64_t cNsTimeout)
7786	{
7787	return pDevIns->CTX_SUFF(pHlp)->pfnSUPSemEventMultiWaitNsRelIntr(pDevIns, hEventMulti, cNsTimeout);
7788	}
7789
7790	/**
7791	* @copydoc PDMDEVHLPR3::pfnSUPSemEventMultiGetResolution
7792	*/
7793	DECLINLINE(uint32_t) PDMDevHlpSUPSemEventMultiGetResolution(PPDMDEVINS pDevIns)
7794	{
7795	return pDevIns->CTX_SUFF(pHlp)->pfnSUPSemEventMultiGetResolution(pDevIns);
7796	}
7797
7798	#ifdef IN_RING3
7799
7800	/**
7801	* Initializes a PDM critical section.
7802	*
7803	* The PDM critical sections are derived from the IPRT critical sections, but
7804	* works in RC and R0 as well.
7805	*
7806	* @returns VBox status code.
7807	* @param pDevIns The device instance.
7808	* @param pCritSect Pointer to the critical section.
7809	* @param SRC_POS Use RT_SRC_POS.
7810	* @param pszNameFmt Format string for naming the critical section.
7811	* For statistics and lock validation.
7812	* @param ... Arguments for the format string.
7813	*/
7814	DECLINLINE(int) RT_IPRT_FORMAT_ATTR(6, 7) PDMDevHlpCritSectInit(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, RT_SRC_POS_DECL,
7815	const char *pszNameFmt, ...)
7816	{
7817	int rc;
7818	va_list va;
7819	va_start(va, pszNameFmt);
7820	rc = pDevIns->pHlpR3->pfnCritSectInit(pDevIns, pCritSect, RT_SRC_POS_ARGS, pszNameFmt, va);
7821	va_end(va);
7822	return rc;
7823	}
7824
7825	#endif /* IN_RING3 */
7826
7827	/**
7828	* @copydoc PDMDEVHLPR3::pfnCritSectGetNop
7829	*/
7830	DECLINLINE(PPDMCRITSECT) PDMDevHlpCritSectGetNop(PPDMDEVINS pDevIns)
7831	{
7832	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectGetNop(pDevIns);
7833	}
7834
7835	#ifdef IN_RING3
7836
7837	/**
7838	* @copydoc PDMDEVHLPR3::pfnCritSectGetNopR0
7839	*/
7840	DECLINLINE(R0PTRTYPE(PPDMCRITSECT)) PDMDevHlpCritSectGetNopR0(PPDMDEVINS pDevIns)
7841	{
7842	return pDevIns->pHlpR3->pfnCritSectGetNopR0(pDevIns);
7843	}
7844
7845	/**
7846	* @copydoc PDMDEVHLPR3::pfnCritSectGetNopRC
7847	*/
7848	DECLINLINE(RCPTRTYPE(PPDMCRITSECT)) PDMDevHlpCritSectGetNopRC(PPDMDEVINS pDevIns)
7849	{
7850	return pDevIns->pHlpR3->pfnCritSectGetNopRC(pDevIns);
7851	}
7852
7853	#endif /* IN_RING3 */
7854
7855	/**
7856	* @copydoc PDMDEVHLPR3::pfnSetDeviceCritSect
7857	*/
7858	DECLINLINE(int) PDMDevHlpSetDeviceCritSect(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect)
7859	{
7860	return pDevIns->CTX_SUFF(pHlp)->pfnSetDeviceCritSect(pDevIns, pCritSect);
7861	}
7862
7863	/**
7864	* @copydoc PDMCritSectEnter
7865	* @param pDevIns The device instance.
7866	*/
7867	DECLINLINE(int) PDMDevHlpCritSectEnter(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, int rcBusy)
7868	{
7869	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectEnter(pDevIns, pCritSect, rcBusy);
7870	}
7871
7872	/**
7873	* @copydoc PDMCritSectEnterDebug
7874	* @param pDevIns The device instance.
7875	*/
7876	DECLINLINE(int) PDMDevHlpCritSectEnterDebug(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, int rcBusy, RTHCUINTPTR uId, RT_SRC_POS_DECL)
7877	{
7878	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectEnterDebug(pDevIns, pCritSect, rcBusy, uId, RT_SRC_POS_ARGS);
7879	}
7880
7881	/**
7882	* @copydoc PDMCritSectTryEnter
7883	* @param pDevIns The device instance.
7884	*/
7885	DECLINLINE(int) PDMDevHlpCritSectTryEnter(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect)
7886	{
7887	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectTryEnter(pDevIns, pCritSect);
7888	}
7889
7890	/**
7891	* @copydoc PDMCritSectTryEnterDebug
7892	* @param pDevIns The device instance.
7893	*/
7894	DECLINLINE(int) PDMDevHlpCritSectTryEnterDebug(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, RTHCUINTPTR uId, RT_SRC_POS_DECL)
7895	{
7896	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectTryEnterDebug(pDevIns, pCritSect, uId, RT_SRC_POS_ARGS);
7897	}
7898
7899	/**
7900	* @copydoc PDMCritSectLeave
7901	* @param pDevIns The device instance.
7902	*/
7903	DECLINLINE(int) PDMDevHlpCritSectLeave(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect)
7904	{
7905	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectLeave(pDevIns, pCritSect);
7906	}
7907
7908	/**
7909	* @copydoc PDMCritSectIsOwner
7910	* @param pDevIns The device instance.
7911	*/
7912	DECLINLINE(bool) PDMDevHlpCritSectIsOwner(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect)
7913	{
7914	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectIsOwner(pDevIns, pCritSect);
7915	}
7916
7917	/**
7918	* @copydoc PDMCritSectIsInitialized
7919	* @param pDevIns The device instance.
7920	*/
7921	DECLINLINE(bool) PDMDevHlpCritSectIsInitialized(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect)
7922	{
7923	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectIsInitialized(pDevIns, pCritSect);
7924	}
7925
7926	/**
7927	* @copydoc PDMCritSectHasWaiters
7928	* @param pDevIns The device instance.
7929	*/
7930	DECLINLINE(bool) PDMDevHlpCritSectHasWaiters(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect)
7931	{
7932	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectHasWaiters(pDevIns, pCritSect);
7933	}
7934
7935	/**
7936	* @copydoc PDMCritSectGetRecursion
7937	* @param pDevIns The device instance.
7938	*/
7939	DECLINLINE(uint32_t) PDMDevHlpCritSectGetRecursion(PPDMDEVINS pDevIns, PCPDMCRITSECT pCritSect)
7940	{
7941	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectGetRecursion(pDevIns, pCritSect);
7942	}
7943
7944	#if defined(IN_RING3) \|\| defined(IN_RING0)
7945	/**
7946	* @copydoc PDMHCCritSectScheduleExitEvent
7947	* @param pDevIns The device instance.
7948	*/
7949	DECLINLINE(int) PDMDevHlpCritSectScheduleExitEvent(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, SUPSEMEVENT hEventToSignal)
7950	{
7951	return pDevIns->CTX_SUFF(pHlp)->pfnCritSectScheduleExitEvent(pDevIns, pCritSect, hEventToSignal);
7952	}
7953	#endif
7954
7955	/* Strict build: Remap the two enter calls to the debug versions. */
7956	#ifdef VBOX_STRICT
7957	# ifdef IPRT_INCLUDED_asm_h
7958	# define PDMDevHlpCritSectEnter(pDevIns, pCritSect, rcBusy) PDMDevHlpCritSectEnterDebug((pDevIns), (pCritSect), (rcBusy), (uintptr_t)ASMReturnAddress(), RT_SRC_POS)
7959	# define PDMDevHlpCritSectTryEnter(pDevIns, pCritSect) PDMDevHlpCritSectTryEnterDebug((pDevIns), (pCritSect), (uintptr_t)ASMReturnAddress(), RT_SRC_POS)
7960	# else
7961	# define PDMDevHlpCritSectEnter(pDevIns, pCritSect, rcBusy) PDMDevHlpCritSectEnterDebug((pDevIns), (pCritSect), (rcBusy), 0, RT_SRC_POS)
7962	# define PDMDevHlpCritSectTryEnter(pDevIns, pCritSect) PDMDevHlpCritSectTryEnterDebug((pDevIns), (pCritSect), 0, RT_SRC_POS)
7963	# endif
7964	#endif
7965
7966	#if defined(IN_RING3) \|\| defined(DOXYGEN_RUNNING)
7967
7968	/**
7969	* @copydoc PDMR3CritSectDelete
7970	* @param pDevIns The device instance.
7971	*/
7972	DECLINLINE(int) PDMDevHlpCritSectDelete(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect)
7973	{
7974	return pDevIns->pHlpR3->pfnCritSectDelete(pDevIns, pCritSect);
7975	}
7976
7977	/**
7978	* @copydoc PDMDEVHLPR3::pfnThreadCreate
7979	*/
7980	DECLINLINE(int) PDMDevHlpThreadCreate(PPDMDEVINS pDevIns, PPPDMTHREAD ppThread, void *pvUser, PFNPDMTHREADDEV pfnThread,
7981	PFNPDMTHREADWAKEUPDEV pfnWakeup, size_t cbStack, RTTHREADTYPE enmType, const char *pszName)
7982	{
7983	return pDevIns->pHlpR3->pfnThreadCreate(pDevIns, ppThread, pvUser, pfnThread, pfnWakeup, cbStack, enmType, pszName);
7984	}
7985
7986	/**
7987	* @copydoc PDMR3ThreadDestroy
7988	* @param pDevIns The device instance.
7989	*/
7990	DECLINLINE(int) PDMDevHlpThreadDestroy(PPDMDEVINS pDevIns, PPDMTHREAD pThread, int *pRcThread)
7991	{
7992	return pDevIns->pHlpR3->pfnThreadDestroy(pThread, pRcThread);
7993	}
7994
7995	/**
7996	* @copydoc PDMR3ThreadIAmSuspending
7997	* @param pDevIns The device instance.
7998	*/
7999	DECLINLINE(int) PDMDevHlpThreadIAmSuspending(PPDMDEVINS pDevIns, PPDMTHREAD pThread)
8000	{
8001	return pDevIns->pHlpR3->pfnThreadIAmSuspending(pThread);
8002	}
8003
8004	/**
8005	* @copydoc PDMR3ThreadIAmRunning
8006	* @param pDevIns The device instance.
8007	*/
8008	DECLINLINE(int) PDMDevHlpThreadIAmRunning(PPDMDEVINS pDevIns, PPDMTHREAD pThread)
8009	{
8010	return pDevIns->pHlpR3->pfnThreadIAmRunning(pThread);
8011	}
8012
8013	/**
8014	* @copydoc PDMR3ThreadSleep
8015	* @param pDevIns The device instance.
8016	*/
8017	DECLINLINE(int) PDMDevHlpThreadSleep(PPDMDEVINS pDevIns, PPDMTHREAD pThread, RTMSINTERVAL cMillies)
8018	{
8019	return pDevIns->pHlpR3->pfnThreadSleep(pThread, cMillies);
8020	}
8021
8022	/**
8023	* @copydoc PDMR3ThreadSuspend
8024	* @param pDevIns The device instance.
8025	*/
8026	DECLINLINE(int) PDMDevHlpThreadSuspend(PPDMDEVINS pDevIns, PPDMTHREAD pThread)
8027	{
8028	return pDevIns->pHlpR3->pfnThreadSuspend(pThread);
8029	}
8030
8031	/**
8032	* @copydoc PDMR3ThreadResume
8033	* @param pDevIns The device instance.
8034	*/
8035	DECLINLINE(int) PDMDevHlpThreadResume(PPDMDEVINS pDevIns, PPDMTHREAD pThread)
8036	{
8037	return pDevIns->pHlpR3->pfnThreadResume(pThread);
8038	}
8039
8040	/**
8041	* @copydoc PDMDEVHLPR3::pfnSetAsyncNotification
8042	*/
8043	DECLINLINE(int) PDMDevHlpSetAsyncNotification(PPDMDEVINS pDevIns, PFNPDMDEVASYNCNOTIFY pfnAsyncNotify)
8044	{
8045	return pDevIns->pHlpR3->pfnSetAsyncNotification(pDevIns, pfnAsyncNotify);
8046	}
8047
8048	/**
8049	* @copydoc PDMDEVHLPR3::pfnAsyncNotificationCompleted
8050	*/
8051	DECLINLINE(void) PDMDevHlpAsyncNotificationCompleted(PPDMDEVINS pDevIns)
8052	{
8053	pDevIns->pHlpR3->pfnAsyncNotificationCompleted(pDevIns);
8054	}
8055
8056	/**
8057	* @copydoc PDMDEVHLPR3::pfnA20Set
8058	*/
8059	DECLINLINE(void) PDMDevHlpA20Set(PPDMDEVINS pDevIns, bool fEnable)
8060	{
8061	pDevIns->pHlpR3->pfnA20Set(pDevIns, fEnable);
8062	}
8063
8064	/**
8065	* @copydoc PDMDEVHLPR3::pfnRTCRegister
8066	*/
8067	DECLINLINE(int) PDMDevHlpRTCRegister(PPDMDEVINS pDevIns, PCPDMRTCREG pRtcReg, PCPDMRTCHLP *ppRtcHlp)
8068	{
8069	return pDevIns->pHlpR3->pfnRTCRegister(pDevIns, pRtcReg, ppRtcHlp);
8070	}
8071
8072	/**
8073	* @copydoc PDMDEVHLPR3::pfnPCIBusRegister
8074	*/
8075	DECLINLINE(int) PDMDevHlpPCIBusRegister(PPDMDEVINS pDevIns, PPDMPCIBUSREGR3 pPciBusReg, PCPDMPCIHLPR3 ppPciHlp, uint32_t piBus)
8076	{
8077	return pDevIns->pHlpR3->pfnPCIBusRegister(pDevIns, pPciBusReg, ppPciHlp, piBus);
8078	}
8079
8080	/**
8081	* @copydoc PDMDEVHLPR3::pfnIommuRegister
8082	*/
8083	DECLINLINE(int) PDMDevHlpIommuRegister(PPDMDEVINS pDevIns, PPDMIOMMUREGR3 pIommuReg, PCPDMIOMMUHLPR3 ppIommuHlp, uint32_t pidxIommu)
8084	{
8085	return pDevIns->pHlpR3->pfnIommuRegister(pDevIns, pIommuReg, ppIommuHlp, pidxIommu);
8086	}
8087
8088	/**
8089	* @copydoc PDMDEVHLPR3::pfnPICRegister
8090	*/
8091	DECLINLINE(int) PDMDevHlpPICRegister(PPDMDEVINS pDevIns, PPDMPICREG pPicReg, PCPDMPICHLP *ppPicHlp)
8092	{
8093	return pDevIns->pHlpR3->pfnPICRegister(pDevIns, pPicReg, ppPicHlp);
8094	}
8095
8096	/**
8097	* @copydoc PDMDEVHLPR3::pfnApicRegister
8098	*/
8099	DECLINLINE(int) PDMDevHlpApicRegister(PPDMDEVINS pDevIns)
8100	{
8101	return pDevIns->pHlpR3->pfnApicRegister(pDevIns);
8102	}
8103
8104	/**
8105	* @copydoc PDMDEVHLPR3::pfnIoApicRegister
8106	*/
8107	DECLINLINE(int) PDMDevHlpIoApicRegister(PPDMDEVINS pDevIns, PPDMIOAPICREG pIoApicReg, PCPDMIOAPICHLP *ppIoApicHlp)
8108	{
8109	return pDevIns->pHlpR3->pfnIoApicRegister(pDevIns, pIoApicReg, ppIoApicHlp);
8110	}
8111
8112	/**
8113	* @copydoc PDMDEVHLPR3::pfnHpetRegister
8114	*/
8115	DECLINLINE(int) PDMDevHlpHpetRegister(PPDMDEVINS pDevIns, PPDMHPETREG pHpetReg, PCPDMHPETHLPR3 *ppHpetHlpR3)
8116	{
8117	return pDevIns->pHlpR3->pfnHpetRegister(pDevIns, pHpetReg, ppHpetHlpR3);
8118	}
8119
8120	/**
8121	* @copydoc PDMDEVHLPR3::pfnPciRawRegister
8122	*/
8123	DECLINLINE(int) PDMDevHlpPciRawRegister(PPDMDEVINS pDevIns, PPDMPCIRAWREG pPciRawReg, PCPDMPCIRAWHLPR3 *ppPciRawHlpR3)
8124	{
8125	return pDevIns->pHlpR3->pfnPciRawRegister(pDevIns, pPciRawReg, ppPciRawHlpR3);
8126	}
8127
8128	/**
8129	* @copydoc PDMDEVHLPR3::pfnDMACRegister
8130	*/
8131	DECLINLINE(int) PDMDevHlpDMACRegister(PPDMDEVINS pDevIns, PPDMDMACREG pDmacReg, PCPDMDMACHLP *ppDmacHlp)
8132	{
8133	return pDevIns->pHlpR3->pfnDMACRegister(pDevIns, pDmacReg, ppDmacHlp);
8134	}
8135
8136	/**
8137	* @copydoc PDMDEVHLPR3::pfnDMARegister
8138	*/
8139	DECLINLINE(int) PDMDevHlpDMARegister(PPDMDEVINS pDevIns, unsigned uChannel, PFNDMATRANSFERHANDLER pfnTransferHandler, void *pvUser)
8140	{
8141	return pDevIns->pHlpR3->pfnDMARegister(pDevIns, uChannel, pfnTransferHandler, pvUser);
8142	}
8143
8144	/**
8145	* @copydoc PDMDEVHLPR3::pfnDMAReadMemory
8146	*/
8147	DECLINLINE(int) PDMDevHlpDMAReadMemory(PPDMDEVINS pDevIns, unsigned uChannel, void pvBuffer, uint32_t off, uint32_t cbBlock, uint32_t pcbRead)
8148	{
8149	return pDevIns->pHlpR3->pfnDMAReadMemory(pDevIns, uChannel, pvBuffer, off, cbBlock, pcbRead);
8150	}
8151
8152	/**
8153	* @copydoc PDMDEVHLPR3::pfnDMAWriteMemory
8154	*/
8155	DECLINLINE(int) PDMDevHlpDMAWriteMemory(PPDMDEVINS pDevIns, unsigned uChannel, const void pvBuffer, uint32_t off, uint32_t cbBlock, uint32_t pcbWritten)
8156	{
8157	return pDevIns->pHlpR3->pfnDMAWriteMemory(pDevIns, uChannel, pvBuffer, off, cbBlock, pcbWritten);
8158	}
8159
8160	/**
8161	* @copydoc PDMDEVHLPR3::pfnDMASetDREQ
8162	*/
8163	DECLINLINE(int) PDMDevHlpDMASetDREQ(PPDMDEVINS pDevIns, unsigned uChannel, unsigned uLevel)
8164	{
8165	return pDevIns->pHlpR3->pfnDMASetDREQ(pDevIns, uChannel, uLevel);
8166	}
8167
8168	/**
8169	* @copydoc PDMDEVHLPR3::pfnDMAGetChannelMode
8170	*/
8171	DECLINLINE(uint8_t) PDMDevHlpDMAGetChannelMode(PPDMDEVINS pDevIns, unsigned uChannel)
8172	{
8173	return pDevIns->pHlpR3->pfnDMAGetChannelMode(pDevIns, uChannel);
8174	}
8175
8176	/**
8177	* @copydoc PDMDEVHLPR3::pfnDMASchedule
8178	*/
8179	DECLINLINE(void) PDMDevHlpDMASchedule(PPDMDEVINS pDevIns)
8180	{
8181	pDevIns->pHlpR3->pfnDMASchedule(pDevIns);
8182	}
8183
8184	/**
8185	* @copydoc PDMDEVHLPR3::pfnCMOSWrite
8186	*/
8187	DECLINLINE(int) PDMDevHlpCMOSWrite(PPDMDEVINS pDevIns, unsigned iReg, uint8_t u8Value)
8188	{
8189	return pDevIns->pHlpR3->pfnCMOSWrite(pDevIns, iReg, u8Value);
8190	}
8191
8192	/**
8193	* @copydoc PDMDEVHLPR3::pfnCMOSRead
8194	*/
8195	DECLINLINE(int) PDMDevHlpCMOSRead(PPDMDEVINS pDevIns, unsigned iReg, uint8_t *pu8Value)
8196	{
8197	return pDevIns->pHlpR3->pfnCMOSRead(pDevIns, iReg, pu8Value);
8198	}
8199
8200	/**
8201	* @copydoc PDMDEVHLPR3::pfnCallR0
8202	*/
8203	DECLINLINE(int) PDMDevHlpCallR0(PPDMDEVINS pDevIns, uint32_t uOperation, uint64_t u64Arg)
8204	{
8205	return pDevIns->pHlpR3->pfnCallR0(pDevIns, uOperation, u64Arg);
8206	}
8207
8208	/**
8209	* @copydoc PDMDEVHLPR3::pfnVMGetSuspendReason
8210	*/
8211	DECLINLINE(VMSUSPENDREASON) PDMDevHlpVMGetSuspendReason(PPDMDEVINS pDevIns)
8212	{
8213	return pDevIns->pHlpR3->pfnVMGetSuspendReason(pDevIns);
8214	}
8215
8216	/**
8217	* @copydoc PDMDEVHLPR3::pfnVMGetResumeReason
8218	*/
8219	DECLINLINE(VMRESUMEREASON) PDMDevHlpVMGetResumeReason(PPDMDEVINS pDevIns)
8220	{
8221	return pDevIns->pHlpR3->pfnVMGetResumeReason(pDevIns);
8222	}
8223
8224	/**
8225	* @copydoc PDMDEVHLPR3::pfnGetUVM
8226	*/
8227	DECLINLINE(PUVM) PDMDevHlpGetUVM(PPDMDEVINS pDevIns)
8228	{
8229	return pDevIns->CTX_SUFF(pHlp)->pfnGetUVM(pDevIns);
8230	}
8231
8232	#endif /* IN_RING3 \|\| DOXYGEN_RUNNING */
8233
8234	#if !defined(IN_RING3) \|\| defined(DOXYGEN_RUNNING)
8235
8236	/**
8237	* @copydoc PDMDEVHLPR0::pfnPCIBusSetUpContext
8238	*/
8239	DECLINLINE(int) PDMDevHlpPCIBusSetUpContext(PPDMDEVINS pDevIns, CTX_SUFF(PPDMPCIBUSREG) pPciBusReg, CTX_SUFF(PCPDMPCIHLP) *ppPciHlp)
8240	{
8241	return pDevIns->CTX_SUFF(pHlp)->pfnPCIBusSetUpContext(pDevIns, pPciBusReg, ppPciHlp);
8242	}
8243
8244	/**
8245	* @copydoc PDMDEVHLPR0::pfnIommuSetUpContext
8246	*/
8247	DECLINLINE(int) PDMDevHlpIommuSetUpContext(PPDMDEVINS pDevIns, CTX_SUFF(PPDMIOMMUREG) pIommuReg, CTX_SUFF(PCPDMIOMMUHLP) *ppIommuHlp)
8248	{
8249	return pDevIns->CTX_SUFF(pHlp)->pfnIommuSetUpContext(pDevIns, pIommuReg, ppIommuHlp);
8250	}
8251
8252	/**
8253	* @copydoc PDMDEVHLPR0::pfnPICSetUpContext
8254	*/
8255	DECLINLINE(int) PDMDevHlpPICSetUpContext(PPDMDEVINS pDevIns, PPDMPICREG pPicReg, PCPDMPICHLP *ppPicHlp)
8256	{
8257	return pDevIns->CTX_SUFF(pHlp)->pfnPICSetUpContext(pDevIns, pPicReg, ppPicHlp);
8258	}
8259
8260	/**
8261	* @copydoc PDMDEVHLPR0::pfnApicSetUpContext
8262	*/
8263	DECLINLINE(int) PDMDevHlpApicSetUpContext(PPDMDEVINS pDevIns)
8264	{
8265	return pDevIns->CTX_SUFF(pHlp)->pfnApicSetUpContext(pDevIns);
8266	}
8267
8268	/**
8269	* @copydoc PDMDEVHLPR0::pfnIoApicSetUpContext
8270	*/
8271	DECLINLINE(int) PDMDevHlpIoApicSetUpContext(PPDMDEVINS pDevIns, PPDMIOAPICREG pIoApicReg, PCPDMIOAPICHLP *ppIoApicHlp)
8272	{
8273	return pDevIns->CTX_SUFF(pHlp)->pfnIoApicSetUpContext(pDevIns, pIoApicReg, ppIoApicHlp);
8274	}
8275
8276	/**
8277	* @copydoc PDMDEVHLPR0::pfnHpetSetUpContext
8278	*/
8279	DECLINLINE(int) PDMDevHlpHpetSetUpContext(PPDMDEVINS pDevIns, PPDMHPETREG pHpetReg, CTX_SUFF(PCPDMHPETHLP) *ppHpetHlp)
8280	{
8281	return pDevIns->CTX_SUFF(pHlp)->pfnHpetSetUpContext(pDevIns, pHpetReg, ppHpetHlp);
8282	}
8283
8284	#endif /* !IN_RING3 \|\| DOXYGEN_RUNNING */
8285
8286	/**
8287	* @copydoc PDMDEVHLPR3::pfnGetVM
8288	*/
8289	DECLINLINE(PVMCC) PDMDevHlpGetVM(PPDMDEVINS pDevIns)
8290	{
8291	return pDevIns->CTX_SUFF(pHlp)->pfnGetVM(pDevIns);
8292	}
8293
8294	/**
8295	* @copydoc PDMDEVHLPR3::pfnGetVMCPU
8296	*/
8297	DECLINLINE(PVMCPUCC) PDMDevHlpGetVMCPU(PPDMDEVINS pDevIns)
8298	{
8299	return pDevIns->CTX_SUFF(pHlp)->pfnGetVMCPU(pDevIns);
8300	}
8301
8302	/**
8303	* @copydoc PDMDEVHLPR3::pfnGetCurrentCpuId
8304	*/
8305	DECLINLINE(VMCPUID) PDMDevHlpGetCurrentCpuId(PPDMDEVINS pDevIns)
8306	{
8307	return pDevIns->CTX_SUFF(pHlp)->pfnGetCurrentCpuId(pDevIns);
8308	}
8309
8310	/**
8311	* @copydoc PDMDEVHLPR3::pfnTMTimeVirtGet
8312	*/
8313	DECLINLINE(uint64_t) PDMDevHlpTMTimeVirtGet(PPDMDEVINS pDevIns)
8314	{
8315	return pDevIns->CTX_SUFF(pHlp)->pfnTMTimeVirtGet(pDevIns);
8316	}
8317
8318	/**
8319	* @copydoc PDMDEVHLPR3::pfnTMTimeVirtGetFreq
8320	*/
8321	DECLINLINE(uint64_t) PDMDevHlpTMTimeVirtGetFreq(PPDMDEVINS pDevIns)
8322	{
8323	return pDevIns->CTX_SUFF(pHlp)->pfnTMTimeVirtGetFreq(pDevIns);
8324	}
8325
8326	/**
8327	* @copydoc PDMDEVHLPR3::pfnTMTimeVirtGetFreq
8328	*/
8329	DECLINLINE(uint64_t) PDMDevHlpTMTimeVirtGetNano(PPDMDEVINS pDevIns)
8330	{
8331	return pDevIns->CTX_SUFF(pHlp)->pfnTMTimeVirtGetNano(pDevIns);
8332	}
8333
8334	#ifdef IN_RING3
8335
8336	/**
8337	* @copydoc PDMDEVHLPR3::pfnRegisterVMMDevHeap
8338	*/
8339	DECLINLINE(int) PDMDevHlpRegisterVMMDevHeap(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTR3PTR pvHeap, unsigned cbHeap)
8340	{
8341	return pDevIns->pHlpR3->pfnRegisterVMMDevHeap(pDevIns, GCPhys, pvHeap, cbHeap);
8342	}
8343
8344	/**
8345	* @copydoc PDMDEVHLPR3::pfnFirmwareRegister
8346	*/
8347	DECLINLINE(int) PDMDevHlpFirmwareRegister(PPDMDEVINS pDevIns, PCPDMFWREG pFwReg, PCPDMFWHLPR3 *ppFwHlp)
8348	{
8349	return pDevIns->pHlpR3->pfnFirmwareRegister(pDevIns, pFwReg, ppFwHlp);
8350	}
8351
8352	/**
8353	* @copydoc PDMDEVHLPR3::pfnVMReset
8354	*/
8355	DECLINLINE(int) PDMDevHlpVMReset(PPDMDEVINS pDevIns, uint32_t fFlags)
8356	{
8357	return pDevIns->pHlpR3->pfnVMReset(pDevIns, fFlags);
8358	}
8359
8360	/**
8361	* @copydoc PDMDEVHLPR3::pfnVMSuspend
8362	*/
8363	DECLINLINE(int) PDMDevHlpVMSuspend(PPDMDEVINS pDevIns)
8364	{
8365	return pDevIns->pHlpR3->pfnVMSuspend(pDevIns);
8366	}
8367
8368	/**
8369	* @copydoc PDMDEVHLPR3::pfnVMSuspendSaveAndPowerOff
8370	*/
8371	DECLINLINE(int) PDMDevHlpVMSuspendSaveAndPowerOff(PPDMDEVINS pDevIns)
8372	{
8373	return pDevIns->pHlpR3->pfnVMSuspendSaveAndPowerOff(pDevIns);
8374	}
8375
8376	/**
8377	* @copydoc PDMDEVHLPR3::pfnVMPowerOff
8378	*/
8379	DECLINLINE(int) PDMDevHlpVMPowerOff(PPDMDEVINS pDevIns)
8380	{
8381	return pDevIns->pHlpR3->pfnVMPowerOff(pDevIns);
8382	}
8383
8384	#endif /* IN_RING3 */
8385
8386	/**
8387	* @copydoc PDMDEVHLPR3::pfnA20IsEnabled
8388	*/
8389	DECLINLINE(bool) PDMDevHlpA20IsEnabled(PPDMDEVINS pDevIns)
8390	{
8391	return pDevIns->CTX_SUFF(pHlp)->pfnA20IsEnabled(pDevIns);
8392	}
8393
8394	#ifdef IN_RING3
8395
8396	/**
8397	* @copydoc PDMDEVHLPR3::pfnGetCpuId
8398	*/
8399	DECLINLINE(void) PDMDevHlpGetCpuId(PPDMDEVINS pDevIns, uint32_t iLeaf, uint32_t pEax, uint32_t pEbx, uint32_t pEcx, uint32_t pEdx)
8400	{
8401	pDevIns->pHlpR3->pfnGetCpuId(pDevIns, iLeaf, pEax, pEbx, pEcx, pEdx);
8402	}
8403
8404	/**
8405	* @copydoc PDMDEVHLPR3::pfnGetSupDrvSession
8406	*/
8407	DECLINLINE(PSUPDRVSESSION) PDMDevHlpGetSupDrvSession(PPDMDEVINS pDevIns)
8408	{
8409	return pDevIns->pHlpR3->pfnGetSupDrvSession(pDevIns);
8410	}
8411
8412	/**
8413	* @copydoc PDMDEVHLPR3::pfnQueryGenericUserObject
8414	*/
8415	DECLINLINE(void *) PDMDevHlpQueryGenericUserObject(PPDMDEVINS pDevIns, PCRTUUID pUuid)
8416	{
8417	return pDevIns->pHlpR3->pfnQueryGenericUserObject(pDevIns, pUuid);
8418	}
8419
8420	/**
8421	* @copydoc PDMDEVHLPR3::pfnPGMHandlerPhysicalTypeRegister
8422	*/
8423	DECLINLINE(int) PDMDevHlpPGMHandlerPhysicalTypeRegister(PPDMDEVINS pDevIns, PGMPHYSHANDLERKIND enmKind,
8424	R3PTRTYPE(PFNPGMPHYSHANDLER) pfnHandlerR3,
8425	const char pszHandlerR0, const char pszPfHandlerR0,
8426	const char pszHandlerRC, const char pszPfHandlerRC,
8427	const char *pszDesc, PPGMPHYSHANDLERTYPE phType)
8428	{
8429	return pDevIns->pHlpR3->pfnPGMHandlerPhysicalTypeRegister(pDevIns, enmKind, pfnHandlerR3,
8430	pszHandlerR0, pszPfHandlerR0,
8431	pszHandlerRC, pszPfHandlerRC,
8432	pszDesc, phType);
8433	}
8434
8435	/** Wrapper around SSMR3GetU32 for simplifying getting enum values saved as uint32_t. */
8436	# define PDMDEVHLP_SSM_GET_ENUM32_RET(a_pHlp, a_pSSM, a_enmDst, a_EnumType) \
8437	do { \
8438	uint32_t u32GetEnumTmp = 0; \
8439	int rcGetEnum32Tmp = (a_pHlp)->pfnSSMGetU32((a_pSSM), &u32GetEnumTmp); \
8440	AssertRCReturn(rcGetEnum32Tmp, rcGetEnum32Tmp); \
8441	(a_enmDst) = (a_EnumType)u32GetEnumTmp; \
8442	AssertCompile(sizeof(a_EnumType) == sizeof(u32GetEnumTmp)); \
8443	} while (0)
8444
8445	/** Wrapper around SSMR3GetU8 for simplifying getting enum values saved as uint8_t. */
8446	# define PDMDEVHLP_SSM_GET_ENUM8_RET(a_pHlp, a_pSSM, a_enmDst, a_EnumType) \
8447	do { \
8448	uint8_t bGetEnumTmp = 0; \
8449	int rcGetEnum32Tmp = (a_pHlp)->pfnSSMGetU8((a_pSSM), &bGetEnumTmp); \
8450	AssertRCReturn(rcGetEnum32Tmp, rcGetEnum32Tmp); \
8451	(a_enmDst) = (a_EnumType)bGetEnumTmp; \
8452	} while (0)
8453
8454	#endif /* IN_RING3 */
8455
8456	/** Pointer to callbacks provided to the VBoxDeviceRegister() call. */
8457	typedef struct PDMDEVREGCB *PPDMDEVREGCB;
8458
8459	/**
8460	* Callbacks for VBoxDeviceRegister().
8461	*/
8462	typedef struct PDMDEVREGCB
8463	{
8464	/** Interface version.
8465	* This is set to PDM_DEVREG_CB_VERSION. */
8466	uint32_t u32Version;
8467
8468	/**
8469	* Registers a device with the current VM instance.
8470	*
8471	* @returns VBox status code.
8472	* @param pCallbacks Pointer to the callback table.
8473	* @param pReg Pointer to the device registration record.
8474	* This data must be permanent and readonly.
8475	*/
8476	DECLR3CALLBACKMEMBER(int, pfnRegister,(PPDMDEVREGCB pCallbacks, PCPDMDEVREG pReg));
8477	} PDMDEVREGCB;
8478
8479	/** Current version of the PDMDEVREGCB structure. */
8480	#define PDM_DEVREG_CB_VERSION PDM_VERSION_MAKE(0xffe3, 1, 0)
8481
8482
8483	/**
8484	* The VBoxDevicesRegister callback function.
8485	*
8486	* PDM will invoke this function after loading a device module and letting
8487	* the module decide which devices to register and how to handle conflicts.
8488	*
8489	* @returns VBox status code.
8490	* @param pCallbacks Pointer to the callback table.
8491	* @param u32Version VBox version number.
8492	*/
8493	typedef DECLCALLBACKTYPE(int, FNPDMVBOXDEVICESREGISTER,(PPDMDEVREGCB pCallbacks, uint32_t u32Version));
8494
8495	/** @} */
8496
8497	RT_C_DECLS_END
8498
8499	#endif /* !VBOX_INCLUDED_vmm_pdmdev_h */

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

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

Download in other formats: