pdm.h@ 3112

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

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

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

Download in other formats: