pdmdev.h@ 84407

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

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

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

Download in other formats: