pdmdev.h@ 81605

Last change on this file since 81605 was 81590, checked in by vboxsync, 5 years ago
pdmdev.h: Adding type-safer PDMDEVINS_2_DATA and PDMDEVINS_2_DATA_CC macros that replaces PDMINS_2_DATA and PDMINS_2_DATA_CC for device instances. On modern compilers these macros will check the size type against the size in the device registration structure, though only in strict builds of course. bugref:9218
Property svn:eol-style set to `native` Property svn:keywords set to `Id Revision`
File size: 323.6 KB

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

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

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

Download in other formats: