pdm.h@ 3781

Last change on this file since 3781 was 3781, checked in by vboxsync, 18 years ago
Correction
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 266.0 KB

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

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

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

Download in other formats: