pdmdev.h@ 90364

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

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

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

Download in other formats: