pdm.h@ 3632

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

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

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

Download in other formats: