pdmdev.h@ 90982

Last change on this file since 90982 was 90502, checked in by vboxsync, 4 years ago
VMM/PDM: Added device helpers for read/write critical sections. bugref:6695
Property svn:eol-style set to `native` Property svn:keywords set to `Id Revision`
File size: 371.8 KB

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

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

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

Download in other formats: