pdm.h@ 3110

Last change on this file since 3110 was 3110, checked in by vboxsync, 18 years ago
Added the display index parameter to the SetVideoModeHint (in the guest all hints are still processed only for the primary monitor).
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 248.5 KB

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

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

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

Download in other formats: