pdmdev.h@ 88054

Last change on this file since 88054 was 87906, checked in by vboxsync, 4 years ago
AMD IOMMU: bugref:9654 Naming cleanup (uDeviceId -> idDevice etc.)
Property svn:eol-style set to `native` Property svn:keywords set to `Id Revision`
File size: 351.2 KB

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

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

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

Download in other formats: