pdm.h@ 554

Last change on this file since 554 was 528, checked in by vboxsync, 18 years ago
forgot to commit one alignment fix.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 238.0 KB

Line
1	/** @file
2	* PDM - Pluggable Device Manager.
3	*/
4
5	/*
6	* Copyright (C) 2006 InnoTek Systemberatung GmbH
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 as published by the Free Software Foundation,
12	* in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
13	* distribution. VirtualBox OSE is distributed in the hope that it will
14	* be useful, but WITHOUT ANY WARRANTY of any kind.
15	*
16	* If you received this file as part of a commercial VirtualBox
17	* distribution, then only the terms of your commercial VirtualBox
18	* license agreement apply instead of the previous paragraph.
19	*/
20
21	#ifndef __VBox_pdm_h__
22	#define __VBox_pdm_h__
23
24	#include <VBox/cdefs.h>
25	#include <VBox/types.h>
26	#include <VBox/iom.h>
27	#include <VBox/ssm.h>
28	#include <VBox/cfgm.h>
29	#include <VBox/dbgf.h>
30	#include <VBox/err.h>
31	#include <VBox/pci.h>
32	#include <VBox/VBoxGuest.h>
33
34	#include <iprt/critsect.h>
35	#include <iprt/stdarg.h>
36
37
38	__BEGIN_DECLS
39
40	/** @defgroup grp_pdm The Pluggable Device Manager API
41	* @{
42	*/
43
44	/** Source position.
45	* @deprecated Use RT_SRC_POS */
46	#define PDM_SRC_POS RT_SRC_POS
47
48	/** Source position declaration.
49	* @deprecated Use RT_SRC_POS_DECL */
50	#define PDM_SRC_POS_DECL RT_SRC_POS_DECL
51
52	/** Source position arguments.
53	* @deprecated Use RT_SRC_POS_ARGS */
54	#define PDM_SRC_POS_ARGS RT_SRC_POS_ARGS
55
56
57	/** @defgroup grp_pdm_queue The PDM Queue
58	* @ingroup grp_pdm
59	* @{
60	*/
61
62	/** Pointer to a PDM queue. Also called PDM queue handle. */
63	typedef struct PDMQUEUE *PPDMQUEUE;
64
65	/** Pointer to a PDM queue item core. */
66	typedef struct PDMQUEUEITEMCORE *PPDMQUEUEITEMCORE;
67
68	/**
69	* PDM queue item core.
70	*/
71	typedef struct PDMQUEUEITEMCORE
72	{
73	/** Pointer to the next item in the pending list - HC Pointer. */
74	HCPTRTYPE(PPDMQUEUEITEMCORE) pNextHC;
75	/** Pointer to the next item in the pending list - GC Pointer. */
76	GCPTRTYPE(PPDMQUEUEITEMCORE) pNextGC;
77	#if HC_ARCH_BITS == 64 && GC_ARCH_BITS == 32
78	uint32_t Alignment0;
79	#endif
80	} PDMQUEUEITEMCORE;
81
82
83	/**
84	* Queue consumer callback for devices.
85	*
86	* @returns Success indicator.
87	* If false the item will not be removed and the flushing will stop.
88	* @param pDevIns The device instance.
89	* @param pItem The item to consume. Upon return this item will be freed.
90	*/
91	typedef DECLCALLBACK(bool) FNPDMQUEUEDEV(PPDMDEVINS pDevIns, PPDMQUEUEITEMCORE pItem);
92	/** Pointer to a FNPDMQUEUEDEV(). */
93	typedef FNPDMQUEUEDEV *PFNPDMQUEUEDEV;
94
95	/**
96	* Queue consumer callback for drivers.
97	*
98	* @returns Success indicator.
99	* If false the item will not be removed and the flushing will stop.
100	* @param pDrvIns The driver instance.
101	* @param pItem The item to consume. Upon return this item will be freed.
102	*/
103	typedef DECLCALLBACK(bool) FNPDMQUEUEDRV(PPDMDRVINS pDrvIns, PPDMQUEUEITEMCORE pItem);
104	/** Pointer to a FNPDMQUEUEDRV(). */
105	typedef FNPDMQUEUEDRV *PFNPDMQUEUEDRV;
106
107	/**
108	* Queue consumer callback for internal component.
109	*
110	* @returns Success indicator.
111	* If false the item will not be removed and the flushing will stop.
112	* @param pVM The VM handle.
113	* @param pItem The item to consume. Upon return this item will be freed.
114	*/
115	typedef DECLCALLBACK(bool) FNPDMQUEUEINT(PVM pVM, PPDMQUEUEITEMCORE pItem);
116	/** Pointer to a FNPDMQUEUEINT(). */
117	typedef FNPDMQUEUEINT *PFNPDMQUEUEINT;
118
119	/**
120	* Queue consumer callback for external component.
121	*
122	* @returns Success indicator.
123	* If false the item will not be removed and the flushing will stop.
124	* @param pvUser User argument.
125	* @param pItem The item to consume. Upon return this item will be freed.
126	*/
127	typedef DECLCALLBACK(bool) FNPDMQUEUEEXT(void *pvUser, PPDMQUEUEITEMCORE pItem);
128	/** Pointer to a FNPDMQUEUEEXT(). */
129	typedef FNPDMQUEUEEXT *PFNPDMQUEUEEXT;
130
131	/**
132	* Create a queue with a device owner.
133	*
134	* @returns VBox status code.
135	* @param pVM VM handle.
136	* @param pDevIns Device instance.
137	* @param cbItem Size a queue item.
138	* @param cItems Number of items in the queue.
139	* @param cMilliesInterval Number of milliseconds between polling the queue.
140	* If 0 then the emulation thread will be notified whenever an item arrives.
141	* @param pfnCallback The consumer function.
142	* @param fGCEnabled Set if the queue must be usable from GC.
143	* @param ppQueue Where to store the queue handle on success.
144	* @thread Emulation thread only.
145	*/
146	PDMR3DECL(int) PDMR3QueueCreateDevice(PVM pVM, PPDMDEVINS pDevIns, RTUINT cbItem, RTUINT cItems, uint32_t cMilliesInterval,
147	PFNPDMQUEUEDEV pfnCallback, bool fGCEnabled, PPDMQUEUE *ppQueue);
148
149	/**
150	* Create a queue with a driver owner.
151	*
152	* @returns VBox status code.
153	* @param pVM VM handle.
154	* @param pDrvIns Driver instance.
155	* @param cbItem Size a queue item.
156	* @param cItems Number of items in the queue.
157	* @param cMilliesInterval Number of milliseconds between polling the queue.
158	* If 0 then the emulation thread will be notified whenever an item arrives.
159	* @param pfnCallback The consumer function.
160	* @param ppQueue Where to store the queue handle on success.
161	* @thread The emulation thread.
162	*/
163	PDMR3DECL(int) PDMR3QueueCreateDriver(PVM pVM, PPDMDRVINS pDrvIns, RTUINT cbItem, RTUINT cItems, uint32_t cMilliesInterval,
164	PFNPDMQUEUEDRV pfnCallback, PPDMQUEUE *ppQueue);
165
166	/**
167	* Create a queue with an internal owner.
168	*
169	* @returns VBox status code.
170	* @param pVM VM handle.
171	* @param cbItem Size a queue item.
172	* @param cItems Number of items in the queue.
173	* @param cMilliesInterval Number of milliseconds between polling the queue.
174	* If 0 then the emulation thread will be notified whenever an item arrives.
175	* @param pfnCallback The consumer function.
176	* @param fGCEnabled Set if the queue must be usable from GC.
177	* @param ppQueue Where to store the queue handle on success.
178	* @thread Emulation thread only.
179	*/
180	PDMR3DECL(int) PDMR3QueueCreateInternal(PVM pVM, RTUINT cbItem, RTUINT cItems, uint32_t cMilliesInterval,
181	PFNPDMQUEUEINT pfnCallback, bool fGCEnabled, PPDMQUEUE *ppQueue);
182
183	/**
184	* Create a queue with an external owner.
185	*
186	* @returns VBox status code.
187	* @param pVM VM handle.
188	* @param cbItem Size a queue item.
189	* @param cItems Number of items in the queue.
190	* @param cMilliesInterval Number of milliseconds between polling the queue.
191	* If 0 then the emulation thread will be notified whenever an item arrives.
192	* @param pfnCallback The consumer function.
193	* @param pvUser The user argument to the consumer function.
194	* @param ppQueue Where to store the queue handle on success.
195	* @thread The emulation thread.
196	*/
197	PDMR3DECL(int) PDMR3QueueCreateExternal(PVM pVM, RTUINT cbItem, RTUINT cItems, uint32_t cMilliesInterval,
198	PFNPDMQUEUEEXT pfnCallback, void pvUser, PPDMQUEUE ppQueue);
199
200	/**
201	* Destroy a queue.
202	*
203	* @returns VBox status code.
204	* @param pQueue Queue to destroy.
205	* @thread The emulation thread.
206	*/
207	PDMR3DECL(int) PDMR3QueueDestroy(PPDMQUEUE pQueue);
208
209	/**
210	* Destroy a all queues owned by the specified device.
211	*
212	* @returns VBox status code.
213	* @param pVM VM handle.
214	* @param pDevIns Device instance.
215	* @thread Emulation thread only.
216	*/
217	PDMR3DECL(int) PDMR3QueueDestroyDevice(PVM pVM, PPDMDEVINS pDevIns);
218
219	/**
220	* Destroy a all queues owned by the specified driver.
221	*
222	* @returns VBox status code.
223	* @param pVM VM handle.
224	* @param pDrvIns Driver instance.
225	* @thread Emulation thread only.
226	*/
227	PDMR3DECL(int) PDMR3QueueDestroyDriver(PVM pVM, PPDMDRVINS pDrvIns);
228
229	/**
230	* Flushes pending queues.
231	* This is a forced action callback.
232	*
233	* @param pVM VM handle.
234	* @thread The emulation thread.
235	*/
236	PDMR3DECL(void) PDMR3QueueFlushAll(PVM pVM);
237
238	/**
239	* This is a worker function used by PDMQueueFlush to perform the
240	* flush in ring-3.
241	*
242	* The queue which should be flushed is pointed to by either pQueueFlushGC,
243	* pQueueFlushHC, or pQueueue. This function will flush that queue and
244	* recalc the queue FF.
245	*
246	* @param pVM The VM handle.
247	* @param pQueue The queue to flush. Only used in Ring-3.
248	*/
249	PDMR3DECL(void) PDMR3QueueFlushWorker(PVM pVM, PPDMQUEUE pQueue);
250
251	/**
252	* Flushes a PDM queue.
253	*
254	* @param pQueue The queue handle.
255	*/
256	PDMDECL(void) PDMQueueFlush(PPDMQUEUE pQueue);
257
258	/**
259	* Allocate an item from a queue.
260	* The allocated item must be handed on to PDMQueueInsert() after the
261	* data has been filled in.
262	*
263	* @returns Pointer to allocated queue item.
264	* @returns NULL on failure. The queue is exhausted.
265	* @param pQueue The queue handle.
266	* @thread Any thread.
267	*/
268	PDMDECL(PPDMQUEUEITEMCORE) PDMQueueAlloc(PPDMQUEUE pQueue);
269
270	/**
271	* Queue an item.
272	* The item must have been obtained using PDMQueueAlloc(). Once the item
273	* has been passed to this function it must not be touched!
274	*
275	* @param pQueue The queue handle.
276	* @param pItem The item to insert.
277	* @thread Any thread.
278	*/
279	PDMDECL(void) PDMQueueInsert(PPDMQUEUE pQueue, PPDMQUEUEITEMCORE pItem);
280
281	/**
282	* Queue an item.
283	* The item must have been obtained using PDMQueueAlloc(). Once the item
284	* have been passed to this function it must not be touched!
285	*
286	* @param pQueue The queue handle.
287	* @param pItem The item to insert.
288	* @param NanoMaxDelay The maximum delay before processing the queue, in nanoseconds.
289	* This applies only to GC.
290	* @thread Any thread.
291	*/
292	PDMDECL(void) PDMQueueInsertEx(PPDMQUEUE pQueue, PPDMQUEUEITEMCORE pItem, uint64_t NanoMaxDelay);
293
294
295	/**
296	* Gets the GC pointer for the specified queue.
297	*
298	* @returns The GC address of the queue.
299	* @returns NULL if pQueue is invalid.
300	* @param pQueue The queue handle.
301	*/
302	PDMDECL(GCPTRTYPE(PPDMQUEUE)) PDMQueueGCPtr(PPDMQUEUE pQueue);
303
304	/** @} */
305
306
307
308	/** @defgroup grp_pdm_critsect The PDM Critical Section
309	* @ingroup grp_pdm
310	* @{
311	*/
312
313	/**
314	* A PDM critical section.
315	* Initialize using PDMDRVHLP::pfnCritSectInit().
316	*/
317	typedef union PDMCRITSECT
318	{
319	/** Padding. */
320	uint8_t padding[HC_ARCH_BITS == 64 ? 0xa8 : 0x80];
321	#ifdef PDMCRITSECTINT_DECLARED
322	/** The internal structure (not normally visible). */
323	struct PDMCRITSECTINT s;
324	#endif
325	} PDMCRITSECT;
326	/** Pointer to a PDM critical section. */
327	typedef PDMCRITSECT *PPDMCRITSECT;
328	/** Pointer to a const PDM critical section. */
329	typedef const PDMCRITSECT *PCPDMCRITSECT;
330
331	/**
332	* Initializes a PDM critical section for internal use.
333	*
334	* The PDM critical sections are derived from the IPRT critical sections, but
335	* works in GC as well.
336	*
337	* @returns VBox status code.
338	* @param pVM The VM handle.
339	* @param pDevIns Device instance.
340	* @param pCritSect Pointer to the critical section.
341	* @param pszName The name of the critical section (for statistics).
342	*/
343	PDMR3DECL(int) PDMR3CritSectInit(PVM pVM, PPDMCRITSECT pCritSect, const char *pszName);
344
345	/**
346	* Leaves a critical section entered with PDMCritSectEnter().
347	*
348	* @returns VINF_SUCCESS if entered successfully.
349	* @returns rcBusy when encountering a busy critical section in GC/R0.
350	* @returns VERR_SEM_DESTROYED if the critical section is dead.
351	*
352	* @param pCritSect The PDM critical section to enter.
353	* @param rcBusy The status code to return when we're in GC or R0
354	* and the section is busy.
355	*/
356	PDMDECL(int) PDMCritSectEnter(PPDMCRITSECT pCritSect, int rcBusy);
357
358	/**
359	* Leaves a critical section entered with PDMCritSectEnter().
360	*
361	* @param pCritSect The PDM critical section to leave.
362	*/
363	PDMDECL(void) PDMCritSectLeave(PPDMCRITSECT pCritSect);
364
365	/**
366	* Checks the caller is the owner of the critical section.
367	*
368	* @returns true if owner.
369	* @returns false if not owner.
370	* @param pCritSect The critical section.
371	*/
372	PDMDECL(bool) PDMCritSectIsOwner(PCPDMCRITSECT pCritSect);
373
374	/**
375	* Deletes the critical section.
376	*
377	* @returns VBox status code.
378	* @param pCritSect The PDM critical section to destroy.
379	*/
380	PDMR3DECL(int) PDMR3CritSectDelete(PPDMCRITSECT pCritSect);
381
382	/**
383	* Deletes all remaining critical sections.
384	*
385	* This is called at the end of the termination process.
386	*
387	* @returns VBox status.
388	* First error code, rest is lost.
389	* @param pVM The VM handle.
390	* @remark Don't confuse this with PDMR3CritSectDelete.
391	*/
392	PDMDECL(int) PDMR3CritSectTerm(PVM pVM);
393
394	/**
395	* Process the critical sections queued for ring-3 'leave'.
396	*
397	* @param pVM The VM handle.
398	*/
399	PDMR3DECL(void) PDMR3CritSectFF(PVM pVM);
400
401	/** @} */
402
403
404
405	/** @defgroup grp_pdm_interfaces Interfaces
406	* @ingroup grp_pdm
407	* @{
408	*/
409
410	/**
411	* Driver interface identficators.
412	*/
413	typedef enum PDMINTERFACE
414	{
415	/** PDMIBASE - The interface everyone supports. */
416	PDMINTERFACE_BASE = 1,
417	/** PDMIMOUSEPORT - The mouse port interface. (Down) Coupled with PDMINTERFACE_MOUSE_CONNECTOR. */
418	PDMINTERFACE_MOUSE_PORT,
419	/** PDMIMOUSECONNECTOR - The mouse connector interface. (Up) Coupled with PDMINTERFACE_MOUSE_PORT. */
420	PDMINTERFACE_MOUSE_CONNECTOR,
421	/** PDMIKEYBOARDPORT - The keyboard port interface. (Down) Coupled with PDMINTERFACE_KEYBOARD_CONNECTOR. */
422	PDMINTERFACE_KEYBOARD_PORT,
423	/** PDMIKEYBOARDCONNECTOR - The keyboard connector interface. (Up) Coupled with PDMINTERFACE_KEYBOARD_PORT. */
424	PDMINTERFACE_KEYBOARD_CONNECTOR,
425	/** PDMIDISPLAYPORT - The display port interface. (Down) Coupled with PDMINTERFACE_DISPLAY_CONNECTOR. */
426	PDMINTERFACE_DISPLAY_PORT,
427	/** PDMIDISPLAYCONNECTOR - The display connector interface. (Up) Coupled with PDMINTERFACE_DISPLAY_PORT. */
428	PDMINTERFACE_DISPLAY_CONNECTOR,
429	/** PDMIBLOCKPORT - The block notify interface (Down) Coupled with PDMINTERFACE_BLOCK. */
430	PDMINTERFACE_BLOCK_PORT,
431	/** PDMIBLOCK - The block driver interface (Up) Coupled with PDMINTERFACE_BLOCK_PORT. */
432	PDMINTERFACE_BLOCK,
433	/** PDMIBLOCKBIOS - The block bios interface. (External) */
434	PDMINTERFACE_BLOCK_BIOS,
435	/** PDMIMOUNTNOTIFY - The mountable notification interface. (Down) Coupled with PDMINTERFACE_MOUNT. */
436	PDMINTERFACE_MOUNT_NOTIFY,
437	/** PDMIMOUNT - The mountable interface. (Up) Coupled with PDMINTERFACE_MOUNT_NOTIFY. */
438	PDMINTERFACE_MOUNT,
439	/** PDMIMEDIA - The media interface. (Up) No coupling.
440	* Used by a block unit driver to implement PDMINTERFACE_BLOCK and PDMINTERFACE_BLOCK_BIOS. */
441	PDMINTERFACE_MEDIA,
442	/** PDMIISCSITRANSPORT - The iSCSI transport interface (Up) No coupling.
443	* used by the iSCSI media driver. */
444	PDMINTERFACE_ISCSITRANSPORT,
445
446	/** PDMINETWORKPORT - The network port interface. (Down) Coupled with PDMINTERFACE_NETWORK_CONNECTOR. */
447	PDMINTERFACE_NETWORK_PORT,
448	/** PDMINETWORKPORT - The network connector interface. (Up) Coupled with PDMINTERFACE_NETWORK_PORT. */
449	PDMINTERFACE_NETWORK_CONNECTOR,
450	/** PDMINETWORKCONFIG - The network configuartion interface. (Main) Used by the managment api. */
451	PDMINTERFACE_NETWORK_CONFIG,
452
453	/** PDMIAUDIOCONNECTOR - The audio driver interface. (Up) No coupling. */
454	PDMINTERFACE_AUDIO_CONNECTOR,
455
456	/** PDMIAUDIOSNIFFERPORT - The Audio Sniffer Device port interface. */
457	PDMINTERFACE_AUDIO_SNIFFER_PORT,
458	/** PDMIAUDIOSNIFFERCONNECTOR - The Audio Sniffer Driver connector interface. */
459	PDMINTERFACE_AUDIO_SNIFFER_CONNECTOR,
460
461	/** PDMIVMMDEVPORT - The VMM Device port interface. */
462	PDMINTERFACE_VMMDEV_PORT,
463	/** PDMIVMMDEVCONNECTOR - The VMM Device connector interface. */
464	PDMINTERFACE_VMMDEV_CONNECTOR,
465
466	/** PDMILEDPORTS - The generic LED port interface. (Down) Coupled with PDMINTERFACE_LED_CONNECTORS. */
467	PDMINTERFACE_LED_PORTS,
468	/** PDMILEDCONNECTORS - The generic LED connector interface. (Up) Coupled with PDMINTERFACE_LED_PORTS. */
469	PDMINTERFACE_LED_CONNECTORS,
470
471	/** PDMIACPIPORT - ACPI port interface. (Down) Coupled with PDMINTERFACE_ACPI_CONNECTOR. */
472	PDMINTERFACE_ACPI_PORT,
473	/** PDMIACPICONNECTOR - ACPI connector interface. (Up) Coupled with PDMINTERFACE_ACPI_PORT. */
474	PDMINTERFACE_ACPI_CONNECTOR,
475
476	/** PDMIHGCMPORT - The Host-Guest communication manager port interface. Normally implemented by VMMDev. */
477	PDMINTERFACE_HGCM_PORT,
478	/** PDMIHGCMCONNECTOR - The Host-Guest communication manager connector interface. Normally implemented by Main::VMMDevInterface. */
479	PDMINTERFACE_HGCM_CONNECTOR,
480
481	/** VUSBIROOTHUBPORT - VUSB RootHub port interface. (Down) Coupled with PDMINTERFACE_USB_RH_CONNECTOR. */
482	PDMINTERFACE_VUSB_RH_PORT,
483	/** VUSBIROOTHUBCONNECTOR - VUSB RootHub connector interface. (Up) Coupled with PDMINTERFACE_USB_RH_PORT. */
484	PDMINTERFACE_VUSB_RH_CONNECTOR,
485	/** VUSBIROOTHUBCONNECTOR - VUSB RootHub configuration interface. (Main) Used by the managment api. */
486	PDMINTERFACE_VUSB_RH_CONFIG,
487
488	/** VUSBROOTHUBCONNECTOR - VUSB Device interface. (Up) No coupling. */
489	PDMINTERFACE_VUSB_DEVICE,
490
491	/** Maximum interface number. */
492	PDMINTERFACE_MAX
493	} PDMINTERFACE;
494
495
496	/**
497	* PDM Driver Base Interface.
498	*/
499	typedef struct PDMIBASE
500	{
501	/**
502	* Queries an interface to the driver.
503	*
504	* @returns Pointer to interface.
505	* @returns NULL if the interface was not supported by the driver.
506	* @param pInterface Pointer to this interface structure.
507	* @param enmInterface The requested interface identification.
508	* @thread Any thread.
509	*/
510	DECLR3CALLBACKMEMBER(void , pfnQueryInterface,(struct PDMIBASE pInterface, PDMINTERFACE enmInterface));
511	} PDMIBASE;
512	/** Pointer to a PDM Driver Base Interface. */
513	typedef PDMIBASE *PPDMIBASE;
514
515
516	/**
517	* Dummy interface.
518	*
519	* This is used to typedef other dummy interfaces. The purpose of a dummy
520	* interface is to validate the logical function of a driver/device and
521	* full a natural interface pair.
522	*/
523	typedef struct PDMIDUMMY
524	{
525	RTHCPTR pvDummy;
526	} PDMIDUMMY;
527
528
529	/** Pointer to a mouse port interface. */
530	typedef struct PDMIMOUSEPORT *PPDMIMOUSEPORT;
531	/**
532	* Mouse port interface.
533	* Pair with PDMIMOUSECONNECTOR.
534	*/
535	typedef struct PDMIMOUSEPORT
536	{
537	/**
538	* Puts a mouse event.
539	* This is called by the source of mouse events. The event will be passed up until the
540	* topmost driver, which then calls the registered event handler.
541	*
542	* @returns VBox status code.
543	* @param pInterface Pointer to this interface structure.
544	* @param i32DeltaX The X delta.
545	* @param i32DeltaY The Y delta.
546	* @param i32DeltaZ The Z delta.
547	* @param fButtonStates The button states, see the PDMIMOUSEPORT_BUTTON_* \#defines.
548	* @thread The emulation thread.
549	*/
550	DECLR3CALLBACKMEMBER(int, pfnPutEvent,(PPDMIMOUSEPORT pInterface, int32_t i32DeltaX, int32_t i32DeltaY, int32_t i32DeltaZ, uint32_t fButtonStates));
551	} PDMIMOUSEPORT;
552
553	/** Mouse button defines for PDMIMOUSEPORT::pfnPutEvent.
554	* @{ */
555	#define PDMIMOUSEPORT_BUTTON_LEFT BIT(0)
556	#define PDMIMOUSEPORT_BUTTON_RIGHT BIT(1)
557	#define PDMIMOUSEPORT_BUTTON_MIDDLE BIT(2)
558	/** @} */
559
560
561	/**
562	* Mouse connector interface.
563	* Pair with PDMIMOUSEPORT.
564	*/
565	typedef PDMIDUMMY PDMIMOUSECONNECTOR;
566	/** Pointer to a mouse connector interface. */
567	typedef PDMIMOUSECONNECTOR *PPDMIMOUSECONNECTOR;
568
569
570	/** Pointer to a keyboard port interface. */
571	typedef struct PDMIKEYBOARDPORT *PPDMIKEYBOARDPORT;
572	/**
573	* Keyboard port interface.
574	* Pair with PDMIKEYBOARDCONNECTOR.
575	*/
576	typedef struct PDMIKEYBOARDPORT
577	{
578	/**
579	* Puts a keyboard event.
580	* This is called by the source of keyboard events. The event will be passed up until the
581	* topmost driver, which then calls the registered event handler.
582	*
583	* @returns VBox status code.
584	* @param pInterface Pointer to this interface structure.
585	* @param u8KeyCode The keycode to queue.
586	* @thread The emulation thread.
587	*/
588	DECLR3CALLBACKMEMBER(int, pfnPutEvent,(PPDMIKEYBOARDPORT pInterface, uint8_t u8KeyCode));
589	} PDMIKEYBOARDPORT;
590
591	/**
592	* Keyboard LEDs.
593	*/
594	typedef enum PDMKEYBLEDS
595	{
596	/** Num Lock */
597	PDMKEYBLEDS_NUMLOCK = 0x0001,
598	/** Caps Lock */
599	PDMKEYBLEDS_CAPSLOCK = 0x0002,
600	/** Scroll Lock */
601	PDMKEYBLEDS_SCROLLLOCK = 0x0004
602	} PDMKEYBLEDS;
603
604	/** Pointer to keyboard connector interface. */
605	typedef struct PDMIKEYBOARDCONNECTOR *PPDMIKEYBOARDCONNECTOR;
606
607
608	/**
609	* Keyboard connector interface.
610	* Pair with PDMIKEYBOARDPORT
611	*/
612	typedef struct PDMIKEYBOARDCONNECTOR
613	{
614	/**
615	* Notifies the the downstream driver about an LED change initiated by the guest.
616	*
617	* @param pInterface Pointer to the this interface.
618	* @param enmLeds The new led mask.
619	*/
620	DECLR3CALLBACKMEMBER(void, pfnLedStatusChange,(PPDMIKEYBOARDCONNECTOR pInterface, PDMKEYBLEDS enmLeds));
621
622	} PDMIKEYBOARDCONNECTOR;
623
624
625	/** Pointer to a display port interface. */
626	typedef struct PDMIDISPLAYPORT *PPDMIDISPLAYPORT;
627	/**
628	* Display port interface.
629	* Pair with PDMIDISPLAYCONNECTOR.
630	*/
631	typedef struct PDMIDISPLAYPORT
632	{
633	/**
634	* Update the display with any changed regions.
635	*
636	* Flushes any display changes to the memory pointed to by the
637	* PDMIDISPLAYCONNECTOR interface and calles PDMIDISPLAYCONNECTOR::pfnUpdateRect()
638	* while doing so.
639	*
640	* @param pInterface Pointer to this interface.
641	* @thread The emulation thread.
642	*/
643	DECLR3CALLBACKMEMBER(void, pfnUpdateDisplay,(PPDMIDISPLAYPORT pInterface));
644
645	/**
646	* Update the entire display.
647	*
648	* Flushes the entire display content to the memory pointed to by the
649	* PDMIDISPLAYCONNECTOR interface and calles PDMIDISPLAYCONNECTOR::pfnUpdateRect().
650	*
651	* @param pInterface Pointer to this interface.
652	* @thread The emulation thread.
653	*/
654	DECLR3CALLBACKMEMBER(void, pfnUpdateDisplayAll,(PPDMIDISPLAYPORT pInterface));
655
656	/**
657	* Return the current guest color depth in bits per pixel (bpp).
658	*
659	* As the graphics card is able to provide display updates with the bpp
660	* requested by the host, this method can be used to query the actual
661	* guest color depth.
662	*
663	* @returns VBox status code.
664	* @param pInterface Pointer to this interface.
665	* @param pcBits Where to store the current guest color depth.
666	* @thread Any thread.
667	*/
668	DECLR3CALLBACKMEMBER(int, pfnQueryColorDepth,(PPDMIDISPLAYPORT pInterface, uint32_t *pcBits));
669
670	/**
671	* Sets the refresh rate and restart the timer.
672	* The rate is defined as the minimum interval between the return of
673	* one PDMIDISPLAYPORT::pfnRefresh() call to the next one.
674	*
675	* The interval timer will be restarted by this call. So at VM startup
676	* this function must be called to start the refresh cycle. The refresh
677	* rate is not saved, but have to be when resuming a loaded VM state.
678	*
679	* @returns VBox status code.
680	* @param pInterface Pointer to this interface.
681	* @param cMilliesInterval Number of millies between two refreshes.
682	* @thread Any thread.
683	*/
684	DECLR3CALLBACKMEMBER(int, pfnSetRefreshRate,(PPDMIDISPLAYPORT pInterface, uint32_t cMilliesInterval));
685
686	/**
687	* Create a 32-bbp snapshot of the display.
688	*
689	* This will create a 32-bbp bitmap with dword aligned scanline length. Because
690	* of a wish for no locks in the graphics device, this must be called from the
691	* emulation thread.
692	*
693	* @param pInterface Pointer to this interface.
694	* @param pvData Pointer the buffer to copy the bits to.
695	* @param cbData Size of the buffer.
696	* @param pcx Where to store the width of the bitmap. (optional)
697	* @param pcy Where to store the height of the bitmap. (optional)
698	* @param pcbData Where to store the actual size of the bitmap. (optional)
699	* @thread The emulation thread.
700	*/
701	DECLR3CALLBACKMEMBER(int, pfnSnapshot,(PPDMIDISPLAYPORT pInterface, void pvData, size_t cbData, uint32_t pcx, uint32_t pcy, size_t pcbData));
702
703	/**
704	* Copy bitmap to the display.
705	*
706	* This will convert and copy a 32-bbp bitmap (with dword aligned scanline length) to
707	* the memory pointed to by the PDMIDISPLAYCONNECTOR interface.
708	*
709	* @param pInterface Pointer to this interface.
710	* @param pvData Pointer to the bitmap bits.
711	* @param x The upper left corner x coordinate of the destination rectangle.
712	* @param y The upper left corner y coordinate of the destination rectangle.
713	* @param cx The width of the source and destination rectangles.
714	* @param cy The height of the source and destination rectangles.
715	* @thread The emulation thread.
716	* @remark This is just a convenience for using the bitmap conversions of the
717	* graphics device.
718	*/
719	DECLR3CALLBACKMEMBER(int, pfnDisplayBlt,(PPDMIDISPLAYPORT pInterface, const void *pvData, uint32_t x, uint32_t y, uint32_t cx, uint32_t cy));
720
721	/**
722	* Render a rectangle from guest VRAM to Framebuffer.
723	*
724	* @param pInterface Pointer to this interface.
725	* @param x The upper left corner x coordinate of the rectangle to be updated.
726	* @param y The upper left corner y coordinate of the rectangle to be updated.
727	* @param cx The width of the rectangle to be updated.
728	* @param cy The height of the rectangle to be updated.
729	* @thread The emulation thread.
730	*/
731	DECLR3CALLBACKMEMBER(void, pfnUpdateDisplayRect,(PPDMIDISPLAYPORT pInterface, int32_t x, int32_t y, uint32_t cx, uint32_t cy));
732
733	/**
734	* Setup guest physical VRAM to use the provided page aligned
735	* memory buffer as the guest VRAM, may be equal to current guest VRAM.
736	*
737	* @returns VBox status code.
738	* @param pInterface Pointer to this interface.
739	* @param pvBuffer Page aligned address. NULL for removing previously set buffer.
740	* @param cbBuffer Size of buffer. Must be equal to a whole number of pages.
741	* @thread The emulation thread.
742	*/
743	DECLR3CALLBACKMEMBER(int, pfnSetupVRAM,(PPDMIDISPLAYPORT pInterface, void *pvBuffer, uint32_t cbBuffer));
744	} PDMIDISPLAYPORT;
745
746
747	/** Pointer to a display connector interface. */
748	typedef struct PDMIDISPLAYCONNECTOR *PPDMIDISPLAYCONNECTOR;
749	/**
750	* Display connector interface.
751	* Pair with PDMIDISPLAYPORT.
752	*/
753	typedef struct PDMIDISPLAYCONNECTOR
754	{
755	/**
756	* Resize the display.
757	* This is called when the resolution changes. This usually happens on
758	* request from the guest os, but may also happen as the result of a reset.
759	*
760	* @param pInterface Pointer to this interface.
761	* @param cBits Color depth (bits per pixel) of the new video mode.
762	* @param pvVRAM Address of guest VRAM.
763	* @param cbLine Size in bytes of a single scan line.
764	* @param cx New display width.
765	* @param cy New display height.
766	* @thread The emulation thread.
767	*/
768	DECLR3CALLBACKMEMBER(void, pfnResize,(PPDMIDISPLAYCONNECTOR pInterface, uint32_t cBits, void *pvVRAM, uint32_t cbLine, uint32_t cx, uint32_t cy));
769
770	/**
771	* Update a rectangle of the display.
772	* PDMIDISPLAYPORT::pfnUpdateDisplay is the caller.
773	*
774	* @param pInterface Pointer to this interface.
775	* @param x The upper left corner x coordinate of the rectangle.
776	* @param y The upper left corner y coordinate of the rectangle.
777	* @param cx The width of the rectangle.
778	* @param cy The height of the rectangle.
779	* @thread The emulation thread.
780	*/
781	DECLR3CALLBACKMEMBER(void, pfnUpdateRect,(PPDMIDISPLAYCONNECTOR pInterface, uint32_t x, uint32_t y, uint32_t cx, uint32_t cy));
782
783	/**
784	* Refresh the display.
785	*
786	* The interval between these calls is set by
787	* PDMIDISPLAYPORT::pfnSetRefreshRate(). The driver should call
788	* PDMIDISPLAYPORT::pfnUpdateDisplay() if it wishes to refresh the
789	* display. PDMIDISPLAYPORT::pfnUpdateDisplay calls pfnUpdateRect with
790	* the changed rectangles.
791	*
792	* @param pInterface Pointer to this interface.
793	* @thread The emulation thread.
794	*/
795	DECLR3CALLBACKMEMBER(void, pfnRefresh,(PPDMIDISPLAYCONNECTOR pInterface));
796
797	/**
798	* Reset the display.
799	*
800	* Notification message when the graphics card has been reset.
801	*
802	* @param pInterface Pointer to this interface.
803	* @thread The emulation thread.
804	*/
805	DECLR3CALLBACKMEMBER(void, pfnReset,(PPDMIDISPLAYCONNECTOR pInterface));
806
807	/**
808	* LFB video mode enter/exit.
809	*
810	* Notification message when LinearFrameBuffer video mode is enabled/disabled.
811	*
812	* @param pInterface Pointer to this interface.
813	* @param fEnabled false - LFB mode was disabled,
814	* true - an LFB mode was disabled
815	* @thread The emulation thread.
816	*/
817	DECLCALLBACKMEMBER(void, pfnLFBModeChange)(PPDMIDISPLAYCONNECTOR pInterface, bool fEnabled);
818
819
820	/** Read-only attributes.
821	* For preformance reasons some readonly attributes are kept in the interface.
822	* We trust the interface users to respect the readonlyness of these.
823	* @{
824	*/
825	/** Pointer to the display data buffer. */
826	uint8_t *pu8Data;
827	/** Size of a scanline in the data buffer. */
828	uint32_t cbScanline;
829	/** The color depth (in bits) the graphics card is supposed to provide. */
830	uint32_t cBits;
831	/** The display width. */
832	uint32_t cx;
833	/** The display height. */
834	uint32_t cy;
835	/** @} */
836	} PDMIDISPLAYCONNECTOR;
837
838
839
840	/**
841	* Block drive type.
842	*/
843	typedef enum PDMBLOCKTYPE
844	{
845	/** Error (for the query function). */
846	PDMBLOCKTYPE_ERROR = 1,
847	/** 360KB 5 1/4" floppy drive. */
848	PDMBLOCKTYPE_FLOPPY_360,
849	/** 720KB 3 1/2" floppy drive. */
850	PDMBLOCKTYPE_FLOPPY_720,
851	/** 1.2MB 5 1/4" floppy drive. */
852	PDMBLOCKTYPE_FLOPPY_1_20,
853	/** 1.44MB 3 1/2" floppy drive. */
854	PDMBLOCKTYPE_FLOPPY_1_44,
855	/** 2.88MB 3 1/2" floppy drive. */
856	PDMBLOCKTYPE_FLOPPY_2_88,
857	/** CDROM drive. */
858	PDMBLOCKTYPE_CDROM,
859	/** DVD drive. */
860	PDMBLOCKTYPE_DVD,
861	/** Hard disk drive. */
862	PDMBLOCKTYPE_HARD_DISK
863	} PDMBLOCKTYPE;
864
865
866	/**
867	* Block raw command data transfer direction.
868	*/
869	typedef enum PDMBLOCKTXDIR
870	{
871	PDMBLOCKTXDIR_NONE = 0,
872	PDMBLOCKTXDIR_FROM_DEVICE,
873	PDMBLOCKTXDIR_TO_DEVICE
874	} PDMBLOCKTXDIR;
875
876	/**
877	* Block notify interface.
878	* Pair with PDMIBLOCK.
879	*/
880	typedef PDMIDUMMY PDMIBLOCKPORT;
881	/** Pointer to a block notify interface (dummy). */
882	typedef PDMIBLOCKPORT *PPDMIBLOCKPORT;
883
884
885	/** Pointer to a block interface. */
886	typedef struct PDMIBLOCK *PPDMIBLOCK;
887	/**
888	* Block interface.
889	* Pair with PDMIBLOCK.
890	*/
891	typedef struct PDMIBLOCK
892	{
893	/**
894	* Read bits.
895	*
896	* @returns VBox status code.
897	* @param pInterface Pointer to the interface structure containing the called function pointer.
898	* @param off Offset to start reading from.
899	* @param pvBuf Where to store the read bits.
900	* @param cbRead Number of bytes to read.
901	* @thread Any thread.
902	*/
903	DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMIBLOCK pInterface, uint64_t off, void *pvBuf, size_t cbRead));
904
905	/**
906	* Write bits.
907	*
908	* @returns VBox status code.
909	* @param pInterface Pointer to the interface structure containing the called function pointer.
910	* @param off Offset to start writing at.
911	* @param pvBuf Where to store the write bits.
912	* @param cbWrite Number of bytes to write.
913	* @thread Any thread.
914	*/
915	DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMIBLOCK pInterface, uint64_t off, const void *pvBuf, size_t cbWrite));
916
917	/**
918	* Make sure that the bits written are actually on the storage medium.
919	*
920	* @returns VBox status code.
921	* @param pInterface Pointer to the interface structure containing the called function pointer.
922	* @thread Any thread.
923	*/
924	DECLR3CALLBACKMEMBER(int, pfnFlush,(PPDMIBLOCK pInterface));
925
926	/**
927	* Send a raw command to the underlying device (CDROM).
928	* This method is optional (i.e. the function pointer may be NULL).
929	*
930	* @returns VBox status code.
931	* @param pInterface Pointer to the interface structure containing the called function pointer.
932	* @param pbCmd Offset to start reading from.
933	* @param enmTxDir Direction of transfer.
934	* @param pvBuf Pointer tp the transfer buffer.
935	* @param cbBuf Size of the transfer buffer.
936	* @param pbSenseKey Status of the command (when return value is VERR_DEV_IO_ERROR).
937	* @param cTimeoutMillies Command timeout in milliseconds.
938	* @thread Any thread.
939	*/
940	DECLR3CALLBACKMEMBER(int, pfnSendCmd,(PPDMIBLOCK pInterface, const uint8_t pbCmd, PDMBLOCKTXDIR enmTxDir, void pvBuf, size_t pcbBuf, uint8_t pbSenseKey, uint32_t cTimeoutMillies));
941
942	/**
943	* Check if the media is readonly or not.
944	*
945	* @returns true if readonly.
946	* @returns false if read/write.
947	* @param pInterface Pointer to the interface structure containing the called function pointer.
948	* @thread Any thread.
949	*/
950	DECLR3CALLBACKMEMBER(bool, pfnIsReadOnly,(PPDMIBLOCK pInterface));
951
952	/**
953	* Gets the media size in bytes.
954	*
955	* @returns Media size in bytes.
956	* @param pInterface Pointer to the interface structure containing the called function pointer.
957	* @thread Any thread.
958	*/
959	DECLR3CALLBACKMEMBER(uint64_t, pfnGetSize,(PPDMIBLOCK pInterface));
960
961	/**
962	* Gets the block drive type.
963	*
964	* @returns block drive type.
965	* @param pInterface Pointer to the interface structure containing the called function pointer.
966	* @thread Any thread.
967	*/
968	DECLR3CALLBACKMEMBER(PDMBLOCKTYPE, pfnGetType,(PPDMIBLOCK pInterface));
969
970	/**
971	* Gets the UUID of the block drive.
972	* Don't return the media UUID if it's removable.
973	*
974	* @returns VBox status code.
975	* @param pInterface Pointer to the interface structure containing the called function pointer.
976	* @param pUuid Where to store the UUID on success.
977	* @thread Any thread.
978	*/
979	DECLR3CALLBACKMEMBER(int, pfnGetUuid,(PPDMIBLOCK pInterface, PRTUUID pUuid));
980	} PDMIBLOCK;
981
982
983	/** Pointer to a mount interface. */
984	typedef struct PDMIMOUNTNOTIFY *PPDMIMOUNTNOTIFY;
985	/**
986	* Block interface.
987	* Pair with PDMIMOUNT.
988	*/
989	typedef struct PDMIMOUNTNOTIFY
990	{
991	/**
992	* Called when a media is mounted.
993	*
994	* @param pInterface Pointer to the interface structure containing the called function pointer.
995	* @thread The emulation thread.
996	*/
997	DECLR3CALLBACKMEMBER(void, pfnMountNotify,(PPDMIMOUNTNOTIFY pInterface));
998
999	/**
1000	* Called when a media is unmounted
1001	* @param pInterface Pointer to the interface structure containing the called function pointer.
1002	* @thread The emulation thread.
1003	*/
1004	DECLR3CALLBACKMEMBER(void, pfnUnmountNotify,(PPDMIMOUNTNOTIFY pInterface));
1005	} PDMIMOUNTNOTIFY;
1006
1007
1008	/* Pointer to mount interface. */
1009	typedef struct PDMIMOUNT *PPDMIMOUNT;
1010	/**
1011	* Mount interface.
1012	* Pair with PDMIMOUNTNOTIFY.
1013	*/
1014	typedef struct PDMIMOUNT
1015	{
1016	/**
1017	* Mount a media.
1018	*
1019	* This will not unmount any currently mounted media!
1020	*
1021	* @returns VBox status code.
1022	* @param pInterface Pointer to the interface structure containing the called function pointer.
1023	* @param pszFilename Pointer to filename. If this is NULL it assumed that the caller have
1024	* constructed a configuration which can be attached to the bottom driver.
1025	* @param pszCoreDriver Core driver name. NULL will cause autodetection. Ignored if pszFilanem is NULL.
1026	* @thread The emulation thread.
1027	*/
1028	DECLR3CALLBACKMEMBER(int, pfnMount,(PPDMIMOUNT pInterface, const char pszFilename, const char pszCoreDriver));
1029
1030	/**
1031	* Unmount the media.
1032	*
1033	* The driver will validate and pass it on. On the rebounce it will decide whether or not to detach it self.
1034	*
1035	* @returns VBox status code.
1036	* @param pInterface Pointer to the interface structure containing the called function pointer.
1037	* @thread The emulation thread.
1038	*/
1039	DECLR3CALLBACKMEMBER(int, pfnUnmount,(PPDMIMOUNT pInterface));
1040
1041	/**
1042	* Checks if a media is mounted.
1043	*
1044	* @returns true if mounted.
1045	* @returns false if not mounted.
1046	* @param pInterface Pointer to the interface structure containing the called function pointer.
1047	* @thread Any thread.
1048	*/
1049	DECLR3CALLBACKMEMBER(bool, pfnIsMounted,(PPDMIMOUNT pInterface));
1050
1051	/**
1052	* Locks the media, preventing any unmounting of it.
1053	*
1054	* @returns VBox status code.
1055	* @param pInterface Pointer to the interface structure containing the called function pointer.
1056	* @thread The emulation thread.
1057	*/
1058	DECLR3CALLBACKMEMBER(int, pfnLock,(PPDMIMOUNT pInterface));
1059
1060	/**
1061	* Unlocks the media, canceling previous calls to pfnLock().
1062	*
1063	* @returns VBox status code.
1064	* @param pInterface Pointer to the interface structure containing the called function pointer.
1065	* @thread The emulation thread.
1066	*/
1067	DECLR3CALLBACKMEMBER(int, pfnUnlock,(PPDMIMOUNT pInterface));
1068
1069	/**
1070	* Checks if a media is locked.
1071	*
1072	* @returns true if locked.
1073	* @returns false if not locked.
1074	* @param pInterface Pointer to the interface structure containing the called function pointer.
1075	* @thread Any thread.
1076	*/
1077	DECLR3CALLBACKMEMBER(bool, pfnIsLocked,(PPDMIMOUNT pInterface));
1078	} PDMIBLOCKMOUNT;
1079
1080	/**
1081	* BIOS translation mode.
1082	*/
1083	typedef enum PDMBIOSTRANSLATION
1084	{
1085	/** No translation. */
1086	PDMBIOSTRANSLATION_NONE = 1,
1087	/** LBA translation. */
1088	PDMBIOSTRANSLATION_LBA,
1089	/** Automatic select mode. */
1090	PDMBIOSTRANSLATION_AUTO
1091	} PDMBIOSTRANSLATION;
1092
1093	/** Pointer to BIOS translation mode. */
1094	typedef PDMBIOSTRANSLATION *PPDMBIOSTRANSLATION;
1095
1096	/** Pointer to a media interface. */
1097	typedef struct PDMIMEDIA *PPDMIMEDIA;
1098	/**
1099	* Media interface.
1100	* Makes up the fundation for PDMIBLOCK and PDMIBLOCKBIOS.
1101	*/
1102	typedef struct PDMIMEDIA
1103	{
1104	/**
1105	* Read bits.
1106	*
1107	* @returns VBox status code.
1108	* @param pInterface Pointer to the interface structure containing the called function pointer.
1109	* @param off Offset to start reading from.
1110	* @param pvBuf Where to store the read bits.
1111	* @param cbRead Number of bytes to read.
1112	* @thread Any thread.
1113	*/
1114	DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMIMEDIA pInterface, uint64_t off, void *pvBuf, size_t cbRead));
1115
1116	/**
1117	* Write bits.
1118	*
1119	* @returns VBox status code.
1120	* @param pInterface Pointer to the interface structure containing the called function pointer.
1121	* @param off Offset to start writing at.
1122	* @param pvBuf Where to store the write bits.
1123	* @param cbWrite Number of bytes to write.
1124	* @thread Any thread.
1125	*/
1126	DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMIMEDIA pInterface, uint64_t off, const void *pvBuf, size_t cbWrite));
1127
1128	/**
1129	* Make sure that the bits written are actually on the storage medium.
1130	*
1131	* @returns VBox status code.
1132	* @param pInterface Pointer to the interface structure containing the called function pointer.
1133	* @thread Any thread.
1134	*/
1135	DECLR3CALLBACKMEMBER(int, pfnFlush,(PPDMIMEDIA pInterface));
1136
1137	/**
1138	* Get the media size in bytes.
1139	*
1140	* @returns Media size in bytes.
1141	* @param pInterface Pointer to the interface structure containing the called function pointer.
1142	* @thread Any thread.
1143	*/
1144	DECLR3CALLBACKMEMBER(uint64_t, pfnGetSize,(PPDMIMEDIA pInterface));
1145
1146	/**
1147	* Check if the media is readonly or not.
1148	*
1149	* @returns true if readonly.
1150	* @returns false if read/write.
1151	* @param pInterface Pointer to the interface structure containing the called function pointer.
1152	* @thread Any thread.
1153	*/
1154	DECLR3CALLBACKMEMBER(bool, pfnIsReadOnly,(PPDMIMEDIA pInterface));
1155
1156	/**
1157	* Get stored media geometry - BIOS property.
1158	* This is an optional feature of a media.
1159	*
1160	* @returns VBox status code.
1161	* @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
1162	* @returns VERR_PDM_GEOMETRY_NOT_SET if the geometry hasn't been set using pfnBiosSetGeometry() yet.
1163	* @param pInterface Pointer to the interface structure containing the called function pointer.
1164	* @param pcCylinders Number of cylinders.
1165	* @param pcHeads Number of heads.
1166	* @param pcSectors Number of sectors. This number is 1-based.
1167	* @remark This have no influence on the read/write operations.
1168	* @thread Any thread.
1169	*/
1170	DECLR3CALLBACKMEMBER(int, pfnBiosGetGeometry,(PPDMIMEDIA pInterface, uint32_t pcCylinders, uint32_t pcHeads, uint32_t *pcSectors));
1171
1172	/**
1173	* Store the media geometry - BIOS property.
1174	* This is an optional feature of a media.
1175	*
1176	* @returns VBox status code.
1177	* @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
1178	* @param pInterface Pointer to the interface structure containing the called function pointer.
1179	* @param cCylinders Number of cylinders.
1180	* @param cHeads Number of heads.
1181	* @param cSectors Number of sectors. This number is 1-based.
1182	* @remark This have no influence on the read/write operations.
1183	* @thread The emulation thread.
1184	*/
1185	DECLR3CALLBACKMEMBER(int, pfnBiosSetGeometry,(PPDMIMEDIA pInterface, uint32_t cCylinders, uint32_t cHeads, uint32_t cSectors));
1186
1187	/**
1188	* Get stored geometry translation mode - BIOS property.
1189	* This is an optional feature of a media.
1190	*
1191	* @returns VBox status code.
1192	* @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry translation mode.
1193	* @returns VERR_PDM_TRANSLATION_NOT_SET if the translation hasn't been set using pfnBiosSetTranslation() yet.
1194	* @param pInterface Pointer to the interface structure containing the called function pointer.
1195	* @param penmTranslation Where to store the translation type.
1196	* @remark This have no influence on the read/write operations.
1197	* @thread Any thread.
1198	*/
1199	DECLR3CALLBACKMEMBER(int, pfnBiosGetTranslation,(PPDMIMEDIA pInterface, PPDMBIOSTRANSLATION penmTranslation));
1200
1201	/**
1202	* Store media geometry - BIOS property.
1203	* This is an optional feature of a media.
1204	*
1205	* @returns VBox status code.
1206	* @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
1207	* @param pInterface Pointer to the interface structure containing the called function pointer.
1208	* @param enmTranslation The translation type.
1209	* @remark This have no influence on the read/write operations.
1210	* @thread The emulation thread.
1211	*/
1212	DECLR3CALLBACKMEMBER(int, pfnBiosSetTranslation,(PPDMIMEDIA pInterface, PDMBIOSTRANSLATION enmTranslation));
1213
1214	/**
1215	* Gets the UUID of the media drive.
1216	*
1217	* @returns VBox status code.
1218	* @param pInterface Pointer to the interface structure containing the called function pointer.
1219	* @param pUuid Where to store the UUID on success.
1220	* @thread Any thread.
1221	*/
1222	DECLR3CALLBACKMEMBER(int, pfnGetUuid,(PPDMIMEDIA pInterface, PRTUUID pUuid));
1223
1224	} PDMIMEDIA;
1225
1226
1227	/** Pointer to a block BIOS interface. */
1228	typedef struct PDMIBLOCKBIOS *PPDMIBLOCKBIOS;
1229	/**
1230	* Media BIOS interface.
1231	* The interface the getting and setting properties which the BIOS/CMOS care about.
1232	*/
1233	typedef struct PDMIBLOCKBIOS
1234	{
1235	/**
1236	* Get stored media geometry - BIOS property.
1237	* This is an optional feature of a media.
1238	*
1239	* @returns VBox status code.
1240	* @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
1241	* @param pInterface Pointer to the interface structure containing the called function pointer.
1242	* @param pcCylinders Number of cylinders.
1243	* @param pcHeads Number of heads.
1244	* @param pcSectors Number of sectors. This number is 1-based.
1245	* @remark This have no influence on the read/write operations.
1246	* @thread Any thread.
1247	*/
1248	DECLR3CALLBACKMEMBER(int, pfnGetGeometry,(PPDMIBLOCKBIOS pInterface, uint32_t pcCylinders, uint32_t pcHeads, uint32_t *pcSectors));
1249
1250	/**
1251	* Store the media geometry - BIOS property.
1252	* This is an optional feature of a media.
1253	*
1254	* @returns VBox status code.
1255	* @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
1256	* @param pInterface Pointer to the interface structure containing the called function pointer.
1257	* @param cCylinders Number of cylinders.
1258	* @param cHeads Number of heads.
1259	* @param cSectors Number of sectors. This number is 1-based.
1260	* @remark This have no influence on the read/write operations.
1261	* @thread The emulation thread.
1262	*/
1263	DECLR3CALLBACKMEMBER(int, pfnSetGeometry,(PPDMIBLOCKBIOS pInterface, uint32_t cCylinders, uint32_t cHeads, uint32_t cSectors));
1264
1265	/**
1266	* Get stored geometry translation mode - BIOS property.
1267	* This is an optional feature of a media.
1268	*
1269	* @returns VBox status code.
1270	* @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry translation mode.
1271	* @param pInterface Pointer to the interface structure containing the called function pointer.
1272	* @param penmTranslation Where to store the translation type.
1273	* @remark This have no influence on the read/write operations.
1274	* @thread Any thread.
1275	*/
1276	DECLR3CALLBACKMEMBER(int, pfnGetTranslation,(PPDMIBLOCKBIOS pInterface, PPDMBIOSTRANSLATION penmTranslation));
1277
1278	/**
1279	* Store media geometry - BIOS property.
1280	* This is an optional feature of a media.
1281	*
1282	* @returns VBox status code.
1283	* @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
1284	* @param pInterface Pointer to the interface structure containing the called function pointer.
1285	* @param enmTranslation The translation type.
1286	* @remark This have no influence on the read/write operations.
1287	* @thread The emulation thread.
1288	*/
1289	DECLR3CALLBACKMEMBER(int, pfnSetTranslation,(PPDMIBLOCKBIOS pInterface, PDMBIOSTRANSLATION enmTranslation));
1290
1291	/**
1292	* Checks if the device should be visible to the BIOS or not.
1293	*
1294	* @returns true if the device is visible to the BIOS.
1295	* @returns false if the device is not visible to the BIOS.
1296	* @param pInterface Pointer to the interface structure containing the called function pointer.
1297	* @thread Any thread.
1298	*/
1299	DECLR3CALLBACKMEMBER(bool, pfnIsVisible,(PPDMIBLOCKBIOS pInterface));
1300
1301	/**
1302	* Gets the block drive type.
1303	*
1304	* @returns block drive type.
1305	* @param pInterface Pointer to the interface structure containing the called function pointer.
1306	* @thread Any thread.
1307	*/
1308	DECLR3CALLBACKMEMBER(PDMBLOCKTYPE, pfnGetType,(PPDMIBLOCKBIOS pInterface));
1309
1310	} PDMIBLOCKBIOS;
1311
1312
1313	/** Pointer to a static block core driver interface. */
1314	typedef struct PDMIMEDIASTATIC *PPDMIMEDIASTATIC;
1315	/**
1316	* Static block core driver interface.
1317	*/
1318	typedef struct PDMIMEDIASTATIC
1319	{
1320	/**
1321	* Check if the specified file is a format which the core driver can handle.
1322	*
1323	* @returns true / false accordingly.
1324	* @param pInterface Pointer to the interface structure containing the called function pointer.
1325	* @param pszFilename Name of the file to probe.
1326	*/
1327	DECLR3CALLBACKMEMBER(bool, pfnCanHandle,(PPDMIMEDIASTATIC pInterface, const char *pszFilename));
1328	} PDMIMEDIASTATIC;
1329
1330
1331	/** Pointer to an iSCSI Request PDU buffer. */
1332	typedef struct ISCSIREQ *PISCSIREQ;
1333	/**
1334	* iSCSI Request PDU buffer (gather).
1335	*/
1336	typedef struct ISCSIREQ
1337	{
1338	/** Length of PDU segment in bytes. */
1339	size_t cbSeg;
1340	/** Pointer to PDU segment. */
1341	const void *pcvSeg;
1342	} ISCSIREQ;
1343
1344	/** Pointer to an iSCSI Response PDU buffer. */
1345	typedef struct ISCSIRES *PISCSIRES;
1346	/**
1347	* iSCSI Response PDU buffer (scatter).
1348	*/
1349	typedef struct ISCSIRES
1350	{
1351	/** Length of PDU segment. */
1352	size_t cbSeg;
1353	/** Pointer to PDU segment. */
1354	void *pvSeg;
1355	} ISCSIRES;
1356
1357	/** Pointer to an iSCSI transport driver interface. */
1358	typedef struct PDMIISCSITRANSPORT *PPDMIISCSITRANSPORT;
1359	/**
1360	* iSCSI transport driver interface.
1361	*/
1362	typedef struct PDMIISCSITRANSPORT
1363	{
1364	/**
1365	* Read bytes from an iSCSI transport stream. If the connection fails, it is automatically
1366	* reopened on the next call after the error is signalled. Error recovery in this case is
1367	* the duty of the caller.
1368	*
1369	* @returns VBox status code.
1370	* @param pTransport Pointer to the interface structure containing the called function pointer.
1371	* @param pvBuf Where to store the read bits.
1372	* @param cbBuf Number of bytes to read.
1373	* @param pcbRead Actual number of bytes read.
1374	* @thread Any thread.
1375	* @todo Correct the docs.
1376	*/
1377	DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMIISCSITRANSPORT pTransport, PISCSIRES prgResponse, unsigned int cnResponse));
1378
1379	/**
1380	* Write bytes to an iSCSI transport stream. Padding is performed when necessary. If the connection
1381	* fails, it is automatically reopened on the next call after the error is signalled. Error recovery
1382	* in this case is the duty of the caller.
1383	*
1384	* @returns VBox status code.
1385	* @param pTransport Pointer to the interface structure containing the called function pointer.
1386	* @param pvBuf Where the write bits are stored.
1387	* @param cbWrite Number of bytes to write.
1388	* @thread Any thread.
1389	* @todo Correct the docs.
1390	*/
1391	DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMIISCSITRANSPORT pTransport, PISCSIREQ prgRequest, unsigned int cnRequest));
1392
1393	/**
1394	* Open the iSCSI transport stream.
1395	*
1396	* @returns VBox status code.
1397	* @param pTransport Pointer to the interface structure containing the called function pointer.
1398	* @param pszTargetAddress Pointer to string of the format address:port.
1399	* @thread Any thread.
1400	*/
1401	DECLR3CALLBACKMEMBER(int, pfnOpen,(PPDMIISCSITRANSPORT pTransport, const char *pszTargetAddress));
1402
1403	/**
1404	* Close the iSCSI transport stream.
1405	*
1406	* @returns VBox status code.
1407	* @param pTransport Pointer to the interface structure containing the called function pointer.
1408	* @thread Any thread.
1409	*/
1410	DECLR3CALLBACKMEMBER(int, pfnClose,(PPDMIISCSITRANSPORT pTransport));
1411	} PDMIISCSITRANSPORT;
1412
1413
1414	/** ACPI power source identifier */
1415	typedef enum PDMACPIPOWERSOURCE
1416	{
1417	PDM_ACPI_POWER_SOURCE_UNKNOWN = 0,
1418	PDM_ACPI_POWER_SOURCE_OUTLET,
1419	PDM_ACPI_POWER_SOURCE_BATTERY
1420	} PDMACPIPOWERSOURCE;
1421	/** Pointer to ACPI battery state. */
1422	typedef PDMACPIPOWERSOURCE *PPDMACPIPOWERSOURCE;
1423
1424	/** ACPI battey capacity */
1425	typedef enum PDMACPIBATCAPACITY
1426	{
1427	PDM_ACPI_BAT_CAPACITY_MIN = 0,
1428	PDM_ACPI_BAT_CAPACITY_MAX = 100,
1429	PDM_ACPI_BAT_CAPACITY_UNKNOWN = 255
1430	} PDMACPIBATCAPACITY;
1431	/** Pointer to ACPI battery capacity. */
1432	typedef PDMACPIBATCAPACITY *PPDMACPIBATCAPACITY;
1433
1434	/** ACPI battery state. See ACPI 3.0 spec '_BST (Battery Status)' */
1435	typedef enum PDMACPIBATSTATE
1436	{
1437	PDM_ACPI_BAT_STATE_CHARGED = 0x00,
1438	PDM_ACPI_BAT_STATE_CHARGING = 0x01,
1439	PDM_ACPI_BAT_STATE_DISCHARGING = 0x02,
1440	PDM_ACPI_BAT_STATE_CRITICAL = 0x04
1441	} PDMACPIBATSTATE;
1442	/** Pointer to ACPI battery state. */
1443	typedef PDMACPIBATSTATE *PPDMACPIBATSTATE;
1444
1445	/** Pointer to an ACPI port interface. */
1446	typedef struct PDMIACPIPORT *PPDMIACPIPORT;
1447	/**
1448	* ACPI port interface.
1449	*/
1450	typedef struct PDMIACPIPORT
1451	{
1452	/**
1453	* Send an ACPI power off event.
1454	*
1455	* @returns VBox status code
1456	* @param pInterface Pointer to the interface structure containing the called function pointer.
1457	*/
1458	DECLR3CALLBACKMEMBER(int, pfnPowerButtonPress,(PPDMIACPIPORT pInterface));
1459	} PDMIACPIPORT;
1460
1461	/** Pointer to an ACPI connector interface. */
1462	typedef struct PDMIACPICONNECTOR *PPDMIACPICONNECTOR;
1463	/**
1464	* ACPI connector interface.
1465	*/
1466	typedef struct PDMIACPICONNECTOR
1467	{
1468	/**
1469	* Get the current power source of the host system.
1470	*
1471	* @returns VBox status code
1472	* @param pInterface Pointer to the interface structure containing the called function pointer.
1473	* @param penmPowerSource Pointer to the power source result variable.
1474	*/
1475	DECLR3CALLBACKMEMBER(int, pfnQueryPowerSource,(PPDMIACPICONNECTOR, PPDMACPIPOWERSOURCE penmPowerSource));
1476
1477	/**
1478	* Query the current battery status of the host system.
1479	*
1480	* @returns VBox status code?
1481	* @param pInterface Pointer to the interface structure containing the called function pointer.
1482	* @param pfPresent Is set to true if battery is present, false otherwise.
1483	* @param penmRemainingCapacity Pointer to the battery remaining capacity (0 - 100 or 255 for unknown).
1484	* @param penmBatteryState Pointer to the battery status.
1485	* @param pu32PresentRate Pointer to the present rate (0..1000 of the total capacity).
1486	*/
1487	DECLR3CALLBACKMEMBER(int, pfnQueryBatteryStatus,(PPDMIACPICONNECTOR, bool *pfPresent, PPDMACPIBATCAPACITY penmRemainingCapacity,
1488	PPDMACPIBATSTATE penmBatteryState, uint32_t *pu32PresentRate));
1489	} PDMIACPICONNECTOR;
1490
1491	/** Pointer to a VMMDevice port interface. */
1492	typedef struct PDMIVMMDEVPORT *PPDMIVMMDEVPORT;
1493	/**
1494	* VMMDevice port interface.
1495	*/
1496	typedef struct PDMIVMMDEVPORT
1497	{
1498	/**
1499	* Return the current absolute mouse position in pixels
1500	*
1501	* @returns VBox status code
1502	* @param pAbsX Pointer of result value, can be NULL
1503	* @param pAbsY Pointer of result value, can be NULL
1504	*/
1505	DECLR3CALLBACKMEMBER(int, pfnQueryAbsoluteMouse,(PPDMIVMMDEVPORT pInterface, uint32_t pAbsX, uint32_t pAbsY));
1506
1507	/**
1508	* Set the new absolute mouse position in pixels
1509	*
1510	* @returns VBox status code
1511	* @param absX New absolute X position
1512	* @param absY New absolute Y position
1513	*/
1514	DECLR3CALLBACKMEMBER(int, pfnSetAbsoluteMouse,(PPDMIVMMDEVPORT pInterface, uint32_t absX, uint32_t absY));
1515
1516	/**
1517	* Return the current mouse capability flags
1518	*
1519	* @returns VBox status code
1520	* @param pCapabilities Pointer of result value
1521	*/
1522	DECLR3CALLBACKMEMBER(int, pfnQueryMouseCapabilities,(PPDMIVMMDEVPORT pInterface, uint32_t *pCapabilities));
1523
1524	/**
1525	* Set the current mouse capability flag (host side)
1526	*
1527	* @returns VBox status code
1528	* @param capabilities Capability mask
1529	*/
1530	DECLR3CALLBACKMEMBER(int, pfnSetMouseCapabilities,(PPDMIVMMDEVPORT pInterface, uint32_t capabilities));
1531
1532	/**
1533	* Issue a display resolution change request.
1534	*
1535	* Note that there can only one request in the queue and that in case the guest does
1536	* not process it, issuing another request will overwrite the previous.
1537	*
1538	* @returns VBox status code
1539	* @param cx Horizontal pixel resolution (0 = do not change).
1540	* @param cy Vertical pixel resolution (0 = do not change).
1541	* @param cBits Bits per pixel (0 = do not change).
1542	*/
1543	DECLR3CALLBACKMEMBER(int, pfnRequestDisplayChange,(PPDMIVMMDEVPORT pInterface, uint32_t cx, uint32_t cy, uint32_t cBits));
1544
1545	/**
1546	* Pass credentials to guest.
1547	*
1548	* Note that there can only be one set of credentials and the guest may or may not
1549	* query them and may do whatever it wants with them.
1550	*
1551	* @returns VBox status code
1552	* @param pszUsername User name, may be empty (UTF-8)
1553	* @param pszPassword Password, may be empty (UTF-8)
1554	* @param pszDomain Domain name, may be empty (UTF-8)
1555	* @param fFlags Bitflags
1556	*/
1557	DECLR3CALLBACKMEMBER(int, pfnSetCredentials,(PPDMIVMMDEVPORT pInterface, const char *pszUsername,
1558	const char pszPassword, const char pszDomain,
1559	uint32_t fFlags));
1560
1561	/**
1562	* Notify the driver about a VBVA status change.
1563	*
1564	* @returns Nothing. Because it is informational callback.
1565	* @param fEnabled Current VBVA status.
1566	*/
1567	DECLCALLBACKMEMBER(void, pfnVBVAChange)(PPDMIVMMDEVPORT pInterface, bool fEnabled);
1568
1569	} PDMIVMMDEVPORT;
1570
1571	/** Forward declaration of video accelerator command memory. */
1572	struct _VBVAMEMORY;
1573	/** Pointer to video accelerator command memory. */
1574	typedef struct _VBVAMEMORY *PVBVAMEMORY;
1575
1576	/** Pointer to a VMMDev connector interface. */
1577	typedef struct PDMIVMMDEVCONNECTOR *PPDMIVMMDEVCONNECTOR;
1578	/**
1579	* VMMDev connector interface.
1580	* Pair with PDMIVMMDEVPORT.
1581	*/
1582	typedef struct PDMIVMMDEVCONNECTOR
1583	{
1584	/**
1585	* Report guest OS version.
1586	* Called whenever the Additions issue a guest version report request.
1587	*
1588	* @param pInterface Pointer to this interface.
1589	* @param pGuestInfo Pointer to guest information structure
1590	* @thread The emulation thread.
1591	*/
1592	DECLR3CALLBACKMEMBER(void, pfnUpdateGuestVersion,(PPDMIVMMDEVCONNECTOR pInterface, VBoxGuestInfo *pGuestInfo));
1593
1594	/**
1595	* Update the mouse capabilities.
1596	* This is called when the mouse capabilities change. The new capabilities
1597	* are given and the connector should update its internal state.
1598	*
1599	* @param pInterface Pointer to this interface.
1600	* @param newCapabilities New capabilities.
1601	* @thread The emulation thread.
1602	*/
1603	DECLR3CALLBACKMEMBER(void, pfnUpdateMouseCapabilities,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t newCapabilities));
1604
1605	/**
1606	* Update the pointer shape.
1607	* This is called when the mouse pointer shape changes. The new shape
1608	* is passed as a caller allocated buffer that will be freed after returning
1609	*
1610	* @param pInterface Pointer to this interface.
1611	* @param fVisible Visibility indicator (if false, the other parameters are undefined).
1612	* @param fAlpha Flag whether alpha channel is being passed.
1613	* @param xHot Pointer hot spot x coordinate.
1614	* @param yHot Pointer hot spot y coordinate.
1615	* @param x Pointer new x coordinate on screen.
1616	* @param y Pointer new y coordinate on screen.
1617	* @param cx Pointer width in pixels.
1618	* @param cy Pointer height in pixels.
1619	* @param cbScanline Size of one scanline in bytes.
1620	* @param pvShape New shape buffer.
1621	* @thread The emulation thread.
1622	*/
1623	DECLR3CALLBACKMEMBER(void, pfnUpdatePointerShape,(PPDMIVMMDEVCONNECTOR pInterface, bool fVisible, bool fAlpha,
1624	uint32_t xHot, uint32_t yHot,
1625	uint32_t cx, uint32_t cy,
1626	void *pvShape));
1627
1628	/**
1629	* Enable or disable video acceleration on behalf of guest.
1630	*
1631	* @param pInterface Pointer to this interface.
1632	* @param fEnable Whether to enable acceleration.
1633	* @param pVbvaMemory Video accelerator memory.
1634
1635	* @return VBox rc. VINF_SUCCESS if VBVA was enabled.
1636	* @thread The emulation thread.
1637	*/
1638	DECLR3CALLBACKMEMBER(int, pfnVideoAccelEnable,(PPDMIVMMDEVCONNECTOR pInterface, bool fEnable, PVBVAMEMORY pVbvaMemory));
1639
1640	/**
1641	* Force video queue processing.
1642	*
1643	* @param pInterface Pointer to this interface.
1644	* @thread The emulation thread.
1645	*/
1646	DECLR3CALLBACKMEMBER(void, pfnVideoAccelFlush,(PPDMIVMMDEVCONNECTOR pInterface));
1647
1648	/**
1649	* Return whether the given video mode is supported/wanted by the host.
1650	*
1651	* @returns VBox status code
1652	* @param pInterface Pointer to this interface.
1653	* @param cy Video mode horizontal resolution in pixels.
1654	* @param cx Video mode vertical resolution in pixels.
1655	* @param cBits Video mode bits per pixel.
1656	* @param pfSupported Where to put the indicator for whether this mode is supported. (output)
1657	* @thread The emulation thread.
1658	*/
1659	DECLR3CALLBACKMEMBER(int, pfnVideoModeSupported,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t cx, uint32_t cy, uint32_t cBits, bool *pfSupported));
1660
1661	/**
1662	* Queries by how many pixels the height should be reduced when calculating video modes
1663	*
1664	* @returns VBox status code
1665	* @param pInterface Pointer to this interface.
1666	* @param pcyReduction Pointer to the result value.
1667	* @thread The emulation thread.
1668	*/
1669	DECLR3CALLBACKMEMBER(int, pfnGetHeightReduction,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t *pcyReduction));
1670
1671	/**
1672	* Informs about a credentials judgement result from the guest.
1673	*
1674	* @returns VBox status code
1675	* @param pInterface Pointer to this interface.
1676	* @param fFlags Judgement result flags.
1677	* @thread The emulation thread.
1678	*/
1679	DECLR3CALLBACKMEMBER(int, pfnSetCredentialsJudgementResult,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t fFlags));
1680	} PDMIVMMDEVCONNECTOR;
1681
1682
1683	/**
1684	* MAC address.
1685	* (The first 24 bits are the 'company id', where the first bit seems to have a special meaning if set.)
1686	*/
1687	typedef union PDMMAC
1688	{
1689	/** 8-bit view. */
1690	uint8_t au8[6];
1691	/** 16-bit view. */
1692	uint16_t au16[3];
1693	} PDMMAC;
1694	/** Pointer to a MAC address. */
1695	typedef PDMMAC *PPDMMAC;
1696	/** Pointer to a const MAC address. */
1697	typedef const PDMMAC *PCPDMMAC;
1698
1699
1700	/** Pointer to a network port interface */
1701	typedef struct PDMINETWORKPORT *PPDMINETWORKPORT;
1702	/**
1703	* Network port interface.
1704	*/
1705	typedef struct PDMINETWORKPORT
1706	{
1707	/**
1708	* Check how much data the device/driver can receive data now.
1709	* This must be called before the pfnRecieve() method is called.
1710	*
1711	* @returns Number of bytes the device can receive now.
1712	* @param pInterface Pointer to the interface structure containing the called function pointer.
1713	* @thread EMT
1714	*/
1715	DECLR3CALLBACKMEMBER(size_t, pfnCanReceive,(PPDMINETWORKPORT pInterface));
1716
1717	/**
1718	* Receive data from the network.
1719	*
1720	* @returns VBox status code.
1721	* @param pInterface Pointer to the interface structure containing the called function pointer.
1722	* @param pvBuf The available data.
1723	* @param cb Number of bytes available in the buffer.
1724	* @thread EMT
1725	*/
1726	DECLR3CALLBACKMEMBER(int, pfnReceive,(PPDMINETWORKPORT pInterface, const void *pvBuf, size_t cb));
1727
1728	} PDMINETWORKPORT;
1729
1730
1731	/**
1732	* Network link state.
1733	*/
1734	typedef enum PDMNETWORKLINKSTATE
1735	{
1736	/** Invalid state. */
1737	PDMNETWORKLINKSTATE_INVALID = 0,
1738	/** The link is up. */
1739	PDMNETWORKLINKSTATE_UP,
1740	/** The link is down. */
1741	PDMNETWORKLINKSTATE_DOWN,
1742	/** The link is temporarily down while resuming. */
1743	PDMNETWORKLINKSTATE_DOWN_RESUME
1744	} PDMNETWORKLINKSTATE;
1745
1746	/** Pointer to a network connector interface */
1747	typedef struct PDMINETWORKCONNECTOR *PPDMINETWORKCONNECTOR;
1748	/**
1749	* Network connector interface.
1750	*/
1751	typedef struct PDMINETWORKCONNECTOR
1752	{
1753	/**
1754	* Send data to the network.
1755	*
1756	* @returns VBox status code.
1757	* @param pInterface Pointer to the interface structure containing the called function pointer.
1758	* @param pvBuf Data to send.
1759	* @param cb Number of bytes to send.
1760	* @thread EMT
1761	*/
1762	DECLR3CALLBACKMEMBER(int, pfnSend,(PPDMINETWORKCONNECTOR pInterface, const void *pvBuf, size_t cb));
1763
1764	/**
1765	* Set promiscuous mode.
1766	*
1767	* This is called when the promiscuous mode is set. This means that there doesn't have
1768	* to be a mode change when it's called.
1769	*
1770	* @param pInterface Pointer to the interface structure containing the called function pointer.
1771	* @param fPromiscuous Set if the adaptor is now in promiscuous mode. Clear if it is not.
1772	* @thread EMT
1773	*/
1774	DECLR3CALLBACKMEMBER(void, pfnSetPromiscuousMode,(PPDMINETWORKCONNECTOR pInterface, bool fPromiscuous));
1775
1776	/**
1777	* Notification on link status changes.
1778	*
1779	* @param pInterface Pointer to the interface structure containing the called function pointer.
1780	* @param enmLinkState The new link state.
1781	* @thread EMT
1782	*/
1783	DECLR3CALLBACKMEMBER(void, pfnNotifyLinkChanged,(PPDMINETWORKCONNECTOR pInterface, PDMNETWORKLINKSTATE enmLinkState));
1784
1785	/**
1786	* More receive buffer has become available.
1787	*
1788	* This is called when the NIC frees up receive buffers.
1789	*
1790	* @param pInterface Pointer to the interface structure containing the called function pointer.
1791	* @remark This function isn't called by pcnet nor yet.
1792	* @thread EMT
1793	*/
1794	DECLR3CALLBACKMEMBER(void, pfnNotifyCanReceive,(PPDMINETWORKCONNECTOR pInterface));
1795
1796	} PDMINETWORKCONNECTOR;
1797
1798
1799	/** Pointer to a network config port interface */
1800	typedef struct PDMINETWORKCONFIG *PPDMINETWORKCONFIG;
1801	/**
1802	* Network config port interface.
1803	*/
1804	typedef struct PDMINETWORKCONFIG
1805	{
1806	/**
1807	* Gets the current Media Access Control (MAC) address.
1808	*
1809	* @returns VBox status code.
1810	* @param pInterface Pointer to the interface structure containing the called function pointer.
1811	* @param pMac Where to store the MAC address.
1812	* @thread EMT
1813	*/
1814	DECLR3CALLBACKMEMBER(int, pfnGetMac,(PPDMINETWORKCONFIG pInterface, PPDMMAC *pMac));
1815
1816	/**
1817	* Gets the new link state.
1818	*
1819	* @returns The current link state.
1820	* @param pInterface Pointer to the interface structure containing the called function pointer.
1821	* @thread EMT
1822	*/
1823	DECLR3CALLBACKMEMBER(PDMNETWORKLINKSTATE, pfnGetLinkState,(PPDMINETWORKCONFIG pInterface));
1824
1825	/**
1826	* Sets the new link state.
1827	*
1828	* @returns VBox status code.
1829	* @param pInterface Pointer to the interface structure containing the called function pointer.
1830	* @param enmState The new link state
1831	* @thread EMT
1832	*/
1833	DECLR3CALLBACKMEMBER(int, pfnSetLinkState,(PPDMINETWORKCONFIG pInterface, PDMNETWORKLINKSTATE enmState));
1834
1835	} PDMINETWORKCONFIG;
1836
1837
1838	/** Pointer to a network connector interface */
1839	typedef struct PDMIAUDIOCONNECTOR *PPDMIAUDIOCONNECTOR;
1840	/**
1841	* Audio connector interface.
1842	*/
1843	typedef struct PDMIAUDIOCONNECTOR
1844	{
1845	DECLR3CALLBACKMEMBER(void, pfnRun,(PPDMIAUDIOCONNECTOR pInterface));
1846
1847	/* DECLR3CALLBACKMEMBER(int, pfnSetRecordSource,(PPDMIAUDIOINCONNECTOR pInterface, AUDIORECSOURCE)); */
1848
1849	} PDMIAUDIOCONNECTOR;
1850
1851
1852	/** @todo r=bird: the two following interfaces are hacks to work around the missing audio driver
1853	* interface. This should be addressed rather than making more temporary hacks. */
1854
1855	/** Pointer to a Audio Sniffer Device port interface. */
1856	typedef struct PDMIAUDIOSNIFFERPORT *PPDMIAUDIOSNIFFERPORT;
1857
1858	/**
1859	* Audio Sniffer port interface.
1860	*/
1861	typedef struct PDMIAUDIOSNIFFERPORT
1862	{
1863	/**
1864	* Enables or disables sniffing. If sniffing is being enabled also sets a flag
1865	* whether the audio must be also left on the host.
1866	*
1867	* @returns VBox status code
1868	* @param pInterface Pointer to this interface.
1869	* @param fEnable 'true' for enable sniffing, 'false' to disable.
1870	* @param fKeepHostAudio Indicates whether host audio should also present
1871	* 'true' means that sound should not be played
1872	* by the audio device.
1873	*/
1874	DECLR3CALLBACKMEMBER(int, pfnSetup,(PPDMIAUDIOSNIFFERPORT pInterface, bool fEnable, bool fKeepHostAudio));
1875
1876	} PDMIAUDIOSNIFFERPORT;
1877
1878	/** Pointer to a Audio Sniffer connector interface. */
1879	typedef struct PDMIAUDIOSNIFFERCONNECTOR *PPDMIAUDIOSNIFFERCONNECTOR;
1880
1881	/**
1882	* Audio Sniffer connector interface.
1883	* Pair with PDMIAUDIOSNIFFERPORT.
1884	*/
1885	typedef struct PDMIAUDIOSNIFFERCONNECTOR
1886	{
1887	/**
1888	* AudioSniffer device calls this method when audio samples
1889	* are about to be played and sniffing is enabled.
1890	*
1891	* @param pInterface Pointer to this interface.
1892	* @param pvSamples Audio samples buffer.
1893	* @param cSamples How many complete samples are in the buffer.
1894	* @param iSampleHz The sample frequency in Hz.
1895	* @param cChannels Number of channels. 1 for mono, 2 for stereo.
1896	* @param cBits How many bits a sample for a single channel has. Normally 8 or 16.
1897	* @param fUnsigned Whether samples are unsigned values.
1898	* @thread The emulation thread.
1899	*/
1900	DECLR3CALLBACKMEMBER(void, pfnAudioSamplesOut,(PPDMIAUDIOSNIFFERCONNECTOR pInterface, void *pvSamples, uint32_t cSamples,
1901	int iSampleHz, int cChannels, int cBits, bool fUnsigned));
1902
1903	/**
1904	* AudioSniffer device calls this method when output volume is changed.
1905	*
1906	* @param pInterface Pointer to this interface.
1907	* @param u16LeftVolume 0..0xFFFF volume level for left channel.
1908	* @param u16RightVolume 0..0xFFFF volume level for right channel.
1909	* @thread The emulation thread.
1910	*/
1911	DECLR3CALLBACKMEMBER(void, pfnAudioVolumeOut,(PPDMIAUDIOSNIFFERCONNECTOR pInterface, uint16_t u16LeftVolume, uint16_t u16RightVolume));
1912
1913	} PDMIAUDIOSNIFFERCONNECTOR;
1914
1915
1916	/**
1917	* Generic status LED core.
1918	* Note that a unit doesn't have to support all the indicators.
1919	*/
1920	typedef union PDMLEDCORE
1921	{
1922	/** 32-bit view. */
1923	uint32_t volatile u32;
1924	/** Bit view. */
1925	struct
1926	{
1927	/** Reading/Receiving indicator. */
1928	uint32_t fReading : 1;
1929	/** Writing/Sending indicator. */
1930	uint32_t fWriting : 1;
1931	/** Busy indicator. */
1932	uint32_t fBusy : 1;
1933	/** Error indicator. */
1934	uint32_t fError : 1;
1935	} s;
1936	} PDMLEDCORE;
1937
1938	/** LED bit masks for the u32 view.
1939	* @{ */
1940	/** Reading/Receiving indicator. */
1941	#define PDMLED_READING BIT(0)
1942	/** Writing/Sending indicator. */
1943	#define PDMLED_WRITING BIT(1)
1944	/** Busy indicator. */
1945	#define PDMLED_BUSY BIT(2)
1946	/** Error indicator. */
1947	#define PDMLED_ERROR BIT(3)
1948	/** @} */
1949
1950
1951	/**
1952	* Generic status LED.
1953	* Note that a unit doesn't have to support all the indicators.
1954	*/
1955	typedef struct PDMLED
1956	{
1957	/** Just a magic for sanity checking. */
1958	uint32_t u32Magic;
1959	uint32_t u32Alignment; /*< structure size alignment. /
1960	/** The actual LED status.
1961	* Only the device is allowed to change this. */
1962	PDMLEDCORE Actual;
1963	/** The asserted LED status which is cleared by the reader.
1964	* The device will assert the bits but never clear them.
1965	* The driver clears them as it sees fit. */
1966	PDMLEDCORE Asserted;
1967	} PDMLED;
1968
1969	/** Pointer to an LED. */
1970	typedef PDMLED *PPDMLED;
1971	/** Pointer to a const LED. */
1972	typedef const PDMLED *PCPDMLED;
1973
1974	#define PDMLED_MAGIC ( 0x11335577 )
1975
1976	/** Pointer to an LED ports interface. */
1977	typedef struct PDMILEDPORTS *PPDMILEDPORTS;
1978	/**
1979	* Interface for exporting LEDs.
1980	*/
1981	typedef struct PDMILEDPORTS
1982	{
1983	/**
1984	* Gets the pointer to the status LED of a unit.
1985	*
1986	* @returns VBox status code.
1987	* @param pInterface Pointer to the interface structure containing the called function pointer.
1988	* @param iLUN The unit which status LED we desire.
1989	* @param ppLed Where to store the LED pointer.
1990	*/
1991	DECLR3CALLBACKMEMBER(int, pfnQueryStatusLed,(PPDMILEDPORTS pInterface, unsigned iLUN, PPDMLED *ppLed));
1992
1993	} PDMILEDPORTS;
1994
1995
1996	/** Pointer to an LED connectors interface. */
1997	typedef struct PDMILEDCONNECTORS *PPDMILEDCONNECTORS;
1998	/**
1999	* Interface for reading LEDs.
2000	*/
2001	typedef struct PDMILEDCONNECTORS
2002	{
2003	/**
2004	* Notification about a unit which have been changed.
2005	*
2006	* The driver must discard any pointers to data owned by
2007	* the unit and requery it.
2008	*
2009	* @param pInterface Pointer to the interface structure containing the called function pointer.
2010	* @param iLUN The unit number.
2011	*/
2012	DECLR3CALLBACKMEMBER(void, pfnUnitChanged,(PPDMILEDCONNECTORS pInterface, unsigned iLUN));
2013	} PDMILEDCONNECTORS;
2014
2015
2016	/** The special status unit number */
2017	#define PDM_STATUS_LUN 999
2018
2019
2020	#ifdef VBOX_HGCM
2021
2022	/** Abstract HGCM command structure. Used only to define a typed pointer. */
2023	struct VBOXHGCMCMD;
2024
2025	/** Pointer to HGCM command structure. This pointer is unique and identifies
2026	* the command being processed. The pointer is passed to HGCM connector methods,
2027	* and must be passed back to HGCM port when command is completed.
2028	*/
2029	typedef struct VBOXHGCMCMD *PVBOXHGCMCMD;
2030
2031	/** Pointer to a HGCM port interface. */
2032	typedef struct PDMIHGCMPORT *PPDMIHGCMPORT;
2033
2034	/**
2035	* HGCM port interface. Normally implemented by VMMDev.
2036	*/
2037	typedef struct PDMIHGCMPORT
2038	{
2039	/**
2040	* Notify the guest on a command completion.
2041	*
2042	* @param pInterface Pointer to this interface.
2043	* @param rc The return code (VBox error code).
2044	* @param pCmd A pointer that identifies the completed command.
2045	*
2046	* @returns VBox status code
2047	*/
2048	DECLR3CALLBACKMEMBER(void, pfnCompleted,(PPDMIHGCMPORT pInterface, int32_t rc, PVBOXHGCMCMD pCmd));
2049
2050	} PDMIHGCMPORT;
2051
2052
2053	/** Pointer to a HGCM connector interface. */
2054	typedef struct PDMIHGCMCONNECTOR *PPDMIHGCMCONNECTOR;
2055
2056	/** Pointer to a HGCM function parameter. */
2057	typedef struct VBOXHGCMSVCPARM *PVBOXHGCMSVCPARM;
2058
2059	/** Pointer to a HGCM service location structure. */
2060	typedef struct HGCMSERVICELOCATION *PHGCMSERVICELOCATION;
2061
2062	/**
2063	* HGCM connector interface.
2064	* Pair with PDMIHGCMPORT.
2065	*/
2066	typedef struct PDMIHGCMCONNECTOR
2067	{
2068	/**
2069	* Locate a service and inform it about a client connection.
2070	*
2071	* @param pInterface Pointer to this interface.
2072	* @param pCmd A pointer that identifies the command.
2073	* @param pServiceLocation Pointer to the service location structure.
2074	* @param pu32ClientID Where to store the client id for the connection.
2075	* @return VBox status code.
2076	* @thread The emulation thread.
2077	*/
2078	DECLR3CALLBACKMEMBER(int, pfnConnect,(PPDMIHGCMCONNECTOR pInterface, PVBOXHGCMCMD pCmd, PHGCMSERVICELOCATION pServiceLocation, uint32_t *pu32ClientID));
2079
2080	/**
2081	* Disconnect from service.
2082	*
2083	* @param pInterface Pointer to this interface.
2084	* @param pCmd A pointer that identifies the command.
2085	* @param u32ClientID The client id returned by the pfnConnect call.
2086	* @return VBox status code.
2087	* @thread The emulation thread.
2088	*/
2089	DECLR3CALLBACKMEMBER(int, pfnDisconnect,(PPDMIHGCMCONNECTOR pInterface, PVBOXHGCMCMD pCmd, uint32_t u32ClientID));
2090
2091	/**
2092	* Process a guest issued command.
2093	*
2094	* @param pInterface Pointer to this interface.
2095	* @param pCmd A pointer that identifies the command.
2096	* @param u32ClientID The client id returned by the pfnConnect call.
2097	* @param u32Function Function to be performed by the service.
2098	* @param cParms Number of parameters in the array pointed to by paParams.
2099	* @param paParms Pointer to an array of parameters.
2100	* @return VBox status code.
2101	* @thread The emulation thread.
2102	*/
2103	DECLR3CALLBACKMEMBER(int, pfnCall,(PPDMIHGCMCONNECTOR pInterface, PVBOXHGCMCMD pCmd, uint32_t u32ClientID, uint32_t u32Function,
2104	uint32_t cParms, PVBOXHGCMSVCPARM paParms));
2105
2106	} PDMIHGCMCONNECTOR;
2107
2108	#endif
2109
2110	/** @} */
2111
2112
2113	/** @defgroup grp_pdm_driver Drivers
2114	* @ingroup grp_pdm
2115	* @{
2116	*/
2117
2118
2119	/**
2120	* Construct a driver instance for a VM.
2121	*
2122	* @returns VBox status.
2123	* @param pDrvIns The driver instance data.
2124	* If the registration structure is needed, pDrvIns->pDrvReg points to it.
2125	* @param pCfgHandle Configuration node handle for the driver. Use this to obtain the configuration
2126	* of the driver instance. It's also found in pDrvIns->pCfgHandle it's expected
2127	* to be used primarily in this function.
2128	*/
2129	typedef DECLCALLBACK(int) FNPDMDRVCONSTRUCT(PPDMDRVINS pDrvIns, PCFGMNODE pCfgHandle);
2130	/** Pointer to a FNPDMDRVCONSTRUCT() function. */
2131	typedef FNPDMDRVCONSTRUCT *PFNPDMDRVCONSTRUCT;
2132
2133	/**
2134	* Destruct a driver instance.
2135	*
2136	* Most VM resources are freed by the VM. This callback is provided so that any non-VM
2137	* resources can be freed correctly.
2138	*
2139	* @param pDrvIns The driver instance data.
2140	*/
2141	typedef DECLCALLBACK(void) FNPDMDRVDESTRUCT(PPDMDRVINS pDrvIns);
2142	/** Pointer to a FNPDMDRVDESTRUCT() function. */
2143	typedef FNPDMDRVDESTRUCT *PFNPDMDRVDESTRUCT;
2144
2145	/**
2146	* Driver I/O Control interface.
2147	*
2148	* This is used by external components, such as the COM interface, to
2149	* communicate with a driver using a driver specific interface. Generally,
2150	* the driver interfaces are used for this task.
2151	*
2152	* @returns VBox status code.
2153	* @param pDrvIns Pointer to the driver instance.
2154	* @param uFunction Function to perform.
2155	* @param pvIn Pointer to input data.
2156	* @param cbIn Size of input data.
2157	* @param pvOut Pointer to output data.
2158	* @param cbOut Size of output data.
2159	* @param pcbOut Where to store the actual size of the output data.
2160	*/
2161	typedef DECLCALLBACK(int) FNPDMDRVIOCTL(PPDMDRVINS pDrvIns, RTUINT uFunction,
2162	void *pvIn, RTUINT cbIn,
2163	void *pvOut, RTUINT cbOut, PRTUINT pcbOut);
2164	/** Pointer to a FNPDMDRVIOCTL() function. */
2165	typedef FNPDMDRVIOCTL *PFNPDMDRVIOCTL;
2166
2167	/**
2168	* Power On notification.
2169	*
2170	* @param pDrvIns The driver instance data.
2171	*/
2172	typedef DECLCALLBACK(void) FNPDMDRVPOWERON(PPDMDRVINS pDrvIns);
2173	/** Pointer to a FNPDMDRVPOWERON() function. */
2174	typedef FNPDMDRVPOWERON *PFNPDMDRVPOWERON;
2175
2176	/**
2177	* Reset notification.
2178	*
2179	* @returns VBox status.
2180	* @param pDrvIns The driver instance data.
2181	*/
2182	typedef DECLCALLBACK(void) FNPDMDRVRESET(PPDMDRVINS pDrvIns);
2183	/** Pointer to a FNPDMDRVRESET() function. */
2184	typedef FNPDMDRVRESET *PFNPDMDRVRESET;
2185
2186	/**
2187	* Suspend notification.
2188	*
2189	* @returns VBox status.
2190	* @param pDrvIns The driver instance data.
2191	*/
2192	typedef DECLCALLBACK(void) FNPDMDRVSUSPEND(PPDMDRVINS pDrvIns);
2193	/** Pointer to a FNPDMDRVSUSPEND() function. */
2194	typedef FNPDMDRVSUSPEND *PFNPDMDRVSUSPEND;
2195
2196	/**
2197	* Resume notification.
2198	*
2199	* @returns VBox status.
2200	* @param pDrvIns The driver instance data.
2201	*/
2202	typedef DECLCALLBACK(void) FNPDMDRVRESUME(PPDMDRVINS pDrvIns);
2203	/** Pointer to a FNPDMDRVRESUME() function. */
2204	typedef FNPDMDRVRESUME *PFNPDMDRVRESUME;
2205
2206	/**
2207	* Power Off notification.
2208	*
2209	* @param pDrvIns The driver instance data.
2210	*/
2211	typedef DECLCALLBACK(void) FNPDMDRVPOWEROFF(PPDMDRVINS pDrvIns);
2212	/** Pointer to a FNPDMDRVPOWEROFF() function. */
2213	typedef FNPDMDRVPOWEROFF *PFNPDMDRVPOWEROFF;
2214
2215	/**
2216	* Detach notification.
2217	*
2218	* This is called when a driver below it in the chain is detaching itself
2219	* from it. The driver should adjust it's state to reflect this.
2220	*
2221	* This is like ejecting a cdrom or floppy.
2222	*
2223	* @param pDrvIns The driver instance.
2224	*/
2225	typedef DECLCALLBACK(void) FNPDMDRVDETACH(PPDMDRVINS pDrvIns);
2226	/** Pointer to a FNPDMDRVDETACH() function. */
2227	typedef FNPDMDRVDETACH *PFNPDMDRVDETACH;
2228
2229
2230
2231	/** PDM Driver Registration Structure,
2232	* This structure is used when registering a driver from
2233	* VBoxInitDrivers() (HC Ring-3). PDM will continue use till
2234	* the VM is terminated.
2235	*/
2236	typedef struct PDMDRVREG
2237	{
2238	/** Structure version. PDM_DRVREG_VERSION defines the current version. */
2239	uint32_t u32Version;
2240	/** Driver name. */
2241	char szDriverName[32];
2242	/** The description of the driver. The UTF-8 string pointed to shall, like this structure,
2243	* remain unchanged from registration till VM destruction. */
2244	const char *pszDescription;
2245
2246	/** Flags, combination of the PDM_DRVREG_FLAGS_* \#defines. */
2247	RTUINT fFlags;
2248	/** Driver class(es), combination of the PDM_DRVREG_CLASS_* \#defines. */
2249	RTUINT fClass;
2250	/** Maximum number of instances (per VM). */
2251	RTUINT cMaxInstances;
2252	/** Size of the instance data. */
2253	RTUINT cbInstance;
2254
2255	/** Construct instance - required. */
2256	PFNPDMDRVCONSTRUCT pfnConstruct;
2257	/** Destruct instance - optional. */
2258	PFNPDMDRVDESTRUCT pfnDestruct;
2259	/** I/O control - optional. */
2260	PFNPDMDRVIOCTL pfnIOCtl;
2261	/** Power on notification - optional. */
2262	PFNPDMDRVPOWERON pfnPowerOn;
2263	/** Reset notification - optional. */
2264	PFNPDMDRVRESET pfnReset;
2265	/** Suspend notification - optional. */
2266	PFNPDMDRVSUSPEND pfnSuspend;
2267	/** Resume notification - optional. */
2268	PFNPDMDRVRESUME pfnResume;
2269	/** Detach notification - optional. */
2270	PFNPDMDRVDETACH pfnDetach;
2271	/** Power off notification - optional. */
2272	PFNPDMDRVPOWEROFF pfnPowerOff;
2273
2274	} PDMDRVREG;
2275	/** Pointer to a PDM Driver Structure. */
2276	typedef PDMDRVREG *PPDMDRVREG;
2277	/** Const pointer to a PDM Driver Structure. */
2278	typedef PDMDRVREG const *PCPDMDRVREG;
2279
2280	/** Current DRVREG version number. */
2281	#define PDM_DRVREG_VERSION 0x80010000
2282
2283	/** PDM Device Flags.
2284	* @{ */
2285	/** @def PDM_DRVREG_FLAGS_HOST_BITS_DEFAULT
2286	* The bit count for the current host. */
2287	#if HC_ARCH_BITS == 32
2288	# define PDM_DRVREG_FLAGS_HOST_BITS_DEFAULT 0x000000001
2289	#elif HC_ARCH_BITS == 64
2290	# define PDM_DRVREG_FLAGS_HOST_BITS_DEFAULT 0x000000002
2291	#else
2292	# error Unsupported HC_ARCH_BITS value.
2293	#endif
2294	/** The host bit count mask. */
2295	#define PDM_DRVREG_FLAGS_HOST_BITS_MASK 0x000000003
2296
2297	/** @} */
2298
2299
2300	/** PDM Driver Classes.
2301	* @{ */
2302	/** Mouse input driver. */
2303	#define PDM_DRVREG_CLASS_MOUSE BIT(0)
2304	/** Keyboard input driver. */
2305	#define PDM_DRVREG_CLASS_KEYBOARD BIT(1)
2306	/** Display driver. */
2307	#define PDM_DRVREG_CLASS_DISPLAY BIT(2)
2308	/** Network transport driver. */
2309	#define PDM_DRVREG_CLASS_NETWORK BIT(3)
2310	/** Block driver. */
2311	#define PDM_DRVREG_CLASS_BLOCK BIT(4)
2312	/** Media driver. */
2313	#define PDM_DRVREG_CLASS_MEDIA BIT(5)
2314	/** Mountable driver. */
2315	#define PDM_DRVREG_CLASS_MOUNTABLE BIT(6)
2316	/** Audio driver. */
2317	#define PDM_DRVREG_CLASS_AUDIO BIT(7)
2318	/** VMMDev driver. */
2319	#define PDM_DRVREG_CLASS_VMMDEV BIT(8)
2320	/** Status driver. */
2321	#define PDM_DRVREG_CLASS_STATUS BIT(9)
2322	/** ACPI driver. */
2323	#define PDM_DRVREG_CLASS_ACPI BIT(10)
2324	/** USB related driver. */
2325	#define PDM_DRVREG_CLASS_USB BIT(11)
2326	/** ISCSI Transport related driver. */
2327	#define PDM_DRVREG_CLASS_ISCSITRANSPORT BIT(12)
2328	/** @} */
2329
2330
2331	/**
2332	* Poller callback.
2333	*
2334	* @param pDrvIns The driver instance.
2335	*/
2336	typedef DECLCALLBACK(void) FNPDMDRVPOLLER(PPDMDRVINS pDrvIns);
2337	/** Pointer to a FNPDMDRVPOLLER function. */
2338	typedef FNPDMDRVPOLLER *PFNPDMDRVPOLLER;
2339
2340	#ifdef IN_RING3
2341	/**
2342	* PDM Driver API.
2343	*/
2344	typedef struct PDMDRVHLP
2345	{
2346	/** Structure version. PDM_DRVHLP_VERSION defines the current version. */
2347	uint32_t u32Version;
2348
2349	/**
2350	* Attaches a driver (chain) to the driver.
2351	*
2352	* @returns VBox status code.
2353	* @param pDrvIns Driver instance.
2354	* @param ppBaseInterface Where to store the pointer to the base interface.
2355	*/
2356	DECLR3CALLBACKMEMBER(int, pfnAttach,(PPDMDRVINS pDrvIns, PPDMIBASE *ppBaseInterface));
2357
2358	/**
2359	* Detach the driver the drivers below us.
2360	*
2361	* @returns VBox status code.
2362	* @param pDrvIns Driver instance.
2363	*/
2364	DECLR3CALLBACKMEMBER(int, pfnDetach,(PPDMDRVINS pDrvIns));
2365
2366	/**
2367	* Detach the driver from the driver above it and destroy this
2368	* driver and all drivers below it.
2369	*
2370	* @returns VBox status code.
2371	* @param pDrvIns Driver instance.
2372	*/
2373	DECLR3CALLBACKMEMBER(int, pfnDetachSelf,(PPDMDRVINS pDrvIns));
2374
2375	/**
2376	* Prepare a media mount.
2377	*
2378	* The driver must not have anything attached to itself
2379	* when calling this function as the purpose is to set up the configuration
2380	* of an future attachment.
2381	*
2382	* @returns VBox status code
2383	* @param pDrvIns Driver instance.
2384	* @param pszFilename Pointer to filename. If this is NULL it assumed that the caller have
2385	* constructed a configuration which can be attached to the bottom driver.
2386	* @param pszCoreDriver Core driver name. NULL will cause autodetection. Ignored if pszFilanem is NULL.
2387	*/
2388	DECLR3CALLBACKMEMBER(int, pfnMountPrepare,(PPDMDRVINS pDrvIns, const char pszFilename, const char pszCoreDriver));
2389
2390	/**
2391	* Assert that the current thread is the emulation thread.
2392	*
2393	* @returns True if correct.
2394	* @returns False if wrong.
2395	* @param pDrvIns Driver instance.
2396	* @param pszFile Filename of the assertion location.
2397	* @param iLine Linenumber of the assertion location.
2398	* @param pszFunction Function of the assertion location.
2399	*/
2400	DECLR3CALLBACKMEMBER(bool, pfnAssertEMT,(PPDMDRVINS pDrvIns, const char pszFile, unsigned iLine, const char pszFunction));
2401
2402	/**
2403	* Assert that the current thread is NOT the emulation thread.
2404	*
2405	* @returns True if correct.
2406	* @returns False if wrong.
2407	* @param pDrvIns Driver instance.
2408	* @param pszFile Filename of the assertion location.
2409	* @param iLine Linenumber of the assertion location.
2410	* @param pszFunction Function of the assertion location.
2411	*/
2412	DECLR3CALLBACKMEMBER(bool, pfnAssertOther,(PPDMDRVINS pDrvIns, const char pszFile, unsigned iLine, const char pszFunction));
2413
2414	/**
2415	* Set the VM error message
2416	*
2417	* @returns rc.
2418	* @param pDrvIns Driver instance.
2419	* @param rc VBox status code.
2420	* @param RT_SRC_POS_DECL Use RT_SRC_POS.
2421	* @param pszFormat Error message format string.
2422	* @param ... Error message arguments.
2423	*/
2424	DECLR3CALLBACKMEMBER(int, pfnVMSetError,(PPDMDRVINS pDrvIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, ...));
2425
2426	/**
2427	* Set the VM error message
2428	*
2429	* @returns rc.
2430	* @param pDrvIns Driver instance.
2431	* @param rc VBox status code.
2432	* @param RT_SRC_POS_DECL Use RT_SRC_POS.
2433	* @param pszFormat Error message format string.
2434	* @param va Error message arguments.
2435	*/
2436	DECLR3CALLBACKMEMBER(int, pfnVMSetErrorV,(PPDMDRVINS pDrvIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va));
2437
2438	/**
2439	* Create a queue.
2440	*
2441	* @returns VBox status code.
2442	* @param pDrvIns Driver instance.
2443	* @param cbItem Size a queue item.
2444	* @param cItems Number of items in the queue.
2445	* @param cMilliesInterval Number of milliseconds between polling the queue.
2446	* If 0 then the emulation thread will be notified whenever an item arrives.
2447	* @param pfnCallback The consumer function.
2448	* @param ppQueue Where to store the queue handle on success.
2449	* @thread The emulation thread.
2450	*/
2451	DECLR3CALLBACKMEMBER(int, pfnPDMQueueCreate,(PPDMDRVINS pDrvIns, RTUINT cbItem, RTUINT cItems, uint32_t cMilliesInterval, PFNPDMQUEUEDRV pfnCallback, PPDMQUEUE *ppQueue));
2452
2453	/**
2454	* Register a poller function.
2455	* TEMPORARY HACK FOR NETWORKING! DON'T USE!
2456	*
2457	* @returns VBox status code.
2458	* @param pDrvIns Driver instance.
2459	* @param pfnPoller The callback function.
2460	*/
2461	DECLR3CALLBACKMEMBER(int, pfnPDMPollerRegister,(PPDMDRVINS pDrvIns, PFNPDMDRVPOLLER pfnPoller));
2462
2463	/**
2464	* Query the virtual timer frequency.
2465	*
2466	* @returns Frequency in Hz.
2467	* @param pDrvIns Driver instance.
2468	* @thread Any thread.
2469	*/
2470	DECLR3CALLBACKMEMBER(uint64_t, pfnTMGetVirtualFreq,(PPDMDRVINS pDrvIns));
2471
2472	/**
2473	* Query the virtual time.
2474	*
2475	* @returns The current virtual time.
2476	* @param pDrvIns Driver instance.
2477	* @thread Any thread.
2478	*/
2479	DECLR3CALLBACKMEMBER(uint64_t, pfnTMGetVirtualTime,(PPDMDRVINS pDrvIns));
2480
2481	/**
2482	* Creates a timer.
2483	*
2484	* @returns VBox status.
2485	* @param pDrvIns Driver instance.
2486	* @param enmClock The clock to use on this timer.
2487	* @param pfnCallback Callback function.
2488	* @param pszDesc Pointer to description string which must stay around
2489	* until the timer is fully destroyed (i.e. a bit after TMTimerDestroy()).
2490	* @param ppTimer Where to store the timer on success.
2491	*/
2492	DECLR3CALLBACKMEMBER(int, pfnTMTimerCreate,(PPDMDRVINS pDrvIns, TMCLOCK enmClock, PFNTMTIMERDRV pfnCallback, const char *pszDesc, PPTMTIMERHC ppTimer));
2493
2494	/**
2495	* Register a save state data unit.
2496	*
2497	* @returns VBox status.
2498	* @param pDrvIns Driver instance.
2499	* @param pszName Data unit name.
2500	* @param u32Instance The instance identifier of the data unit.
2501	* This must together with the name be unique.
2502	* @param u32Version Data layout version number.
2503	* @param cbGuess The approximate amount of data in the unit.
2504	* Only for progress indicators.
2505	* @param pfnSavePrep Prepare save callback, optional.
2506	* @param pfnSaveExec Execute save callback, optional.
2507	* @param pfnSaveDone Done save callback, optional.
2508	* @param pfnLoadPrep Prepare load callback, optional.
2509	* @param pfnLoadExec Execute load callback, optional.
2510	* @param pfnLoadDone Done load callback, optional.
2511	*/
2512	DECLR3CALLBACKMEMBER(int, pfnSSMRegister,(PPDMDRVINS pDrvIns, const char *pszName, uint32_t u32Instance, uint32_t u32Version, size_t cbGuess,
2513	PFNSSMDRVSAVEPREP pfnSavePrep, PFNSSMDRVSAVEEXEC pfnSaveExec, PFNSSMDRVSAVEDONE pfnSaveDone,
2514	PFNSSMDRVLOADPREP pfnLoadPrep, PFNSSMDRVLOADEXEC pfnLoadExec, PFNSSMDRVLOADDONE pfnLoadDone));
2515
2516	/**
2517	* Deregister a save state data unit.
2518	*
2519	* @returns VBox status.
2520	* @param pDrvIns Driver instance.
2521	* @param pszName Data unit name.
2522	* @param u32Instance The instance identifier of the data unit.
2523	* This must together with the name be unique.
2524	*/
2525	DECLR3CALLBACKMEMBER(int, pfnSSMDeregister,(PPDMDRVINS pDrvIns, const char *pszName, uint32_t u32Instance));
2526
2527	/**
2528	* Registers a statistics sample if statistics are enabled.
2529	*
2530	* @param pDrvIns Driver instance.
2531	* @param pvSample Pointer to the sample.
2532	* @param enmType Sample type. This indicates what pvSample is pointing at.
2533	* @param pszName Sample name. The name is on this form "/<component>/<sample>".
2534	* Further nesting is possible.
2535	* @param enmUnit Sample unit.
2536	* @param pszDesc Sample description.
2537	*/
2538	DECLR3CALLBACKMEMBER(void, pfnSTAMRegister,(PPDMDRVINS pDrvIns, void pvSample, STAMTYPE enmType, const char pszName,
2539	STAMUNIT enmUnit, const char *pszDesc));
2540
2541	/**
2542	* Same as pfnSTAMRegister except that the name is specified in a
2543	* RTStrPrintf like fashion.
2544	*
2545	* @returns VBox status.
2546	* @param pDrvIns Driver instance.
2547	* @param pvSample Pointer to the sample.
2548	* @param enmType Sample type. This indicates what pvSample is pointing at.
2549	* @param enmVisibility Visibility type specifying whether unused statistics should be visible or not.
2550	* @param enmUnit Sample unit.
2551	* @param pszDesc Sample description.
2552	* @param pszName The sample name format string.
2553	* @param ... Arguments to the format string.
2554	*/
2555	DECLR3CALLBACKMEMBER(void, pfnSTAMRegisterF,(PPDMDRVINS pDrvIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,
2556	STAMUNIT enmUnit, const char pszDesc, const char pszName, ...));
2557
2558	/**
2559	* Same as pfnSTAMRegister except that the name is specified in a
2560	* RTStrPrintfV like fashion.
2561	*
2562	* @returns VBox status.
2563	* @param pDrvIns Driver instance.
2564	* @param pvSample Pointer to the sample.
2565	* @param enmType Sample type. This indicates what pvSample is pointing at.
2566	* @param enmVisibility Visibility type specifying whether unused statistics should be visible or not.
2567	* @param enmUnit Sample unit.
2568	* @param pszDesc Sample description.
2569	* @param pszName The sample name format string.
2570	* @param args Arguments to the format string.
2571	*/
2572	DECLR3CALLBACKMEMBER(void, pfnSTAMRegisterV,(PPDMDRVINS pDrvIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,
2573	STAMUNIT enmUnit, const char pszDesc, const char pszName, va_list args));
2574
2575	/**
2576	* Calls the HC R0 VMM entry point, in a safer but slower manner than SUPCallVMMR0.
2577	* When entering using this call the R0 components can call into the host kernel
2578	* (i.e. use the SUPR0 and RT APIs).
2579	*
2580	* See VMMR0Entry() for more details.
2581	*
2582	* @returns error code specific to uFunction.
2583	* @param pDrvIns The driver instance.
2584	* @param uOperation Operation to execute.
2585	* This is limited to services.
2586	* @param pvArg Pointer to argument structure or if cbArg is 0 just an value.
2587	* @param cbArg The size of the argument. This is used to copy whatever the argument
2588	* points at into a kernel buffer to avoid problems like the user page
2589	* being invalidated while we're executing the call.
2590	*/
2591	DECLR3CALLBACKMEMBER(int, pfnSUPCallVMMR0Ex,(PPDMDRVINS pDrvIns, unsigned uOperation, void *pvArg, unsigned cbArg));
2592
2593	/** Just a safety precaution. */
2594	uint32_t u32TheEnd;
2595	} PDMDRVHLP;
2596	/** Pointer PDM Driver API. */
2597	typedef PDMDRVHLP *PPDMDRVHLP;
2598	/** Pointer const PDM Driver API. */
2599	typedef const PDMDRVHLP *PCPDMDRVHLP;
2600
2601	/** Current DRVHLP version number. */
2602	#define PDM_DRVHLP_VERSION 0x90010000
2603
2604
2605
2606	/**
2607	* PDM Driver Instance.
2608	*/
2609	typedef struct PDMDRVINS
2610	{
2611	/** Structure version. PDM_DRVINS_VERSION defines the current version. */
2612	uint32_t u32Version;
2613
2614	/** Internal data. */
2615	union
2616	{
2617	#ifdef PDMDRVINSINT_DECLARED
2618	PDMDRVINSINT s;
2619	#endif
2620	uint8_t padding[HC_ARCH_BITS == 32 ? 32 : 64];
2621	} Internal;
2622
2623	/** Pointer the PDM Driver API. */
2624	HCPTRTYPE(PCPDMDRVHLP) pDrvHlp;
2625	/** Pointer to driver registration structure. */
2626	HCPTRTYPE(PCPDMDRVREG) pDrvReg;
2627	/** Configuration handle. */
2628	HCPTRTYPE(PCFGMNODE) pCfgHandle;
2629	/** Driver instance number. */
2630	RTUINT iInstance;
2631	/** Pointer to the base interface of the device/driver instance above. */
2632	HCPTRTYPE(PPDMIBASE) pUpBase;
2633	/** Pointer to the base interface of the driver instance below. */
2634	HCPTRTYPE(PPDMIBASE) pDownBase;
2635	/** The base interface of the driver.
2636	* The driver constructor initializes this. */
2637	PDMIBASE IBase;
2638	/* padding to make achInstanceData aligned at 16 byte boundrary. */
2639	uint32_t au32Padding[HC_ARCH_BITS == 32 ? 3 : 1];
2640	/** Pointer to driver instance data. */
2641	HCPTRTYPE(void *) pvInstanceData;
2642	/** Driver instance data. The size of this area is defined
2643	* in the PDMDRVREG::cbInstanceData field. */
2644	char achInstanceData[4];
2645	} PDMDRVINS;
2646
2647	/** Current DRVREG version number. */
2648	#define PDM_DRVINS_VERSION 0xa0010000
2649
2650	/** Converts a pointer to the PDMDRVINS::IBase to a pointer to PDMDRVINS. */
2651	#define PDMIBASE_2_PDMDRV(pInterface) ( (PPDMDRVINS)((char *)(pInterface) - RT_OFFSETOF(PDMDRVINS, IBase)) )
2652
2653	/**
2654	* @copydoc PDMDRVHLP::pfnVMSetError
2655	*/
2656	DECLINLINE(int) PDMDrvHlpVMSetError(PPDMDRVINS pDrvIns, const int rc, RT_SRC_POS_DECL, const char *pszFormat, ...)
2657	{
2658	va_list va;
2659	va_start(va, pszFormat);
2660	pDrvIns->pDrvHlp->pfnVMSetErrorV(pDrvIns, rc, RT_SRC_POS_ARGS, pszFormat, va);
2661	va_end(va);
2662	return rc;
2663	}
2664
2665	/** @def PDMDRV_SET_ERROR
2666	* Set the VM error. See PDMDrvHlpVMSetError() for printf like message formatting.
2667	* Don't use any '%' in the error string!
2668	*/
2669	#define PDMDRV_SET_ERROR(pDrvIns, rc, pszError) \
2670	PDMDrvHlpVMSetError(pDrvIns, rc, RT_SRC_POS, pszError)
2671
2672	#endif /* IN_RING3 */
2673
2674
2675	/** @def PDMDRV_ASSERT_EMT
2676	* Assert that the current thread is the emulation thread.
2677	*/
2678	#ifdef VBOX_STRICT
2679	# define PDMDRV_ASSERT_EMT(pDrvIns) pDrvIns->pDrvHlp->pfnAssertEMT(pDrvIns, __FILE__, __LINE__, __FUNCTION__)
2680	#else
2681	# define PDMDRV_ASSERT_EMT(pDrvIns) do { } while (0)
2682	#endif
2683
2684	/** @def PDMDRV_ASSERT_OTHER
2685	* Assert that the current thread is NOT the emulation thread.
2686	*/
2687	#ifdef VBOX_STRICT
2688	# define PDMDRV_ASSERT_OTHER(pDrvIns) pDrvIns->pDrvHlp->pfnAssertOther(pDrvIns, __FILE__, __LINE__, __FUNCTION__)
2689	#else
2690	# define PDMDRV_ASSERT_OTHER(pDrvIns) do { } while (0)
2691	#endif
2692
2693
2694	#ifdef IN_RING3
2695	/**
2696	* @copydoc PDMDRVHLP::pfnSTAMRegister
2697	*/
2698	DECLINLINE(void) PDMDrvHlpSTAMRegister(PPDMDRVINS pDrvIns, void pvSample, STAMTYPE enmType, const char pszName, STAMUNIT enmUnit, const char *pszDesc)
2699	{
2700	pDrvIns->pDrvHlp->pfnSTAMRegister(pDrvIns, pvSample, enmType, pszName, enmUnit, pszDesc);
2701	}
2702
2703	/**
2704	* @copydoc PDMDRVHLP::pfnSTAMRegisterF
2705	*/
2706	DECLINLINE(void) PDMDrvHlpSTAMRegisterF(PPDMDRVINS pDrvIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility, STAMUNIT enmUnit,
2707	const char pszDesc, const char pszName, ...)
2708	{
2709	va_list va;
2710	va_start(va, pszName);
2711	pDrvIns->pDrvHlp->pfnSTAMRegisterV(pDrvIns, pvSample, enmType, enmVisibility, enmUnit, pszDesc, pszName, va);
2712	va_end(va);
2713	}
2714	#endif /* IN_RING3 */
2715
2716
2717
2718	/** Pointer to callbacks provided to the VBoxDriverRegister() call. */
2719	typedef struct PDMDRVREGCB *PPDMDRVREGCB;
2720	/** Pointer to const callbacks provided to the VBoxDriverRegister() call. */
2721	typedef const struct PDMDRVREGCB *PCPDMDRVREGCB;
2722
2723	/**
2724	* Callbacks for VBoxDriverRegister().
2725	*/
2726	typedef struct PDMDRVREGCB
2727	{
2728	/** Interface version.
2729	* This is set to PDM_DRVREG_CB_VERSION. */
2730	uint32_t u32Version;
2731
2732	/**
2733	* Registers a driver with the current VM instance.
2734	*
2735	* @returns VBox status code.
2736	* @param pCallbacks Pointer to the callback table.
2737	* @param pDrvReg Pointer to the driver registration record.
2738	* This data must be permanent and readonly.
2739	*/
2740	DECLR3CALLBACKMEMBER(int, pfnRegister,(PCPDMDRVREGCB pCallbacks, PCPDMDRVREG pDrvReg));
2741	} PDMDRVREGCB;
2742
2743	/** Current version of the PDMDRVREGCB structure. */
2744	#define PDM_DRVREG_CB_VERSION 0xb0010000
2745
2746
2747	/**
2748	* The VBoxDriverRegister callback function.
2749	*
2750	* PDM will invoke this function after loading a driver module and letting
2751	* the module decide which drivers to register and how to handle conflicts.
2752	*
2753	* @returns VBox status code.
2754	* @param pCallbacks Pointer to the callback table.
2755	* @param u32Version VBox version number.
2756	*/
2757	typedef DECLCALLBACK(int) FNPDMVBOXDRIVERSREGISTER(PCPDMDRVREGCB pCallbacks, uint32_t u32Version);
2758
2759	/**
2760	* Register external drivers
2761	*
2762	* @returns VBox status code.
2763	* @param pVM The VM to operate on.
2764	* @param pfnCallback Driver registration callback
2765	*/
2766	PDMR3DECL(int) PDMR3RegisterDrivers(PVM pVM, FNPDMVBOXDRIVERSREGISTER pfnCallback);
2767
2768	/** @} */
2769
2770
2771
2772
2773	/** @defgroup grp_pdm_device Devices
2774	* @ingroup grp_pdm
2775	* @{
2776	*/
2777
2778
2779	/** @def PDMBOTHCBDECL
2780	* Macro for declaring a callback which is static in HC and exported in GC.
2781	*/
2782	#if defined(IN_GC) \|\| defined(IN_RING0)
2783	# define PDMBOTHCBDECL(type) DECLEXPORT(type)
2784	#else
2785	# define PDMBOTHCBDECL(type) static type
2786	#endif
2787
2788
2789	/**
2790	* Construct a device instance for a VM.
2791	*
2792	* @returns VBox status.
2793	* @param pDevIns The device instance data.
2794	* If the registration structure is needed, pDevIns->pDevReg points to it.
2795	* @param iInstance Instance number. Use this to figure out which registers and such to use.
2796	* The instance number is also found in pDevIns->iInstance, but since it's
2797	* likely to be freqently used PDM passes it as parameter.
2798	* @param pCfgHandle Configuration node handle for the device. Use this to obtain the configuration
2799	* of the device instance. It's also found in pDevIns->pCfgHandle, but since it's
2800	* primary usage will in this function it's passed as a parameter.
2801	*/
2802	typedef DECLCALLBACK(int) FNPDMDEVCONSTRUCT(PPDMDEVINS pDevIns, int iInstance, PCFGMNODE pCfgHandle);
2803	/** Pointer to a FNPDMDEVCONSTRUCT() function. */
2804	typedef FNPDMDEVCONSTRUCT *PFNPDMDEVCONSTRUCT;
2805
2806	/**
2807	* Destruct a device instance.
2808	*
2809	* Most VM resources are freed by the VM. This callback is provided so that any non-VM
2810	* resources can be freed correctly.
2811	*
2812	* @returns VBox status.
2813	* @param pDevIns The device instance data.
2814	*/
2815	typedef DECLCALLBACK(int) FNPDMDEVDESTRUCT(PPDMDEVINS pDevIns);
2816	/** Pointer to a FNPDMDEVDESTRUCT() function. */
2817	typedef FNPDMDEVDESTRUCT *PFNPDMDEVDESTRUCT;
2818
2819	/**
2820	* Device relocation callback.
2821	*
2822	* When this callback is called the device instance data, and if the
2823	* device have a GC component, is being relocated, or/and the selectors
2824	* have been changed. The device must use the chance to perform the
2825	* necessary pointer relocations and data updates.
2826	*
2827	* Before the GC code is executed the first time, this function will be
2828	* called with a 0 delta so GC pointer calculations can be one in one place.
2829	*
2830	* @param pDevIns Pointer to the device instance.
2831	* @param offDelta The relocation delta relative to the old location.
2832	*
2833	* @remark A relocation CANNOT fail.
2834	*/
2835	typedef DECLCALLBACK(void) FNPDMDEVRELOCATE(PPDMDEVINS pDevIns, RTGCINTPTR offDelta);
2836	/** Pointer to a FNPDMDEVRELOCATE() function. */
2837	typedef FNPDMDEVRELOCATE *PFNPDMDEVRELOCATE;
2838
2839
2840	/**
2841	* Device I/O Control interface.
2842	*
2843	* This is used by external components, such as the COM interface, to
2844	* communicate with devices using a class wide interface or a device
2845	* specific interface.
2846	*
2847	* @returns VBox status code.
2848	* @param pDevIns Pointer to the device instance.
2849	* @param uFunction Function to perform.
2850	* @param pvIn Pointer to input data.
2851	* @param cbIn Size of input data.
2852	* @param pvOut Pointer to output data.
2853	* @param cbOut Size of output data.
2854	* @param pcbOut Where to store the actual size of the output data.
2855	*/
2856	typedef DECLCALLBACK(int) FNPDMDEVIOCTL(PPDMDEVINS pDevIns, RTUINT uFunction,
2857	void *pvIn, RTUINT cbIn,
2858	void *pvOut, RTUINT cbOut, PRTUINT pcbOut);
2859	/** Pointer to a FNPDMDEVIOCTL() function. */
2860	typedef FNPDMDEVIOCTL *PFNPDMDEVIOCTL;
2861
2862	/**
2863	* Power On notification.
2864	*
2865	* @returns VBox status.
2866	* @param pDevIns The device instance data.
2867	*/
2868	typedef DECLCALLBACK(void) FNPDMDEVPOWERON(PPDMDEVINS pDevIns);
2869	/** Pointer to a FNPDMDEVPOWERON() function. */
2870	typedef FNPDMDEVPOWERON *PFNPDMDEVPOWERON;
2871
2872	/**
2873	* Reset notification.
2874	*
2875	* @returns VBox status.
2876	* @param pDevIns The device instance data.
2877	*/
2878	typedef DECLCALLBACK(void) FNPDMDEVRESET(PPDMDEVINS pDevIns);
2879	/** Pointer to a FNPDMDEVRESET() function. */
2880	typedef FNPDMDEVRESET *PFNPDMDEVRESET;
2881
2882	/**
2883	* Suspend notification.
2884	*
2885	* @returns VBox status.
2886	* @param pDevIns The device instance data.
2887	*/
2888	typedef DECLCALLBACK(void) FNPDMDEVSUSPEND(PPDMDEVINS pDevIns);
2889	/** Pointer to a FNPDMDEVSUSPEND() function. */
2890	typedef FNPDMDEVSUSPEND *PFNPDMDEVSUSPEND;
2891
2892	/**
2893	* Resume notification.
2894	*
2895	* @returns VBox status.
2896	* @param pDevIns The device instance data.
2897	*/
2898	typedef DECLCALLBACK(void) FNPDMDEVRESUME(PPDMDEVINS pDevIns);
2899	/** Pointer to a FNPDMDEVRESUME() function. */
2900	typedef FNPDMDEVRESUME *PFNPDMDEVRESUME;
2901
2902	/**
2903	* Power Off notification.
2904	*
2905	* @param pDevIns The device instance data.
2906	*/
2907	typedef DECLCALLBACK(void) FNPDMDEVPOWEROFF(PPDMDEVINS pDevIns);
2908	/** Pointer to a FNPDMDEVPOWEROFF() function. */
2909	typedef FNPDMDEVPOWEROFF *PFNPDMDEVPOWEROFF;
2910
2911	/**
2912	* Attach command.
2913	*
2914	* This is called to let the device attach to a driver for a specified LUN
2915	* during runtime. This is not called during VM construction, the device
2916	* constructor have to attach to all the available drivers.
2917	*
2918	* This is like plugging in the keyboard or mouse after turning on the PC.
2919	*
2920	* @returns VBox status code.
2921	* @param pDevIns The device instance.
2922	* @param iLUN The logical unit which is being detached.
2923	*/
2924	typedef DECLCALLBACK(int) FNPDMDEVATTACH(PPDMDEVINS pDevIns, unsigned iLUN);
2925	/** Pointer to a FNPDMDEVATTACH() function. */
2926	typedef FNPDMDEVATTACH *PFNPDMDEVATTACH;
2927
2928	/**
2929	* Detach notification.
2930	*
2931	* This is called when a driver is detaching itself from a LUN of the device.
2932	* The device should adjust it's state to reflect this.
2933	*
2934	* This is like unplugging the network cable to use it for the laptop or
2935	* something while the PC is still running.
2936	*
2937	* @param pDevIns The device instance.
2938	* @param iLUN The logical unit which is being detached.
2939	*/
2940	typedef DECLCALLBACK(void) FNPDMDEVDETACH(PPDMDEVINS pDevIns, unsigned iLUN);
2941	/** Pointer to a FNPDMDEVDETACH() function. */
2942	typedef FNPDMDEVDETACH *PFNPDMDEVDETACH;
2943
2944	/**
2945	* Query the base interface of a logical unit.
2946	*
2947	* @returns VBOX status code.
2948	* @param pDevIns The device instance.
2949	* @param iLUN The logicial unit to query.
2950	* @param ppBase Where to store the pointer to the base interface of the LUN.
2951	*/
2952	typedef DECLCALLBACK(int) FNPDMDEVQUERYINTERFACE(PPDMDEVINS pDevIns, unsigned iLUN, PPDMIBASE *ppBase);
2953	/** Pointer to a FNPDMDEVQUERYINTERFACE() function. */
2954	typedef FNPDMDEVQUERYINTERFACE *PFNPDMDEVQUERYINTERFACE;
2955
2956	/**
2957	* Init complete notification.
2958	* This can be done to do communication with other devices and other
2959	* initialization which requires everything to be in place.
2960	*
2961	* @returns VBOX status code.
2962	* @param pDevIns The device instance.
2963	*/
2964	typedef DECLCALLBACK(int) FNPDMDEVINITCOMPLETE(PPDMDEVINS pDevIns);
2965	/** Pointer to a FNPDMDEVINITCOMPLETE() function. */
2966	typedef FNPDMDEVINITCOMPLETE *PFNPDMDEVINITCOMPLETE;
2967
2968
2969
2970	/** PDM Device Registration Structure,
2971	* This structure is used when registering a device from
2972	* VBoxInitDevices() in HC Ring-3. PDM will continue use till
2973	* the VM is terminated.
2974	*/
2975	typedef struct PDMDEVREG
2976	{
2977	/** Structure version. PDM_DEVREG_VERSION defines the current version. */
2978	uint32_t u32Version;
2979	/** Device name. */
2980	char szDeviceName[32];
2981	/** Name of guest context module (no path).
2982	* Only evalutated if PDM_DEVREG_FLAGS_GC is set. */
2983	char szGCMod[32];
2984	/** Name of guest context module (no path).
2985	* Only evalutated if PDM_DEVREG_FLAGS_GC is set. */
2986	char szR0Mod[32];
2987	/** The description of the device. The UTF-8 string pointed to shall, like this structure,
2988	* remain unchanged from registration till VM destruction. */
2989	const char *pszDescription;
2990
2991	/** Flags, combination of the PDM_DEVREG_FLAGS_* \#defines. */
2992	RTUINT fFlags;
2993	/** Device class(es), combination of the PDM_DEVREG_CLASS_* \#defines. */
2994	RTUINT fClass;
2995	/** Maximum number of instances (per VM). */
2996	RTUINT cMaxInstances;
2997	/** Size of the instance data. */
2998	RTUINT cbInstance;
2999
3000	/** Construct instance - required. */
3001	PFNPDMDEVCONSTRUCT pfnConstruct;
3002	/** Destruct instance - optional. */
3003	PFNPDMDEVDESTRUCT pfnDestruct;
3004	/** Relocation command - optional. */
3005	PFNPDMDEVRELOCATE pfnRelocate;
3006	/** I/O Control interface - optional. */
3007	PFNPDMDEVIOCTL pfnIOCtl;
3008	/** Power on notification - optional. */
3009	PFNPDMDEVPOWERON pfnPowerOn;
3010	/** Reset notification - optional. */
3011	PFNPDMDEVRESET pfnReset;
3012	/** Suspend notification - optional. */
3013	PFNPDMDEVSUSPEND pfnSuspend;
3014	/** Resume notification - optional. */
3015	PFNPDMDEVRESUME pfnResume;
3016	/** Attach command - optional. */
3017	PFNPDMDEVATTACH pfnAttach;
3018	/** Detach notification - optional. */
3019	PFNPDMDEVDETACH pfnDetach;
3020	/** Query a LUN base interface - optional. */
3021	PFNPDMDEVQUERYINTERFACE pfnQueryInterface;
3022	/** Init complete notification - optional. */
3023	PFNPDMDEVINITCOMPLETE pfnInitComplete;
3024	/** Power off notification - optional. */
3025	PFNPDMDEVPOWEROFF pfnPowerOff;
3026	} PDMDEVREG;
3027	/** Pointer to a PDM Device Structure. */
3028	typedef PDMDEVREG *PPDMDEVREG;
3029	/** Const pointer to a PDM Device Structure. */
3030	typedef PDMDEVREG const *PCPDMDEVREG;
3031
3032	/** Current DEVREG version number. */
3033	#define PDM_DEVREG_VERSION 0xc0010000
3034
3035	/** PDM Device Flags.
3036	* @{ */
3037	/** This flag is used to indicate that the device has a GC component. */
3038	#define PDM_DEVREG_FLAGS_GC 0x00000001
3039	/** This flag is used to indicate that the device has a R0 component. */
3040	#define PDM_DEVREG_FLAGS_R0 0x00010000
3041
3042	/** @def PDM_DEVREG_FLAGS_HOST_BITS_DEFAULT
3043	* The bit count for the current host. */
3044	#if HC_ARCH_BITS == 32
3045	# define PDM_DEVREG_FLAGS_HOST_BITS_DEFAULT 0x00000002
3046	#elif HC_ARCH_BITS == 64
3047	# define PDM_DEVREG_FLAGS_HOST_BITS_DEFAULT 0x00000004
3048	#else
3049	# error Unsupported HC_ARCH_BITS value.
3050	#endif
3051	/** The host bit count mask. */
3052	#define PDM_DEVREG_FLAGS_HOST_BITS_MASK 0x00000006
3053
3054	/** The device support only 32-bit guests. */
3055	#define PDM_DEVREG_FLAGS_GUEST_BITS_32 0x00000008
3056	/** The device support only 64-bit guests. */
3057	#define PDM_DEVREG_FLAGS_GUEST_BITS_64 0x00000010
3058	/** The device support both 32-bit & 64-bit guests. */
3059	#define PDM_DEVREG_FLAGS_GUEST_BITS_32_64 0x00000018
3060	/** @def PDM_DEVREG_FLAGS_GUEST_BITS_DEFAULT
3061	* The guest bit count for the current compilation. */
3062	#if GC_ARCH_BITS == 32
3063	# define PDM_DEVREG_FLAGS_GUEST_BITS_DEFAULT PDM_DEVREG_FLAGS_GUEST_BITS_32
3064	#elif GC_ARCH_BITS == 64
3065	# define PDM_DEVREG_FLAGS_GUEST_BITS_DEFAULT PDM_DEVREG_FLAGS_GUEST_BITS_64
3066	#else
3067	# error Unsupported GC_ARCH_BITS value.
3068	#endif
3069	/** The guest bit count mask. */
3070	#define PDM_DEVREG_FLAGS_GUEST_BITS_MASK 0x00000018
3071
3072	/** Indicates that the devices support PAE36 on a 32-bit guest. */
3073	#define PDM_DEVREG_FLAGS_PAE36 0x00000020
3074	/** @} */
3075
3076
3077	/** PDM Device Classes.
3078	* The order is important, lower bit earlier instantiation.
3079	* @{ */
3080	/** Architecture device. */
3081	#define PDM_DEVREG_CLASS_ARCH BIT(0)
3082	/** Architecture BIOS device. */
3083	#define PDM_DEVREG_CLASS_ARCH_BIOS BIT(1)
3084	/** PCI bus brigde. */
3085	#define PDM_DEVREG_CLASS_BUS_PCI BIT(2)
3086	/** ISA bus brigde. */
3087	#define PDM_DEVREG_CLASS_BUS_ISA BIT(3)
3088	/** Input device (mouse, keyboard, joystick,..). */
3089	#define PDM_DEVREG_CLASS_INPUT BIT(4)
3090	/** Interrupt controller (PIC). */
3091	#define PDM_DEVREG_CLASS_PIC BIT(5)
3092	/** Interval controoler (PIT). */
3093	#define PDM_DEVREG_CLASS_PIT BIT(6)
3094	/** RTC/CMOS. */
3095	#define PDM_DEVREG_CLASS_RTC BIT(7)
3096	/** DMA controller. */
3097	#define PDM_DEVREG_CLASS_DMA BIT(8)
3098	/** VMM Device. */
3099	#define PDM_DEVREG_CLASS_VMM_DEV BIT(9)
3100	/** Graphics device, like VGA. */
3101	#define PDM_DEVREG_CLASS_GRAPHICS BIT(10)
3102	/** Storage controller device. */
3103	#define PDM_DEVREG_CLASS_STORAGE BIT(11)
3104	/** Network interface controller. */
3105	#define PDM_DEVREG_CLASS_NETWORK BIT(12)
3106	/** Audio. */
3107	#define PDM_DEVREG_CLASS_AUDIO BIT(13)
3108	/** USB bus? */
3109	#define PDM_DEVREG_CLASS_BUS_USB BIT(14) /* ??? */
3110	/** ACPI. */
3111	#define PDM_DEVREG_CLASS_ACPI BIT(15)
3112	/** Serial Porst */
3113	#define PDM_DEVREG_CLASS_SERIAL_PORT BIT(16)
3114	/** @} */
3115
3116
3117	/**
3118	* PCI Bus registaration structure.
3119	* All the callbacks, except the PCIBIOS hack, are working on PCI devices.
3120	*/
3121	typedef struct PDMPCIBUSREG
3122	{
3123	/** Structure version number. PDM_PCIBUSREG_VERSION defines the current version. */
3124	uint32_t u32Version;
3125
3126	/**
3127	* Registers the device with the default PCI bus.
3128	*
3129	* @returns VBox status code.
3130	* @param pDevIns Device instance of the PCI Bus.
3131	* @param pPciDev The PCI device structure.
3132	* Any PCI enabled device must keep this in it's instance data!
3133	* Fill in the PCI data config before registration, please.
3134	* @param pszName Pointer to device name (permanent, readonly). For debugging, not unique.
3135	* @param iDev The device number ((dev << 3) \| function) the device should have on the bus.
3136	* If negative, the pci bus device will assign one.
3137	*/
3138	DECLR3CALLBACKMEMBER(int, pfnRegisterHC,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, const char *pszName, int iDev));
3139
3140	/**
3141	* Registers a I/O region (memory mapped or I/O ports) for a PCI device.
3142	*
3143	* @returns VBox status code.
3144	* @param pDevIns Device instance of the PCI Bus.
3145	* @param pPciDev The PCI device structure.
3146	* @param iRegion The region number.
3147	* @param cbRegion Size of the region.
3148	* @param iType PCI_ADDRESS_SPACE_MEM, PCI_ADDRESS_SPACE_IO or PCI_ADDRESS_SPACE_MEM_PREFETCH.
3149	* @param pfnCallback Callback for doing the mapping.
3150	*/
3151	DECLR3CALLBACKMEMBER(int, pfnIORegionRegisterHC,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, int iRegion, uint32_t cbRegion, PCIADDRESSSPACE enmType, PFNPCIIOREGIONMAP pfnCallback));
3152
3153	/**
3154	* Set the IRQ for a PCI device.
3155	*
3156	* @param pDevIns Device instance of the PCI Bus.
3157	* @param pPciDev The PCI device structure.
3158	* @param iIrq IRQ number to set.
3159	* @param iLevel IRQ level.
3160	*/
3161	DECLR3CALLBACKMEMBER(void, pfnSetIrqHC,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, int iIrq, int iLevel));
3162
3163	/**
3164	* Saves a state of the PCI device.
3165	*
3166	* @returns VBox status code.
3167	* @param pDevIns Device instance of the PCI Bus.
3168	* @param pPciDev Pointer to PCI device.
3169	* @param pSSMHandle The handle to save the state to.
3170	*/
3171	DECLR3CALLBACKMEMBER(int, pfnSaveExecHC,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, PSSMHANDLE pSSMHandle));
3172
3173	/**
3174	* Loads a saved PCI device state.
3175	*
3176	* @returns VBox status code.
3177	* @param pDevIns Device instance of the PCI Bus.
3178	* @param pPciDev Pointer to PCI device.
3179	* @param pSSMHandle The handle to the saved state.
3180	*/
3181	DECLR3CALLBACKMEMBER(int, pfnLoadExecHC,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, PSSMHANDLE pSSMHandle));
3182
3183	/**
3184	* Called to perform the job of the bios.
3185	* This is only called for the first PCI Bus - it is expected to
3186	* service all the PCI buses.
3187	*
3188	* @returns VBox status.
3189	* @param pDevIns Device instance of the first bus.
3190	*/
3191	DECLR3CALLBACKMEMBER(int, pfnFakePCIBIOSHC,(PPDMDEVINS pDevIns));
3192
3193	/** The name of the SetIrq GC entry point. */
3194	const char *pszSetIrqGC;
3195
3196	/** The name of the SetIrq R0 entry point. */
3197	const char *pszSetIrqR0;
3198
3199	} PDMPCIBUSREG;
3200	/** Pointer to a PCI bus registration structure. */
3201	typedef PDMPCIBUSREG *PPDMPCIBUSREG;
3202
3203	/** Current PDMPCIBUSREG version number. */
3204	#define PDM_PCIBUSREG_VERSION 0xd0010000
3205
3206	/**
3207	* PCI Bus GC helpers.
3208	*/
3209	typedef struct PDMPCIHLPGC
3210	{
3211	/** Structure version. PDM_PCIHLPGC_VERSION defines the current version. */
3212	uint32_t u32Version;
3213
3214	/**
3215	* Set an ISA IRQ.
3216	*
3217	* @param pDevIns PCI device instance.
3218	* @param iIrq IRQ number to set.
3219	* @param iLevel IRQ level.
3220	* @thread EMT only.
3221	*/
3222	DECLGCCALLBACKMEMBER(void, pfnIsaSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
3223
3224	/**
3225	* Set an I/O-APIC IRQ.
3226	*
3227	* @param pDevIns PCI device instance.
3228	* @param iIrq IRQ number to set.
3229	* @param iLevel IRQ level.
3230	* @thread EMT only.
3231	*/
3232	DECLGCCALLBACKMEMBER(void, pfnIoApicSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
3233
3234	#ifdef VBOX_WITH_PDM_LOCK
3235	/**
3236	* Acquires the PDM lock.
3237	*
3238	* @returns VINF_SUCCESS on success.
3239	* @returns rc if we failed to acquire the lock.
3240	* @param pDevIns The PCI device instance.
3241	* @param rc What to return if we fail to acquire the lock.
3242	*/
3243	DECLGCCALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
3244
3245	/**
3246	* Releases the PDM lock.
3247	*
3248	* @param pDevIns The PCI device instance.
3249	*/
3250	DECLGCCALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
3251	#endif
3252	/** Just a safety precaution. */
3253	uint32_t u32TheEnd;
3254	} PDMPCIHLPGC;
3255	/** Pointer to PCI helpers. */
3256	typedef GCPTRTYPE(PDMPCIHLPGC *) PPDMPCIHLPGC;
3257	/** Pointer to const PCI helpers. */
3258	typedef GCPTRTYPE(const PDMPCIHLPGC *) PCPDMPCIHLPGC;
3259
3260	/** Current PDMPCIHLPR3 version number. */
3261	#define PDM_PCIHLPGC_VERSION 0xe1010000
3262
3263
3264	/**
3265	* PCI Bus R0 helpers.
3266	*/
3267	typedef struct PDMPCIHLPR0
3268	{
3269	/** Structure version. PDM_PCIHLPR0_VERSION defines the current version. */
3270	uint32_t u32Version;
3271
3272	/**
3273	* Set an ISA IRQ.
3274	*
3275	* @param pDevIns PCI device instance.
3276	* @param iIrq IRQ number to set.
3277	* @param iLevel IRQ level.
3278	* @thread EMT only.
3279	*/
3280	DECLR0CALLBACKMEMBER(void, pfnIsaSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
3281
3282	/**
3283	* Set an I/O-APIC IRQ.
3284	*
3285	* @param pDevIns PCI device instance.
3286	* @param iIrq IRQ number to set.
3287	* @param iLevel IRQ level.
3288	* @thread EMT only.
3289	*/
3290	DECLR0CALLBACKMEMBER(void, pfnIoApicSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
3291
3292	#ifdef VBOX_WITH_PDM_LOCK
3293	/**
3294	* Acquires the PDM lock.
3295	*
3296	* @returns VINF_SUCCESS on success.
3297	* @returns rc if we failed to acquire the lock.
3298	* @param pDevIns The PCI device instance.
3299	* @param rc What to return if we fail to acquire the lock.
3300	*/
3301	DECLR0CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
3302
3303	/**
3304	* Releases the PDM lock.
3305	*
3306	* @param pDevIns The PCI device instance.
3307	*/
3308	DECLR0CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
3309	#endif
3310
3311	/** Just a safety precaution. */
3312	uint32_t u32TheEnd;
3313	} PDMPCIHLPR0;
3314	/** Pointer to PCI helpers. */
3315	typedef HCPTRTYPE(PDMPCIHLPR0 *) PPDMPCIHLPR0;
3316	/** Pointer to const PCI helpers. */
3317	typedef HCPTRTYPE(const PDMPCIHLPR0 *) PCPDMPCIHLPR0;
3318
3319	/** Current PDMPCIHLPR0 version number. */
3320	#define PDM_PCIHLPR0_VERSION 0xe1010000
3321
3322	/**
3323	* PCI device helpers.
3324	*/
3325	typedef struct PDMPCIHLPR3
3326	{
3327	/** Structure version. PDM_PCIHLPR3_VERSION defines the current version. */
3328	uint32_t u32Version;
3329
3330	/**
3331	* Set an ISA IRQ.
3332	*
3333	* @param pDevIns The PCI device instance.
3334	* @param iIrq IRQ number to set.
3335	* @param iLevel IRQ level.
3336	* @thread EMT only.
3337	*/
3338	DECLR3CALLBACKMEMBER(void, pfnIsaSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
3339
3340	/**
3341	* Set an I/O-APIC IRQ.
3342	*
3343	* @param pDevIns The PCI device instance.
3344	* @param iIrq IRQ number to set.
3345	* @param iLevel IRQ level.
3346	* @thread EMT only.
3347	*/
3348	DECLR3CALLBACKMEMBER(void, pfnIoApicSetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
3349
3350	#ifdef VBOX_WITH_PDM_LOCK
3351	/**
3352	* Acquires the PDM lock.
3353	*
3354	* @returns VINF_SUCCESS on success.
3355	* @returns Fatal error on failure.
3356	* @param pDevIns The PCI device instance.
3357	* @param rc Dummy for making the interface identical to the GC and R0 versions.
3358	*/
3359	DECLR3CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
3360
3361	/**
3362	* Releases the PDM lock.
3363	*
3364	* @param pDevIns The PCI device instance.
3365	*/
3366	DECLR3CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
3367	#endif
3368
3369	/**
3370	* Gets the address of the GC PCI Bus helpers.
3371	*
3372	* This should be called at both construction and relocation time
3373	* to obtain the correct address of the GC helpers.
3374	*
3375	* @returns GC pointer to the PCI Bus helpers.
3376	* @param pDevIns Device instance of the PCI Bus.
3377	* @thread EMT only.
3378	*/
3379	DECLR3CALLBACKMEMBER(PCPDMPCIHLPGC, pfnGetGCHelpers,(PPDMDEVINS pDevIns));
3380
3381	/**
3382	* Gets the address of the R0 PCI Bus helpers.
3383	*
3384	* This should be called at both construction and relocation time
3385	* to obtain the correct address of the GC helpers.
3386	*
3387	* @returns R0 pointer to the PCI Bus helpers.
3388	* @param pDevIns Device instance of the PCI Bus.
3389	* @thread EMT only.
3390	*/
3391	DECLR3CALLBACKMEMBER(PCPDMPCIHLPR0, pfnGetR0Helpers,(PPDMDEVINS pDevIns));
3392
3393	/** Just a safety precaution. */
3394	uint32_t u32TheEnd;
3395	} PDMPCIHLPR3;
3396	/** Pointer to PCI helpers. */
3397	typedef HCPTRTYPE(PDMPCIHLPR3 *) PPDMPCIHLPR3;
3398	/** Pointer to const PCI helpers. */
3399	typedef HCPTRTYPE(const PDMPCIHLPR3 *) PCPDMPCIHLPR3;
3400
3401	/** Current PDMPCIHLPR3 version number. */
3402	#define PDM_PCIHLPR3_VERSION 0xf1010000
3403
3404
3405	/**
3406	* Programmable Interrupt Controller registration structure.
3407	*/
3408	typedef struct PDMPICREG
3409	{
3410	/** Structure version number. PDM_PICREG_VERSION defines the current version. */
3411	uint32_t u32Version;
3412
3413	/**
3414	* Set the an IRQ.
3415	*
3416	* @param pDevIns Device instance of the PIC.
3417	* @param iIrq IRQ number to set.
3418	* @param iLevel IRQ level.
3419	*/
3420	DECLR3CALLBACKMEMBER(void, pfnSetIrqHC,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
3421
3422	/**
3423	* Get a pending interrupt.
3424	*
3425	* @returns Pending interrupt number.
3426	* @param pDevIns Device instance of the PIC.
3427	*/
3428	DECLR3CALLBACKMEMBER(int, pfnGetInterruptHC,(PPDMDEVINS pDevIns));
3429
3430	/** The name of the GC SetIrq entry point. */
3431	const char *pszSetIrqGC;
3432	/** The name of the GC GetInterrupt entry point. */
3433	const char *pszGetInterruptGC;
3434
3435	/** The name of the R0 SetIrq entry point. */
3436	const char *pszSetIrqR0;
3437	/** The name of the R0 GetInterrupt entry point. */
3438	const char *pszGetInterruptR0;
3439	} PDMPICREG;
3440	/** Pointer to a PIC registration structure. */
3441	typedef PDMPICREG *PPDMPICREG;
3442
3443	/** Current PDMPICREG version number. */
3444	#define PDM_PICREG_VERSION 0xe0020000
3445
3446	/**
3447	* PIC GC helpers.
3448	*/
3449	typedef struct PDMPICHLPGC
3450	{
3451	/** Structure version. PDM_PICHLPGC_VERSION defines the current version. */
3452	uint32_t u32Version;
3453
3454	/**
3455	* Set the interrupt force action flag.
3456	*
3457	* @param pDevIns Device instance of the PIC.
3458	*/
3459	DECLGCCALLBACKMEMBER(void, pfnSetInterruptFF,(PPDMDEVINS pDevIns));
3460
3461	/**
3462	* Clear the interrupt force action flag.
3463	*
3464	* @param pDevIns Device instance of the PIC.
3465	*/
3466	DECLGCCALLBACKMEMBER(void, pfnClearInterruptFF,(PPDMDEVINS pDevIns));
3467
3468	#ifdef VBOX_WITH_PDM_LOCK
3469	/**
3470	* Acquires the PDM lock.
3471	*
3472	* @returns VINF_SUCCESS on success.
3473	* @returns rc if we failed to acquire the lock.
3474	* @param pDevIns The PIC device instance.
3475	* @param rc What to return if we fail to acquire the lock.
3476	*/
3477	DECLGCCALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
3478
3479	/**
3480	* Releases the PDM lock.
3481	*
3482	* @param pDevIns The PIC device instance.
3483	*/
3484	DECLGCCALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
3485	#endif
3486	/** Just a safety precaution. */
3487	uint32_t u32TheEnd;
3488	} PDMPICHLPGC;
3489
3490	/** Pointer to PIC GC helpers. */
3491	typedef GCPTRTYPE(PDMPICHLPGC *) PPDMPICHLPGC;
3492	/** Pointer to const PIC GC helpers. */
3493	typedef GCPTRTYPE(const PDMPICHLPGC *) PCPDMPICHLPGC;
3494
3495	/** Current PDMPICHLPGC version number. */
3496	#define PDM_PICHLPGC_VERSION 0xfc010000
3497
3498
3499	/**
3500	* PIC R0 helpers.
3501	*/
3502	typedef struct PDMPICHLPR0
3503	{
3504	/** Structure version. PDM_PICHLPR0_VERSION defines the current version. */
3505	uint32_t u32Version;
3506
3507	/**
3508	* Set the interrupt force action flag.
3509	*
3510	* @param pDevIns Device instance of the PIC.
3511	*/
3512	DECLR0CALLBACKMEMBER(void, pfnSetInterruptFF,(PPDMDEVINS pDevIns));
3513
3514	/**
3515	* Clear the interrupt force action flag.
3516	*
3517	* @param pDevIns Device instance of the PIC.
3518	*/
3519	DECLR0CALLBACKMEMBER(void, pfnClearInterruptFF,(PPDMDEVINS pDevIns));
3520
3521	#ifdef VBOX_WITH_PDM_LOCK
3522	/**
3523	* Acquires the PDM lock.
3524	*
3525	* @returns VINF_SUCCESS on success.
3526	* @returns rc if we failed to acquire the lock.
3527	* @param pDevIns The PIC device instance.
3528	* @param rc What to return if we fail to acquire the lock.
3529	*/
3530	DECLR0CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
3531
3532	/**
3533	* Releases the PDM lock.
3534	*
3535	* @param pDevIns The PCI device instance.
3536	*/
3537	DECLR0CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
3538	#endif
3539
3540	/** Just a safety precaution. */
3541	uint32_t u32TheEnd;
3542	} PDMPICHLPR0;
3543
3544	/** Pointer to PIC R0 helpers. */
3545	typedef HCPTRTYPE(PDMPICHLPR0 *) PPDMPICHLPR0;
3546	/** Pointer to const PIC R0 helpers. */
3547	typedef HCPTRTYPE(const PDMPICHLPR0 *) PCPDMPICHLPR0;
3548
3549	/** Current PDMPICHLPR0 version number. */
3550	#define PDM_PICHLPR0_VERSION 0xfc010000
3551
3552	/**
3553	* PIC HC helpers.
3554	*/
3555	typedef struct PDMPICHLPR3
3556	{
3557	/** Structure version. PDM_PICHLP_VERSION defines the current version. */
3558	uint32_t u32Version;
3559
3560	/**
3561	* Set the interrupt force action flag.
3562	*
3563	* @param pDevIns Device instance of the PIC.
3564	*/
3565	DECLR3CALLBACKMEMBER(void, pfnSetInterruptFF,(PPDMDEVINS pDevIns));
3566
3567	/**
3568	* Clear the interrupt force action flag.
3569	*
3570	* @param pDevIns Device instance of the PIC.
3571	*/
3572	DECLR3CALLBACKMEMBER(void, pfnClearInterruptFF,(PPDMDEVINS pDevIns));
3573
3574	#ifdef VBOX_WITH_PDM_LOCK
3575	/**
3576	* Acquires the PDM lock.
3577	*
3578	* @returns VINF_SUCCESS on success.
3579	* @returns Fatal error on failure.
3580	* @param pDevIns The PIC device instance.
3581	* @param rc Dummy for making the interface identical to the GC and R0 versions.
3582	*/
3583	DECLR3CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
3584
3585	/**
3586	* Releases the PDM lock.
3587	*
3588	* @param pDevIns The PIC device instance.
3589	*/
3590	DECLR3CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
3591	#endif
3592
3593	/**
3594	* Gets the address of the GC PIC helpers.
3595	*
3596	* This should be called at both construction and relocation time
3597	* to obtain the correct address of the GC helpers.
3598	*
3599	* @returns GC pointer to the PIC helpers.
3600	* @param pDevIns Device instance of the PIC.
3601	*/
3602	DECLR3CALLBACKMEMBER(PCPDMPICHLPGC, pfnGetGCHelpers,(PPDMDEVINS pDevIns));
3603
3604	/**
3605	* Gets the address of the R0 PIC helpers.
3606	*
3607	* This should be called at both construction and relocation time
3608	* to obtain the correct address of the GC helpers.
3609	*
3610	* @returns R0 pointer to the PIC helpers.
3611	* @param pDevIns Device instance of the PIC.
3612	*/
3613	DECLR3CALLBACKMEMBER(PCPDMPICHLPR0, pfnGetR0Helpers,(PPDMDEVINS pDevIns));
3614
3615	/** Just a safety precaution. */
3616	uint32_t u32TheEnd;
3617	} PDMPICHLPR3;
3618
3619	/** Pointer to PIC HC helpers. */
3620	typedef HCPTRTYPE(PDMPICHLPR3 *) PPDMPICHLPR3;
3621	/** Pointer to const PIC HC helpers. */
3622	typedef HCPTRTYPE(const PDMPICHLPR3 *) PCPDMPICHLPR3;
3623
3624	/** Current PDMPICHLPR3 version number. */
3625	#define PDM_PICHLPR3_VERSION 0xf0010000
3626
3627
3628
3629	/**
3630	* Advanced Programmable Interrupt Controller registration structure.
3631	*/
3632	typedef struct PDMAPICREG
3633	{
3634	/** Structure version number. PDM_APICREG_VERSION defines the current version. */
3635	uint32_t u32Version;
3636
3637	/**
3638	* Get a pending interrupt.
3639	*
3640	* @returns Pending interrupt number.
3641	* @param pDevIns Device instance of the APIC.
3642	*/
3643	DECLR3CALLBACKMEMBER(int, pfnGetInterruptHC,(PPDMDEVINS pDevIns));
3644
3645	/**
3646	* Set the APIC base.
3647	*
3648	* @param pDevIns Device instance of the APIC.
3649	* @param u64Base The new base.
3650	*/
3651	DECLR3CALLBACKMEMBER(void, pfnSetBaseHC,(PPDMDEVINS pDevIns, uint64_t u64Base));
3652
3653	/**
3654	* Get the APIC base.
3655	*
3656	* @returns Current base.
3657	* @param pDevIns Device instance of the APIC.
3658	*/
3659	DECLR3CALLBACKMEMBER(uint64_t, pfnGetBaseHC,(PPDMDEVINS pDevIns));
3660
3661	/**
3662	* Set the TPR (task priority register?).
3663	*
3664	* @param pDevIns Device instance of the APIC.
3665	* @param u8TPR The new TPR.
3666	*/
3667	DECLR3CALLBACKMEMBER(void, pfnSetTPRHC,(PPDMDEVINS pDevIns, uint8_t u8TPR));
3668
3669	/**
3670	* Get the TPR (task priority register?).
3671	*
3672	* @returns The current TPR.
3673	* @param pDevIns Device instance of the APIC.
3674	*/
3675	DECLR3CALLBACKMEMBER(uint8_t, pfnGetTPRHC,(PPDMDEVINS pDevIns));
3676
3677	/**
3678	* Private interface between the IOAPIC and APIC.
3679	*
3680	* This is a low-level, APIC/IOAPIC implementation specific interface
3681	* which is registered with PDM only because it makes life so much
3682	* simpler right now (GC bits). This is a bad bad hack! The correct
3683	* way of doing this would involve some way of querying GC interfaces
3684	* and relocating them. Perhaps doing some kind of device init in GC...
3685	*
3686	* @returns The current TPR.
3687	* @param pDevIns Device instance of the APIC.
3688	* @param u8Dest See APIC implementation.
3689	* @param u8DestMode See APIC implementation.
3690	* @param u8DeliveryMode See APIC implementation.
3691	* @param iVector See APIC implementation.
3692	* @param u8Polarity See APIC implementation.
3693	* @param u8TriggerMode See APIC implementation.
3694	*/
3695	DECLR3CALLBACKMEMBER(void, pfnBusDeliverHC,(PPDMDEVINS pDevIns, uint8_t u8Dest, uint8_t u8DestMode, uint8_t u8DeliveryMode,
3696	uint8_t iVector, uint8_t u8Polarity, uint8_t u8TriggerMode));
3697
3698	/** The name of the GC GetInterrupt entry point. */
3699	const char *pszGetInterruptGC;
3700	/** The name of the GC SetBase entry point. */
3701	const char *pszSetBaseGC;
3702	/** The name of the GC GetBase entry point. */
3703	const char *pszGetBaseGC;
3704	/** The name of the GC SetTPR entry point. */
3705	const char *pszSetTPRGC;
3706	/** The name of the GC GetTPR entry point. */
3707	const char *pszGetTPRGC;
3708	/** The name of the GC BusDeliver entry point. */
3709	const char *pszBusDeliverGC;
3710
3711	/** The name of the R0 GetInterrupt entry point. */
3712	const char *pszGetInterruptR0;
3713	/** The name of the R0 SetBase entry point. */
3714	const char *pszSetBaseR0;
3715	/** The name of the R0 GetBase entry point. */
3716	const char *pszGetBaseR0;
3717	/** The name of the R0 SetTPR entry point. */
3718	const char *pszSetTPRR0;
3719	/** The name of the R0 GetTPR entry point. */
3720	const char *pszGetTPRR0;
3721	/** The name of the R0 BusDeliver entry point. */
3722	const char *pszBusDeliverR0;
3723
3724	} PDMAPICREG;
3725	/** Pointer to an APIC registration structure. */
3726	typedef PDMAPICREG *PPDMAPICREG;
3727
3728	/** Current PDMAPICREG version number. */
3729	#define PDM_APICREG_VERSION 0x70010000
3730
3731
3732	/**
3733	* APIC GC helpers.
3734	*/
3735	typedef struct PDMAPICHLPGC
3736	{
3737	/** Structure version. PDM_APICHLPGC_VERSION defines the current version. */
3738	uint32_t u32Version;
3739
3740	/**
3741	* Set the interrupt force action flag.
3742	*
3743	* @param pDevIns Device instance of the APIC.
3744	*/
3745	DECLGCCALLBACKMEMBER(void, pfnSetInterruptFF,(PPDMDEVINS pDevIns));
3746
3747	/**
3748	* Clear the interrupt force action flag.
3749	*
3750	* @param pDevIns Device instance of the APIC.
3751	*/
3752	DECLGCCALLBACKMEMBER(void, pfnClearInterruptFF,(PPDMDEVINS pDevIns));
3753
3754	/**
3755	* Sets or clears the APIC bit in the CPUID feature masks.
3756	*
3757	* @param pDevIns Device instance of the APIC.
3758	* @param fEnabled If true the bit is set, else cleared.
3759	*/
3760	DECLGCCALLBACKMEMBER(void, pfnChangeFeature,(PPDMDEVINS pDevIns, bool fEnabled));
3761
3762	#ifdef VBOX_WITH_PDM_LOCK
3763	/**
3764	* Acquires the PDM lock.
3765	*
3766	* @returns VINF_SUCCESS on success.
3767	* @returns rc if we failed to acquire the lock.
3768	* @param pDevIns The APIC device instance.
3769	* @param rc What to return if we fail to acquire the lock.
3770	*/
3771	DECLGCCALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
3772
3773	/**
3774	* Releases the PDM lock.
3775	*
3776	* @param pDevIns The APIC device instance.
3777	*/
3778	DECLGCCALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
3779	#endif
3780	/** Just a safety precaution. */
3781	uint32_t u32TheEnd;
3782	} PDMAPICHLPGC;
3783	/** Pointer to APIC GC helpers. */
3784	typedef GCPTRTYPE(PDMAPICHLPGC *) PPDMAPICHLPGC;
3785	/** Pointer to const APIC helpers. */
3786	typedef GCPTRTYPE(const PDMAPICHLPGC *) PCPDMAPICHLPGC;
3787
3788	/** Current PDMAPICHLPGC version number. */
3789	#define PDM_APICHLPGC_VERSION 0x60010000
3790
3791
3792	/**
3793	* APIC R0 helpers.
3794	*/
3795	typedef struct PDMAPICHLPR0
3796	{
3797	/** Structure version. PDM_APICHLPR0_VERSION defines the current version. */
3798	uint32_t u32Version;
3799
3800	/**
3801	* Set the interrupt force action flag.
3802	*
3803	* @param pDevIns Device instance of the APIC.
3804	*/
3805	DECLR0CALLBACKMEMBER(void, pfnSetInterruptFF,(PPDMDEVINS pDevIns));
3806
3807	/**
3808	* Clear the interrupt force action flag.
3809	*
3810	* @param pDevIns Device instance of the APIC.
3811	*/
3812	DECLR0CALLBACKMEMBER(void, pfnClearInterruptFF,(PPDMDEVINS pDevIns));
3813
3814	/**
3815	* Sets or clears the APIC bit in the CPUID feature masks.
3816	*
3817	* @param pDevIns Device instance of the APIC.
3818	* @param fEnabled If true the bit is set, else cleared.
3819	*/
3820	DECLR0CALLBACKMEMBER(void, pfnChangeFeature,(PPDMDEVINS pDevIns, bool fEnabled));
3821
3822	#ifdef VBOX_WITH_PDM_LOCK
3823	/**
3824	* Acquires the PDM lock.
3825	*
3826	* @returns VINF_SUCCESS on success.
3827	* @returns rc if we failed to acquire the lock.
3828	* @param pDevIns The APIC device instance.
3829	* @param rc What to return if we fail to acquire the lock.
3830	*/
3831	DECLR0CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
3832
3833	/**
3834	* Releases the PDM lock.
3835	*
3836	* @param pDevIns The APIC device instance.
3837	*/
3838	DECLR0CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
3839	#endif
3840
3841	/** Just a safety precaution. */
3842	uint32_t u32TheEnd;
3843	} PDMAPICHLPR0;
3844	/** Pointer to APIC GC helpers. */
3845	typedef GCPTRTYPE(PDMAPICHLPR0 *) PPDMAPICHLPR0;
3846	/** Pointer to const APIC helpers. */
3847	typedef HCPTRTYPE(const PDMAPICHLPR0 *) PCPDMAPICHLPR0;
3848
3849	/** Current PDMAPICHLPR0 version number. */
3850	#define PDM_APICHLPR0_VERSION 0x60010000
3851
3852	/**
3853	* APIC HC helpers.
3854	*/
3855	typedef struct PDMAPICHLPR3
3856	{
3857	/** Structure version. PDM_APICHLPR3_VERSION defines the current version. */
3858	uint32_t u32Version;
3859
3860	/**
3861	* Set the interrupt force action flag.
3862	*
3863	* @param pDevIns Device instance of the APIC.
3864	*/
3865	DECLR3CALLBACKMEMBER(void, pfnSetInterruptFF,(PPDMDEVINS pDevIns));
3866
3867	/**
3868	* Clear the interrupt force action flag.
3869	*
3870	* @param pDevIns Device instance of the APIC.
3871	*/
3872	DECLR3CALLBACKMEMBER(void, pfnClearInterruptFF,(PPDMDEVINS pDevIns));
3873
3874	/**
3875	* Sets or clears the APIC bit in the CPUID feature masks.
3876	*
3877	* @param pDevIns Device instance of the APIC.
3878	* @param fEnabled If true the bit is set, else cleared.
3879	*/
3880	DECLR3CALLBACKMEMBER(void, pfnChangeFeature,(PPDMDEVINS pDevIns, bool fEnabled));
3881
3882	#ifdef VBOX_WITH_PDM_LOCK
3883	/**
3884	* Acquires the PDM lock.
3885	*
3886	* @returns VINF_SUCCESS on success.
3887	* @returns Fatal error on failure.
3888	* @param pDevIns The APIC device instance.
3889	* @param rc Dummy for making the interface identical to the GC and R0 versions.
3890	*/
3891	DECLR3CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
3892
3893	/**
3894	* Releases the PDM lock.
3895	*
3896	* @param pDevIns The APIC device instance.
3897	*/
3898	DECLR3CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
3899	#endif
3900
3901	/**
3902	* Gets the address of the GC APIC helpers.
3903	*
3904	* This should be called at both construction and relocation time
3905	* to obtain the correct address of the GC helpers.
3906	*
3907	* @returns GC pointer to the APIC helpers.
3908	* @param pDevIns Device instance of the APIC.
3909	*/
3910	DECLR3CALLBACKMEMBER(PCPDMAPICHLPGC, pfnGetGCHelpers,(PPDMDEVINS pDevIns));
3911
3912	/**
3913	* Gets the address of the R0 APIC helpers.
3914	*
3915	* This should be called at both construction and relocation time
3916	* to obtain the correct address of the R0 helpers.
3917	*
3918	* @returns R0 pointer to the APIC helpers.
3919	* @param pDevIns Device instance of the APIC.
3920	*/
3921	DECLR3CALLBACKMEMBER(PCPDMAPICHLPR0, pfnGetR0Helpers,(PPDMDEVINS pDevIns));
3922
3923	/** Just a safety precaution. */
3924	uint32_t u32TheEnd;
3925	} PDMAPICHLPR3;
3926	/** Pointer to APIC helpers. */
3927	typedef HCPTRTYPE(PDMAPICHLPR3 *) PPDMAPICHLPR3;
3928	/** Pointer to const APIC helpers. */
3929	typedef HCPTRTYPE(const PDMAPICHLPR3 *) PCPDMAPICHLPR3;
3930
3931	/** Current PDMAPICHLP version number. */
3932	#define PDM_APICHLPR3_VERSION 0xfd010000
3933
3934
3935	/**
3936	* I/O APIC registration structure.
3937	*/
3938	typedef struct PDMIOAPICREG
3939	{
3940	/** Struct version+magic number (PDM_IOAPICREG_VERSION). */
3941	uint32_t u32Version;
3942
3943	/**
3944	* Set the an IRQ.
3945	*
3946	* @param pDevIns Device instance of the I/O APIC.
3947	* @param iIrq IRQ number to set.
3948	* @param iLevel IRQ level.
3949	*/
3950	DECLR3CALLBACKMEMBER(void, pfnSetIrqHC,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
3951
3952	/** The name of the GC SetIrq entry point. */
3953	const char *pszSetIrqGC;
3954
3955	/** The name of the R0 SetIrq entry point. */
3956	const char *pszSetIrqR0;
3957	} PDMIOAPICREG;
3958	/** Pointer to an APIC registration structure. */
3959	typedef PDMIOAPICREG *PPDMIOAPICREG;
3960
3961	/** Current PDMAPICREG version number. */
3962	#define PDM_IOAPICREG_VERSION 0x50010000
3963
3964
3965	/**
3966	* IOAPIC GC helpers.
3967	*/
3968	typedef struct PDMIOAPICHLPGC
3969	{
3970	/** Structure version. PDM_IOAPICHLPGC_VERSION defines the current version. */
3971	uint32_t u32Version;
3972
3973	/**
3974	* Private interface between the IOAPIC and APIC.
3975	*
3976	* See comments about this hack on PDMAPICREG::pfnBusDeliverHC.
3977	*
3978	* @returns The current TPR.
3979	* @param pDevIns Device instance of the IOAPIC.
3980	* @param u8Dest See APIC implementation.
3981	* @param u8DestMode See APIC implementation.
3982	* @param u8DeliveryMode See APIC implementation.
3983	* @param iVector See APIC implementation.
3984	* @param u8Polarity See APIC implementation.
3985	* @param u8TriggerMode See APIC implementation.
3986	*/
3987	DECLGCCALLBACKMEMBER(void, pfnApicBusDeliver,(PPDMDEVINS pDevIns, uint8_t u8Dest, uint8_t u8DestMode, uint8_t u8DeliveryMode,
3988	uint8_t iVector, uint8_t u8Polarity, uint8_t u8TriggerMode));
3989
3990	#ifdef VBOX_WITH_PDM_LOCK
3991	/**
3992	* Acquires the PDM lock.
3993	*
3994	* @returns VINF_SUCCESS on success.
3995	* @returns rc if we failed to acquire the lock.
3996	* @param pDevIns The IOAPIC device instance.
3997	* @param rc What to return if we fail to acquire the lock.
3998	*/
3999	DECLGCCALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
4000
4001	/**
4002	* Releases the PDM lock.
4003	*
4004	* @param pDevIns The IOAPIC device instance.
4005	*/
4006	DECLGCCALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
4007	#endif
4008
4009	/** Just a safety precaution. */
4010	uint32_t u32TheEnd;
4011	} PDMIOAPICHLPGC;
4012	/** Pointer to IOAPIC GC helpers. */
4013	typedef GCPTRTYPE(PDMAPICHLPGC *)PPDMIOAPICHLPGC;
4014	/** Pointer to const IOAPIC helpers. */
4015	typedef GCPTRTYPE(const PDMIOAPICHLPGC *) PCPDMIOAPICHLPGC;
4016
4017	/** Current PDMIOAPICHLPGC version number. */
4018	#define PDM_IOAPICHLPGC_VERSION 0xfe010000
4019
4020
4021	/**
4022	* IOAPIC R0 helpers.
4023	*/
4024	typedef struct PDMIOAPICHLPR0
4025	{
4026	/** Structure version. PDM_IOAPICHLPR0_VERSION defines the current version. */
4027	uint32_t u32Version;
4028
4029	/**
4030	* Private interface between the IOAPIC and APIC.
4031	*
4032	* See comments about this hack on PDMAPICREG::pfnBusDeliverHC.
4033	*
4034	* @returns The current TPR.
4035	* @param pDevIns Device instance of the IOAPIC.
4036	* @param u8Dest See APIC implementation.
4037	* @param u8DestMode See APIC implementation.
4038	* @param u8DeliveryMode See APIC implementation.
4039	* @param iVector See APIC implementation.
4040	* @param u8Polarity See APIC implementation.
4041	* @param u8TriggerMode See APIC implementation.
4042	*/
4043	DECLR0CALLBACKMEMBER(void, pfnApicBusDeliver,(PPDMDEVINS pDevIns, uint8_t u8Dest, uint8_t u8DestMode, uint8_t u8DeliveryMode,
4044	uint8_t iVector, uint8_t u8Polarity, uint8_t u8TriggerMode));
4045
4046	#ifdef VBOX_WITH_PDM_LOCK
4047	/**
4048	* Acquires the PDM lock.
4049	*
4050	* @returns VINF_SUCCESS on success.
4051	* @returns rc if we failed to acquire the lock.
4052	* @param pDevIns The IOAPIC device instance.
4053	* @param rc What to return if we fail to acquire the lock.
4054	*/
4055	DECLR0CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
4056
4057	/**
4058	* Releases the PDM lock.
4059	*
4060	* @param pDevIns The IOAPIC device instance.
4061	*/
4062	DECLR0CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
4063	#endif
4064
4065	/** Just a safety precaution. */
4066	uint32_t u32TheEnd;
4067	} PDMIOAPICHLPR0;
4068	/** Pointer to IOAPIC R0 helpers. */
4069	typedef HCPTRTYPE(PDMAPICHLPGC *)PPDMIOAPICHLPR0;
4070	/** Pointer to const IOAPIC helpers. */
4071	typedef HCPTRTYPE(const PDMIOAPICHLPR0 *) PCPDMIOAPICHLPR0;
4072
4073	/** Current PDMIOAPICHLPR0 version number. */
4074	#define PDM_IOAPICHLPR0_VERSION 0xfe010000
4075
4076	/**
4077	* IOAPIC HC helpers.
4078	*/
4079	typedef struct PDMIOAPICHLPR3
4080	{
4081	/** Structure version. PDM_IOAPICHLPR3_VERSION defines the current version. */
4082	uint32_t u32Version;
4083
4084	/**
4085	* Private interface between the IOAPIC and APIC.
4086	*
4087	* See comments about this hack on PDMAPICREG::pfnBusDeliverHC.
4088	*
4089	* @returns The current TPR.
4090	* @param pDevIns Device instance of the IOAPIC.
4091	* @param u8Dest See APIC implementation.
4092	* @param u8DestMode See APIC implementation.
4093	* @param u8DeliveryMode See APIC implementation.
4094	* @param iVector See APIC implementation.
4095	* @param u8Polarity See APIC implementation.
4096	* @param u8TriggerMode See APIC implementation.
4097	*/
4098	DECLR3CALLBACKMEMBER(void, pfnApicBusDeliver,(PPDMDEVINS pDevIns, uint8_t u8Dest, uint8_t u8DestMode, uint8_t u8DeliveryMode,
4099	uint8_t iVector, uint8_t u8Polarity, uint8_t u8TriggerMode));
4100
4101	#ifdef VBOX_WITH_PDM_LOCK
4102	/**
4103	* Acquires the PDM lock.
4104	*
4105	* @returns VINF_SUCCESS on success.
4106	* @returns Fatal error on failure.
4107	* @param pDevIns The IOAPIC device instance.
4108	* @param rc Dummy for making the interface identical to the GC and R0 versions.
4109	*/
4110	DECLR3CALLBACKMEMBER(int, pfnLock,(PPDMDEVINS pDevIns, int rc));
4111
4112	/**
4113	* Releases the PDM lock.
4114	*
4115	* @param pDevIns The IOAPIC device instance.
4116	*/
4117	DECLR3CALLBACKMEMBER(void, pfnUnlock,(PPDMDEVINS pDevIns));
4118	#endif
4119
4120	/**
4121	* Gets the address of the GC IOAPIC helpers.
4122	*
4123	* This should be called at both construction and relocation time
4124	* to obtain the correct address of the GC helpers.
4125	*
4126	* @returns GC pointer to the IOAPIC helpers.
4127	* @param pDevIns Device instance of the IOAPIC.
4128	*/
4129	DECLR3CALLBACKMEMBER(PCPDMIOAPICHLPGC, pfnGetGCHelpers,(PPDMDEVINS pDevIns));
4130
4131	/**
4132	* Gets the address of the R0 IOAPIC helpers.
4133	*
4134	* This should be called at both construction and relocation time
4135	* to obtain the correct address of the R0 helpers.
4136	*
4137	* @returns R0 pointer to the IOAPIC helpers.
4138	* @param pDevIns Device instance of the IOAPIC.
4139	*/
4140	DECLR3CALLBACKMEMBER(PCPDMIOAPICHLPR0, pfnGetR0Helpers,(PPDMDEVINS pDevIns));
4141
4142	/** Just a safety precaution. */
4143	uint32_t u32TheEnd;
4144	} PDMIOAPICHLPR3;
4145	/** Pointer to IOAPIC HC helpers. */
4146	typedef HCPTRTYPE(PDMIOAPICHLPR3 *) PPDMIOAPICHLPR3;
4147	/** Pointer to const IOAPIC helpers. */
4148	typedef HCPTRTYPE(const PDMIOAPICHLPR3 *) PCPDMIOAPICHLPR3;
4149
4150	/** Current PDMIOAPICHLPR3 version number. */
4151	#define PDM_IOAPICHLPR3_VERSION 0xff010000
4152
4153
4154
4155	#ifdef IN_RING3
4156
4157	/**
4158	* DMA Transfer Handler.
4159	*
4160	* @returns Number of bytes transferred.
4161	* @param pDevIns Device instance of the DMA.
4162	* @param pvUser User pointer.
4163	* @param uChannel Channel number.
4164	* @param off DMA position.
4165	* @param cb Block size.
4166	*/
4167	typedef DECLCALLBACK(uint32_t) FNDMATRANSFERHANDLER(PPDMDEVINS pDevIns, void *pvUser, unsigned uChannel, uint32_t off, uint32_t cb);
4168	/** Pointer to a FNDMATRANSFERHANDLER(). */
4169	typedef FNDMATRANSFERHANDLER *PFNDMATRANSFERHANDLER;
4170
4171	/**
4172	* DMA Controller registration structure.
4173	*/
4174	typedef struct PDMDMAREG
4175	{
4176	/** Structure version number. PDM_DMACREG_VERSION defines the current version. */
4177	uint32_t u32Version;
4178
4179	/**
4180	* Execute pending transfers.
4181	*
4182	* @returns A more work indiciator. I.e. 'true' if there is more to be done, and 'false' if all is done.
4183	* @param pDevIns Device instance of the DMAC.
4184	*/
4185	DECLR3CALLBACKMEMBER(bool, pfnRun,(PPDMDEVINS pDevIns));
4186
4187	/**
4188	* Register transfer function for DMA channel.
4189	*
4190	* @param pDevIns Device instance of the DMAC.
4191	* @param uChannel Channel number.
4192	* @param pfnTransferHandler Device specific transfer function.
4193	* @param pvUSer User pointer to be passed to the callback.
4194	*/
4195	DECLR3CALLBACKMEMBER(void, pfnRegister,(PPDMDEVINS pDevIns, unsigned uChannel, PFNDMATRANSFERHANDLER pfnTransferHandler, void *pvUser));
4196
4197	/**
4198	* Read memory
4199	*
4200	* @returns Number of bytes read.
4201	* @param pDevIns Device instance of the DMAC.
4202	* @param pvBuffer Pointer to target buffer.
4203	* @param off DMA position.
4204	* @param cbBlock Block size.
4205	*/
4206	DECLR3CALLBACKMEMBER(uint32_t, pfnReadMemory,(PPDMDEVINS pDevIns, unsigned uChannel, void *pvBuffer, uint32_t off, uint32_t cbBlock));
4207
4208	/**
4209	* Write memory
4210	*
4211	* @returns Number of bytes written.
4212	* @param pDevIns Device instance of the DMAC.
4213	* @param pvBuffer Memory to write.
4214	* @param off DMA position.
4215	* @param cbBlock Block size.
4216	*/
4217	DECLR3CALLBACKMEMBER(uint32_t, pfnWriteMemory,(PPDMDEVINS pDevIns, unsigned uChannel, const void *pvBuffer, uint32_t off, uint32_t cbBlock));
4218
4219	/**
4220	* Set the DREQ line.
4221	*
4222	* @param pDevIns Device instance of the DMAC.
4223	* @param uChannel Channel number.
4224	* @param uLevel Level of the line.
4225	*/
4226	DECLR3CALLBACKMEMBER(void, pfnSetDREQ,(PPDMDEVINS pDevIns, unsigned uChannel, unsigned uLevel));
4227
4228	/**
4229	* Get channel mode
4230	*
4231	* @returns Channel mode.
4232	* @param pDevIns Device instance of the DMAC.
4233	* @param uChannel Channel number.
4234	*/
4235	DECLR3CALLBACKMEMBER(uint8_t, pfnGetChannelMode,(PPDMDEVINS pDevIns, unsigned uChannel));
4236
4237	} PDMDMACREG;
4238	/** Pointer to a DMAC registration structure. */
4239	typedef PDMDMACREG *PPDMDMACREG;
4240
4241	/** Current PDMDMACREG version number. */
4242	#define PDM_DMACREG_VERSION 0xf5010000
4243
4244
4245	/**
4246	* DMA Controller device helpers.
4247	*/
4248	typedef struct PDMDMACHLP
4249	{
4250	/** Structure version. PDM_DMACHLP_VERSION defines the current version. */
4251	uint32_t u32Version;
4252
4253	/* to-be-defined */
4254
4255	} PDMDMACHLP;
4256	/** Pointer to DMAC helpers. */
4257	typedef PDMDMACHLP *PPDMDMACHLP;
4258	/** Pointer to const DMAC helpers. */
4259	typedef const PDMDMACHLP *PCPDMDMACHLP;
4260
4261	/** Current PDMDMACHLP version number. */
4262	#define PDM_DMACHLP_VERSION 0xf6010000
4263
4264	#endif /* IN_RING3 */
4265
4266
4267
4268	/**
4269	* RTC registration structure.
4270	*/
4271	typedef struct PDMRTCREG
4272	{
4273	/** Structure version number. PDM_RTCREG_VERSION defines the current version. */
4274	uint32_t u32Version;
4275	uint32_t u32Alignment; /*< structure size alignment. /
4276
4277	/**
4278	* Write to a CMOS register and update the checksum if necessary.
4279	*
4280	* @returns VBox status code.
4281	* @param pDevIns Device instance of the RTC.
4282	* @param iReg The CMOS register index.
4283	* @param u8Value The CMOS register value.
4284	*/
4285	DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMDEVINS pDevIns, unsigned iReg, uint8_t u8Value));
4286
4287	/**
4288	* Read a CMOS register.
4289	*
4290	* @returns VBox status code.
4291	* @param pDevIns Device instance of the RTC.
4292	* @param iReg The CMOS register index.
4293	* @param pu8Value Where to store the CMOS register value.
4294	*/
4295	DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMDEVINS pDevIns, unsigned iReg, uint8_t *pu8Value));
4296
4297	} PDMRTCREG;
4298	/** Pointer to a RTC registration structure. */
4299	typedef PDMRTCREG *PPDMRTCREG;
4300	/** Pointer to a const RTC registration structure. */
4301	typedef const PDMRTCREG *PCPDMRTCREG;
4302
4303	/** Current PDMRTCREG version number. */
4304	#define PDM_RTCREG_VERSION 0xfa010000
4305
4306
4307	/**
4308	* RTC device helpers.
4309	*/
4310	typedef struct PDMRTCHLP
4311	{
4312	/** Structure version. PDM_RTCHLP_VERSION defines the current version. */
4313	uint32_t u32Version;
4314
4315	/* to-be-defined */
4316
4317	} PDMRTCHLP;
4318	/** Pointer to RTC helpers. */
4319	typedef PDMRTCHLP *PPDMRTCHLP;
4320	/** Pointer to const RTC helpers. */
4321	typedef const PDMRTCHLP *PCPDMRTCHLP;
4322
4323	/** Current PDMRTCHLP version number. */
4324	#define PDM_RTCHLP_VERSION 0xf6010000
4325
4326
4327
4328	#ifdef IN_RING3
4329
4330	/**
4331	* PDM Device API.
4332	*/
4333	typedef struct PDMDEVHLP
4334	{
4335	/** Structure version. PDM_DEVHLP_VERSION defines the current version. */
4336	uint32_t u32Version;
4337
4338	/**
4339	* Register a number of I/O ports with a device.
4340	*
4341	* These callbacks are of course for the host context (HC).
4342	* Register HC handlers before guest context (GC) handlers! There must be a
4343	* HC handler for every GC handler!
4344	*
4345	* @returns VBox status.
4346	* @param pDevIns The device instance to register the ports with.
4347	* @param Port First port number in the range.
4348	* @param cPorts Number of ports to register.
4349	* @param pvUser User argument.
4350	* @param pfnOut Pointer to function which is gonna handle OUT operations.
4351	* @param pfnIn Pointer to function which is gonna handle IN operations.
4352	* @param pfnOutStr Pointer to function which is gonna handle string OUT operations.
4353	* @param pfnInStr Pointer to function which is gonna handle string IN operations.
4354	* @param pszDesc Pointer to description string. This must not be freed.
4355	*/
4356	DECLR3CALLBACKMEMBER(int, pfnIOPortRegister,(PPDMDEVINS pDevIns, RTIOPORT Port, RTUINT cPorts, RTHCPTR pvUser,
4357	PFNIOMIOPORTOUT pfnOut, PFNIOMIOPORTIN pfnIn,
4358	PFNIOMIOPORTOUTSTRING pfnOutStr, PFNIOMIOPORTINSTRING pfnInStr, const char *pszDesc));
4359
4360	/**
4361	* Register a number of I/O ports with a device for GC.
4362	*
4363	* These callbacks are for the host context (GC).
4364	* Register host context (HC) handlers before guest context handlers! There must be a
4365	* HC handler for every GC handler!
4366	*
4367	* @returns VBox status.
4368	* @param pDevIns The device instance to register the ports with and which GC module
4369	* to resolve the names against.
4370	* @param Port First port number in the range.
4371	* @param cPorts Number of ports to register.
4372	* @param pvUser User argument.
4373	* @param pszOut Name of the GC function which is gonna handle OUT operations.
4374	* @param pszIn Name of the GC function which is gonna handle IN operations.
4375	* @param pszOutStr Name of the GC function which is gonna handle string OUT operations.
4376	* @param pszInStr Name of the GC function which is gonna handle string IN operations.
4377	* @param pszDesc Pointer to description string. This must not be freed.
4378	*/
4379	DECLR3CALLBACKMEMBER(int, pfnIOPortRegisterGC,(PPDMDEVINS pDevIns, RTIOPORT Port, RTUINT cPorts, RTGCPTR pvUser,
4380	const char pszOut, const char pszIn,
4381	const char pszOutStr, const char pszInStr, const char *pszDesc));
4382
4383	/**
4384	* Register a number of I/O ports with a device.
4385	*
4386	* These callbacks are of course for the ring-0 host context (R0).
4387	* Register R3 (HC) handlers before R0 (R0) handlers! There must be a R3 (HC) handler for every R0 handler!
4388	*
4389	* @returns VBox status.
4390	* @param pDevIns The device instance to register the ports with.
4391	* @param Port First port number in the range.
4392	* @param cPorts Number of ports to register.
4393	* @param pvUser User argument. (if pointer, then it must be in locked memory!)
4394	* @param pszOut Name of the R0 function which is gonna handle OUT operations.
4395	* @param pszIn Name of the R0 function which is gonna handle IN operations.
4396	* @param pszOutStr Name of the R0 function which is gonna handle string OUT operations.
4397	* @param pszInStr Name of the R0 function which is gonna handle string IN operations.
4398	* @param pszDesc Pointer to description string. This must not be freed.
4399	*/
4400	DECLR3CALLBACKMEMBER(int, pfnIOPortRegisterR0,(PPDMDEVINS pDevIns, RTIOPORT Port, RTUINT cPorts, RTHCPTR pvUser,
4401	const char pszOut, const char pszIn,
4402	const char pszOutStr, const char pszInStr, const char *pszDesc));
4403
4404	/**
4405	* Deregister I/O ports.
4406	*
4407	* This naturally affects both guest context (GC), ring-0 (R0) and ring-3 (R3/HC) handlers.
4408	*
4409	* @returns VBox status.
4410	* @param pDevIns The device instance owning the ports.
4411	* @param Port First port number in the range.
4412	* @param cPorts Number of ports to deregister.
4413	*/
4414	DECLR3CALLBACKMEMBER(int, pfnIOPortDeregister,(PPDMDEVINS pDevIns, RTIOPORT Port, RTUINT cPorts));
4415
4416
4417	/**
4418	* Register a Memory Mapped I/O (MMIO) region.
4419	*
4420	* These callbacks are of course for the host context (HC).
4421	* Register HC handlers before guest context (GC) handlers! There must be a
4422	* HC handler for every GC handler!
4423	*
4424	* @returns VBox status.
4425	* @param pDevIns The device instance to register the MMIO with.
4426	* @param GCPhysStart First physical address in the range.
4427	* @param cbRange The size of the range (in bytes).
4428	* @param pvUser User argument.
4429	* @param pfnWrite Pointer to function which is gonna handle Write operations.
4430	* @param pfnRead Pointer to function which is gonna handle Read operations.
4431	* @param pfnFill Pointer to function which is gonna handle Fill/memset operations. (optional)
4432	* @param pszDesc Pointer to description string. This must not be freed.
4433	*/
4434	DECLR3CALLBACKMEMBER(int, pfnMMIORegister,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange, RTHCPTR pvUser,
4435	PFNIOMMMIOWRITE pfnWrite, PFNIOMMMIOREAD pfnRead, PFNIOMMMIOFILL pfnFill,
4436	const char *pszDesc));
4437
4438	/**
4439	* Register a Memory Mapped I/O (MMIO) region for GC.
4440	*
4441	* These callbacks are for the guest context (GC).
4442	* Register host context (HC) handlers before guest context handlers! There must be a
4443	* HC handler for every GC handler!
4444	*
4445	* @returns VBox status.
4446	* @param pDevIns The device instance to register the MMIO with.
4447	* @param GCPhysStart First physical address in the range.
4448	* @param cbRange The size of the range (in bytes).
4449	* @param pvUser User argument.
4450	* @param pszWrite Name of the GC function which is gonna handle Write operations.
4451	* @param pszRead Name of the GC function which is gonna handle Read operations.
4452	* @param pszFill Name of the GC function which is gonna handle Fill/memset operations. (optional)
4453	* @param pszDesc Pointer to description string. This must not be freed.
4454	*/
4455	DECLR3CALLBACKMEMBER(int, pfnMMIORegisterGC,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange, RTGCPTR pvUser,
4456	const char pszWrite, const char pszRead, const char *pszFill,
4457	const char *pszDesc));
4458
4459	/**
4460	* Register a Memory Mapped I/O (MMIO) region for R0.
4461	*
4462	* These callbacks are for the ring-0 host context (R0).
4463	* Register R3 (HC) handlers before R0 handlers! There must be a R3 handler for every R0 handler!
4464	*
4465	* @returns VBox status.
4466	* @param pDevIns The device instance to register the MMIO with.
4467	* @param GCPhysStart First physical address in the range.
4468	* @param cbRange The size of the range (in bytes).
4469	* @param pvUser User argument. (if pointer, then it must be in locked memory!)
4470	* @param pszWrite Name of the GC function which is gonna handle Write operations.
4471	* @param pszRead Name of the GC function which is gonna handle Read operations.
4472	* @param pszFill Name of the GC function which is gonna handle Fill/memset operations. (optional)
4473	* @param pszDesc Pointer to description string. This must not be freed.
4474	*/
4475	DECLR3CALLBACKMEMBER(int, pfnMMIORegisterR0,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange, RTHCPTR pvUser,
4476	const char pszWrite, const char pszRead, const char *pszFill,
4477	const char *pszDesc));
4478
4479	/**
4480	* Deregister a Memory Mapped I/O (MMIO) region.
4481	*
4482	* This naturally affects both guest context (GC), ring-0 (R0) and ring-3 (R3/HC) handlers.
4483	*
4484	* @returns VBox status.
4485	* @param pDevIns The device instance owning the MMIO region(s).
4486	* @param GCPhysStart First physical address in the range.
4487	* @param cbRange The size of the range (in bytes).
4488	*/
4489	DECLR3CALLBACKMEMBER(int, pfnMMIODeregister,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange));
4490
4491	/**
4492	* Register a ROM (BIOS) region.
4493	*
4494	* It goes without saying that this is read-only memory. The memory region must be
4495	* in unassigned memory. I.e. from the top of the address space or on the PC in
4496	* the 0xa0000-0xfffff range.
4497	*
4498	* @returns VBox status.
4499	* @param pDevIns The device instance owning the ROM region.
4500	* @param GCPhysStart First physical address in the range.
4501	* Must be page aligned!
4502	* @param cbRange The size of the range (in bytes).
4503	* Must be page aligned!
4504	* @param pvBinary Pointer to the binary data backing the ROM image.
4505	* This must be cbRange bytes big.
4506	* It will be copied and doesn't have to stick around.
4507	* @param pszDesc Pointer to description string. This must not be freed.
4508	* @remark There is no way to remove the rom, automatically on device cleanup or
4509	* manually from the device yet. At present I doubt we need such features...
4510	*/
4511	DECLR3CALLBACKMEMBER(int, pfnROMRegister,(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange, const void pvBinary, const char pszDesc));
4512
4513	/**
4514	* Register a save state data unit.
4515	*
4516	* @returns VBox status.
4517	* @param pDevIns Device instance.
4518	* @param pszName Data unit name.
4519	* @param u32Instance The instance identifier of the data unit.
4520	* This must together with the name be unique.
4521	* @param u32Version Data layout version number.
4522	* @param cbGuess The approximate amount of data in the unit.
4523	* Only for progress indicators.
4524	* @param pfnSavePrep Prepare save callback, optional.
4525	* @param pfnSaveExec Execute save callback, optional.
4526	* @param pfnSaveDone Done save callback, optional.
4527	* @param pfnLoadPrep Prepare load callback, optional.
4528	* @param pfnLoadExec Execute load callback, optional.
4529	* @param pfnLoadDone Done load callback, optional.
4530	*/
4531	DECLR3CALLBACKMEMBER(int, pfnSSMRegister,(PPDMDEVINS pDevIns, const char *pszName, uint32_t u32Instance, uint32_t u32Version, size_t cbGuess,
4532	PFNSSMDEVSAVEPREP pfnSavePrep, PFNSSMDEVSAVEEXEC pfnSaveExec, PFNSSMDEVSAVEDONE pfnSaveDone,
4533	PFNSSMDEVLOADPREP pfnLoadPrep, PFNSSMDEVLOADEXEC pfnLoadExec, PFNSSMDEVLOADDONE pfnLoadDone));
4534
4535	/**
4536	* Creates a timer.
4537	*
4538	* @returns VBox status.
4539	* @param pDevIns Device instance.
4540	* @param enmClock The clock to use on this timer.
4541	* @param pfnCallback Callback function.
4542	* @param pszDesc Pointer to description string which must stay around
4543	* until the timer is fully destroyed (i.e. a bit after TMTimerDestroy()).
4544	* @param ppTimer Where to store the timer on success.
4545	*/
4546	DECLR3CALLBACKMEMBER(int, pfnTMTimerCreate,(PPDMDEVINS pDevIns, TMCLOCK enmClock, PFNTMTIMERDEV pfnCallback, const char *pszDesc, PPTMTIMERHC ppTimer));
4547
4548	/**
4549	* Creates an external timer.
4550	*
4551	* @returns timer pointer
4552	* @param pDevIns Device instance.
4553	* @param enmClock The clock to use on this timer.
4554	* @param pfnCallback Callback function.
4555	* @param pvUser User pointer
4556	* @param pszDesc Pointer to description string which must stay around
4557	* until the timer is fully destroyed (i.e. a bit after TMTimerDestroy()).
4558	*/
4559	DECLR3CALLBACKMEMBER(PTMTIMERHC, pfnTMTimerCreateExternal,(PPDMDEVINS pDevIns, TMCLOCK enmClock, PFNTMTIMEREXT pfnCallback, void pvUser, const char pszDesc));
4560
4561	/**
4562	* Registers the device with the default PCI bus.
4563	*
4564	* @returns VBox status code.
4565	* @param pDevIns Device instance.
4566	* @param pPciDev The PCI device structure.
4567	* Any PCI enabled device must keep this in it's instance data!
4568	* Fill in the PCI data config before registration, please.
4569	* @remark This is the simple interface, a Ex interface will be created if
4570	* more features are needed later.
4571	*/
4572	DECLR3CALLBACKMEMBER(int, pfnPCIRegister,(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev));
4573
4574	/**
4575	* Registers a I/O region (memory mapped or I/O ports) for a PCI device.
4576	*
4577	* @returns VBox status code.
4578	* @param pDevIns Device instance.
4579	* @param iRegion The region number.
4580	* @param cbRegion Size of the region.
4581	* @param enmType PCI_ADDRESS_SPACE_MEM, PCI_ADDRESS_SPACE_IO or PCI_ADDRESS_SPACE_MEM_PREFETCH.
4582	* @param pfnCallback Callback for doing the mapping.
4583	*/
4584	DECLR3CALLBACKMEMBER(int, pfnPCIIORegionRegister,(PPDMDEVINS pDevIns, int iRegion, uint32_t cbRegion, PCIADDRESSSPACE enmType, PFNPCIIOREGIONMAP pfnCallback));
4585
4586	/**
4587	* Set the IRQ for a PCI device.
4588	*
4589	* @param pDevIns Device instance.
4590	* @param iIrq IRQ number to set.
4591	* @param iLevel IRQ level.
4592	* @thread Any thread, but will involve the emulation thread.
4593	*/
4594	DECLR3CALLBACKMEMBER(void, pfnPCISetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
4595
4596	/**
4597	* Set the IRQ for a PCI device, but don't wait for EMT to process
4598	* the request when not called from EMT.
4599	*
4600	* @param pDevIns Device instance.
4601	* @param iIrq IRQ number to set.
4602	* @param iLevel IRQ level.
4603	* @thread Any thread, but will involve the emulation thread.
4604	*/
4605	DECLR3CALLBACKMEMBER(void, pfnPCISetIrqNoWait,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
4606
4607	/**
4608	* Set ISA IRQ for a device.
4609	*
4610	* @param pDevIns Device instance.
4611	* @param iIrq IRQ number to set.
4612	* @param iLevel IRQ level.
4613	* @thread Any thread, but will involve the emulation thread.
4614	*/
4615	DECLR3CALLBACKMEMBER(void, pfnISASetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
4616
4617	/**
4618	* Set the ISA IRQ for a device, but don't wait for EMT to process
4619	* the request when not called from EMT.
4620	*
4621	* @param pDevIns Device instance.
4622	* @param iIrq IRQ number to set.
4623	* @param iLevel IRQ level.
4624	* @thread Any thread, but will involve the emulation thread.
4625	*/
4626	DECLR3CALLBACKMEMBER(void, pfnISASetIrqNoWait,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
4627
4628	/**
4629	* Attaches a driver (chain) to the device.
4630	*
4631	* The first call for a LUN this will serve as a registartion of the LUN. The pBaseInterface and
4632	* the pszDesc string will be registered with that LUN and kept around for PDMR3QueryDeviceLun().
4633	*
4634	* @returns VBox status code.
4635	* @param pDevIns Device instance.
4636	* @param iLun The logical unit to attach.
4637	* @param pBaseInterface Pointer to the base interface for that LUN. (device side / down)
4638	* @param ppBaseInterface Where to store the pointer to the base interface. (driver side / up)
4639	* @param pszDesc Pointer to a string describing the LUN. This string must remain valid
4640	* for the live of the device instance.
4641	*/
4642	DECLR3CALLBACKMEMBER(int, pfnDriverAttach,(PPDMDEVINS pDevIns, RTUINT iLun, PPDMIBASE pBaseInterface, PPDMIBASE ppBaseInterface, const char pszDesc));
4643
4644	#if 0
4645	/* USB... */
4646
4647	#endif
4648
4649	/**
4650	* Allocate memory which is associated with current VM instance
4651	* and automatically freed on it's destruction.
4652	*
4653	* @returns Pointer to allocated memory. The memory is NOT zero-ed.
4654	* @param pDevIns Device instance.
4655	* @param cb Number of bytes to allocate.
4656	*/
4657	DECLR3CALLBACKMEMBER(void *, pfnMMHeapAlloc,(PPDMDEVINS pDevIns, size_t cb));
4658
4659	/**
4660	* Allocate memory which is associated with current VM instance
4661	* and automatically freed on it's destruction. The memory is ZEROed.
4662	*
4663	* @returns Pointer to allocated memory. The memory is NOT zero-ed.
4664	* @param pDevIns Device instance.
4665	* @param cb Number of bytes to allocate.
4666	*/
4667	DECLR3CALLBACKMEMBER(void *, pfnMMHeapAllocZ,(PPDMDEVINS pDevIns, size_t cb));
4668
4669	/**
4670	* Free memory allocated with pfnMMHeapAlloc() and pfnMMHeapAllocZ().
4671	*
4672	* @param pDevIns Device instance.
4673	* @param pv Pointer to the memory to free.
4674	*/
4675	DECLR3CALLBACKMEMBER(void, pfnMMHeapFree,(PPDMDEVINS pDevIns, void *pv));
4676
4677	/**
4678	* Set the VM error message
4679	*
4680	* @returns rc.
4681	* @param pDevIns Device instance.
4682	* @param rc VBox status code.
4683	* @param RT_SRC_POS_DECL Use RT_SRC_POS.
4684	* @param pszFormat Error message format string.
4685	* @param ... Error message arguments.
4686	*/
4687	DECLR3CALLBACKMEMBER(int, pfnVMSetError,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, ...));
4688
4689	/**
4690	* Set the VM error message
4691	*
4692	* @returns rc.
4693	* @param pDevIns Device instance.
4694	* @param rc VBox status code.
4695	* @param RT_SRC_POS_DECL Use RT_SRC_POS.
4696	* @param pszFormat Error message format string.
4697	* @param va Error message arguments.
4698	*/
4699	DECLR3CALLBACKMEMBER(int, pfnVMSetErrorV,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va));
4700
4701	/**
4702	* Assert that the current thread is the emulation thread.
4703	*
4704	* @returns True if correct.
4705	* @returns False if wrong.
4706	* @param pDevIns Device instance.
4707	* @param pszFile Filename of the assertion location.
4708	* @param iLine The linenumber of the assertion location.
4709	* @param pszFunction Function of the assertion location.
4710	*/
4711	DECLR3CALLBACKMEMBER(bool, pfnAssertEMT,(PPDMDEVINS pDevIns, const char pszFile, unsigned iLine, const char pszFunction));
4712
4713	/**
4714	* Assert that the current thread is NOT the emulation thread.
4715	*
4716	* @returns True if correct.
4717	* @returns False if wrong.
4718	* @param pDevIns Device instance.
4719	* @param pszFile Filename of the assertion location.
4720	* @param iLine The linenumber of the assertion location.
4721	* @param pszFunction Function of the assertion location.
4722	*/
4723	DECLR3CALLBACKMEMBER(bool, pfnAssertOther,(PPDMDEVINS pDevIns, const char pszFile, unsigned iLine, const char pszFunction));
4724
4725	/**
4726	* Stops the VM and enters the debugger to look at the guest state.
4727	*
4728	* Use the PDMDeviceDBGFStop() inline function with the RT_SRC_POS macro instead of
4729	* invoking this function directly.
4730	*
4731	* @returns VBox status code which must be passed up to the VMM.
4732	* @param pDevIns Device instance.
4733	* @param pszFile Filename of the assertion location.
4734	* @param iLine The linenumber of the assertion location.
4735	* @param pszFunction Function of the assertion location.
4736	* @param pszFormat Message. (optional)
4737	* @param args Message parameters.
4738	*/
4739	DECLR3CALLBACKMEMBER(int, pfnDBGFStopV,(PPDMDEVINS pDevIns, const char pszFile, unsigned iLine, const char pszFunction, const char *pszFormat, va_list args));
4740
4741	/**
4742	* Register a info handler with DBGF,
4743	*
4744	* @returns VBox status code.
4745	* @param pDevIns Device instance.
4746	* @param pszName The identifier of the info.
4747	* @param pszDesc The description of the info and any arguments the handler may take.
4748	* @param pfnHandler The handler function to be called to display the info.
4749	*/
4750	DECLR3CALLBACKMEMBER(int, pfnDBGFInfoRegister,(PPDMDEVINS pDevIns, const char pszName, const char pszDesc, PFNDBGFHANDLERDEV pfnHandler));
4751
4752	/**
4753	* Registers a statistics sample if statistics are enabled.
4754	*
4755	* @param pDevIns Device instance of the DMA.
4756	* @param pvSample Pointer to the sample.
4757	* @param enmType Sample type. This indicates what pvSample is pointing at.
4758	* @param pszName Sample name. The name is on this form "/<component>/<sample>".
4759	* Further nesting is possible.
4760	* @param enmUnit Sample unit.
4761	* @param pszDesc Sample description.
4762	*/
4763	DECLR3CALLBACKMEMBER(void, pfnSTAMRegister,(PPDMDEVINS pDevIns, void pvSample, STAMTYPE enmType, const char pszName, STAMUNIT enmUnit, const char *pszDesc));
4764
4765	/**
4766	* Same as pfnSTAMRegister except that the name is specified in a
4767	* RTStrPrintf like fashion.
4768	*
4769	* @returns VBox status.
4770	* @param pDevIns Device instance of the DMA.
4771	* @param pvSample Pointer to the sample.
4772	* @param enmType Sample type. This indicates what pvSample is pointing at.
4773	* @param enmVisibility Visibility type specifying whether unused statistics should be visible or not.
4774	* @param enmUnit Sample unit.
4775	* @param pszDesc Sample description.
4776	* @param pszName The sample name format string.
4777	* @param ... Arguments to the format string.
4778	*/
4779	DECLR3CALLBACKMEMBER(void, pfnSTAMRegisterF,(PPDMDEVINS pDevIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,
4780	STAMUNIT enmUnit, const char pszDesc, const char pszName, ...));
4781
4782	/**
4783	* Same as pfnSTAMRegister except that the name is specified in a
4784	* RTStrPrintfV like fashion.
4785	*
4786	* @returns VBox status.
4787	* @param pDevIns Device instance of the DMA.
4788	* @param pvSample Pointer to the sample.
4789	* @param enmType Sample type. This indicates what pvSample is pointing at.
4790	* @param enmVisibility Visibility type specifying whether unused statistics should be visible or not.
4791	* @param enmUnit Sample unit.
4792	* @param pszDesc Sample description.
4793	* @param pszName The sample name format string.
4794	* @param args Arguments to the format string.
4795	*/
4796	DECLR3CALLBACKMEMBER(void, pfnSTAMRegisterV,(PPDMDEVINS pDevIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility,
4797	STAMUNIT enmUnit, const char pszDesc, const char pszName, va_list args));
4798
4799	/**
4800	* Register the RTC device.
4801	*
4802	* @returns VBox status code.
4803	* @param pDevIns Device instance.
4804	* @param pRtcReg Pointer to a RTC registration structure.
4805	* @param ppRtcHlp Where to store the pointer to the helper functions.
4806	*/
4807	DECLR3CALLBACKMEMBER(int, pfnRTCRegister,(PPDMDEVINS pDevIns, PCPDMRTCREG pRtcReg, PCPDMRTCHLP *ppRtcHlp));
4808
4809	/**
4810	* Create a queue.
4811	*
4812	* @returns VBox status code.
4813	* @param pDevIns The device instance.
4814	* @param cbItem The size of a queue item.
4815	* @param cItems The number of items in the queue.
4816	* @param cMilliesInterval The number of milliseconds between polling the queue.
4817	* If 0 then the emulation thread will be notified whenever an item arrives.
4818	* @param pfnCallback The consumer function.
4819	* @param fGCEnabled Set if the queue should work in GC too.
4820	* @param ppQueue Where to store the queue handle on success.
4821	* @thread The emulation thread.
4822	*/
4823	DECLR3CALLBACKMEMBER(int, pfnPDMQueueCreate,(PPDMDEVINS pDevIns, RTUINT cbItem, RTUINT cItems, uint32_t cMilliesInterval,
4824	PFNPDMQUEUEDEV pfnCallback, bool fGCEnabled, PPDMQUEUE *ppQueue));
4825
4826	/**
4827	* Initializes a PDM critical section.
4828	*
4829	* The PDM critical sections are derived from the IPRT critical sections, but
4830	* works in GC as well.
4831	*
4832	* @returns VBox status code.
4833	* @param pDevIns Device instance.
4834	* @param pCritSect Pointer to the critical section.
4835	* @param pszName The name of the critical section (for statistics).
4836	*/
4837	DECLR3CALLBACKMEMBER(int, pfnCritSectInit,(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, const char *pszName));
4838
4839
4840	/** API available to trusted devices only.
4841	*
4842	* These APIs are providing unrestricted access to the guest and the VM,
4843	* or they are interacting intimately with PDM.
4844	*
4845	* @{
4846	*/
4847	/**
4848	* Gets the VM handle. Restricted API.
4849	*
4850	* @returns VM Handle.
4851	* @param pDevIns Device instance.
4852	*/
4853	DECLR3CALLBACKMEMBER(PVM, pfnGetVM,(PPDMDEVINS pDevIns));
4854
4855	/**
4856	* Register the PCI Bus.
4857	*
4858	* @returns VBox status code.
4859	* @param pDevIns Device instance.
4860	* @param pPciBusReg Pointer to PCI bus registration structure.
4861	* @param ppPciHlpR3 Where to store the pointer to the PCI Bus helpers.
4862	*/
4863	DECLR3CALLBACKMEMBER(int, pfnPCIBusRegister,(PPDMDEVINS pDevIns, PPDMPCIBUSREG pPciBusReg, PCPDMPCIHLPR3 *ppPciHlpR3));
4864
4865	/**
4866	* Register the PIC device.
4867	*
4868	* @returns VBox status code.
4869	* @param pDevIns Device instance.
4870	* @param pPicReg Pointer to a PIC registration structure.
4871	* @param ppPicHlpR3 Where to store the pointer to the PIC HC helpers.
4872	*/
4873	DECLR3CALLBACKMEMBER(int, pfnPICRegister,(PPDMDEVINS pDevIns, PPDMPICREG pPicReg, PCPDMPICHLPR3 *ppPicHlpR3));
4874
4875	/**
4876	* Register the APIC device.
4877	*
4878	* @returns VBox status code.
4879	* @param pDevIns Device instance.
4880	* @param pApicReg Pointer to a APIC registration structure.
4881	* @param ppApicHlpR3 Where to store the pointer to the APIC helpers.
4882	*/
4883	DECLR3CALLBACKMEMBER(int, pfnAPICRegister,(PPDMDEVINS pDevIns, PPDMAPICREG pApicReg, PCPDMAPICHLPR3 *ppApicHlpR3));
4884
4885	/**
4886	* Register the I/O APIC device.
4887	*
4888	* @returns VBox status code.
4889	* @param pDevIns Device instance.
4890	* @param pIoApicReg Pointer to a I/O APIC registration structure.
4891	* @param ppIoApicHlpR3 Where to store the pointer to the IOAPIC helpers.
4892	*/
4893	DECLR3CALLBACKMEMBER(int, pfnIOAPICRegister,(PPDMDEVINS pDevIns, PPDMIOAPICREG pIoApicReg, PCPDMIOAPICHLPR3 *ppIoApicHlpR3));
4894
4895	/**
4896	* Register the DMA device.
4897	*
4898	* @returns VBox status code.
4899	* @param pDevIns Device instance.
4900	* @param pDmacReg Pointer to a DMAC registration structure.
4901	* @param ppDmacHlp Where to store the pointer to the DMA helpers.
4902	*/
4903	DECLR3CALLBACKMEMBER(int, pfnDMACRegister,(PPDMDEVINS pDevIns, PPDMDMACREG pDmacReg, PCPDMDMACHLP *ppDmacHlp));
4904
4905	/**
4906	* Read physical memory.
4907	*
4908	* @param pDevIns Device instance.
4909	* @param GCPhys Physical address start reading from.
4910	* @param pvBuf Where to put the read bits.
4911	* @param cbRead How many bytes to read.
4912	* @thread Any thread, but the call may involve the emulation thread.
4913	*/
4914	DECLR3CALLBACKMEMBER(void, pfnPhysRead,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead));
4915
4916	/**
4917	* Write to physical memory.
4918	*
4919	* @param pDevIns Device instance.
4920	* @param GCPhys Physical address to write to.
4921	* @param pvBuf What to write.
4922	* @param cbWrite How many bytes to write.
4923	* @thread Any thread, but the call may involve the emulation thread.
4924	*/
4925	DECLR3CALLBACKMEMBER(void, pfnPhysWrite,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite));
4926
4927	/**
4928	* Read guest physical memory by virtual address.
4929	*
4930	* @param pDevIns Device instance.
4931	* @param pvDst Where to put the read bits.
4932	* @param GCVirtSrc Guest virtual address to start reading from.
4933	* @param cb How many bytes to read.
4934	* @thread The emulation thread.
4935	*/
4936	DECLR3CALLBACKMEMBER(int, pfnPhysReadGCVirt,(PPDMDEVINS pDevIns, void *pvDst, RTGCPTR GCVirtSrc, size_t cb));
4937
4938	/**
4939	* Write to guest physical memory by virtual address.
4940	*
4941	* @param pDevIns Device instance.
4942	* @param GCVirtDst Guest virtual address to write to.
4943	* @param pvSrc What to write.
4944	* @param cb How many bytes to write.
4945	* @thread The emulation thread.
4946	*/
4947	DECLR3CALLBACKMEMBER(int, pfnPhysWriteGCVirt,(PPDMDEVINS pDevIns, RTGCPTR GCVirtDst, const void *pvSrc, size_t cb));
4948
4949	/**
4950	* Reserve physical address space for ROM and MMIO ranges.
4951	*
4952	* @returns VBox status code.
4953	* @param pDevIns Device instance.
4954	* @param GCPhys Start physical address.
4955	* @param cbRange The size of the range.
4956	* @param pszDesc Description string.
4957	* @thread The emulation thread.
4958	*/
4959	DECLR3CALLBACKMEMBER(int, pfnPhysReserve,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTUINT cbRange, const char *pszDesc));
4960
4961	/**
4962	* Convert a guest physical address to a host virtual address.
4963	*
4964	* @returns VBox status code.
4965	* @param pDevIns Device instance.
4966	* @param GCPhys Start physical address.
4967	* @param cbRange The size of the range. Use 0 if you don't care about the range.
4968	* @param ppvHC Where to store the HC pointer corresponding to GCPhys.
4969	* @thread Any thread.
4970	*/
4971	DECLR3CALLBACKMEMBER(int, pfnPhys2HCVirt,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTUINT cbRange, PRTHCPTR ppvHC));
4972
4973	/**
4974	* Convert a guest virtual address to a host virtual address.
4975	*
4976	* @returns VBox status code.
4977	* @param pDevIns Device instance.
4978	* @param GCPtr Guest virtual address.
4979	* @param pHCPtr Where to store the HC pointer corresponding to GCPtr.
4980	* @thread The emulation thread.
4981	* @remark Careful with page boundraries.
4982	*/
4983	DECLR3CALLBACKMEMBER(int, pfnPhysGCPtr2HCPtr,(PPDMDEVINS pDevIns, RTGCPTR GCPtr, PRTHCPTR pHCPtr));
4984
4985	/**
4986	* Checks if the Gate A20 is enabled or not.
4987	*
4988	* @returns true if A20 is enabled.
4989	* @returns false if A20 is disabled.
4990	* @param pDevIns Device instance.
4991	* @thread The emulation thread.
4992	*/
4993	DECLR3CALLBACKMEMBER(bool, pfnA20IsEnabled,(PPDMDEVINS pDevIns));
4994
4995	/**
4996	* Enables or disables the Gate A20.
4997	*
4998	* @param pDevIns Device instance.
4999	* @param fEnable Set this flag to enable the Gate A20; clear it to disable.
5000	* @thread The emulation thread.
5001	*/
5002	DECLR3CALLBACKMEMBER(void, pfnA20Set,(PPDMDEVINS pDevIns, bool fEnable));
5003
5004	/**
5005	* Resets the VM.
5006	*
5007	* @returns The appropriate VBox status code to pass around on reset.
5008	* @param pDevIns Device instance.
5009	* @thread The emulation thread.
5010	*/
5011	DECLR3CALLBACKMEMBER(int, pfnVMReset,(PPDMDEVINS pDevIns));
5012
5013	/**
5014	* Suspends the VM.
5015	*
5016	* @returns The appropriate VBox status code to pass around on suspend.
5017	* @param pDevIns Device instance.
5018	* @thread The emulation thread.
5019	*/
5020	DECLR3CALLBACKMEMBER(int, pfnVMSuspend,(PPDMDEVINS pDevIns));
5021
5022	/**
5023	* Power off the VM.
5024	*
5025	* @returns The appropriate VBox status code to pass around on power off.
5026	* @param pDevIns Device instance.
5027	* @thread The emulation thread.
5028	*/
5029	DECLR3CALLBACKMEMBER(int, pfnVMPowerOff,(PPDMDEVINS pDevIns));
5030
5031	/**
5032	* Acquire global VM lock
5033	*
5034	* @returns VBox status code
5035	* @param pDevIns Device instance.
5036	*/
5037	DECLR3CALLBACKMEMBER(int , pfnLockVM,(PPDMDEVINS pDevIns));
5038
5039	/**
5040	* Release global VM lock
5041	*
5042	* @returns VBox status code
5043	* @param pDevIns Device instance.
5044	*/
5045	DECLR3CALLBACKMEMBER(int, pfnUnlockVM,(PPDMDEVINS pDevIns));
5046
5047	/**
5048	* Check that the current thread owns the global VM lock.
5049	*
5050	* @returns boolean
5051	* @param pDevIns Device instance.
5052	* @param pszFile Filename of the assertion location.
5053	* @param iLine Linenumber of the assertion location.
5054	* @param pszFunction Function of the assertion location.
5055	*/
5056	DECLR3CALLBACKMEMBER(bool, pfnAssertVMLock,(PPDMDEVINS pDevIns, const char pszFile, unsigned iLine, const char pszFunction));
5057
5058	/**
5059	* Register transfer function for DMA channel.
5060	*
5061	* @returns VBox status code.
5062	* @param pDevIns Device instance.
5063	* @param uChannel Channel number.
5064	* @param pfnTransferHandler Device specific transfer callback function.
5065	* @param pvUser User pointer to pass to the callback.
5066	* @thread EMT
5067	*/
5068	DECLR3CALLBACKMEMBER(int, pfnDMARegister,(PPDMDEVINS pDevIns, unsigned uChannel, PFNDMATRANSFERHANDLER pfnTransferHandler, void *pvUser));
5069
5070	/**
5071	* Read memory.
5072	*
5073	* @returns VBox status code.
5074	* @param pDevIns Device instance.
5075	* @param uChannel Channel number.
5076	* @param pvBuffer Pointer to target buffer.
5077	* @param off DMA position.
5078	* @param cbBlock Block size.
5079	* @param pcbRead Where to store the number of bytes which was read. optional.
5080	* @thread EMT
5081	*/
5082	DECLR3CALLBACKMEMBER(int, pfnDMAReadMemory,(PPDMDEVINS pDevIns, unsigned uChannel, void pvBuffer, uint32_t off, uint32_t cbBlock, uint32_t pcbRead));
5083
5084	/**
5085	* Write memory.
5086	*
5087	* @returns VBox status code.
5088	* @param pDevIns Device instance.
5089	* @param uChannel Channel number.
5090	* @param pvBuffer Memory to write.
5091	* @param off DMA position.
5092	* @param cbBlock Block size.
5093	* @param pcbWritten Where to store the number of bytes which was written. optional.
5094	* @thread EMT
5095	*/
5096	DECLR3CALLBACKMEMBER(int, pfnDMAWriteMemory,(PPDMDEVINS pDevIns, unsigned uChannel, const void pvBuffer, uint32_t off, uint32_t cbBlock, uint32_t pcbWritten));
5097
5098	/**
5099	* Set the DREQ line.
5100	*
5101	* @returns VBox status code.
5102	* @param pDevIns Device instance.
5103	* @param uChannel Channel number.
5104	* @param uLevel Level of the line.
5105	* @thread EMT
5106	*/
5107	DECLR3CALLBACKMEMBER(int, pfnDMASetDREQ,(PPDMDEVINS pDevIns, unsigned uChannel, unsigned uLevel));
5108
5109	/**
5110	* Get channel mode.
5111	*
5112	* @returns Channel mode. See specs.
5113	* @param pDevIns Device instance.
5114	* @param uChannel Channel number.
5115	* @thread EMT
5116	*/
5117	DECLR3CALLBACKMEMBER(uint8_t, pfnDMAGetChannelMode,(PPDMDEVINS pDevIns, unsigned uChannel));
5118
5119	/**
5120	* Schedule DMA execution.
5121	*
5122	* @param pDevIns Device instance.
5123	* @thread Any thread.
5124	*/
5125	DECLR3CALLBACKMEMBER(void, pfnDMASchedule,(PPDMDEVINS pDevIns));
5126
5127	/**
5128	* Write CMOS value and update the checksum(s).
5129	*
5130	* @returns VBox status code.
5131	* @param pDevIns Device instance.
5132	* @param iReg The CMOS register index.
5133	* @param u8Value The CMOS register value.
5134	* @thread EMT
5135	*/
5136	DECLR3CALLBACKMEMBER(int, pfnCMOSWrite,(PPDMDEVINS pDevIns, unsigned iReg, uint8_t u8Value));
5137
5138	/**
5139	* Read CMOS value.
5140	*
5141	* @returns VBox status code.
5142	* @param pDevIns Device instance.
5143	* @param iReg The CMOS register index.
5144	* @param pu8Value Where to store the CMOS register value.
5145	* @thread EMT
5146	*/
5147	DECLR3CALLBACKMEMBER(int, pfnCMOSRead,(PPDMDEVINS pDevIns, unsigned iReg, uint8_t *pu8Value));
5148
5149	/** @} */
5150
5151	/** Just a safety precaution. (The value is 0.) */
5152	uint32_t u32TheEnd;
5153	} PDMDEVHLP;
5154	#endif /* !IN_RING3 */
5155	/** Pointer PDM Device API. */
5156	typedef HCPTRTYPE(struct PDMDEVHLP *) PPDMDEVHLP;
5157	/** Pointer PDM Device API. */
5158	typedef HCPTRTYPE(const struct PDMDEVHLP *) PCPDMDEVHLP;
5159
5160	/** Current PDMDEVHLP version number. */
5161	#define PDM_DEVHLP_VERSION 0xf2010000
5162
5163
5164	/**
5165	* PDM Device API - GC Variant.
5166	*/
5167	typedef struct PDMDEVHLPGC
5168	{
5169	/** Structure version. PDM_DEVHLPGC_VERSION defines the current version. */
5170	uint32_t u32Version;
5171
5172	/**
5173	* Set the IRQ for a PCI device.
5174	*
5175	* @param pDevIns Device instance.
5176	* @param iIrq IRQ number to set.
5177	* @param iLevel IRQ level.
5178	* @thread Any thread, but will involve the emulation thread.
5179	*/
5180	DECLGCCALLBACKMEMBER(void, pfnPCISetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
5181
5182	/**
5183	* Set ISA IRQ for a device.
5184	*
5185	* @param pDevIns Device instance.
5186	* @param iIrq IRQ number to set.
5187	* @param iLevel IRQ level.
5188	* @thread Any thread, but will involve the emulation thread.
5189	*/
5190	DECLGCCALLBACKMEMBER(void, pfnISASetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
5191
5192	/**
5193	* Read physical memory.
5194	*
5195	* @param pDevIns Device instance.
5196	* @param GCPhys Physical address start reading from.
5197	* @param pvBuf Where to put the read bits.
5198	* @param cbRead How many bytes to read.
5199	*/
5200	DECLGCCALLBACKMEMBER(void, pfnPhysRead,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead));
5201
5202	/**
5203	* Write to physical memory.
5204	*
5205	* @param pDevIns Device instance.
5206	* @param GCPhys Physical address to write to.
5207	* @param pvBuf What to write.
5208	* @param cbWrite How many bytes to write.
5209	*/
5210	DECLGCCALLBACKMEMBER(void, pfnPhysWrite,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite));
5211
5212	/**
5213	* Checks if the Gate A20 is enabled or not.
5214	*
5215	* @returns true if A20 is enabled.
5216	* @returns false if A20 is disabled.
5217	* @param pDevIns Device instance.
5218	* @thread The emulation thread.
5219	*/
5220	DECLGCCALLBACKMEMBER(bool, pfnA20IsEnabled,(PPDMDEVINS pDevIns));
5221
5222	/**
5223	* Set the VM error message
5224	*
5225	* @returns rc.
5226	* @param pDrvIns Driver instance.
5227	* @param rc VBox status code.
5228	* @param RT_SRC_POS_DECL Use RT_SRC_POS.
5229	* @param pszFormat Error message format string.
5230	* @param ... Error message arguments.
5231	*/
5232	DECLGCCALLBACKMEMBER(int, pfnVMSetError,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, ...));
5233
5234	/**
5235	* Set the VM error message
5236	*
5237	* @returns rc.
5238	* @param pDrvIns Driver instance.
5239	* @param rc VBox status code.
5240	* @param RT_SRC_POS_DECL Use RT_SRC_POS.
5241	* @param pszFormat Error message format string.
5242	* @param va Error message arguments.
5243	*/
5244	DECLGCCALLBACKMEMBER(int, pfnVMSetErrorV,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va));
5245
5246	/**
5247	* Set parameters for pending MMIO patch operation
5248	*
5249	* @returns VBox status code.
5250	* @param pDevIns Device instance.
5251	* @param GCPhys MMIO physical address
5252	* @param pCachedData GC pointer to cached data
5253	*/
5254	DECLGCCALLBACKMEMBER(int, pfnPATMSetMMIOPatchInfo,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTGCPTR pCachedData));
5255
5256	/** Just a safety precaution. */
5257	uint32_t u32TheEnd;
5258	} PDMDEVHLPGC;
5259	/** Pointer PDM Device GC API. */
5260	typedef GCPTRTYPE(struct PDMDEVHLPGC *) PPDMDEVHLPGC;
5261	/** Pointer PDM Device GC API. */
5262	typedef GCPTRTYPE(const struct PDMDEVHLPGC *) PCPDMDEVHLPGC;
5263
5264	/** Current PDMDEVHLP version number. */
5265	#define PDM_DEVHLPGC_VERSION 0xfb010000
5266
5267
5268	/**
5269	* PDM Device API - R0 Variant.
5270	*/
5271	typedef struct PDMDEVHLPR0
5272	{
5273	/** Structure version. PDM_DEVHLPR0_VERSION defines the current version. */
5274	uint32_t u32Version;
5275
5276	/**
5277	* Set the IRQ for a PCI device.
5278	*
5279	* @param pDevIns Device instance.
5280	* @param iIrq IRQ number to set.
5281	* @param iLevel IRQ level.
5282	* @thread Any thread, but will involve the emulation thread.
5283	*/
5284	DECLR0CALLBACKMEMBER(void, pfnPCISetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
5285
5286	/**
5287	* Set ISA IRQ for a device.
5288	*
5289	* @param pDevIns Device instance.
5290	* @param iIrq IRQ number to set.
5291	* @param iLevel IRQ level.
5292	* @thread Any thread, but will involve the emulation thread.
5293	*/
5294	DECLR0CALLBACKMEMBER(void, pfnISASetIrq,(PPDMDEVINS pDevIns, int iIrq, int iLevel));
5295
5296	/**
5297	* Read physical memory.
5298	*
5299	* @param pDevIns Device instance.
5300	* @param GCPhys Physical address start reading from.
5301	* @param pvBuf Where to put the read bits.
5302	* @param cbRead How many bytes to read.
5303	*/
5304	DECLR0CALLBACKMEMBER(void, pfnPhysRead,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead));
5305
5306	/**
5307	* Write to physical memory.
5308	*
5309	* @param pDevIns Device instance.
5310	* @param GCPhys Physical address to write to.
5311	* @param pvBuf What to write.
5312	* @param cbWrite How many bytes to write.
5313	*/
5314	DECLR0CALLBACKMEMBER(void, pfnPhysWrite,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite));
5315
5316	/**
5317	* Checks if the Gate A20 is enabled or not.
5318	*
5319	* @returns true if A20 is enabled.
5320	* @returns false if A20 is disabled.
5321	* @param pDevIns Device instance.
5322	* @thread The emulation thread.
5323	*/
5324	DECLR0CALLBACKMEMBER(bool, pfnA20IsEnabled,(PPDMDEVINS pDevIns));
5325
5326	/**
5327	* Set the VM error message
5328	*
5329	* @returns rc.
5330	* @param pDrvIns Driver instance.
5331	* @param rc VBox status code.
5332	* @param RT_SRC_POS_DECL Use RT_SRC_POS.
5333	* @param pszFormat Error message format string.
5334	* @param ... Error message arguments.
5335	*/
5336	DECLR0CALLBACKMEMBER(int, pfnVMSetError,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, ...));
5337
5338	/**
5339	* Set the VM error message
5340	*
5341	* @returns rc.
5342	* @param pDrvIns Driver instance.
5343	* @param rc VBox status code.
5344	* @param RT_SRC_POS_DECL Use RT_SRC_POS.
5345	* @param pszFormat Error message format string.
5346	* @param va Error message arguments.
5347	*/
5348	DECLR0CALLBACKMEMBER(int, pfnVMSetErrorV,(PPDMDEVINS pDevIns, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va));
5349
5350	/**
5351	* Set parameters for pending MMIO patch operation
5352	*
5353	* @returns rc.
5354	* @param pDevIns Device instance.
5355	* @param GCPhys MMIO physical address
5356	* @param pCachedData GC pointer to cached data
5357	*/
5358	DECLR0CALLBACKMEMBER(int, pfnPATMSetMMIOPatchInfo,(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTGCPTR pCachedData));
5359
5360	/** Just a safety precaution. */
5361	uint32_t u32TheEnd;
5362	} PDMDEVHLPR0;
5363	/** Pointer PDM Device R0 API. */
5364	typedef HCPTRTYPE(struct PDMDEVHLPR0 *) PPDMDEVHLPR0;
5365	/** Pointer PDM Device GC API. */
5366	typedef HCPTRTYPE(const struct PDMDEVHLPR0 *) PCPDMDEVHLPR0;
5367
5368	/** Current PDMDEVHLP version number. */
5369	#define PDM_DEVHLPR0_VERSION 0xfb010000
5370
5371
5372
5373	/**
5374	* PDM Device Instance.
5375	*/
5376	typedef struct PDMDEVINS
5377	{
5378	/** Structure version. PDM_DEVINS_VERSION defines the current version. */
5379	uint32_t u32Version;
5380	/** Device instance number. */
5381	RTUINT iInstance;
5382	/** The base interface of the device.
5383	* The device constructor initializes this if it has any
5384	* device level interfaces to export. To obtain this interface
5385	* call PDMR3QueryDevice(). */
5386	PDMIBASE IBase;
5387
5388	/** Internal data. */
5389	union
5390	{
5391	#ifdef PDMDEVINSINT_DECLARED
5392	PDMDEVINSINT s;
5393	#endif
5394	uint8_t padding[HC_ARCH_BITS == 32 ? 48 : 96];
5395	} Internal;
5396
5397	/** Pointer the HC PDM Device API. */
5398	HCPTRTYPE(PCPDMDEVHLP) pDevHlp;
5399	/** Pointer the R0 PDM Device API. */
5400	R0PTRTYPE(PCPDMDEVHLPR0) pDevHlpR0;
5401	/** Pointer to device registration structure. */
5402	HCPTRTYPE(PCPDMDEVREG) pDevReg;
5403	/** Configuration handle. */
5404	HCPTRTYPE(PCFGMNODE) pCfgHandle;
5405	/** Pointer to device instance data. */
5406	HCPTRTYPE(void *) pvInstanceDataHC;
5407	/** Pointer the GC PDM Device API. */
5408	GCPTRTYPE(PCPDMDEVHLPGC) pDevHlpGC;
5409	/** Pointer to device instance data. */
5410	GCPTRTYPE(void *) pvInstanceDataGC;
5411	#if HC_ARCH_BITS == 32
5412	/* padding to make achInstanceData aligned at 16 byte boundrary. */
5413	uint32_t au32Padding[HC_ARCH_BITS == 32 ? 2 : 0];
5414	#endif
5415	/** Device instance data. The size of this area is defined
5416	* in the PDMDEVREG::cbInstanceData field. */
5417	char achInstanceData[8];
5418	} PDMDEVINS;
5419
5420	/** Current DEVREG version number. */
5421	#define PDM_DEVINS_VERSION 0xf3010000
5422
5423	/** Converts a pointer to the PDMDEVINS::IBase to a pointer to PDMDEVINS. */
5424	#define PDMIBASE_2_PDMDEV(pInterface) ( (PPDMDEVINS)((char *)(pInterface) - RT_OFFSETOF(PDMDEVINS, IBase)) )
5425
5426
5427	/** @def PDMDEV_ASSERT_EMT
5428	* Assert that the current thread is the emulation thread.
5429	*/
5430	#ifdef VBOX_STRICT
5431	# define PDMDEV_ASSERT_EMT(pDevIns) pDevIns->pDevHlp->pfnAssertEMT(pDevIns, __FILE__, __LINE__, __FUNCTION__)
5432	#else
5433	# define PDMDEV_ASSERT_EMT(pDevIns) do { } while (0)
5434	#endif
5435
5436	/** @def PDMDEV_ASSERT_OTHER
5437	* Assert that the current thread is NOT the emulation thread.
5438	*/
5439	#ifdef VBOX_STRICT
5440	# define PDMDEV_ASSERT_OTHER(pDevIns) pDevIns->pDevHlp->pfnAssertOther(pDevIns, __FILE__, __LINE__, __FUNCTION__)
5441	#else
5442	# define PDMDEV_ASSERT_OTHER(pDevIns) do { } while (0)
5443	#endif
5444
5445	/** @def PDMDEV_ASSERT_VMLOCK_OWNER
5446	* Assert that the current thread is owner of the VM lock.
5447	*/
5448	#ifdef VBOX_STRICT
5449	# define PDMDEV_ASSERT_VMLOCK_OWNER(pDevIns) pDevIns->pDevHlp->pfnAssertVMLock(pDevIns, __FILE__, __LINE__, __FUNCTION__)
5450	#else
5451	# define PDMDEV_ASSERT_VMLOCK_OWNER(pDevIns) do { } while (0)
5452	#endif
5453
5454	/** @def PDMDEV_SET_ERROR
5455	* Set the VM error. See PDMDevHlpVMSetError() for printf like message formatting.
5456	* Don't use any '%' in the error string!
5457	*/
5458	#define PDMDEV_SET_ERROR(pDevIns, rc, pszError) \
5459	PDMDevHlpVMSetError(pDevIns, rc, RT_SRC_POS, pszError)
5460
5461	/** @def PDMINS2DATA
5462	* Converts a PDM Device or Driver instance pointer to a pointer to the instance data.
5463	*/
5464	#define PDMINS2DATA(pIns, type) ( (type)(void *)&(pIns)->achInstanceData[0] )
5465
5466	/** @def PDMINS2DATA_GCPTR
5467	* Converts a PDM Device or Driver instance pointer to a GC pointer to the instance data.
5468	*/
5469	#define PDMINS2DATA_GCPTR(pIns) ( (pIns)->pvInstanceDataGC )
5470
5471	/** @def PDMINS2DATA_HCPTR
5472	* Converts a PDM Device or Driver instance pointer to a HC pointer to the instance data.
5473	*/
5474	#define PDMINS2DATA_HCPTR(pIns) ( (pIns)->pvInstanceDataHC )
5475
5476	/** @def PDMDEVINS_2_GCPTR
5477	* Converts a PDM Device instance pointer a GC PDM Device instance pointer.
5478	*/
5479	#define PDMDEVINS_2_GCPTR(pDevIns) ( (GCPTRTYPE(PPDMDEVINS))((RTGCUINTPTR)(pDevIns)->pvInstanceDataGC - RT_OFFSETOF(PDMDEVINS, achInstanceData)) )
5480
5481	/** @def PDMDEVINS_2_HCPTR
5482	* Converts a PDM Device instance pointer a HC PDM Device instance pointer.
5483	*/
5484	#define PDMDEVINS_2_HCPTR(pDevIns) ( (HCPTRTYPE(PPDMDEVINS))((RTHCUINTPTR)(pDevIns)->pvInstanceDataHC - RT_OFFSETOF(PDMDEVINS, achInstanceData)) )
5485
5486
5487	/**
5488	* VBOX_STRICT wrapper for pDevHlp->pfnDBGFStopV.
5489	*
5490	* @returns VBox status code which must be passed up to the VMM.
5491	* @param pDevIns Device instance.
5492	* @param RT_SRC_POS_DECL Use RT_SRC_POS.
5493	* @param pszFormat Message. (optional)
5494	* @param ... Message parameters.
5495	*/
5496	DECLINLINE(int) PDMDeviceDBGFStop(PPDMDEVINS pDevIns, RT_SRC_POS_DECL, const char *pszFormat, ...)
5497	{
5498	#ifdef VBOX_STRICT
5499	# ifdef IN_RING3
5500	int rc;
5501	va_list args;
5502	va_start(args, pszFormat);
5503	rc = pDevIns->pDevHlp->pfnDBGFStopV(pDevIns, RT_SRC_POS_ARGS, pszFormat, args);
5504	va_end(args);
5505	return rc;
5506	# else
5507	return VINF_EM_DBG_STOP;
5508	# endif
5509	#else
5510	return VINF_SUCCESS;
5511	#endif
5512	}
5513
5514
5515	#ifdef IN_RING3
5516	/**
5517	* @copydoc PDMDEVHLP::pfnIOPortRegister
5518	*/
5519	DECLINLINE(int) PDMDevHlpIOPortRegister(PPDMDEVINS pDevIns, RTIOPORT Port, RTUINT cPorts, RTHCPTR pvUser,
5520	PFNIOMIOPORTOUT pfnOut, PFNIOMIOPORTIN pfnIn,
5521	PFNIOMIOPORTOUTSTRING pfnOutStr, PFNIOMIOPORTINSTRING pfnInStr, const char *pszDesc)
5522	{
5523	return pDevIns->pDevHlp->pfnIOPortRegister(pDevIns, Port, cPorts, pvUser, pfnOut, pfnIn, pfnOutStr, pfnInStr, pszDesc);
5524	}
5525
5526	/**
5527	* @copydoc PDMDEVHLP::pfnIOPortRegisterGC
5528	*/
5529	DECLINLINE(int) PDMDevHlpIOPortRegisterGC(PPDMDEVINS pDevIns, RTIOPORT Port, RTUINT cPorts, RTGCPTR pvUser,
5530	const char pszOut, const char pszIn, const char *pszOutStr,
5531	const char pszInStr, const char pszDesc)
5532	{
5533	return pDevIns->pDevHlp->pfnIOPortRegisterGC(pDevIns, Port, cPorts, pvUser, pszOut, pszIn, pszOutStr, pszInStr, pszDesc);
5534	}
5535
5536	/**
5537	* @copydoc PDMDEVHLP::pfnIOPortRegisterR0
5538	*/
5539	DECLINLINE(int) PDMDevHlpIOPortRegisterR0(PPDMDEVINS pDevIns, RTIOPORT Port, RTUINT cPorts, RTHCPTR pvUser,
5540	const char pszOut, const char pszIn, const char *pszOutStr,
5541	const char pszInStr, const char pszDesc)
5542	{
5543	return pDevIns->pDevHlp->pfnIOPortRegisterR0(pDevIns, Port, cPorts, pvUser, pszOut, pszIn, pszOutStr, pszInStr, pszDesc);
5544	}
5545
5546	/**
5547	* @copydoc PDMDEVHLP::pfnMMIORegister
5548	*/
5549	DECLINLINE(int) PDMDevHlpMMIORegister(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange, RTHCPTR pvUser,
5550	PFNIOMMMIOWRITE pfnWrite, PFNIOMMMIOREAD pfnRead, PFNIOMMMIOFILL pfnFill,
5551	const char *pszDesc)
5552	{
5553	return pDevIns->pDevHlp->pfnMMIORegister(pDevIns, GCPhysStart, cbRange, pvUser, pfnWrite, pfnRead, pfnFill, pszDesc);
5554	}
5555
5556	/**
5557	* @copydoc PDMDEVHLP::pfnMMIORegisterGC
5558	*/
5559	DECLINLINE(int) PDMDevHlpMMIORegisterGC(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange, RTGCPTR pvUser,
5560	const char pszWrite, const char pszRead, const char pszFill, const char pszDesc)
5561	{
5562	return pDevIns->pDevHlp->pfnMMIORegisterGC(pDevIns, GCPhysStart, cbRange, pvUser, pszWrite, pszRead, pszFill, pszDesc);
5563	}
5564
5565	/**
5566	* @copydoc PDMDEVHLP::pfnMMIORegisterR0
5567	*/
5568	DECLINLINE(int) PDMDevHlpMMIORegisterR0(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange, RTHCPTR pvUser,
5569	const char pszWrite, const char pszRead, const char pszFill, const char pszDesc)
5570	{
5571	return pDevIns->pDevHlp->pfnMMIORegisterR0(pDevIns, GCPhysStart, cbRange, pvUser, pszWrite, pszRead, pszFill, pszDesc);
5572	}
5573
5574	/**
5575	* @copydoc PDMDEVHLP::pfnROMRegister
5576	*/
5577	DECLINLINE(int) PDMDevHlpROMRegister(PPDMDEVINS pDevIns, RTGCPHYS GCPhysStart, RTUINT cbRange, const void pvBinary, const char pszDesc)
5578	{
5579	return pDevIns->pDevHlp->pfnROMRegister(pDevIns, GCPhysStart, cbRange, pvBinary, pszDesc);
5580	}
5581
5582	/**
5583	* @copydoc PDMDEVHLP::pfnSSMRegister
5584	*/
5585	DECLINLINE(int) PDMDevHlpSSMRegister(PPDMDEVINS pDevIns, const char *pszName, uint32_t u32Instance, uint32_t u32Version, size_t cbGuess,
5586	PFNSSMDEVSAVEPREP pfnSavePrep, PFNSSMDEVSAVEEXEC pfnSaveExec, PFNSSMDEVSAVEDONE pfnSaveDone,
5587	PFNSSMDEVLOADPREP pfnLoadPrep, PFNSSMDEVLOADEXEC pfnLoadExec, PFNSSMDEVLOADDONE pfnLoadDone)
5588	{
5589	return pDevIns->pDevHlp->pfnSSMRegister(pDevIns, pszName, u32Instance, u32Version, cbGuess,
5590	pfnSavePrep, pfnSaveExec, pfnSaveDone,
5591	pfnLoadPrep, pfnLoadExec, pfnLoadDone);
5592	}
5593
5594	/**
5595	* @copydoc PDMDEVHLP::pfnTMTimerCreate
5596	*/
5597	DECLINLINE(int) PDMDevHlpTMTimerCreate(PPDMDEVINS pDevIns, TMCLOCK enmClock, PFNTMTIMERDEV pfnCallback, const char *pszDesc, PPTMTIMERHC ppTimer)
5598	{
5599	return pDevIns->pDevHlp->pfnTMTimerCreate(pDevIns, enmClock, pfnCallback, pszDesc, ppTimer);
5600	}
5601
5602	/**
5603	* @copydoc PDMDEVHLP::pfnPCIRegister
5604	*/
5605	DECLINLINE(int) PDMDevHlpPCIRegister(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev)
5606	{
5607	return pDevIns->pDevHlp->pfnPCIRegister(pDevIns, pPciDev);
5608	}
5609
5610	/**
5611	* @copydoc PDMDEVHLP::pfnPCIIORegionRegister
5612	*/
5613	DECLINLINE(int) PDMDevHlpPCIIORegionRegister(PPDMDEVINS pDevIns, int iRegion, uint32_t cbRegion, PCIADDRESSSPACE enmType, PFNPCIIOREGIONMAP pfnCallback)
5614	{
5615	return pDevIns->pDevHlp->pfnPCIIORegionRegister(pDevIns, iRegion, cbRegion, enmType, pfnCallback);
5616	}
5617
5618	/**
5619	* @copydoc PDMDEVHLP::pfnDriverAttach
5620	*/
5621	DECLINLINE(int) PDMDevHlpDriverAttach(PPDMDEVINS pDevIns, RTUINT iLun, PPDMIBASE pBaseInterface, PPDMIBASE ppBaseInterface, const char pszDesc)
5622	{
5623	return pDevIns->pDevHlp->pfnDriverAttach(pDevIns, iLun, pBaseInterface, ppBaseInterface, pszDesc);
5624	}
5625
5626	/**
5627	* @copydoc PDMDEVHLP::pfnMMHeapAlloc
5628	*/
5629	DECLINLINE(void *) PDMDevHlpMMHeapAlloc(PPDMDEVINS pDevIns, size_t cb)
5630	{
5631	return pDevIns->pDevHlp->pfnMMHeapAlloc(pDevIns, cb);
5632	}
5633
5634	/**
5635	* @copydoc PDMDEVHLP::pfnMMHeapAllocZ
5636	*/
5637	DECLINLINE(void *) PDMDevHlpMMHeapAllocZ(PPDMDEVINS pDevIns, size_t cb)
5638	{
5639	return pDevIns->pDevHlp->pfnMMHeapAllocZ(pDevIns, cb);
5640	}
5641
5642	/**
5643	* @copydoc PDMDEVHLP::pfnMMHeapFree
5644	*/
5645	DECLINLINE(void) PDMDevHlpMMHeapFree(PPDMDEVINS pDevIns, void *pv)
5646	{
5647	pDevIns->pDevHlp->pfnMMHeapFree(pDevIns, pv);
5648	}
5649
5650	/**
5651	* @copydoc PDMDEVHLP::pfnDBGFInfoRegister
5652	*/
5653	DECLINLINE(int) PDMDevHlpDBGFInfoRegister(PPDMDEVINS pDevIns, const char pszName, const char pszDesc, PFNDBGFHANDLERDEV pfnHandler)
5654	{
5655	return pDevIns->pDevHlp->pfnDBGFInfoRegister(pDevIns, pszName, pszDesc, pfnHandler);
5656	}
5657
5658	/**
5659	* @copydoc PDMDEVHLP::pfnSTAMRegister
5660	*/
5661	DECLINLINE(void) PDMDevHlpSTAMRegister(PPDMDEVINS pDevIns, void pvSample, STAMTYPE enmType, const char pszName, STAMUNIT enmUnit, const char *pszDesc)
5662	{
5663	pDevIns->pDevHlp->pfnSTAMRegister(pDevIns, pvSample, enmType, pszName, enmUnit, pszDesc);
5664	}
5665
5666	/**
5667	* @copydoc PDMDEVHLP::pfnSTAMRegisterF
5668	*/
5669	DECLINLINE(void) PDMDevHlpSTAMRegisterF(PPDMDEVINS pDevIns, void *pvSample, STAMTYPE enmType, STAMVISIBILITY enmVisibility, STAMUNIT enmUnit,
5670	const char pszDesc, const char pszName, ...)
5671	{
5672	va_list va;
5673	va_start(va, pszName);
5674	pDevIns->pDevHlp->pfnSTAMRegisterV(pDevIns, pvSample, enmType, enmVisibility, enmUnit, pszDesc, pszName, va);
5675	va_end(va);
5676	}
5677
5678	/**
5679	* @copydoc PDMDEVHLP::pfnPDMQueueCreate
5680	*/
5681	DECLINLINE(int) PDMDevHlpPDMQueueCreate(PPDMDEVINS pDevIns, RTUINT cbItem, RTUINT cItems, uint32_t cMilliesInterval,
5682	PFNPDMQUEUEDEV pfnCallback, bool fGCEnabled, PPDMQUEUE *ppQueue)
5683	{
5684	return pDevIns->pDevHlp->pfnPDMQueueCreate(pDevIns, cbItem, cItems, cMilliesInterval, pfnCallback, fGCEnabled, ppQueue);
5685	}
5686
5687	/**
5688	* @copydoc PDMDEVHLP::pfnCritSectInit
5689	*/
5690	DECLINLINE(int) PDMDevHlpCritSectInit(PPDMDEVINS pDevIns, PPDMCRITSECT pCritSect, const char *pszName)
5691	{
5692	return pDevIns->pDevHlp->pfnCritSectInit(pDevIns, pCritSect, pszName);
5693	}
5694
5695	/**
5696	* @copydoc PDMDEVHLP::pfnGetVM
5697	*/
5698	DECLINLINE(PVM) PDMDevHlpGetVM(PPDMDEVINS pDevIns)
5699	{
5700	return pDevIns->pDevHlp->pfnGetVM(pDevIns);
5701	}
5702
5703	/**
5704	* @copydoc PDMDEVHLP::pfnPhysReadGCVirt
5705	*/
5706	DECLINLINE(int) PDMDevHlpPhysReadGCVirt(PPDMDEVINS pDevIns, void *pvDst, RTGCPTR GCVirtSrc, size_t cb)
5707	{
5708	return pDevIns->pDevHlp->pfnPhysReadGCVirt(pDevIns, pvDst, GCVirtSrc, cb);
5709	}
5710
5711	/**
5712	* @copydoc PDMDEVHLP::pfnPhysWriteGCVirt
5713	*/
5714	DECLINLINE(int) PDMDevHlpPhysWriteGCVirt(PPDMDEVINS pDevIns, RTGCPTR GCVirtDst, const void *pvSrc, size_t cb)
5715	{
5716	return pDevIns->pDevHlp->pfnPhysWriteGCVirt(pDevIns, GCVirtDst, pvSrc, cb);
5717	}
5718
5719	/**
5720	* @copydoc PDMDEVHLP::pfnPhysReserve
5721	*/
5722	DECLINLINE(int) PDMDevHlpPhysReserve(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTUINT cbRange, const char *pszDesc)
5723	{
5724	return pDevIns->pDevHlp->pfnPhysReserve(pDevIns, GCPhys, cbRange, pszDesc);
5725	}
5726
5727	/**
5728	* @copydoc PDMDEVHLP::pfnPhys2HCVirt
5729	*/
5730	DECLINLINE(int) PDMDevHlpPhys2HCVirt(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, RTUINT cbRange, PRTHCPTR ppvHC)
5731	{
5732	return pDevIns->pDevHlp->pfnPhys2HCVirt(pDevIns, GCPhys, cbRange, ppvHC);
5733	}
5734
5735	/**
5736	* @copydoc PDMDEVHLP::pfnPhysGCPtr2HCPtr
5737	*/
5738	DECLINLINE(int) PDMDevHlpPhysGCPtr2HCPtr(PPDMDEVINS pDevIns, RTGCPTR GCPtr, PRTHCPTR pHCPtr)
5739	{
5740	return pDevIns->pDevHlp->pfnPhysGCPtr2HCPtr(pDevIns, GCPtr, pHCPtr);
5741	}
5742
5743	/**
5744	* @copydoc PDMDEVHLP::pfnA20Set
5745	*/
5746	DECLINLINE(void) PDMDevHlpA20Set(PPDMDEVINS pDevIns, bool fEnable)
5747	{
5748	pDevIns->pDevHlp->pfnA20Set(pDevIns, fEnable);
5749	}
5750
5751	/**
5752	* @copydoc PDMDEVHLP::pfnVMReset
5753	*/
5754	DECLINLINE(int) PDMDevHlpVMReset(PPDMDEVINS pDevIns)
5755	{
5756	return pDevIns->pDevHlp->pfnVMReset(pDevIns);
5757	}
5758
5759	/**
5760	* @copydoc PDMDEVHLP::pfnVMSuspend
5761	*/
5762	DECLINLINE(int) PDMDevHlpVMSuspend(PPDMDEVINS pDevIns)
5763	{
5764	return pDevIns->pDevHlp->pfnVMSuspend(pDevIns);
5765	}
5766
5767	/**
5768	* @copydoc PDMDEVHLP::pfnVMPowerOff
5769	*/
5770	DECLINLINE(int) PDMDevHlpVMPowerOff(PPDMDEVINS pDevIns)
5771	{
5772	return pDevIns->pDevHlp->pfnVMPowerOff(pDevIns);
5773	}
5774
5775	/**
5776	* @copydoc PDMDEVHLP::pfnDMARegister
5777	*/
5778	DECLINLINE(int) PDMDevHlpDMARegister(PPDMDEVINS pDevIns, unsigned uChannel, PFNDMATRANSFERHANDLER pfnTransferHandler, void *pvUser)
5779	{
5780	return pDevIns->pDevHlp->pfnDMARegister(pDevIns, uChannel, pfnTransferHandler, pvUser);
5781	}
5782
5783	/**
5784	* @copydoc PDMDEVHLP::pfnDMAReadMemory
5785	*/
5786	DECLINLINE(int) PDMDevHlpDMAReadMemory(PPDMDEVINS pDevIns, unsigned uChannel, void pvBuffer, uint32_t off, uint32_t cbBlock, uint32_t pcbRead)
5787	{
5788	return pDevIns->pDevHlp->pfnDMAReadMemory(pDevIns, uChannel, pvBuffer, off, cbBlock, pcbRead);
5789	}
5790
5791	/**
5792	* @copydoc PDMDEVHLP::pfnDMAWriteMemory
5793	*/
5794	DECLINLINE(int) PDMDevHlpDMAWriteMemory(PPDMDEVINS pDevIns, unsigned uChannel, const void pvBuffer, uint32_t off, uint32_t cbBlock, uint32_t pcbWritten)
5795	{
5796	return pDevIns->pDevHlp->pfnDMAWriteMemory(pDevIns, uChannel, pvBuffer, off, cbBlock, pcbWritten);
5797	}
5798
5799	/**
5800	* @copydoc PDMDEVHLP::pfnDMASetDREQ
5801	*/
5802	DECLINLINE(int) PDMDevHlpDMASetDREQ(PPDMDEVINS pDevIns, unsigned uChannel, unsigned uLevel)
5803	{
5804	return pDevIns->pDevHlp->pfnDMASetDREQ(pDevIns, uChannel, uLevel);
5805	}
5806
5807	/**
5808	* @copydoc PDMDEVHLP::pfnDMAGetChannelMode
5809	*/
5810	DECLINLINE(uint8_t) PDMDevHlpDMAGetChannelMode(PPDMDEVINS pDevIns, unsigned uChannel)
5811	{
5812	return pDevIns->pDevHlp->pfnDMAGetChannelMode(pDevIns, uChannel);
5813	}
5814
5815	/**
5816	* @copydoc PDMDEVHLP::pfnDMASchedule
5817	*/
5818	DECLINLINE(void) PDMDevHlpDMASchedule(PPDMDEVINS pDevIns)
5819	{
5820	pDevIns->pDevHlp->pfnDMASchedule(pDevIns);
5821	}
5822
5823	/**
5824	* @copydoc PDMDEVHLP::pfnCMOSWrite
5825	*/
5826	DECLINLINE(int) PDMDevHlpCMOSWrite(PPDMDEVINS pDevIns, unsigned iReg, uint8_t u8Value)
5827	{
5828	return pDevIns->pDevHlp->pfnCMOSWrite(pDevIns, iReg, u8Value);
5829	}
5830
5831	/**
5832	* @copydoc PDMDEVHLP::pfnCMOSRead
5833	*/
5834	DECLINLINE(int) PDMDevHlpCMOSRead(PPDMDEVINS pDevIns, unsigned iReg, uint8_t *pu8Value)
5835	{
5836	return pDevIns->pDevHlp->pfnCMOSRead(pDevIns, iReg, pu8Value);
5837	}
5838	#endif /* IN_RING3 */
5839
5840
5841	/**
5842	* @copydoc PDMDEVHLP::pfnPCISetIrq
5843	*/
5844	DECLINLINE(void) PDMDevHlpPCISetIrq(PPDMDEVINS pDevIns, int iIrq, int iLevel)
5845	{
5846	#ifdef IN_GC
5847	pDevIns->pDevHlpGC->pfnPCISetIrq(pDevIns, iIrq, iLevel);
5848	#elif defined(IN_RING0)
5849	pDevIns->pDevHlpR0->pfnPCISetIrq(pDevIns, iIrq, iLevel);
5850	#else
5851	pDevIns->pDevHlp->pfnPCISetIrq(pDevIns, iIrq, iLevel);
5852	#endif
5853	}
5854
5855	/**
5856	* @copydoc PDMDEVHLP::pfnPCISetIrqNoWait
5857	*/
5858	DECLINLINE(void) PDMDevHlpPCISetIrqNoWait(PPDMDEVINS pDevIns, int iIrq, int iLevel)
5859	{
5860	#ifdef IN_GC
5861	pDevIns->pDevHlpGC->pfnPCISetIrq(pDevIns, iIrq, iLevel);
5862	#elif defined(IN_RING0)
5863	pDevIns->pDevHlpR0->pfnPCISetIrq(pDevIns, iIrq, iLevel);
5864	#else
5865	pDevIns->pDevHlp->pfnPCISetIrqNoWait(pDevIns, iIrq, iLevel);
5866	#endif
5867	}
5868
5869	/**
5870	* @copydoc PDMDEVHLP::pfnISASetIrq
5871	*/
5872	DECLINLINE(void) PDMDevHlpISASetIrq(PPDMDEVINS pDevIns, int iIrq, int iLevel)
5873	{
5874	#ifdef IN_GC
5875	pDevIns->pDevHlpGC->pfnISASetIrq(pDevIns, iIrq, iLevel);
5876	#elif defined(IN_RING0)
5877	pDevIns->pDevHlpR0->pfnISASetIrq(pDevIns, iIrq, iLevel);
5878	#else
5879	pDevIns->pDevHlp->pfnISASetIrq(pDevIns, iIrq, iLevel);
5880	#endif
5881	}
5882
5883	/**
5884	* @copydoc PDMDEVHLP::pfnISASetIrqNoWait
5885	*/
5886	DECLINLINE(void) PDMDevHlpISASetIrqNoWait(PPDMDEVINS pDevIns, int iIrq, int iLevel)
5887	{
5888	#ifdef IN_GC
5889	pDevIns->pDevHlpGC->pfnISASetIrq(pDevIns, iIrq, iLevel);
5890	#elif defined(IN_RING0)
5891	pDevIns->pDevHlpR0->pfnISASetIrq(pDevIns, iIrq, iLevel);
5892	#else
5893	pDevIns->pDevHlp->pfnISASetIrqNoWait(pDevIns, iIrq, iLevel);
5894	#endif
5895	}
5896
5897	/**
5898	* @copydoc PDMDEVHLP::pfnPhysRead
5899	*/
5900	DECLINLINE(void) PDMDevHlpPhysRead(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, void *pvBuf, size_t cbRead)
5901	{
5902	#ifdef IN_GC
5903	pDevIns->pDevHlpGC->pfnPhysRead(pDevIns, GCPhys, pvBuf, cbRead);
5904	#elif defined(IN_RING0)
5905	pDevIns->pDevHlpR0->pfnPhysRead(pDevIns, GCPhys, pvBuf, cbRead);
5906	#else
5907	pDevIns->pDevHlp->pfnPhysRead(pDevIns, GCPhys, pvBuf, cbRead);
5908	#endif
5909	}
5910
5911	/**
5912	* @copydoc PDMDEVHLP::pfnPhysWrite
5913	*/
5914	DECLINLINE(void) PDMDevHlpPhysWrite(PPDMDEVINS pDevIns, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite)
5915	{
5916	#ifdef IN_GC
5917	pDevIns->pDevHlpGC->pfnPhysWrite(pDevIns, GCPhys, pvBuf, cbWrite);
5918	#elif defined(IN_RING0)
5919	pDevIns->pDevHlpR0->pfnPhysWrite(pDevIns, GCPhys, pvBuf, cbWrite);
5920	#else
5921	pDevIns->pDevHlp->pfnPhysWrite(pDevIns, GCPhys, pvBuf, cbWrite);
5922	#endif
5923	}
5924
5925	/**
5926	* @copydoc PDMDEVHLP::pfnA20IsEnabled
5927	*/
5928	DECLINLINE(bool) PDMDevHlpA20IsEnabled(PPDMDEVINS pDevIns)
5929	{
5930	#ifdef IN_GC
5931	return pDevIns->pDevHlpGC->pfnA20IsEnabled(pDevIns);
5932	#elif defined(IN_RING0)
5933	return pDevIns->pDevHlpR0->pfnA20IsEnabled(pDevIns);
5934	#else
5935	return pDevIns->pDevHlp->pfnA20IsEnabled(pDevIns);
5936	#endif
5937	}
5938
5939	/**
5940	* @copydoc PDMDEVHLP::pfnVMSetError
5941	*/
5942	DECLINLINE(int) PDMDevHlpVMSetError(PPDMDEVINS pDevIns, const int rc, RT_SRC_POS_DECL, const char *pszFormat, ...)
5943	{
5944	va_list va;
5945	va_start(va, pszFormat);
5946	#ifdef IN_GC
5947	pDevIns->pDevHlpGC->pfnVMSetErrorV(pDevIns, rc, RT_SRC_POS_ARGS, pszFormat, va);
5948	#elif defined(IN_RING0)
5949	pDevIns->pDevHlpR0->pfnVMSetErrorV(pDevIns, rc, RT_SRC_POS_ARGS, pszFormat, va);
5950	#else
5951	pDevIns->pDevHlp->pfnVMSetErrorV(pDevIns, rc, RT_SRC_POS_ARGS, pszFormat, va);
5952	#endif
5953	va_end(va);
5954	return rc;
5955	}
5956
5957
5958
5959	/** Pointer to callbacks provided to the VBoxDeviceRegister() call. */
5960	typedef struct PDMDEVREGCB *PPDMDEVREGCB;
5961
5962	/**
5963	* Callbacks for VBoxDeviceRegister().
5964	*/
5965	typedef struct PDMDEVREGCB
5966	{
5967	/** Interface version.
5968	* This is set to PDM_DEVREG_CB_VERSION. */
5969	uint32_t u32Version;
5970
5971	/**
5972	* Registers a device with the current VM instance.
5973	*
5974	* @returns VBox status code.
5975	* @param pCallbacks Pointer to the callback table.
5976	* @param pDevReg Pointer to the device registration record.
5977	* This data must be permanent and readonly.
5978	*/
5979	DECLR3CALLBACKMEMBER(int, pfnRegister,(PPDMDEVREGCB pCallbacks, PCPDMDEVREG pDevReg));
5980
5981	/**
5982	* Allocate memory which is associated with current VM instance
5983	* and automatically freed on it's destruction.
5984	*
5985	* @returns Pointer to allocated memory. The memory is NOT zero-ed.
5986	* @param pCallbacks Pointer to the callback table.
5987	* @param cb Number of bytes to allocate.
5988	*/
5989	DECLR3CALLBACKMEMBER(void *, pfnMMHeapAlloc,(PPDMDEVREGCB pCallbacks, size_t cb));
5990	} PDMDEVREGCB;
5991
5992	/** Current version of the PDMDEVREGCB structure. */
5993	#define PDM_DEVREG_CB_VERSION 0xf4010000
5994
5995
5996	/**
5997	* The VBoxDevicesRegister callback function.
5998	*
5999	* PDM will invoke this function after loading a device module and letting
6000	* the module decide which devices to register and how to handle conflicts.
6001	*
6002	* @returns VBox status code.
6003	* @param pCallbacks Pointer to the callback table.
6004	* @param u32Version VBox version number.
6005	*/
6006	typedef DECLCALLBACK(int) FNPDMVBOXDEVICESREGISTER(PPDMDEVREGCB pCallbacks, uint32_t u32Version);
6007
6008	/** @} */
6009
6010
6011
6012
6013	/** @defgroup grp_pdm_services Services
6014	* @ingroup grp_pdm
6015	* @{ */
6016
6017
6018	/**
6019	* Construct a service instance for a VM.
6020	*
6021	* @returns VBox status.
6022	* @param pSrvIns The service instance data.
6023	* If the registration structure is needed, pSrvIns->pReg points to it.
6024	* @param pCfg Configuration node handle for the service. Use this to obtain the configuration
6025	* of the driver instance. It's also found in pSrvIns->pCfg, but since it's primary
6026	* usage is expected in this function it is passed as a parameter.
6027	*/
6028	typedef DECLCALLBACK(int) FNPDMSRVCONSTRUCT(PPDMSRVINS pSrvIns, PCFGMNODE pCfg);
6029	/** Pointer to a FNPDMSRVCONSTRUCT() function. */
6030	typedef FNPDMSRVCONSTRUCT *PFNPDMSRVCONSTRUCT;
6031
6032	/**
6033	* Destruct a driver instance.
6034	*
6035	* Most VM resources are freed by the VM. This callback is provided so that any non-VM
6036	* resources can be freed correctly.
6037	*
6038	* @param pSrvIns The service instance data.
6039	*/
6040	typedef DECLCALLBACK(void) FNPDMSRVDESTRUCT(PPDMSRVINS pSrvIns);
6041	/** Pointer to a FNPDMSRVDESTRUCT() function. */
6042	typedef FNPDMSRVDESTRUCT *PFNPDMSRVDESTRUCT;
6043
6044	/**
6045	* Power On notification.
6046	*
6047	* @param pSrvIns The service instance data.
6048	*/
6049	typedef DECLCALLBACK(void) FNPDMSRVPOWERON(PPDMSRVINS pSrvIns);
6050	/** Pointer to a FNPDMSRVPOWERON() function. */
6051	typedef FNPDMSRVPOWERON *PFNPDMSRVPOWERON;
6052
6053	/**
6054	* Reset notification.
6055	*
6056	* @returns VBox status.
6057	* @param pSrvIns The service instance data.
6058	*/
6059	typedef DECLCALLBACK(void) FNPDMSRVRESET(PPDMSRVINS pSrvIns);
6060	/** Pointer to a FNPDMSRVRESET() function. */
6061	typedef FNPDMSRVRESET *PFNPDMSRVRESET;
6062
6063	/**
6064	* Suspend notification.
6065	*
6066	* @returns VBox status.
6067	* @param pSrvIns The service instance data.
6068	*/
6069	typedef DECLCALLBACK(void) FNPDMSRVSUSPEND(PPDMSRVINS pSrvIns);
6070	/** Pointer to a FNPDMSRVSUSPEND() function. */
6071	typedef FNPDMSRVSUSPEND *PFNPDMSRVSUSPEND;
6072
6073	/**
6074	* Resume notification.
6075	*
6076	* @returns VBox status.
6077	* @param pSrvIns The service instance data.
6078	*/
6079	typedef DECLCALLBACK(void) FNPDMSRVRESUME(PPDMSRVINS pSrvIns);
6080	/** Pointer to a FNPDMSRVRESUME() function. */
6081	typedef FNPDMSRVRESUME *PFNPDMSRVRESUME;
6082
6083	/**
6084	* Power Off notification.
6085	*
6086	* @param pSrvIns The service instance data.
6087	*/
6088	typedef DECLCALLBACK(void) FNPDMSRVPOWEROFF(PPDMSRVINS pSrvIns);
6089	/** Pointer to a FNPDMSRVPOWEROFF() function. */
6090	typedef FNPDMSRVPOWEROFF *PFNPDMSRVPOWEROFF;
6091
6092	/**
6093	* Detach notification.
6094	*
6095	* This is called when a driver or device is detached from the service
6096	*
6097	* @param pSrvIns The service instance data.
6098	*/
6099	typedef DECLCALLBACK(void) FNPDMSRVDETACH(PPDMSRVINS pSrvIns, PPDMDEVINS pDevIns, PPDMDRVINS pDrvIns);
6100	/** Pointer to a FNPDMSRVDETACH() function. */
6101	typedef FNPDMSRVDETACH *PFNPDMSRVDETACH;
6102
6103
6104
6105	/** PDM Service Registration Structure,
6106	* This structure is used when registering a driver from
6107	* VBoxServicesRegister() (HC Ring-3). PDM will continue use till
6108	* the VM is terminated.
6109	*/
6110	typedef struct PDMSRVREG
6111	{
6112	/** Structure version. PDM_SRVREG_VERSION defines the current version. */
6113	uint32_t u32Version;
6114	/** Driver name. */
6115	char szServiceName[32];
6116	/** The description of the driver. The UTF-8 string pointed to shall, like this structure,
6117	* remain unchanged from registration till VM destruction. */
6118	const char *pszDescription;
6119
6120	/** Flags, combination of the PDM_SRVREG_FLAGS_* \#defines. */
6121	RTUINT fFlags;
6122	/** Size of the instance data. */
6123	RTUINT cbInstance;
6124
6125	/** Construct instance - required. */
6126	PFNPDMSRVCONSTRUCT pfnConstruct;
6127	/** Destruct instance - optional. */
6128	PFNPDMSRVDESTRUCT pfnDestruct;
6129	/** Power on notification - optional. */
6130	PFNPDMSRVPOWERON pfnPowerOn;
6131	/** Reset notification - optional. */
6132	PFNPDMSRVRESET pfnReset;
6133	/** Suspend notification - optional. */
6134	PFNPDMSRVSUSPEND pfnSuspend;
6135	/** Resume notification - optional. */
6136	PFNPDMSRVRESUME pfnResume;
6137	/** Detach notification - optional. */
6138	PFNPDMSRVDETACH pfnDetach;
6139	/** Power off notification - optional. */
6140	PFNPDMSRVPOWEROFF pfnPowerOff;
6141
6142	} PDMSRVREG;
6143	/** Pointer to a PDM Driver Structure. */
6144	typedef PDMSRVREG *PPDMSRVREG;
6145	/** Const pointer to a PDM Driver Structure. */
6146	typedef PDMSRVREG const *PCPDMSRVREG;
6147
6148
6149
6150	/**
6151	* PDM Service API.
6152	*/
6153	typedef struct PDMSRVHLP
6154	{
6155	/** Structure version. PDM_SRVHLP_VERSION defines the current version. */
6156	uint32_t u32Version;
6157
6158	/**
6159	* Assert that the current thread is the emulation thread.
6160	*
6161	* @returns True if correct.
6162	* @returns False if wrong.
6163	* @param pSrvIns Service instance.
6164	* @param pszFile Filename of the assertion location.
6165	* @param iLine Linenumber of the assertion location.
6166	* @param pszFunction Function of the assertion location.
6167	*/
6168	DECLR3CALLBACKMEMBER(bool, pfnAssertEMT,(PPDMSRVINS pSrvIns, const char pszFile, unsigned iLine, const char pszFunction));
6169
6170	/**
6171	* Assert that the current thread is NOT the emulation thread.
6172	*
6173	* @returns True if correct.
6174	* @returns False if wrong.
6175	* @param pSrvIns Service instance.
6176	* @param pszFile Filename of the assertion location.
6177	* @param iLine Linenumber of the assertion location.
6178	* @param pszFunction Function of the assertion location.
6179	*/
6180	DECLR3CALLBACKMEMBER(bool, pfnAssertOther,(PPDMSRVINS pSrvIns, const char pszFile, unsigned iLine, const char pszFunction));
6181
6182	/**
6183	* Creates a timer.
6184	*
6185	* @returns VBox status.
6186	* @param pVM The VM to create the timer in.
6187	* @param pSrvIns Service instance.
6188	* @param enmClock The clock to use on this timer.
6189	* @param pfnCallback Callback function.
6190	* @param pszDesc Pointer to description string which must stay around
6191	* until the timer is fully destroyed (i.e. a bit after TMTimerDestroy()).
6192	* @param ppTimer Where to store the timer on success.
6193	*/
6194	DECLR3CALLBACKMEMBER(int, pfnTMTimerCreate,(PPDMSRVINS pSrvIns, TMCLOCK enmClock, PFNTMTIMERDEV pfnCallback, const char *pszDesc, PPTMTIMERHC ppTimer));
6195
6196	/**
6197	* Query the virtual timer frequency.
6198	*
6199	* @returns Frequency in Hz.
6200	* @param pSrvIns Service instance.
6201	* @thread Any thread.
6202	*/
6203	DECLR3CALLBACKMEMBER(uint64_t, pfnTMGetVirtualFreq,(PPDMSRVINS pSrvIns));
6204
6205	/**
6206	* Query the virtual time.
6207	*
6208	* @returns The current virtual time.
6209	* @param pSrvIns Service instance.
6210	* @thread Any thread.
6211	*/
6212	DECLR3CALLBACKMEMBER(uint64_t, pfnTMGetVirtualTime,(PPDMSRVINS pSrvIns));
6213
6214	} PDMSRVHLP;
6215	/** Pointer PDM Service API. */
6216	typedef PDMSRVHLP *PPDMSRVHLP;
6217	/** Pointer const PDM Service API. */
6218	typedef const PDMSRVHLP *PCPDMSRVHLP;
6219
6220	/** Current SRVHLP version number. */
6221	#define PDM_SRVHLP_VERSION 0xf9010000
6222
6223
6224	/**
6225	* PDM Service Instance.
6226	*/
6227	typedef struct PDMSRVINS
6228	{
6229	/** Structure version. PDM_SRVINS_VERSION defines the current version. */
6230	uint32_t u32Version;
6231
6232	/** Internal data. */
6233	union
6234	{
6235	#ifdef PDMSRVINSINT_DECLARED
6236	PDMSRVINSINT s;
6237	#endif
6238	uint8_t padding[HC_ARCH_BITS == 32 ? 32 : 32];
6239	} Internal;
6240
6241	/** Pointer the PDM Service API. */
6242	HCPTRTYPE(PCPDMSRVHLP) pHlp;
6243	/** Pointer to driver registration structure. */
6244	HCPTRTYPE(PCPDMSRVREG) pReg;
6245	/** Configuration handle. */
6246	HCPTRTYPE(PCFGMNODE) pCfg;
6247	/** The base interface of the service.
6248	* The service constructor initializes this. */
6249	PDMIBASE IBase;
6250	/* padding to make achInstanceData aligned at 16 byte boundrary. */
6251	uint32_t au32Padding[2];
6252	/** Pointer to driver instance data. */
6253	HCPTRTYPE(void *) pvInstanceData;
6254	/** Driver instance data. The size of this area is defined
6255	* in the PDMSRVREG::cbInstanceData field. */
6256	char achInstanceData[4];
6257	} PDMSRVINS;
6258
6259	/** Current PDMSRVREG version number. */
6260	#define PDM_SRVINS_VERSION 0xf7010000
6261
6262	/** Converts a pointer to the PDMSRVINS::IBase to a pointer to PDMSRVINS. */
6263	#define PDMIBASE_2_PDMSRV(pInterface) ( (PPDMSRVINS)((char *)(pInterface) - RT_OFFSETOF(PDMSRVINS, IBase)) )
6264
6265
6266
6267	/** Pointer to callbacks provided to the VBoxServiceRegister() call. */
6268	typedef struct PDMSRVREGCB *PPDMSRVREGCB;
6269
6270	/**
6271	* Callbacks for VBoxServiceRegister().
6272	*/
6273	typedef struct PDMSRVREGCB
6274	{
6275	/** Interface version.
6276	* This is set to PDM_SRVREG_CB_VERSION. */
6277	uint32_t u32Version;
6278
6279	/**
6280	* Registers a service with the current VM instance.
6281	*
6282	* @returns VBox status code.
6283	* @param pCallbacks Pointer to the callback table.
6284	* @param pSrvReg Pointer to the device registration record.
6285	* This data must be permanent and readonly.
6286	*/
6287	DECLR3CALLBACKMEMBER(int, pfnRegister,(PPDMSRVREGCB pCallbacks, PCPDMSRVREG pSrvReg));
6288	} PDMSRVREGCB;
6289
6290	/** Current version of the PDMSRVREGCB structure. */
6291	#define PDM_SRVREG_CB_VERSION 0xf8010000
6292
6293
6294	/**
6295	* The VBoxServicesRegister callback function.
6296	*
6297	* PDM will invoke this function after loading a device module and letting
6298	* the module decide which devices to register and how to handle conflicts.
6299	*
6300	* @returns VBox status code.
6301	* @param pCallbacks Pointer to the callback table.
6302	* @param u32Version VBox version number.
6303	*/
6304	typedef DECLCALLBACK(int) FNPDMVBOXSERVICESREGISTER(PPDMSRVREGCB pCallbacks, uint32_t u32Version);
6305
6306
6307	/** @} */
6308
6309	/**
6310	* Gets the pending interrupt.
6311	*
6312	* @returns VBox status code.
6313	* @param pVM VM handle.
6314	* @param pu8Interrupt Where to store the interrupt on success.
6315	*/
6316	PDMDECL(int) PDMGetInterrupt(PVM pVM, uint8_t *pu8Interrupt);
6317
6318	/**
6319	* Sets the pending ISA interrupt.
6320	*
6321	* @returns VBox status code.
6322	* @param pVM VM handle.
6323	* @param u8Irq The IRQ line.
6324	* @param u8Level The new level.
6325	*/
6326	PDMDECL(int) PDMIsaSetIrq(PVM pVM, uint8_t u8Irq, uint8_t u8Level);
6327
6328	/**
6329	* Sets the pending I/O APIC interrupt.
6330	*
6331	* @returns VBox status code.
6332	* @param pVM VM handle.
6333	* @param u8Irq The IRQ line.
6334	* @param u8Level The new level.
6335	*/
6336	PDMDECL(int) PDMIoApicSetIrq(PVM pVM, uint8_t u8Irq, uint8_t u8Level);
6337
6338	/**
6339	* Set the APIC base.
6340	*
6341	* @returns VBox status code.
6342	* @param pVM VM handle.
6343	* @param u64Base The new base.
6344	*/
6345	PDMDECL(int) PDMApicSetBase(PVM pVM, uint64_t u64Base);
6346
6347	/**
6348	* Get the APIC base.
6349	*
6350	* @returns VBox status code.
6351	* @param pVM VM handle.
6352	* @param pu64Base Where to store the APIC base.
6353	*/
6354	PDMDECL(int) PDMApicGetBase(PVM pVM, uint64_t *pu64Base);
6355
6356	/**
6357	* Set the TPR (task priority register?).
6358	*
6359	* @returns VBox status code.
6360	* @param pVM VM handle.
6361	* @param u8TPR The new TPR.
6362	*/
6363	PDMDECL(int) PDMApicSetTPR(PVM pVM, uint8_t u8TPR);
6364
6365	/**
6366	* Get the TPR (task priority register?).
6367	*
6368	* @returns The current TPR.
6369	* @param pVM VM handle.
6370	* @param pu8TPR Where to store the TRP.
6371	*/
6372	PDMDECL(int) PDMApicGetTPR(PVM pVM, uint8_t *pu8TPR);
6373
6374
6375	#ifdef IN_RING3
6376	/** @defgroup grp_pdm_r3 The PDM Host Context Ring-3 API
6377	* @ingroup grp_pdm
6378	* @{
6379	*/
6380
6381	/**
6382	* Initializes the PDM.
6383	*
6384	* @returns VBox status code.
6385	* @param pVM The VM to operate on.
6386	*/
6387	PDMR3DECL(int) PDMR3Init(PVM pVM);
6388
6389	/**
6390	* This function will notify all the devices and their
6391	* attached drivers about the VM now being powered on.
6392	*
6393	* @param pVM VM Handle.
6394	*/
6395	PDMR3DECL(void) PDMR3PowerOn(PVM pVM);
6396
6397	/**
6398	* This function will notify all the devices and their
6399	* attached drivers about the VM now being reset.
6400	*
6401	* @param pVM VM Handle.
6402	*/
6403	PDMR3DECL(void) PDMR3Reset(PVM pVM);
6404
6405	/**
6406	* This function will notify all the devices and their
6407	* attached drivers about the VM now being reset.
6408	*
6409	* @param pVM VM Handle.
6410	*/
6411	PDMR3DECL(void) PDMR3Suspend(PVM pVM);
6412
6413	/**
6414	* This function will notify all the devices and their
6415	* attached drivers about the VM now being resumed.
6416	*
6417	* @param pVM VM Handle.
6418	*/
6419	PDMR3DECL(void) PDMR3Resume(PVM pVM);
6420
6421	/**
6422	* This function will notify all the devices and their
6423	* attached drivers about the VM being powered off.
6424	*
6425	* @param pVM VM Handle.
6426	*/
6427	PDMR3DECL(void) PDMR3PowerOff(PVM pVM);
6428
6429
6430	/**
6431	* Applies relocations to GC modules.
6432	*
6433	* This must be done very early in the relocation
6434	* process so that components can resolve GC symbols during relocation.
6435	*
6436	* @param pVM VM handle.
6437	* @param offDelta Relocation delta relative to old location.
6438	*/
6439	PDMR3DECL(void) PDMR3LdrRelocate(PVM pVM, RTGCINTPTR offDelta);
6440
6441	/**
6442	* Applies relocations to data and code managed by this
6443	* component. This function will be called at init and
6444	* whenever the VMM need to relocate it self inside the GC.
6445	*
6446	* @param pVM VM handle.
6447	* @param offDelta Relocation delta relative to old location.
6448	*/
6449	PDMR3DECL(void) PDMR3Relocate(PVM pVM, RTGCINTPTR offDelta);
6450
6451	/**
6452	* Terminates the PDM.
6453	*
6454	* Termination means cleaning up and freeing all resources,
6455	* the VM it self is at this point powered off or suspended.
6456	*
6457	* @returns VBox status code.
6458	* @param pVM The VM to operate on.
6459	*/
6460	PDMR3DECL(int) PDMR3Term(PVM pVM);
6461
6462
6463	/**
6464	* Get the address of a symbol in a given HC ring-3 module.
6465	*
6466	* @returns VBox status code.
6467	* @param pVM VM handle.
6468	* @param pszModule Module name.
6469	* @param pszSymbol Symbol name. If it's value is less than 64k it's treated like a
6470	* ordinal value rather than a string pointer.
6471	* @param ppvValue Where to store the symbol value.
6472	*/
6473	PDMR3DECL(int) PDMR3GetSymbolR3(PVM pVM, const char pszModule, const char pszSymbol, void **ppvValue);
6474
6475	/**
6476	* Get the address of a symbol in a given HC ring-0 module.
6477	*
6478	* @returns VBox status code.
6479	* @param pVM VM handle.
6480	* @param pszModule Module name. If NULL the main R0 module (VMMR0.r0) is assumed.
6481	* @param pszSymbol Symbol name. If it's value is less than 64k it's treated like a
6482	* ordinal value rather than a string pointer.
6483	* @param ppvValue Where to store the symbol value.
6484	*/
6485	PDMR3DECL(int) PDMR3GetSymbolR0(PVM pVM, const char pszModule, const char pszSymbol, void **ppvValue);
6486
6487	/**
6488	* Same as PDMR3GetSymbolR0 except that the module will be attempted loaded if not found.
6489	*
6490	* @returns VBox status code.
6491	* @param pVM VM handle.
6492	* @param pszModule Module name. If NULL the main R0 module (VMMR0.r0) is assumed.
6493	* @param pszSymbol Symbol name. If it's value is less than 64k it's treated like a
6494	* ordinal value rather than a string pointer.
6495	* @param ppvValue Where to store the symbol value.
6496	*/
6497	PDMR3DECL(int) PDMR3GetSymbolR0Lazy(PVM pVM, const char pszModule, const char pszSymbol, void **ppvValue);
6498
6499	/**
6500	* Loads a module into the guest context (i.e. into the Hypervisor memory region).
6501	*
6502	* The external (to PDM) use of this interface is to load VMMGC.gc.
6503	*
6504	* @returns VBox status code.
6505	* @param pVM The VM to load it into.
6506	* @param pszFilename Filename of the module binary.
6507	* @param pszName Module name. Case sensitive and the length is limited!
6508	*/
6509	PDMR3DECL(int) PDMR3LoadGC(PVM pVM, const char pszFilename, const char pszName);
6510
6511	/**
6512	* Get the address of a symbol in a given GC module.
6513	*
6514	* @returns VBox status code.
6515	* @param pVM VM handle.
6516	* @param pszModule Module name. If NULL the main GC module (VMMGC.gc) is assumed.
6517	* @param pszSymbol Symbol name. If it's value is less than 64k it's treated like a
6518	* ordinal value rather than a string pointer.
6519	* @param pGCPtrValue Where to store the symbol value.
6520	*/
6521	PDMR3DECL(int) PDMR3GetSymbolGC(PVM pVM, const char pszModule, const char pszSymbol, PRTGCPTR pGCPtrValue);
6522
6523	/**
6524	* Same as PDMR3GetSymbolGC except that the module will be attempted loaded if not found.
6525	*
6526	* @returns VBox status code.
6527	* @param pVM VM handle.
6528	* @param pszModule Module name. If NULL the main GC module (VMMGC.gc) is assumed.
6529	* @param pszSymbol Symbol name. If it's value is less than 64k it's treated like a
6530	* ordinal value rather than a string pointer.
6531	* @param pGCPtrValue Where to store the symbol value.
6532	*/
6533	PDMR3DECL(int) PDMR3GetSymbolGCLazy(PVM pVM, const char pszModule, const char pszSymbol, PRTGCPTR pGCPtrValue);
6534
6535	/**
6536	* Queries module information from an EIP.
6537	*
6538	* This is typically used to locate a crash address.
6539	*
6540	* @returns VBox status code.
6541	* @param pVM VM handle
6542	* @param uEIP EIP to locate.
6543	* @param pszModName Where to store the module name.
6544	* @param cchModName Size of the module name buffer.
6545	* @param pMod Base address of the module.
6546	* @param pszNearSym1 Name of the closes symbol from below.
6547	* @param cchNearSym1 Size of the buffer pointed to by pszNearSym1.
6548	* @param pNearSym1 The address of pszNearSym1.
6549	* @param pszNearSym2 Name of the closes symbol from below.
6550	* @param cchNearSym2 Size of the buffer pointed to by pszNearSym2.
6551	* @param pNearSym2 The address of pszNearSym2.
6552	*/
6553	PDMR3DECL(int) PDMR3QueryModFromEIP(PVM pVM, uint32_t uEIP,
6554	char pszModName, unsigned cchModName, RTGCPTR pMod,
6555	char pszNearSym1, unsigned cchNearSym1, RTGCPTR pNearSym1,
6556	char pszNearSym2, unsigned cchNearSym2, RTGCPTR pNearSym2);
6557
6558
6559	/**
6560	* Module enumeration callback function.
6561	*
6562	* @returns VBox status.
6563	* Failure will stop the search and return the return code.
6564	* Warnings will be ignored and not returned.
6565	* @param pVM VM Handle.
6566	* @param pszFilename Module filename.
6567	* @param pszName Module name. (short and unique)
6568	* @param ImageBase Address where to executable image is loaded.
6569	* @param cbImage Size of the executable image.
6570	* @param fGC Set if guest context, clear if host context.
6571	* @param pvArg User argument.
6572	*/
6573	typedef DECLCALLBACK(int) FNPDMR3ENUM(PVM pVM, const char pszFilename, const char pszName, RTUINTPTR ImageBase, size_t cbImage, bool fGC);
6574	/** Pointer to a FNPDMR3ENUM() function. */
6575	typedef FNPDMR3ENUM *PFNPDMR3ENUM;
6576
6577
6578	/**
6579	* Enumerate all PDM modules.
6580	*
6581	* @returns VBox status.
6582	* @param pVM VM Handle.
6583	* @param pfnCallback Function to call back for each of the modules.
6584	* @param pvArg User argument.
6585	*/
6586	PDMR3DECL(int) PDMR3EnumModules(PVM pVM, PFNPDMR3ENUM pfnCallback, void *pvArg);
6587
6588
6589	/**
6590	* Queries the base interace of a device instance.
6591	*
6592	* The caller can use this to query other interfaces the device implements
6593	* and use them to talk to the device.
6594	*
6595	* @returns VBox status code.
6596	* @param pVM VM handle.
6597	* @param pszDevice Device name.
6598	* @param iInstance Device instance.
6599	* @param ppBase Where to store the pointer to the base device interface on success.
6600	* @remark We're doing any locking ATM, so don't try call this at times when the
6601	* device chain is known to be updated.
6602	*/
6603	PDMR3DECL(int) PDMR3QueryDevice(PVM pVM, const char pszDevice, unsigned iInstance, PPDMIBASE ppBase);
6604
6605	/**
6606	* Queries the base interface of a device LUN.
6607	*
6608	* This differs from PDMR3QueryLun by that it returns the interface on the
6609	* device and not the top level driver.
6610	*
6611	* @returns VBox status code.
6612	* @param pVM VM Handle.
6613	* @param pszDevice Device name.
6614	* @param iInstance Device instance.
6615	* @param iLun The Logical Unit to obtain the interface of.
6616	* @param ppBase Where to store the base interface pointer.
6617	* @remark We're doing any locking ATM, so don't try call this at times when the
6618	* device chain is known to be updated.
6619	*/
6620	PDMR3DECL(int) PDMR3QueryDeviceLun(PVM pVM, const char pszDevice, unsigned iInstance, unsigned iLun, PPDMIBASE ppBase);
6621
6622	/**
6623	* Query the interface of the top level driver on a LUN.
6624	*
6625	* @returns VBox status code.
6626	* @param pVM VM Handle.
6627	* @param pszDevice Device name.
6628	* @param iInstance Device instance.
6629	* @param iLun The Logical Unit to obtain the interface of.
6630	* @param ppBase Where to store the base interface pointer.
6631	* @remark We're doing any locking ATM, so don't try call this at times when the
6632	* device chain is known to be updated.
6633	*/
6634	PDMR3DECL(int) PDMR3QueryLun(PVM pVM, const char pszDevice, unsigned iInstance, unsigned iLun, PPDMIBASE ppBase);
6635
6636	/**
6637	* Attaches a preconfigured driver to an existing device instance.
6638	*
6639	* This is used to change drivers and suchlike at runtime.
6640	*
6641	* @returns VBox status code.
6642	* @param pVM VM Handle.
6643	* @param pszDevice Device name.
6644	* @param iInstance Device instance.
6645	* @param iLun The Logical Unit to obtain the interface of.
6646	* @param ppBase Where to store the base interface pointer. Optional.
6647	* @thread EMT
6648	*/
6649	PDMR3DECL(int) PDMR3DeviceAttach(PVM pVM, const char pszDevice, unsigned iInstance, unsigned iLun, PPDMIBASE ppBase);
6650
6651	/**
6652	* Detaches a driver from an existing device instance.
6653	*
6654	* This is used to change drivers and suchlike at runtime.
6655	*
6656	* @returns VBox status code.
6657	* @param pVM VM Handle.
6658	* @param pszDevice Device name.
6659	* @param iInstance Device instance.
6660	* @param iLun The Logical Unit to obtain the interface of.
6661	* @thread EMT
6662	*/
6663	PDMR3DECL(int) PDMR3DeviceDetach(PVM pVM, const char *pszDevice, unsigned iInstance, unsigned iLun);
6664
6665	/**
6666	* Executes pending DMA transfers.
6667	* Forced Action handler.
6668	*
6669	* @param pVM VM handle.
6670	*/
6671	PDMR3DECL(void) PDMR3DmaRun(PVM pVM);
6672
6673	/**
6674	* Call polling function.
6675	*
6676	* @param pVM VM handle.
6677	*/
6678	PDMR3DECL(void) PDMR3Poll(PVM pVM);
6679
6680	/**
6681	* Serivce a VMMCALLHOST_PDM_LOCK call.
6682	*
6683	* @returns VBox status code.
6684	* @param pVM The VM handle.
6685	*/
6686	PDMR3DECL(int) PDMR3LockCall(PVM pVM);
6687
6688	/** @} */
6689	#endif
6690
6691
6692	#ifdef IN_GC
6693	/** @defgroup grp_pdm_gc The PDM Guest Context API
6694	* @ingroup grp_pdm
6695	* @{
6696	*/
6697	/** @} */
6698	#endif
6699
6700	__END_DECLS
6701
6702	/** @} */
6703
6704	#endif
6705

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

source: vbox/trunk/include/VBox/pdm.h@ 554

Download in other formats: