pdm.h@ 3525

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

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

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

Download in other formats: