pdmifs.h@ 72352

Last change on this file since 72352 was 72352, checked in by vboxsync, 7 years ago
Main, VMMDev: implemented IDisplay::SetScreenLayout, VMMDev multimonitor resize request and VBoxManage controlvm setscreenlayout. bugref:8393
Property svn:eol-style set to `native` Property svn:keywords set to `Id Revision`
File size: 97.4 KB

Line
1	/** @file
2	* PDM - Pluggable Device Manager, Interfaces.
3	*/
4
5	/*
6	* Copyright (C) 2006-2017 Oracle Corporation
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 (GPL) as published by the Free Software
12	* Foundation, in version 2 as it comes in the "COPYING" file of the
13	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15	*
16	* The contents of this file may alternatively be used under the terms
17	* of the Common Development and Distribution License Version 1.0
18	* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19	* VirtualBox OSE distribution, in which case the provisions of the
20	* CDDL are applicable instead of those of the GPL.
21	*
22	* You may elect to license modified versions of this file under the
23	* terms and conditions of either the GPL or the CDDL or both.
24	*/
25
26	#ifndef ___VBox_vmm_pdmifs_h
27	#define ___VBox_vmm_pdmifs_h
28
29	#include <iprt/sg.h>
30	#include <VBox/types.h>
31	#include <VBox/hgcmsvc.h>
32
33
34	RT_C_DECLS_BEGIN
35
36	/** @defgroup grp_pdm_interfaces The PDM Interface Definitions
37	* @ingroup grp_pdm
38	*
39	* For historical reasons (the PDMINTERFACE enum) a lot of interface was stuffed
40	* together in this group instead, dragging stuff into global space that didn't
41	* need to be there and making this file huge (>2500 lines). Since we're using
42	* UUIDs as interface identifiers (IIDs) now, no only generic PDM interface will
43	* be added to this file. Component specific interface should be defined in the
44	* header file of that component.
45	*
46	* Interfaces consists of a method table (typedef'ed struct) and an interface
47	* ID. The typename of the method table should have an 'I' in it, be all
48	* capitals and according to the rules, no underscores. The interface ID is a
49	* \#define constructed by appending '_IID' to the typename. The IID value is a
50	* UUID string on the form "a2299c0d-b709-4551-aa5a-73f59ffbed74". If you stick
51	* to these rules, you can make use of the PDMIBASE_QUERY_INTERFACE and
52	* PDMIBASE_RETURN_INTERFACE when querying interface and implementing
53	* PDMIBASE::pfnQueryInterface respectively.
54	*
55	* In most interface descriptions the orientation of the interface is given as
56	* 'down' or 'up'. This refers to a model with the device on the top and the
57	* drivers stacked below it. Sometimes there is mention of 'main' or 'external'
58	* which normally means the same, i.e. the Main or VBoxBFE API. Picture the
59	* orientation of 'main' as horizontal.
60	*
61	* @{
62	*/
63
64
65	/** @name PDMIBASE
66	* @{
67	*/
68
69	/**
70	* PDM Base Interface.
71	*
72	* Everyone implements this.
73	*/
74	typedef struct PDMIBASE
75	{
76	/**
77	* Queries an interface to the driver.
78	*
79	* @returns Pointer to interface.
80	* @returns NULL if the interface was not supported by the driver.
81	* @param pInterface Pointer to this interface structure.
82	* @param pszIID The interface ID, a UUID string.
83	* @thread Any thread.
84	*/
85	DECLR3CALLBACKMEMBER(void , pfnQueryInterface,(struct PDMIBASE pInterface, const char *pszIID));
86	} PDMIBASE;
87	/** PDMIBASE interface ID. */
88	#define PDMIBASE_IID "a2299c0d-b709-4551-aa5a-73f59ffbed74"
89
90	/**
91	* Helper macro for querying an interface from PDMIBASE.
92	*
93	* @returns Correctly typed PDMIBASE::pfnQueryInterface return value.
94	*
95	* @param pIBase Pointer to the base interface.
96	* @param InterfaceType The interface type name. The interface ID is
97	* derived from this by appending _IID.
98	*/
99	#define PDMIBASE_QUERY_INTERFACE(pIBase, InterfaceType) \
100	( (InterfaceType *)(pIBase)->pfnQueryInterface(pIBase, InterfaceType##_IID ) )
101
102	/**
103	* Helper macro for implementing PDMIBASE::pfnQueryInterface.
104	*
105	* Return @a pInterface if @a pszIID matches the @a InterfaceType. This will
106	* perform basic type checking.
107	*
108	* @param pszIID The ID of the interface that is being queried.
109	* @param InterfaceType The interface type name. The interface ID is
110	* derived from this by appending _IID.
111	* @param pInterface The interface address expression.
112	*/
113	#define PDMIBASE_RETURN_INTERFACE(pszIID, InterfaceType, pInterface) \
114	do { \
115	if (RTUuidCompare2Strs((pszIID), InterfaceType##_IID) == 0) \
116	{ \
117	P##InterfaceType pReturnInterfaceTypeCheck = (pInterface); \
118	return pReturnInterfaceTypeCheck; \
119	} \
120	} while (0)
121
122	/** @} */
123
124
125	/** @name PDMIBASERC
126	* @{
127	*/
128
129	/**
130	* PDM Base Interface for querying ring-mode context interfaces in
131	* ring-3.
132	*
133	* This is mandatory for drivers present in raw-mode context.
134	*/
135	typedef struct PDMIBASERC
136	{
137	/**
138	* Queries an ring-mode context interface to the driver.
139	*
140	* @returns Pointer to interface.
141	* @returns NULL if the interface was not supported by the driver.
142	* @param pInterface Pointer to this interface structure.
143	* @param pszIID The interface ID, a UUID string.
144	* @thread Any thread.
145	*/
146	DECLR3CALLBACKMEMBER(RTRCPTR, pfnQueryInterface,(struct PDMIBASERC pInterface, const char pszIID));
147	} PDMIBASERC;
148	/** Pointer to a PDM Base Interface for query ring-mode context interfaces. */
149	typedef PDMIBASERC *PPDMIBASERC;
150	/** PDMIBASERC interface ID. */
151	#define PDMIBASERC_IID "f6a6c649-6cb3-493f-9737-4653f221aeca"
152
153	/**
154	* Helper macro for querying an interface from PDMIBASERC.
155	*
156	* @returns PDMIBASERC::pfnQueryInterface return value.
157	*
158	* @param pIBaseRC Pointer to the base raw-mode context interface. Can
159	* be NULL.
160	* @param InterfaceType The interface type base name, no trailing RC. The
161	* interface ID is derived from this by appending _IID.
162	*
163	* @remarks Unlike PDMIBASE_QUERY_INTERFACE, this macro is not able to do any
164	* implicit type checking for you.
165	*/
166	#define PDMIBASERC_QUERY_INTERFACE(pIBaseRC, InterfaceType) \
167	( (P##InterfaceType##RC)((pIBaseRC) ? (pIBaseRC)->pfnQueryInterface(pIBaseRC, InterfaceType##_IID) : NIL_RTRCPTR) )
168
169	/**
170	* Helper macro for implementing PDMIBASERC::pfnQueryInterface.
171	*
172	* Return @a pInterface if @a pszIID matches the @a InterfaceType. This will
173	* perform basic type checking.
174	*
175	* @param pIns Pointer to the instance data.
176	* @param pszIID The ID of the interface that is being queried.
177	* @param InterfaceType The interface type base name, no trailing RC. The
178	* interface ID is derived from this by appending _IID.
179	* @param pInterface The interface address expression. This must resolve
180	* to some address within the instance data.
181	* @remarks Don't use with PDMIBASE.
182	*/
183	#define PDMIBASERC_RETURN_INTERFACE(pIns, pszIID, InterfaceType, pInterface) \
184	do { \
185	Assert((uintptr_t)pInterface - PDMINS_2_DATA(pIns, uintptr_t) < _4M); \
186	if (RTUuidCompare2Strs((pszIID), InterfaceType##_IID) == 0) \
187	{ \
188	InterfaceType##RC *pReturnInterfaceTypeCheck = (pInterface); \
189	return (uintptr_t)pReturnInterfaceTypeCheck \
190	- PDMINS_2_DATA(pIns, uintptr_t) \
191	+ PDMINS_2_DATA_RCPTR(pIns); \
192	} \
193	} while (0)
194
195	/** @} */
196
197
198	/** @name PDMIBASER0
199	* @{
200	*/
201
202	/**
203	* PDM Base Interface for querying ring-0 interfaces in ring-3.
204	*
205	* This is mandatory for drivers present in ring-0 context.
206	*/
207	typedef struct PDMIBASER0
208	{
209	/**
210	* Queries an ring-0 interface to the driver.
211	*
212	* @returns Pointer to interface.
213	* @returns NULL if the interface was not supported by the driver.
214	* @param pInterface Pointer to this interface structure.
215	* @param pszIID The interface ID, a UUID string.
216	* @thread Any thread.
217	*/
218	DECLR3CALLBACKMEMBER(RTR0PTR, pfnQueryInterface,(struct PDMIBASER0 pInterface, const char pszIID));
219	} PDMIBASER0;
220	/** Pointer to a PDM Base Interface for query ring-0 context interfaces. */
221	typedef PDMIBASER0 *PPDMIBASER0;
222	/** PDMIBASER0 interface ID. */
223	#define PDMIBASER0_IID "9c9b99b8-7f53-4f59-a3c2-5bc9659c7944"
224
225	/**
226	* Helper macro for querying an interface from PDMIBASER0.
227	*
228	* @returns PDMIBASER0::pfnQueryInterface return value.
229	*
230	* @param pIBaseR0 Pointer to the base ring-0 interface. Can be NULL.
231	* @param InterfaceType The interface type base name, no trailing R0. The
232	* interface ID is derived from this by appending _IID.
233	*
234	* @remarks Unlike PDMIBASE_QUERY_INTERFACE, this macro is not able to do any
235	* implicit type checking for you.
236	*/
237	#define PDMIBASER0_QUERY_INTERFACE(pIBaseR0, InterfaceType) \
238	( (P##InterfaceType##R0)((pIBaseR0) ? (pIBaseR0)->pfnQueryInterface(pIBaseR0, InterfaceType##_IID) : NIL_RTR0PTR) )
239
240	/**
241	* Helper macro for implementing PDMIBASER0::pfnQueryInterface.
242	*
243	* Return @a pInterface if @a pszIID matches the @a InterfaceType. This will
244	* perform basic type checking.
245	*
246	* @param pIns Pointer to the instance data.
247	* @param pszIID The ID of the interface that is being queried.
248	* @param InterfaceType The interface type base name, no trailing R0. The
249	* interface ID is derived from this by appending _IID.
250	* @param pInterface The interface address expression. This must resolve
251	* to some address within the instance data.
252	* @remarks Don't use with PDMIBASE.
253	*/
254	#define PDMIBASER0_RETURN_INTERFACE(pIns, pszIID, InterfaceType, pInterface) \
255	do { \
256	Assert((uintptr_t)pInterface - PDMINS_2_DATA(pIns, uintptr_t) < _4M); \
257	if (RTUuidCompare2Strs((pszIID), InterfaceType##_IID) == 0) \
258	{ \
259	InterfaceType##R0 *pReturnInterfaceTypeCheck = (pInterface); \
260	return (uintptr_t)pReturnInterfaceTypeCheck \
261	- PDMINS_2_DATA(pIns, uintptr_t) \
262	+ PDMINS_2_DATA_R0PTR(pIns); \
263	} \
264	} while (0)
265
266	/** @} */
267
268
269	/**
270	* Dummy interface.
271	*
272	* This is used to typedef other dummy interfaces. The purpose of a dummy
273	* interface is to validate the logical function of a driver/device and
274	* full a natural interface pair.
275	*/
276	typedef struct PDMIDUMMY
277	{
278	RTHCPTR pvDummy;
279	} PDMIDUMMY;
280
281
282	/** Pointer to a mouse port interface. */
283	typedef struct PDMIMOUSEPORT *PPDMIMOUSEPORT;
284	/**
285	* Mouse port interface (down).
286	* Pair with PDMIMOUSECONNECTOR.
287	*/
288	typedef struct PDMIMOUSEPORT
289	{
290	/**
291	* Puts a mouse event.
292	*
293	* This is called by the source of mouse events. The event will be passed up
294	* until the topmost driver, which then calls the registered event handler.
295	*
296	* @returns VBox status code. Return VERR_TRY_AGAIN if you cannot process the
297	* event now and want it to be repeated at a later point.
298	*
299	* @param pInterface Pointer to this interface structure.
300	* @param dx The X delta.
301	* @param dy The Y delta.
302	* @param dz The Z delta.
303	* @param dw The W (horizontal scroll button) delta.
304	* @param fButtons The button states, see the PDMIMOUSEPORT_BUTTON_* \#defines.
305	*/
306	DECLR3CALLBACKMEMBER(int, pfnPutEvent,(PPDMIMOUSEPORT pInterface,
307	int32_t dx, int32_t dy, int32_t dz,
308	int32_t dw, uint32_t fButtons));
309	/**
310	* Puts an absolute mouse event.
311	*
312	* This is called by the source of mouse events. The event will be passed up
313	* until the topmost driver, which then calls the registered event handler.
314	*
315	* @returns VBox status code. Return VERR_TRY_AGAIN if you cannot process the
316	* event now and want it to be repeated at a later point.
317	*
318	* @param pInterface Pointer to this interface structure.
319	* @param x The X value, in the range 0 to 0xffff.
320	* @param y The Y value, in the range 0 to 0xffff.
321	* @param dz The Z delta.
322	* @param dw The W (horizontal scroll button) delta.
323	* @param fButtons The button states, see the PDMIMOUSEPORT_BUTTON_* \#defines.
324	*/
325	DECLR3CALLBACKMEMBER(int, pfnPutEventAbs,(PPDMIMOUSEPORT pInterface,
326	uint32_t x, uint32_t y,
327	int32_t dz, int32_t dw,
328	uint32_t fButtons));
329	/**
330	* Puts a multi-touch event.
331	*
332	* @returns VBox status code. Return VERR_TRY_AGAIN if you cannot process the
333	* event now and want it to be repeated at a later point.
334	*
335	* @param pInterface Pointer to this interface structure.
336	* @param cContacts How many touch contacts in this event.
337	* @param pau64Contacts Pointer to array of packed contact information.
338	* Each 64bit element contains:
339	* Bits 0..15: X coordinate in pixels (signed).
340	* Bits 16..31: Y coordinate in pixels (signed).
341	* Bits 32..39: contact identifier.
342	* Bit 40: "in contact" flag, which indicates that
343	* there is a contact with the touch surface.
344	* Bit 41: "in range" flag, the contact is close enough
345	* to the touch surface.
346	* All other bits are reserved for future use and must be set to 0.
347	* @param u32ScanTime Timestamp of this event in milliseconds. Only relative
348	* time between event is important.
349	*/
350	DECLR3CALLBACKMEMBER(int, pfnPutEventMultiTouch,(PPDMIMOUSEPORT pInterface,
351	uint8_t cContacts,
352	const uint64_t *pau64Contacts,
353	uint32_t u32ScanTime));
354	} PDMIMOUSEPORT;
355	/** PDMIMOUSEPORT interface ID. */
356	#define PDMIMOUSEPORT_IID "359364f0-9fa3-4490-a6b4-7ed771901c93"
357
358	/** Mouse button defines for PDMIMOUSEPORT::pfnPutEvent.
359	* @{ */
360	#define PDMIMOUSEPORT_BUTTON_LEFT RT_BIT(0)
361	#define PDMIMOUSEPORT_BUTTON_RIGHT RT_BIT(1)
362	#define PDMIMOUSEPORT_BUTTON_MIDDLE RT_BIT(2)
363	#define PDMIMOUSEPORT_BUTTON_X1 RT_BIT(3)
364	#define PDMIMOUSEPORT_BUTTON_X2 RT_BIT(4)
365	/** @} */
366
367
368	/** Pointer to a mouse connector interface. */
369	typedef struct PDMIMOUSECONNECTOR *PPDMIMOUSECONNECTOR;
370	/**
371	* Mouse connector interface (up).
372	* Pair with PDMIMOUSEPORT.
373	*/
374	typedef struct PDMIMOUSECONNECTOR
375	{
376	/**
377	* Notifies the the downstream driver of changes to the reporting modes
378	* supported by the driver
379	*
380	* @param pInterface Pointer to this interface structure.
381	* @param fRelative Whether relative mode is currently supported.
382	* @param fAbsolute Whether absolute mode is currently supported.
383	* @param fMultiTouch Whether multi-touch mode is currently supported.
384	*/
385	DECLR3CALLBACKMEMBER(void, pfnReportModes,(PPDMIMOUSECONNECTOR pInterface, bool fRelative, bool fAbsolute, bool fMultiTouch));
386
387	/**
388	* Flushes the mouse queue if it contains pending events.
389	*
390	* @param pInterface Pointer to this interface structure.
391	*/
392	DECLR3CALLBACKMEMBER(void, pfnFlushQueue,(PPDMIMOUSECONNECTOR pInterface));
393
394	} PDMIMOUSECONNECTOR;
395	/** PDMIMOUSECONNECTOR interface ID. */
396	#define PDMIMOUSECONNECTOR_IID "ce64d7bd-fa8f-41d1-a6fb-d102a2d6bffe"
397
398
399	/** Pointer to a keyboard port interface. */
400	typedef struct PDMIKEYBOARDPORT *PPDMIKEYBOARDPORT;
401	/**
402	* Keyboard port interface (down).
403	* Pair with PDMIKEYBOARDCONNECTOR.
404	*/
405	typedef struct PDMIKEYBOARDPORT
406	{
407	/**
408	* Puts a scan code based keyboard event.
409	*
410	* This is called by the source of keyboard events. The event will be passed up
411	* until the topmost driver, which then calls the registered event handler.
412	*
413	* @returns VBox status code. Return VERR_TRY_AGAIN if you cannot process the
414	* event now and want it to be repeated at a later point.
415	*
416	* @param pInterface Pointer to this interface structure.
417	* @param u8ScanCode The scan code to queue.
418	*/
419	DECLR3CALLBACKMEMBER(int, pfnPutEventScan,(PPDMIKEYBOARDPORT pInterface, uint8_t u8KeyCode));
420
421	/**
422	* Puts a USB HID usage ID based keyboard event.
423	*
424	* This is called by the source of keyboard events. The event will be passed up
425	* until the topmost driver, which then calls the registered event handler.
426	*
427	* @returns VBox status code. Return VERR_TRY_AGAIN if you cannot process the
428	* event now and want it to be repeated at a later point.
429	*
430	* @param pInterface Pointer to this interface structure.
431	* @param u32UsageID The HID usage code event to queue.
432	*/
433	DECLR3CALLBACKMEMBER(int, pfnPutEventHid,(PPDMIKEYBOARDPORT pInterface, uint32_t u32UsageID));
434	} PDMIKEYBOARDPORT;
435	/** PDMIKEYBOARDPORT interface ID. */
436	#define PDMIKEYBOARDPORT_IID "2a0844f0-410b-40ab-a6ed-6575f3aa3e29"
437
438
439	/**
440	* Keyboard LEDs.
441	*/
442	typedef enum PDMKEYBLEDS
443	{
444	/** No leds. */
445	PDMKEYBLEDS_NONE = 0x0000,
446	/** Num Lock */
447	PDMKEYBLEDS_NUMLOCK = 0x0001,
448	/** Caps Lock */
449	PDMKEYBLEDS_CAPSLOCK = 0x0002,
450	/** Scroll Lock */
451	PDMKEYBLEDS_SCROLLLOCK = 0x0004
452	} PDMKEYBLEDS;
453
454	/** Pointer to keyboard connector interface. */
455	typedef struct PDMIKEYBOARDCONNECTOR *PPDMIKEYBOARDCONNECTOR;
456	/**
457	* Keyboard connector interface (up).
458	* Pair with PDMIKEYBOARDPORT
459	*/
460	typedef struct PDMIKEYBOARDCONNECTOR
461	{
462	/**
463	* Notifies the the downstream driver about an LED change initiated by the guest.
464	*
465	* @param pInterface Pointer to this interface structure.
466	* @param enmLeds The new led mask.
467	*/
468	DECLR3CALLBACKMEMBER(void, pfnLedStatusChange,(PPDMIKEYBOARDCONNECTOR pInterface, PDMKEYBLEDS enmLeds));
469
470	/**
471	* Notifies the the downstream driver of changes in driver state.
472	*
473	* @param pInterface Pointer to this interface structure.
474	* @param fActive Whether interface wishes to get "focus".
475	*/
476	DECLR3CALLBACKMEMBER(void, pfnSetActive,(PPDMIKEYBOARDCONNECTOR pInterface, bool fActive));
477
478	/**
479	* Flushes the keyboard queue if it contains pending events.
480	*
481	* @param pInterface Pointer to this interface structure.
482	*/
483	DECLR3CALLBACKMEMBER(void, pfnFlushQueue,(PPDMIKEYBOARDCONNECTOR pInterface));
484
485	} PDMIKEYBOARDCONNECTOR;
486	/** PDMIKEYBOARDCONNECTOR interface ID. */
487	#define PDMIKEYBOARDCONNECTOR_IID "db3f7bd5-953e-436f-9f8e-077905a92d82"
488
489
490
491	/** Pointer to a display port interface. */
492	typedef struct PDMIDISPLAYPORT *PPDMIDISPLAYPORT;
493	/**
494	* Display port interface (down).
495	* Pair with PDMIDISPLAYCONNECTOR.
496	*/
497	typedef struct PDMIDISPLAYPORT
498	{
499	/**
500	* Update the display with any changed regions.
501	*
502	* Flushes any display changes to the memory pointed to by the
503	* PDMIDISPLAYCONNECTOR interface and calles PDMIDISPLAYCONNECTOR::pfnUpdateRect()
504	* while doing so.
505	*
506	* @returns VBox status code.
507	* @param pInterface Pointer to this interface.
508	* @thread The emulation thread.
509	*/
510	DECLR3CALLBACKMEMBER(int, pfnUpdateDisplay,(PPDMIDISPLAYPORT pInterface));
511
512	/**
513	* Update the entire display.
514	*
515	* Flushes the entire display content to the memory pointed to by the
516	* PDMIDISPLAYCONNECTOR interface and calles PDMIDISPLAYCONNECTOR::pfnUpdateRect().
517	*
518	* @returns VBox status code.
519	* @param pInterface Pointer to this interface.
520	* @param fFailOnResize Fail is a resize is pending.
521	* @thread The emulation thread.
522	*/
523	DECLR3CALLBACKMEMBER(int, pfnUpdateDisplayAll,(PPDMIDISPLAYPORT pInterface, bool fFailOnResize));
524
525	/**
526	* Return the current guest resolution and color depth in bits per pixel (bpp).
527	*
528	* As the graphics card is able to provide display updates with the bpp
529	* requested by the host, this method can be used to query the actual
530	* guest color depth.
531	*
532	* @returns VBox status code.
533	* @param pInterface Pointer to this interface.
534	* @param pcBits Where to store the current guest color depth.
535	* @param pcx Where to store the horizontal resolution.
536	* @param pcy Where to store the vertical resolution.
537	* @thread Any thread.
538	*/
539	DECLR3CALLBACKMEMBER(int, pfnQueryVideoMode,(PPDMIDISPLAYPORT pInterface, uint32_t pcBits, uint32_t pcx, uint32_t *pcy));
540
541	/**
542	* Sets the refresh rate and restart the timer.
543	* The rate is defined as the minimum interval between the return of
544	* one PDMIDISPLAYPORT::pfnRefresh() call to the next one.
545	*
546	* The interval timer will be restarted by this call. So at VM startup
547	* this function must be called to start the refresh cycle. The refresh
548	* rate is not saved, but have to be when resuming a loaded VM state.
549	*
550	* @returns VBox status code.
551	* @param pInterface Pointer to this interface.
552	* @param cMilliesInterval Number of millis between two refreshes.
553	* @thread Any thread.
554	*/
555	DECLR3CALLBACKMEMBER(int, pfnSetRefreshRate,(PPDMIDISPLAYPORT pInterface, uint32_t cMilliesInterval));
556
557	/**
558	* Create a 32-bbp screenshot of the display.
559	*
560	* This will allocate and return a 32-bbp bitmap. Size of the bitmap scanline in bytes is 4*width.
561	*
562	* The allocated bitmap buffer must be freed with pfnFreeScreenshot.
563	*
564	* @param pInterface Pointer to this interface.
565	* @param ppbData Where to store the pointer to the allocated
566	* buffer.
567	* @param pcbData Where to store the actual size of the bitmap.
568	* @param pcx Where to store the width of the bitmap.
569	* @param pcy Where to store the height of the bitmap.
570	* @thread The emulation thread.
571	*/
572	DECLR3CALLBACKMEMBER(int, pfnTakeScreenshot,(PPDMIDISPLAYPORT pInterface, uint8_t *ppbData, size_t pcbData, uint32_t pcx, uint32_t pcy));
573
574	/**
575	* Free screenshot buffer.
576	*
577	* This will free the memory buffer allocated by pfnTakeScreenshot.
578	*
579	* @param pInterface Pointer to this interface.
580	* @param pbData Pointer to the buffer returned by
581	* pfnTakeScreenshot.
582	* @thread Any.
583	*/
584	DECLR3CALLBACKMEMBER(void, pfnFreeScreenshot,(PPDMIDISPLAYPORT pInterface, uint8_t *pbData));
585
586	/**
587	* Copy bitmap to the display.
588	*
589	* This will convert and copy a 32-bbp bitmap (with dword aligned scanline length) to
590	* the memory pointed to by the PDMIDISPLAYCONNECTOR interface.
591	*
592	* @param pInterface Pointer to this interface.
593	* @param pvData Pointer to the bitmap bits.
594	* @param x The upper left corner x coordinate of the destination rectangle.
595	* @param y The upper left corner y coordinate of the destination rectangle.
596	* @param cx The width of the source and destination rectangles.
597	* @param cy The height of the source and destination rectangles.
598	* @thread The emulation thread.
599	* @remark This is just a convenience for using the bitmap conversions of the
600	* graphics device.
601	*/
602	DECLR3CALLBACKMEMBER(int, pfnDisplayBlt,(PPDMIDISPLAYPORT pInterface, const void *pvData, uint32_t x, uint32_t y, uint32_t cx, uint32_t cy));
603
604	/**
605	* Render a rectangle from guest VRAM to Framebuffer.
606	*
607	* @param pInterface Pointer to this interface.
608	* @param x The upper left corner x coordinate of the rectangle to be updated.
609	* @param y The upper left corner y coordinate of the rectangle to be updated.
610	* @param cx The width of the rectangle to be updated.
611	* @param cy The height of the rectangle to be updated.
612	* @thread The emulation thread.
613	*/
614	DECLR3CALLBACKMEMBER(void, pfnUpdateDisplayRect,(PPDMIDISPLAYPORT pInterface, int32_t x, int32_t y, uint32_t cx, uint32_t cy));
615
616	/**
617	* Inform the VGA device whether the Display is directly using the guest VRAM and there is no need
618	* to render the VRAM to the framebuffer memory.
619	*
620	* @param pInterface Pointer to this interface.
621	* @param fRender Whether the VRAM content must be rendered to the framebuffer.
622	* @thread The emulation thread.
623	*/
624	DECLR3CALLBACKMEMBER(void, pfnSetRenderVRAM,(PPDMIDISPLAYPORT pInterface, bool fRender));
625
626	/**
627	* Render a bitmap rectangle from source to target buffer.
628	*
629	* @param pInterface Pointer to this interface.
630	* @param cx The width of the rectangle to be copied.
631	* @param cy The height of the rectangle to be copied.
632	* @param pbSrc Source frame buffer 0,0.
633	* @param xSrc The upper left corner x coordinate of the source rectangle.
634	* @param ySrc The upper left corner y coordinate of the source rectangle.
635	* @param cxSrc The width of the source frame buffer.
636	* @param cySrc The height of the source frame buffer.
637	* @param cbSrcLine The line length of the source frame buffer.
638	* @param cSrcBitsPerPixel The pixel depth of the source.
639	* @param pbDst Destination frame buffer 0,0.
640	* @param xDst The upper left corner x coordinate of the destination rectangle.
641	* @param yDst The upper left corner y coordinate of the destination rectangle.
642	* @param cxDst The width of the destination frame buffer.
643	* @param cyDst The height of the destination frame buffer.
644	* @param cbDstLine The line length of the destination frame buffer.
645	* @param cDstBitsPerPixel The pixel depth of the destination.
646	* @thread The emulation thread.
647	*/
648	DECLR3CALLBACKMEMBER(int, pfnCopyRect,(PPDMIDISPLAYPORT pInterface, uint32_t cx, uint32_t cy,
649	const uint8_t *pbSrc, int32_t xSrc, int32_t ySrc, uint32_t cxSrc, uint32_t cySrc, uint32_t cbSrcLine, uint32_t cSrcBitsPerPixel,
650	uint8_t *pbDst, int32_t xDst, int32_t yDst, uint32_t cxDst, uint32_t cyDst, uint32_t cbDstLine, uint32_t cDstBitsPerPixel));
651
652	/**
653	* Inform the VGA device of viewport changes (as a result of e.g. scrolling).
654	*
655	* @param pInterface Pointer to this interface.
656	* @param idScreen The screen updates are for.
657	* @param x The upper left corner x coordinate of the new viewport rectangle
658	* @param y The upper left corner y coordinate of the new viewport rectangle
659	* @param cx The width of the new viewport rectangle
660	* @param cy The height of the new viewport rectangle
661	* @thread GUI thread?
662	*
663	* @remarks Is allowed to be NULL.
664	*/
665	DECLR3CALLBACKMEMBER(void, pfnSetViewport,(PPDMIDISPLAYPORT pInterface,
666	uint32_t idScreen, uint32_t x, uint32_t y, uint32_t cx, uint32_t cy));
667
668	/**
669	* Send a video mode hint to the VGA device.
670	*
671	* @param pInterface Pointer to this interface.
672	* @param cx The X resolution.
673	* @param cy The Y resolution.
674	* @param cBPP The bit count.
675	* @param iDisplay The screen number.
676	* @param dx X offset into the virtual framebuffer or ~0.
677	* @param dy Y offset into the virtual framebuffer or ~0.
678	* @param fEnabled Is this screen currently enabled?
679	* @param fNotifyGuest Should the device send the guest an IRQ?
680	* Set for the last hint of a series.
681	* @thread Schedules on the emulation thread.
682	*/
683	DECLR3CALLBACKMEMBER(int, pfnSendModeHint, (PPDMIDISPLAYPORT pInterface, uint32_t cx, uint32_t cy,
684	uint32_t cBPP, uint32_t iDisplay, uint32_t dx,
685	uint32_t dy, uint32_t fEnabled, uint32_t fNotifyGuest));
686
687	/**
688	* Send the guest a notification about host cursor capabilities changes.
689	*
690	* @param pInterface Pointer to this interface.
691	* @param fCapabilitiesAdded New supported capabilities.
692	* @param fCapabilitiesRemoved No longer supported capabilities.
693	* @thread Any.
694	*/
695	DECLR3CALLBACKMEMBER(void, pfnReportHostCursorCapabilities, (PPDMIDISPLAYPORT pInterface, uint32_t fCapabilitiesAdded,
696	uint32_t fCapabilitiesRemoved));
697
698	/**
699	* Tell the graphics device about the host cursor position.
700	*
701	* @param pInterface Pointer to this interface.
702	* @param x X offset into the cursor range.
703	* @param y Y offset into the cursor range.
704	* @thread Any.
705	*/
706	DECLR3CALLBACKMEMBER(void, pfnReportHostCursorPosition, (PPDMIDISPLAYPORT pInterface, uint32_t x, uint32_t y));
707	} PDMIDISPLAYPORT;
708	/** PDMIDISPLAYPORT interface ID. */
709	#ifdef VBOX_WITH_VMSVGA
710	#define PDMIDISPLAYPORT_IID "9672e2b0-1aef-4c4d-9108-864cdb28333f"
711	#else
712	#define PDMIDISPLAYPORT_IID "323f3412-8903-4564-b04c-cbfe0d2d1596"
713	#endif
714
715
716	/** Pointer to a 2D graphics acceleration command. */
717	typedef struct VBOXVHWACMD VBOXVHWACMD;
718	/** Pointer to a VBVA command header. */
719	typedef struct VBVACMDHDR *PVBVACMDHDR;
720	/** Pointer to a const VBVA command header. */
721	typedef const struct VBVACMDHDR *PCVBVACMDHDR;
722	/** Pointer to a VBVA screen information. */
723	typedef struct VBVAINFOSCREEN *PVBVAINFOSCREEN;
724	/** Pointer to a const VBVA screen information. */
725	typedef const struct VBVAINFOSCREEN *PCVBVAINFOSCREEN;
726	/** Pointer to a VBVA guest VRAM area information. */
727	typedef struct VBVAINFOVIEW *PVBVAINFOVIEW;
728	/** Pointer to a const VBVA guest VRAM area information. */
729	typedef const struct VBVAINFOVIEW *PCVBVAINFOVIEW;
730	typedef struct VBVAHOSTFLAGS *PVBVAHOSTFLAGS;
731	struct VBOXVDMACMD_CHROMIUM_CMD; /* <- chromium [hgsmi] command */
732	struct VBOXVDMACMD_CHROMIUM_CTL; /* <- chromium [hgsmi] command */
733
734
735	/** Pointer to a display connector interface. */
736	typedef struct PDMIDISPLAYCONNECTOR *PPDMIDISPLAYCONNECTOR;
737	struct VBOXCRCMDCTL;
738	typedef DECLCALLBACK(void) FNCRCTLCOMPLETION(struct VBOXCRCMDCTL pCmd, uint32_t cbCmd, int rc, void pvCompletion);
739	typedef FNCRCTLCOMPLETION *PFNCRCTLCOMPLETION;
740
741	/**
742	* Display connector interface (up).
743	* Pair with PDMIDISPLAYPORT.
744	*/
745	typedef struct PDMIDISPLAYCONNECTOR
746	{
747	/**
748	* Resize the display.
749	* This is called when the resolution changes. This usually happens on
750	* request from the guest os, but may also happen as the result of a reset.
751	* If the callback returns VINF_VGA_RESIZE_IN_PROGRESS, the caller (VGA device)
752	* must not access the connector and return.
753	*
754	* @returns VINF_SUCCESS if the framebuffer resize was completed,
755	* VINF_VGA_RESIZE_IN_PROGRESS if resize takes time and not yet finished.
756	* @param pInterface Pointer to this interface.
757	* @param cBits Color depth (bits per pixel) of the new video mode.
758	* @param pvVRAM Address of the guest VRAM.
759	* @param cbLine Size in bytes of a single scan line.
760	* @param cx New display width.
761	* @param cy New display height.
762	* @thread The emulation thread.
763	*/
764	DECLR3CALLBACKMEMBER(int, pfnResize,(PPDMIDISPLAYCONNECTOR pInterface, uint32_t cBits, void *pvVRAM, uint32_t cbLine,
765	uint32_t cx, uint32_t cy));
766
767	/**
768	* Update a rectangle of the display.
769	* PDMIDISPLAYPORT::pfnUpdateDisplay is the caller.
770	*
771	* @param pInterface Pointer to this interface.
772	* @param x The upper left corner x coordinate of the rectangle.
773	* @param y The upper left corner y coordinate of the rectangle.
774	* @param cx The width of the rectangle.
775	* @param cy The height of the rectangle.
776	* @thread The emulation thread.
777	*/
778	DECLR3CALLBACKMEMBER(void, pfnUpdateRect,(PPDMIDISPLAYCONNECTOR pInterface, uint32_t x, uint32_t y, uint32_t cx, uint32_t cy));
779
780	/**
781	* Refresh the display.
782	*
783	* The interval between these calls is set by
784	* PDMIDISPLAYPORT::pfnSetRefreshRate(). The driver should call
785	* PDMIDISPLAYPORT::pfnUpdateDisplay() if it wishes to refresh the
786	* display. PDMIDISPLAYPORT::pfnUpdateDisplay calls pfnUpdateRect with
787	* the changed rectangles.
788	*
789	* @param pInterface Pointer to this interface.
790	* @thread The emulation thread.
791	*/
792	DECLR3CALLBACKMEMBER(void, pfnRefresh,(PPDMIDISPLAYCONNECTOR pInterface));
793
794	/**
795	* Reset the display.
796	*
797	* Notification message when the graphics card has been reset.
798	*
799	* @param pInterface Pointer to this interface.
800	* @thread The emulation thread.
801	*/
802	DECLR3CALLBACKMEMBER(void, pfnReset,(PPDMIDISPLAYCONNECTOR pInterface));
803
804	/**
805	* LFB video mode enter/exit.
806	*
807	* Notification message when LinearFrameBuffer video mode is enabled/disabled.
808	*
809	* @param pInterface Pointer to this interface.
810	* @param fEnabled false - LFB mode was disabled,
811	* true - an LFB mode was disabled
812	* @thread The emulation thread.
813	*/
814	DECLR3CALLBACKMEMBER(void, pfnLFBModeChange,(PPDMIDISPLAYCONNECTOR pInterface, bool fEnabled));
815
816	/**
817	* Process the guest graphics adapter information.
818	*
819	* Direct notification from guest to the display connector.
820	*
821	* @param pInterface Pointer to this interface.
822	* @param pvVRAM Address of the guest VRAM.
823	* @param u32VRAMSize Size of the guest VRAM.
824	* @thread The emulation thread.
825	*/
826	DECLR3CALLBACKMEMBER(void, pfnProcessAdapterData,(PPDMIDISPLAYCONNECTOR pInterface, void *pvVRAM, uint32_t u32VRAMSize));
827
828	/**
829	* Process the guest display information.
830	*
831	* Direct notification from guest to the display connector.
832	*
833	* @param pInterface Pointer to this interface.
834	* @param pvVRAM Address of the guest VRAM.
835	* @param uScreenId The index of the guest display to be processed.
836	* @thread The emulation thread.
837	*/
838	DECLR3CALLBACKMEMBER(void, pfnProcessDisplayData,(PPDMIDISPLAYCONNECTOR pInterface, void *pvVRAM, unsigned uScreenId));
839
840	/**
841	* Process the guest Video HW Acceleration command.
842	*
843	* @param pInterface Pointer to this interface.
844	* @param enmCmd The command type (don't re-read from pCmd).
845	* @param fGuestCmd Set if the command origins with the guest and
846	* pCmd must be considered volatile.
847	* @param pCmd Video HW Acceleration Command to be processed.
848	* @retval VINF_SUCCESS - command is completed,
849	* @retval VINF_CALLBACK_RETURN if command will by asynchronously completed via
850	* complete callback.
851	* @retval VERR_INVALID_STATE if the command could not be processed (most
852	* likely because the framebuffer was disconnected) - the post should
853	* be retried later.
854	* @thread EMT
855	*/
856	DECLR3CALLBACKMEMBER(int, pfnVHWACommandProcess,(PPDMIDISPLAYCONNECTOR pInterface, int enmCmd, bool fGuestCmd,
857	VBOXVHWACMD RT_UNTRUSTED_VOLATILE_GUEST *pCmd));
858
859	/**
860	* Process the guest chromium command.
861	*
862	* @param pInterface Pointer to this interface.
863	* @param pCmd Video HW Acceleration Command to be processed.
864	* @thread EMT
865	*/
866	DECLR3CALLBACKMEMBER(void, pfnCrHgsmiCommandProcess,(PPDMIDISPLAYCONNECTOR pInterface,
867	struct VBOXVDMACMD_CHROMIUM_CMD RT_UNTRUSTED_VOLATILE_GUEST *pCmd,
868	uint32_t cbCmd));
869
870	/**
871	* Process the guest chromium control command.
872	*
873	* @param pInterface Pointer to this interface.
874	* @param pCmd Video HW Acceleration Command to be processed.
875	* @thread EMT
876	*/
877	DECLR3CALLBACKMEMBER(void, pfnCrHgsmiControlProcess,(PPDMIDISPLAYCONNECTOR pInterface,
878	struct VBOXVDMACMD_CHROMIUM_CTL RT_UNTRUSTED_VOLATILE_GUEST *pCtl,
879	uint32_t cbCtl));
880
881	/**
882	* Process the guest chromium control command.
883	*
884	* @param pInterface Pointer to this interface.
885	* @param pCmd Video HW Acceleration Command to be processed.
886	* @param cbCmd Undocumented!
887	* @param pfnCompletion Undocumented!
888	* @param pvCompletion Undocumented!
889	* @thread EMT
890	*/
891	DECLR3CALLBACKMEMBER(int, pfnCrHgcmCtlSubmit,(PPDMIDISPLAYCONNECTOR pInterface, struct VBOXCRCMDCTL *pCmd, uint32_t cbCmd,
892	PFNCRCTLCOMPLETION pfnCompletion, void *pvCompletion));
893
894	/**
895	* The specified screen enters VBVA mode.
896	*
897	* @param pInterface Pointer to this interface.
898	* @param uScreenId The screen updates are for.
899	* @param pHostFlags Undocumented!
900	* @param fRenderThreadMode if true - the graphics device has a separate thread that does all rendering.
901	* This means that:
902	* 1. most pfnVBVAXxx callbacks (see the individual documentation for each one)
903	* will be called in the context of the render thread rather than the emulation thread
904	* 2. PDMIDISPLAYCONNECTOR implementor (i.e. DisplayImpl) must NOT notify crogl backend
905	* about vbva-originated events (e.g. resize), because crogl is working in CrCmd mode,
906	* in the context of the render thread as part of the Graphics device, and gets notified about those events directly
907	* @thread if fRenderThreadMode is TRUE - the render thread, otherwise - the emulation thread.
908	*/
909	DECLR3CALLBACKMEMBER(int, pfnVBVAEnable,(PPDMIDISPLAYCONNECTOR pInterface, unsigned uScreenId,
910	struct VBVAHOSTFLAGS RT_UNTRUSTED_VOLATILE_GUEST *pHostFlags, bool fRenderThreadMode));
911
912	/**
913	* The specified screen leaves VBVA mode.
914	*
915	* @param pInterface Pointer to this interface.
916	* @param uScreenId The screen updates are for.
917	* @thread if render thread mode is on (fRenderThreadMode that was passed to pfnVBVAEnable is TRUE) - the render thread pfnVBVAEnable was called in,
918	* otherwise - the emulation thread.
919	*/
920	DECLR3CALLBACKMEMBER(void, pfnVBVADisable,(PPDMIDISPLAYCONNECTOR pInterface, unsigned uScreenId));
921
922	/**
923	* A sequence of pfnVBVAUpdateProcess calls begins.
924	*
925	* @param pInterface Pointer to this interface.
926	* @param uScreenId The screen updates are for.
927	* @thread if render thread mode is on (fRenderThreadMode that was passed to pfnVBVAEnable is TRUE) - the render thread pfnVBVAEnable was called in,
928	* otherwise - the emulation thread.
929	*/
930	DECLR3CALLBACKMEMBER(void, pfnVBVAUpdateBegin,(PPDMIDISPLAYCONNECTOR pInterface, unsigned uScreenId));
931
932	/**
933	* Process the guest VBVA command.
934	*
935	* @param pInterface Pointer to this interface.
936	* @param uScreenId The screen updates are for.
937	* @param pCmd Video HW Acceleration Command to be processed.
938	* @param cbCmd Undocumented!
939	* @thread if render thread mode is on (fRenderThreadMode that was passed to pfnVBVAEnable is TRUE) - the render thread pfnVBVAEnable was called in,
940	* otherwise - the emulation thread.
941	*/
942	DECLR3CALLBACKMEMBER(void, pfnVBVAUpdateProcess,(PPDMIDISPLAYCONNECTOR pInterface, unsigned uScreenId,
943	struct VBVACMDHDR const RT_UNTRUSTED_VOLATILE_GUEST *pCmd, size_t cbCmd));
944
945	/**
946	* A sequence of pfnVBVAUpdateProcess calls ends.
947	*
948	* @param pInterface Pointer to this interface.
949	* @param uScreenId The screen updates are for.
950	* @param x The upper left corner x coordinate of the combined rectangle of all VBVA updates.
951	* @param y The upper left corner y coordinate of the rectangle.
952	* @param cx The width of the rectangle.
953	* @param cy The height of the rectangle.
954	* @thread if render thread mode is on (fRenderThreadMode that was passed to pfnVBVAEnable is TRUE) - the render thread pfnVBVAEnable was called in,
955	* otherwise - the emulation thread.
956	*/
957	DECLR3CALLBACKMEMBER(void, pfnVBVAUpdateEnd,(PPDMIDISPLAYCONNECTOR pInterface, unsigned uScreenId, int32_t x, int32_t y,
958	uint32_t cx, uint32_t cy));
959
960	/**
961	* Resize the display.
962	* This is called when the resolution changes. This usually happens on
963	* request from the guest os, but may also happen as the result of a reset.
964	* If the callback returns VINF_VGA_RESIZE_IN_PROGRESS, the caller (VGA device)
965	* must not access the connector and return.
966	*
967	* @todo Merge with pfnResize.
968	*
969	* @returns VINF_SUCCESS if the framebuffer resize was completed,
970	* VINF_VGA_RESIZE_IN_PROGRESS if resize takes time and not yet finished.
971	* @param pInterface Pointer to this interface.
972	* @param pView The description of VRAM block for this screen.
973	* @param pScreen The data of screen being resized.
974	* @param pvVRAM Address of the guest VRAM.
975	* @param fResetInputMapping Whether to reset the absolute pointing device to screen position co-ordinate
976	* mapping. Needed for real resizes, as the caller on the guest may not know how
977	* to set the mapping. Not wanted when we restore a saved state and are resetting
978	* the mode.
979	* @thread if render thread mode is on (fRenderThreadMode that was passed to pfnVBVAEnable is TRUE) - the render thread pfnVBVAEnable was called in,
980	* otherwise - the emulation thread.
981	*/
982	DECLR3CALLBACKMEMBER(int, pfnVBVAResize,(PPDMIDISPLAYCONNECTOR pInterface, PCVBVAINFOVIEW pView, PCVBVAINFOSCREEN pScreen,
983	void *pvVRAM, bool fResetInputMapping));
984
985	/**
986	* Update the pointer shape.
987	* This is called when the mouse pointer shape changes. The new shape
988	* is passed as a caller allocated buffer that will be freed after returning
989	*
990	* @param pInterface Pointer to this interface.
991	* @param fVisible Visibility indicator (if false, the other parameters are undefined).
992	* @param fAlpha Flag whether alpha channel is being passed.
993	* @param xHot Pointer hot spot x coordinate.
994	* @param yHot Pointer hot spot y coordinate.
995	* @param x Pointer new x coordinate on screen.
996	* @param y Pointer new y coordinate on screen.
997	* @param cx Pointer width in pixels.
998	* @param cy Pointer height in pixels.
999	* @param cbScanline Size of one scanline in bytes.
1000	* @param pvShape New shape buffer.
1001	* @thread The emulation thread.
1002	*/
1003	DECLR3CALLBACKMEMBER(int, pfnVBVAMousePointerShape,(PPDMIDISPLAYCONNECTOR pInterface, bool fVisible, bool fAlpha,
1004	uint32_t xHot, uint32_t yHot, uint32_t cx, uint32_t cy,
1005	const void *pvShape));
1006
1007	/**
1008	* The guest capabilities were updated.
1009	*
1010	* @param pInterface Pointer to this interface.
1011	* @param fCapabilities The new capability flag state.
1012	* @thread The emulation thread.
1013	*/
1014	DECLR3CALLBACKMEMBER(void, pfnVBVAGuestCapabilityUpdate,(PPDMIDISPLAYCONNECTOR pInterface, uint32_t fCapabilities));
1015
1016	/** Read-only attributes.
1017	* For preformance reasons some readonly attributes are kept in the interface.
1018	* We trust the interface users to respect the readonlyness of these.
1019	* @{
1020	*/
1021	/** Pointer to the display data buffer. */
1022	uint8_t *pbData;
1023	/** Size of a scanline in the data buffer. */
1024	uint32_t cbScanline;
1025	/** The color depth (in bits) the graphics card is supposed to provide. */
1026	uint32_t cBits;
1027	/** The display width. */
1028	uint32_t cx;
1029	/** The display height. */
1030	uint32_t cy;
1031	/** @} */
1032
1033	/**
1034	* The guest display input mapping rectangle was updated.
1035	*
1036	* @param pInterface Pointer to this interface.
1037	* @param xOrigin Upper left X co-ordinate relative to the first screen.
1038	* @param yOrigin Upper left Y co-ordinate relative to the first screen.
1039	* @param cx Rectangle width.
1040	* @param cy Rectangle height.
1041	* @thread The emulation thread.
1042	*/
1043	DECLR3CALLBACKMEMBER(void, pfnVBVAInputMappingUpdate,(PPDMIDISPLAYCONNECTOR pInterface, int32_t xOrigin, int32_t yOrigin, uint32_t cx, uint32_t cy));
1044
1045	/**
1046	* The guest is reporting the requested location of the host pointer.
1047	*
1048	* @param pInterface Pointer to this interface.
1049	* @param fData Does this report contain valid X and Y data or is
1050	* it only reporting interface support?
1051	* @param x Cursor X offset.
1052	* @param y Cursor Y offset.
1053	* @thread The emulation thread.
1054	*/
1055	DECLR3CALLBACKMEMBER(void, pfnVBVAReportCursorPosition,(PPDMIDISPLAYCONNECTOR pInterface, bool fData, uint32_t x, uint32_t y));
1056	} PDMIDISPLAYCONNECTOR;
1057	/** PDMIDISPLAYCONNECTOR interface ID. */
1058	#define PDMIDISPLAYCONNECTOR_IID "e648dac6-c918-11e7-8be6-a317e6b79645"
1059
1060
1061	/** Pointer to a secret key interface. */
1062	typedef struct PDMISECKEY *PPDMISECKEY;
1063
1064	/**
1065	* Secret key interface to retrieve secret keys.
1066	*/
1067	typedef struct PDMISECKEY
1068	{
1069	/**
1070	* Retains a key identified by the ID. The caller will only hold a reference
1071	* to the key and must not modify the key buffer in any way.
1072	*
1073	* @returns VBox status code.
1074	* @param pInterface Pointer to this interface.
1075	* @param pszId The alias/id for the key to retrieve.
1076	* @param ppbKey Where to store the pointer to the key buffer on success.
1077	* @param pcbKey Where to store the size of the key in bytes on success.
1078	*/
1079	DECLR3CALLBACKMEMBER(int, pfnKeyRetain, (PPDMISECKEY pInterface, const char *pszId,
1080	const uint8_t *pbKey, size_t pcbKey));
1081
1082	/**
1083	* Releases one reference of the key identified by the given identifier.
1084	* The caller must not access the key buffer after calling this operation.
1085	*
1086	* @returns VBox status code.
1087	* @param pInterface Pointer to this interface.
1088	* @param pszId The alias/id for the key to release.
1089	*
1090	* @note: It is advised to release the key whenever it is not used anymore so the entity
1091	* storing the key can do anything to make retrieving the key from memory more
1092	* difficult like scrambling the memory buffer for instance.
1093	*/
1094	DECLR3CALLBACKMEMBER(int, pfnKeyRelease, (PPDMISECKEY pInterface, const char *pszId));
1095
1096	/**
1097	* Retains a password identified by the ID. The caller will only hold a reference
1098	* to the password and must not modify the buffer in any way.
1099	*
1100	* @returns VBox status code.
1101	* @param pInterface Pointer to this interface.
1102	* @param pszId The alias/id for the password to retrieve.
1103	* @param ppszPassword Where to store the pointer to the password on success.
1104	*/
1105	DECLR3CALLBACKMEMBER(int, pfnPasswordRetain, (PPDMISECKEY pInterface, const char *pszId,
1106	const char **ppszPassword));
1107
1108	/**
1109	* Releases one reference of the password identified by the given identifier.
1110	* The caller must not access the password after calling this operation.
1111	*
1112	* @returns VBox status code.
1113	* @param pInterface Pointer to this interface.
1114	* @param pszId The alias/id for the password to release.
1115	*
1116	* @note: It is advised to release the password whenever it is not used anymore so the entity
1117	* storing the password can do anything to make retrieving the password from memory more
1118	* difficult like scrambling the memory buffer for instance.
1119	*/
1120	DECLR3CALLBACKMEMBER(int, pfnPasswordRelease, (PPDMISECKEY pInterface, const char *pszId));
1121	} PDMISECKEY;
1122	/** PDMISECKEY interface ID. */
1123	#define PDMISECKEY_IID "3d698355-d995-453d-960f-31566a891df2"
1124
1125	/** Pointer to a secret key helper interface. */
1126	typedef struct PDMISECKEYHLP *PPDMISECKEYHLP;
1127
1128	/**
1129	* Secret key helper interface for non critical functionality.
1130	*/
1131	typedef struct PDMISECKEYHLP
1132	{
1133	/**
1134	* Notifies the interface provider that a key couldn't be retrieved from the key store.
1135	*
1136	* @returns VBox status code.
1137	* @param pInterface Pointer to this interface.
1138	*/
1139	DECLR3CALLBACKMEMBER(int, pfnKeyMissingNotify, (PPDMISECKEYHLP pInterface));
1140
1141	} PDMISECKEYHLP;
1142	/** PDMISECKEY interface ID. */
1143	#define PDMISECKEYHLP_IID "7be96168-4156-40ac-86d2-3073bf8b318e"
1144
1145
1146	/** Pointer to a char port interface. */
1147	typedef struct PDMICHARPORT *PPDMICHARPORT;
1148	/**
1149	* Char port interface (down).
1150	* Pair with PDMICHARCONNECTOR.
1151	*/
1152	typedef struct PDMICHARPORT
1153	{
1154	/**
1155	* Deliver data read to the device/driver.
1156	*
1157	* @returns VBox status code.
1158	* @param pInterface Pointer to the interface structure containing the called function pointer.
1159	* @param pvBuf Where the read bits are stored.
1160	* @param pcbRead Number of bytes available for reading/having been read.
1161	* @thread Any thread.
1162	*/
1163	DECLR3CALLBACKMEMBER(int, pfnNotifyRead,(PPDMICHARPORT pInterface, const void pvBuf, size_t pcbRead));
1164
1165	/**
1166	* Notify the device/driver when the status lines changed.
1167	*
1168	* @returns VBox status code.
1169	* @param pInterface Pointer to the interface structure containing the called function pointer.
1170	* @param fNewStatusLine New state of the status line pins.
1171	* @thread Any thread.
1172	*/
1173	DECLR3CALLBACKMEMBER(int, pfnNotifyStatusLinesChanged,(PPDMICHARPORT pInterface, uint32_t fNewStatusLines));
1174
1175	/**
1176	* Notify the device when the driver buffer is full.
1177	*
1178	* @returns VBox status code.
1179	* @param pInterface Pointer to the interface structure containing the called function pointer.
1180	* @param fFull Buffer full.
1181	* @thread Any thread.
1182	*/
1183	DECLR3CALLBACKMEMBER(int, pfnNotifyBufferFull,(PPDMICHARPORT pInterface, bool fFull));
1184
1185	/**
1186	* Notify the device/driver that a break occurred.
1187	*
1188	* @returns VBox statsus code.
1189	* @param pInterface Pointer to the interface structure containing the called function pointer.
1190	* @thread Any thread.
1191	*/
1192	DECLR3CALLBACKMEMBER(int, pfnNotifyBreak,(PPDMICHARPORT pInterface));
1193	} PDMICHARPORT;
1194	/** PDMICHARPORT interface ID. */
1195	#define PDMICHARPORT_IID "22769834-ea8b-4a6d-ade1-213dcdbd1228"
1196
1197	/** @name Bit mask definitions for status line type.
1198	* @{ */
1199	#define PDMICHARPORT_STATUS_LINES_DCD RT_BIT(0)
1200	#define PDMICHARPORT_STATUS_LINES_RI RT_BIT(1)
1201	#define PDMICHARPORT_STATUS_LINES_DSR RT_BIT(2)
1202	#define PDMICHARPORT_STATUS_LINES_CTS RT_BIT(3)
1203	/** @} */
1204
1205
1206	/** Pointer to a char interface. */
1207	typedef struct PDMICHARCONNECTOR *PPDMICHARCONNECTOR;
1208	/**
1209	* Char connector interface (up).
1210	* Pair with PDMICHARPORT.
1211	*/
1212	typedef struct PDMICHARCONNECTOR
1213	{
1214	/**
1215	* Write bits.
1216	*
1217	* @returns VBox status code.
1218	* @param pInterface Pointer to the interface structure containing the called function pointer.
1219	* @param pvBuf Where to store the write bits.
1220	* @param cbWrite Number of bytes to write.
1221	* @thread Any thread.
1222	*/
1223	DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMICHARCONNECTOR pInterface, const void *pvBuf, size_t cbWrite));
1224
1225	/**
1226	* Set device parameters.
1227	*
1228	* @returns VBox status code.
1229	* @param pInterface Pointer to the interface structure containing the called function pointer.
1230	* @param Bps Speed of the serial connection. (bits per second)
1231	* @param chParity Parity method: 'E' - even, 'O' - odd, 'N' - none.
1232	* @param cDataBits Number of data bits.
1233	* @param cStopBits Number of stop bits.
1234	* @thread Any thread.
1235	*/
1236	DECLR3CALLBACKMEMBER(int, pfnSetParameters,(PPDMICHARCONNECTOR pInterface, unsigned Bps, char chParity,
1237	unsigned cDataBits, unsigned cStopBits));
1238
1239	/**
1240	* Set the state of the modem lines.
1241	*
1242	* @returns VBox status code.
1243	* @param pInterface Pointer to the interface structure containing the called function pointer.
1244	* @param fRequestToSend Set to true to make the Request to Send line active otherwise to 0.
1245	* @param fDataTerminalReady Set to true to make the Data Terminal Ready line active otherwise 0.
1246	* @thread Any thread.
1247	*/
1248	DECLR3CALLBACKMEMBER(int, pfnSetModemLines,(PPDMICHARCONNECTOR pInterface, bool fRequestToSend, bool fDataTerminalReady));
1249
1250	/**
1251	* Sets the TD line into break condition.
1252	*
1253	* @returns VBox status code.
1254	* @param pInterface Pointer to the interface structure containing the called function pointer.
1255	* @param fBreak Set to true to let the device send a break false to put into normal operation.
1256	* @thread Any thread.
1257	*/
1258	DECLR3CALLBACKMEMBER(int, pfnSetBreak,(PPDMICHARCONNECTOR pInterface, bool fBreak));
1259	} PDMICHARCONNECTOR;
1260	/** PDMICHARCONNECTOR interface ID. */
1261	#define PDMICHARCONNECTOR_IID "4ad5c190-b408-4cef-926f-fbffce0dc5cc"
1262
1263
1264	/** Pointer to a stream interface. */
1265	typedef struct PDMISTREAM *PPDMISTREAM;
1266	/**
1267	* Stream interface (up).
1268	* Makes up the foundation for PDMICHARCONNECTOR. No pair interface.
1269	*/
1270	typedef struct PDMISTREAM
1271	{
1272	/**
1273	* Polls for the specified events.
1274	*
1275	* @returns VBox status code.
1276	* @retval VERR_INTERRUPTED if the poll was interrupted.
1277	* @retval VERR_TIMEOUT if the maximum waiting time was reached.
1278	* @param pInterface Pointer to the interface structure containing the called function pointer.
1279	* @param fEvts The events to poll for, see RTPOLL_EVT_XXX.
1280	* @param *pfEvts Where to return details about the events that occurred.
1281	* @param cMillies Number of milliseconds to wait. Use
1282	* RT_INDEFINITE_WAIT to wait for ever.
1283	*/
1284	DECLR3CALLBACKMEMBER(int, pfnPoll,(PPDMISTREAM pInterface, uint32_t fEvts, uint32_t *pfEvts, RTMSINTERVAL cMillies));
1285
1286	/**
1287	* Interrupts the current poll call.
1288	*
1289	* @returns VBox status code.
1290	* @param pInterface Pointer to the interface structure containing the called function pointer.
1291	*/
1292	DECLR3CALLBACKMEMBER(int, pfnPollInterrupt,(PPDMISTREAM pInterface));
1293
1294	/**
1295	* Read bits.
1296	*
1297	* @returns VBox status code.
1298	* @param pInterface Pointer to the interface structure containing the called function pointer.
1299	* @param pvBuf Where to store the read bits.
1300	* @param pcbRead Number of bytes to read/bytes actually read.
1301	* @thread Any thread.
1302	*
1303	* @note: This is non blocking, use the poll callback to block when there is nothing to read.
1304	*/
1305	DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMISTREAM pInterface, void pvBuf, size_t pcbRead));
1306
1307	/**
1308	* Write bits.
1309	*
1310	* @returns VBox status code.
1311	* @param pInterface Pointer to the interface structure containing the called function pointer.
1312	* @param pvBuf Where to store the write bits.
1313	* @param pcbWrite Number of bytes to write/bytes actually written.
1314	* @thread Any thread.
1315	*
1316	* @note: This is non blocking, use the poll callback to block until there is room to write.
1317	*/
1318	DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMISTREAM pInterface, const void pvBuf, size_t pcbWrite));
1319	} PDMISTREAM;
1320	/** PDMISTREAM interface ID. */
1321	#define PDMISTREAM_IID "f9bd1ba6-c134-44cc-8259-febe14393952"
1322
1323
1324	/** Mode of the parallel port */
1325	typedef enum PDMPARALLELPORTMODE
1326	{
1327	/** First invalid mode. */
1328	PDM_PARALLEL_PORT_MODE_INVALID = 0,
1329	/** SPP (Compatibility mode). */
1330	PDM_PARALLEL_PORT_MODE_SPP,
1331	/** EPP Data mode. */
1332	PDM_PARALLEL_PORT_MODE_EPP_DATA,
1333	/** EPP Address mode. */
1334	PDM_PARALLEL_PORT_MODE_EPP_ADDR,
1335	/** ECP mode (not implemented yet). */
1336	PDM_PARALLEL_PORT_MODE_ECP,
1337	/** 32bit hack. */
1338	PDM_PARALLEL_PORT_MODE_32BIT_HACK = 0x7fffffff
1339	} PDMPARALLELPORTMODE;
1340
1341	/** Pointer to a host parallel port interface. */
1342	typedef struct PDMIHOSTPARALLELPORT *PPDMIHOSTPARALLELPORT;
1343	/**
1344	* Host parallel port interface (down).
1345	* Pair with PDMIHOSTPARALLELCONNECTOR.
1346	*/
1347	typedef struct PDMIHOSTPARALLELPORT
1348	{
1349	/**
1350	* Notify device/driver that an interrupt has occurred.
1351	*
1352	* @returns VBox status code.
1353	* @param pInterface Pointer to the interface structure containing the called function pointer.
1354	* @thread Any thread.
1355	*/
1356	DECLR3CALLBACKMEMBER(int, pfnNotifyInterrupt,(PPDMIHOSTPARALLELPORT pInterface));
1357	} PDMIHOSTPARALLELPORT;
1358	/** PDMIHOSTPARALLELPORT interface ID. */
1359	#define PDMIHOSTPARALLELPORT_IID "f24b8668-e7f6-4eaa-a14c-4aa2a5f7048e"
1360
1361
1362
1363	/** Pointer to a Host Parallel connector interface. */
1364	typedef struct PDMIHOSTPARALLELCONNECTOR *PPDMIHOSTPARALLELCONNECTOR;
1365	/**
1366	* Host parallel connector interface (up).
1367	* Pair with PDMIHOSTPARALLELPORT.
1368	*/
1369	typedef struct PDMIHOSTPARALLELCONNECTOR
1370	{
1371	/**
1372	* Write bits.
1373	*
1374	* @returns VBox status code.
1375	* @param pInterface Pointer to the interface structure containing the called function pointer.
1376	* @param pvBuf Where to store the write bits.
1377	* @param cbWrite Number of bytes to write.
1378	* @param enmMode Mode to write the data.
1379	* @thread Any thread.
1380	* @todo r=klaus cbWrite only defines buffer length, method needs a way top return actually written amount of data.
1381	*/
1382	DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMIHOSTPARALLELCONNECTOR pInterface, const void *pvBuf,
1383	size_t cbWrite, PDMPARALLELPORTMODE enmMode));
1384
1385	/**
1386	* Read bits.
1387	*
1388	* @returns VBox status code.
1389	* @param pInterface Pointer to the interface structure containing the called function pointer.
1390	* @param pvBuf Where to store the read bits.
1391	* @param cbRead Number of bytes to read.
1392	* @param enmMode Mode to read the data.
1393	* @thread Any thread.
1394	* @todo r=klaus cbRead only defines buffer length, method needs a way top return actually read amount of data.
1395	*/
1396	DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMIHOSTPARALLELCONNECTOR pInterface, void *pvBuf,
1397	size_t cbRead, PDMPARALLELPORTMODE enmMode));
1398
1399	/**
1400	* Set data direction of the port (forward/reverse).
1401	*
1402	* @returns VBox status code.
1403	* @param pInterface Pointer to the interface structure containing the called function pointer.
1404	* @param fForward Flag whether to indicate whether the port is operated in forward or reverse mode.
1405	* @thread Any thread.
1406	*/
1407	DECLR3CALLBACKMEMBER(int, pfnSetPortDirection,(PPDMIHOSTPARALLELCONNECTOR pInterface, bool fForward));
1408
1409	/**
1410	* Write control register bits.
1411	*
1412	* @returns VBox status code.
1413	* @param pInterface Pointer to the interface structure containing the called function pointer.
1414	* @param fReg The new control register value.
1415	* @thread Any thread.
1416	*/
1417	DECLR3CALLBACKMEMBER(int, pfnWriteControl,(PPDMIHOSTPARALLELCONNECTOR pInterface, uint8_t fReg));
1418
1419	/**
1420	* Read control register bits.
1421	*
1422	* @returns VBox status code.
1423	* @param pInterface Pointer to the interface structure containing the called function pointer.
1424	* @param pfReg Where to store the control register bits.
1425	* @thread Any thread.
1426	*/
1427	DECLR3CALLBACKMEMBER(int, pfnReadControl,(PPDMIHOSTPARALLELCONNECTOR pInterface, uint8_t *pfReg));
1428
1429	/**
1430	* Read status register bits.
1431	*
1432	* @returns VBox status code.
1433	* @param pInterface Pointer to the interface structure containing the called function pointer.
1434	* @param pfReg Where to store the status register bits.
1435	* @thread Any thread.
1436	*/
1437	DECLR3CALLBACKMEMBER(int, pfnReadStatus,(PPDMIHOSTPARALLELCONNECTOR pInterface, uint8_t *pfReg));
1438
1439	} PDMIHOSTPARALLELCONNECTOR;
1440	/** PDMIHOSTPARALLELCONNECTOR interface ID. */
1441	#define PDMIHOSTPARALLELCONNECTOR_IID "7c532602-7438-4fbc-9265-349d9f0415f9"
1442
1443
1444	/** ACPI power source identifier */
1445	typedef enum PDMACPIPOWERSOURCE
1446	{
1447	PDM_ACPI_POWER_SOURCE_UNKNOWN = 0,
1448	PDM_ACPI_POWER_SOURCE_OUTLET,
1449	PDM_ACPI_POWER_SOURCE_BATTERY
1450	} PDMACPIPOWERSOURCE;
1451	/** Pointer to ACPI battery state. */
1452	typedef PDMACPIPOWERSOURCE *PPDMACPIPOWERSOURCE;
1453
1454	/** ACPI battey capacity */
1455	typedef enum PDMACPIBATCAPACITY
1456	{
1457	PDM_ACPI_BAT_CAPACITY_MIN = 0,
1458	PDM_ACPI_BAT_CAPACITY_MAX = 100,
1459	PDM_ACPI_BAT_CAPACITY_UNKNOWN = 255
1460	} PDMACPIBATCAPACITY;
1461	/** Pointer to ACPI battery capacity. */
1462	typedef PDMACPIBATCAPACITY *PPDMACPIBATCAPACITY;
1463
1464	/** ACPI battery state. See ACPI 3.0 spec '_BST (Battery Status)' */
1465	typedef enum PDMACPIBATSTATE
1466	{
1467	PDM_ACPI_BAT_STATE_CHARGED = 0x00,
1468	PDM_ACPI_BAT_STATE_DISCHARGING = 0x01,
1469	PDM_ACPI_BAT_STATE_CHARGING = 0x02,
1470	PDM_ACPI_BAT_STATE_CRITICAL = 0x04
1471	} PDMACPIBATSTATE;
1472	/** Pointer to ACPI battery state. */
1473	typedef PDMACPIBATSTATE *PPDMACPIBATSTATE;
1474
1475	/** Pointer to an ACPI port interface. */
1476	typedef struct PDMIACPIPORT *PPDMIACPIPORT;
1477	/**
1478	* ACPI port interface (down). Used by both the ACPI driver and (grumble) main.
1479	* Pair with PDMIACPICONNECTOR.
1480	*/
1481	typedef struct PDMIACPIPORT
1482	{
1483	/**
1484	* Send an ACPI power off event.
1485	*
1486	* @returns VBox status code
1487	* @param pInterface Pointer to the interface structure containing the called function pointer.
1488	*/
1489	DECLR3CALLBACKMEMBER(int, pfnPowerButtonPress,(PPDMIACPIPORT pInterface));
1490
1491	/**
1492	* Send an ACPI sleep button event.
1493	*
1494	* @returns VBox status code
1495	* @param pInterface Pointer to the interface structure containing the called function pointer.
1496	*/
1497	DECLR3CALLBACKMEMBER(int, pfnSleepButtonPress,(PPDMIACPIPORT pInterface));
1498
1499	/**
1500	* Check if the last power button event was handled by the guest.
1501	*
1502	* @returns VBox status code
1503	* @param pInterface Pointer to the interface structure containing the called function pointer.
1504	* @param pfHandled Is set to true if the last power button event was handled, false otherwise.
1505	*/
1506	DECLR3CALLBACKMEMBER(int, pfnGetPowerButtonHandled,(PPDMIACPIPORT pInterface, bool *pfHandled));
1507
1508	/**
1509	* Check if the guest entered the ACPI mode.
1510	*
1511	* @returns VBox status code
1512	* @param pInterface Pointer to the interface structure containing the called function pointer.
1513	* @param pfEntered Is set to true if the guest entered the ACPI mode, false otherwise.
1514	*/
1515	DECLR3CALLBACKMEMBER(int, pfnGetGuestEnteredACPIMode,(PPDMIACPIPORT pInterface, bool *pfEntered));
1516
1517	/**
1518	* Check if the given CPU is still locked by the guest.
1519	*
1520	* @returns VBox status code
1521	* @param pInterface Pointer to the interface structure containing the called function pointer.
1522	* @param uCpu The CPU to check for.
1523	* @param pfLocked Is set to true if the CPU is still locked by the guest, false otherwise.
1524	*/
1525	DECLR3CALLBACKMEMBER(int, pfnGetCpuStatus,(PPDMIACPIPORT pInterface, unsigned uCpu, bool *pfLocked));
1526
1527	/**
1528	* Send an ACPI monitor hot-plug event.
1529	*
1530	* @returns VBox status code
1531	* @param pInterface Pointer to the interface structure containing
1532	* the called function pointer.
1533	*/
1534	DECLR3CALLBACKMEMBER(int, pfnMonitorHotPlugEvent,(PPDMIACPIPORT pInterface));
1535
1536	/**
1537	* Send a battery status change event.
1538	*
1539	* @returns VBox status code
1540	* @param pInterface Pointer to the interface structure containing
1541	* the called function pointer.
1542	*/
1543	DECLR3CALLBACKMEMBER(int, pfnBatteryStatusChangeEvent,(PPDMIACPIPORT pInterface));
1544	} PDMIACPIPORT;
1545	/** PDMIACPIPORT interface ID. */
1546	#define PDMIACPIPORT_IID "974cb8fb-7fda-408c-f9b4-7ff4e3b2a699"
1547
1548
1549	/** Pointer to an ACPI connector interface. */
1550	typedef struct PDMIACPICONNECTOR *PPDMIACPICONNECTOR;
1551	/**
1552	* ACPI connector interface (up).
1553	* Pair with PDMIACPIPORT.
1554	*/
1555	typedef struct PDMIACPICONNECTOR
1556	{
1557	/**
1558	* Get the current power source of the host system.
1559	*
1560	* @returns VBox status code
1561	* @param pInterface Pointer to the interface structure containing the called function pointer.
1562	* @param penmPowerSource Pointer to the power source result variable.
1563	*/
1564	DECLR3CALLBACKMEMBER(int, pfnQueryPowerSource,(PPDMIACPICONNECTOR, PPDMACPIPOWERSOURCE penmPowerSource));
1565
1566	/**
1567	* Query the current battery status of the host system.
1568	*
1569	* @returns VBox status code?
1570	* @param pInterface Pointer to the interface structure containing the called function pointer.
1571	* @param pfPresent Is set to true if battery is present, false otherwise.
1572	* @param penmRemainingCapacity Pointer to the battery remaining capacity (0 - 100 or 255 for unknown).
1573	* @param penmBatteryState Pointer to the battery status.
1574	* @param pu32PresentRate Pointer to the present rate (0..1000 of the total capacity).
1575	*/
1576	DECLR3CALLBACKMEMBER(int, pfnQueryBatteryStatus,(PPDMIACPICONNECTOR, bool *pfPresent, PPDMACPIBATCAPACITY penmRemainingCapacity,
1577	PPDMACPIBATSTATE penmBatteryState, uint32_t *pu32PresentRate));
1578	} PDMIACPICONNECTOR;
1579	/** PDMIACPICONNECTOR interface ID. */
1580	#define PDMIACPICONNECTOR_IID "5f14bf8d-1edf-4e3a-a1e1-cca9fd08e359"
1581
1582	struct VMMDevDisplayDef;
1583
1584	/** Pointer to a VMMDevice port interface. */
1585	typedef struct PDMIVMMDEVPORT *PPDMIVMMDEVPORT;
1586	/**
1587	* VMMDevice port interface (down).
1588	* Pair with PDMIVMMDEVCONNECTOR.
1589	*/
1590	typedef struct PDMIVMMDEVPORT
1591	{
1592	/**
1593	* Return the current absolute mouse position in pixels
1594	*
1595	* @returns VBox status code
1596	* @param pInterface Pointer to the interface structure containing the called function pointer.
1597	* @param pxAbs Pointer of result value, can be NULL
1598	* @param pyAbs Pointer of result value, can be NULL
1599	*/
1600	DECLR3CALLBACKMEMBER(int, pfnQueryAbsoluteMouse,(PPDMIVMMDEVPORT pInterface, int32_t pxAbs, int32_t pyAbs));
1601
1602	/**
1603	* Set the new absolute mouse position in pixels
1604	*
1605	* @returns VBox status code
1606	* @param pInterface Pointer to the interface structure containing the called function pointer.
1607	* @param xAbs New absolute X position
1608	* @param yAbs New absolute Y position
1609	*/
1610	DECLR3CALLBACKMEMBER(int, pfnSetAbsoluteMouse,(PPDMIVMMDEVPORT pInterface, int32_t xAbs, int32_t yAbs));
1611
1612	/**
1613	* Return the current mouse capability flags
1614	*
1615	* @returns VBox status code
1616	* @param pInterface Pointer to the interface structure containing the called function pointer.
1617	* @param pfCapabilities Pointer of result value
1618	*/
1619	DECLR3CALLBACKMEMBER(int, pfnQueryMouseCapabilities,(PPDMIVMMDEVPORT pInterface, uint32_t *pfCapabilities));
1620
1621	/**
1622	* Set the current mouse capability flag (host side)
1623	*
1624	* @returns VBox status code
1625	* @param pInterface Pointer to the interface structure containing the called function pointer.
1626	* @param fCapsAdded Mask of capabilities to add to the flag
1627	* @param fCapsRemoved Mask of capabilities to remove from the flag
1628	*/
1629	DECLR3CALLBACKMEMBER(int, pfnUpdateMouseCapabilities,(PPDMIVMMDEVPORT pInterface, uint32_t fCapsAdded, uint32_t fCapsRemoved));
1630
1631	/**
1632	* Issue a display resolution change request.
1633	*
1634	* Note that there can only one request in the queue and that in case the guest does
1635	* not process it, issuing another request will overwrite the previous.
1636	*
1637	* @returns VBox status code
1638	* @param pInterface Pointer to the interface structure containing the called function pointer.
1639	* @param cDisplays Number of displays. Can be either 1 or the number of VM virtual monitors.
1640	* @param paDisplays Definitions of guest screens to be applied. See VMMDev.h
1641	* @param fForce Whether to deliver the request to the guest even if the guest has
1642	* the requested resolution already.
1643	*/
1644	DECLR3CALLBACKMEMBER(int, pfnRequestDisplayChange,(PPDMIVMMDEVPORT pInterface, uint32_t cDisplays,
1645	struct VMMDevDisplayDef const *paDisplays, bool fForce));
1646
1647	/**
1648	* Pass credentials to guest.
1649	*
1650	* Note that there can only be one set of credentials and the guest may or may not
1651	* query them and may do whatever it wants with them.
1652	*
1653	* @returns VBox status code.
1654	* @param pInterface Pointer to the interface structure containing the called function pointer.
1655	* @param pszUsername User name, may be empty (UTF-8).
1656	* @param pszPassword Password, may be empty (UTF-8).
1657	* @param pszDomain Domain name, may be empty (UTF-8).
1658	* @param fFlags VMMDEV_SETCREDENTIALS_*.
1659	*/
1660	DECLR3CALLBACKMEMBER(int, pfnSetCredentials,(PPDMIVMMDEVPORT pInterface, const char *pszUsername,
1661	const char pszPassword, const char pszDomain,
1662	uint32_t fFlags));
1663
1664	/**
1665	* Notify the driver about a VBVA status change.
1666	*
1667	* @returns Nothing. Because it is informational callback.
1668	* @param pInterface Pointer to the interface structure containing the called function pointer.
1669	* @param fEnabled Current VBVA status.
1670	*/
1671	DECLR3CALLBACKMEMBER(void, pfnVBVAChange, (PPDMIVMMDEVPORT pInterface, bool fEnabled));
1672
1673	/**
1674	* Issue a seamless mode change request.
1675	*
1676	* Note that there can only one request in the queue and that in case the guest does
1677	* not process it, issuing another request will overwrite the previous.
1678	*
1679	* @returns VBox status code
1680	* @param pInterface Pointer to the interface structure containing the called function pointer.
1681	* @param fEnabled Seamless mode enabled or not
1682	*/
1683	DECLR3CALLBACKMEMBER(int, pfnRequestSeamlessChange,(PPDMIVMMDEVPORT pInterface, bool fEnabled));
1684
1685	/**
1686	* Issue a memory balloon change request.
1687	*
1688	* Note that there can only one request in the queue and that in case the guest does
1689	* not process it, issuing another request will overwrite the previous.
1690	*
1691	* @returns VBox status code
1692	* @param pInterface Pointer to the interface structure containing the called function pointer.
1693	* @param cMbBalloon Balloon size in megabytes
1694	*/
1695	DECLR3CALLBACKMEMBER(int, pfnSetMemoryBalloon,(PPDMIVMMDEVPORT pInterface, uint32_t cMbBalloon));
1696
1697	/**
1698	* Issue a statistcs interval change request.
1699	*
1700	* Note that there can only one request in the queue and that in case the guest does
1701	* not process it, issuing another request will overwrite the previous.
1702	*
1703	* @returns VBox status code
1704	* @param pInterface Pointer to the interface structure containing the called function pointer.
1705	* @param cSecsStatInterval Statistics query interval in seconds
1706	* (0=disable).
1707	*/
1708	DECLR3CALLBACKMEMBER(int, pfnSetStatisticsInterval,(PPDMIVMMDEVPORT pInterface, uint32_t cSecsStatInterval));
1709
1710	/**
1711	* Notify the guest about a VRDP status change.
1712	*
1713	* @returns VBox status code
1714	* @param pInterface Pointer to the interface structure containing the called function pointer.
1715	* @param fVRDPEnabled Current VRDP status.
1716	* @param uVRDPExperienceLevel Which visual effects to be disabled in
1717	* the guest.
1718	*/
1719	DECLR3CALLBACKMEMBER(int, pfnVRDPChange, (PPDMIVMMDEVPORT pInterface, bool fVRDPEnabled, uint32_t uVRDPExperienceLevel));
1720
1721	/**
1722	* Notify the guest of CPU hot-unplug event.
1723	*
1724	* @returns VBox status code
1725	* @param pInterface Pointer to the interface structure containing the called function pointer.
1726	* @param idCpuCore The core id of the CPU to remove.
1727	* @param idCpuPackage The package id of the CPU to remove.
1728	*/
1729	DECLR3CALLBACKMEMBER(int, pfnCpuHotUnplug, (PPDMIVMMDEVPORT pInterface, uint32_t idCpuCore, uint32_t idCpuPackage));
1730
1731	/**
1732	* Notify the guest of CPU hot-plug event.
1733	*
1734	* @returns VBox status code
1735	* @param pInterface Pointer to the interface structure containing the called function pointer.
1736	* @param idCpuCore The core id of the CPU to add.
1737	* @param idCpuPackage The package id of the CPU to add.
1738	*/
1739	DECLR3CALLBACKMEMBER(int, pfnCpuHotPlug, (PPDMIVMMDEVPORT pInterface, uint32_t idCpuCore, uint32_t idCpuPackage));
1740
1741	} PDMIVMMDEVPORT;
1742	/** PDMIVMMDEVPORT interface ID. */
1743	#define PDMIVMMDEVPORT_IID "2ccc19a5-742a-4af0-a7d3-31ea67ff50e9"
1744
1745
1746	/** Pointer to a HPET legacy notification interface. */
1747	typedef struct PDMIHPETLEGACYNOTIFY *PPDMIHPETLEGACYNOTIFY;
1748	/**
1749	* HPET legacy notification interface.
1750	*/
1751	typedef struct PDMIHPETLEGACYNOTIFY
1752	{
1753	/**
1754	* Notify about change of HPET legacy mode.
1755	*
1756	* @param pInterface Pointer to the interface structure containing the
1757	* called function pointer.
1758	* @param fActivated If HPET legacy mode is activated (@c true) or
1759	* deactivated (@c false).
1760	*/
1761	DECLR3CALLBACKMEMBER(void, pfnModeChanged,(PPDMIHPETLEGACYNOTIFY pInterface, bool fActivated));
1762	} PDMIHPETLEGACYNOTIFY;
1763	/** PDMIHPETLEGACYNOTIFY interface ID. */
1764	#define PDMIHPETLEGACYNOTIFY_IID "c9ada595-4b65-4311-8b21-b10498997774"
1765
1766
1767	/** @name Flags for PDMIVMMDEVPORT::pfnSetCredentials.
1768	* @{ */
1769	/** The guest should perform a logon with the credentials. */
1770	#define VMMDEV_SETCREDENTIALS_GUESTLOGON RT_BIT(0)
1771	/** The guest should prevent local logons. */
1772	#define VMMDEV_SETCREDENTIALS_NOLOCALLOGON RT_BIT(1)
1773	/** The guest should verify the credentials. */
1774	#define VMMDEV_SETCREDENTIALS_JUDGE RT_BIT(15)
1775	/** @} */
1776
1777	/** Forward declaration of the guest information structure. */
1778	struct VBoxGuestInfo;
1779	/** Forward declaration of the guest information-2 structure. */
1780	struct VBoxGuestInfo2;
1781	/** Forward declaration of the guest statistics structure */
1782	struct VBoxGuestStatistics;
1783	/** Forward declaration of the guest status structure */
1784	struct VBoxGuestStatus;
1785
1786	/** Forward declaration of the video accelerator command memory. */
1787	struct VBVAMEMORY;
1788	/** Pointer to video accelerator command memory. */
1789	typedef struct VBVAMEMORY *PVBVAMEMORY;
1790
1791	/** Pointer to a VMMDev connector interface. */
1792	typedef struct PDMIVMMDEVCONNECTOR *PPDMIVMMDEVCONNECTOR;
1793	/**
1794	* VMMDev connector interface (up).
1795	* Pair with PDMIVMMDEVPORT.
1796	*/
1797	typedef struct PDMIVMMDEVCONNECTOR
1798	{
1799	/**
1800	* Update guest facility status.
1801	*
1802	* Called in response to VMMDevReq_ReportGuestStatus, reset or state restore.
1803	*
1804	* @param pInterface Pointer to this interface.
1805	* @param uFacility The facility.
1806	* @param uStatus The status.
1807	* @param fFlags Flags assoicated with the update. Currently
1808	* reserved and should be ignored.
1809	* @param pTimeSpecTS Pointer to the timestamp of this report.
1810	* @thread The emulation thread.
1811	*/
1812	DECLR3CALLBACKMEMBER(void, pfnUpdateGuestStatus,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t uFacility, uint16_t uStatus,
1813	uint32_t fFlags, PCRTTIMESPEC pTimeSpecTS));
1814
1815	/**
1816	* Updates a guest user state.
1817	*
1818	* Called in response to VMMDevReq_ReportGuestUserState.
1819	*
1820	* @param pInterface Pointer to this interface.
1821	* @param pszUser Guest user name to update status for.
1822	* @param pszDomain Domain the guest user is bound to. Optional.
1823	* @param uState New guest user state to notify host about.
1824	* @param pabDetails Pointer to optional state data.
1825	* @param cbDetails Size (in bytes) of optional state data.
1826	* @thread The emulation thread.
1827	*/
1828	DECLR3CALLBACKMEMBER(void, pfnUpdateGuestUserState,(PPDMIVMMDEVCONNECTOR pInterface, const char *pszUser,
1829	const char *pszDomain, uint32_t uState,
1830	const uint8_t *pabDetails, uint32_t cbDetails));
1831
1832	/**
1833	* Reports the guest API and OS version.
1834	* Called whenever the Additions issue a guest info report request.
1835	*
1836	* @param pInterface Pointer to this interface.
1837	* @param pGuestInfo Pointer to guest information structure
1838	* @thread The emulation thread.
1839	*/
1840	DECLR3CALLBACKMEMBER(void, pfnUpdateGuestInfo,(PPDMIVMMDEVCONNECTOR pInterface, const struct VBoxGuestInfo *pGuestInfo));
1841
1842	/**
1843	* Reports the detailed Guest Additions version.
1844	*
1845	* @param pInterface Pointer to this interface.
1846	* @param uFullVersion The guest additions version as a full version.
1847	* Use VBOX_FULL_VERSION_GET_MAJOR,
1848	* VBOX_FULL_VERSION_GET_MINOR and
1849	* VBOX_FULL_VERSION_GET_BUILD to access it.
1850	* (This will not be zero, so turn down the
1851	* paranoia level a notch.)
1852	* @param pszName Pointer to the sanitized version name. This can
1853	* be empty, but will not be NULL. If not empty,
1854	* it will contain a build type tag and/or a
1855	* publisher tag. If both, then they are separated
1856	* by an underscore (VBOX_VERSION_STRING fashion).
1857	* @param uRevision The SVN revision. Can be 0.
1858	* @param fFeatures Feature mask, currently none are defined.
1859	*
1860	* @thread The emulation thread.
1861	*/
1862	DECLR3CALLBACKMEMBER(void, pfnUpdateGuestInfo2,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t uFullVersion,
1863	const char *pszName, uint32_t uRevision, uint32_t fFeatures));
1864
1865	/**
1866	* Update the guest additions capabilities.
1867	* This is called when the guest additions capabilities change. The new capabilities
1868	* are given and the connector should update its internal state.
1869	*
1870	* @param pInterface Pointer to this interface.
1871	* @param newCapabilities New capabilities.
1872	* @thread The emulation thread.
1873	*/
1874	DECLR3CALLBACKMEMBER(void, pfnUpdateGuestCapabilities,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t newCapabilities));
1875
1876	/**
1877	* Update the mouse capabilities.
1878	* This is called when the mouse capabilities change. The new capabilities
1879	* are given and the connector should update its internal state.
1880	*
1881	* @param pInterface Pointer to this interface.
1882	* @param newCapabilities New capabilities.
1883	* @thread The emulation thread.
1884	*/
1885	DECLR3CALLBACKMEMBER(void, pfnUpdateMouseCapabilities,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t newCapabilities));
1886
1887	/**
1888	* Update the pointer shape.
1889	* This is called when the mouse pointer shape changes. The new shape
1890	* is passed as a caller allocated buffer that will be freed after returning
1891	*
1892	* @param pInterface Pointer to this interface.
1893	* @param fVisible Visibility indicator (if false, the other parameters are undefined).
1894	* @param fAlpha Flag whether alpha channel is being passed.
1895	* @param xHot Pointer hot spot x coordinate.
1896	* @param yHot Pointer hot spot y coordinate.
1897	* @param x Pointer new x coordinate on screen.
1898	* @param y Pointer new y coordinate on screen.
1899	* @param cx Pointer width in pixels.
1900	* @param cy Pointer height in pixels.
1901	* @param cbScanline Size of one scanline in bytes.
1902	* @param pvShape New shape buffer.
1903	* @thread The emulation thread.
1904	*/
1905	DECLR3CALLBACKMEMBER(void, pfnUpdatePointerShape,(PPDMIVMMDEVCONNECTOR pInterface, bool fVisible, bool fAlpha,
1906	uint32_t xHot, uint32_t yHot,
1907	uint32_t cx, uint32_t cy,
1908	void *pvShape));
1909
1910	/**
1911	* Enable or disable video acceleration on behalf of guest.
1912	*
1913	* @param pInterface Pointer to this interface.
1914	* @param fEnable Whether to enable acceleration.
1915	* @param pVbvaMemory Video accelerator memory.
1916
1917	* @return VBox rc. VINF_SUCCESS if VBVA was enabled.
1918	* @thread The emulation thread.
1919	*/
1920	DECLR3CALLBACKMEMBER(int, pfnVideoAccelEnable,(PPDMIVMMDEVCONNECTOR pInterface, bool fEnable, PVBVAMEMORY pVbvaMemory));
1921
1922	/**
1923	* Force video queue processing.
1924	*
1925	* @param pInterface Pointer to this interface.
1926	* @thread The emulation thread.
1927	*/
1928	DECLR3CALLBACKMEMBER(void, pfnVideoAccelFlush,(PPDMIVMMDEVCONNECTOR pInterface));
1929
1930	/**
1931	* Return whether the given video mode is supported/wanted by the host.
1932	*
1933	* @returns VBox status code
1934	* @param pInterface Pointer to this interface.
1935	* @param display The guest monitor, 0 for primary.
1936	* @param cy Video mode horizontal resolution in pixels.
1937	* @param cx Video mode vertical resolution in pixels.
1938	* @param cBits Video mode bits per pixel.
1939	* @param pfSupported Where to put the indicator for whether this mode is supported. (output)
1940	* @thread The emulation thread.
1941	*/
1942	DECLR3CALLBACKMEMBER(int, pfnVideoModeSupported,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t display, uint32_t cx, uint32_t cy, uint32_t cBits, bool *pfSupported));
1943
1944	/**
1945	* Queries by how many pixels the height should be reduced when calculating video modes
1946	*
1947	* @returns VBox status code
1948	* @param pInterface Pointer to this interface.
1949	* @param pcyReduction Pointer to the result value.
1950	* @thread The emulation thread.
1951	*/
1952	DECLR3CALLBACKMEMBER(int, pfnGetHeightReduction,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t *pcyReduction));
1953
1954	/**
1955	* Informs about a credentials judgement result from the guest.
1956	*
1957	* @returns VBox status code
1958	* @param pInterface Pointer to this interface.
1959	* @param fFlags Judgement result flags.
1960	* @thread The emulation thread.
1961	*/
1962	DECLR3CALLBACKMEMBER(int, pfnSetCredentialsJudgementResult,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t fFlags));
1963
1964	/**
1965	* Set the visible region of the display
1966	*
1967	* @returns VBox status code.
1968	* @param pInterface Pointer to this interface.
1969	* @param cRect Number of rectangles in pRect
1970	* @param pRect Rectangle array
1971	* @thread The emulation thread.
1972	*/
1973	DECLR3CALLBACKMEMBER(int, pfnSetVisibleRegion,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t cRect, PRTRECT pRect));
1974
1975	/**
1976	* Query the visible region of the display
1977	*
1978	* @returns VBox status code.
1979	* @param pInterface Pointer to this interface.
1980	* @param pcRects Where to return the number of rectangles in
1981	* paRects.
1982	* @param paRects Rectangle array (set to NULL to query the number
1983	* of rectangles)
1984	* @thread The emulation thread.
1985	*/
1986	DECLR3CALLBACKMEMBER(int, pfnQueryVisibleRegion,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t *pcRects, PRTRECT paRects));
1987
1988	/**
1989	* Request the statistics interval
1990	*
1991	* @returns VBox status code.
1992	* @param pInterface Pointer to this interface.
1993	* @param pulInterval Pointer to interval in seconds
1994	* @thread The emulation thread.
1995	*/
1996	DECLR3CALLBACKMEMBER(int, pfnQueryStatisticsInterval,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t *pulInterval));
1997
1998	/**
1999	* Report new guest statistics
2000	*
2001	* @returns VBox status code.
2002	* @param pInterface Pointer to this interface.
2003	* @param pGuestStats Guest statistics
2004	* @thread The emulation thread.
2005	*/
2006	DECLR3CALLBACKMEMBER(int, pfnReportStatistics,(PPDMIVMMDEVCONNECTOR pInterface, struct VBoxGuestStatistics *pGuestStats));
2007
2008	/**
2009	* Query the current balloon size
2010	*
2011	* @returns VBox status code.
2012	* @param pInterface Pointer to this interface.
2013	* @param pcbBalloon Balloon size
2014	* @thread The emulation thread.
2015	*/
2016	DECLR3CALLBACKMEMBER(int, pfnQueryBalloonSize,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t *pcbBalloon));
2017
2018	/**
2019	* Query the current page fusion setting
2020	*
2021	* @returns VBox status code.
2022	* @param pInterface Pointer to this interface.
2023	* @param pfPageFusionEnabled Pointer to boolean
2024	* @thread The emulation thread.
2025	*/
2026	DECLR3CALLBACKMEMBER(int, pfnIsPageFusionEnabled,(PPDMIVMMDEVCONNECTOR pInterface, bool *pfPageFusionEnabled));
2027
2028	} PDMIVMMDEVCONNECTOR;
2029	/** PDMIVMMDEVCONNECTOR interface ID. */
2030	#define PDMIVMMDEVCONNECTOR_IID "aff90240-a443-434e-9132-80c186ab97d4"
2031
2032
2033	/**
2034	* Generic status LED core.
2035	* Note that a unit doesn't have to support all the indicators.
2036	*/
2037	typedef union PDMLEDCORE
2038	{
2039	/** 32-bit view. */
2040	uint32_t volatile u32;
2041	/** Bit view. */
2042	struct
2043	{
2044	/** Reading/Receiving indicator. */
2045	uint32_t fReading : 1;
2046	/** Writing/Sending indicator. */
2047	uint32_t fWriting : 1;
2048	/** Busy indicator. */
2049	uint32_t fBusy : 1;
2050	/** Error indicator. */
2051	uint32_t fError : 1;
2052	} s;
2053	} PDMLEDCORE;
2054
2055	/** LED bit masks for the u32 view.
2056	* @{ */
2057	/** Reading/Receiving indicator. */
2058	#define PDMLED_READING RT_BIT(0)
2059	/** Writing/Sending indicator. */
2060	#define PDMLED_WRITING RT_BIT(1)
2061	/** Busy indicator. */
2062	#define PDMLED_BUSY RT_BIT(2)
2063	/** Error indicator. */
2064	#define PDMLED_ERROR RT_BIT(3)
2065	/** @} */
2066
2067
2068	/**
2069	* Generic status LED.
2070	* Note that a unit doesn't have to support all the indicators.
2071	*/
2072	typedef struct PDMLED
2073	{
2074	/** Just a magic for sanity checking. */
2075	uint32_t u32Magic;
2076	uint32_t u32Alignment; /*< structure size alignment. /
2077	/** The actual LED status.
2078	* Only the device is allowed to change this. */
2079	PDMLEDCORE Actual;
2080	/** The asserted LED status which is cleared by the reader.
2081	* The device will assert the bits but never clear them.
2082	* The driver clears them as it sees fit. */
2083	PDMLEDCORE Asserted;
2084	} PDMLED;
2085
2086	/** Pointer to an LED. */
2087	typedef PDMLED *PPDMLED;
2088	/** Pointer to a const LED. */
2089	typedef const PDMLED *PCPDMLED;
2090
2091	/** Magic value for PDMLED::u32Magic. */
2092	#define PDMLED_MAGIC UINT32_C(0x11335577)
2093
2094	/** Pointer to an LED ports interface. */
2095	typedef struct PDMILEDPORTS *PPDMILEDPORTS;
2096	/**
2097	* Interface for exporting LEDs (down).
2098	* Pair with PDMILEDCONNECTORS.
2099	*/
2100	typedef struct PDMILEDPORTS
2101	{
2102	/**
2103	* Gets the pointer to the status LED of a unit.
2104	*
2105	* @returns VBox status code.
2106	* @param pInterface Pointer to the interface structure containing the called function pointer.
2107	* @param iLUN The unit which status LED we desire.
2108	* @param ppLed Where to store the LED pointer.
2109	*/
2110	DECLR3CALLBACKMEMBER(int, pfnQueryStatusLed,(PPDMILEDPORTS pInterface, unsigned iLUN, PPDMLED *ppLed));
2111
2112	} PDMILEDPORTS;
2113	/** PDMILEDPORTS interface ID. */
2114	#define PDMILEDPORTS_IID "435e0cec-8549-4ca0-8c0d-98e52f1dc038"
2115
2116
2117	/** Pointer to an LED connectors interface. */
2118	typedef struct PDMILEDCONNECTORS *PPDMILEDCONNECTORS;
2119	/**
2120	* Interface for reading LEDs (up).
2121	* Pair with PDMILEDPORTS.
2122	*/
2123	typedef struct PDMILEDCONNECTORS
2124	{
2125	/**
2126	* Notification about a unit which have been changed.
2127	*
2128	* The driver must discard any pointers to data owned by
2129	* the unit and requery it.
2130	*
2131	* @param pInterface Pointer to the interface structure containing the called function pointer.
2132	* @param iLUN The unit number.
2133	*/
2134	DECLR3CALLBACKMEMBER(void, pfnUnitChanged,(PPDMILEDCONNECTORS pInterface, unsigned iLUN));
2135	} PDMILEDCONNECTORS;
2136	/** PDMILEDCONNECTORS interface ID. */
2137	#define PDMILEDCONNECTORS_IID "8ed63568-82a7-4193-b57b-db8085ac4495"
2138
2139
2140	/** Pointer to a Media Notification interface. */
2141	typedef struct PDMIMEDIANOTIFY *PPDMIMEDIANOTIFY;
2142	/**
2143	* Interface for exporting Medium eject information (up). No interface pair.
2144	*/
2145	typedef struct PDMIMEDIANOTIFY
2146	{
2147	/**
2148	* Signals that the medium was ejected.
2149	*
2150	* @returns VBox status code.
2151	* @param pInterface Pointer to the interface structure containing the called function pointer.
2152	* @param iLUN The unit which had the medium ejected.
2153	*/
2154	DECLR3CALLBACKMEMBER(int, pfnEjected,(PPDMIMEDIANOTIFY pInterface, unsigned iLUN));
2155
2156	} PDMIMEDIANOTIFY;
2157	/** PDMIMEDIANOTIFY interface ID. */
2158	#define PDMIMEDIANOTIFY_IID "fc22d53e-feb1-4a9c-b9fb-0a990a6ab288"
2159
2160
2161	/** The special status unit number */
2162	#define PDM_STATUS_LUN 999
2163
2164
2165	#ifdef VBOX_WITH_HGCM
2166
2167	/** Abstract HGCM command structure. Used only to define a typed pointer. */
2168	struct VBOXHGCMCMD;
2169
2170	/** Pointer to HGCM command structure. This pointer is unique and identifies
2171	* the command being processed. The pointer is passed to HGCM connector methods,
2172	* and must be passed back to HGCM port when command is completed.
2173	*/
2174	typedef struct VBOXHGCMCMD *PVBOXHGCMCMD;
2175
2176	/** Pointer to a HGCM port interface. */
2177	typedef struct PDMIHGCMPORT *PPDMIHGCMPORT;
2178	/**
2179	* Host-Guest communication manager port interface (down). Normally implemented
2180	* by VMMDev.
2181	* Pair with PDMIHGCMCONNECTOR.
2182	*/
2183	typedef struct PDMIHGCMPORT
2184	{
2185	/**
2186	* Notify the guest on a command completion.
2187	*
2188	* @param pInterface Pointer to this interface.
2189	* @param rc The return code (VBox error code).
2190	* @param pCmd A pointer that identifies the completed command.
2191	*
2192	* @returns VBox status code
2193	*/
2194	DECLR3CALLBACKMEMBER(void, pfnCompleted,(PPDMIHGCMPORT pInterface, int32_t rc, PVBOXHGCMCMD pCmd));
2195
2196	} PDMIHGCMPORT;
2197	/** PDMIHGCMPORT interface ID. */
2198	# define PDMIHGCMPORT_IID "e00a0cbf-b75a-45c3-87f4-41cddbc5ae0b"
2199
2200
2201	/** Pointer to a HGCM service location structure. */
2202	typedef struct HGCMSERVICELOCATION *PHGCMSERVICELOCATION;
2203
2204	/** Pointer to a HGCM connector interface. */
2205	typedef struct PDMIHGCMCONNECTOR *PPDMIHGCMCONNECTOR;
2206	/**
2207	* The Host-Guest communication manager connector interface (up). Normally
2208	* implemented by Main::VMMDevInterface.
2209	* Pair with PDMIHGCMPORT.
2210	*/
2211	typedef struct PDMIHGCMCONNECTOR
2212	{
2213	/**
2214	* Locate a service and inform it about a client connection.
2215	*
2216	* @param pInterface Pointer to this interface.
2217	* @param pCmd A pointer that identifies the command.
2218	* @param pServiceLocation Pointer to the service location structure.
2219	* @param pu32ClientID Where to store the client id for the connection.
2220	* @return VBox status code.
2221	* @thread The emulation thread.
2222	*/
2223	DECLR3CALLBACKMEMBER(int, pfnConnect,(PPDMIHGCMCONNECTOR pInterface, PVBOXHGCMCMD pCmd, PHGCMSERVICELOCATION pServiceLocation, uint32_t *pu32ClientID));
2224
2225	/**
2226	* Disconnect from service.
2227	*
2228	* @param pInterface Pointer to this interface.
2229	* @param pCmd A pointer that identifies the command.
2230	* @param u32ClientID The client id returned by the pfnConnect call.
2231	* @return VBox status code.
2232	* @thread The emulation thread.
2233	*/
2234	DECLR3CALLBACKMEMBER(int, pfnDisconnect,(PPDMIHGCMCONNECTOR pInterface, PVBOXHGCMCMD pCmd, uint32_t u32ClientID));
2235
2236	/**
2237	* Process a guest issued command.
2238	*
2239	* @param pInterface Pointer to this interface.
2240	* @param pCmd A pointer that identifies the command.
2241	* @param u32ClientID The client id returned by the pfnConnect call.
2242	* @param u32Function Function to be performed by the service.
2243	* @param cParms Number of parameters in the array pointed to by paParams.
2244	* @param paParms Pointer to an array of parameters.
2245	* @return VBox status code.
2246	* @thread The emulation thread.
2247	*/
2248	DECLR3CALLBACKMEMBER(int, pfnCall,(PPDMIHGCMCONNECTOR pInterface, PVBOXHGCMCMD pCmd, uint32_t u32ClientID, uint32_t u32Function,
2249	uint32_t cParms, PVBOXHGCMSVCPARM paParms));
2250
2251	} PDMIHGCMCONNECTOR;
2252	/** PDMIHGCMCONNECTOR interface ID. */
2253	# define PDMIHGCMCONNECTOR_IID "a1104758-c888-4437-8f2a-7bac17865b5c"
2254
2255	#endif /* VBOX_WITH_HGCM */
2256
2257
2258	/** Pointer to a display VBVA callbacks interface. */
2259	typedef struct PDMIDISPLAYVBVACALLBACKS *PPDMIDISPLAYVBVACALLBACKS;
2260	/**
2261	* Display VBVA callbacks interface (up).
2262	*/
2263	typedef struct PDMIDISPLAYVBVACALLBACKS
2264	{
2265
2266	/**
2267	* Informs guest about completion of processing the given Video HW Acceleration
2268	* command, does not wait for the guest to process the command.
2269	*
2270	* @returns ???
2271	* @param pInterface Pointer to this interface.
2272	* @param pCmd The Video HW Acceleration Command that was
2273	* completed.
2274	*/
2275	DECLR3CALLBACKMEMBER(int, pfnVHWACommandCompleteAsync,(PPDMIDISPLAYVBVACALLBACKS pInterface,
2276	VBOXVHWACMD RT_UNTRUSTED_VOLATILE_GUEST *pCmd));
2277
2278	DECLR3CALLBACKMEMBER(int, pfnCrHgsmiCommandCompleteAsync,(PPDMIDISPLAYVBVACALLBACKS pInterface,
2279	struct VBOXVDMACMD_CHROMIUM_CMD *pCmd, int rc));
2280
2281	DECLR3CALLBACKMEMBER(int, pfnCrHgsmiControlCompleteAsync,(PPDMIDISPLAYVBVACALLBACKS pInterface,
2282	struct VBOXVDMACMD_CHROMIUM_CTL *pCmd, int rc));
2283
2284	DECLR3CALLBACKMEMBER(int, pfnCrCtlSubmit,(PPDMIDISPLAYVBVACALLBACKS pInterface, struct VBOXCRCMDCTL *pCmd, uint32_t cbCmd,
2285	PFNCRCTLCOMPLETION pfnCompletion, void *pvCompletion));
2286
2287	DECLR3CALLBACKMEMBER(int, pfnCrCtlSubmitSync,(PPDMIDISPLAYVBVACALLBACKS pInterface,
2288	struct VBOXCRCMDCTL *pCmd, uint32_t cbCmd));
2289	} PDMIDISPLAYVBVACALLBACKS;
2290	/** PDMIDISPLAYVBVACALLBACKS */
2291	#define PDMIDISPLAYVBVACALLBACKS_IID "ddac0bd0-332d-4671-8853-732921a80216"
2292
2293	/** Pointer to a PCI raw connector interface. */
2294	typedef struct PDMIPCIRAWCONNECTOR *PPDMIPCIRAWCONNECTOR;
2295	/**
2296	* PCI raw connector interface (up).
2297	*/
2298	typedef struct PDMIPCIRAWCONNECTOR
2299	{
2300
2301	/**
2302	*
2303	*/
2304	DECLR3CALLBACKMEMBER(int, pfnDeviceConstructComplete, (PPDMIPCIRAWCONNECTOR pInterface, const char *pcszName,
2305	uint32_t uHostPciAddress, uint32_t uGuestPciAddress,
2306	int rc));
2307
2308	} PDMIPCIRAWCONNECTOR;
2309	/** PDMIPCIRAWCONNECTOR interface ID. */
2310	#define PDMIPCIRAWCONNECTOR_IID "14aa9c6c-8869-4782-9dfc-910071a6aebf"
2311
2312	/** @} */
2313
2314	RT_C_DECLS_END
2315
2316	#endif

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

source: vbox/trunk/include/VBox/vmm/pdmifs.h@ 72352

Download in other formats: