pdm.h@ 2246

Last change on this file since 2246 was 2246, checked in by vboxsync, 18 years ago
Input/pckbd.c => Input/DevPS2.cpp
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 241.7 KB

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

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

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

Download in other formats: