pdm.h@ 2981

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

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

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

Download in other formats: