pdm.h@ 3773

Last change on this file since 3773 was 3773, checked in by vboxsync, 18 years ago
Updates for changing seamless mode.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 266.1 KB

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

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

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

Download in other formats: