pdmdev.h@ 53411

Last change on this file since 53411 was 52670, checked in by vboxsync, 10 years ago
VMM, Devices: Add interface to query the APIC frequency from the APIC device.
Property svn:eol-style set to `native` Property svn:keywords set to `Id`
File size: 200.0 KB

Line
1	/** @file
2	* PDM - Pluggable Device Manager, Devices.
3	*/
4
5	/*
6	* Copyright (C) 2006-2013 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_vmm_pdmdev_h
27	#define ___VBox_vmm_pdmdev_h
28
29	#include <VBox/vmm/pdmqueue.h>
30	#include <VBox/vmm/pdmcritsect.h>
31	#include <VBox/vmm/pdmthread.h>
32	#include <VBox/vmm/pdmifs.h>
33	#include <VBox/vmm/pdmins.h>
34	#include <VBox/vmm/pdmcommon.h>
35	#include <VBox/vmm/iom.h>
36	#include <VBox/vmm/tm.h>
37	#include <VBox/vmm/ssm.h>
38	#include <VBox/vmm/cfgm.h>
39	#include <VBox/vmm/dbgf.h>
40	#include <VBox/err.h>
41	#include <VBox/pci.h>
42	#include <VBox/sup.h>
43	#include <iprt/stdarg.h>
44
45
46	RT_C_DECLS_BEGIN
47
48	/** @defgroup grp_pdm_device The PDM Devices API
49	* @ingroup grp_pdm
50	* @{
51	*/
52
53	/**
54	* Construct a device instance for a VM.
55	*
56	* @returns VBox status.
57	* @param pDevIns The device instance data. If the registration structure
58	* is needed, it can be accessed thru pDevIns->pReg.
59	* @param iInstance Instance number. Use this to figure out which registers
60	* and such to use. The instance number is also found in
61	* pDevIns->iInstance, but since it's likely to be
62	* frequently used PDM passes it as parameter.
63	* @param pCfg Configuration node handle for the driver. This is
64	* expected to be in high demand in the constructor and is
65	* therefore passed as an argument. When using it at other
66	* times, it can be found in pDrvIns->pCfg.
67	*/
68	typedef DECLCALLBACK(int) FNPDMDEVCONSTRUCT(PPDMDEVINS pDevIns, int iInstance, PCFGMNODE pCfg);
69	/** Pointer to a FNPDMDEVCONSTRUCT() function. */
70	typedef FNPDMDEVCONSTRUCT *PFNPDMDEVCONSTRUCT;
71
72	/**
73	* Destruct a device instance.
74	*
75	* Most VM resources are freed by the VM. This callback is provided so that any non-VM
76	* resources can be freed correctly.
77	*
78	* @returns VBox status.
79	* @param pDevIns The device instance data.
80	*
81	* @remarks The device critical section is not entered. The routine may delete
82	* the critical section, so the caller cannot exit it.
83	*/
84	typedef DECLCALLBACK(int) FNPDMDEVDESTRUCT(PPDMDEVINS pDevIns);
85	/** Pointer to a FNPDMDEVDESTRUCT() function. */
86	typedef FNPDMDEVDESTRUCT *PFNPDMDEVDESTRUCT;
87
88	/**
89	* Device relocation callback.
90	*
91	* This is called when the instance data has been relocated in raw-mode context
92	* (RC). It is also called when the RC hypervisor selects changes. The device
93	* must fixup all necessary pointers and re-query all interfaces to other RC
94	* devices and drivers.
95	*
96	* Before the RC code is executed the first time, this function will be called
97	* with a 0 delta so RC pointer calculations can be one in one place.
98	*
99	* @param pDevIns Pointer to the device instance.
100	* @param offDelta The relocation delta relative to the old location.
101	*
102	* @remarks A relocation CANNOT fail.
103	*
104	* @remarks The device critical section is not entered. The relocations should
105	* not normally require any locking.
106	*/
107	typedef DECLCALLBACK(void) FNPDMDEVRELOCATE(PPDMDEVINS pDevIns, RTGCINTPTR offDelta);
108	/** Pointer to a FNPDMDEVRELOCATE() function. */
109	typedef FNPDMDEVRELOCATE *PFNPDMDEVRELOCATE;
110
111	/**
112	* Power On notification.
113	*
114	* @returns VBox status.
115	* @param pDevIns The device instance data.
116	*
117	* @remarks Caller enters the device critical section.
118	*/
119	typedef DECLCALLBACK(void) FNPDMDEVPOWERON(PPDMDEVINS pDevIns);
120	/** Pointer to a FNPDMDEVPOWERON() function. */
121	typedef FNPDMDEVPOWERON *PFNPDMDEVPOWERON;
122
123	/**
124	* Reset notification.
125	*
126	* @returns VBox status.
127	* @param pDevIns The device instance data.
128	*
129	* @remarks Caller enters the device critical section.
130	*/
131	typedef DECLCALLBACK(void) FNPDMDEVRESET(PPDMDEVINS pDevIns);
132	/** Pointer to a FNPDMDEVRESET() function. */
133	typedef FNPDMDEVRESET *PFNPDMDEVRESET;
134
135	/**
136	* Suspend notification.
137	*
138	* @returns VBox status.
139	* @param pDevIns The device instance data.
140	* @thread EMT(0)
141	*
142	* @remarks Caller enters the device critical section.
143	*/
144	typedef DECLCALLBACK(void) FNPDMDEVSUSPEND(PPDMDEVINS pDevIns);
145	/** Pointer to a FNPDMDEVSUSPEND() function. */
146	typedef FNPDMDEVSUSPEND *PFNPDMDEVSUSPEND;
147
148	/**
149	* Resume notification.
150	*
151	* @returns VBox status.
152	* @param pDevIns The device instance data.
153	*
154	* @remarks Caller enters the device critical section.
155	*/
156	typedef DECLCALLBACK(void) FNPDMDEVRESUME(PPDMDEVINS pDevIns);
157	/** Pointer to a FNPDMDEVRESUME() function. */
158	typedef FNPDMDEVRESUME *PFNPDMDEVRESUME;
159
160	/**
161	* Power Off notification.
162	*
163	* This is only called when the VMR3PowerOff call is made on a running VM. This
164	* means that there is no notification if the VM was suspended before being
165	* powered off. There will also be no callback when hot plugging devices.
166	*
167	* @param pDevIns The device instance data.
168	* @thread EMT(0)
169	*
170	* @remarks Caller enters the device critical section.
171	*/
172	typedef DECLCALLBACK(void) FNPDMDEVPOWEROFF(PPDMDEVINS pDevIns);
173	/** Pointer to a FNPDMDEVPOWEROFF() function. */
174	typedef FNPDMDEVPOWEROFF *PFNPDMDEVPOWEROFF;
175
176	/**
177	* Attach command.
178	*
179	* This is called to let the device attach to a driver for a specified LUN
180	* at runtime. This is not called during VM construction, the device
181	* constructor have to attach to all the available drivers.
182	*
183	* This is like plugging in the keyboard or mouse after turning on the PC.
184	*
185	* @returns VBox status code.
186	* @param pDevIns The device instance.
187	* @param iLUN The logical unit which is being detached.
188	* @param fFlags Flags, combination of the PDM_TACH_FLAGS_* \#defines.
189	*
190	* @remarks Caller enters the device critical section.
191	*/
192	typedef DECLCALLBACK(int) FNPDMDEVATTACH(PPDMDEVINS pDevIns, unsigned iLUN, uint32_t fFlags);
193	/** Pointer to a FNPDMDEVATTACH() function. */
194	typedef FNPDMDEVATTACH *PFNPDMDEVATTACH;
195
196	/**
197	* Detach notification.
198	*
199	* This is called when a driver is detaching itself from a LUN of the device.
200	* The device should adjust it's state to reflect this.
201	*
202	* This is like unplugging the network cable to use it for the laptop or
203	* something while the PC is still running.
204	*
205	* @param pDevIns The device instance.
206	* @param iLUN The logical unit which is being detached.
207	* @param fFlags Flags, combination of the PDMDEVATT_FLAGS_* \#defines.
208	*
209	* @remarks Caller enters the device critical section.
210	*/
211	typedef DECLCALLBACK(void) FNPDMDEVDETACH(PPDMDEVINS pDevIns, unsigned iLUN, uint32_t fFlags);
212	/** Pointer to a FNPDMDEVDETACH() function. */
213	typedef FNPDMDEVDETACH *PFNPDMDEVDETACH;
214
215	/**
216	* Query the base interface of a logical unit.
217	*
218	* @returns VBOX status code.
219	* @param pDevIns The device instance.
220	* @param iLUN The logicial unit to query.
221	* @param ppBase Where to store the pointer to the base interface of the LUN.
222	*
223	* @remarks The device critical section is not entered.
224	*/
225	typedef DECLCALLBACK(int) FNPDMDEVQUERYINTERFACE(PPDMDEVINS pDevIns, unsigned iLUN, PPDMIBASE *ppBase);
226	/** Pointer to a FNPDMDEVQUERYINTERFACE() function. */
227	typedef FNPDMDEVQUERYINTERFACE *PFNPDMDEVQUERYINTERFACE;
228
229	/**
230	* Init complete notification.
231	* This can be done to do communication with other devices and other
232	* initialization which requires everything to be in place.
233	*
234	* @returns VBOX status code.
235	* @param pDevIns The device instance.
236	*
237	* @remarks Caller enters the device critical section.
238	*/
239	typedef DECLCALLBACK(int) FNPDMDEVINITCOMPLETE(PPDMDEVINS pDevIns);
240	/** Pointer to a FNPDMDEVINITCOMPLETE() function. */
241	typedef FNPDMDEVINITCOMPLETE *PFNPDMDEVINITCOMPLETE;
242
243
244	/**
245	* The context of a pfnMemSetup call.
246	*/
247	typedef enum PDMDEVMEMSETUPCTX
248	{
249	/** Invalid zero value. */
250	PDMDEVMEMSETUPCTX_INVALID = 0,
251	/** After construction. */
252	PDMDEVMEMSETUPCTX_AFTER_CONSTRUCTION,
253	/** After reset. */
254	PDMDEVMEMSETUPCTX_AFTER_RESET,
255	/** Type size hack. */
256	PDMDEVMEMSETUPCTX_32BIT_HACK = 0x7fffffff
257	} PDMDEVMEMSETUPCTX;
258
259
260	/**
261	* PDM Device Registration Structure.
262	*
263	* This structure is used when registering a device from VBoxInitDevices() in HC
264	* Ring-3. PDM will continue use till the VM is terminated.
265	*/
266	typedef struct PDMDEVREG
267	{
268	/** Structure version. PDM_DEVREG_VERSION defines the current version. */
269	uint32_t u32Version;
270	/** Device name. */
271	char szName[32];
272	/** Name of the raw-mode context module (no path).
273	* Only evalutated if PDM_DEVREG_FLAGS_RC is set. */
274	char szRCMod[32];
275	/** Name of the ring-0 module (no path).
276	* Only evalutated if PDM_DEVREG_FLAGS_R0 is set. */
277	char szR0Mod[32];
278	/** The description of the device. The UTF-8 string pointed to shall, like this structure,
279	* remain unchanged from registration till VM destruction. */
280	const char *pszDescription;
281
282	/** Flags, combination of the PDM_DEVREG_FLAGS_* \#defines. */
283	uint32_t fFlags;
284	/** Device class(es), combination of the PDM_DEVREG_CLASS_* \#defines. */
285	uint32_t fClass;
286	/** Maximum number of instances (per VM). */
287	uint32_t cMaxInstances;
288	/** Size of the instance data. */
289	uint32_t cbInstance;
290
291	/** Construct instance - required. */
292	PFNPDMDEVCONSTRUCT pfnConstruct;
293	/** Destruct instance - optional.
294	* Critical section NOT entered (will be destroyed). */
295	PFNPDMDEVDESTRUCT pfnDestruct;
296	/** Relocation command - optional.
297	* Critical section NOT entered. */
298	PFNPDMDEVRELOCATE pfnRelocate;
299
300	/**
301	* Memory setup callback.
302	*
303	* @param pDevIns The device instance data.
304	* @param enmCtx Indicates the context of the call.
305	* @remarks The critical section is entered prior to calling this method.
306	*/
307	DECLR3CALLBACKMEMBER(void, pfnMemSetup, (PPDMDEVINS pDevIns, PDMDEVMEMSETUPCTX enmCtx));
308
309	/** Power on notification - optional.
310	* Critical section is entered. */
311	PFNPDMDEVPOWERON pfnPowerOn;
312	/** Reset notification - optional.
313	* Critical section is entered. */
314	PFNPDMDEVRESET pfnReset;
315	/** Suspend notification - optional.
316	* Critical section is entered. */
317	PFNPDMDEVSUSPEND pfnSuspend;
318	/** Resume notification - optional.
319	* Critical section is entered. */
320	PFNPDMDEVRESUME pfnResume;
321	/** Attach command - optional.
322	* Critical section is entered. */
323	PFNPDMDEVATTACH pfnAttach;
324	/** Detach notification - optional.
325	* Critical section is entered. */
326	PFNPDMDEVDETACH pfnDetach;
327	/** Query a LUN base interface - optional.
328	* Critical section is NOT entered. */
329	PFNPDMDEVQUERYINTERFACE pfnQueryInterface;
330	/** Init complete notification - optional.
331	* Critical section is entered. */
332	PFNPDMDEVINITCOMPLETE pfnInitComplete;
333	/** Power off notification - optional.
334	* Critical section is entered. */
335	PFNPDMDEVPOWEROFF pfnPowerOff;
336	/** @todo */
337	PFNRT pfnSoftReset;
338	/** Initialization safty marker. */
339	uint32_t u32VersionEnd;
340	} PDMDEVREG;
341	/** Pointer to a PDM Device Structure. */
342	typedef PDMDEVREG *PPDMDEVREG;
343	/** Const pointer to a PDM Device Structure. */
344	typedef PDMDEVREG const *PCPDMDEVREG;
345
346	/** Current DEVREG version number. */
347	#define PDM_DEVREG_VERSION PDM_VERSION_MAKE(0xffff, 2, 0)
348
349	/** PDM Device Flags.
350	* @{ */
351	/** This flag is used to indicate that the device has a RC component. */
352	#define PDM_DEVREG_FLAGS_RC 0x00000001
353	/** This flag is used to indicate that the device has a R0 component. */
354	#define PDM_DEVREG_FLAGS_R0 0x00000002
355
356	/** @def PDM_DEVREG_FLAGS_HOST_BITS_DEFAULT
357	* The bit count for the current host. */
358	#if HC_ARCH_BITS == 32
359	# define PDM_DEVREG_FLAGS_HOST_BITS_DEFAULT 0x00000010
360	#elif HC_ARCH_BITS == 64
361	# define PDM_DEVREG_FLAGS_HOST_BITS_DEFAULT 0x00000020
362	#else
363	# error Unsupported HC_ARCH_BITS value.
364	#endif
365	/** The host bit count mask. */
366	#define PDM_DEVREG_FLAGS_HOST_BITS_MASK 0x00000030
367
368	/** The device support only 32-bit guests. */
369	#define PDM_DEVREG_FLAGS_GUEST_BITS_32 0x00000100
370	/** The device support only 64-bit guests. */
371	#define PDM_DEVREG_FLAGS_GUEST_BITS_64 0x00000200
372	/** The device support both 32-bit & 64-bit guests. */
373	#define PDM_DEVREG_FLAGS_GUEST_BITS_32_64 0x00000300
374	/** @def PDM_DEVREG_FLAGS_GUEST_BITS_DEFAULT
375	* The guest bit count for the current compilation. */
376	#if GC_ARCH_BITS == 32
377	# define PDM_DEVREG_FLAGS_GUEST_BITS_DEFAULT PDM_DEVREG_FLAGS_GUEST_BITS_32
378	#elif GC_ARCH_BITS == 64
379	# define PDM_DEVREG_FLAGS_GUEST_BITS_DEFAULT PDM_DEVREG_FLAGS_GUEST_BITS_32_64
380	#else
381	# error Unsupported GC_ARCH_BITS value.
382	#endif
383	/** The guest bit count mask. */
384	#define PDM_DEVREG_FLAGS_GUEST_BITS_MASK 0x00000300
385
386	/** A convenience. */
387	#define PDM_DEVREG_FLAGS_DEFAULT_BITS (PDM_DEVREG_FLAGS_GUEST_BITS_DEFAULT \| PDM_DEVREG_FLAGS_HOST_BITS_DEFAULT)
388
389	/** Indicates that the devices support PAE36 on a 32-bit guest. */
390	#define PDM_DEVREG_FLAGS_PAE36 0x00001000
391
392	/** Indicates that the device needs to be notified before the drivers when suspending. */
393	#define PDM_DEVREG_FLAGS_FIRST_SUSPEND_NOTIFICATION 0x00002000
394
395	/** Indicates that the device needs to be notified before the drivers when powering off. */
396	#define PDM_DEVREG_FLAGS_FIRST_POWEROFF_NOTIFICATION 0x00004000
397
398	/** Indicates that the device needs to be notified before the drivers when resetting. */
399	#define PDM_DEVREG_FLAGS_FIRST_RESET_NOTIFICATION 0x00008000
400	/** @} */
401
402
403	/** PDM Device Classes.
404	* The order is important, lower bit earlier instantiation.
405	* @{ */
406	/** Architecture device. */
407	#define PDM_DEVREG_CLASS_ARCH RT_BIT(0)
408	/** Architecture BIOS device. */
409	#define PDM_DEVREG_CLASS_ARCH_BIOS RT_BIT(1)
410	/** PCI bus brigde. */
411	#define PDM_DEVREG_CLASS_BUS_PCI RT_BIT(2)
412	/** ISA bus brigde. */
413	#define PDM_DEVREG_CLASS_BUS_ISA RT_BIT(3)
414	/** Input device (mouse, keyboard, joystick, HID, ...). */
415	#define PDM_DEVREG_CLASS_INPUT RT_BIT(4)
416	/** Interrupt controller (PIC). */
417	#define PDM_DEVREG_CLASS_PIC RT_BIT(5)
418	/** Interval controoler (PIT). */
419	#define PDM_DEVREG_CLASS_PIT RT_BIT(6)
420	/** RTC/CMOS. */
421	#define PDM_DEVREG_CLASS_RTC RT_BIT(7)
422	/** DMA controller. */
423	#define PDM_DEVREG_CLASS_DMA RT_BIT(8)
424	/** VMM Device. */
425	#define PDM_DEVREG_CLASS_VMM_DEV RT_BIT(9)
426	/** Graphics device, like VGA. */
427	#define PDM_DEVREG_CLASS_GRAPHICS RT_BIT(10)
428	/** Storage controller device. */
429	#define PDM_DEVREG_CLASS_STORAGE RT_BIT(11)
430	/** Network interface controller. */
431	#define PDM_DEVREG_CLASS_NETWORK RT_BIT(12)
432	/** Audio. */
433	#define PDM_DEVREG_CLASS_AUDIO RT_BIT(13)
434	/** USB HIC. */
435	#define PDM_DEVREG_CLASS_BUS_USB RT_BIT(14)
436	/** ACPI. */
437	#define PDM_DEVREG_CLASS_ACPI RT_BIT(15)
438	/** Serial controller device. */
439	#define PDM_DEVREG_CLASS_SERIAL RT_BIT(16)
440	/** Parallel controller device */
441	#define PDM_DEVREG_CLASS_PARALLEL RT_BIT(17)
442	/** Host PCI pass-through device */
443	#define PDM_DEVREG_CLASS_HOST_DEV RT_BIT(18)
444	/** Misc devices (always last). */
445	#define PDM_DEVREG_CLASS_MISC RT_BIT(31)
446	/** @} */
447
448
449	/** @name IRQ Level for use with the *SetIrq APIs.
450	* @{
451	*/
452	/** Assert the IRQ (can assume value 1). */
453	#define PDM_IRQ_LEVEL_HIGH RT_BIT(0)
454	/** Deassert the IRQ (can assume value 0). */
455	#define PDM_IRQ_LEVEL_LOW 0
456	/** flip-flop - deassert and then assert the IRQ again immediately. */
457	#define PDM_IRQ_LEVEL_FLIP_FLOP (RT_BIT(1) \| PDM_IRQ_LEVEL_HIGH)
458	/** @} */
459
460	/**
461	* Registration record for MSI.
462	*/
463	typedef struct PDMMSIREG
464	{
465	/** Number of MSI interrupt vectors, 0 if MSI not supported */
466	uint16_t cMsiVectors;
467	/** Offset of MSI capability */
468	uint8_t iMsiCapOffset;
469	/** Offset of next capability to MSI */
470	uint8_t iMsiNextOffset;
471	/** If we support 64-bit MSI addressing */
472	bool fMsi64bit;
473
474	/** Number of MSI-X interrupt vectors, 0 if MSI-X not supported */
475	uint16_t cMsixVectors;
476	/** Offset of MSI-X capability */
477	uint8_t iMsixCapOffset;
478	/** Offset of next capability to MSI-X */
479	uint8_t iMsixNextOffset;
480	/** Value of PCI BAR (base addresss register) assigned by device for MSI-X page access */
481	uint8_t iMsixBar;
482	} PDMMSIREG;
483	typedef PDMMSIREG *PPDMMSIREG;
484
485	/**
486	* PCI Bus registration structure.
487	* All the callbacks, except the PCIBIOS hack, are working on PCI devices.
488	*/
489	typedef struct PDMPCIBUSREG
490	{
491	/** Structure version number. PDM_PCIBUSREG_VERSION defines the current version. */
492	uint32_t u32Version;
493
494	/**
495	* Registers the device with the default PCI bus.
496	*
497	* @returns VBox status code.
498	* @param pDevIns Device instance of the PCI Bus.
499	* @param pPciDev The PCI device structure.
500	* Any PCI enabled device must keep this in it's instance data!
501	* Fill in the PCI data config before registration, please.
502	* @param pszName Pointer to device name (permanent, readonly). For debugging, not unique.
503	* @param iDev The device number ((dev << 3) \| function) the device should have on the bus.
504	* If negative, the pci bus device will assign one.
505	* @remarks Caller enters the PDM critical section.
506	*/
507	DECLR3CALLBACKMEMBER(int, pfnRegisterR3,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, const char *pszName, int iDev));
508
509	/**
510	* Initialize MSI support in a PCI device.
511	*
512	* @returns VBox status code.
513	* @param pDevIns Device instance of the PCI Bus.
514	* @param pPciDev The PCI device structure.
515	* @param pMsiReg MSI registration structure
516	* @remarks Caller enters the PDM critical section.
517	*/
518	DECLR3CALLBACKMEMBER(int, pfnRegisterMsiR3,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, PPDMMSIREG pMsiReg));
519
520	/**
521	* Registers a I/O region (memory mapped or I/O ports) for a PCI device.
522	*
523	* @returns VBox status code.
524	* @param pDevIns Device instance of the PCI Bus.
525	* @param pPciDev The PCI device structure.
526	* @param iRegion The region number.
527	* @param cbRegion Size of the region.
528	* @param iType PCI_ADDRESS_SPACE_MEM, PCI_ADDRESS_SPACE_IO or PCI_ADDRESS_SPACE_MEM_PREFETCH.
529	* @param pfnCallback Callback for doing the mapping.
530	* @remarks Caller enters the PDM critical section.
531	*/
532	DECLR3CALLBACKMEMBER(int, pfnIORegionRegisterR3,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, int iRegion, uint32_t cbRegion, PCIADDRESSSPACE enmType, PFNPCIIOREGIONMAP pfnCallback));
533
534	/**
535	* Register PCI configuration space read/write callbacks.
536	*
537	* @param pDevIns Device instance of the PCI Bus.
538	* @param pPciDev The PCI device structure.
539	* @param pfnRead Pointer to the user defined PCI config read function.
540	* @param ppfnReadOld Pointer to function pointer which will receive the old (default)
541	* PCI config read function. This way, user can decide when (and if)
542	* to call default PCI config read function. Can be NULL.
543	* @param pfnWrite Pointer to the user defined PCI config write function.
544	* @param pfnWriteOld Pointer to function pointer which will receive the old (default)
545	* PCI config write function. This way, user can decide when (and if)
546	* to call default PCI config write function. Can be NULL.
547	* @remarks Caller enters the PDM critical section.
548	* @thread EMT
549	*/
550	DECLR3CALLBACKMEMBER(void, pfnSetConfigCallbacksR3,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, PFNPCICONFIGREAD pfnRead, PPFNPCICONFIGREAD ppfnReadOld,
551	PFNPCICONFIGWRITE pfnWrite, PPFNPCICONFIGWRITE ppfnWriteOld));
552
553	/**
554	* Set the IRQ for a PCI device.
555	*
556	* @param pDevIns Device instance of the PCI Bus.
557	* @param pPciDev The PCI device structure.
558	* @param iIrq IRQ number to set.
559	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
560	* @param uTagSrc The IRQ tag and source (for tracing).
561	* @remarks Caller enters the PDM critical section.
562	*/
563	DECLR3CALLBACKMEMBER(void, pfnSetIrqR3,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, int iIrq, int iLevel, uint32_t uTagSrc));
564
565	/**
566	* Called to perform the job of the bios.
567	* This is only called for the first PCI Bus - it is expected to
568	* service all the PCI buses.
569	*
570	* @returns VBox status.
571	* @param pDevIns Device instance of the first bus.
572	* @remarks Caller enters the PDM critical section.
573	*/
574	DECLR3CALLBACKMEMBER(int, pfnFakePCIBIOSR3,(PPDMDEVINS pDevIns));
575
576	/** The name of the SetIrq RC entry point. */
577	const char *pszSetIrqRC;
578
579	/** The name of the SetIrq R0 entry point. */
580	const char *pszSetIrqR0;
581
582	} PDMPCIBUSREG;
583	/** Pointer to a PCI bus registration structure. */
584	typedef PDMPCIBUSREG *PPDMPCIBUSREG;
585
586	/** Current PDMPCIBUSREG version number. */
587	#define PDM_PCIBUSREG_VERSION PDM_VERSION_MAKE(0xfffe, 4, 0)
588
589	/**
590	* PCI Bus RC helpers.
591	*/
592	typedef struct PDMPCIHLPRC
593	{
594	/** Structure version. PDM_PCIHLPRC_VERSION defines the current version. */
595	uint32_t u32Version;
596
597	/**
598	* Set an ISA IRQ.
599	*
600	* @param pDevIns PCI device instance.
601	* @param iIrq IRQ number to set.
602	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
603	* @param uTagSrc The IRQ tag and source (for tracing).
604	* @thread EMT only.
605	*/
606	DECLRCCALLBACKMEMBER(void, pfnIsaSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel, uint32_t uTagSrc));
607
608	/**
609	* Set an I/O-APIC IRQ.
610	*
611	* @param pDevIns PCI device instance.
612	* @param iIrq IRQ number to set.
613	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
614	* @param uTagSrc The IRQ tag and source (for tracing).
615	* @thread EMT only.
616	*/
617	DECLRCCALLBACKMEMBER(void, pfnIoApicSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel, uint32_t uTagSrc));
618
619	/**
620	* Send an MSI.
621	*
622	* @param pDevIns PCI device instance.
623	* @param GCPhys Physical address MSI request was written.
624	* @param uValue Value written.
625	* @param uTagSrc The IRQ tag and source (for tracing).
626	* @thread EMT only.
627	*/
628	DECLRCCALLBACKMEMBER(void, pfnIoApicSendMsi,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, uint32_t uValue, uint32_t uTagSrc));
629
630
631	/**
632	* Acquires the PDM lock.
633	*
634	* @returns VINF_SUCCESS on success.
635	* @returns rc if we failed to acquire the lock.
636	* @param pDevIns The PCI device instance.
637	* @param rc What to return if we fail to acquire the lock.
638	*/
639	DECLRCCALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
640
641	/**
642	* Releases the PDM lock.
643	*
644	* @param pDevIns The PCI device instance.
645	*/
646	DECLRCCALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
647
648	/** Just a safety precaution. */
649	uint32_t u32TheEnd;
650	} PDMPCIHLPRC;
651	/** Pointer to PCI helpers. */
652	typedef RCPTRTYPE(PDMPCIHLPRC *) PPDMPCIHLPRC;
653	/** Pointer to const PCI helpers. */
654	typedef RCPTRTYPE(const PDMPCIHLPRC *) PCPDMPCIHLPRC;
655
656	/** Current PDMPCIHLPRC version number. */
657	#define PDM_PCIHLPRC_VERSION PDM_VERSION_MAKE(0xfffd, 3, 0)
658
659
660	/**
661	* PCI Bus R0 helpers.
662	*/
663	typedef struct PDMPCIHLPR0
664	{
665	/** Structure version. PDM_PCIHLPR0_VERSION defines the current version. */
666	uint32_t u32Version;
667
668	/**
669	* Set an ISA IRQ.
670	*
671	* @param pDevIns PCI device instance.
672	* @param iIrq IRQ number to set.
673	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
674	* @param uTagSrc The IRQ tag and source (for tracing).
675	* @thread EMT only.
676	*/
677	DECLR0CALLBACKMEMBER(void, pfnIsaSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel, uint32_t uTagSrc));
678
679	/**
680	* Set an I/O-APIC IRQ.
681	*
682	* @param pDevIns PCI device instance.
683	* @param iIrq IRQ number to set.
684	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
685	* @param uTagSrc The IRQ tag and source (for tracing).
686	* @thread EMT only.
687	*/
688	DECLR0CALLBACKMEMBER(void, pfnIoApicSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel, uint32_t uTagSrc));
689
690	/**
691	* Send an MSI.
692	*
693	* @param pDevIns PCI device instance.
694	* @param GCPhys Physical address MSI request was written.
695	* @param uValue Value written.
696	* @param uTagSrc The IRQ tag and source (for tracing).
697	* @thread EMT only.
698	*/
699	DECLR0CALLBACKMEMBER(void, pfnIoApicSendMsi,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, uint32_t uValue, uint32_t uTagSrc));
700
701
702	/**
703	* Acquires the PDM lock.
704	*
705	* @returns VINF_SUCCESS on success.
706	* @returns rc if we failed to acquire the lock.
707	* @param pDevIns The PCI device instance.
708	* @param rc What to return if we fail to acquire the lock.
709	*/
710	DECLR0CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
711
712	/**
713	* Releases the PDM lock.
714	*
715	* @param pDevIns The PCI device instance.
716	*/
717	DECLR0CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
718
719	/** Just a safety precaution. */
720	uint32_t u32TheEnd;
721	} PDMPCIHLPR0;
722	/** Pointer to PCI helpers. */
723	typedef R0PTRTYPE(PDMPCIHLPR0 *) PPDMPCIHLPR0;
724	/** Pointer to const PCI helpers. */
725	typedef R0PTRTYPE(const PDMPCIHLPR0 *) PCPDMPCIHLPR0;
726
727	/** Current PDMPCIHLPR0 version number. */
728	#define PDM_PCIHLPR0_VERSION PDM_VERSION_MAKE(0xfffc, 3, 0)
729
730	/**
731	* PCI device helpers.
732	*/
733	typedef struct PDMPCIHLPR3
734	{
735	/** Structure version. PDM_PCIHLPR3_VERSION defines the current version. */
736	uint32_t u32Version;
737
738	/**
739	* Set an ISA IRQ.
740	*
741	* @param pDevIns The PCI device instance.
742	* @param iIrq IRQ number to set.
743	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
744	* @param uTagSrc The IRQ tag and source (for tracing).
745	*/
746	DECLR3CALLBACKMEMBER(void, pfnIsaSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel, uint32_t uTagSrc));
747
748	/**
749	* Set an I/O-APIC IRQ.
750	*
751	* @param pDevIns The PCI device instance.
752	* @param iIrq IRQ number to set.
753	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
754	* @param uTagSrc The IRQ tag and source (for tracing).
755	*/
756	DECLR3CALLBACKMEMBER(void, pfnIoApicSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel, uint32_t uTagSrc));
757
758	/**
759	* Send an MSI.
760	*
761	* @param pDevIns PCI device instance.
762	* @param GCPhys Physical address MSI request was written.
763	* @param uValue Value written.
764	* @param uTagSrc The IRQ tag and source (for tracing).
765	*/
766	DECLR3CALLBACKMEMBER(void, pfnIoApicSendMsi,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, uint32_t uValue, uint32_t uTagSrc));
767
768	/**
769	* Checks if the given address is an MMIO2 base address or not.
770	*
771	* @returns true/false accordingly.
772	* @param pDevIns The PCI device instance.
773	* @param pOwner The owner of the memory, optional.
774	* @param GCPhys The address to check.
775	*/
776	DECLR3CALLBACKMEMBER(bool, pfnIsMMIO2Base,(PPDMDEVINS pDevIns, PPDMDEVINS pOwner, RTGCPHYS GCPhys));
777
778	/**
779	* Gets the address of the RC PCI Bus helpers.
780	*
781	* This should be called at both construction and relocation time
782	* to obtain the correct address of the RC helpers.
783	*
784	* @returns RC pointer to the PCI Bus helpers.
785	* @param pDevIns Device instance of the PCI Bus.
786	* @thread EMT only.
787	*/
788	DECLR3CALLBACKMEMBER(PCPDMPCIHLPRC, pfnGetRCHelpers,(PPDMDEVINS pDevIns));
789
790	/**
791	* Gets the address of the R0 PCI Bus helpers.
792	*
793	* This should be called at both construction and relocation time
794	* to obtain the correct address of the R0 helpers.
795	*
796	* @returns R0 pointer to the PCI Bus helpers.
797	* @param pDevIns Device instance of the PCI Bus.
798	* @thread EMT only.
799	*/
800	DECLR3CALLBACKMEMBER(PCPDMPCIHLPR0, pfnGetR0Helpers,(PPDMDEVINS pDevIns));
801
802	/**
803	* Acquires the PDM lock.
804	*
805	* @returns VINF_SUCCESS on success.
806	* @returns Fatal error on failure.
807	* @param pDevIns The PCI device instance.
808	* @param rc Dummy for making the interface identical to the RC and R0 versions.
809	*/
810	DECLR3CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
811
812	/**
813	* Releases the PDM lock.
814	*
815	* @param pDevIns The PCI device instance.
816	*/
817	DECLR3CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
818
819	/** Just a safety precaution. */
820	uint32_t u32TheEnd;
821	} PDMPCIHLPR3;
822	/** Pointer to PCI helpers. */
823	typedef R3PTRTYPE(PDMPCIHLPR3 *) PPDMPCIHLPR3;
824	/** Pointer to const PCI helpers. */
825	typedef R3PTRTYPE(const PDMPCIHLPR3 *) PCPDMPCIHLPR3;
826
827	/** Current PDMPCIHLPR3 version number. */
828	#define PDM_PCIHLPR3_VERSION PDM_VERSION_MAKE(0xfffb, 3, 0)
829
830
831	/**
832	* Programmable Interrupt Controller registration structure.
833	*/
834	typedef struct PDMPICREG
835	{
836	/** Structure version number. PDM_PICREG_VERSION defines the current version. */
837	uint32_t u32Version;
838
839	/**
840	* Set the an IRQ.
841	*
842	* @param pDevIns Device instance of the PIC.
843	* @param iIrq IRQ number to set.
844	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
845	* @param uTagSrc The IRQ tag and source (for tracing).
846	* @remarks Caller enters the PDM critical section.
847	*/
848	DECLR3CALLBACKMEMBER(void, pfnSetIrqR3,(PPDMDEVINS pDevIns, int iIrq, int iLevel, uint32_t uTagSrc));
849
850	/**
851	* Get a pending interrupt.
852	*
853	* @returns Pending interrupt number.
854	* @param pDevIns Device instance of the PIC.
855	* @param puTagSrc Where to return the IRQ tag and source.
856	* @remarks Caller enters the PDM critical section.
857	*/
858	DECLR3CALLBACKMEMBER(int, pfnGetInterruptR3,(PPDMDEVINS pDevIns, uint32_t *puTagSrc));
859
860	/** The name of the RC SetIrq entry point. */
861	const char *pszSetIrqRC;
862	/** The name of the RC GetInterrupt entry point. */
863	const char *pszGetInterruptRC;
864
865	/** The name of the R0 SetIrq entry point. */
866	const char *pszSetIrqR0;
867	/** The name of the R0 GetInterrupt entry point. */
868	const char *pszGetInterruptR0;
869	} PDMPICREG;
870	/** Pointer to a PIC registration structure. */
871	typedef PDMPICREG *PPDMPICREG;
872
873	/** Current PDMPICREG version number. */
874	#define PDM_PICREG_VERSION PDM_VERSION_MAKE(0xfffa, 2, 0)
875
876	/**
877	* PIC RC helpers.
878	*/
879	typedef struct PDMPICHLPRC
880	{
881	/** Structure version. PDM_PICHLPRC_VERSION defines the current version. */
882	uint32_t u32Version;
883
884	/**
885	* Set the interrupt force action flag.
886	*
887	* @param pDevIns Device instance of the PIC.
888	*/
889	DECLRCCALLBACKMEMBER(void, pfnSetInterruptFF,(PPDMDEVINS pDevIns));
890
891	/**
892	* Clear the interrupt force action flag.
893	*
894	* @param pDevIns Device instance of the PIC.
895	*/
896	DECLRCCALLBACKMEMBER(void, pfnClearInterruptFF,(PPDMDEVINS pDevIns));
897
898	/**
899	* Acquires the PDM lock.
900	*
901	* @returns VINF_SUCCESS on success.
902	* @returns rc if we failed to acquire the lock.
903	* @param pDevIns The PIC device instance.
904	* @param rc What to return if we fail to acquire the lock.
905	*/
906	DECLRCCALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
907
908	/**
909	* Releases the PDM lock.
910	*
911	* @param pDevIns The PIC device instance.
912	*/
913	DECLRCCALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
914
915	/** Just a safety precaution. */
916	uint32_t u32TheEnd;
917	} PDMPICHLPRC;
918
919	/** Pointer to PIC RC helpers. */
920	typedef RCPTRTYPE(PDMPICHLPRC *) PPDMPICHLPRC;
921	/** Pointer to const PIC RC helpers. */
922	typedef RCPTRTYPE(const PDMPICHLPRC *) PCPDMPICHLPRC;
923
924	/** Current PDMPICHLPRC version number. */
925	#define PDM_PICHLPRC_VERSION PDM_VERSION_MAKE(0xfff9, 2, 0)
926
927
928	/**
929	* PIC R0 helpers.
930	*/
931	typedef struct PDMPICHLPR0
932	{
933	/** Structure version. PDM_PICHLPR0_VERSION defines the current version. */
934	uint32_t u32Version;
935
936	/**
937	* Set the interrupt force action flag.
938	*
939	* @param pDevIns Device instance of the PIC.
940	*/
941	DECLR0CALLBACKMEMBER(void, pfnSetInterruptFF,(PPDMDEVINS pDevIns));
942
943	/**
944	* Clear the interrupt force action flag.
945	*
946	* @param pDevIns Device instance of the PIC.
947	*/
948	DECLR0CALLBACKMEMBER(void, pfnClearInterruptFF,(PPDMDEVINS pDevIns));
949
950	/**
951	* Acquires the PDM lock.
952	*
953	* @returns VINF_SUCCESS on success.
954	* @returns rc if we failed to acquire the lock.
955	* @param pDevIns The PIC device instance.
956	* @param rc What to return if we fail to acquire the lock.
957	*/
958	DECLR0CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
959
960	/**
961	* Releases the PDM lock.
962	*
963	* @param pDevIns The PCI device instance.
964	*/
965	DECLR0CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
966
967	/** Just a safety precaution. */
968	uint32_t u32TheEnd;
969	} PDMPICHLPR0;
970
971	/** Pointer to PIC R0 helpers. */
972	typedef R0PTRTYPE(PDMPICHLPR0 *) PPDMPICHLPR0;
973	/** Pointer to const PIC R0 helpers. */
974	typedef R0PTRTYPE(const PDMPICHLPR0 *) PCPDMPICHLPR0;
975
976	/** Current PDMPICHLPR0 version number. */
977	#define PDM_PICHLPR0_VERSION PDM_VERSION_MAKE(0xfff8, 1, 0)
978
979	/**
980	* PIC R3 helpers.
981	*/
982	typedef struct PDMPICHLPR3
983	{
984	/** Structure version. PDM_PICHLP_VERSION defines the current version. */
985	uint32_t u32Version;
986
987	/**
988	* Set the interrupt force action flag.
989	*
990	* @param pDevIns Device instance of the PIC.
991	*/
992	DECLR3CALLBACKMEMBER(void, pfnSetInterruptFF,(PPDMDEVINS pDevIns));
993
994	/**
995	* Clear the interrupt force action flag.
996	*
997	* @param pDevIns Device instance of the PIC.
998	*/
999	DECLR3CALLBACKMEMBER(void, pfnClearInterruptFF,(PPDMDEVINS pDevIns));
1000
1001	/**
1002	* Acquires the PDM lock.
1003	*
1004	* @returns VINF_SUCCESS on success.
1005	* @returns Fatal error on failure.
1006	* @param pDevIns The PIC device instance.
1007	* @param rc Dummy for making the interface identical to the RC and R0 versions.
1008	*/
1009	DECLR3CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
1010
1011	/**
1012	* Releases the PDM lock.
1013	*
1014	* @param pDevIns The PIC device instance.
1015	*/
1016	DECLR3CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
1017
1018	/**
1019	* Gets the address of the RC PIC helpers.
1020	*
1021	* This should be called at both construction and relocation time
1022	* to obtain the correct address of the RC helpers.
1023	*
1024	* @returns RC pointer to the PIC helpers.
1025	* @param pDevIns Device instance of the PIC.
1026	*/
1027	DECLR3CALLBACKMEMBER(PCPDMPICHLPRC, pfnGetRCHelpers,(PPDMDEVINS pDevIns));
1028
1029	/**
1030	* Gets the address of the R0 PIC helpers.
1031	*
1032	* This should be called at both construction and relocation time
1033	* to obtain the correct address of the R0 helpers.
1034	*
1035	* @returns R0 pointer to the PIC helpers.
1036	* @param pDevIns Device instance of the PIC.
1037	*/
1038	DECLR3CALLBACKMEMBER(PCPDMPICHLPR0, pfnGetR0Helpers,(PPDMDEVINS pDevIns));
1039
1040	/** Just a safety precaution. */
1041	uint32_t u32TheEnd;
1042	} PDMPICHLPR3;
1043
1044	/** Pointer to PIC R3 helpers. */
1045	typedef R3PTRTYPE(PDMPICHLPR3 *) PPDMPICHLPR3;
1046	/** Pointer to const PIC R3 helpers. */
1047	typedef R3PTRTYPE(const PDMPICHLPR3 *) PCPDMPICHLPR3;
1048
1049	/** Current PDMPICHLPR3 version number. */
1050	#define PDM_PICHLPR3_VERSION PDM_VERSION_MAKE(0xfff7, 1, 0)
1051
1052
1053
1054	/**
1055	* Advanced Programmable Interrupt Controller registration structure.
1056	*/
1057	typedef struct PDMAPICREG
1058	{
1059	/** Structure version number. PDM_APICREG_VERSION defines the current version. */
1060	uint32_t u32Version;
1061
1062	/**
1063	* Get a pending interrupt.
1064	*
1065	* @returns Pending interrupt number.
1066	* @param pDevIns Device instance of the APIC.
1067	* @param idCpu The VCPU Id.
1068	* @param puTagSrc Where to return the tag source.
1069	* @remarks Caller enters the PDM critical section
1070	*/
1071	DECLR3CALLBACKMEMBER(int, pfnGetInterruptR3,(PPDMDEVINS pDevIns, VMCPUID idCpu, uint32_t *puTagSrc));
1072
1073	/**
1074	* Check if the APIC has a pending interrupt/if a TPR change would active one
1075	*
1076	* @returns Pending interrupt yes/no
1077	* @param pDevIns Device instance of the APIC.
1078	* @param idCpu The VCPU Id.
1079	* @param pu8PendingIrq Where to store the highest priority pending IRQ
1080	* (optional, can be NULL).
1081	* @remarks Unlike the other callbacks, the PDM lock may not always be entered
1082	* prior to calling this method.
1083	*/
1084	DECLR3CALLBACKMEMBER(bool, pfnHasPendingIrqR3,(PPDMDEVINS pDevIns, VMCPUID idCpu, uint8_t *pu8PendingIrq));
1085
1086	/**
1087	* Set the APIC base.
1088	*
1089	* @param pDevIns Device instance of the APIC.
1090	* @param idCpu The VCPU Id.
1091	* @param u64Base The new base.
1092	* @remarks Caller enters the PDM critical section.
1093	*/
1094	DECLR3CALLBACKMEMBER(void, pfnSetBaseR3,(PPDMDEVINS pDevIns, VMCPUID idCpu, uint64_t u64Base));
1095
1096	/**
1097	* Get the APIC base.
1098	*
1099	* @returns Current base.
1100	* @param pDevIns Device instance of the APIC.
1101	* @param idCpu The VCPU Id.
1102	* @remarks Caller enters the PDM critical section.
1103	*/
1104	DECLR3CALLBACKMEMBER(uint64_t, pfnGetBaseR3,(PPDMDEVINS pDevIns, VMCPUID idCpu));
1105
1106	/**
1107	* Set the TPR (task priority register).
1108	*
1109	* @param pDevIns Device instance of the APIC.
1110	* @param idCpu The VCPU id.
1111	* @param u8TPR The new TPR.
1112	* @remarks Caller enters the PDM critical section.
1113	*/
1114	DECLR3CALLBACKMEMBER(void, pfnSetTPRR3,(PPDMDEVINS pDevIns, VMCPUID idCpu, uint8_t u8TPR));
1115
1116	/**
1117	* Get the TPR (task priority register).
1118	*
1119	* @returns The current TPR.
1120	* @param pDevIns Device instance of the APIC.
1121	* @param idCpu VCPU id
1122	* @remarks Caller enters the PDM critical section.
1123	*/
1124	DECLR3CALLBACKMEMBER(uint8_t, pfnGetTPRR3,(PPDMDEVINS pDevIns, VMCPUID idCpu));
1125
1126	/**
1127	* Write to a MSR in APIC range.
1128	*
1129	* @returns VBox status code.
1130	* @param pDevIns Device instance of the APIC.
1131	* @param idCpu Target CPU.
1132	* @param u32Reg The MSR begin written to.
1133	* @param u64Value The value to write.
1134	*
1135	* @remarks Unlike the other callbacks, the PDM lock is not taken before
1136	* calling this method.
1137	*/
1138	DECLR3CALLBACKMEMBER(int, pfnWriteMSRR3, (PPDMDEVINS pDevIns, VMCPUID idCpu, uint32_t u32Reg, uint64_t u64Value));
1139
1140	/**
1141	* Read from a MSR in APIC range.
1142	*
1143	* @returns VBox status code.
1144	* @param pDevIns Device instance of the APIC.
1145	* @param idCpu Target CPU.
1146	* @param u32Reg MSR to read.
1147	* @param pu64Value Where to return the read value.
1148	*
1149	* @remarks Unlike the other callbacks, the PDM lock is not taken before
1150	* calling this method.
1151	*/
1152	DECLR3CALLBACKMEMBER(int, pfnReadMSRR3, (PPDMDEVINS pDevIns, VMCPUID idCpu, uint32_t u32Reg, uint64_t *pu64Value));
1153
1154	/**
1155	* Private interface between the IOAPIC and APIC.
1156	*
1157	* This is a low-level, APIC/IOAPIC implementation specific interface which
1158	* is registered with PDM only because it makes life so much simpler right
1159	* now (GC bits). This is a bad bad hack! The correct way of doing this
1160	* would involve some way of querying GC interfaces and relocating them.
1161	* Perhaps doing some kind of device init in GC...
1162	*
1163	* @returns status code.
1164	* @param pDevIns Device instance of the APIC.
1165	* @param u8Dest See APIC implementation.
1166	* @param u8DestMode See APIC implementation.
1167	* @param u8DeliveryMode See APIC implementation.
1168	* @param iVector See APIC implementation.
1169	* @param u8Polarity See APIC implementation.
1170	* @param u8TriggerMode See APIC implementation.
1171	* @param uTagSrc The IRQ tag and source (for tracing).
1172	* @remarks Caller enters the PDM critical section
1173	*/
1174	DECLR3CALLBACKMEMBER(int, pfnBusDeliverR3,(PPDMDEVINS pDevIns, uint8_t u8Dest, uint8_t u8DestMode, uint8_t u8DeliveryMode,
1175	uint8_t iVector, uint8_t u8Polarity, uint8_t u8TriggerMode, uint32_t uTagSrc));
1176
1177	/**
1178	* Deliver a signal to CPU's local interrupt pins (LINT0/LINT1).
1179	*
1180	* Used for virtual wire mode when interrupts from the PIC are passed through
1181	* LAPIC.
1182	*
1183	* @returns status code.
1184	* @param pDevIns Device instance of the APIC.
1185	* @param u8Pin Local pin number (0 or 1 for current CPUs).
1186	* @param u8Level The level.
1187	* @param uTagSrc The IRQ tag and source (for tracing).
1188	* @remarks Caller enters the PDM critical section
1189	*/
1190	DECLR3CALLBACKMEMBER(int, pfnLocalInterruptR3,(PPDMDEVINS pDevIns, uint8_t u8Pin, uint8_t u8Level));
1191
1192	/**
1193	* Get the APIC timer frequency (in Hz).
1194	*
1195	* @returns The frequency of the APIC timer.
1196	* @param pDevIns Device instance of the APIC.
1197	*/
1198	DECLR3CALLBACKMEMBER(uint64_t, pfnGetTimerFreqR3, (PPDMDEVINS pDevIns));
1199
1200	/** The name of the RC GetInterrupt entry point. */
1201	const char *pszGetInterruptRC;
1202	/** The name of the RC HasPendingIrq entry point. */
1203	const char *pszHasPendingIrqRC;
1204	/** The name of the RC SetBase entry point. */
1205	const char *pszSetBaseRC;
1206	/** The name of the RC GetBase entry point. */
1207	const char *pszGetBaseRC;
1208	/** The name of the RC SetTPR entry point. */
1209	const char *pszSetTPRRC;
1210	/** The name of the RC GetTPR entry point. */
1211	const char *pszGetTPRRC;
1212	/** The name of the RC WriteMSR entry point. */
1213	const char *pszWriteMSRRC;
1214	/** The name of the RC ReadMSR entry point. */
1215	const char *pszReadMSRRC;
1216	/** The name of the RC BusDeliver entry point. */
1217	const char *pszBusDeliverRC;
1218	/** The name of the RC LocalInterrupt entry point. */
1219	const char *pszLocalInterruptRC;
1220	/** The name of the RC GetTimerFreq entry point. */
1221	const char *pszGetTimerFreqRC;
1222
1223	/** The name of the R0 GetInterrupt entry point. */
1224	const char *pszGetInterruptR0;
1225	/** The name of the R0 HasPendingIrq entry point. */
1226	const char *pszHasPendingIrqR0;
1227	/** The name of the R0 SetBase entry point. */
1228	const char *pszSetBaseR0;
1229	/** The name of the R0 GetBase entry point. */
1230	const char *pszGetBaseR0;
1231	/** The name of the R0 SetTPR entry point. */
1232	const char *pszSetTPRR0;
1233	/** The name of the R0 GetTPR entry point. */
1234	const char *pszGetTPRR0;
1235	/** The name of the R0 WriteMSR entry point. */
1236	const char *pszWriteMSRR0;
1237	/** The name of the R0 ReadMSR entry point. */
1238	const char *pszReadMSRR0;
1239	/** The name of the R0 BusDeliver entry point. */
1240	const char *pszBusDeliverR0;
1241	/** The name of the R0 LocalInterrupt entry point. */
1242	const char *pszLocalInterruptR0;
1243	/** The name of the R0 GetTimerFreq entry point. */
1244	const char *pszGetTimerFreqR0;
1245	} PDMAPICREG;
1246	/** Pointer to an APIC registration structure. */
1247	typedef PDMAPICREG *PPDMAPICREG;
1248
1249	/** Current PDMAPICREG version number. */
1250	#define PDM_APICREG_VERSION PDM_VERSION_MAKE(0xfff6, 2, 0)
1251
1252
1253	/**
1254	* APIC version argument for pfnChangeFeature.
1255	*/
1256	typedef enum PDMAPICVERSION
1257	{
1258	/** Invalid 0 entry. */
1259	PDMAPICVERSION_INVALID = 0,
1260	/** No APIC. */
1261	PDMAPICVERSION_NONE,
1262	/** Standard APIC (X86_CPUID_FEATURE_EDX_APIC). */
1263	PDMAPICVERSION_APIC,
1264	/** Intel X2APIC (X86_CPUID_FEATURE_ECX_X2APIC). */
1265	PDMAPICVERSION_X2APIC,
1266	/** The usual 32-bit paranoia. */
1267	PDMAPICVERSION_32BIT_HACK = 0x7fffffff
1268	} PDMAPICVERSION;
1269
1270	/**
1271	* APIC irq argument for SetInterruptFF.
1272	*/
1273	typedef enum PDMAPICIRQ
1274	{
1275	/** Invalid 0 entry. */
1276	PDMAPICIRQ_INVALID = 0,
1277	/** Normal hardware interrupt. */
1278	PDMAPICIRQ_HARDWARE,
1279	/** NMI. */
1280	PDMAPICIRQ_NMI,
1281	/** SMI. */
1282	PDMAPICIRQ_SMI,
1283	/** ExtINT (HW interrupt via PIC). */
1284	PDMAPICIRQ_EXTINT,
1285	/** The usual 32-bit paranoia. */
1286	PDMAPICIRQ_32BIT_HACK = 0x7fffffff
1287	} PDMAPICIRQ;
1288
1289
1290	/**
1291	* APIC RC helpers.
1292	*/
1293	typedef struct PDMAPICHLPRC
1294	{
1295	/** Structure version. PDM_APICHLPRC_VERSION defines the current version. */
1296	uint32_t u32Version;
1297
1298	/**
1299	* Set the interrupt force action flag.
1300	*
1301	* @param pDevIns Device instance of the APIC.
1302	* @param enmType IRQ type.
1303	* @param idCpu Virtual CPU to set flag upon.
1304	*/
1305	DECLRCCALLBACKMEMBER(void, pfnSetInterruptFF,(PPDMDEVINS pDevIns, PDMAPICIRQ enmType, VMCPUID idCpu));
1306
1307	/**
1308	* Clear the interrupt force action flag.
1309	*
1310	* @param pDevIns Device instance of the APIC.
1311	* @param enmType IRQ type.
1312	* @param idCpu Virtual CPU to clear flag upon.
1313	*/
1314	DECLRCCALLBACKMEMBER(void, pfnClearInterruptFF,(PPDMDEVINS pDevIns, PDMAPICIRQ enmType, VMCPUID idCpu));
1315
1316	/**
1317	* Calculates an IRQ tag for a timer, IPI or similar event.
1318	*
1319	* @returns The IRQ tag.
1320	* @param pDevIns Device instance of the APIC.
1321	* @param u8Level PDM_IRQ_LEVEL_HIGH or PDM_IRQ_LEVEL_FLIP_FLOP.
1322	*/
1323	DECLRCCALLBACKMEMBER(uint32_t, pfnCalcIrqTag,(PPDMDEVINS pDevIns, uint8_t u8Level));
1324
1325	/**
1326	* Modifies APIC-related bits in the CPUID feature mask.
1327	*
1328	* @param pDevIns Device instance of the APIC.
1329	* @param enmVersion Supported APIC version.
1330	*/
1331	DECLRCCALLBACKMEMBER(void, pfnChangeFeature,(PPDMDEVINS pDevIns, PDMAPICVERSION enmVersion));
1332
1333	/**
1334	* Acquires the PDM lock.
1335	*
1336	* @returns VINF_SUCCESS on success.
1337	* @returns rc if we failed to acquire the lock.
1338	* @param pDevIns The APIC device instance.
1339	* @param rc What to return if we fail to acquire the lock.
1340	*/
1341	DECLRCCALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
1342
1343	/**
1344	* Releases the PDM lock.
1345	*
1346	* @param pDevIns The APIC device instance.
1347	*/
1348	DECLRCCALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
1349
1350	/**
1351	* Get the virtual CPU id corresponding to the current EMT.
1352	*
1353	* @param pDevIns The APIC device instance.
1354	*/
1355	DECLRCCALLBACKMEMBER(VMCPUID, pfnGetCpuId,(PPDMDEVINS pDevIns));
1356
1357	/** Just a safety precaution. */
1358	uint32_t u32TheEnd;
1359	} PDMAPICHLPRC;
1360	/** Pointer to APIC GC helpers. */
1361	typedef RCPTRTYPE(PDMAPICHLPRC *) PPDMAPICHLPRC;
1362	/** Pointer to const APIC helpers. */
1363	typedef RCPTRTYPE(const PDMAPICHLPRC *) PCPDMAPICHLPRC;
1364
1365	/** Current PDMAPICHLPRC version number. */
1366	#define PDM_APICHLPRC_VERSION PDM_VERSION_MAKE(0xfff5, 2, 0)
1367
1368
1369	/**
1370	* APIC R0 helpers.
1371	*/
1372	typedef struct PDMAPICHLPR0
1373	{
1374	/** Structure version. PDM_APICHLPR0_VERSION defines the current version. */
1375	uint32_t u32Version;
1376
1377	/**
1378	* Set the interrupt force action flag.
1379	*
1380	* @param pDevIns Device instance of the APIC.
1381	* @param enmType IRQ type.
1382	* @param idCpu Virtual CPU to set flag upon.
1383	*/
1384	DECLR0CALLBACKMEMBER(void, pfnSetInterruptFF,(PPDMDEVINS pDevIns, PDMAPICIRQ enmType, VMCPUID idCpu));
1385
1386	/**
1387	* Clear the interrupt force action flag.
1388	*
1389	* @param pDevIns Device instance of the APIC.
1390	* @param enmType IRQ type.
1391	* @param idCpu Virtual CPU to clear flag upon.
1392	*/
1393	DECLR0CALLBACKMEMBER(void, pfnClearInterruptFF,(PPDMDEVINS pDevIns, PDMAPICIRQ enmType, VMCPUID idCpu));
1394
1395	/**
1396	* Calculates an IRQ tag for a timer, IPI or similar event.
1397	*
1398	* @returns The IRQ tag.
1399	* @param pDevIns Device instance of the APIC.
1400	* @param u8Level PDM_IRQ_LEVEL_HIGH or PDM_IRQ_LEVEL_FLIP_FLOP.
1401	*/
1402	DECLR0CALLBACKMEMBER(uint32_t, pfnCalcIrqTag,(PPDMDEVINS pDevIns, uint8_t u8Level));
1403
1404	/**
1405	* Modifies APIC-related bits in the CPUID feature mask.
1406	*
1407	* @param pDevIns Device instance of the APIC.
1408	* @param enmVersion Supported APIC version.
1409	*/
1410	DECLR0CALLBACKMEMBER(void, pfnChangeFeature,(PPDMDEVINS pDevIns, PDMAPICVERSION enmVersion));
1411
1412	/**
1413	* Acquires the PDM lock.
1414	*
1415	* @returns VINF_SUCCESS on success.
1416	* @returns rc if we failed to acquire the lock.
1417	* @param pDevIns The APIC device instance.
1418	* @param rc What to return if we fail to acquire the lock.
1419	*/
1420	DECLR0CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
1421
1422	/**
1423	* Releases the PDM lock.
1424	*
1425	* @param pDevIns The APIC device instance.
1426	*/
1427	DECLR0CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
1428
1429	/**
1430	* Get the virtual CPU id corresponding to the current EMT.
1431	*
1432	* @param pDevIns The APIC device instance.
1433	*/
1434	DECLR0CALLBACKMEMBER(VMCPUID, pfnGetCpuId,(PPDMDEVINS pDevIns));
1435
1436	/** Just a safety precaution. */
1437	uint32_t u32TheEnd;
1438	} PDMAPICHLPR0;
1439	/** Pointer to APIC GC helpers. */
1440	typedef RCPTRTYPE(PDMAPICHLPR0 *) PPDMAPICHLPR0;
1441	/** Pointer to const APIC helpers. */
1442	typedef R0PTRTYPE(const PDMAPICHLPR0 *) PCPDMAPICHLPR0;
1443
1444	/** Current PDMAPICHLPR0 version number. */
1445	#define PDM_APICHLPR0_VERSION PDM_VERSION_MAKE(0xfff4, 2, 0)
1446
1447	/**
1448	* APIC R3 helpers.
1449	*/
1450	typedef struct PDMAPICHLPR3
1451	{
1452	/** Structure version. PDM_APICHLPR3_VERSION defines the current version. */
1453	uint32_t u32Version;
1454
1455	/**
1456	* Set the interrupt force action flag.
1457	*
1458	* @param pDevIns Device instance of the APIC.
1459	* @param enmType IRQ type.
1460	* @param idCpu Virtual CPU to set flag upon.
1461	*/
1462	DECLR3CALLBACKMEMBER(void, pfnSetInterruptFF,(PPDMDEVINS pDevIns, PDMAPICIRQ enmType, VMCPUID idCpu));
1463
1464	/**
1465	* Clear the interrupt force action flag.
1466	*
1467	* @param pDevIns Device instance of the APIC.
1468	* @param enmType IRQ type.
1469	* @param idCpu Virtual CPU to clear flag upon.
1470	*/
1471	DECLR3CALLBACKMEMBER(void, pfnClearInterruptFF,(PPDMDEVINS pDevIns, PDMAPICIRQ enmType, VMCPUID idCpu));
1472
1473	/**
1474	* Calculates an IRQ tag for a timer, IPI or similar event.
1475	*
1476	* @returns The IRQ tag.
1477	* @param pDevIns Device instance of the APIC.
1478	* @param u8Level PDM_IRQ_LEVEL_HIGH or PDM_IRQ_LEVEL_FLIP_FLOP.
1479	*/
1480	DECLR3CALLBACKMEMBER(uint32_t, pfnCalcIrqTag,(PPDMDEVINS pDevIns, uint8_t u8Level));
1481
1482	/**
1483	* Modifies APIC-related bits in the CPUID feature mask.
1484	*
1485	* @param pDevIns Device instance of the APIC.
1486	* @param enmVersion Supported APIC version.
1487	*/
1488	DECLR3CALLBACKMEMBER(void, pfnChangeFeature,(PPDMDEVINS pDevIns, PDMAPICVERSION enmVersion));
1489
1490	/**
1491	* Get the virtual CPU id corresponding to the current EMT.
1492	*
1493	* @param pDevIns The APIC device instance.
1494	*/
1495	DECLR3CALLBACKMEMBER(VMCPUID, pfnGetCpuId,(PPDMDEVINS pDevIns));
1496
1497	/**
1498	* Sends SIPI to given virtual CPU.
1499	*
1500	* @param pDevIns The APIC device instance.
1501	* @param idCpu Virtual CPU to perform SIPI on
1502	* @param iVector SIPI vector
1503	*/
1504	DECLR3CALLBACKMEMBER(void, pfnSendSipi,(PPDMDEVINS pDevIns, VMCPUID idCpu, uint32_t uVector));
1505
1506	/**
1507	* Sends init IPI to given virtual CPU, should result in reset and
1508	* halting till SIPI.
1509	*
1510	* @param pDevIns The APIC device instance.
1511	* @param idCpu Virtual CPU to perform SIPI on
1512	*/
1513	DECLR3CALLBACKMEMBER(void, pfnSendInitIpi,(PPDMDEVINS pDevIns, VMCPUID idCpu));
1514
1515	/**
1516	* Gets the address of the RC APIC helpers.
1517	*
1518	* This should be called at both construction and relocation time
1519	* to obtain the correct address of the RC helpers.
1520	*
1521	* @returns GC pointer to the APIC helpers.
1522	* @param pDevIns Device instance of the APIC.
1523	*/
1524	DECLR3CALLBACKMEMBER(PCPDMAPICHLPRC, pfnGetRCHelpers,(PPDMDEVINS pDevIns));
1525
1526	/**
1527	* Gets the address of the R0 APIC helpers.
1528	*
1529	* This should be called at both construction and relocation time
1530	* to obtain the correct address of the R0 helpers.
1531	*
1532	* @returns R0 pointer to the APIC helpers.
1533	* @param pDevIns Device instance of the APIC.
1534	*/
1535	DECLR3CALLBACKMEMBER(PCPDMAPICHLPR0, pfnGetR0Helpers,(PPDMDEVINS pDevIns));
1536
1537	/**
1538	* Get the critical section used to synchronize the PICs, PCI and stuff.
1539	*
1540	* @returns Ring-3 pointer to the critical section.
1541	* @param pDevIns The APIC device instance.
1542	*/
1543	DECLR3CALLBACKMEMBER(R3PTRTYPE(PPDMCRITSECT), pfnGetR3CritSect,(PPDMDEVINS pDevIns));
1544
1545	/**
1546	* Get the critical section used to synchronize the PICs, PCI and stuff.
1547	*
1548	* @returns Raw-mode context pointer to the critical section.
1549	* @param pDevIns The APIC device instance.
1550	*/
1551	DECLR3CALLBACKMEMBER(RCPTRTYPE(PPDMCRITSECT), pfnGetRCCritSect,(PPDMDEVINS pDevIns));
1552
1553	/**
1554	* Get the critical section used to synchronize the PICs, PCI and stuff.
1555	*
1556	* @returns Ring-0 pointer to the critical section.
1557	* @param pDevIns The APIC device instance.
1558	*/
1559	DECLR3CALLBACKMEMBER(R0PTRTYPE(PPDMCRITSECT), pfnGetR0CritSect,(PPDMDEVINS pDevIns));
1560
1561	/** Just a safety precaution. */
1562	uint32_t u32TheEnd;
1563	} PDMAPICHLPR3;
1564	/** Pointer to APIC helpers. */
1565	typedef R3PTRTYPE(PDMAPICHLPR3 *) PPDMAPICHLPR3;
1566	/** Pointer to const APIC helpers. */
1567	typedef R3PTRTYPE(const PDMAPICHLPR3 *) PCPDMAPICHLPR3;
1568
1569	/** Current PDMAPICHLP version number. */
1570	#define PDM_APICHLPR3_VERSION PDM_VERSION_MAKE(0xfff3, 2, 0)
1571
1572
1573	/**
1574	* I/O APIC registration structure.
1575	*/
1576	typedef struct PDMIOAPICREG
1577	{
1578	/** Struct version+magic number (PDM_IOAPICREG_VERSION). */
1579	uint32_t u32Version;
1580
1581	/**
1582	* Set the an IRQ.
1583	*
1584	* @param pDevIns Device instance of the I/O APIC.
1585	* @param iIrq IRQ number to set.
1586	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
1587	* @param uTagSrc The IRQ tag and source (for tracing).
1588	* @remarks Caller enters the PDM critical section
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	* @remarks Caller enters the PDM critical section
1606	*/
1607	DECLR3CALLBACKMEMBER(void, pfnSendMsiR3,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, uint32_t uValue, uint32_t uTagSrc));
1608
1609	/** The name of the RC SendMsi entry point. */
1610	const char *pszSendMsiRC;
1611
1612	/** The name of the R0 SendMsi entry point. */
1613	const char *pszSendMsiR0;
1614	} PDMIOAPICREG;
1615	/** Pointer to an APIC registration structure. */
1616	typedef PDMIOAPICREG *PPDMIOAPICREG;
1617
1618	/** Current PDMAPICREG version number. */
1619	#define PDM_IOAPICREG_VERSION PDM_VERSION_MAKE(0xfff2, 3, 0)
1620
1621
1622	/**
1623	* IOAPIC RC helpers.
1624	*/
1625	typedef struct PDMIOAPICHLPRC
1626	{
1627	/** Structure version. PDM_IOAPICHLPRC_VERSION defines the current version. */
1628	uint32_t u32Version;
1629
1630	/**
1631	* Private interface between the IOAPIC and APIC.
1632	*
1633	* See comments about this hack on PDMAPICREG::pfnBusDeliverR3.
1634	*
1635	* @returns status code.
1636	* @param pDevIns Device instance of the IOAPIC.
1637	* @param u8Dest See APIC implementation.
1638	* @param u8DestMode See APIC implementation.
1639	* @param u8DeliveryMode See APIC implementation.
1640	* @param iVector See APIC implementation.
1641	* @param u8Polarity See APIC implementation.
1642	* @param u8TriggerMode See APIC implementation.
1643	* @param uTagSrc The IRQ tag and source (for tracing).
1644	*/
1645	DECLRCCALLBACKMEMBER(int, pfnApicBusDeliver,(PPDMDEVINS pDevIns, uint8_t u8Dest, uint8_t u8DestMode, uint8_t u8DeliveryMode,
1646	uint8_t iVector, uint8_t u8Polarity, uint8_t u8TriggerMode, uint32_t uTagSrc));
1647
1648	/**
1649	* Acquires the PDM lock.
1650	*
1651	* @returns VINF_SUCCESS on success.
1652	* @returns rc if we failed to acquire the lock.
1653	* @param pDevIns The IOAPIC device instance.
1654	* @param rc What to return if we fail to acquire the lock.
1655	*/
1656	DECLRCCALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
1657
1658	/**
1659	* Releases the PDM lock.
1660	*
1661	* @param pDevIns The IOAPIC device instance.
1662	*/
1663	DECLRCCALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
1664
1665	/** Just a safety precaution. */
1666	uint32_t u32TheEnd;
1667	} PDMIOAPICHLPRC;
1668	/** Pointer to IOAPIC RC helpers. */
1669	typedef RCPTRTYPE(PDMIOAPICHLPRC *) PPDMIOAPICHLPRC;
1670	/** Pointer to const IOAPIC helpers. */
1671	typedef RCPTRTYPE(const PDMIOAPICHLPRC *) PCPDMIOAPICHLPRC;
1672
1673	/** Current PDMIOAPICHLPRC version number. */
1674	#define PDM_IOAPICHLPRC_VERSION PDM_VERSION_MAKE(0xfff1, 2, 0)
1675
1676
1677	/**
1678	* IOAPIC R0 helpers.
1679	*/
1680	typedef struct PDMIOAPICHLPR0
1681	{
1682	/** Structure version. PDM_IOAPICHLPR0_VERSION defines the current version. */
1683	uint32_t u32Version;
1684
1685	/**
1686	* Private interface between the IOAPIC and APIC.
1687	*
1688	* See comments about this hack on PDMAPICREG::pfnBusDeliverR3.
1689	*
1690	* @returns status code.
1691	* @param pDevIns Device instance of the IOAPIC.
1692	* @param u8Dest See APIC implementation.
1693	* @param u8DestMode See APIC implementation.
1694	* @param u8DeliveryMode See APIC implementation.
1695	* @param iVector See APIC implementation.
1696	* @param u8Polarity See APIC implementation.
1697	* @param u8TriggerMode See APIC implementation.
1698	* @param uTagSrc The IRQ tag and source (for tracing).
1699	*/
1700	DECLR0CALLBACKMEMBER(int, pfnApicBusDeliver,(PPDMDEVINS pDevIns, uint8_t u8Dest, uint8_t u8DestMode, uint8_t u8DeliveryMode,
1701	uint8_t iVector, uint8_t u8Polarity, uint8_t u8TriggerMode, uint32_t uTagSrc));
1702
1703	/**
1704	* Acquires the PDM lock.
1705	*
1706	* @returns VINF_SUCCESS on success.
1707	* @returns rc if we failed to acquire the lock.
1708	* @param pDevIns The IOAPIC device instance.
1709	* @param rc What to return if we fail to acquire the lock.
1710	*/
1711	DECLR0CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
1712
1713	/**
1714	* Releases the PDM lock.
1715	*
1716	* @param pDevIns The IOAPIC device instance.
1717	*/
1718	DECLR0CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
1719
1720	/** Just a safety precaution. */
1721	uint32_t u32TheEnd;
1722	} PDMIOAPICHLPR0;
1723	/** Pointer to IOAPIC R0 helpers. */
1724	typedef R0PTRTYPE(PDMIOAPICHLPR0 *) PPDMIOAPICHLPR0;
1725	/** Pointer to const IOAPIC helpers. */
1726	typedef R0PTRTYPE(const PDMIOAPICHLPR0 *) PCPDMIOAPICHLPR0;
1727
1728	/** Current PDMIOAPICHLPR0 version number. */
1729	#define PDM_IOAPICHLPR0_VERSION PDM_VERSION_MAKE(0xfff0, 2, 0)
1730
1731	/**
1732	* IOAPIC R3 helpers.
1733	*/
1734	typedef struct PDMIOAPICHLPR3
1735	{
1736	/** Structure version. PDM_IOAPICHLPR3_VERSION defines the current version. */
1737	uint32_t u32Version;
1738
1739	/**
1740	* Private interface between the IOAPIC and APIC.
1741	*
1742	* See comments about this hack on PDMAPICREG::pfnBusDeliverR3.
1743	*
1744	* @returns status code
1745	* @param pDevIns Device instance of the IOAPIC.
1746	* @param u8Dest See APIC implementation.
1747	* @param u8DestMode See APIC implementation.
1748	* @param u8DeliveryMode See APIC implementation.
1749	* @param iVector See APIC implementation.
1750	* @param u8Polarity See APIC implementation.
1751	* @param u8TriggerMode See APIC implementation.
1752	* @param uTagSrc The IRQ tag and source (for tracing).
1753	*/
1754	DECLR3CALLBACKMEMBER(int, pfnApicBusDeliver,(PPDMDEVINS pDevIns, uint8_t u8Dest, uint8_t u8DestMode, uint8_t u8DeliveryMode,
1755	uint8_t iVector, uint8_t u8Polarity, uint8_t u8TriggerMode, uint32_t uTagSrc));
1756
1757	/**
1758	* Acquires the PDM lock.
1759	*
1760	* @returns VINF_SUCCESS on success.
1761	* @returns Fatal error on failure.
1762	* @param pDevIns The IOAPIC device instance.
1763	* @param rc Dummy for making the interface identical to the GC and R0 versions.
1764	*/
1765	DECLR3CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
1766
1767	/**
1768	* Releases the PDM lock.
1769	*
1770	* @param pDevIns The IOAPIC device instance.
1771	*/
1772	DECLR3CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
1773
1774	/**
1775	* Gets the address of the RC IOAPIC helpers.
1776	*
1777	* This should be called at both construction and relocation time
1778	* to obtain the correct address of the RC helpers.
1779	*
1780	* @returns RC pointer to the IOAPIC helpers.
1781	* @param pDevIns Device instance of the IOAPIC.
1782	*/
1783	DECLR3CALLBACKMEMBER(PCPDMIOAPICHLPRC, pfnGetRCHelpers,(PPDMDEVINS pDevIns));
1784
1785	/**
1786	* Gets the address of the R0 IOAPIC helpers.
1787	*
1788	* This should be called at both construction and relocation time
1789	* to obtain the correct address of the R0 helpers.
1790	*
1791	* @returns R0 pointer to the IOAPIC helpers.
1792	* @param pDevIns Device instance of the IOAPIC.
1793	*/
1794	DECLR3CALLBACKMEMBER(PCPDMIOAPICHLPR0, pfnGetR0Helpers,(PPDMDEVINS pDevIns));
1795
1796	/** Just a safety precaution. */
1797	uint32_t u32TheEnd;
1798	} PDMIOAPICHLPR3;
1799	/** Pointer to IOAPIC R3 helpers. */
1800	typedef R3PTRTYPE(PDMIOAPICHLPR3 *) PPDMIOAPICHLPR3;
1801	/** Pointer to const IOAPIC helpers. */
1802	typedef R3PTRTYPE(const PDMIOAPICHLPR3 *) PCPDMIOAPICHLPR3;
1803
1804	/** Current PDMIOAPICHLPR3 version number. */
1805	#define PDM_IOAPICHLPR3_VERSION PDM_VERSION_MAKE(0xffef, 2, 0)
1806
1807
1808	/**
1809	* HPET registration structure.
1810	*/
1811	typedef struct PDMHPETREG
1812	{
1813	/** Struct version+magic number (PDM_HPETREG_VERSION). */
1814	uint32_t u32Version;
1815
1816	} PDMHPETREG;
1817	/** Pointer to an HPET registration structure. */
1818	typedef PDMHPETREG *PPDMHPETREG;
1819
1820	/** Current PDMHPETREG version number. */
1821	#define PDM_HPETREG_VERSION PDM_VERSION_MAKE(0xffe2, 1, 0)
1822
1823	/**
1824	* HPET RC helpers.
1825	*
1826	* @remarks Keep this around in case HPET will need PDM interaction in again RC
1827	* at some later point.
1828	*/
1829	typedef struct PDMHPETHLPRC
1830	{
1831	/** Structure version. PDM_HPETHLPRC_VERSION defines the current version. */
1832	uint32_t u32Version;
1833
1834	/** Just a safety precaution. */
1835	uint32_t u32TheEnd;
1836	} PDMHPETHLPRC;
1837
1838	/** Pointer to HPET RC helpers. */
1839	typedef RCPTRTYPE(PDMHPETHLPRC *) PPDMHPETHLPRC;
1840	/** Pointer to const HPET RC helpers. */
1841	typedef RCPTRTYPE(const PDMHPETHLPRC *) PCPDMHPETHLPRC;
1842
1843	/** Current PDMHPETHLPRC version number. */
1844	#define PDM_HPETHLPRC_VERSION PDM_VERSION_MAKE(0xffee, 2, 0)
1845
1846
1847	/**
1848	* HPET R0 helpers.
1849	*
1850	* @remarks Keep this around in case HPET will need PDM interaction in again R0
1851	* at some later point.
1852	*/
1853	typedef struct PDMHPETHLPR0
1854	{
1855	/** Structure version. PDM_HPETHLPR0_VERSION defines the current version. */
1856	uint32_t u32Version;
1857
1858	/** Just a safety precaution. */
1859	uint32_t u32TheEnd;
1860	} PDMHPETHLPR0;
1861
1862	/** Pointer to HPET R0 helpers. */
1863	typedef R0PTRTYPE(PDMHPETHLPR0 *) PPDMHPETHLPR0;
1864	/** Pointer to const HPET R0 helpers. */
1865	typedef R0PTRTYPE(const PDMHPETHLPR0 *) PCPDMHPETHLPR0;
1866
1867	/** Current PDMHPETHLPR0 version number. */
1868	#define PDM_HPETHLPR0_VERSION PDM_VERSION_MAKE(0xffed, 2, 0)
1869
1870	/**
1871	* HPET R3 helpers.
1872	*/
1873	typedef struct PDMHPETHLPR3
1874	{
1875	/** Structure version. PDM_HPETHLP_VERSION defines the current version. */
1876	uint32_t u32Version;
1877
1878	/**
1879	* Gets the address of the RC HPET helpers.
1880	*
1881	* This should be called at both construction and relocation time
1882	* to obtain the correct address of the RC helpers.
1883	*
1884	* @returns RC pointer to the HPET helpers.
1885	* @param pDevIns Device instance of the HPET.
1886	*/
1887	DECLR3CALLBACKMEMBER(PCPDMHPETHLPRC, pfnGetRCHelpers,(PPDMDEVINS pDevIns));
1888
1889	/**
1890	* Gets the address of the R0 HPET helpers.
1891	*
1892	* This should be called at both construction and relocation time
1893	* to obtain the correct address of the R0 helpers.
1894	*
1895	* @returns R0 pointer to the HPET helpers.
1896	* @param pDevIns Device instance of the HPET.
1897	*/
1898	DECLR3CALLBACKMEMBER(PCPDMHPETHLPR0, pfnGetR0Helpers,(PPDMDEVINS pDevIns));
1899
1900	/**
1901	* Set legacy mode on PIT and RTC.
1902	*
1903	* @returns VINF_SUCCESS on success.
1904	* @returns rc if we failed to set legacy mode.
1905	* @param pDevIns Device instance of the HPET.
1906	* @param fActivated Whether legacy mode is activated or deactivated.
1907	*/
1908	DECLR3CALLBACKMEMBER(int, pfnSetLegacyMode,(PPDMDEVINS pDevIns, bool fActivated));
1909
1910
1911	/**
1912	* Set IRQ, bypassing ISA bus override rules.
1913	*
1914	* @returns VINF_SUCCESS on success.
1915	* @returns rc if we failed to set legacy mode.
1916	* @param pDevIns Device instance of the HPET.
1917	* @param fActivate Activate or deactivate legacy mode.
1918	*/
1919	DECLR3CALLBACKMEMBER(int, pfnSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
1920
1921	/** Just a safety precaution. */
1922	uint32_t u32TheEnd;
1923	} PDMHPETHLPR3;
1924
1925	/** Pointer to HPET R3 helpers. */
1926	typedef R3PTRTYPE(PDMHPETHLPR3 *) PPDMHPETHLPR3;
1927	/** Pointer to const HPET R3 helpers. */
1928	typedef R3PTRTYPE(const PDMHPETHLPR3 *) PCPDMHPETHLPR3;
1929
1930	/** Current PDMHPETHLPR3 version number. */
1931	#define PDM_HPETHLPR3_VERSION PDM_VERSION_MAKE(0xffec, 2, 0)
1932
1933
1934	/**
1935	* Raw PCI device registration structure.
1936	*/
1937	typedef struct PDMPCIRAWREG
1938	{
1939	/** Struct version+magic number (PDM_PCIRAWREG_VERSION). */
1940	uint32_t u32Version;
1941	/** Just a safety precaution. */
1942	uint32_t u32TheEnd;
1943	} PDMPCIRAWREG;
1944	/** Pointer to a raw PCI registration structure. */
1945	typedef PDMPCIRAWREG *PPDMPCIRAWREG;
1946
1947	/** Current PDMPCIRAWREG version number. */
1948	#define PDM_PCIRAWREG_VERSION PDM_VERSION_MAKE(0xffe1, 1, 0)
1949
1950	/**
1951	* Raw PCI device raw-mode context helpers.
1952	*/
1953	typedef struct PDMPCIRAWHLPRC
1954	{
1955	/** Structure version and magic number (PDM_PCIRAWHLPRC_VERSION). */
1956	uint32_t u32Version;
1957	/** Just a safety precaution. */
1958	uint32_t u32TheEnd;
1959	} PDMPCIRAWHLPRC;
1960	/** Pointer to a raw PCI deviec raw-mode context helper structure. */
1961	typedef RCPTRTYPE(PDMPCIRAWHLPRC *) PPDMPCIRAWHLPRC;
1962	/** Pointer to a const raw PCI deviec raw-mode context helper structure. */
1963	typedef RCPTRTYPE(const PDMPCIRAWHLPRC *) PCPDMPCIRAWHLPRC;
1964
1965	/** Current PDMPCIRAWHLPRC version number. */
1966	#define PDM_PCIRAWHLPRC_VERSION PDM_VERSION_MAKE(0xffe0, 1, 0)
1967
1968	/**
1969	* Raw PCI device ring-0 context helpers.
1970	*/
1971	typedef struct PDMPCIRAWHLPR0
1972	{
1973	/** Structure version and magic number (PDM_PCIRAWHLPR0_VERSION). */
1974	uint32_t u32Version;
1975	/** Just a safety precaution. */
1976	uint32_t u32TheEnd;
1977	} PDMPCIRAWHLPR0;
1978	/** Pointer to a raw PCI deviec ring-0 context helper structure. */
1979	typedef R0PTRTYPE(PDMPCIRAWHLPR0 *) PPDMPCIRAWHLPR0;
1980	/** Pointer to a const raw PCI deviec ring-0 context helper structure. */
1981	typedef R0PTRTYPE(const PDMPCIRAWHLPR0 *) PCPDMPCIRAWHLPR0;
1982
1983	/** Current PDMPCIRAWHLPR0 version number. */
1984	#define PDM_PCIRAWHLPR0_VERSION PDM_VERSION_MAKE(0xffdf, 1, 0)
1985
1986
1987	/**
1988	* Raw PCI device ring-3 context helpers.
1989	*/
1990	typedef struct PDMPCIRAWHLPR3
1991	{
1992	/** Undefined structure version and magic number. */
1993	uint32_t u32Version;
1994
1995	/**
1996	* Gets the address of the RC raw PCI device helpers.
1997	*
1998	* This should be called at both construction and relocation time to obtain
1999	* the correct address of the RC helpers.
2000	*
2001	* @returns RC pointer to the raw PCI device helpers.
2002	* @param pDevIns Device instance of the raw PCI device.
2003	*/
2004	DECLR3CALLBACKMEMBER(PCPDMPCIRAWHLPRC, pfnGetRCHelpers,(PPDMDEVINS pDevIns));
2005
2006	/**
2007	* Gets the address of the R0 raw PCI device helpers.
2008	*
2009	* This should be called at both construction and relocation time to obtain
2010	* the correct address of the R0 helpers.
2011	*
2012	* @returns R0 pointer to the raw PCI device helpers.
2013	* @param pDevIns Device instance of the raw PCI device.
2014	*/
2015	DECLR3CALLBACKMEMBER(PCPDMPCIRAWHLPR0, pfnGetR0Helpers,(PPDMDEVINS pDevIns));
2016
2017	/** Just a safety precaution. */
2018	uint32_t u32TheEnd;
2019	} PDMPCIRAWHLPR3;
2020	/** Pointer to raw PCI R3 helpers. */
2021	typedef R3PTRTYPE(PDMPCIRAWHLPR3 *) PPDMPCIRAWHLPR3;
2022	/** Pointer to const raw PCI R3 helpers. */
2023	typedef R3PTRTYPE(const PDMPCIRAWHLPR3 *) PCPDMPCIRAWHLPR3;
2024
2025	/** Current PDMPCIRAWHLPR3 version number. */
2026	#define PDM_PCIRAWHLPR3_VERSION PDM_VERSION_MAKE(0xffde, 1, 0)
2027
2028
2029	#ifdef IN_RING3
2030
2031	/**
2032	* DMA Transfer Handler.
2033	*
2034	* @returns Number of bytes transferred.
2035	* @param pDevIns Device instance of the DMA.
2036	* @param pvUser User pointer.
2037	* @param uChannel Channel number.
2038	* @param off DMA position.
2039	* @param cb Block size.
2040	* @remarks The device lock is not taken, however, the DMA device lock is held.
2041	*/
2042	typedef DECLCALLBACK(uint32_t) FNDMATRANSFERHANDLER(PPDMDEVINS pDevIns, void *pvUser, unsigned uChannel, uint32_t off, uint32_t cb);
2043	/** Pointer to a FNDMATRANSFERHANDLER(). */
2044	typedef FNDMATRANSFERHANDLER *PFNDMATRANSFERHANDLER;
2045
2046	/**
2047	* DMA Controller registration structure.
2048	*/
2049	typedef struct PDMDMAREG
2050	{
2051	/** Structure version number. PDM_DMACREG_VERSION defines the current version. */
2052	uint32_t u32Version;
2053
2054	/**
2055	* Execute pending transfers.
2056	*
2057	* @returns A more work indiciator. I.e. 'true' if there is more to be done, and 'false' if all is done.
2058	* @param pDevIns Device instance of the DMAC.
2059	* @remarks No locks held, called on EMT(0) as a form of serialization.
2060	*/
2061	DECLR3CALLBACKMEMBER(bool, pfnRun,(PPDMDEVINS pDevIns));
2062
2063	/**
2064	* Register transfer function for DMA channel.
2065	*
2066	* @param pDevIns Device instance of the DMAC.
2067	* @param uChannel Channel number.
2068	* @param pfnTransferHandler Device specific transfer function.
2069	* @param pvUSer User pointer to be passed to the callback.
2070	* @remarks No locks held, called on an EMT.
2071	*/
2072	DECLR3CALLBACKMEMBER(void, pfnRegister,(PPDMDEVINS pDevIns, unsigned uChannel, PFNDMATRANSFERHANDLER pfnTransferHandler, void *pvUser));
2073
2074	/**
2075	* Read memory
2076	*
2077	* @returns Number of bytes read.
2078	* @param pDevIns Device instance of the DMAC.
2079	* @param pvBuffer Pointer to target buffer.
2080	* @param off DMA position.
2081	* @param cbBlock Block size.
2082	* @remarks No locks held, called on an EMT.
2083	*/
2084	DECLR3CALLBACKMEMBER(uint32_t, pfnReadMemory,(PPDMDEVINS pDevIns, unsigned uChannel, void *pvBuffer, uint32_t off, uint32_t cbBlock));
2085
2086	/**
2087	* Write memory
2088	*
2089	* @returns Number of bytes written.
2090	* @param pDevIns Device instance of the DMAC.
2091	* @param pvBuffer Memory to write.
2092	* @param off DMA position.
2093	* @param cbBlock Block size.
2094	* @remarks No locks held, called on an EMT.
2095	*/
2096	DECLR3CALLBACKMEMBER(uint32_t, pfnWriteMemory,(PPDMDEVINS pDevIns, unsigned uChannel, const void *pvBuffer, uint32_t off, uint32_t cbBlock));
2097
2098	/**
2099	* Set the DREQ line.
2100	*
2101	* @param pDevIns Device instance of the DMAC.
2102	* @param uChannel Channel number.
2103	* @param uLevel Level of the line.
2104	* @remarks No locks held, called on an EMT.
2105	*/
2106	DECLR3CALLBACKMEMBER(void, pfnSetDREQ,(PPDMDEVINS pDevIns, unsigned uChannel, unsigned uLevel));
2107
2108	/**
2109	* Get channel mode
2110	*
2111	* @returns Channel mode.
2112	* @param pDevIns Device instance of the DMAC.
2113	* @param uChannel Channel number.
2114	* @remarks No locks held, called on an EMT.
2115	*/
2116	DECLR3CALLBACKMEMBER(uint8_t, pfnGetChannelMode,(PPDMDEVINS pDevIns, unsigned uChannel));
2117
2118	} PDMDMACREG;
2119	/** Pointer to a DMAC registration structure. */
2120	typedef PDMDMACREG *PPDMDMACREG;
2121
2122	/** Current PDMDMACREG version number. */
2123	#define PDM_DMACREG_VERSION PDM_VERSION_MAKE(0xffeb, 1, 0)
2124
2125
2126	/**
2127	* DMA Controller device helpers.
2128	*/
2129	typedef struct PDMDMACHLP
2130	{
2131	/** Structure version. PDM_DMACHLP_VERSION defines the current version. */
2132	uint32_t u32Version;
2133
2134	/* to-be-defined */
2135
2136	} PDMDMACHLP;
2137	/** Pointer to DMAC helpers. */
2138	typedef PDMDMACHLP *PPDMDMACHLP;
2139	/** Pointer to const DMAC helpers. */
2140	typedef const PDMDMACHLP *PCPDMDMACHLP;
2141
2142	/** Current PDMDMACHLP version number. */
2143	#define PDM_DMACHLP_VERSION PDM_VERSION_MAKE(0xffea, 1, 0)
2144
2145	#endif /* IN_RING3 */
2146
2147
2148
2149	/**
2150	* RTC registration structure.
2151	*/
2152	typedef struct PDMRTCREG
2153	{
2154	/** Structure version number. PDM_RTCREG_VERSION defines the current version. */
2155	uint32_t u32Version;
2156	uint32_t u32Alignment; /*< structure size alignment. /
2157
2158	/**
2159	* Write to a CMOS register and update the checksum if necessary.
2160	*
2161	* @returns VBox status code.
2162	* @param pDevIns Device instance of the RTC.
2163	* @param iReg The CMOS register index.
2164	* @param u8Value The CMOS register value.
2165	* @remarks Caller enters the device critical section.
2166	*/
2167	DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMDEVINS pDevIns, unsigned iReg, uint8_t u8Value));
2168
2169	/**
2170	* Read a CMOS register.
2171	*
2172	* @returns VBox status code.
2173	* @param pDevIns Device instance of the RTC.
2174	* @param iReg The CMOS register index.
2175	* @param pu8Value Where to store the CMOS register value.
2176	* @remarks Caller enters the device critical section.
2177	*/
2178	DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMDEVINS pDevIns, unsigned iReg, uint8_t *pu8Value));
2179
2180	} PDMRTCREG;
2181	/** Pointer to a RTC registration structure. */
2182	typedef PDMRTCREG *PPDMRTCREG;
2183	/** Pointer to a const RTC registration structure. */
2184	typedef const PDMRTCREG *PCPDMRTCREG;
2185
2186	/** Current PDMRTCREG version number. */
2187	#define PDM_RTCREG_VERSION PDM_VERSION_MAKE(0xffe9, 2, 0)
2188
2189
2190	/**
2191	* RTC device helpers.
2192	*/
2193	typedef struct PDMRTCHLP
2194	{
2195	/** Structure version. PDM_RTCHLP_VERSION defines the current version. */
2196	uint32_t u32Version;
2197
2198	/* to-be-defined */
2199
2200	} PDMRTCHLP;
2201	/** Pointer to RTC helpers. */
2202	typedef PDMRTCHLP *PPDMRTCHLP;
2203	/** Pointer to const RTC helpers. */
2204	typedef const PDMRTCHLP *PCPDMRTCHLP;
2205
2206	/** Current PDMRTCHLP version number. */
2207	#define PDM_RTCHLP_VERSION PDM_VERSION_MAKE(0xffe8, 1, 0)
2208
2209
2210
2211	#ifdef IN_RING3
2212
2213	/**
2214	* PDM Device API.
2215	*/
2216	typedef struct PDMDEVHLPR3
2217	{
2218	/** Structure version. PDM_DEVHLPR3_VERSION defines the current version. */
2219	uint32_t u32Version;
2220
2221	/**
2222	* Register a number of I/O ports with a device.
2223	*
2224	* These callbacks are of course for the host context (HC).
2225	* Register HC handlers before guest context (GC) handlers! There must be a
2226	* HC handler for every GC handler!
2227	*
2228	* @returns VBox status.
2229	* @param pDevIns The device instance to register the ports with.
2230	* @param Port First port number in the range.
2231	* @param cPorts Number of ports to register.
2232	* @param pvUser User argument.
2233	* @param pfnOut Pointer to function which is gonna handle OUT operations.
2234	* @param pfnIn Pointer to function which is gonna handle IN operations.
2235	* @param pfnOutStr Pointer to function which is gonna handle string OUT operations.
2236	* @param pfnInStr Pointer to function which is gonna handle string IN operations.
2237	* @param pszDesc Pointer to description string. This must not be freed.
2238	* @remarks Caller enters the device critical section prior to invoking the
2239	* registered callback methods.
2240	*/
2241	DECLR3CALLBACKMEMBER(int, pfnIOPortRegister,(PPDMDEVINS pDevIns, RTIOPORT Port, RTIOPORT cPorts, RTHCPTR pvUser,
2242	PFNIOMIOPORTOUT pfnOut, PFNIOMIOPORTIN pfnIn,
2243	PFNIOMIOPORTOUTSTRING pfnOutStr, PFNIOMIOPORTINSTRING pfnInStr, const char *pszDesc));
2244
2245	/**
2246	* Register a number of I/O ports with a device for RC.
2247	*
2248	* These callbacks are for the raw-mode context (RC). Register ring-3 context
2249	* (R3) handlers before raw-mode context handlers! There must be a R3 handler
2250	* for every RC handler!
2251	*
2252	* @returns VBox status.
2253	* @param pDevIns The device instance to register the ports with
2254	* and which RC module to resolve the names
2255	* against.
2256	* @param Port First port number in the range.
2257	* @param cPorts Number of ports to register.
2258	* @param pvUser User argument.
2259	* @param pszOut Name of the RC function which is gonna handle OUT operations.
2260	* @param pszIn Name of the RC function which is gonna handle IN operations.
2261	* @param pszOutStr Name of the RC function which is gonna handle string OUT operations.
2262	* @param pszInStr Name of the RC function which is gonna handle string IN operations.
2263	* @param pszDesc Pointer to description string. This must not be freed.
2264	* @remarks Caller enters the device critical section prior to invoking the
2265	* registered callback methods.
2266	*/
2267	DECLR3CALLBACKMEMBER(int, pfnIOPortRegisterRC,(PPDMDEVINS pDevIns, RTIOPORT Port, RTIOPORT cPorts, RTRCPTR pvUser,
2268	const char pszOut, const char pszIn,
2269	const char pszOutStr, const char pszInStr, const char *pszDesc));
2270
2271	/**
2272	* Register a number of I/O ports with a device.
2273	*
2274	* These callbacks are of course for the ring-0 host context (R0).
2275	* Register R3 (HC) handlers before R0 (R0) handlers! There must be a R3 (HC) handler for every R0 handler!
2276	*
2277	* @returns VBox status.
2278	* @param pDevIns The device instance to register the ports with.
2279	* @param Port First port number in the range.
2280	* @param cPorts Number of ports to register.
2281	* @param pvUser User argument. (if pointer, then it must be in locked memory!)
2282	* @param pszOut Name of the R0 function which is gonna handle OUT operations.
2283	* @param pszIn Name of the R0 function which is gonna handle IN operations.
2284	* @param pszOutStr Name of the R0 function which is gonna handle string OUT operations.
2285	* @param pszInStr Name of the R0 function which is gonna handle string IN operations.
2286	* @param pszDesc Pointer to description string. This must not be freed.
2287	* @remarks Caller enters the device critical section prior to invoking the
2288	* registered callback methods.
2289	*/
2290	DECLR3CALLBACKMEMBER(int, pfnIOPortRegisterR0,(PPDMDEVINS pDevIns, RTIOPORT Port, RTIOPORT cPorts, RTR0PTR pvUser,
2291	const char pszOut, const char pszIn,
2292	const char pszOutStr, const char pszInStr, const char *pszDesc));
2293
2294	/**
2295	* Deregister I/O ports.
2296	*
2297	* This naturally affects both guest context (GC), ring-0 (R0) and ring-3 (R3/HC) handlers.
2298	*
2299	* @returns VBox status.
2300	* @param pDevIns The device instance owning the ports.
2301	* @param Port First port number in the range.
2302	* @param cPorts Number of ports to deregister.
2303	*/
2304	DECLR3CALLBACKMEMBER(int, pfnIOPortDeregister,(PPDMDEVINS pDevIns, RTIOPORT Port, RTIOPORT cPorts));
2305
2306	/**
2307	* Register a Memory Mapped I/O (MMIO) region.
2308	*
2309	* These callbacks are of course for the ring-3 context (R3). Register HC
2310	* handlers before raw-mode context (RC) and ring-0 context (R0) handlers! There
2311	* must be a R3 handler for every RC and R0 handler!
2312	*
2313	* @returns VBox status.
2314	* @param pDevIns The device instance to register the MMIO with.
2315	* @param GCPhysStart First physical address in the range.
2316	* @param cbRange The size of the range (in bytes).
2317	* @param pvUser User argument.
2318	* @param pfnWrite Pointer to function which is gonna handle Write operations.
2319	* @param pfnRead Pointer to function which is gonna handle Read operations.
2320	* @param pfnFill Pointer to function which is gonna handle Fill/memset operations. (optional)
2321	* @param fFlags Flags, IOMMMIO_FLAGS_XXX.
2322	* @param pszDesc Pointer to description string. This must not be freed.
2323	* @remarks Caller enters the device critical section prior to invoking the
2324	* registered callback methods.
2325	*/
2326	DECLR3CALLBACKMEMBER(int, pfnMMIORegister,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, uint32_t cbRange, RTHCPTR pvUser,
2327	PFNIOMMMIOWRITE pfnWrite, PFNIOMMMIOREAD pfnRead, PFNIOMMMIOFILL pfnFill,
2328	uint32_t fFlags, const char *pszDesc));
2329
2330	/**
2331	* Register a Memory Mapped I/O (MMIO) region for GC.
2332	*
2333	* These callbacks are for the raw-mode context (RC). Register ring-3 context
2334	* (R3) handlers before guest context handlers! There must be a R3 handler for
2335	* every RC handler!
2336	*
2337	* @returns VBox status.
2338	* @param pDevIns The device instance to register the MMIO with.
2339	* @param GCPhysStart First physical address in the range.
2340	* @param cbRange The size of the range (in bytes).
2341	* @param pvUser User argument.
2342	* @param pszWrite Name of the RC function which is gonna handle Write operations.
2343	* @param pszRead Name of the RC function which is gonna handle Read operations.
2344	* @param pszFill Name of the RC function which is gonna handle Fill/memset operations. (optional)
2345	* @remarks Caller enters the device critical section prior to invoking the
2346	* registered callback methods.
2347	*/
2348	DECLR3CALLBACKMEMBER(int, pfnMMIORegisterRC,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, uint32_t cbRange, RTRCPTR pvUser,
2349	const char pszWrite, const char pszRead, const char *pszFill));
2350
2351	/**
2352	* Register a Memory Mapped I/O (MMIO) region for R0.
2353	*
2354	* These callbacks are for the ring-0 host context (R0). Register ring-3
2355	* constext (R3) handlers before R0 handlers! There must be a R3 handler for
2356	* every R0 handler!
2357	*
2358	* @returns VBox status.
2359	* @param pDevIns The device instance to register the MMIO with.
2360	* @param GCPhysStart First physical address in the range.
2361	* @param cbRange The size of the range (in bytes).
2362	* @param pvUser User argument. (if pointer, then it must be in locked memory!)
2363	* @param pszWrite Name of the RC function which is gonna handle Write operations.
2364	* @param pszRead Name of the RC function which is gonna handle Read operations.
2365	* @param pszFill Name of the RC function which is gonna handle Fill/memset operations. (optional)
2366	* @param pszDesc Obsolete. NULL is fine.
2367	* @remarks Caller enters the device critical section prior to invoking the
2368	* registered callback methods.
2369	*/
2370	DECLR3CALLBACKMEMBER(int, pfnMMIORegisterR0,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, uint32_t cbRange, RTR0PTR pvUser,
2371	const char pszWrite, const char pszRead, const char *pszFill));
2372
2373	/**
2374	* Deregister a Memory Mapped I/O (MMIO) region.
2375	*
2376	* This naturally affects both guest context (GC), ring-0 (R0) and ring-3 (R3/HC) handlers.
2377	*
2378	* @returns VBox status.
2379	* @param pDevIns The device instance owning the MMIO region(s).
2380	* @param GCPhysStart First physical address in the range.
2381	* @param cbRange The size of the range (in bytes).
2382	*/
2383	DECLR3CALLBACKMEMBER(int, pfnMMIODeregister,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, uint32_t cbRange));
2384
2385	/**
2386	* Allocate and register a MMIO2 region.
2387	*
2388	* As mentioned elsewhere, MMIO2 is just RAM spelled differently. It's
2389	* RAM associated with a device. It is also non-shared memory with a
2390	* permanent ring-3 mapping and page backing (presently).
2391	*
2392	* @returns VBox status.
2393	* @param pDevIns The device instance.
2394	* @param iRegion The region number. Use the PCI region number as
2395	* this must be known to the PCI bus device too. If
2396	* it's not associated with the PCI device, then
2397	* any number up to UINT8_MAX is fine.
2398	* @param cb The size (in bytes) of the region.
2399	* @param fFlags Reserved for future use, must be zero.
2400	* @param ppv Where to store the address of the ring-3 mapping
2401	* of the memory.
2402	* @param pszDesc Pointer to description string. This must not be
2403	* freed.
2404	* @thread EMT.
2405	*/
2406	DECLR3CALLBACKMEMBER(int, pfnMMIO2Register,(PPDMDEVINS pDevIns, uint32_t iRegion, RTGCPHYS cb, uint32_t fFlags, void *ppv, const char pszDesc));
2407
2408	/**
2409	* Deregisters and frees a MMIO2 region.
2410	*
2411	* Any physical (and virtual) access handlers registered for the region must
2412	* be deregistered before calling this function.
2413	*
2414	* @returns VBox status code.
2415	* @param pDevIns The device instance.
2416	* @param iRegion The region number used during registration.
2417	* @thread EMT.
2418	*/
2419	DECLR3CALLBACKMEMBER(int, pfnMMIO2Deregister,(PPDMDEVINS pDevIns, uint32_t iRegion));
2420
2421	/**
2422	* Maps a MMIO2 region into the physical memory space.
2423	*
2424	* A MMIO2 range may overlap with base memory if a lot of RAM
2425	* is configured for the VM, in which case we'll drop the base
2426	* memory pages. Presently we will make no attempt to preserve
2427	* anything that happens to be present in the base memory that
2428	* is replaced, this is of course incorrect but it's too much
2429	* effort.
2430	*
2431	* @returns VBox status code.
2432	* @param pDevIns The device instance.
2433	* @param iRegion The region number used during registration.
2434	* @param GCPhys The physical address to map it at.
2435	* @thread EMT.
2436	*/
2437	DECLR3CALLBACKMEMBER(int, pfnMMIO2Map,(PPDMDEVINS pDevIns, uint32_t iRegion, RTGCPHYS GCPhys));
2438
2439	/**
2440	* Unmaps a MMIO2 region previously mapped using pfnMMIO2Map.
2441	*
2442	* @returns VBox status code.
2443	* @param pDevIns The device instance.
2444	* @param iRegion The region number used during registration.
2445	* @param GCPhys The physical address it's currently mapped at.
2446	* @thread EMT.
2447	*/
2448	DECLR3CALLBACKMEMBER(int, pfnMMIO2Unmap,(PPDMDEVINS pDevIns, uint32_t iRegion, RTGCPHYS GCPhys));
2449
2450	/**
2451	* Maps a portion of an MMIO2 region into the hypervisor region.
2452	*
2453	* Callers of this API must never deregister the MMIO2 region before the
2454	* VM is powered off.
2455	*
2456	* @return VBox status code.
2457	* @param pDevIns The device owning the MMIO2 memory.
2458	* @param iRegion The region.
2459	* @param off The offset into the region. Will be rounded down
2460	* to closest page boundary.
2461	* @param cb The number of bytes to map. Will be rounded up
2462	* to the closest page boundary.
2463	* @param pszDesc Mapping description.
2464	* @param pRCPtr Where to store the RC address.
2465	*/
2466	DECLR3CALLBACKMEMBER(int, pfnMMHyperMapMMIO2,(PPDMDEVINS pDevIns, uint32_t iRegion, RTGCPHYS off, RTGCPHYS cb,
2467	const char *pszDesc, PRTRCPTR pRCPtr));
2468
2469	/**
2470	* Maps a portion of an MMIO2 region into kernel space (host).
2471	*
2472	* The kernel mapping will become invalid when the MMIO2 memory is deregistered
2473	* or the VM is terminated.
2474	*
2475	* @return VBox status code.
2476	* @param pDevIns The device owning the MMIO2 memory.
2477	* @param iRegion The region.
2478	* @param off The offset into the region. Must be page
2479	* aligned.
2480	* @param cb The number of bytes to map. Must be page
2481	* aligned.
2482	* @param pszDesc Mapping description.
2483	* @param pR0Ptr Where to store the R0 address.
2484	*/
2485	DECLR3CALLBACKMEMBER(int, pfnMMIO2MapKernel,(PPDMDEVINS pDevIns, uint32_t iRegion, RTGCPHYS off, RTGCPHYS cb,
2486	const char *pszDesc, PRTR0PTR pR0Ptr));
2487
2488	/**
2489	* Register a ROM (BIOS) region.
2490	*
2491	* It goes without saying that this is read-only memory. The memory region must be
2492	* in unassigned memory. I.e. from the top of the address space or on the PC in
2493	* the 0xa0000-0xfffff range.
2494	*
2495	* @returns VBox status.
2496	* @param pDevIns The device instance owning the ROM region.
2497	* @param GCPhysStart First physical address in the range.
2498	* Must be page aligned!
2499	* @param cbRange The size of the range (in bytes).
2500	* Must be page aligned!
2501	* @param pvBinary Pointer to the binary data backing the ROM image.
2502	* @param cbBinary The size of the binary pointer. This must
2503	* be equal or smaller than @a cbRange.
2504	* @param fFlags Shadow ROM flags, PGMPHYS_ROM_FLAGS_* in pgm.h.
2505	* @param pszDesc Pointer to description string. This must not be freed.
2506	*
2507	* @remark There is no way to remove the rom, automatically on device cleanup or
2508	* manually from the device yet. At present I doubt we need such features...
2509	*/
2510	DECLR3CALLBACKMEMBER(int, pfnROMRegister,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, uint32_t cbRange,
2511	const void pvBinary, uint32_t cbBinary, uint32_t fFlags, const char pszDesc));
2512
2513	/**
2514	* Changes the protection of shadowed ROM mapping.
2515	*
2516	* This is intented for use by the system BIOS, chipset or device in question to
2517	* change the protection of shadowed ROM code after init and on reset.
2518	*
2519	* @param pDevIns The device instance.
2520	* @param GCPhysStart Where the mapping starts.
2521	* @param cbRange The size of the mapping.
2522	* @param enmProt The new protection type.
2523	*/
2524	DECLR3CALLBACKMEMBER(int, pfnROMProtectShadow,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, uint32_t cbRange, PGMROMPROT enmProt));
2525
2526	/**
2527	* Register a save state data unit.
2528	*
2529	* @returns VBox status.
2530	* @param pDevIns The device instance.
2531	* @param pszName Data unit name.
2532	* @param uInstance The instance identifier of the data unit.
2533	* This must together with the name be unique.
2534	* @param uVersion Data layout version number.
2535	* @param cbGuess The approximate amount of data in the unit.
2536	* Only for progress indicators.
2537	* @param pszBefore Name of data unit which we should be put in
2538	* front of. Optional (NULL).
2539	*
2540	* @param pfnLivePrep Prepare live save callback, optional.
2541	* @param pfnLiveExec Execute live save callback, optional.
2542	* @param pfnLiveVote Vote live save callback, optional.
2543	*
2544	* @param pfnSavePrep Prepare save callback, optional.
2545	* @param pfnSaveExec Execute save callback, optional.
2546	* @param pfnSaveDone Done save callback, optional.
2547	*
2548	* @param pfnLoadPrep Prepare load callback, optional.
2549	* @param pfnLoadExec Execute load callback, optional.
2550	* @param pfnLoadDone Done load callback, optional.
2551	* @remarks Caller enters the device critical section prior to invoking the
2552	* registered callback methods.
2553	*/
2554	DECLR3CALLBACKMEMBER(int, pfnSSMRegister,(PPDMDEVINS pDevIns, uint32_t uVersion, size_t cbGuess, const char *pszBefore,
2555	PFNSSMDEVLIVEPREP pfnLivePrep, PFNSSMDEVLIVEEXEC pfnLiveExec, PFNSSMDEVLIVEVOTE pfnLiveVote,
2556	PFNSSMDEVSAVEPREP pfnSavePrep, PFNSSMDEVSAVEEXEC pfnSaveExec, PFNSSMDEVSAVEDONE pfnSaveDone,
2557	PFNSSMDEVLOADPREP pfnLoadPrep, PFNSSMDEVLOADEXEC pfnLoadExec, PFNSSMDEVLOADDONE pfnLoadDone));
2558
2559	/**
2560	* Creates a timer.
2561	*
2562	* @returns VBox status.
2563	* @param pDevIns The device instance.
2564	* @param enmClock The clock to use on this timer.
2565	* @param pfnCallback Callback function.
2566	* @param pvUser User argument for the callback.
2567	* @param fFlags Flags, see TMTIMER_FLAGS_*.
2568	* @param pszDesc Pointer to description string which must stay around
2569	* until the timer is fully destroyed (i.e. a bit after TMTimerDestroy()).
2570	* @param ppTimer Where to store the timer on success.
2571	* @remarks Caller enters the device critical section prior to invoking the
2572	* callback.
2573	*/
2574	DECLR3CALLBACKMEMBER(int, pfnTMTimerCreate,(PPDMDEVINS pDevIns, TMCLOCK enmClock, PFNTMTIMERDEV pfnCallback, void pvUser, uint32_t fFlags, const char pszDesc, PPTMTIMERR3 ppTimer));
2575
2576	/**
2577	* Get the real world UTC time adjusted for VM lag, user offset and warpdrive.
2578	*
2579	* @returns pTime.
2580	* @param pDevIns The device instance.
2581	* @param pTime Where to store the time.
2582	*/
2583	DECLR3CALLBACKMEMBER(PRTTIMESPEC, pfnTMUtcNow,(PPDMDEVINS pDevIns, PRTTIMESPEC pTime));
2584
2585	/**
2586	* Read physical memory.
2587	*
2588	* @returns VINF_SUCCESS (for now).
2589	* @param pDevIns The device instance.
2590	* @param GCPhys Physical address start reading from.
2591	* @param pvBuf Where to put the read bits.
2592	* @param cbRead How many bytes to read.
2593	* @thread Any thread, but the call may involve the emulation thread.
2594	*/
2595	DECLR3CALLBACKMEMBER(int, pfnPhysRead,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead));
2596
2597	/**
2598	* Write to physical memory.
2599	*
2600	* @returns VINF_SUCCESS for now, and later maybe VERR_EM_MEMORY.
2601	* @param pDevIns The device instance.
2602	* @param GCPhys Physical address to write to.
2603	* @param pvBuf What to write.
2604	* @param cbWrite How many bytes to write.
2605	* @thread Any thread, but the call may involve the emulation thread.
2606	*/
2607	DECLR3CALLBACKMEMBER(int, pfnPhysWrite,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite));
2608
2609	/**
2610	* Requests the mapping of a guest page into ring-3.
2611	*
2612	* When you're done with the page, call pfnPhysReleasePageMappingLock() ASAP to
2613	* release it.
2614	*
2615	* This API will assume your intention is to write to the page, and will
2616	* therefore replace shared and zero pages. If you do not intend to modify the
2617	* page, use the pfnPhysGCPhys2CCPtrReadOnly() API.
2618	*
2619	* @returns VBox status code.
2620	* @retval VINF_SUCCESS on success.
2621	* @retval VERR_PGM_PHYS_PAGE_RESERVED it it's a valid page but has no physical
2622	* backing or if the page has any active access handlers. The caller
2623	* must fall back on using PGMR3PhysWriteExternal.
2624	* @retval VERR_PGM_INVALID_GC_PHYSICAL_ADDRESS if it's not a valid physical address.
2625	*
2626	* @param pVM The VM handle.
2627	* @param GCPhys The guest physical address of the page that
2628	* should be mapped.
2629	* @param fFlags Flags reserved for future use, MBZ.
2630	* @param ppv Where to store the address corresponding to
2631	* GCPhys.
2632	* @param pLock Where to store the lock information that
2633	* pfnPhysReleasePageMappingLock needs.
2634	*
2635	* @remark Avoid calling this API from within critical sections (other than the
2636	* PGM one) because of the deadlock risk when we have to delegating the
2637	* task to an EMT.
2638	* @thread Any.
2639	*/
2640	DECLR3CALLBACKMEMBER(int, pfnPhysGCPhys2CCPtr,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, uint32_t fFlags, void **ppv, PPGMPAGEMAPLOCK pLock));
2641
2642	/**
2643	* Requests the mapping of a guest page into ring-3, external threads.
2644	*
2645	* When you're done with the page, call pfnPhysReleasePageMappingLock() ASAP to
2646	* release it.
2647	*
2648	* @returns VBox status code.
2649	* @retval VINF_SUCCESS on success.
2650	* @retval VERR_PGM_PHYS_PAGE_RESERVED it it's a valid page but has no physical
2651	* backing or if the page as an active ALL access handler. The caller
2652	* must fall back on using PGMPhysRead.
2653	* @retval VERR_PGM_INVALID_GC_PHYSICAL_ADDRESS if it's not a valid physical address.
2654	*
2655	* @param pDevIns The device instance.
2656	* @param GCPhys The guest physical address of the page that
2657	* should be mapped.
2658	* @param fFlags Flags reserved for future use, MBZ.
2659	* @param ppv Where to store the address corresponding to
2660	* GCPhys.
2661	* @param pLock Where to store the lock information that
2662	* pfnPhysReleasePageMappingLock needs.
2663	*
2664	* @remark Avoid calling this API from within critical sections.
2665	* @thread Any.
2666	*/
2667	DECLR3CALLBACKMEMBER(int, pfnPhysGCPhys2CCPtrReadOnly,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, uint32_t fFlags, void const **ppv, PPGMPAGEMAPLOCK pLock));
2668
2669	/**
2670	* Release the mapping of a guest page.
2671	*
2672	* This is the counter part of pfnPhysGCPhys2CCPtr and
2673	* pfnPhysGCPhys2CCPtrReadOnly.
2674	*
2675	* @param pDevIns The device instance.
2676	* @param pLock The lock structure initialized by the mapping
2677	* function.
2678	*/
2679	DECLR3CALLBACKMEMBER(void, pfnPhysReleasePageMappingLock,(PPDMDEVINS pDevIns, PPGMPAGEMAPLOCK pLock));
2680
2681	/**
2682	* Read guest physical memory by virtual address.
2683	*
2684	* @param pDevIns The device instance.
2685	* @param pvDst Where to put the read bits.
2686	* @param GCVirtSrc Guest virtual address to start reading from.
2687	* @param cb How many bytes to read.
2688	* @thread The emulation thread.
2689	*/
2690	DECLR3CALLBACKMEMBER(int, pfnPhysReadGCVirt,(PPDMDEVINS pDevIns, void *pvDst, RTGCPTR GCVirtSrc, size_t cb));
2691
2692	/**
2693	* Write to guest physical memory by virtual address.
2694	*
2695	* @param pDevIns The device instance.
2696	* @param GCVirtDst Guest virtual address to write to.
2697	* @param pvSrc What to write.
2698	* @param cb How many bytes to write.
2699	* @thread The emulation thread.
2700	*/
2701	DECLR3CALLBACKMEMBER(int, pfnPhysWriteGCVirt,(PPDMDEVINS pDevIns, RTGCPTR GCVirtDst, const void *pvSrc, size_t cb));
2702
2703	/**
2704	* Convert a guest virtual address to a guest physical address.
2705	*
2706	* @returns VBox status code.
2707	* @param pDevIns The device instance.
2708	* @param GCPtr Guest virtual address.
2709	* @param pGCPhys Where to store the GC physical address
2710	* corresponding to GCPtr.
2711	* @thread The emulation thread.
2712	* @remark Careful with page boundaries.
2713	*/
2714	DECLR3CALLBACKMEMBER(int, pfnPhysGCPtr2GCPhys, (PPDMDEVINS pDevIns, RTGCPTR GCPtr, PRTGCPHYS pGCPhys));
2715
2716	/**
2717	* Allocate memory which is associated with current VM instance
2718	* and automatically freed on it's destruction.
2719	*
2720	* @returns Pointer to allocated memory. The memory is NOT zero-ed.
2721	* @param pDevIns The device instance.
2722	* @param cb Number of bytes to allocate.
2723	*/
2724	DECLR3CALLBACKMEMBER(void *, pfnMMHeapAlloc,(PPDMDEVINS pDevIns, size_t cb));
2725
2726	/**
2727	* Allocate memory which is associated with current VM instance
2728	* and automatically freed on it's destruction. The memory is ZEROed.
2729	*
2730	* @returns Pointer to allocated memory. The memory is NOT zero-ed.
2731	* @param pDevIns The device instance.
2732	* @param cb Number of bytes to allocate.
2733	*/
2734	DECLR3CALLBACKMEMBER(void *, pfnMMHeapAllocZ,(PPDMDEVINS pDevIns, size_t cb));
2735
2736	/**
2737	* Free memory allocated with pfnMMHeapAlloc() and pfnMMHeapAllocZ().
2738	*
2739	* @param pDevIns The device instance.
2740	* @param pv Pointer to the memory to free.
2741	*/
2742	DECLR3CALLBACKMEMBER(void, pfnMMHeapFree,(PPDMDEVINS pDevIns, void *pv));
2743
2744	/**
2745	* Gets the VM state.
2746	*
2747	* @returns VM state.
2748	* @param pDevIns The device instance.
2749	* @thread Any thread (just keep in mind that it's volatile info).
2750	*/
2751	DECLR3CALLBACKMEMBER(VMSTATE, pfnVMState, (PPDMDEVINS pDevIns));
2752
2753	/**
2754	* Checks if the VM was teleported and hasn't been fully resumed yet.
2755	*
2756	* @returns true / false.
2757	* @param pDevIns The device instance.
2758	* @thread Any thread.
2759	*/
2760	DECLR3CALLBACKMEMBER(bool, pfnVMTeleportedAndNotFullyResumedYet,(PPDMDEVINS pDevIns));
2761
2762	/**
2763	* Set the VM error message
2764	*
2765	* @returns rc.
2766	* @param pDevIns The device instance.
2767	* @param rc VBox status code.
2768	* @param RT_SRC_POS_DECL Use RT_SRC_POS.
2769	* @param pszFormat Error message format string.
2770	* @param ... Error message arguments.
2771	*/
2772	DECLR3CALLBACKMEMBER(int, pfnVMSetError,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, ...));
2773
2774	/**
2775	* Set the VM error message
2776	*
2777	* @returns rc.
2778	* @param pDevIns The device instance.
2779	* @param rc VBox status code.
2780	* @param RT_SRC_POS_DECL Use RT_SRC_POS.
2781	* @param pszFormat Error message format string.
2782	* @param va Error message arguments.
2783	*/
2784	DECLR3CALLBACKMEMBER(int, pfnVMSetErrorV,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va));
2785
2786	/**
2787	* Set the VM runtime error message
2788	*
2789	* @returns VBox status code.
2790	* @param pDevIns The device instance.
2791	* @param fFlags The action flags. See VMSETRTERR_FLAGS_*.
2792	* @param pszErrorId Error ID string.
2793	* @param pszFormat Error message format string.
2794	* @param ... Error message arguments.
2795	*/
2796	DECLR3CALLBACKMEMBER(int, pfnVMSetRuntimeError,(PPDMDEVINS pDevIns, uint32_t fFlags, const char pszErrorId, const char pszFormat, ...));
2797
2798	/**
2799	* Set the VM runtime error message
2800	*
2801	* @returns VBox status code.
2802	* @param pDevIns The device instance.
2803	* @param fFlags The action flags. See VMSETRTERR_FLAGS_*.
2804	* @param pszErrorId Error ID string.
2805	* @param pszFormat Error message format string.
2806	* @param va Error message arguments.
2807	*/
2808	DECLR3CALLBACKMEMBER(int, pfnVMSetRuntimeErrorV,(PPDMDEVINS pDevIns, uint32_t fFlags, const char pszErrorId, const char pszFormat, va_list va));
2809
2810	/**
2811	* Stops the VM and enters the debugger to look at the guest state.
2812	*
2813	* Use the PDMDeviceDBGFStop() inline function with the RT_SRC_POS macro instead of
2814	* invoking this function directly.
2815	*
2816	* @returns VBox status code which must be passed up to the VMM.
2817	* @param pDevIns The device instance.
2818	* @param pszFile Filename of the assertion location.
2819	* @param iLine The linenumber of the assertion location.
2820	* @param pszFunction Function of the assertion location.
2821	* @param pszFormat Message. (optional)
2822	* @param args Message parameters.
2823	*/
2824	DECLR3CALLBACKMEMBER(int, pfnDBGFStopV,(PPDMDEVINS pDevIns, const char pszFile, unsigned iLine, const char pszFunction, const char *pszFormat, va_list args));
2825
2826	/**
2827	* Register a info handler with DBGF,
2828	*
2829	* @returns VBox status code.
2830	* @param pDevIns The device instance.
2831	* @param pszName The identifier of the info.
2832	* @param pszDesc The description of the info and any arguments
2833	* the handler may take.
2834	* @param pfnHandler The handler function to be called to display the
2835	* info.
2836	*/
2837	DECLR3CALLBACKMEMBER(int, pfnDBGFInfoRegister,(PPDMDEVINS pDevIns, const char pszName, const char pszDesc, PFNDBGFHANDLERDEV pfnHandler));
2838
2839	/**
2840	* Registers a set of registers for a device.
2841	*
2842	* The @a pvUser argument of the getter and setter callbacks will be
2843	* @a pDevIns. The register names will be prefixed by the device name followed
2844	* immediately by the instance number.
2845	*
2846	* @returns VBox status code.
2847	* @param pDevIns The device instance.
2848	* @param paRegisters The register descriptors.
2849	*
2850	* @remarks The device critical section is NOT entered prior to working the
2851	* callbacks registered via this helper!
2852	*/
2853	DECLR3CALLBACKMEMBER(int, pfnDBGFRegRegister,(PPDMDEVINS pDevIns, PCDBGFREGDESC paRegisters));
2854
2855	/**
2856	* Gets the trace buffer handle.
2857	*
2858	* This is used by the macros found in VBox/vmm/dbgftrace.h and is not
2859	* really inteded for direct usage, thus no inline wrapper function.
2860	*
2861	* @returns Trace buffer handle or NIL_RTTRACEBUF.
2862	* @param pDevIns The device instance.
2863	*/
2864	DECLR3CALLBACKMEMBER(RTTRACEBUF, pfnDBGFTraceBuf,(PPDMDEVINS pDevIns));
2865
2866	/**
2867	* Registers a statistics sample if statistics are enabled.
2868	*
2869	* @param pDevIns Device instance of the DMA.
2870	* @param pvSample Pointer to the sample.
2871	* @param enmType Sample type. This indicates what pvSample is
2872	* pointing at.
2873	* @param pszName Sample name. The name is on this form
2874	* "/<component>/<sample>". Further nesting is
2875	* possible.
2876	* @param enmUnit Sample unit.
2877	* @param pszDesc Sample description.
2878	*/
2879	DECLR3CALLBACKMEMBER(void, pfnSTAMRegister,(PPDMDEVINS pDevIns, void pvSample, STAMTYPE enmType, const char pszName, STAMUNIT enmUnit, const char *pszDesc));
2880
2881	/**
2882	* Same as pfnSTAMRegister except that the name is specified in a
2883	* RTStrPrintf like fashion.
2884	*
2885	* @returns VBox status.
2886	* @param pDevIns Device instance of the DMA.
2887	* @param pvSample Pointer to the sample.
2888	* @param enmType Sample type. This indicates what pvSample is
2889	* pointing at.
2890	* @param enmVisibility Visibility type specifying whether unused
2891	* statistics should be visible or not.
2892	* @param enmUnit Sample unit.
2893	* @param pszDesc Sample description.
2894	* @param pszName The sample name format string.
2895	* @param ... Arguments to the format string.
2896	*/
2897	DECLR3CALLBACKMEMBER(void, pfnSTAMRegisterF,(PPDMDEVINS pDevIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,
2898	STAMUNIT enmUnit, const char pszDesc, const char pszName, ...));
2899
2900	/**
2901	* Same as pfnSTAMRegister except that the name is specified in a
2902	* RTStrPrintfV like fashion.
2903	*
2904	* @returns VBox status.
2905	* @param pDevIns Device instance of the DMA.
2906	* @param pvSample Pointer to the sample.
2907	* @param enmType Sample type. This indicates what pvSample is
2908	* pointing at.
2909	* @param enmVisibility Visibility type specifying whether unused
2910	* statistics should be visible or not.
2911	* @param enmUnit Sample unit.
2912	* @param pszDesc Sample description.
2913	* @param pszName The sample name format string.
2914	* @param args Arguments to the format string.
2915	*/
2916	DECLR3CALLBACKMEMBER(void, pfnSTAMRegisterV,(PPDMDEVINS pDevIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,
2917	STAMUNIT enmUnit, const char pszDesc, const char pszName, va_list args));
2918
2919	/**
2920	* Registers the device with the default PCI bus.
2921	*
2922	* @returns VBox status code.
2923	* @param pDevIns The device instance.
2924	* @param pPciDev The PCI device structure.
2925	* Any PCI enabled device must keep this in it's instance data!
2926	* Fill in the PCI data config before registration, please.
2927	* @remark This is the simple interface, a Ex interface will be created if
2928	* more features are needed later.
2929	*/
2930	DECLR3CALLBACKMEMBER(int, pfnPCIRegister,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev));
2931
2932	/**
2933	* Initialize MSI support in a PCI device.
2934	*
2935	* @returns VBox status code.
2936	* @param pDevIns The device instance.
2937	* @param pMsiReg MSI registartion structure.
2938	*/
2939	DECLR3CALLBACKMEMBER(int, pfnPCIRegisterMsi,(PPDMDEVINS pDevIns, PPDMMSIREG pMsiReg));
2940
2941	/**
2942	* Registers a I/O region (memory mapped or I/O ports) for a PCI device.
2943	*
2944	* @returns VBox status code.
2945	* @param pDevIns The device instance.
2946	* @param iRegion The region number.
2947	* @param cbRegion Size of the region.
2948	* @param enmType PCI_ADDRESS_SPACE_MEM, PCI_ADDRESS_SPACE_IO or PCI_ADDRESS_SPACE_MEM_PREFETCH.
2949	* @param pfnCallback Callback for doing the mapping.
2950	* @remarks The callback will be invoked holding the PDM lock. The device lock
2951	* is NOT take because that is very likely be a lock order violation.
2952	*/
2953	DECLR3CALLBACKMEMBER(int, pfnPCIIORegionRegister,(PPDMDEVINS pDevIns, int iRegion, uint32_t cbRegion,
2954	PCIADDRESSSPACE enmType, PFNPCIIOREGIONMAP pfnCallback));
2955
2956	/**
2957	* Register PCI configuration space read/write callbacks.
2958	*
2959	* @param pDevIns The device instance.
2960	* @param pPciDev The PCI device structure.
2961	* If NULL the default PCI device for this device instance is used.
2962	* @param pfnRead Pointer to the user defined PCI config read function.
2963	* @param ppfnReadOld Pointer to function pointer which will receive the old (default)
2964	* PCI config read function. This way, user can decide when (and if)
2965	* to call default PCI config read function. Can be NULL.
2966	* @param pfnWrite Pointer to the user defined PCI config write function.
2967	* @param pfnWriteOld Pointer to function pointer which will receive the old (default)
2968	* PCI config write function. This way, user can decide when (and if)
2969	* to call default PCI config write function. Can be NULL.
2970	* @remarks The callbacks will be invoked holding the PDM lock. The device lock
2971	* is NOT take because that is very likely be a lock order violation.
2972	* @thread EMT
2973	*/
2974	DECLR3CALLBACKMEMBER(void, pfnPCISetConfigCallbacks,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, PFNPCICONFIGREAD pfnRead, PPFNPCICONFIGREAD ppfnReadOld,
2975	PFNPCICONFIGWRITE pfnWrite, PPFNPCICONFIGWRITE ppfnWriteOld));
2976
2977	/**
2978	* Bus master physical memory read.
2979	*
2980	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_READ_BM_DISABLED, later maybe
2981	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
2982	* @param pDevIns The device instance.
2983	* @param GCPhys Physical address start reading from.
2984	* @param pvBuf Where to put the read bits.
2985	* @param cbRead How many bytes to read.
2986	* @thread Any thread, but the call may involve the emulation thread.
2987	*/
2988	DECLR3CALLBACKMEMBER(int, pfnPCIPhysRead,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead));
2989
2990	/**
2991	* Bus master physical memory write.
2992	*
2993	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_WRITE_BM_DISABLED, later maybe
2994	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
2995	* @param pDevIns The device instance.
2996	* @param GCPhys Physical address to write to.
2997	* @param pvBuf What to write.
2998	* @param cbWrite How many bytes to write.
2999	* @thread Any thread, but the call may involve the emulation thread.
3000	*/
3001	DECLR3CALLBACKMEMBER(int, pfnPCIPhysWrite,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite));
3002
3003	/**
3004	* Set the IRQ for a PCI device.
3005	*
3006	* @param pDevIns The device instance.
3007	* @param iIrq IRQ number to set.
3008	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
3009	* @thread Any thread, but will involve the emulation thread.
3010	*/
3011	DECLR3CALLBACKMEMBER(void, pfnPCISetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
3012
3013	/**
3014	* Set the IRQ for a PCI device, but don't wait for EMT to process
3015	* the request when not called from EMT.
3016	*
3017	* @param pDevIns The device instance.
3018	* @param iIrq IRQ number to set.
3019	* @param iLevel IRQ level.
3020	* @thread Any thread, but will involve the emulation thread.
3021	*/
3022	DECLR3CALLBACKMEMBER(void, pfnPCISetIrqNoWait,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
3023
3024	/**
3025	* Set ISA IRQ for a device.
3026	*
3027	* @param pDevIns The device instance.
3028	* @param iIrq IRQ number to set.
3029	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
3030	* @thread Any thread, but will involve the emulation thread.
3031	*/
3032	DECLR3CALLBACKMEMBER(void, pfnISASetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
3033
3034	/**
3035	* Set the ISA IRQ for a device, but don't wait for EMT to process
3036	* the request when not called from EMT.
3037	*
3038	* @param pDevIns The device instance.
3039	* @param iIrq IRQ number to set.
3040	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
3041	* @thread Any thread, but will involve the emulation thread.
3042	*/
3043	DECLR3CALLBACKMEMBER(void, pfnISASetIrqNoWait,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
3044
3045	/**
3046	* Attaches a driver (chain) to the device.
3047	*
3048	* The first call for a LUN this will serve as a registartion of the LUN. The pBaseInterface and
3049	* the pszDesc string will be registered with that LUN and kept around for PDMR3QueryDeviceLun().
3050	*
3051	* @returns VBox status code.
3052	* @param pDevIns The device instance.
3053	* @param iLun The logical unit to attach.
3054	* @param pBaseInterface Pointer to the base interface for that LUN. (device side / down)
3055	* @param ppBaseInterface Where to store the pointer to the base interface. (driver side / up)
3056	* @param pszDesc Pointer to a string describing the LUN. This string must remain valid
3057	* for the live of the device instance.
3058	*/
3059	DECLR3CALLBACKMEMBER(int, pfnDriverAttach,(PPDMDEVINS pDevIns, uint32_t iLun, PPDMIBASE pBaseInterface,
3060	PPDMIBASE ppBaseInterface, const char pszDesc));
3061
3062	/**
3063	* Create a queue.
3064	*
3065	* @returns VBox status code.
3066	* @param pDevIns The device instance.
3067	* @param cbItem The size of a queue item.
3068	* @param cItems The number of items in the queue.
3069	* @param cMilliesInterval The number of milliseconds between polling the queue.
3070	* If 0 then the emulation thread will be notified whenever an item arrives.
3071	* @param pfnCallback The consumer function.
3072	* @param fRZEnabled Set if the queue should work in RC and R0.
3073	* @param pszName The queue base name. The instance number will be
3074	* appended automatically.
3075	* @param ppQueue Where to store the queue handle on success.
3076	* @thread The emulation thread.
3077	* @remarks The device critical section will NOT be entered before calling the
3078	* callback. No locks will be held, but for now it's safe to assume
3079	* that only one EMT will do queue callbacks at any one time.
3080	*/
3081	DECLR3CALLBACKMEMBER(int, pfnQueueCreate,(PPDMDEVINS pDevIns, size_t cbItem, uint32_t cItems, uint32_t cMilliesInterval,
3082	PFNPDMQUEUEDEV pfnCallback, bool fRZEnabled, const char pszName, PPDMQUEUE ppQueue));
3083
3084	/**
3085	* Initializes a PDM critical section.
3086	*
3087	* The PDM critical sections are derived from the IPRT critical sections, but
3088	* works in RC and R0 as well.
3089	*
3090	* @returns VBox status code.
3091	* @param pDevIns The device instance.
3092	* @param pCritSect Pointer to the critical section.
3093	* @param RT_SRC_POS_DECL Use RT_SRC_POS.
3094	* @param pszNameFmt Format string for naming the critical section.
3095	* For statistics and lock validation.
3096	* @param va Arguments for the format string.
3097	*/
3098	DECLR3CALLBACKMEMBER(int, pfnCritSectInit,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, RT_SRC_POS_DECL,
3099	const char *pszNameFmt, va_list va));
3100
3101	/**
3102	* Gets the NOP critical section.
3103	*
3104	* @returns The ring-3 address of the NOP critical section.
3105	* @param pDevIns The device instance.
3106	*/
3107	DECLR3CALLBACKMEMBER(PPDMCRITSECT, pfnCritSectGetNop,(PPDMDEVINS pDevIns));
3108
3109	/**
3110	* Gets the NOP critical section.
3111	*
3112	* @returns The ring-0 address of the NOP critical section.
3113	* @param pDevIns The device instance.
3114	*/
3115	DECLR3CALLBACKMEMBER(R0PTRTYPE(PPDMCRITSECT), pfnCritSectGetNopR0,(PPDMDEVINS pDevIns));
3116
3117	/**
3118	* Gets the NOP critical section.
3119	*
3120	* @returns The raw-mode context address of the NOP critical section.
3121	* @param pDevIns The device instance.
3122	*/
3123	DECLR3CALLBACKMEMBER(RCPTRTYPE(PPDMCRITSECT), pfnCritSectGetNopRC,(PPDMDEVINS pDevIns));
3124
3125	/**
3126	* Changes the device level critical section from the automatically created
3127	* default to one desired by the device constructor.
3128	*
3129	* @returns VBox status code.
3130	* @param pDevIns The device instance.
3131	* @param pCritSect The critical section to use. NULL is not
3132	* valid, instead use the NOP critical
3133	* section.
3134	*/
3135	DECLR3CALLBACKMEMBER(int, pfnSetDeviceCritSect,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect));
3136
3137	/**
3138	* Creates a PDM thread.
3139	*
3140	* This differs from the RTThreadCreate() API in that PDM takes care of suspending,
3141	* resuming, and destroying the thread as the VM state changes.
3142	*
3143	* @returns VBox status code.
3144	* @param pDevIns The device instance.
3145	* @param ppThread Where to store the thread 'handle'.
3146	* @param pvUser The user argument to the thread function.
3147	* @param pfnThread The thread function.
3148	* @param pfnWakeup The wakup callback. This is called on the EMT
3149	* thread when a state change is pending.
3150	* @param cbStack See RTThreadCreate.
3151	* @param enmType See RTThreadCreate.
3152	* @param pszName See RTThreadCreate.
3153	* @remarks The device critical section will NOT be entered prior to invoking
3154	* the function pointers.
3155	*/
3156	DECLR3CALLBACKMEMBER(int, pfnThreadCreate,(PPDMDEVINS pDevIns, PPPDMTHREAD ppThread, void *pvUser, PFNPDMTHREADDEV pfnThread,
3157	PFNPDMTHREADWAKEUPDEV pfnWakeup, size_t cbStack, RTTHREADTYPE enmType, const char *pszName));
3158
3159	/**
3160	* Set up asynchronous handling of a suspend, reset or power off notification.
3161	*
3162	* This shall only be called when getting the notification. It must be called
3163	* for each one.
3164	*
3165	* @returns VBox status code.
3166	* @param pDevIns The device instance.
3167	* @param pfnAsyncNotify The callback.
3168	* @thread EMT(0)
3169	* @remarks The caller will enter the device critical section prior to invoking
3170	* the callback.
3171	*/
3172	DECLR3CALLBACKMEMBER(int, pfnSetAsyncNotification, (PPDMDEVINS pDevIns, PFNPDMDEVASYNCNOTIFY pfnAsyncNotify));
3173
3174	/**
3175	* Notify EMT(0) that the device has completed the asynchronous notification
3176	* handling.
3177	*
3178	* This can be called at any time, spurious calls will simply be ignored.
3179	*
3180	* @param pDevIns The device instance.
3181	* @thread Any
3182	*/
3183	DECLR3CALLBACKMEMBER(void, pfnAsyncNotificationCompleted, (PPDMDEVINS pDevIns));
3184
3185	/**
3186	* Register the RTC device.
3187	*
3188	* @returns VBox status code.
3189	* @param pDevIns The device instance.
3190	* @param pRtcReg Pointer to a RTC registration structure.
3191	* @param ppRtcHlp Where to store the pointer to the helper
3192	* functions.
3193	*/
3194	DECLR3CALLBACKMEMBER(int, pfnRTCRegister,(PPDMDEVINS pDevIns, PCPDMRTCREG pRtcReg, PCPDMRTCHLP *ppRtcHlp));
3195
3196	/**
3197	* Register the PCI Bus.
3198	*
3199	* @returns VBox status code.
3200	* @param pDevIns The device instance.
3201	* @param pPciBusReg Pointer to PCI bus registration structure.
3202	* @param ppPciHlpR3 Where to store the pointer to the PCI Bus
3203	* helpers.
3204	*/
3205	DECLR3CALLBACKMEMBER(int, pfnPCIBusRegister,(PPDMDEVINS pDevIns, PPDMPCIBUSREG pPciBusReg, PCPDMPCIHLPR3 *ppPciHlpR3));
3206
3207	/**
3208	* Register the PIC device.
3209	*
3210	* @returns VBox status code.
3211	* @param pDevIns The device instance.
3212	* @param pPicReg Pointer to a PIC registration structure.
3213	* @param ppPicHlpR3 Where to store the pointer to the PIC HC
3214	* helpers.
3215	*/
3216	DECLR3CALLBACKMEMBER(int, pfnPICRegister,(PPDMDEVINS pDevIns, PPDMPICREG pPicReg, PCPDMPICHLPR3 *ppPicHlpR3));
3217
3218	/**
3219	* Register the APIC device.
3220	*
3221	* @returns VBox status code.
3222	* @param pDevIns The device instance.
3223	* @param pApicReg Pointer to a APIC registration structure.
3224	* @param ppApicHlpR3 Where to store the pointer to the APIC helpers.
3225	*/
3226	DECLR3CALLBACKMEMBER(int, pfnAPICRegister,(PPDMDEVINS pDevIns, PPDMAPICREG pApicReg, PCPDMAPICHLPR3 *ppApicHlpR3));
3227
3228	/**
3229	* Register the I/O APIC device.
3230	*
3231	* @returns VBox status code.
3232	* @param pDevIns The device instance.
3233	* @param pIoApicReg Pointer to a I/O APIC registration structure.
3234	* @param ppIoApicHlpR3 Where to store the pointer to the IOAPIC
3235	* helpers.
3236	*/
3237	DECLR3CALLBACKMEMBER(int, pfnIOAPICRegister,(PPDMDEVINS pDevIns, PPDMIOAPICREG pIoApicReg, PCPDMIOAPICHLPR3 *ppIoApicHlpR3));
3238
3239	/**
3240	* Register the HPET device.
3241	*
3242	* @returns VBox status code.
3243	* @param pDevIns The device instance.
3244	* @param pHpetReg Pointer to a HPET registration structure.
3245	* @param ppHpetHlpR3 Where to store the pointer to the HPET
3246	* helpers.
3247	*/
3248	DECLR3CALLBACKMEMBER(int, pfnHPETRegister,(PPDMDEVINS pDevIns, PPDMHPETREG pHpetReg, PCPDMHPETHLPR3 *ppHpetHlpR3));
3249
3250	/**
3251	* Register a raw PCI device.
3252	*
3253	* @returns VBox status code.
3254	* @param pDevIns The device instance.
3255	* @param pHpetReg Pointer to a raw PCI registration structure.
3256	* @param ppPciRawHlpR3 Where to store the pointer to the raw PCI
3257	* device helpers.
3258	*/
3259	DECLR3CALLBACKMEMBER(int, pfnPciRawRegister,(PPDMDEVINS pDevIns, PPDMPCIRAWREG pPciRawReg, PCPDMPCIRAWHLPR3 *ppPciRawHlpR3));
3260
3261	/**
3262	* Register the DMA device.
3263	*
3264	* @returns VBox status code.
3265	* @param pDevIns The device instance.
3266	* @param pDmacReg Pointer to a DMAC registration structure.
3267	* @param ppDmacHlp Where to store the pointer to the DMA helpers.
3268	*/
3269	DECLR3CALLBACKMEMBER(int, pfnDMACRegister,(PPDMDEVINS pDevIns, PPDMDMACREG pDmacReg, PCPDMDMACHLP *ppDmacHlp));
3270
3271	/**
3272	* Register transfer function for DMA channel.
3273	*
3274	* @returns VBox status code.
3275	* @param pDevIns The device instance.
3276	* @param uChannel Channel number.
3277	* @param pfnTransferHandler Device specific transfer callback function.
3278	* @param pvUser User pointer to pass to the callback.
3279	* @thread EMT
3280	*/
3281	DECLR3CALLBACKMEMBER(int, pfnDMARegister,(PPDMDEVINS pDevIns, unsigned uChannel, PFNDMATRANSFERHANDLER pfnTransferHandler, void *pvUser));
3282
3283	/**
3284	* Read memory.
3285	*
3286	* @returns VBox status code.
3287	* @param pDevIns The device instance.
3288	* @param uChannel Channel number.
3289	* @param pvBuffer Pointer to target buffer.
3290	* @param off DMA position.
3291	* @param cbBlock Block size.
3292	* @param pcbRead Where to store the number of bytes which was
3293	* read. optional.
3294	* @thread EMT
3295	*/
3296	DECLR3CALLBACKMEMBER(int, pfnDMAReadMemory,(PPDMDEVINS pDevIns, unsigned uChannel, void pvBuffer, uint32_t off, uint32_t cbBlock, uint32_t pcbRead));
3297
3298	/**
3299	* Write memory.
3300	*
3301	* @returns VBox status code.
3302	* @param pDevIns The device instance.
3303	* @param uChannel Channel number.
3304	* @param pvBuffer Memory to write.
3305	* @param off DMA position.
3306	* @param cbBlock Block size.
3307	* @param pcbWritten Where to store the number of bytes which was
3308	* written. optional.
3309	* @thread EMT
3310	*/
3311	DECLR3CALLBACKMEMBER(int, pfnDMAWriteMemory,(PPDMDEVINS pDevIns, unsigned uChannel, const void pvBuffer, uint32_t off, uint32_t cbBlock, uint32_t pcbWritten));
3312
3313	/**
3314	* Set the DREQ line.
3315	*
3316	* @returns VBox status code.
3317	* @param pDevIns Device instance.
3318	* @param uChannel Channel number.
3319	* @param uLevel Level of the line.
3320	* @thread EMT
3321	*/
3322	DECLR3CALLBACKMEMBER(int, pfnDMASetDREQ,(PPDMDEVINS pDevIns, unsigned uChannel, unsigned uLevel));
3323
3324	/**
3325	* Get channel mode.
3326	*
3327	* @returns Channel mode. See specs.
3328	* @param pDevIns The device instance.
3329	* @param uChannel Channel number.
3330	* @thread EMT
3331	*/
3332	DECLR3CALLBACKMEMBER(uint8_t, pfnDMAGetChannelMode,(PPDMDEVINS pDevIns, unsigned uChannel));
3333
3334	/**
3335	* Schedule DMA execution.
3336	*
3337	* @param pDevIns The device instance.
3338	* @thread Any thread.
3339	*/
3340	DECLR3CALLBACKMEMBER(void, pfnDMASchedule,(PPDMDEVINS pDevIns));
3341
3342	/**
3343	* Write CMOS value and update the checksum(s).
3344	*
3345	* @returns VBox status code.
3346	* @param pDevIns The device instance.
3347	* @param iReg The CMOS register index.
3348	* @param u8Value The CMOS register value.
3349	* @thread EMT
3350	*/
3351	DECLR3CALLBACKMEMBER(int, pfnCMOSWrite,(PPDMDEVINS pDevIns, unsigned iReg, uint8_t u8Value));
3352
3353	/**
3354	* Read CMOS value.
3355	*
3356	* @returns VBox status code.
3357	* @param pDevIns The device instance.
3358	* @param iReg The CMOS register index.
3359	* @param pu8Value Where to store the CMOS register value.
3360	* @thread EMT
3361	*/
3362	DECLR3CALLBACKMEMBER(int, pfnCMOSRead,(PPDMDEVINS pDevIns, unsigned iReg, uint8_t *pu8Value));
3363
3364	/**
3365	* Assert that the current thread is the emulation thread.
3366	*
3367	* @returns True if correct.
3368	* @returns False if wrong.
3369	* @param pDevIns The device instance.
3370	* @param pszFile Filename of the assertion location.
3371	* @param iLine The linenumber of the assertion location.
3372	* @param pszFunction Function of the assertion location.
3373	*/
3374	DECLR3CALLBACKMEMBER(bool, pfnAssertEMT,(PPDMDEVINS pDevIns, const char pszFile, unsigned iLine, const char pszFunction));
3375
3376	/**
3377	* Assert that the current thread is NOT the emulation thread.
3378	*
3379	* @returns True if correct.
3380	* @returns False if wrong.
3381	* @param pDevIns The device instance.
3382	* @param pszFile Filename of the assertion location.
3383	* @param iLine The linenumber of the assertion location.
3384	* @param pszFunction Function of the assertion location.
3385	*/
3386	DECLR3CALLBACKMEMBER(bool, pfnAssertOther,(PPDMDEVINS pDevIns, const char pszFile, unsigned iLine, const char pszFunction));
3387
3388	/**
3389	* Resolves the symbol for a raw-mode context interface.
3390	*
3391	* @returns VBox status code.
3392	* @param pDevIns The device instance.
3393	* @param pvInterface The interface structure.
3394	* @param cbInterface The size of the interface structure.
3395	* @param pszSymPrefix What to prefix the symbols in the list with
3396	* before resolving them. This must start with
3397	* 'dev' and contain the driver name.
3398	* @param pszSymList List of symbols corresponding to the interface.
3399	* There is generally a there is generally a define
3400	* holding this list associated with the interface
3401	* definition (INTERFACE_SYM_LIST). For more
3402	* details see PDMR3LdrGetInterfaceSymbols.
3403	* @thread EMT
3404	*/
3405	DECLR3CALLBACKMEMBER(int, pfnLdrGetRCInterfaceSymbols,(PPDMDEVINS pDevIns, void *pvInterface, size_t cbInterface,
3406	const char pszSymPrefix, const char pszSymList));
3407
3408	/**
3409	* Resolves the symbol for a ring-0 context interface.
3410	*
3411	* @returns VBox status code.
3412	* @param pDevIns The device instance.
3413	* @param pvInterface The interface structure.
3414	* @param cbInterface The size of the interface structure.
3415	* @param pszSymPrefix What to prefix the symbols in the list with
3416	* before resolving them. This must start with
3417	* 'dev' and contain the driver name.
3418	* @param pszSymList List of symbols corresponding to the interface.
3419	* There is generally a there is generally a define
3420	* holding this list associated with the interface
3421	* definition (INTERFACE_SYM_LIST). For more
3422	* details see PDMR3LdrGetInterfaceSymbols.
3423	* @thread EMT
3424	*/
3425	DECLR3CALLBACKMEMBER(int, pfnLdrGetR0InterfaceSymbols,(PPDMDEVINS pDevIns, void *pvInterface, size_t cbInterface,
3426	const char pszSymPrefix, const char pszSymList));
3427
3428	/**
3429	* Call the ring-0 request handler routine of the device.
3430	*
3431	* For this to work, the device must be ring-0 enabled and export a request
3432	* handler function. The name of the function must be the device name in
3433	* the PDMDRVREG struct prefixed with 'drvR0' and suffixed with
3434	* 'ReqHandler'. The device name will be captialized. It shall take the
3435	* exact same arguments as this function and be declared using
3436	* PDMBOTHCBDECL. See FNPDMDEVREQHANDLERR0.
3437	*
3438	* Unlike PDMDrvHlpCallR0, this is current unsuitable for more than a call
3439	* or two as the handler address will be resolved on each invocation. This
3440	* is the reason for the EMT only restriction as well.
3441	*
3442	* @returns VBox status code.
3443	* @retval VERR_SYMBOL_NOT_FOUND if the device doesn't export the required
3444	* handler function.
3445	* @retval VERR_ACCESS_DENIED if the device isn't ring-0 capable.
3446	*
3447	* @param pDevIns The device instance.
3448	* @param uOperation The operation to perform.
3449	* @param u64Arg 64-bit integer argument.
3450	* @thread EMT
3451	*/
3452	DECLR3CALLBACKMEMBER(int, pfnCallR0,(PPDMDEVINS pDevIns, uint32_t uOperation, uint64_t u64Arg));
3453
3454	/**
3455	* Gets the reason for the most recent VM suspend.
3456	*
3457	* @returns The suspend reason. VMSUSPENDREASON_INVALID is returned if no
3458	* suspend has been made or if the pDevIns is invalid.
3459	* @param pDevIns The device instance.
3460	*/
3461	DECLR3CALLBACKMEMBER(VMSUSPENDREASON, pfnVMGetSuspendReason,(PPDMDEVINS pDevIns));
3462
3463	/**
3464	* Gets the reason for the most recent VM resume.
3465	*
3466	* @returns The resume reason. VMRESUMEREASON_INVALID is returned if no
3467	* resume has been made or if the pDevIns is invalid.
3468	* @param pDevIns The device instance.
3469	*/
3470	DECLR3CALLBACKMEMBER(VMRESUMEREASON, pfnVMGetResumeReason,(PPDMDEVINS pDevIns));
3471
3472
3473	/** Space reserved for future members.
3474	* @{ */
3475	DECLR3CALLBACKMEMBER(void, pfnReserved1,(void));
3476	DECLR3CALLBACKMEMBER(void, pfnReserved2,(void));
3477	DECLR3CALLBACKMEMBER(void, pfnReserved3,(void));
3478	DECLR3CALLBACKMEMBER(void, pfnReserved4,(void));
3479	DECLR3CALLBACKMEMBER(void, pfnReserved5,(void));
3480	DECLR3CALLBACKMEMBER(void, pfnReserved6,(void));
3481	DECLR3CALLBACKMEMBER(void, pfnReserved7,(void));
3482	/*DECLR3CALLBACKMEMBER(void, pfnReserved8,(void));
3483	DECLR3CALLBACKMEMBER(void, pfnReserved9,(void));*/
3484	/DECLR3CALLBACKMEMBER(void, pfnReserved10,(void));/
3485	/** @} */
3486
3487
3488	/** API available to trusted devices only.
3489	*
3490	* These APIs are providing unrestricted access to the guest and the VM,
3491	* or they are interacting intimately with PDM.
3492	*
3493	* @{
3494	*/
3495
3496	/**
3497	* Gets the user mode VM handle. Restricted API.
3498	*
3499	* @returns User mode VM Handle.
3500	* @param pDevIns The device instance.
3501	*/
3502	DECLR3CALLBACKMEMBER(PUVM, pfnGetUVM,(PPDMDEVINS pDevIns));
3503
3504	/**
3505	* Gets the global VM handle. Restricted API.
3506	*
3507	* @returns VM Handle.
3508	* @param pDevIns The device instance.
3509	*/
3510	DECLR3CALLBACKMEMBER(PVM, pfnGetVM,(PPDMDEVINS pDevIns));
3511
3512	/**
3513	* Gets the VMCPU handle. Restricted API.
3514	*
3515	* @returns VMCPU Handle.
3516	* @param pDevIns The device instance.
3517	*/
3518	DECLR3CALLBACKMEMBER(PVMCPU, pfnGetVMCPU,(PPDMDEVINS pDevIns));
3519
3520	/**
3521	* Registers the VMM device heap
3522	*
3523	* @returns VBox status code.
3524	* @param pDevIns The device instance.
3525	* @param GCPhys The physical address.
3526	* @param pvHeap Ring 3 heap pointer.
3527	* @param cbSize Size of the heap.
3528	* @thread EMT.
3529	*/
3530	DECLR3CALLBACKMEMBER(int, pfnRegisterVMMDevHeap,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTR3PTR pvHeap, unsigned cbSize));
3531
3532	/**
3533	* Unregisters the VMM device heap
3534	*
3535	* @returns VBox status code.
3536	* @param pDevIns The device instance.
3537	* @param GCPhys The physical address.
3538	* @thread EMT.
3539	*/
3540	DECLR3CALLBACKMEMBER(int, pfnUnregisterVMMDevHeap,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys));
3541
3542	/**
3543	* Resets the VM.
3544	*
3545	* @returns The appropriate VBox status code to pass around on reset.
3546	* @param pDevIns The device instance.
3547	* @thread The emulation thread.
3548	*/
3549	DECLR3CALLBACKMEMBER(int, pfnVMReset,(PPDMDEVINS pDevIns));
3550
3551	/**
3552	* Suspends the VM.
3553	*
3554	* @returns The appropriate VBox status code to pass around on suspend.
3555	* @param pDevIns The device instance.
3556	* @thread The emulation thread.
3557	*/
3558	DECLR3CALLBACKMEMBER(int, pfnVMSuspend,(PPDMDEVINS pDevIns));
3559
3560	/**
3561	* Suspends, saves and powers off the VM.
3562	*
3563	* @returns The appropriate VBox status code to pass around.
3564	* @param pDevIns The device instance.
3565	* @thread An emulation thread.
3566	*/
3567	DECLR3CALLBACKMEMBER(int, pfnVMSuspendSaveAndPowerOff,(PPDMDEVINS pDevIns));
3568
3569	/**
3570	* Power off the VM.
3571	*
3572	* @returns The appropriate VBox status code to pass around on power off.
3573	* @param pDevIns The device instance.
3574	* @thread The emulation thread.
3575	*/
3576	DECLR3CALLBACKMEMBER(int, pfnVMPowerOff,(PPDMDEVINS pDevIns));
3577
3578	/**
3579	* Checks if the Gate A20 is enabled or not.
3580	*
3581	* @returns true if A20 is enabled.
3582	* @returns false if A20 is disabled.
3583	* @param pDevIns The device instance.
3584	* @thread The emulation thread.
3585	*/
3586	DECLR3CALLBACKMEMBER(bool, pfnA20IsEnabled,(PPDMDEVINS pDevIns));
3587
3588	/**
3589	* Enables or disables the Gate A20.
3590	*
3591	* @param pDevIns The device instance.
3592	* @param fEnable Set this flag to enable the Gate A20; clear it
3593	* to disable.
3594	* @thread The emulation thread.
3595	*/
3596	DECLR3CALLBACKMEMBER(void, pfnA20Set,(PPDMDEVINS pDevIns, bool fEnable));
3597
3598	/**
3599	* Get the specified CPUID leaf for the virtual CPU associated with the calling
3600	* thread.
3601	*
3602	* @param pDevIns The device instance.
3603	* @param iLeaf The CPUID leaf to get.
3604	* @param pEax Where to store the EAX value.
3605	* @param pEbx Where to store the EBX value.
3606	* @param pEcx Where to store the ECX value.
3607	* @param pEdx Where to store the EDX value.
3608	* @thread EMT.
3609	*/
3610	DECLR3CALLBACKMEMBER(void, pfnGetCpuId,(PPDMDEVINS pDevIns, uint32_t iLeaf, uint32_t pEax, uint32_t pEbx, uint32_t pEcx, uint32_t pEdx));
3611
3612	/**
3613	* Get the current virtual clock time in a VM. The clock frequency must be
3614	* queried separately.
3615	*
3616	* @returns Current clock time.
3617	* @param pDevIns The device instance.
3618	*/
3619	DECLR3CALLBACKMEMBER(uint64_t, pfnTMTimeVirtGet,(PPDMDEVINS pDevIns));
3620
3621	/**
3622	* Get the frequency of the virtual clock.
3623	*
3624	* @returns The clock frequency (not variable at run-time).
3625	* @param pDevIns The device instance.
3626	*/
3627	DECLR3CALLBACKMEMBER(uint64_t, pfnTMTimeVirtGetFreq,(PPDMDEVINS pDevIns));
3628
3629	/**
3630	* Get the current virtual clock time in a VM, in nanoseconds.
3631	*
3632	* @returns Current clock time (in ns).
3633	* @param pDevIns The device instance.
3634	*/
3635	DECLR3CALLBACKMEMBER(uint64_t, pfnTMTimeVirtGetNano,(PPDMDEVINS pDevIns));
3636
3637	/**
3638	* Gets the support driver session.
3639	*
3640	* This is intended for working with the semaphore API.
3641	*
3642	* @returns Support driver session handle.
3643	* @param pDrvIns The driver instance.
3644	*/
3645	DECLR3CALLBACKMEMBER(PSUPDRVSESSION, pfnGetSupDrvSession,(PPDMDEVINS pDevIns));
3646
3647	/** @} */
3648
3649	/** Just a safety precaution. (PDM_DEVHLPR3_VERSION) */
3650	uint32_t u32TheEnd;
3651	} PDMDEVHLPR3;
3652	#endif /* !IN_RING3 */
3653	/** Pointer to the R3 PDM Device API. */
3654	typedef R3PTRTYPE(struct PDMDEVHLPR3 *) PPDMDEVHLPR3;
3655	/** Pointer to the R3 PDM Device API, const variant. */
3656	typedef R3PTRTYPE(const struct PDMDEVHLPR3 *) PCPDMDEVHLPR3;
3657
3658	/** Current PDMDEVHLPR3 version number. */
3659	#define PDM_DEVHLPR3_VERSION PDM_VERSION_MAKE(0xffe7, 12, 1)
3660
3661
3662	/**
3663	* PDM Device API - RC Variant.
3664	*/
3665	typedef struct PDMDEVHLPRC
3666	{
3667	/** Structure version. PDM_DEVHLPRC_VERSION defines the current version. */
3668	uint32_t u32Version;
3669
3670	/**
3671	* Bus master physical memory read.
3672	*
3673	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_READ_BM_DISABLED, later maybe
3674	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
3675	* @param pDevIns The device instance.
3676	* @param GCPhys Physical address start reading from.
3677	* @param pvBuf Where to put the read bits.
3678	* @param cbRead How many bytes to read.
3679	* @thread Any thread, but the call may involve the emulation thread.
3680	*/
3681	DECLRCCALLBACKMEMBER(int, pfnPCIPhysRead,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead));
3682
3683	/**
3684	* Bus master physical memory write.
3685	*
3686	* @returns VINF_SUCCESS or VERR_PGM_PCI_PHYS_WRITE_BM_DISABLED, later maybe
3687	* VERR_EM_MEMORY. The informational status shall NOT be propagated!
3688	* @param pDevIns The device instance.
3689	* @param GCPhys Physical address to write to.
3690	* @param pvBuf What to write.
3691	* @param cbWrite How many bytes to write.
3692	* @thread Any thread, but the call may involve the emulation thread.
3693	*/
3694	DECLRCCALLBACKMEMBER(int, pfnPCIPhysWrite,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite));
3695
3696	/**
3697	* Set the IRQ for a PCI device.
3698	*
3699	* @param pDevIns Device instance.
3700	* @param iIrq IRQ number to set.
3701	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
3702	* @thread Any thread, but will involve the emulation thread.
3703	*/
3704	DECLRCCALLBACKMEMBER(void, pfnPCISetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
3705
3706	/**
3707	* Set ISA IRQ for a device.
3708	*
3709	* @param pDevIns Device instance.
3710	* @param iIrq IRQ number to set.
3711	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
3712	* @thread Any thread, but will involve the emulation thread.
3713	*/
3714	DECLRCCALLBACKMEMBER(void, pfnISASetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
3715
3716	/**
3717	* Read physical memory.
3718	*
3719	* @returns VINF_SUCCESS (for now).
3720	* @param pDevIns Device instance.
3721	* @param GCPhys Physical address start reading from.
3722	* @param pvBuf Where to put the read bits.
3723	* @param cbRead How many bytes to read.
3724	*/
3725	DECLRCCALLBACKMEMBER(int, pfnPhysRead,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead));
3726
3727	/**
3728	* Write to physical memory.
3729	*
3730	* @returns VINF_SUCCESS for now, and later maybe VERR_EM_MEMORY.
3731	* @param pDevIns Device instance.
3732	* @param GCPhys Physical address to write to.
3733	* @param pvBuf What to write.
3734	* @param cbWrite How many bytes to write.
3735	*/
3736	DECLRCCALLBACKMEMBER(int, pfnPhysWrite,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite));
3737
3738	/**
3739	* Checks if the Gate A20 is enabled or not.
3740	*
3741	* @returns true if A20 is enabled.
3742	* @returns false if A20 is disabled.
3743	* @param pDevIns Device instance.
3744	* @thread The emulation thread.
3745	*/
3746	DECLRCCALLBACKMEMBER(bool, pfnA20IsEnabled,(PPDMDEVINS pDevIns));
3747
3748	/**
3749	* Gets the VM state.
3750	*
3751	* @returns VM state.
3752	* @param pDevIns The device instance.
3753	* @thread Any thread (just keep in mind that it's volatile info).
3754	*/
3755	DECLRCCALLBACKMEMBER(VMSTATE, pfnVMState, (PPDMDEVINS pDevIns));
3756
3757	/**
3758	* Set the VM error message
3759	*
3760	* @returns rc.
3761	* @param pDrvIns Driver instance.
3762	* @param rc VBox status code.
3763	* @param RT_SRC_POS_DECL Use RT_SRC_POS.
3764	* @param pszFormat Error message format string.
3765	* @param ... Error message arguments.
3766	*/
3767	DECLRCCALLBACKMEMBER(int, pfnVMSetError,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, ...));
3768
3769	/**
3770	* Set the VM error message
3771	*
3772	* @returns rc.
3773	* @param pDrvIns Driver instance.
3774	* @param rc VBox status code.
3775	* @param RT_SRC_POS_DECL Use RT_SRC_POS.
3776	* @param pszFormat Error message format string.
3777	* @param va Error message arguments.
3778	*/
3779	DECLRCCALLBACKMEMBER(int, pfnVMSetErrorV,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va));
3780
3781	/**
3782	* Set the VM runtime error message
3783	*
3784	* @returns VBox status code.
3785	* @param pDevIns Device instance.
3786	* @param fFlags The action flags. See VMSETRTERR_FLAGS_*.
3787	* @param pszErrorId Error ID string.
3788	* @param pszFormat Error message format string.
3789	* @param ... Error message arguments.
3790	*/
3791	DECLRCCALLBACKMEMBER(int, pfnVMSetRuntimeError,(PPDMDEVINS pDevIns, uint32_t fFlags, const char pszErrorId, const char pszFormat, ...));
3792
3793	/**
3794	* Set the VM runtime error message
3795	*
3796	* @returns VBox status code.
3797	* @param pDevIns Device instance.
3798	* @param fFlags The action flags. See VMSETRTERR_FLAGS_*.
3799	* @param pszErrorId Error ID string.
3800	* @param pszFormat Error message format string.
3801	* @param va Error message arguments.
3802	*/
3803	DECLRCCALLBACKMEMBER(int, pfnVMSetRuntimeErrorV,(PPDMDEVINS pDevIns, uint32_t fFlags, const char pszErrorId, const char pszFormat, va_list va));
3804
3805	/**
3806	* Set parameters for pending MMIO patch operation
3807	*
3808	* @returns VBox status code.
3809	* @param pDevIns Device instance.
3810	* @param GCPhys MMIO physical address
3811	* @param pCachedData GC pointer to cached data
3812	*/
3813	DECLRCCALLBACKMEMBER(int, pfnPATMSetMMIOPatchInfo,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTGCPTR pCachedData));
3814
3815	/**
3816	* Gets the VM handle. Restricted API.
3817	*
3818	* @returns VM Handle.
3819	* @param pDevIns Device instance.
3820	*/
3821	DECLRCCALLBACKMEMBER(PVM, pfnGetVM,(PPDMDEVINS pDevIns));
3822
3823	/**
3824	* Gets the VMCPU handle. Restricted API.
3825	*
3826	* @returns VMCPU Handle.
3827	* @param pDevIns The device instance.
3828	*/
3829	DECLRCCALLBACKMEMBER(PVMCPU, pfnGetVMCPU,(PPDMDEVINS pDevIns));
3830
3831	/**
3832	* Get the current virtual clock time in a VM. The clock frequency must be
3833	* queried separately.
3834	*
3835	* @returns Current clock time.
3836	* @param pDevIns The device instance.
3837	*/
3838	DECLRCCALLBACKMEMBER(uint64_t, pfnTMTimeVirtGet,(PPDMDEVINS pDevIns));
3839
3840	/**
3841	* Get the frequency of the virtual clock.
3842	*
3843	* @returns The clock frequency (not variable at run-time).
3844	* @param pDevIns The device instance.
3845	*/
3846	DECLRCCALLBACKMEMBER(uint64_t, pfnTMTimeVirtGetFreq,(PPDMDEVINS pDevIns));
3847
3848	/**
3849	* Get the current virtual clock time in a VM, in nanoseconds.
3850	*
3851	* @returns Current clock time (in ns).
3852	* @param pDevIns The device instance.
3853	*/
3854	DECLRCCALLBACKMEMBER(uint64_t, pfnTMTimeVirtGetNano,(PPDMDEVINS pDevIns));
3855
3856	/**
3857	* Gets the trace buffer handle.
3858	*
3859	* This is used by the macros found in VBox/vmm/dbgftrace.h and is not
3860	* really inteded for direct usage, thus no inline wrapper function.
3861	*
3862	* @returns Trace buffer handle or NIL_RTTRACEBUF.
3863	* @param pDevIns The device instance.
3864	*/
3865	DECLRCCALLBACKMEMBER(RTTRACEBUF, pfnDBGFTraceBuf,(PPDMDEVINS pDevIns));
3866
3867	/** Just a safety precaution. */
3868	uint32_t u32TheEnd;
3869	} PDMDEVHLPRC;
3870	/** Pointer PDM Device RC API. */
3871	typedef RCPTRTYPE(struct PDMDEVHLPRC *) PPDMDEVHLPRC;
3872	/** Pointer PDM Device RC API. */
3873	typedef RCPTRTYPE(const struct PDMDEVHLPRC *) PCPDMDEVHLPRC;
3874
3875	/** Current PDMDEVHLP version number. */
3876	#define PDM_DEVHLPRC_VERSION PDM_VERSION_MAKE(0xffe6, 3, 1)
3877
3878
3879	/**
3880	* PDM Device API - R0 Variant.
3881	*/
3882	typedef struct PDMDEVHLPR0
3883	{
3884	/** Structure version. PDM_DEVHLPR0_VERSION defines the current version. */
3885	uint32_t u32Version;
3886
3887	/**
3888	* Bus master physical memory read.
3889	*
3890	* @returns VINF_SUCCESS or VERR_PDM_NOT_PCI_BUS_MASTER, later maybe
3891	* VERR_EM_MEMORY.
3892	* @param pDevIns The device instance.
3893	* @param GCPhys Physical address start reading from.
3894	* @param pvBuf Where to put the read bits.
3895	* @param cbRead How many bytes to read.
3896	* @thread Any thread, but the call may involve the emulation thread.
3897	*/
3898	DECLR0CALLBACKMEMBER(int, pfnPCIPhysRead,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead));
3899
3900	/**
3901	* Bus master physical memory write.
3902	*
3903	* @returns VINF_SUCCESS or VERR_PDM_NOT_PCI_BUS_MASTER, later maybe
3904	* VERR_EM_MEMORY.
3905	* @param pDevIns The device instance.
3906	* @param GCPhys Physical address to write to.
3907	* @param pvBuf What to write.
3908	* @param cbWrite How many bytes to write.
3909	* @thread Any thread, but the call may involve the emulation thread.
3910	*/
3911	DECLR0CALLBACKMEMBER(int, pfnPCIPhysWrite,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite));
3912
3913	/**
3914	* Set the IRQ for a PCI device.
3915	*
3916	* @param pDevIns Device instance.
3917	* @param iIrq IRQ number to set.
3918	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
3919	* @thread Any thread, but will involve the emulation thread.
3920	*/
3921	DECLR0CALLBACKMEMBER(void, pfnPCISetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
3922
3923	/**
3924	* Set ISA IRQ for a device.
3925	*
3926	* @param pDevIns Device instance.
3927	* @param iIrq IRQ number to set.
3928	* @param iLevel IRQ level. See the PDM_IRQ_LEVEL_* \#defines.
3929	* @thread Any thread, but will involve the emulation thread.
3930	*/
3931	DECLR0CALLBACKMEMBER(void, pfnISASetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
3932
3933	/**
3934	* Read physical memory.
3935	*
3936	* @returns VINF_SUCCESS (for now).
3937	* @param pDevIns Device instance.
3938	* @param GCPhys Physical address start reading from.
3939	* @param pvBuf Where to put the read bits.
3940	* @param cbRead How many bytes to read.
3941	*/
3942	DECLR0CALLBACKMEMBER(int, pfnPhysRead,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead));
3943
3944	/**
3945	* Write to physical memory.
3946	*
3947	* @returns VINF_SUCCESS for now, and later maybe VERR_EM_MEMORY.
3948	* @param pDevIns Device instance.
3949	* @param GCPhys Physical address to write to.
3950	* @param pvBuf What to write.
3951	* @param cbWrite How many bytes to write.
3952	*/
3953	DECLR0CALLBACKMEMBER(int, pfnPhysWrite,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite));
3954
3955	/**
3956	* Checks if the Gate A20 is enabled or not.
3957	*
3958	* @returns true if A20 is enabled.
3959	* @returns false if A20 is disabled.
3960	* @param pDevIns Device instance.
3961	* @thread The emulation thread.
3962	*/
3963	DECLR0CALLBACKMEMBER(bool, pfnA20IsEnabled,(PPDMDEVINS pDevIns));
3964
3965	/**
3966	* Gets the VM state.
3967	*
3968	* @returns VM state.
3969	* @param pDevIns The device instance.
3970	* @thread Any thread (just keep in mind that it's volatile info).
3971	*/
3972	DECLR0CALLBACKMEMBER(VMSTATE, pfnVMState, (PPDMDEVINS pDevIns));
3973
3974	/**
3975	* Set the VM error message
3976	*
3977	* @returns rc.
3978	* @param pDrvIns Driver instance.
3979	* @param rc VBox status code.
3980	* @param RT_SRC_POS_DECL Use RT_SRC_POS.
3981	* @param pszFormat Error message format string.
3982	* @param ... Error message arguments.
3983	*/
3984	DECLR0CALLBACKMEMBER(int, pfnVMSetError,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, ...));
3985
3986	/**
3987	* Set the VM error message
3988	*
3989	* @returns rc.
3990	* @param pDrvIns Driver instance.
3991	* @param rc VBox status code.
3992	* @param RT_SRC_POS_DECL Use RT_SRC_POS.
3993	* @param pszFormat Error message format string.
3994	* @param va Error message arguments.
3995	*/
3996	DECLR0CALLBACKMEMBER(int, pfnVMSetErrorV,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va));
3997
3998	/**
3999	* Set the VM runtime error message
4000	*
4001	* @returns VBox status code.
4002	* @param pDevIns Device instance.
4003	* @param fFlags The action flags. See VMSETRTERR_FLAGS_*.
4004	* @param pszErrorId Error ID string.
4005	* @param pszFormat Error message format string.
4006	* @param ... Error message arguments.
4007	*/
4008	DECLR0CALLBACKMEMBER(int, pfnVMSetRuntimeError,(PPDMDEVINS pDevIns, uint32_t fFlags, const char pszErrorId, const char pszFormat, ...));
4009
4010	/**
4011	* Set the VM runtime error message
4012	*
4013	* @returns VBox status code.
4014	* @param pDevIns Device instance.
4015	* @param fFlags The action flags. See VMSETRTERR_FLAGS_*.
4016	* @param pszErrorId Error ID string.
4017	* @param pszFormat Error message format string.
4018	* @param va Error message arguments.
4019	*/
4020	DECLR0CALLBACKMEMBER(int, pfnVMSetRuntimeErrorV,(PPDMDEVINS pDevIns, uint32_t fFlags, const char pszErrorId, const char pszFormat, va_list va));
4021
4022	/**
4023	* Set parameters for pending MMIO patch operation
4024	*
4025	* @returns rc.
4026	* @param pDevIns Device instance.
4027	* @param GCPhys MMIO physical address
4028	* @param pCachedData GC pointer to cached data
4029	*/
4030	DECLR0CALLBACKMEMBER(int, pfnPATMSetMMIOPatchInfo,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTGCPTR pCachedData));
4031
4032	/**
4033	* Gets the VM handle. Restricted API.
4034	*
4035	* @returns VM Handle.
4036	* @param pDevIns Device instance.
4037	*/
4038	DECLR0CALLBACKMEMBER(PVM, pfnGetVM,(PPDMDEVINS pDevIns));
4039
4040	/**
4041	* Checks if our current CPU state allows for IO block emulation fallback to the recompiler
4042	*
4043	* @returns true = yes, false = no
4044	* @param pDevIns Device instance.
4045	*/
4046	DECLR0CALLBACKMEMBER(bool, pfnCanEmulateIoBlock,(PPDMDEVINS pDevIns));
4047
4048	/**
4049	* Gets the VMCPU handle. Restricted API.
4050	*
4051	* @returns VMCPU Handle.
4052	* @param pDevIns The device instance.
4053	*/
4054	DECLR0CALLBACKMEMBER(PVMCPU, pfnGetVMCPU,(PPDMDEVINS pDevIns));
4055
4056	/**
4057	* Get the current virtual clock time in a VM. The clock frequency must be
4058	* queried separately.
4059	*
4060	* @returns Current clock time.
4061	* @param pDevIns The device instance.
4062	*/
4063	DECLR0CALLBACKMEMBER(uint64_t, pfnTMTimeVirtGet,(PPDMDEVINS pDevIns));
4064
4065	/**
4066	* Get the frequency of the virtual clock.
4067	*
4068	* @returns The clock frequency (not variable at run-time).
4069	* @param pDevIns The device instance.
4070	*/
4071	DECLR0CALLBACKMEMBER(uint64_t, pfnTMTimeVirtGetFreq,(PPDMDEVINS pDevIns));
4072
4073	/**
4074	* Get the current virtual clock time in a VM, in nanoseconds.
4075	*
4076	* @returns Current clock time (in ns).
4077	* @param pDevIns The device instance.
4078	*/
4079	DECLR0CALLBACKMEMBER(uint64_t, pfnTMTimeVirtGetNano,(PPDMDEVINS pDevIns));
4080
4081	/**
4082	* Gets the trace buffer handle.
4083	*
4084	* This is used by the macros found in VBox/vmm/dbgftrace.h and is not
4085	* really inteded for direct usage, thus no inline wrapper function.
4086	*
4087	* @returns Trace buffer handle or NIL_RTTRACEBUF.
4088	* @param pDevIns The device instance.
4089	*/
4090	DECLR0CALLBACKMEMBER(RTTRACEBUF, pfnDBGFTraceBuf,(PPDMDEVINS pDevIns));
4091
4092	/** Just a safety precaution. */
4093	uint32_t u32TheEnd;
4094	} PDMDEVHLPR0;
4095	/** Pointer PDM Device R0 API. */
4096	typedef R0PTRTYPE(struct PDMDEVHLPR0 *) PPDMDEVHLPR0;
4097	/** Pointer PDM Device GC API. */
4098	typedef R0PTRTYPE(const struct PDMDEVHLPR0 *) PCPDMDEVHLPR0;
4099
4100	/** Current PDMDEVHLP version number. */
4101	#define PDM_DEVHLPR0_VERSION PDM_VERSION_MAKE(0xffe5, 3, 1)
4102
4103
4104
4105	/**
4106	* PDM Device Instance.
4107	*/
4108	typedef struct PDMDEVINS
4109	{
4110	/** Structure version. PDM_DEVINS_VERSION defines the current version. */
4111	uint32_t u32Version;
4112	/** Device instance number. */
4113	uint32_t iInstance;
4114
4115	/** Pointer the GC PDM Device API. */
4116	PCPDMDEVHLPRC pHlpRC;
4117	/** Pointer to device instance data. */
4118	RTRCPTR pvInstanceDataRC;
4119	/** The critical section for the device, see pCritSectXR3. */
4120	RCPTRTYPE(PPDMCRITSECT) pCritSectRoRC;
4121	/** Alignment padding. */
4122	RTRCPTR pAlignmentRC;
4123
4124	/** Pointer the R0 PDM Device API. */
4125	PCPDMDEVHLPR0 pHlpR0;
4126	/** Pointer to device instance data (R0). */
4127	RTR0PTR pvInstanceDataR0;
4128	/** The critical section for the device, see pCritSectXR3. */
4129	R0PTRTYPE(PPDMCRITSECT) pCritSectRoR0;
4130
4131	/** Pointer the HC PDM Device API. */
4132	PCPDMDEVHLPR3 pHlpR3;
4133	/** Pointer to device instance data. */
4134	RTR3PTR pvInstanceDataR3;
4135	/** The critical section for the device.
4136	*
4137	* TM and IOM will enter this critical section before calling into the device
4138	* code. PDM will when doing power on, power off, reset, suspend and resume
4139	* notifications. SSM will currently not, but this will be changed later on.
4140	*
4141	* The device gets a critical section automatically assigned to it before
4142	* the constructor is called. If the constructor wishes to use a different
4143	* critical section, it calls PDMDevHlpSetDeviceCritSect() to change it
4144	* very early on.
4145	*/
4146	R3PTRTYPE(PPDMCRITSECT) pCritSectRoR3;
4147
4148	/** Pointer to device registration structure. */
4149	R3PTRTYPE(PCPDMDEVREG) pReg;
4150	/** Configuration handle. */
4151	R3PTRTYPE(PCFGMNODE) pCfg;
4152
4153	/** The base interface of the device.
4154	*
4155	* The device constructor initializes this if it has any
4156	* device level interfaces to export. To obtain this interface
4157	* call PDMR3QueryDevice(). */
4158	PDMIBASE IBase;
4159
4160	/** Tracing indicator. */
4161	uint32_t fTracing;
4162	/** The tracing ID of this device. */
4163	uint32_t idTracing;
4164	#if HC_ARCH_BITS == 32
4165	/** Align the internal data more naturally. */
4166	uint32_t au32Padding[HC_ARCH_BITS == 32 ? 13 : 0];
4167	#endif
4168
4169	/** Internal data. */
4170	union
4171	{
4172	#ifdef PDMDEVINSINT_DECLARED
4173	PDMDEVINSINT s;
4174	#endif
4175	uint8_t padding[HC_ARCH_BITS == 32 ? 72 : 112 + 0x28];
4176	} Internal;
4177
4178	/** Device instance data. The size of this area is defined
4179	* in the PDMDEVREG::cbInstanceData field. */
4180	char achInstanceData[8];
4181	} PDMDEVINS;
4182
4183	/** Current PDMDEVINS version number. */
4184	#define PDM_DEVINS_VERSION PDM_VERSION_MAKE(0xffe4, 3, 0)
4185
4186	/** Converts a pointer to the PDMDEVINS::IBase to a pointer to PDMDEVINS. */
4187	#define PDMIBASE_2_PDMDEV(pInterface) ( (PPDMDEVINS)((char *)(pInterface) - RT_OFFSETOF(PDMDEVINS, IBase)) )
4188
4189	/**
4190	* Checks the structure versions of the device instance and device helpers,
4191	* returning if they are incompatible.
4192	*
4193	* This is for use in the constructor.
4194	*
4195	* @param pDevIns The device instance pointer.
4196	*/
4197	#define PDMDEV_CHECK_VERSIONS_RETURN(pDevIns) \
4198	do \
4199	{ \
4200	PPDMDEVINS pDevInsTypeCheck = (pDevIns); NOREF(pDevInsTypeCheck); \
4201	AssertLogRelMsgReturn(PDM_VERSION_ARE_COMPATIBLE((pDevIns)->u32Version, PDM_DEVINS_VERSION), \
4202	("DevIns=%#x mine=%#x\n", (pDevIns)->u32Version, PDM_DEVINS_VERSION), \
4203	VERR_PDM_DEVINS_VERSION_MISMATCH); \
4204	AssertLogRelMsgReturn(PDM_VERSION_ARE_COMPATIBLE((pDevIns)->pHlpR3->u32Version, PDM_DEVHLPR3_VERSION), \
4205	("DevHlp=%#x mine=%#x\n", (pDevIns)->pHlpR3->u32Version, PDM_DEVHLPR3_VERSION), \
4206	VERR_PDM_DEVHLPR3_VERSION_MISMATCH); \
4207	} while (0)
4208
4209	/**
4210	* Quietly checks the structure versions of the device instance and device
4211	* helpers, returning if they are incompatible.
4212	*
4213	* This is for use in the destructor.
4214	*
4215	* @param pDevIns The device instance pointer.
4216	*/
4217	#define PDMDEV_CHECK_VERSIONS_RETURN_QUIET(pDevIns) \
4218	do \
4219	{ \
4220	PPDMDEVINS pDevInsTypeCheck = (pDevIns); NOREF(pDevInsTypeCheck); \
4221	if (RT_UNLIKELY(!PDM_VERSION_ARE_COMPATIBLE((pDevIns)->u32Version, PDM_DEVINS_VERSION) )) \
4222	return VERR_PDM_DEVINS_VERSION_MISMATCH; \
4223	if (RT_UNLIKELY(!PDM_VERSION_ARE_COMPATIBLE((pDevIns)->pHlpR3->u32Version, PDM_DEVHLPR3_VERSION) )) \
4224	return VERR_PDM_DEVHLPR3_VERSION_MISMATCH; \
4225	} while (0)
4226
4227	/**
4228	* Wrapper around CFGMR3ValidateConfig for the root config for use in the
4229	* constructor - returns on failure.
4230	*
4231	* This should be invoked after having initialized the instance data
4232	* sufficiently for the correct operation of the destructor. The destructor is
4233	* always called!
4234	*
4235	* @param pDevIns Pointer to the PDM device instance.
4236	* @param pszValidValues Patterns describing the valid value names. See
4237	* RTStrSimplePatternMultiMatch for details on the
4238	* pattern syntax.
4239	* @param pszValidNodes Patterns describing the valid node (key) names.
4240	* Pass empty string if no valid nodes.
4241	*/
4242	#define PDMDEV_VALIDATE_CONFIG_RETURN(pDevIns, pszValidValues, pszValidNodes) \
4243	do \
4244	{ \
4245	int rcValCfg = CFGMR3ValidateConfig((pDevIns)->pCfg, "/", pszValidValues, pszValidNodes, \
4246	(pDevIns)->pReg->szName, (pDevIns)->iInstance); \
4247	if (RT_FAILURE(rcValCfg)) \
4248	return rcValCfg; \
4249	} while (0)
4250
4251	/** @def PDMDEV_ASSERT_EMT
4252	* Assert that the current thread is the emulation thread.
4253	*/
4254	#ifdef VBOX_STRICT
4255	# define PDMDEV_ASSERT_EMT(pDevIns) pDevIns->pHlpR3->pfnAssertEMT(pDevIns, __FILE__, __LINE__, __FUNCTION__)
4256	#else
4257	# define PDMDEV_ASSERT_EMT(pDevIns) do { } while (0)
4258	#endif
4259
4260	/** @def PDMDEV_ASSERT_OTHER
4261	* Assert that the current thread is NOT the emulation thread.
4262	*/
4263	#ifdef VBOX_STRICT
4264	# define PDMDEV_ASSERT_OTHER(pDevIns) pDevIns->pHlpR3->pfnAssertOther(pDevIns, __FILE__, __LINE__, __FUNCTION__)
4265	#else
4266	# define PDMDEV_ASSERT_OTHER(pDevIns) do { } while (0)
4267	#endif
4268
4269	/** @def PDMDEV_ASSERT_VMLOCK_OWNER
4270	* Assert that the current thread is owner of the VM lock.
4271	*/
4272	#ifdef VBOX_STRICT
4273	# define PDMDEV_ASSERT_VMLOCK_OWNER(pDevIns) pDevIns->pHlpR3->pfnAssertVMLock(pDevIns, __FILE__, __LINE__, __FUNCTION__)
4274	#else
4275	# define PDMDEV_ASSERT_VMLOCK_OWNER(pDevIns) do { } while (0)
4276	#endif
4277
4278	/** @def PDMDEV_SET_ERROR
4279	* Set the VM error. See PDMDevHlpVMSetError() for printf like message formatting.
4280	*/
4281	#define PDMDEV_SET_ERROR(pDevIns, rc, pszError) \
4282	PDMDevHlpVMSetError(pDevIns, rc, RT_SRC_POS, "%s", pszError)
4283
4284	/** @def PDMDEV_SET_RUNTIME_ERROR
4285	* Set the VM runtime error. See PDMDevHlpVMSetRuntimeError() for printf like message formatting.
4286	*/
4287	#define PDMDEV_SET_RUNTIME_ERROR(pDevIns, fFlags, pszErrorId, pszError) \
4288	PDMDevHlpVMSetRuntimeError(pDevIns, fFlags, pszErrorId, "%s", pszError)
4289
4290	/** @def PDMDEVINS_2_RCPTR
4291	* Converts a PDM Device instance pointer a RC PDM Device instance pointer.
4292	*/
4293	#define PDMDEVINS_2_RCPTR(pDevIns) ( (RCPTRTYPE(PPDMDEVINS))((RTGCUINTPTR)(pDevIns)->pvInstanceDataRC - RT_OFFSETOF(PDMDEVINS, achInstanceData)) )
4294
4295	/** @def PDMDEVINS_2_R3PTR
4296	* Converts a PDM Device instance pointer a R3 PDM Device instance pointer.
4297	*/
4298	#define PDMDEVINS_2_R3PTR(pDevIns) ( (R3PTRTYPE(PPDMDEVINS))((RTHCUINTPTR)(pDevIns)->pvInstanceDataR3 - RT_OFFSETOF(PDMDEVINS, achInstanceData)) )
4299
4300	/** @def PDMDEVINS_2_R0PTR
4301	* Converts a PDM Device instance pointer a R0 PDM Device instance pointer.
4302	*/
4303	#define PDMDEVINS_2_R0PTR(pDevIns) ( (R0PTRTYPE(PPDMDEVINS))((RTR0UINTPTR)(pDevIns)->pvInstanceDataR0 - RT_OFFSETOF(PDMDEVINS, achInstanceData)) )
4304
4305
4306	#ifdef IN_RING3
4307
4308	/**
4309	* @copydoc PDMDEVHLPR3::pfnIOPortRegister
4310	*/
4311	DECLINLINE(int) PDMDevHlpIOPortRegister(PPDMDEVINS pDevIns, RTIOPORT Port, RTIOPORT cPorts, RTHCPTR pvUser,
4312	PFNIOMIOPORTOUT pfnOut, PFNIOMIOPORTIN pfnIn,
4313	PFNIOMIOPORTOUTSTRING pfnOutStr, PFNIOMIOPORTINSTRING pfnInStr, const char *pszDesc)
4314	{
4315	return pDevIns->pHlpR3->pfnIOPortRegister(pDevIns, Port, cPorts, pvUser, pfnOut, pfnIn, pfnOutStr, pfnInStr, pszDesc);
4316	}
4317
4318	/**
4319	* @copydoc PDMDEVHLPR3::pfnIOPortRegisterRC
4320	*/
4321	DECLINLINE(int) PDMDevHlpIOPortRegisterRC(PPDMDEVINS pDevIns, RTIOPORT Port, RTIOPORT cPorts, RTRCPTR pvUser,
4322	const char pszOut, const char pszIn, const char *pszOutStr,
4323	const char pszInStr, const char pszDesc)
4324	{
4325	return pDevIns->pHlpR3->pfnIOPortRegisterRC(pDevIns, Port, cPorts, pvUser, pszOut, pszIn, pszOutStr, pszInStr, pszDesc);
4326	}
4327
4328	/**
4329	* @copydoc PDMDEVHLPR3::pfnIOPortRegisterR0
4330	*/
4331	DECLINLINE(int) PDMDevHlpIOPortRegisterR0(PPDMDEVINS pDevIns, RTIOPORT Port, RTIOPORT cPorts, RTR0PTR pvUser,
4332	const char pszOut, const char pszIn, const char *pszOutStr,
4333	const char pszInStr, const char pszDesc)
4334	{
4335	return pDevIns->pHlpR3->pfnIOPortRegisterR0(pDevIns, Port, cPorts, pvUser, pszOut, pszIn, pszOutStr, pszInStr, pszDesc);
4336	}
4337
4338	/**
4339	* @copydoc PDMDEVHLPR3::pfnIOPortDeregister
4340	*/
4341	DECLINLINE(int) PDMDevHlpIOPortDeregister(PPDMDEVINS pDevIns, RTIOPORT Port, RTIOPORT cPorts)
4342	{
4343	return pDevIns->pHlpR3->pfnIOPortDeregister(pDevIns, Port, cPorts);
4344	}
4345
4346	/**
4347	* Register a Memory Mapped I/O (MMIO) region.
4348	*
4349	* These callbacks are of course for the ring-3 context (R3). Register HC
4350	* handlers before raw-mode context (RC) and ring-0 context (R0) handlers! There
4351	* must be a R3 handler for every RC and R0 handler!
4352	*
4353	* @returns VBox status.
4354	* @param pDevIns The device instance to register the MMIO with.
4355	* @param GCPhysStart First physical address in the range.
4356	* @param cbRange The size of the range (in bytes).
4357	* @param pvUser User argument.
4358	* @param fFlags Flags, IOMMMIO_FLAGS_XXX.
4359	* @param pfnWrite Pointer to function which is gonna handle Write operations.
4360	* @param pfnRead Pointer to function which is gonna handle Read operations.
4361	* @param pszDesc Pointer to description string. This must not be freed.
4362	*/
4363	DECLINLINE(int) PDMDevHlpMMIORegister(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, uint32_t cbRange, RTHCPTR pvUser,
4364	uint32_t fFlags, PFNIOMMMIOWRITE pfnWrite, PFNIOMMMIOREAD pfnRead, const char *pszDesc)
4365	{
4366	return pDevIns->pHlpR3->pfnMMIORegister(pDevIns, GCPhysStart, cbRange, pvUser, pfnWrite, pfnRead, NULL /pfnFill/,
4367	fFlags, pszDesc);
4368	}
4369
4370	/**
4371	* Register a Memory Mapped I/O (MMIO) region for GC.
4372	*
4373	* These callbacks are for the raw-mode context (RC). Register ring-3 context
4374	* (R3) handlers before guest context handlers! There must be a R3 handler for
4375	* every RC handler!
4376	*
4377	* @returns VBox status.
4378	* @param pDevIns The device instance to register the MMIO with.
4379	* @param GCPhysStart First physical address in the range.
4380	* @param cbRange The size of the range (in bytes).
4381	* @param pvUser User argument.
4382	* @param pszWrite Name of the RC function which is gonna handle Write operations.
4383	* @param pszRead Name of the RC function which is gonna handle Read operations.
4384	*/
4385	DECLINLINE(int) PDMDevHlpMMIORegisterRC(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, uint32_t cbRange, RTRCPTR pvUser,
4386	const char pszWrite, const char pszRead)
4387	{
4388	return pDevIns->pHlpR3->pfnMMIORegisterRC(pDevIns, GCPhysStart, cbRange, pvUser, pszWrite, pszRead, NULL /pszFill/);
4389	}
4390
4391	/**
4392	* @copydoc PDMDEVHLPR3::pfnMMIORegisterR0
4393	*/
4394	DECLINLINE(int) PDMDevHlpMMIORegisterR0(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, uint32_t cbRange, RTR0PTR pvUser,
4395	const char pszWrite, const char pszRead)
4396	{
4397	return pDevIns->pHlpR3->pfnMMIORegisterR0(pDevIns, GCPhysStart, cbRange, pvUser, pszWrite, pszRead, NULL /pszFill/);
4398	}
4399
4400	/**
4401	* @copydoc PDMDEVHLPR3::pfnMMIORegister
4402	*/
4403	DECLINLINE(int) PDMDevHlpMMIORegisterEx(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, uint32_t cbRange, RTHCPTR pvUser,
4404	uint32_t fFlags, PFNIOMMMIOWRITE pfnWrite, PFNIOMMMIOREAD pfnRead,
4405	PFNIOMMMIOFILL pfnFill, const char *pszDesc)
4406	{
4407	return pDevIns->pHlpR3->pfnMMIORegister(pDevIns, GCPhysStart, cbRange, pvUser, pfnWrite, pfnRead, pfnFill,
4408	fFlags, pszDesc);
4409	}
4410
4411	/**
4412	* @copydoc PDMDEVHLPR3::pfnMMIORegisterRC
4413	*/
4414	DECLINLINE(int) PDMDevHlpMMIORegisterRCEx(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, uint32_t cbRange, RTRCPTR pvUser,
4415	const char pszWrite, const char pszRead, const char *pszFill)
4416	{
4417	return pDevIns->pHlpR3->pfnMMIORegisterRC(pDevIns, GCPhysStart, cbRange, pvUser, pszWrite, pszRead, pszFill);
4418	}
4419
4420	/**
4421	* @copydoc PDMDEVHLPR3::pfnMMIORegisterR0
4422	*/
4423	DECLINLINE(int) PDMDevHlpMMIORegisterR0Ex(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, uint32_t cbRange, RTR0PTR pvUser,
4424	const char pszWrite, const char pszRead, const char *pszFill)
4425	{
4426	return pDevIns->pHlpR3->pfnMMIORegisterR0(pDevIns, GCPhysStart, cbRange, pvUser, pszWrite, pszRead, pszFill);
4427	}
4428
4429	/**
4430	* @copydoc PDMDEVHLPR3::pfnMMIODeregister
4431	*/
4432	DECLINLINE(int) PDMDevHlpMMIODeregister(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, uint32_t cbRange)
4433	{
4434	return pDevIns->pHlpR3->pfnMMIODeregister(pDevIns, GCPhysStart, cbRange);
4435	}
4436
4437	/**
4438	* @copydoc PDMDEVHLPR3::pfnMMIO2Register
4439	*/
4440	DECLINLINE(int) PDMDevHlpMMIO2Register(PPDMDEVINS pDevIns, uint32_t iRegion, RTGCPHYS cb, uint32_t fFlags, void *ppv, const char pszDesc)
4441	{
4442	return pDevIns->pHlpR3->pfnMMIO2Register(pDevIns, iRegion, cb, fFlags, ppv, pszDesc);
4443	}
4444
4445	/**
4446	* @copydoc PDMDEVHLPR3::pfnMMIO2Deregister
4447	*/
4448	DECLINLINE(int) PDMDevHlpMMIO2Deregister(PPDMDEVINS pDevIns, uint32_t iRegion)
4449	{
4450	return pDevIns->pHlpR3->pfnMMIO2Deregister(pDevIns, iRegion);
4451	}
4452
4453	/**
4454	* @copydoc PDMDEVHLPR3::pfnMMIO2Map
4455	*/
4456	DECLINLINE(int) PDMDevHlpMMIO2Map(PPDMDEVINS pDevIns, uint32_t iRegion, RTGCPHYS GCPhys)
4457	{
4458	return pDevIns->pHlpR3->pfnMMIO2Map(pDevIns, iRegion, GCPhys);
4459	}
4460
4461	/**
4462	* @copydoc PDMDEVHLPR3::pfnMMIO2Unmap
4463	*/
4464	DECLINLINE(int) PDMDevHlpMMIO2Unmap(PPDMDEVINS pDevIns, uint32_t iRegion, RTGCPHYS GCPhys)
4465	{
4466	return pDevIns->pHlpR3->pfnMMIO2Unmap(pDevIns, iRegion, GCPhys);
4467	}
4468
4469	/**
4470	* @copydoc PDMDEVHLPR3::pfnMMHyperMapMMIO2
4471	*/
4472	DECLINLINE(int) PDMDevHlpMMHyperMapMMIO2(PPDMDEVINS pDevIns, uint32_t iRegion, RTGCPHYS off, RTGCPHYS cb,
4473	const char *pszDesc, PRTRCPTR pRCPtr)
4474	{
4475	return pDevIns->pHlpR3->pfnMMHyperMapMMIO2(pDevIns, iRegion, off, cb, pszDesc, pRCPtr);
4476	}
4477
4478	/**
4479	* @copydoc PDMDEVHLPR3::pfnMMIO2MapKernel
4480	*/
4481	DECLINLINE(int) PDMDevHlpMMIO2MapKernel(PPDMDEVINS pDevIns, uint32_t iRegion, RTGCPHYS off, RTGCPHYS cb,
4482	const char *pszDesc, PRTR0PTR pR0Ptr)
4483	{
4484	return pDevIns->pHlpR3->pfnMMIO2MapKernel(pDevIns, iRegion, off, cb, pszDesc, pR0Ptr);
4485	}
4486
4487	/**
4488	* @copydoc PDMDEVHLPR3::pfnROMRegister
4489	*/
4490	DECLINLINE(int) PDMDevHlpROMRegister(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, uint32_t cbRange,
4491	const void pvBinary, uint32_t cbBinary, uint32_t fFlags, const char pszDesc)
4492	{
4493	return pDevIns->pHlpR3->pfnROMRegister(pDevIns, GCPhysStart, cbRange, pvBinary, cbBinary, fFlags, pszDesc);
4494	}
4495
4496	/**
4497	* @copydoc PDMDEVHLPR3::pfnROMProtectShadow
4498	*/
4499	DECLINLINE(int) PDMDevHlpROMProtectShadow(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, uint32_t cbRange, PGMROMPROT enmProt)
4500	{
4501	return pDevIns->pHlpR3->pfnROMProtectShadow(pDevIns, GCPhysStart, cbRange, enmProt);
4502	}
4503
4504	/**
4505	* Register a save state data unit.
4506	*
4507	* @returns VBox status.
4508	* @param pDevIns The device instance.
4509	* @param uVersion Data layout version number.
4510	* @param cbGuess The approximate amount of data in the unit.
4511	* Only for progress indicators.
4512	* @param pfnSaveExec Execute save callback, optional.
4513	* @param pfnLoadExec Execute load callback, optional.
4514	*/
4515	DECLINLINE(int) PDMDevHlpSSMRegister(PPDMDEVINS pDevIns, uint32_t uVersion, size_t cbGuess,
4516	PFNSSMDEVSAVEEXEC pfnSaveExec, PFNSSMDEVLOADEXEC pfnLoadExec)
4517	{
4518	return pDevIns->pHlpR3->pfnSSMRegister(pDevIns, uVersion, cbGuess, NULL /pszBefore/,
4519	NULL /pfnLivePrep/, NULL /pfnLiveExec/, NULL /pfnLiveDone/,
4520	NULL /pfnSavePrep/, pfnSaveExec, NULL /pfnSaveDone/,
4521	NULL /pfnLoadPrep/, pfnLoadExec, NULL /pfnLoadDone/);
4522	}
4523
4524	/**
4525	* Register a save state data unit with a live save callback as well.
4526	*
4527	* @returns VBox status.
4528	* @param pDevIns The device instance.
4529	* @param uVersion Data layout version number.
4530	* @param cbGuess The approximate amount of data in the unit.
4531	* Only for progress indicators.
4532	* @param pfnLiveExec Execute live callback, optional.
4533	* @param pfnSaveExec Execute save callback, optional.
4534	* @param pfnLoadExec Execute load callback, optional.
4535	*/
4536	DECLINLINE(int) PDMDevHlpSSMRegister3(PPDMDEVINS pDevIns, uint32_t uVersion, size_t cbGuess,
4537	FNSSMDEVLIVEEXEC pfnLiveExec, PFNSSMDEVSAVEEXEC pfnSaveExec, PFNSSMDEVLOADEXEC pfnLoadExec)
4538	{
4539	return pDevIns->pHlpR3->pfnSSMRegister(pDevIns, uVersion, cbGuess, NULL /pszBefore/,
4540	NULL /pfnLivePrep/, pfnLiveExec, NULL /pfnLiveDone/,
4541	NULL /pfnSavePrep/, pfnSaveExec, NULL /pfnSaveDone/,
4542	NULL /pfnLoadPrep/, pfnLoadExec, NULL /pfnLoadDone/);
4543	}
4544
4545	/**
4546	* @copydoc PDMDEVHLPR3::pfnSSMRegister
4547	*/
4548	DECLINLINE(int) PDMDevHlpSSMRegisterEx(PPDMDEVINS pDevIns, uint32_t uVersion, size_t cbGuess, const char *pszBefore,
4549	PFNSSMDEVLIVEPREP pfnLivePrep, PFNSSMDEVLIVEEXEC pfnLiveExec, PFNSSMDEVLIVEVOTE pfnLiveVote,
4550	PFNSSMDEVSAVEPREP pfnSavePrep, PFNSSMDEVSAVEEXEC pfnSaveExec, PFNSSMDEVSAVEDONE pfnSaveDone,
4551	PFNSSMDEVLOADPREP pfnLoadPrep, PFNSSMDEVLOADEXEC pfnLoadExec, PFNSSMDEVLOADDONE pfnLoadDone)
4552	{
4553	return pDevIns->pHlpR3->pfnSSMRegister(pDevIns, uVersion, cbGuess, pszBefore,
4554	pfnLivePrep, pfnLiveExec, pfnLiveVote,
4555	pfnSavePrep, pfnSaveExec, pfnSaveDone,
4556	pfnLoadPrep, pfnLoadExec, pfnLoadDone);
4557	}
4558
4559	/**
4560	* @copydoc PDMDEVHLPR3::pfnTMTimerCreate
4561	*/
4562	DECLINLINE(int) PDMDevHlpTMTimerCreate(PPDMDEVINS pDevIns, TMCLOCK enmClock, PFNTMTIMERDEV pfnCallback, void *pvUser, uint32_t fFlags,
4563	const char *pszDesc, PPTMTIMERR3 ppTimer)
4564	{
4565	return pDevIns->pHlpR3->pfnTMTimerCreate(pDevIns, enmClock, pfnCallback, pvUser, fFlags, pszDesc, ppTimer);
4566	}
4567
4568	/**
4569	* @copydoc PDMDEVHLPR3::pfnTMUtcNow
4570	*/
4571	DECLINLINE(PRTTIMESPEC) PDMDevHlpTMUtcNow(PPDMDEVINS pDevIns, PRTTIMESPEC pTime)
4572	{
4573	return pDevIns->pHlpR3->pfnTMUtcNow(pDevIns, pTime);
4574	}
4575
4576	#endif /* IN_RING3 */
4577
4578	/**
4579	* @copydoc PDMDEVHLPR3::pfnPhysRead
4580	*/
4581	DECLINLINE(int) PDMDevHlpPhysRead(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead)
4582	{
4583	return pDevIns->CTX_SUFF(pHlp)->pfnPhysRead(pDevIns, GCPhys, pvBuf, cbRead);
4584	}
4585
4586	/**
4587	* @copydoc PDMDEVHLPR3::pfnPhysWrite
4588	*/
4589	DECLINLINE(int) PDMDevHlpPhysWrite(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite)
4590	{
4591	return pDevIns->CTX_SUFF(pHlp)->pfnPhysWrite(pDevIns, GCPhys, pvBuf, cbWrite);
4592	}
4593
4594	#ifdef IN_RING3
4595
4596	/**
4597	* @copydoc PDMDEVHLPR3::pfnPhysGCPhys2CCPtr
4598	*/
4599	DECLINLINE(int) PDMDevHlpPhysGCPhys2CCPtr(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, uint32_t fFlags, void **ppv, PPGMPAGEMAPLOCK pLock)
4600	{
4601	return pDevIns->CTX_SUFF(pHlp)->pfnPhysGCPhys2CCPtr(pDevIns, GCPhys, fFlags, ppv, pLock);
4602	}
4603
4604	/**
4605	* @copydoc PDMDEVHLPR3::pfnPhysGCPhys2CCPtrReadOnly
4606	*/
4607	DECLINLINE(int) PDMDevHlpPhysGCPhys2CCPtrReadOnly(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, uint32_t fFlags, void const **ppv, PPGMPAGEMAPLOCK pLock)
4608	{
4609	return pDevIns->CTX_SUFF(pHlp)->pfnPhysGCPhys2CCPtrReadOnly(pDevIns, GCPhys, fFlags, ppv, pLock);
4610	}
4611
4612	/**
4613	* @copydoc PDMDEVHLPR3::pfnPhysReleasePageMappingLock
4614	*/
4615	DECLINLINE(void) PDMDevHlpPhysReleasePageMappingLock(PPDMDEVINS pDevIns, PPGMPAGEMAPLOCK pLock)
4616	{
4617	pDevIns->CTX_SUFF(pHlp)->pfnPhysReleasePageMappingLock(pDevIns, pLock);
4618	}
4619
4620	/**
4621	* @copydoc PDMDEVHLPR3::pfnPhysReadGCVirt
4622	*/
4623	DECLINLINE(int) PDMDevHlpPhysReadGCVirt(PPDMDEVINS pDevIns, void *pvDst, RTGCPTR GCVirtSrc, size_t cb)
4624	{
4625	return pDevIns->pHlpR3->pfnPhysReadGCVirt(pDevIns, pvDst, GCVirtSrc, cb);
4626	}
4627
4628	/**
4629	* @copydoc PDMDEVHLPR3::pfnPhysWriteGCVirt
4630	*/
4631	DECLINLINE(int) PDMDevHlpPhysWriteGCVirt(PPDMDEVINS pDevIns, RTGCPTR GCVirtDst, const void *pvSrc, size_t cb)
4632	{
4633	return pDevIns->pHlpR3->pfnPhysWriteGCVirt(pDevIns, GCVirtDst, pvSrc, cb);
4634	}
4635
4636	/**
4637	* @copydoc PDMDEVHLPR3::pfnPhysGCPtr2GCPhys
4638	*/
4639	DECLINLINE(int) PDMDevHlpPhysGCPtr2GCPhys(PPDMDEVINS pDevIns, RTGCPTR GCPtr, PRTGCPHYS pGCPhys)
4640	{
4641	return pDevIns->pHlpR3->pfnPhysGCPtr2GCPhys(pDevIns, GCPtr, pGCPhys);
4642	}
4643
4644	/**
4645	* @copydoc PDMDEVHLPR3::pfnMMHeapAlloc
4646	*/
4647	DECLINLINE(void *) PDMDevHlpMMHeapAlloc(PPDMDEVINS pDevIns, size_t cb)
4648	{
4649	return pDevIns->pHlpR3->pfnMMHeapAlloc(pDevIns, cb);
4650	}
4651
4652	/**
4653	* @copydoc PDMDEVHLPR3::pfnMMHeapAllocZ
4654	*/
4655	DECLINLINE(void *) PDMDevHlpMMHeapAllocZ(PPDMDEVINS pDevIns, size_t cb)
4656	{
4657	return pDevIns->pHlpR3->pfnMMHeapAllocZ(pDevIns, cb);
4658	}
4659
4660	/**
4661	* @copydoc PDMDEVHLPR3::pfnMMHeapFree
4662	*/
4663	DECLINLINE(void) PDMDevHlpMMHeapFree(PPDMDEVINS pDevIns, void *pv)
4664	{
4665	pDevIns->pHlpR3->pfnMMHeapFree(pDevIns, pv);
4666	}
4667	#endif /* IN_RING3 */
4668
4669	/**
4670	* @copydoc PDMDEVHLPR3::pfnVMState
4671	*/
4672	DECLINLINE(VMSTATE) PDMDevHlpVMState(PPDMDEVINS pDevIns)
4673	{
4674	return pDevIns->CTX_SUFF(pHlp)->pfnVMState(pDevIns);
4675	}
4676
4677	#ifdef IN_RING3
4678	/**
4679	* @copydoc PDMDEVHLPR3::pfnVMTeleportedAndNotFullyResumedYet
4680	*/
4681	DECLINLINE(bool) PDMDevHlpVMTeleportedAndNotFullyResumedYet(PPDMDEVINS pDevIns)
4682	{
4683	return pDevIns->pHlpR3->pfnVMTeleportedAndNotFullyResumedYet(pDevIns);
4684	}
4685	#endif /* IN_RING3 */
4686
4687	/**
4688	* @copydoc PDMDEVHLPR3::pfnVMSetError
4689	*/
4690	DECLINLINE(int) PDMDevHlpVMSetError(PPDMDEVINS pDevIns, const int rc, RT_SRC_POS_DECL, const char *pszFormat, ...)
4691	{
4692	va_list va;
4693	va_start(va, pszFormat);
4694	pDevIns->CTX_SUFF(pHlp)->pfnVMSetErrorV(pDevIns, rc, RT_SRC_POS_ARGS, pszFormat, va);
4695	va_end(va);
4696	return rc;
4697	}
4698
4699	/**
4700	* @copydoc PDMDEVHLPR3::pfnVMSetRuntimeError
4701	*/
4702	DECLINLINE(int) PDMDevHlpVMSetRuntimeError(PPDMDEVINS pDevIns, uint32_t fFlags, const char pszErrorId, const char pszFormat, ...)
4703	{
4704	va_list va;
4705	int rc;
4706	va_start(va, pszFormat);
4707	rc = pDevIns->CTX_SUFF(pHlp)->pfnVMSetRuntimeErrorV(pDevIns, fFlags, pszErrorId, pszFormat, va);
4708	va_end(va);
4709	return rc;
4710	}
4711
4712	/**
4713	* VBOX_STRICT wrapper for pHlp->pfnDBGFStopV.
4714	*
4715	* @returns VBox status code which must be passed up to the VMM. This will be
4716	* VINF_SUCCESS in non-strict builds.
4717	* @param pDevIns The device instance.
4718	* @param RT_SRC_POS_DECL Use RT_SRC_POS.
4719	* @param pszFormat Message. (optional)
4720	* @param ... Message parameters.
4721	*/
4722	DECLINLINE(int) PDMDevHlpDBGFStop(PPDMDEVINS pDevIns, RT_SRC_POS_DECL, const char *pszFormat, ...)
4723	{
4724	#ifdef VBOX_STRICT
4725	# ifdef IN_RING3
4726	int rc;
4727	va_list args;
4728	va_start(args, pszFormat);
4729	rc = pDevIns->pHlpR3->pfnDBGFStopV(pDevIns, RT_SRC_POS_ARGS, pszFormat, args);
4730	va_end(args);
4731	return rc;
4732	# else
4733	NOREF(pDevIns);
4734	NOREF(pszFile);
4735	NOREF(iLine);
4736	NOREF(pszFunction);
4737	NOREF(pszFormat);
4738	return VINF_EM_DBG_STOP;
4739	# endif
4740	#else
4741	NOREF(pDevIns);
4742	NOREF(pszFile);
4743	NOREF(iLine);
4744	NOREF(pszFunction);
4745	NOREF(pszFormat);
4746	return VINF_SUCCESS;
4747	#endif
4748	}
4749
4750	#ifdef IN_RING3
4751
4752	/**
4753	* @copydoc PDMDEVHLPR3::pfnDBGFInfoRegister
4754	*/
4755	DECLINLINE(int) PDMDevHlpDBGFInfoRegister(PPDMDEVINS pDevIns, const char pszName, const char pszDesc, PFNDBGFHANDLERDEV pfnHandler)
4756	{
4757	return pDevIns->pHlpR3->pfnDBGFInfoRegister(pDevIns, pszName, pszDesc, pfnHandler);
4758	}
4759
4760	/**
4761	* @copydoc PDMDEVHLPR3::pfnDBGFRegRegister
4762	*/
4763	DECLINLINE(int) PDMDevHlpDBGFRegRegister(PPDMDEVINS pDevIns, PCDBGFREGDESC paRegisters)
4764	{
4765	return pDevIns->pHlpR3->pfnDBGFRegRegister(pDevIns, paRegisters);
4766	}
4767
4768	/**
4769	* @copydoc PDMDEVHLPR3::pfnSTAMRegister
4770	*/
4771	DECLINLINE(void) PDMDevHlpSTAMRegister(PPDMDEVINS pDevIns, void pvSample, STAMTYPE enmType, const char pszName, STAMUNIT enmUnit, const char *pszDesc)
4772	{
4773	pDevIns->pHlpR3->pfnSTAMRegister(pDevIns, pvSample, enmType, pszName, enmUnit, pszDesc);
4774	}
4775
4776	/**
4777	* @copydoc PDMDEVHLPR3::pfnSTAMRegisterF
4778	*/
4779	DECLINLINE(void) PDMDevHlpSTAMRegisterF(PPDMDEVINS pDevIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility, STAMUNIT enmUnit,
4780	const char pszDesc, const char pszName, ...)
4781	{
4782	va_list va;
4783	va_start(va, pszName);
4784	pDevIns->pHlpR3->pfnSTAMRegisterV(pDevIns, pvSample, enmType, enmVisibility, enmUnit, pszDesc, pszName, va);
4785	va_end(va);
4786	}
4787
4788	/**
4789	* @copydoc PDMDEVHLPR3::pfnPCIRegister
4790	*/
4791	DECLINLINE(int) PDMDevHlpPCIRegister(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev)
4792	{
4793	return pDevIns->pHlpR3->pfnPCIRegister(pDevIns, pPciDev);
4794	}
4795
4796	/**
4797	* @copydoc PDMDEVHLPR3::pfnPCIIORegionRegister
4798	*/
4799	DECLINLINE(int) PDMDevHlpPCIIORegionRegister(PPDMDEVINS pDevIns, int iRegion, uint32_t cbRegion, PCIADDRESSSPACE enmType, PFNPCIIOREGIONMAP pfnCallback)
4800	{
4801	return pDevIns->pHlpR3->pfnPCIIORegionRegister(pDevIns, iRegion, cbRegion, enmType, pfnCallback);
4802	}
4803
4804	/**
4805	* @copydoc PDMDEVHLPR3::pfnPCIRegisterMsi
4806	*/
4807	DECLINLINE(int) PDMDevHlpPCIRegisterMsi(PPDMDEVINS pDevIns, PPDMMSIREG pMsiReg)
4808	{
4809	return pDevIns->pHlpR3->pfnPCIRegisterMsi(pDevIns, pMsiReg);
4810	}
4811
4812	/**
4813	* @copydoc PDMDEVHLPR3::pfnPCISetConfigCallbacks
4814	*/
4815	DECLINLINE(void) PDMDevHlpPCISetConfigCallbacks(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, PFNPCICONFIGREAD pfnRead, PPFNPCICONFIGREAD ppfnReadOld,
4816	PFNPCICONFIGWRITE pfnWrite, PPFNPCICONFIGWRITE ppfnWriteOld)
4817	{
4818	pDevIns->pHlpR3->pfnPCISetConfigCallbacks(pDevIns, pPciDev, pfnRead, ppfnReadOld, pfnWrite, ppfnWriteOld);
4819	}
4820
4821	#endif /* IN_RING3 */
4822
4823	/**
4824	* @copydoc PDMDEVHLPR3::pfnPCIPhysRead
4825	*/
4826	DECLINLINE(int) PDMDevHlpPCIPhysRead(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead)
4827	{
4828	return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysRead(pDevIns, GCPhys, pvBuf, cbRead);
4829	}
4830
4831	/**
4832	* @copydoc PDMDEVHLPR3::pfnPCIPhysWrite
4833	*/
4834	DECLINLINE(int) PDMDevHlpPCIPhysWrite(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite)
4835	{
4836	return pDevIns->CTX_SUFF(pHlp)->pfnPCIPhysWrite(pDevIns, GCPhys, pvBuf, cbWrite);
4837	}
4838
4839	/**
4840	* @copydoc PDMDEVHLPR3::pfnPCISetIrq
4841	*/
4842	DECLINLINE(void) PDMDevHlpPCISetIrq(PPDMDEVINS pDevIns, int iIrq, int iLevel)
4843	{
4844	pDevIns->CTX_SUFF(pHlp)->pfnPCISetIrq(pDevIns, iIrq, iLevel);
4845	}
4846
4847	/**
4848	* @copydoc PDMDEVHLPR3::pfnPCISetIrqNoWait
4849	*/
4850	DECLINLINE(void) PDMDevHlpPCISetIrqNoWait(PPDMDEVINS pDevIns, int iIrq, int iLevel)
4851	{
4852	pDevIns->CTX_SUFF(pHlp)->pfnPCISetIrq(pDevIns, iIrq, iLevel);
4853	}
4854
4855	/**
4856	* @copydoc PDMDEVHLPR3::pfnISASetIrq
4857	*/
4858	DECLINLINE(void) PDMDevHlpISASetIrq(PPDMDEVINS pDevIns, int iIrq, int iLevel)
4859	{
4860	pDevIns->CTX_SUFF(pHlp)->pfnISASetIrq(pDevIns, iIrq, iLevel);
4861	}
4862
4863	/**
4864	* @copydoc PDMDEVHLPR3::pfnISASetIrqNoWait
4865	*/
4866	DECLINLINE(void) PDMDevHlpISASetIrqNoWait(PPDMDEVINS pDevIns, int iIrq, int iLevel)
4867	{
4868	pDevIns->CTX_SUFF(pHlp)->pfnISASetIrq(pDevIns, iIrq, iLevel);
4869	}
4870
4871	#ifdef IN_RING3
4872
4873	/**
4874	* @copydoc PDMDEVHLPR3::pfnDriverAttach
4875	*/
4876	DECLINLINE(int) PDMDevHlpDriverAttach(PPDMDEVINS pDevIns, uint32_t iLun, PPDMIBASE pBaseInterface, PPDMIBASE ppBaseInterface, const char pszDesc)
4877	{
4878	return pDevIns->pHlpR3->pfnDriverAttach(pDevIns, iLun, pBaseInterface, ppBaseInterface, pszDesc);
4879	}
4880
4881	/**
4882	* @copydoc PDMDEVHLPR3::pfnQueueCreate
4883	*/
4884	DECLINLINE(int) PDMDevHlpQueueCreate(PPDMDEVINS pDevIns, size_t cbItem, uint32_t cItems, uint32_t cMilliesInterval,
4885	PFNPDMQUEUEDEV pfnCallback, bool fRZEnabled, const char pszName, PPDMQUEUE ppQueue)
4886	{
4887	return pDevIns->pHlpR3->pfnQueueCreate(pDevIns, cbItem, cItems, cMilliesInterval, pfnCallback, fRZEnabled, pszName, ppQueue);
4888	}
4889
4890	/**
4891	* Initializes a PDM critical section.
4892	*
4893	* The PDM critical sections are derived from the IPRT critical sections, but
4894	* works in RC and R0 as well.
4895	*
4896	* @returns VBox status code.
4897	* @param pDevIns The device instance.
4898	* @param pCritSect Pointer to the critical section.
4899	* @param RT_SRC_POS_DECL Use RT_SRC_POS.
4900	* @param pszNameFmt Format string for naming the critical section.
4901	* For statistics and lock validation.
4902	* @param ... Arguments for the format string.
4903	*/
4904	DECLINLINE(int) PDMDevHlpCritSectInit(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, RT_SRC_POS_DECL, const char *pszNameFmt, ...)
4905	{
4906	int rc;
4907	va_list va;
4908	va_start(va, pszNameFmt);
4909	rc = pDevIns->pHlpR3->pfnCritSectInit(pDevIns, pCritSect, RT_SRC_POS_ARGS, pszNameFmt, va);
4910	va_end(va);
4911	return rc;
4912	}
4913
4914	/**
4915	* @copydoc PDMDEVHLPR3::pfnCritSectGetNop
4916	*/
4917	DECLINLINE(PPDMCRITSECT) PDMDevHlpCritSectGetNop(PPDMDEVINS pDevIns)
4918	{
4919	return pDevIns->pHlpR3->pfnCritSectGetNop(pDevIns);
4920	}
4921
4922	/**
4923	* @copydoc PDMDEVHLPR3::pfnCritSectGetNopR0
4924	*/
4925	DECLINLINE(R0PTRTYPE(PPDMCRITSECT)) PDMDevHlpCritSectGetNopR0(PPDMDEVINS pDevIns)
4926	{
4927	return pDevIns->pHlpR3->pfnCritSectGetNopR0(pDevIns);
4928	}
4929
4930	/**
4931	* @copydoc PDMDEVHLPR3::pfnCritSectGetNopRC
4932	*/
4933	DECLINLINE(RCPTRTYPE(PPDMCRITSECT)) PDMDevHlpCritSectGetNopRC(PPDMDEVINS pDevIns)
4934	{
4935	return pDevIns->pHlpR3->pfnCritSectGetNopRC(pDevIns);
4936	}
4937
4938	/**
4939	* @copydoc PDMDEVHLPR3::pfnSetDeviceCritSect
4940	*/
4941	DECLINLINE(int) PDMDevHlpSetDeviceCritSect(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect)
4942	{
4943	return pDevIns->pHlpR3->pfnSetDeviceCritSect(pDevIns, pCritSect);
4944	}
4945
4946	/**
4947	* @copydoc PDMDEVHLPR3::pfnThreadCreate
4948	*/
4949	DECLINLINE(int) PDMDevHlpThreadCreate(PPDMDEVINS pDevIns, PPPDMTHREAD ppThread, void *pvUser, PFNPDMTHREADDEV pfnThread,
4950	PFNPDMTHREADWAKEUPDEV pfnWakeup, size_t cbStack, RTTHREADTYPE enmType, const char *pszName)
4951	{
4952	return pDevIns->pHlpR3->pfnThreadCreate(pDevIns, ppThread, pvUser, pfnThread, pfnWakeup, cbStack, enmType, pszName);
4953	}
4954
4955	/**
4956	* @copydoc PDMDEVHLPR3::pfnSetAsyncNotification
4957	*/
4958	DECLINLINE(int) PDMDevHlpSetAsyncNotification(PPDMDEVINS pDevIns, PFNPDMDEVASYNCNOTIFY pfnAsyncNotify)
4959	{
4960	return pDevIns->pHlpR3->pfnSetAsyncNotification(pDevIns, pfnAsyncNotify);
4961	}
4962
4963	/**
4964	* @copydoc PDMDEVHLPR3::pfnAsyncNotificationCompleted
4965	*/
4966	DECLINLINE(void) PDMDevHlpAsyncNotificationCompleted(PPDMDEVINS pDevIns)
4967	{
4968	pDevIns->pHlpR3->pfnAsyncNotificationCompleted(pDevIns);
4969	}
4970
4971	/**
4972	* @copydoc PDMDEVHLPR3::pfnA20Set
4973	*/
4974	DECLINLINE(void) PDMDevHlpA20Set(PPDMDEVINS pDevIns, bool fEnable)
4975	{
4976	pDevIns->pHlpR3->pfnA20Set(pDevIns, fEnable);
4977	}
4978
4979	/**
4980	* @copydoc PDMDEVHLPR3::pfnRTCRegister
4981	*/
4982	DECLINLINE(int) PDMDevHlpRTCRegister(PPDMDEVINS pDevIns, PCPDMRTCREG pRtcReg, PCPDMRTCHLP *ppRtcHlp)
4983	{
4984	return pDevIns->pHlpR3->pfnRTCRegister(pDevIns, pRtcReg, ppRtcHlp);
4985	}
4986
4987	/**
4988	* @copydoc PDMDEVHLPR3::pfnPCIBusRegister
4989	*/
4990	DECLINLINE(int) PDMDevHlpPCIBusRegister(PPDMDEVINS pDevIns, PPDMPCIBUSREG pPciBusReg, PCPDMPCIHLPR3 *ppPciHlpR3)
4991	{
4992	return pDevIns->pHlpR3->pfnPCIBusRegister(pDevIns, pPciBusReg, ppPciHlpR3);
4993	}
4994
4995	/**
4996	* @copydoc PDMDEVHLPR3::pfnPICRegister
4997	*/
4998	DECLINLINE(int) PDMDevHlpPICRegister(PPDMDEVINS pDevIns, PPDMPICREG pPicReg, PCPDMPICHLPR3 *ppPicHlpR3)
4999	{
5000	return pDevIns->pHlpR3->pfnPICRegister(pDevIns, pPicReg, ppPicHlpR3);
5001	}
5002
5003	/**
5004	* @copydoc PDMDEVHLPR3::pfnAPICRegister
5005	*/
5006	DECLINLINE(int) PDMDevHlpAPICRegister(PPDMDEVINS pDevIns, PPDMAPICREG pApicReg, PCPDMAPICHLPR3 *ppApicHlpR3)
5007	{
5008	return pDevIns->pHlpR3->pfnAPICRegister(pDevIns, pApicReg, ppApicHlpR3);
5009	}
5010
5011	/**
5012	* @copydoc PDMDEVHLPR3::pfn
5013	*/
5014	DECLINLINE(int) PDMDevHlpIOAPICRegister(PPDMDEVINS pDevIns, PPDMIOAPICREG pIoApicReg, PCPDMIOAPICHLPR3 *ppIoApicHlpR3)
5015	{
5016	return pDevIns->pHlpR3->pfnIOAPICRegister(pDevIns, pIoApicReg, ppIoApicHlpR3);
5017	}
5018
5019	/**
5020	* @copydoc PDMDEVHLPR3::pfnHPETRegister
5021	*/
5022	DECLINLINE(int) PDMDevHlpHPETRegister(PPDMDEVINS pDevIns, PPDMHPETREG pHpetReg, PCPDMHPETHLPR3 *ppHpetHlpR3)
5023	{
5024	return pDevIns->pHlpR3->pfnHPETRegister(pDevIns, pHpetReg, ppHpetHlpR3);
5025	}
5026
5027	/**
5028	* @copydoc PDMDEVHLPR3::pfnPciRawRegister
5029	*/
5030	DECLINLINE(int) PDMDevHlpPciRawRegister(PPDMDEVINS pDevIns, PPDMPCIRAWREG pPciRawReg, PCPDMPCIRAWHLPR3 *ppPciRawHlpR3)
5031	{
5032	return pDevIns->pHlpR3->pfnPciRawRegister(pDevIns, pPciRawReg, ppPciRawHlpR3);
5033	}
5034
5035	/**
5036	* @copydoc PDMDEVHLPR3::pfnDMACRegister
5037	*/
5038	DECLINLINE(int) PDMDevHlpDMACRegister(PPDMDEVINS pDevIns, PPDMDMACREG pDmacReg, PCPDMDMACHLP *ppDmacHlp)
5039	{
5040	return pDevIns->pHlpR3->pfnDMACRegister(pDevIns, pDmacReg, ppDmacHlp);
5041	}
5042
5043	/**
5044	* @copydoc PDMDEVHLPR3::pfnDMARegister
5045	*/
5046	DECLINLINE(int) PDMDevHlpDMARegister(PPDMDEVINS pDevIns, unsigned uChannel, PFNDMATRANSFERHANDLER pfnTransferHandler, void *pvUser)
5047	{
5048	return pDevIns->pHlpR3->pfnDMARegister(pDevIns, uChannel, pfnTransferHandler, pvUser);
5049	}
5050
5051	/**
5052	* @copydoc PDMDEVHLPR3::pfnDMAReadMemory
5053	*/
5054	DECLINLINE(int) PDMDevHlpDMAReadMemory(PPDMDEVINS pDevIns, unsigned uChannel, void pvBuffer, uint32_t off, uint32_t cbBlock, uint32_t pcbRead)
5055	{
5056	return pDevIns->pHlpR3->pfnDMAReadMemory(pDevIns, uChannel, pvBuffer, off, cbBlock, pcbRead);
5057	}
5058
5059	/**
5060	* @copydoc PDMDEVHLPR3::pfnDMAWriteMemory
5061	*/
5062	DECLINLINE(int) PDMDevHlpDMAWriteMemory(PPDMDEVINS pDevIns, unsigned uChannel, const void pvBuffer, uint32_t off, uint32_t cbBlock, uint32_t pcbWritten)
5063	{
5064	return pDevIns->pHlpR3->pfnDMAWriteMemory(pDevIns, uChannel, pvBuffer, off, cbBlock, pcbWritten);
5065	}
5066
5067	/**
5068	* @copydoc PDMDEVHLPR3::pfnDMASetDREQ
5069	*/
5070	DECLINLINE(int) PDMDevHlpDMASetDREQ(PPDMDEVINS pDevIns, unsigned uChannel, unsigned uLevel)
5071	{
5072	return pDevIns->pHlpR3->pfnDMASetDREQ(pDevIns, uChannel, uLevel);
5073	}
5074
5075	/**
5076	* @copydoc PDMDEVHLPR3::pfnDMAGetChannelMode
5077	*/
5078	DECLINLINE(uint8_t) PDMDevHlpDMAGetChannelMode(PPDMDEVINS pDevIns, unsigned uChannel)
5079	{
5080	return pDevIns->pHlpR3->pfnDMAGetChannelMode(pDevIns, uChannel);
5081	}
5082
5083	/**
5084	* @copydoc PDMDEVHLPR3::pfnDMASchedule
5085	*/
5086	DECLINLINE(void) PDMDevHlpDMASchedule(PPDMDEVINS pDevIns)
5087	{
5088	pDevIns->pHlpR3->pfnDMASchedule(pDevIns);
5089	}
5090
5091	/**
5092	* @copydoc PDMDEVHLPR3::pfnCMOSWrite
5093	*/
5094	DECLINLINE(int) PDMDevHlpCMOSWrite(PPDMDEVINS pDevIns, unsigned iReg, uint8_t u8Value)
5095	{
5096	return pDevIns->pHlpR3->pfnCMOSWrite(pDevIns, iReg, u8Value);
5097	}
5098
5099	/**
5100	* @copydoc PDMDEVHLPR3::pfnCMOSRead
5101	*/
5102	DECLINLINE(int) PDMDevHlpCMOSRead(PPDMDEVINS pDevIns, unsigned iReg, uint8_t *pu8Value)
5103	{
5104	return pDevIns->pHlpR3->pfnCMOSRead(pDevIns, iReg, pu8Value);
5105	}
5106
5107	/**
5108	* @copydoc PDMDEVHLP::pfnCallR0
5109	*/
5110	DECLINLINE(int) PDMDevHlpCallR0(PPDMDEVINS pDevIns, uint32_t uOperation, uint64_t u64Arg)
5111	{
5112	return pDevIns->pHlpR3->pfnCallR0(pDevIns, uOperation, u64Arg);
5113	}
5114
5115	/**
5116	* @copydoc PDMDEVHLP::pfnVMGetSuspendReason
5117	*/
5118	DECLINLINE(VMSUSPENDREASON) PDMDevHlpVMGetSuspendReason(PPDMDEVINS pDevIns)
5119	{
5120	return pDevIns->pHlpR3->pfnVMGetSuspendReason(pDevIns);
5121	}
5122
5123	/**
5124	* @copydoc PDMDEVHLP::pfnVMGetResumeReason
5125	*/
5126	DECLINLINE(VMRESUMEREASON) PDMDevHlpVMGetResumeReason(PPDMDEVINS pDevIns)
5127	{
5128	return pDevIns->pHlpR3->pfnVMGetResumeReason(pDevIns);
5129	}
5130
5131	/**
5132	* @copydoc PDMDEVHLPR3::pfnGetUVM
5133	*/
5134	DECLINLINE(PUVM) PDMDevHlpGetUVM(PPDMDEVINS pDevIns)
5135	{
5136	return pDevIns->CTX_SUFF(pHlp)->pfnGetUVM(pDevIns);
5137	}
5138
5139	#endif /* IN_RING3 */
5140
5141	/**
5142	* @copydoc PDMDEVHLPR3::pfnGetVM
5143	*/
5144	DECLINLINE(PVM) PDMDevHlpGetVM(PPDMDEVINS pDevIns)
5145	{
5146	return pDevIns->CTX_SUFF(pHlp)->pfnGetVM(pDevIns);
5147	}
5148
5149	/**
5150	* @copydoc PDMDEVHLPR3::pfnGetVMCPU
5151	*/
5152	DECLINLINE(PVMCPU) PDMDevHlpGetVMCPU(PPDMDEVINS pDevIns)
5153	{
5154	return pDevIns->CTX_SUFF(pHlp)->pfnGetVMCPU(pDevIns);
5155	}
5156
5157	/**
5158	* @copydoc PDMDEVHLPR3::pfnTMTimeVirtGet
5159	*/
5160	DECLINLINE(uint64_t) PDMDevHlpTMTimeVirtGet(PPDMDEVINS pDevIns)
5161	{
5162	return pDevIns->CTX_SUFF(pHlp)->pfnTMTimeVirtGet(pDevIns);
5163	}
5164
5165	/**
5166	* @copydoc PDMDEVHLPR3::pfnTMTimeVirtGetFreq
5167	*/
5168	DECLINLINE(uint64_t) PDMDevHlpTMTimeVirtGetFreq(PPDMDEVINS pDevIns)
5169	{
5170	return pDevIns->CTX_SUFF(pHlp)->pfnTMTimeVirtGetFreq(pDevIns);
5171	}
5172
5173	/**
5174	* @copydoc PDMDEVHLPR3::pfnTMTimeVirtGetFreq
5175	*/
5176	DECLINLINE(uint64_t) PDMDevHlpTMTimeVirtGetNano(PPDMDEVINS pDevIns)
5177	{
5178	return pDevIns->CTX_SUFF(pHlp)->pfnTMTimeVirtGetNano(pDevIns);
5179	}
5180
5181	#ifdef IN_RING3
5182
5183	/**
5184	* @copydoc PDMDEVHLPR3::pfnRegisterVMMDevHeap
5185	*/
5186	DECLINLINE(int) PDMDevHlpRegisterVMMDevHeap(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTR3PTR pvHeap, unsigned cbSize)
5187	{
5188	return pDevIns->pHlpR3->pfnRegisterVMMDevHeap(pDevIns, GCPhys, pvHeap, cbSize);
5189	}
5190
5191	/**
5192	* @copydoc PDMDEVHLPR3::pfnUnregisterVMMDevHeap
5193	*/
5194	DECLINLINE(int) PDMDevHlpUnregisterVMMDevHeap(PPDMDEVINS pDevIns, RTGCPHYS GCPhys)
5195	{
5196	return pDevIns->pHlpR3->pfnUnregisterVMMDevHeap(pDevIns, GCPhys);
5197	}
5198
5199	/**
5200	* @copydoc PDMDEVHLPR3::pfnVMReset
5201	*/
5202	DECLINLINE(int) PDMDevHlpVMReset(PPDMDEVINS pDevIns)
5203	{
5204	return pDevIns->pHlpR3->pfnVMReset(pDevIns);
5205	}
5206
5207	/**
5208	* @copydoc PDMDEVHLPR3::pfnVMSuspend
5209	*/
5210	DECLINLINE(int) PDMDevHlpVMSuspend(PPDMDEVINS pDevIns)
5211	{
5212	return pDevIns->pHlpR3->pfnVMSuspend(pDevIns);
5213	}
5214
5215	/**
5216	* @copydoc PDMDEVHLPR3::pfnVMSuspendSaveAndPowerOff
5217	*/
5218	DECLINLINE(int) PDMDevHlpVMSuspendSaveAndPowerOff(PPDMDEVINS pDevIns)
5219	{
5220	return pDevIns->pHlpR3->pfnVMSuspendSaveAndPowerOff(pDevIns);
5221	}
5222
5223	/**
5224	* @copydoc PDMDEVHLPR3::pfnVMPowerOff
5225	*/
5226	DECLINLINE(int) PDMDevHlpVMPowerOff(PPDMDEVINS pDevIns)
5227	{
5228	return pDevIns->pHlpR3->pfnVMPowerOff(pDevIns);
5229	}
5230
5231	#endif /* IN_RING3 */
5232
5233	/**
5234	* @copydoc PDMDEVHLPR3::pfnA20IsEnabled
5235	*/
5236	DECLINLINE(bool) PDMDevHlpA20IsEnabled(PPDMDEVINS pDevIns)
5237	{
5238	return pDevIns->CTX_SUFF(pHlp)->pfnA20IsEnabled(pDevIns);
5239	}
5240
5241	#ifdef IN_RING3
5242
5243	/**
5244	* @copydoc PDMDEVHLPR3::pfnGetCpuId
5245	*/
5246	DECLINLINE(void) PDMDevHlpGetCpuId(PPDMDEVINS pDevIns, uint32_t iLeaf, uint32_t pEax, uint32_t pEbx, uint32_t pEcx, uint32_t pEdx)
5247	{
5248	pDevIns->pHlpR3->pfnGetCpuId(pDevIns, iLeaf, pEax, pEbx, pEcx, pEdx);
5249	}
5250
5251	/**
5252	* @copydoc PDMDEVHLPR3::pfnGetSupDrvSession
5253	*/
5254	DECLINLINE(PSUPDRVSESSION) PDMDevHlpGetSupDrvSession(PPDMDEVINS pDevIns)
5255	{
5256	return pDevIns->pHlpR3->pfnGetSupDrvSession(pDevIns);
5257	}
5258
5259	#endif /* IN_RING3 */
5260	#ifdef IN_RING0
5261
5262	/**
5263	* @copydoc PDMDEVHLPR0::pfnCanEmulateIoBlock
5264	*/
5265	DECLINLINE(bool) PDMDevHlpCanEmulateIoBlock(PPDMDEVINS pDevIns)
5266	{
5267	return pDevIns->CTX_SUFF(pHlp)->pfnCanEmulateIoBlock(pDevIns);
5268	}
5269
5270	#endif /* IN_RING0 */
5271
5272
5273
5274
5275	/** Pointer to callbacks provided to the VBoxDeviceRegister() call. */
5276	typedef struct PDMDEVREGCB *PPDMDEVREGCB;
5277
5278	/**
5279	* Callbacks for VBoxDeviceRegister().
5280	*/
5281	typedef struct PDMDEVREGCB
5282	{
5283	/** Interface version.
5284	* This is set to PDM_DEVREG_CB_VERSION. */
5285	uint32_t u32Version;
5286
5287	/**
5288	* Registers a device with the current VM instance.
5289	*
5290	* @returns VBox status code.
5291	* @param pCallbacks Pointer to the callback table.
5292	* @param pReg Pointer to the device registration record.
5293	* This data must be permanent and readonly.
5294	*/
5295	DECLR3CALLBACKMEMBER(int, pfnRegister,(PPDMDEVREGCB pCallbacks, PCPDMDEVREG pReg));
5296	} PDMDEVREGCB;
5297
5298	/** Current version of the PDMDEVREGCB structure. */
5299	#define PDM_DEVREG_CB_VERSION PDM_VERSION_MAKE(0xffe3, 1, 0)
5300
5301
5302	/**
5303	* The VBoxDevicesRegister callback function.
5304	*
5305	* PDM will invoke this function after loading a device module and letting
5306	* the module decide which devices to register and how to handle conflicts.
5307	*
5308	* @returns VBox status code.
5309	* @param pCallbacks Pointer to the callback table.
5310	* @param u32Version VBox version number.
5311	*/
5312	typedef DECLCALLBACK(int) FNPDMVBOXDEVICESREGISTER(PPDMDEVREGCB pCallbacks, uint32_t u32Version);
5313
5314	/** @} */
5315
5316	RT_C_DECLS_END
5317
5318	#endif

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

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

Download in other formats: