pdm.h@ 3291

Last change on this file since 3291 was 3159, checked in by vboxsync, 17 years ago
Increased the devhlp version since somebody might be using it externally. (don't care too much about the drvhlp version yet, so don't increase it.)
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 255.2 KB

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

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

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

Download in other formats: