pdm.h@ 3548

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

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

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

Download in other formats: