pdmdev.h@ 92071

最後變更在這個檔案從92071是 92071,由 vboxsync 提交於 3 年前
VMM/DevHlp: Added PDMDevHlpSSMRegisterLegacy for dealing with renamed and merged devices. bugref:8651
屬性 svn:eol-style 設為 `native` 屬性 svn:keywords 設為 `Id Revision`
檔案大小: 401.0 KB

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

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

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

以其他格式下載: