pdmifs.h@ 47036

Last change on this file since 47036 was 47036, checked in by vboxsync, 11 years ago
BIOS,DevFdc,DrvBlock: The floppy controller should query the block/host driver for the drive type, or it'll all go real bad if the guest code trusts CMOS/BIOS drive info. Changed the block driver to automatically upgrade the drive type (for fdc and bios/cmos setup only) if the image is larger than the configured drive capacity. Introduced two fake drive types with max capacities, 15.6 MB and 63.5 MB, the first is the max that INT13 can officially access, the second is reinterpreting CL as holding an 8-bit wide sector number and no cylinder bits (which actually seems to be how real bioses work with floppies).
Property svn:eol-style set to `native` Property svn:keywords set to `Id`
File size: 122.2 KB

Line
1	/** @file
2	* PDM - Pluggable Device Manager, Interfaces.
3	*/
4
5	/*
6	* Copyright (C) 2006-2012 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 iDeltaX The X delta.
301	* @param iDeltaY The Y delta.
302	* @param iDeltaZ The Z delta.
303	* @param iDeltaW The W (horizontal scroll button) delta.
304	* @param fButtonStates The button states, see the PDMIMOUSEPORT_BUTTON_* \#defines.
305	*/
306	DECLR3CALLBACKMEMBER(int, pfnPutEvent,(PPDMIMOUSEPORT pInterface, int32_t iDeltaX, int32_t iDeltaY, int32_t iDeltaZ, int32_t iDeltaW, uint32_t fButtonStates));
307	/**
308	* Puts an absolute mouse event.
309	*
310	* This is called by the source of mouse events. The event will be passed up
311	* until the topmost driver, which then calls the registered event handler.
312	*
313	* @returns VBox status code. Return VERR_TRY_AGAIN if you cannot process the
314	* event now and want it to be repeated at a later point.
315	*
316	* @param pInterface Pointer to this interface structure.
317	* @param uX The X value, in the range 0 to 0xffff.
318	* @param uY The Y value, in the range 0 to 0xffff.
319	* @param iDeltaZ The Z delta.
320	* @param iDeltaW The W (horizontal scroll button) delta.
321	* @param fButtonStates The button states, see the PDMIMOUSEPORT_BUTTON_* \#defines.
322	*/
323	DECLR3CALLBACKMEMBER(int, pfnPutEventAbs,(PPDMIMOUSEPORT pInterface, uint32_t uX, uint32_t uY, int32_t iDeltaZ, int32_t iDeltaW, uint32_t fButtonStates));
324	} PDMIMOUSEPORT;
325	/** PDMIMOUSEPORT interface ID. */
326	#define PDMIMOUSEPORT_IID "442136fe-6f3c-49ec-9964-259b378ffa64"
327
328	/** Mouse button defines for PDMIMOUSEPORT::pfnPutEvent.
329	* @{ */
330	#define PDMIMOUSEPORT_BUTTON_LEFT RT_BIT(0)
331	#define PDMIMOUSEPORT_BUTTON_RIGHT RT_BIT(1)
332	#define PDMIMOUSEPORT_BUTTON_MIDDLE RT_BIT(2)
333	#define PDMIMOUSEPORT_BUTTON_X1 RT_BIT(3)
334	#define PDMIMOUSEPORT_BUTTON_X2 RT_BIT(4)
335	/** @} */
336
337
338	/** Pointer to a mouse connector interface. */
339	typedef struct PDMIMOUSECONNECTOR *PPDMIMOUSECONNECTOR;
340	/**
341	* Mouse connector interface (up).
342	* Pair with PDMIMOUSEPORT.
343	*/
344	typedef struct PDMIMOUSECONNECTOR
345	{
346	/**
347	* Notifies the the downstream driver of changes to the reporting modes
348	* supported by the driver
349	*
350	* @param pInterface Pointer to the this interface.
351	* @param fRelative Whether relative mode is currently supported.
352	* @param fAbsolute Whether absolute mode is currently supported.
353	* @param fAbsolute Whether multi-touch mode is currently supported.
354	*/
355	DECLR3CALLBACKMEMBER(void, pfnReportModes,(PPDMIMOUSECONNECTOR pInterface, bool fRelative, bool fAbsolute, bool fMultiTouch));
356
357	} PDMIMOUSECONNECTOR;
358	/** PDMIMOUSECONNECTOR interface ID. */
359	#define PDMIMOUSECONNECTOR_IID "ce64d7bd-fa8f-41d1-a6fb-d102a2d6bffe"
360
361
362	/** Pointer to a keyboard port interface. */
363	typedef struct PDMIKEYBOARDPORT *PPDMIKEYBOARDPORT;
364	/**
365	* Keyboard port interface (down).
366	* Pair with PDMIKEYBOARDCONNECTOR.
367	*/
368	typedef struct PDMIKEYBOARDPORT
369	{
370	/**
371	* Puts a keyboard event.
372	*
373	* This is called by the source of keyboard events. The event will be passed up
374	* until the topmost driver, which then calls the registered event handler.
375	*
376	* @returns VBox status code. Return VERR_TRY_AGAIN if you cannot process the
377	* event now and want it to be repeated at a later point.
378	*
379	* @param pInterface Pointer to this interface structure.
380	* @param u8KeyCode The keycode to queue.
381	*/
382	DECLR3CALLBACKMEMBER(int, pfnPutEvent,(PPDMIKEYBOARDPORT pInterface, uint8_t u8KeyCode));
383	} PDMIKEYBOARDPORT;
384	/** PDMIKEYBOARDPORT interface ID. */
385	#define PDMIKEYBOARDPORT_IID "2a0844f0-410b-40ab-a6ed-6575f3aa3e29"
386
387
388	/**
389	* Keyboard LEDs.
390	*/
391	typedef enum PDMKEYBLEDS
392	{
393	/** No leds. */
394	PDMKEYBLEDS_NONE = 0x0000,
395	/** Num Lock */
396	PDMKEYBLEDS_NUMLOCK = 0x0001,
397	/** Caps Lock */
398	PDMKEYBLEDS_CAPSLOCK = 0x0002,
399	/** Scroll Lock */
400	PDMKEYBLEDS_SCROLLLOCK = 0x0004
401	} PDMKEYBLEDS;
402
403	/** Pointer to keyboard connector interface. */
404	typedef struct PDMIKEYBOARDCONNECTOR *PPDMIKEYBOARDCONNECTOR;
405	/**
406	* Keyboard connector interface (up).
407	* Pair with PDMIKEYBOARDPORT
408	*/
409	typedef struct PDMIKEYBOARDCONNECTOR
410	{
411	/**
412	* Notifies the the downstream driver about an LED change initiated by the guest.
413	*
414	* @param pInterface Pointer to the this interface.
415	* @param enmLeds The new led mask.
416	*/
417	DECLR3CALLBACKMEMBER(void, pfnLedStatusChange,(PPDMIKEYBOARDCONNECTOR pInterface, PDMKEYBLEDS enmLeds));
418
419	/**
420	* Notifies the the downstream driver of changes in driver state.
421	*
422	* @param pInterface Pointer to the this interface.
423	* @param fActive Whether interface wishes to get "focus".
424	*/
425	DECLR3CALLBACKMEMBER(void, pfnSetActive,(PPDMIKEYBOARDCONNECTOR pInterface, bool fActive));
426
427	} PDMIKEYBOARDCONNECTOR;
428	/** PDMIKEYBOARDCONNECTOR interface ID. */
429	#define PDMIKEYBOARDCONNECTOR_IID "db3f7bd5-953e-436f-9f8e-077905a92d82"
430
431
432
433	/** Pointer to a display port interface. */
434	typedef struct PDMIDISPLAYPORT *PPDMIDISPLAYPORT;
435	/**
436	* Display port interface (down).
437	* Pair with PDMIDISPLAYCONNECTOR.
438	*/
439	typedef struct PDMIDISPLAYPORT
440	{
441	/**
442	* Update the display with any changed regions.
443	*
444	* Flushes any display changes to the memory pointed to by the
445	* PDMIDISPLAYCONNECTOR interface and calles PDMIDISPLAYCONNECTOR::pfnUpdateRect()
446	* while doing so.
447	*
448	* @returns VBox status code.
449	* @param pInterface Pointer to this interface.
450	* @thread The emulation thread.
451	*/
452	DECLR3CALLBACKMEMBER(int, pfnUpdateDisplay,(PPDMIDISPLAYPORT pInterface));
453
454	/**
455	* Update the entire display.
456	*
457	* Flushes the entire display content to the memory pointed to by the
458	* PDMIDISPLAYCONNECTOR interface and calles PDMIDISPLAYCONNECTOR::pfnUpdateRect().
459	*
460	* @returns VBox status code.
461	* @param pInterface Pointer to this interface.
462	* @thread The emulation thread.
463	*/
464	DECLR3CALLBACKMEMBER(int, pfnUpdateDisplayAll,(PPDMIDISPLAYPORT pInterface));
465
466	/**
467	* Return the current guest color depth in bits per pixel (bpp).
468	*
469	* As the graphics card is able to provide display updates with the bpp
470	* requested by the host, this method can be used to query the actual
471	* guest color depth.
472	*
473	* @returns VBox status code.
474	* @param pInterface Pointer to this interface.
475	* @param pcBits Where to store the current guest color depth.
476	* @thread Any thread.
477	*/
478	DECLR3CALLBACKMEMBER(int, pfnQueryColorDepth,(PPDMIDISPLAYPORT pInterface, uint32_t *pcBits));
479
480	/**
481	* Sets the refresh rate and restart the timer.
482	* The rate is defined as the minimum interval between the return of
483	* one PDMIDISPLAYPORT::pfnRefresh() call to the next one.
484	*
485	* The interval timer will be restarted by this call. So at VM startup
486	* this function must be called to start the refresh cycle. The refresh
487	* rate is not saved, but have to be when resuming a loaded VM state.
488	*
489	* @returns VBox status code.
490	* @param pInterface Pointer to this interface.
491	* @param cMilliesInterval Number of millis between two refreshes.
492	* @thread Any thread.
493	*/
494	DECLR3CALLBACKMEMBER(int, pfnSetRefreshRate,(PPDMIDISPLAYPORT pInterface, uint32_t cMilliesInterval));
495
496	/**
497	* Create a 32-bbp screenshot of the display.
498	*
499	* This will allocate and return a 32-bbp bitmap. Size of the bitmap scanline in bytes is 4*width.
500	*
501	* The allocated bitmap buffer must be freed with pfnFreeScreenshot.
502	*
503	* @param pInterface Pointer to this interface.
504	* @param ppu8Data Where to store the pointer to the allocated buffer.
505	* @param pcbData Where to store the actual size of the bitmap.
506	* @param pcx Where to store the width of the bitmap.
507	* @param pcy Where to store the height of the bitmap.
508	* @thread The emulation thread.
509	*/
510	DECLR3CALLBACKMEMBER(int, pfnTakeScreenshot,(PPDMIDISPLAYPORT pInterface, uint8_t *ppu8Data, size_t pcbData, uint32_t pcx, uint32_t pcy));
511
512	/**
513	* Free screenshot buffer.
514	*
515	* This will free the memory buffer allocated by pfnTakeScreenshot.
516	*
517	* @param pInterface Pointer to this interface.
518	* @param ppu8Data Pointer to the buffer returned by pfnTakeScreenshot.
519	* @thread Any.
520	*/
521	DECLR3CALLBACKMEMBER(void, pfnFreeScreenshot,(PPDMIDISPLAYPORT pInterface, uint8_t *pu8Data));
522
523	/**
524	* Copy bitmap to the display.
525	*
526	* This will convert and copy a 32-bbp bitmap (with dword aligned scanline length) to
527	* the memory pointed to by the PDMIDISPLAYCONNECTOR interface.
528	*
529	* @param pInterface Pointer to this interface.
530	* @param pvData Pointer to the bitmap bits.
531	* @param x The upper left corner x coordinate of the destination rectangle.
532	* @param y The upper left corner y coordinate of the destination rectangle.
533	* @param cx The width of the source and destination rectangles.
534	* @param cy The height of the source and destination rectangles.
535	* @thread The emulation thread.
536	* @remark This is just a convenience for using the bitmap conversions of the
537	* graphics device.
538	*/
539	DECLR3CALLBACKMEMBER(int, pfnDisplayBlt,(PPDMIDISPLAYPORT pInterface, const void *pvData, uint32_t x, uint32_t y, uint32_t cx, uint32_t cy));
540
541	/**
542	* Render a rectangle from guest VRAM to Framebuffer.
543	*
544	* @param pInterface Pointer to this interface.
545	* @param x The upper left corner x coordinate of the rectangle to be updated.
546	* @param y The upper left corner y coordinate of the rectangle to be updated.
547	* @param cx The width of the rectangle to be updated.
548	* @param cy The height of the rectangle to be updated.
549	* @thread The emulation thread.
550	*/
551	DECLR3CALLBACKMEMBER(void, pfnUpdateDisplayRect,(PPDMIDISPLAYPORT pInterface, int32_t x, int32_t y, uint32_t cx, uint32_t cy));
552
553	/**
554	* Inform the VGA device whether the Display is directly using the guest VRAM and there is no need
555	* to render the VRAM to the framebuffer memory.
556	*
557	* @param pInterface Pointer to this interface.
558	* @param fRender Whether the VRAM content must be rendered to the framebuffer.
559	* @thread The emulation thread.
560	*/
561	DECLR3CALLBACKMEMBER(void, pfnSetRenderVRAM,(PPDMIDISPLAYPORT pInterface, bool fRender));
562
563	/**
564	* Render a bitmap rectangle from source to target buffer.
565	*
566	* @param pInterface Pointer to this interface.
567	* @param cx The width of the rectangle to be copied.
568	* @param cy The height of the rectangle to be copied.
569	* @param pbSrc Source frame buffer 0,0.
570	* @param xSrc The upper left corner x coordinate of the source rectangle.
571	* @param ySrc The upper left corner y coordinate of the source rectangle.
572	* @param cxSrc The width of the source frame buffer.
573	* @param cySrc The height of the source frame buffer.
574	* @param cbSrcLine The line length of the source frame buffer.
575	* @param cSrcBitsPerPixel The pixel depth of the source.
576	* @param pbDst Destination frame buffer 0,0.
577	* @param xDst The upper left corner x coordinate of the destination rectangle.
578	* @param yDst The upper left corner y coordinate of the destination rectangle.
579	* @param cxDst The width of the destination frame buffer.
580	* @param cyDst The height of the destination frame buffer.
581	* @param cbDstLine The line length of the destination frame buffer.
582	* @param cDstBitsPerPixel The pixel depth of the destination.
583	* @thread The emulation thread.
584	*/
585	DECLR3CALLBACKMEMBER(int, pfnCopyRect,(PPDMIDISPLAYPORT pInterface, uint32_t cx, uint32_t cy,
586	const uint8_t *pbSrc, int32_t xSrc, int32_t ySrc, uint32_t cxSrc, uint32_t cySrc, uint32_t cbSrcLine, uint32_t cSrcBitsPerPixel,
587	uint8_t *pbDst, int32_t xDst, int32_t yDst, uint32_t cxDst, uint32_t cyDst, uint32_t cbDstLine, uint32_t cDstBitsPerPixel));
588
589	} PDMIDISPLAYPORT;
590	/** PDMIDISPLAYPORT interface ID. */
591	#define PDMIDISPLAYPORT_IID "22d3d93d-3407-487a-8308-85367eae00bb"
592
593
594	typedef struct VBOXVHWACMD PVBOXVHWACMD; /< @todo r=bird: A line what it is to make doxygen happy. /
595	typedef struct VBVACMDHDR *PVBVACMDHDR;
596	typedef struct VBVAINFOSCREEN *PVBVAINFOSCREEN;
597	typedef struct VBVAINFOVIEW *PVBVAINFOVIEW;
598	typedef struct VBVAHOSTFLAGS *PVBVAHOSTFLAGS;
599	typedef struct VBOXVDMACMD_CHROMIUM_CMD PVBOXVDMACMD_CHROMIUM_CMD; / <- chromium [hgsmi] command */
600	typedef struct VBOXVDMACMD_CHROMIUM_CTL PVBOXVDMACMD_CHROMIUM_CTL; / <- chromium [hgsmi] command */
601
602	/** Pointer to a display connector interface. */
603	typedef struct PDMIDISPLAYCONNECTOR *PPDMIDISPLAYCONNECTOR;
604	/**
605	* Display connector interface (up).
606	* Pair with PDMIDISPLAYPORT.
607	*/
608	typedef struct PDMIDISPLAYCONNECTOR
609	{
610	/**
611	* Resize the display.
612	* This is called when the resolution changes. This usually happens on
613	* request from the guest os, but may also happen as the result of a reset.
614	* If the callback returns VINF_VGA_RESIZE_IN_PROGRESS, the caller (VGA device)
615	* must not access the connector and return.
616	*
617	* @returns VINF_SUCCESS if the framebuffer resize was completed,
618	* VINF_VGA_RESIZE_IN_PROGRESS if resize takes time and not yet finished.
619	* @param pInterface Pointer to this interface.
620	* @param cBits Color depth (bits per pixel) of the new video mode.
621	* @param pvVRAM Address of the guest VRAM.
622	* @param cbLine Size in bytes of a single scan line.
623	* @param cx New display width.
624	* @param cy New display height.
625	* @thread The emulation thread.
626	*/
627	DECLR3CALLBACKMEMBER(int, pfnResize,(PPDMIDISPLAYCONNECTOR pInterface, uint32_t cBits, void *pvVRAM, uint32_t cbLine, uint32_t cx, uint32_t cy));
628
629	/**
630	* Update a rectangle of the display.
631	* PDMIDISPLAYPORT::pfnUpdateDisplay is the caller.
632	*
633	* @param pInterface Pointer to this interface.
634	* @param x The upper left corner x coordinate of the rectangle.
635	* @param y The upper left corner y coordinate of the rectangle.
636	* @param cx The width of the rectangle.
637	* @param cy The height of the rectangle.
638	* @thread The emulation thread.
639	*/
640	DECLR3CALLBACKMEMBER(void, pfnUpdateRect,(PPDMIDISPLAYCONNECTOR pInterface, uint32_t x, uint32_t y, uint32_t cx, uint32_t cy));
641
642	/**
643	* Refresh the display.
644	*
645	* The interval between these calls is set by
646	* PDMIDISPLAYPORT::pfnSetRefreshRate(). The driver should call
647	* PDMIDISPLAYPORT::pfnUpdateDisplay() if it wishes to refresh the
648	* display. PDMIDISPLAYPORT::pfnUpdateDisplay calls pfnUpdateRect with
649	* the changed rectangles.
650	*
651	* @param pInterface Pointer to this interface.
652	* @thread The emulation thread.
653	*/
654	DECLR3CALLBACKMEMBER(void, pfnRefresh,(PPDMIDISPLAYCONNECTOR pInterface));
655
656	/**
657	* Reset the display.
658	*
659	* Notification message when the graphics card has been reset.
660	*
661	* @param pInterface Pointer to this interface.
662	* @thread The emulation thread.
663	*/
664	DECLR3CALLBACKMEMBER(void, pfnReset,(PPDMIDISPLAYCONNECTOR pInterface));
665
666	/**
667	* LFB video mode enter/exit.
668	*
669	* Notification message when LinearFrameBuffer video mode is enabled/disabled.
670	*
671	* @param pInterface Pointer to this interface.
672	* @param fEnabled false - LFB mode was disabled,
673	* true - an LFB mode was disabled
674	* @thread The emulation thread.
675	*/
676	DECLR3CALLBACKMEMBER(void, pfnLFBModeChange, (PPDMIDISPLAYCONNECTOR pInterface, bool fEnabled));
677
678	/**
679	* Process the guest graphics adapter information.
680	*
681	* Direct notification from guest to the display connector.
682	*
683	* @param pInterface Pointer to this interface.
684	* @param pvVRAM Address of the guest VRAM.
685	* @param u32VRAMSize Size of the guest VRAM.
686	* @thread The emulation thread.
687	*/
688	DECLR3CALLBACKMEMBER(void, pfnProcessAdapterData, (PPDMIDISPLAYCONNECTOR pInterface, void *pvVRAM, uint32_t u32VRAMSize));
689
690	/**
691	* Process the guest display information.
692	*
693	* Direct notification from guest to the display connector.
694	*
695	* @param pInterface Pointer to this interface.
696	* @param pvVRAM Address of the guest VRAM.
697	* @param uScreenId The index of the guest display to be processed.
698	* @thread The emulation thread.
699	*/
700	DECLR3CALLBACKMEMBER(void, pfnProcessDisplayData, (PPDMIDISPLAYCONNECTOR pInterface, void *pvVRAM, unsigned uScreenId));
701
702	/**
703	* Process the guest Video HW Acceleration command.
704	*
705	* @param pInterface Pointer to this interface.
706	* @param pCmd Video HW Acceleration Command to be processed.
707	* @thread The emulation thread.
708	*/
709	DECLR3CALLBACKMEMBER(void, pfnVHWACommandProcess, (PPDMIDISPLAYCONNECTOR pInterface, PVBOXVHWACMD pCmd));
710
711	/**
712	* Process the guest chromium command.
713	*
714	* @param pInterface Pointer to this interface.
715	* @param pCmd Video HW Acceleration Command to be processed.
716	* @thread The emulation thread.
717	*/
718	DECLR3CALLBACKMEMBER(void, pfnCrHgsmiCommandProcess, (PPDMIDISPLAYCONNECTOR pInterface, PVBOXVDMACMD_CHROMIUM_CMD pCmd, uint32_t cbCmd));
719
720	/**
721	* Process the guest chromium control command.
722	*
723	* @param pInterface Pointer to this interface.
724	* @param pCmd Video HW Acceleration Command to be processed.
725	* @thread The emulation thread.
726	*/
727	DECLR3CALLBACKMEMBER(void, pfnCrHgsmiControlProcess, (PPDMIDISPLAYCONNECTOR pInterface, PVBOXVDMACMD_CHROMIUM_CTL pCtl, uint32_t cbCtl));
728
729
730	/**
731	* The specified screen enters VBVA mode.
732	*
733	* @param pInterface Pointer to this interface.
734	* @param uScreenId The screen updates are for.
735	* @thread The emulation thread.
736	*/
737	DECLR3CALLBACKMEMBER(int, pfnVBVAEnable,(PPDMIDISPLAYCONNECTOR pInterface, unsigned uScreenId, PVBVAHOSTFLAGS pHostFlags));
738
739	/**
740	* The specified screen leaves VBVA mode.
741	*
742	* @param pInterface Pointer to this interface.
743	* @param uScreenId The screen updates are for.
744	* @thread The emulation thread.
745	*/
746	DECLR3CALLBACKMEMBER(void, pfnVBVADisable,(PPDMIDISPLAYCONNECTOR pInterface, unsigned uScreenId));
747
748	/**
749	* A sequence of pfnVBVAUpdateProcess calls begins.
750	*
751	* @param pInterface Pointer to this interface.
752	* @param uScreenId The screen updates are for.
753	* @thread The emulation thread.
754	*/
755	DECLR3CALLBACKMEMBER(void, pfnVBVAUpdateBegin,(PPDMIDISPLAYCONNECTOR pInterface, unsigned uScreenId));
756
757	/**
758	* Process the guest VBVA command.
759	*
760	* @param pInterface Pointer to this interface.
761	* @param pCmd Video HW Acceleration Command to be processed.
762	* @thread The emulation thread.
763	*/
764	DECLR3CALLBACKMEMBER(void, pfnVBVAUpdateProcess,(PPDMIDISPLAYCONNECTOR pInterface, unsigned uScreenId, const PVBVACMDHDR pCmd, size_t cbCmd));
765
766	/**
767	* A sequence of pfnVBVAUpdateProcess calls ends.
768	*
769	* @param pInterface Pointer to this interface.
770	* @param uScreenId The screen updates are for.
771	* @param x The upper left corner x coordinate of the combined rectangle of all VBVA updates.
772	* @param y The upper left corner y coordinate of the rectangle.
773	* @param cx The width of the rectangle.
774	* @param cy The height of the rectangle.
775	* @thread The emulation thread.
776	*/
777	DECLR3CALLBACKMEMBER(void, pfnVBVAUpdateEnd,(PPDMIDISPLAYCONNECTOR pInterface, unsigned uScreenId, int32_t x, int32_t y, uint32_t cx, uint32_t cy));
778
779	/**
780	* Resize the display.
781	* This is called when the resolution changes. This usually happens on
782	* request from the guest os, but may also happen as the result of a reset.
783	* If the callback returns VINF_VGA_RESIZE_IN_PROGRESS, the caller (VGA device)
784	* must not access the connector and return.
785	*
786	* @todo Merge with pfnResize.
787	*
788	* @returns VINF_SUCCESS if the framebuffer resize was completed,
789	* VINF_VGA_RESIZE_IN_PROGRESS if resize takes time and not yet finished.
790	* @param pInterface Pointer to this interface.
791	* @param pView The description of VRAM block for this screen.
792	* @param pScreen The data of screen being resized.
793	* @param pvVRAM Address of the guest VRAM.
794	* @thread The emulation thread.
795	*/
796	DECLR3CALLBACKMEMBER(int, pfnVBVAResize,(PPDMIDISPLAYCONNECTOR pInterface, const PVBVAINFOVIEW pView, const PVBVAINFOSCREEN pScreen, void *pvVRAM));
797
798	/**
799	* Update the pointer shape.
800	* This is called when the mouse pointer shape changes. The new shape
801	* is passed as a caller allocated buffer that will be freed after returning
802	*
803	* @param pInterface Pointer to this interface.
804	* @param fVisible Visibility indicator (if false, the other parameters are undefined).
805	* @param fAlpha Flag whether alpha channel is being passed.
806	* @param xHot Pointer hot spot x coordinate.
807	* @param yHot Pointer hot spot y coordinate.
808	* @param x Pointer new x coordinate on screen.
809	* @param y Pointer new y coordinate on screen.
810	* @param cx Pointer width in pixels.
811	* @param cy Pointer height in pixels.
812	* @param cbScanline Size of one scanline in bytes.
813	* @param pvShape New shape buffer.
814	* @thread The emulation thread.
815	*/
816	DECLR3CALLBACKMEMBER(int, pfnVBVAMousePointerShape,(PPDMIDISPLAYCONNECTOR pInterface, bool fVisible, bool fAlpha,
817	uint32_t xHot, uint32_t yHot,
818	uint32_t cx, uint32_t cy,
819	const void *pvShape));
820
821	/** Read-only attributes.
822	* For preformance reasons some readonly attributes are kept in the interface.
823	* We trust the interface users to respect the readonlyness of these.
824	* @{
825	*/
826	/** Pointer to the display data buffer. */
827	uint8_t *pu8Data;
828	/** Size of a scanline in the data buffer. */
829	uint32_t cbScanline;
830	/** The color depth (in bits) the graphics card is supposed to provide. */
831	uint32_t cBits;
832	/** The display width. */
833	uint32_t cx;
834	/** The display height. */
835	uint32_t cy;
836	/** @} */
837	} PDMIDISPLAYCONNECTOR;
838	/** PDMIDISPLAYCONNECTOR interface ID. */
839	#define PDMIDISPLAYCONNECTOR_IID "c7a1b36d-8dfc-421d-b71f-3a0eeaf733e6"
840
841
842	/** Pointer to a block port interface. */
843	typedef struct PDMIBLOCKPORT *PPDMIBLOCKPORT;
844	/**
845	* Block notify interface (down).
846	* Pair with PDMIBLOCK.
847	*/
848	typedef struct PDMIBLOCKPORT
849	{
850	/**
851	* Returns the storage controller name, instance and LUN of the attached medium.
852	*
853	* @returns VBox status.
854	* @param pInterface Pointer to this interface.
855	* @param ppcszController Where to store the name of the storage controller.
856	* @param piInstance Where to store the instance number of the controller.
857	* @param piLUN Where to store the LUN of the attached device.
858	*/
859	DECLR3CALLBACKMEMBER(int, pfnQueryDeviceLocation, (PPDMIBLOCKPORT pInterface, const char **ppcszController,
860	uint32_t piInstance, uint32_t piLUN));
861
862	} PDMIBLOCKPORT;
863	/** PDMIBLOCKPORT interface ID. */
864	#define PDMIBLOCKPORT_IID "bbbed4cf-0862-4ffd-b60c-f7a65ef8e8ff"
865
866
867	/**
868	* Callback which provides progress information.
869	*
870	* @return VBox status code.
871	* @param pvUser Opaque user data.
872	* @param uPercent Completion percentage.
873	*/
874	typedef DECLCALLBACK(int) FNSIMPLEPROGRESS(void *pvUser, unsigned uPercentage);
875	/** Pointer to FNSIMPLEPROGRESS() */
876	typedef FNSIMPLEPROGRESS *PFNSIMPLEPROGRESS;
877
878
879	/**
880	* Block drive type.
881	*/
882	typedef enum PDMBLOCKTYPE
883	{
884	/** Error (for the query function). */
885	PDMBLOCKTYPE_ERROR = 1,
886	/** 360KB 5 1/4" floppy drive. */
887	PDMBLOCKTYPE_FLOPPY_360,
888	/** 720KB 3 1/2" floppy drive. */
889	PDMBLOCKTYPE_FLOPPY_720,
890	/** 1.2MB 5 1/4" floppy drive. */
891	PDMBLOCKTYPE_FLOPPY_1_20,
892	/** 1.44MB 3 1/2" floppy drive. */
893	PDMBLOCKTYPE_FLOPPY_1_44,
894	/** 2.88MB 3 1/2" floppy drive. */
895	PDMBLOCKTYPE_FLOPPY_2_88,
896	/** Fake drive that can take up to 15.6 MB images.
897	* C=255, H=2, S=63. */
898	PDMBLOCKTYPE_FLOPPY_FAKE_15_6,
899	/** Fake drive that can take up to 63.5 MB images.
900	* C=255, H=2, S=255. */
901	PDMBLOCKTYPE_FLOPPY_FAKE_63_5,
902	/** CDROM drive. */
903	PDMBLOCKTYPE_CDROM,
904	/** DVD drive. */
905	PDMBLOCKTYPE_DVD,
906	/** Hard disk drive. */
907	PDMBLOCKTYPE_HARD_DISK
908	} PDMBLOCKTYPE;
909
910	/** Check if the given block type is a floppy. */
911	#define PDMBLOCKTYPE_IS_FLOPPY(a_enmType) ( (a_enmType) >= PDMBLOCKTYPE_FLOPPY_360 && (a_enmType) <= PDMBLOCKTYPE_FLOPPY_2_88 )
912
913	/**
914	* Block raw command data transfer direction.
915	*/
916	typedef enum PDMBLOCKTXDIR
917	{
918	PDMBLOCKTXDIR_NONE = 0,
919	PDMBLOCKTXDIR_FROM_DEVICE,
920	PDMBLOCKTXDIR_TO_DEVICE
921	} PDMBLOCKTXDIR;
922
923
924	/** Pointer to a block interface. */
925	typedef struct PDMIBLOCK *PPDMIBLOCK;
926	/**
927	* Block interface (up).
928	* Pair with PDMIBLOCKPORT.
929	*/
930	typedef struct PDMIBLOCK
931	{
932	/**
933	* Read bits.
934	*
935	* @returns VBox status code.
936	* @param pInterface Pointer to the interface structure containing the called function pointer.
937	* @param off Offset to start reading from. The offset must be aligned to a sector boundary.
938	* @param pvBuf Where to store the read bits.
939	* @param cbRead Number of bytes to read. Must be aligned to a sector boundary.
940	* @thread Any thread.
941	*/
942	DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMIBLOCK pInterface, uint64_t off, void *pvBuf, size_t cbRead));
943
944	/**
945	* Write bits.
946	*
947	* @returns VBox status code.
948	* @param pInterface Pointer to the interface structure containing the called function pointer.
949	* @param off Offset to start writing at. The offset must be aligned to a sector boundary.
950	* @param pvBuf Where to store the write bits.
951	* @param cbWrite Number of bytes to write. Must be aligned to a sector boundary.
952	* @thread Any thread.
953	*/
954	DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMIBLOCK pInterface, uint64_t off, const void *pvBuf, size_t cbWrite));
955
956	/**
957	* Make sure that the bits written are actually on the storage medium.
958	*
959	* @returns VBox status code.
960	* @param pInterface Pointer to the interface structure containing the called function pointer.
961	* @thread Any thread.
962	*/
963	DECLR3CALLBACKMEMBER(int, pfnFlush,(PPDMIBLOCK pInterface));
964
965	/**
966	* Send a raw command to the underlying device (CDROM).
967	* This method is optional (i.e. the function pointer may be NULL).
968	*
969	* @returns VBox status code.
970	* @param pInterface Pointer to the interface structure containing the called function pointer.
971	* @param pbCmd Offset to start reading from.
972	* @param enmTxDir Direction of transfer.
973	* @param pvBuf Pointer tp the transfer buffer.
974	* @param cbBuf Size of the transfer buffer.
975	* @param pbSenseKey Status of the command (when return value is VERR_DEV_IO_ERROR).
976	* @param cTimeoutMillies Command timeout in milliseconds.
977	* @thread Any thread.
978	*/
979	DECLR3CALLBACKMEMBER(int, pfnSendCmd,(PPDMIBLOCK pInterface, const uint8_t pbCmd, PDMBLOCKTXDIR enmTxDir, void pvBuf, uint32_t pcbBuf, uint8_t pabSense, size_t cbSense, uint32_t cTimeoutMillies));
980
981	/**
982	* Merge medium contents during a live snapshot deletion.
983	*
984	* @returns VBox status code.
985	* @param pInterface Pointer to the interface structure containing the called function pointer.
986	* @param pfnProgress Function pointer for progress notification.
987	* @param pvUser Opaque user data for progress notification.
988	* @thread Any thread.
989	*/
990	DECLR3CALLBACKMEMBER(int, pfnMerge,(PPDMIBLOCK pInterface, PFNSIMPLEPROGRESS pfnProgress, void *pvUser));
991
992	/**
993	* Check if the media is readonly or not.
994	*
995	* @returns true if readonly.
996	* @returns false if read/write.
997	* @param pInterface Pointer to the interface structure containing the called function pointer.
998	* @thread Any thread.
999	*/
1000	DECLR3CALLBACKMEMBER(bool, pfnIsReadOnly,(PPDMIBLOCK pInterface));
1001
1002	/**
1003	* Gets the media size in bytes.
1004	*
1005	* @returns Media size in bytes.
1006	* @param pInterface Pointer to the interface structure containing the called function pointer.
1007	* @thread Any thread.
1008	*/
1009	DECLR3CALLBACKMEMBER(uint64_t, pfnGetSize,(PPDMIBLOCK pInterface));
1010
1011	/**
1012	* Gets the block drive type.
1013	*
1014	* @returns block drive type.
1015	* @param pInterface Pointer to the interface structure containing the called function pointer.
1016	* @thread Any thread.
1017	*/
1018	DECLR3CALLBACKMEMBER(PDMBLOCKTYPE, pfnGetType,(PPDMIBLOCK pInterface));
1019
1020	/**
1021	* Gets the UUID of the block drive.
1022	* Don't return the media UUID if it's removable.
1023	*
1024	* @returns VBox status code.
1025	* @param pInterface Pointer to the interface structure containing the called function pointer.
1026	* @param pUuid Where to store the UUID on success.
1027	* @thread Any thread.
1028	*/
1029	DECLR3CALLBACKMEMBER(int, pfnGetUuid,(PPDMIBLOCK pInterface, PRTUUID pUuid));
1030
1031	/**
1032	* Discards the given range.
1033	*
1034	* @returns VBox status code.
1035	* @param pInterface Pointer to the interface structure containing the called function pointer.
1036	* @param paRanges Array of ranges to discard.
1037	* @param cRanges Number of entries in the array.
1038	* @thread Any thread.
1039	*/
1040	DECLR3CALLBACKMEMBER(int, pfnDiscard,(PPDMIBLOCK pInterface, PCRTRANGE paRanges, unsigned cRanges));
1041	} PDMIBLOCK;
1042	/** PDMIBLOCK interface ID. */
1043	#define PDMIBLOCK_IID "5e7123dd-8cdf-4a6e-97a5-ab0c68d7e850"
1044
1045
1046	/** Pointer to a mount interface. */
1047	typedef struct PDMIMOUNTNOTIFY *PPDMIMOUNTNOTIFY;
1048	/**
1049	* Block interface (up).
1050	* Pair with PDMIMOUNT.
1051	*/
1052	typedef struct PDMIMOUNTNOTIFY
1053	{
1054	/**
1055	* Called when a media is mounted.
1056	*
1057	* @param pInterface Pointer to the interface structure containing the called function pointer.
1058	* @thread The emulation thread.
1059	*/
1060	DECLR3CALLBACKMEMBER(void, pfnMountNotify,(PPDMIMOUNTNOTIFY pInterface));
1061
1062	/**
1063	* Called when a media is unmounted
1064	* @param pInterface Pointer to the interface structure containing the called function pointer.
1065	* @thread The emulation thread.
1066	*/
1067	DECLR3CALLBACKMEMBER(void, pfnUnmountNotify,(PPDMIMOUNTNOTIFY pInterface));
1068	} PDMIMOUNTNOTIFY;
1069	/** PDMIMOUNTNOTIFY interface ID. */
1070	#define PDMIMOUNTNOTIFY_IID "fa143ac9-9fc6-498e-997f-945380a558f9"
1071
1072
1073	/** Pointer to mount interface. */
1074	typedef struct PDMIMOUNT *PPDMIMOUNT;
1075	/**
1076	* Mount interface (down).
1077	* Pair with PDMIMOUNTNOTIFY.
1078	*/
1079	typedef struct PDMIMOUNT
1080	{
1081	/**
1082	* Mount a media.
1083	*
1084	* This will not unmount any currently mounted media!
1085	*
1086	* @returns VBox status code.
1087	* @param pInterface Pointer to the interface structure containing the called function pointer.
1088	* @param pszFilename Pointer to filename. If this is NULL it assumed that the caller have
1089	* constructed a configuration which can be attached to the bottom driver.
1090	* @param pszCoreDriver Core driver name. NULL will cause autodetection. Ignored if pszFilanem is NULL.
1091	* @thread The emulation thread.
1092	*/
1093	DECLR3CALLBACKMEMBER(int, pfnMount,(PPDMIMOUNT pInterface, const char pszFilename, const char pszCoreDriver));
1094
1095	/**
1096	* Unmount the media.
1097	*
1098	* The driver will validate and pass it on. On the rebounce it will decide whether or not to detach it self.
1099	*
1100	* @returns VBox status code.
1101	* @param pInterface Pointer to the interface structure containing the called function pointer.
1102	* @thread The emulation thread.
1103	* @param fForce Force the unmount, even for locked media.
1104	* @param fEject Eject the medium. Only relevant for host drives.
1105	* @thread The emulation thread.
1106	*/
1107	DECLR3CALLBACKMEMBER(int, pfnUnmount,(PPDMIMOUNT pInterface, bool fForce, bool fEject));
1108
1109	/**
1110	* Checks if a media is mounted.
1111	*
1112	* @returns true if mounted.
1113	* @returns false if not mounted.
1114	* @param pInterface Pointer to the interface structure containing the called function pointer.
1115	* @thread Any thread.
1116	*/
1117	DECLR3CALLBACKMEMBER(bool, pfnIsMounted,(PPDMIMOUNT pInterface));
1118
1119	/**
1120	* Locks the media, preventing any unmounting of it.
1121	*
1122	* @returns VBox status code.
1123	* @param pInterface Pointer to the interface structure containing the called function pointer.
1124	* @thread The emulation thread.
1125	*/
1126	DECLR3CALLBACKMEMBER(int, pfnLock,(PPDMIMOUNT pInterface));
1127
1128	/**
1129	* Unlocks the media, canceling previous calls to pfnLock().
1130	*
1131	* @returns VBox status code.
1132	* @param pInterface Pointer to the interface structure containing the called function pointer.
1133	* @thread The emulation thread.
1134	*/
1135	DECLR3CALLBACKMEMBER(int, pfnUnlock,(PPDMIMOUNT pInterface));
1136
1137	/**
1138	* Checks if a media is locked.
1139	*
1140	* @returns true if locked.
1141	* @returns false if not locked.
1142	* @param pInterface Pointer to the interface structure containing the called function pointer.
1143	* @thread Any thread.
1144	*/
1145	DECLR3CALLBACKMEMBER(bool, pfnIsLocked,(PPDMIMOUNT pInterface));
1146	} PDMIMOUNT;
1147	/** PDMIMOUNT interface ID. */
1148	#define PDMIMOUNT_IID "34fc7a4c-623a-4806-a6bf-5be1be33c99f"
1149
1150
1151	/**
1152	* Media geometry structure.
1153	*/
1154	typedef struct PDMMEDIAGEOMETRY
1155	{
1156	/** Number of cylinders. */
1157	uint32_t cCylinders;
1158	/** Number of heads. */
1159	uint32_t cHeads;
1160	/** Number of sectors. */
1161	uint32_t cSectors;
1162	} PDMMEDIAGEOMETRY;
1163
1164	/** Pointer to media geometry structure. */
1165	typedef PDMMEDIAGEOMETRY *PPDMMEDIAGEOMETRY;
1166	/** Pointer to constant media geometry structure. */
1167	typedef const PDMMEDIAGEOMETRY *PCPDMMEDIAGEOMETRY;
1168
1169	/** Pointer to a media port interface. */
1170	typedef struct PDMIMEDIAPORT *PPDMIMEDIAPORT;
1171	/**
1172	* Media port interface (down).
1173	*/
1174	typedef struct PDMIMEDIAPORT
1175	{
1176	/**
1177	* Returns the storage controller name, instance and LUN of the attached medium.
1178	*
1179	* @returns VBox status.
1180	* @param pInterface Pointer to this interface.
1181	* @param ppcszController Where to store the name of the storage controller.
1182	* @param piInstance Where to store the instance number of the controller.
1183	* @param piLUN Where to store the LUN of the attached device.
1184	*/
1185	DECLR3CALLBACKMEMBER(int, pfnQueryDeviceLocation, (PPDMIMEDIAPORT pInterface, const char **ppcszController,
1186	uint32_t piInstance, uint32_t piLUN));
1187
1188	} PDMIMEDIAPORT;
1189	/** PDMIMEDIAPORT interface ID. */
1190	#define PDMIMEDIAPORT_IID "9f7e8c9e-6d35-4453-bbef-1f78033174d6"
1191
1192	/** Pointer to a media interface. */
1193	typedef struct PDMIMEDIA *PPDMIMEDIA;
1194	/**
1195	* Media interface (up).
1196	* Makes up the foundation for PDMIBLOCK and PDMIBLOCKBIOS.
1197	* Pairs with PDMIMEDIAPORT.
1198	*/
1199	typedef struct PDMIMEDIA
1200	{
1201	/**
1202	* Read bits.
1203	*
1204	* @returns VBox status code.
1205	* @param pInterface Pointer to the interface structure containing the called function pointer.
1206	* @param off Offset to start reading from. The offset must be aligned to a sector boundary.
1207	* @param pvBuf Where to store the read bits.
1208	* @param cbRead Number of bytes to read. Must be aligned to a sector boundary.
1209	* @thread Any thread.
1210	*/
1211	DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMIMEDIA pInterface, uint64_t off, void *pvBuf, size_t cbRead));
1212
1213	/**
1214	* Write bits.
1215	*
1216	* @returns VBox status code.
1217	* @param pInterface Pointer to the interface structure containing the called function pointer.
1218	* @param off Offset to start writing at. The offset must be aligned to a sector boundary.
1219	* @param pvBuf Where to store the write bits.
1220	* @param cbWrite Number of bytes to write. Must be aligned to a sector boundary.
1221	* @thread Any thread.
1222	*/
1223	DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMIMEDIA pInterface, uint64_t off, const void *pvBuf, size_t cbWrite));
1224
1225	/**
1226	* Make sure that the bits written are actually on the storage medium.
1227	*
1228	* @returns VBox status code.
1229	* @param pInterface Pointer to the interface structure containing the called function pointer.
1230	* @thread Any thread.
1231	*/
1232	DECLR3CALLBACKMEMBER(int, pfnFlush,(PPDMIMEDIA pInterface));
1233
1234	/**
1235	* Merge medium contents during a live snapshot deletion. All details
1236	* must have been configured through CFGM or this will fail.
1237	* This method is optional (i.e. the function pointer may be NULL).
1238	*
1239	* @returns VBox status code.
1240	* @param pInterface Pointer to the interface structure containing the called function pointer.
1241	* @param pfnProgress Function pointer for progress notification.
1242	* @param pvUser Opaque user data for progress notification.
1243	* @thread Any thread.
1244	*/
1245	DECLR3CALLBACKMEMBER(int, pfnMerge,(PPDMIMEDIA pInterface, PFNSIMPLEPROGRESS pfnProgress, void *pvUser));
1246
1247	/**
1248	* Get the media size in bytes.
1249	*
1250	* @returns Media size in bytes.
1251	* @param pInterface Pointer to the interface structure containing the called function pointer.
1252	* @thread Any thread.
1253	*/
1254	DECLR3CALLBACKMEMBER(uint64_t, pfnGetSize,(PPDMIMEDIA pInterface));
1255
1256	/**
1257	* Check if the media is readonly or not.
1258	*
1259	* @returns true if readonly.
1260	* @returns false if read/write.
1261	* @param pInterface Pointer to the interface structure containing the called function pointer.
1262	* @thread Any thread.
1263	*/
1264	DECLR3CALLBACKMEMBER(bool, pfnIsReadOnly,(PPDMIMEDIA pInterface));
1265
1266	/**
1267	* Get stored media geometry (physical CHS, PCHS) - BIOS property.
1268	* This is an optional feature of a media.
1269	*
1270	* @returns VBox status code.
1271	* @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
1272	* @returns VERR_PDM_GEOMETRY_NOT_SET if the geometry hasn't been set using pfnBiosSetPCHSGeometry() yet.
1273	* @param pInterface Pointer to the interface structure containing the called function pointer.
1274	* @param pPCHSGeometry Pointer to PCHS geometry (cylinders/heads/sectors).
1275	* @remark This has no influence on the read/write operations.
1276	* @thread Any thread.
1277	*/
1278	DECLR3CALLBACKMEMBER(int, pfnBiosGetPCHSGeometry,(PPDMIMEDIA pInterface, PPDMMEDIAGEOMETRY pPCHSGeometry));
1279
1280	/**
1281	* Store the media geometry (physical CHS, PCHS) - BIOS property.
1282	* This is an optional feature of a media.
1283	*
1284	* @returns VBox status code.
1285	* @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
1286	* @param pInterface Pointer to the interface structure containing the called function pointer.
1287	* @param pPCHSGeometry Pointer to PCHS geometry (cylinders/heads/sectors).
1288	* @remark This has no influence on the read/write operations.
1289	* @thread The emulation thread.
1290	*/
1291	DECLR3CALLBACKMEMBER(int, pfnBiosSetPCHSGeometry,(PPDMIMEDIA pInterface, PCPDMMEDIAGEOMETRY pPCHSGeometry));
1292
1293	/**
1294	* Get stored media geometry (logical CHS, LCHS) - BIOS property.
1295	* This is an optional feature of a media.
1296	*
1297	* @returns VBox status code.
1298	* @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
1299	* @returns VERR_PDM_GEOMETRY_NOT_SET if the geometry hasn't been set using pfnBiosSetLCHSGeometry() yet.
1300	* @param pInterface Pointer to the interface structure containing the called function pointer.
1301	* @param pLCHSGeometry Pointer to LCHS geometry (cylinders/heads/sectors).
1302	* @remark This has no influence on the read/write operations.
1303	* @thread Any thread.
1304	*/
1305	DECLR3CALLBACKMEMBER(int, pfnBiosGetLCHSGeometry,(PPDMIMEDIA pInterface, PPDMMEDIAGEOMETRY pLCHSGeometry));
1306
1307	/**
1308	* Store the media geometry (logical CHS, LCHS) - BIOS property.
1309	* This is an optional feature of a media.
1310	*
1311	* @returns VBox status code.
1312	* @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
1313	* @param pInterface Pointer to the interface structure containing the called function pointer.
1314	* @param pLCHSGeometry Pointer to LCHS geometry (cylinders/heads/sectors).
1315	* @remark This has no influence on the read/write operations.
1316	* @thread The emulation thread.
1317	*/
1318	DECLR3CALLBACKMEMBER(int, pfnBiosSetLCHSGeometry,(PPDMIMEDIA pInterface, PCPDMMEDIAGEOMETRY pLCHSGeometry));
1319
1320	/**
1321	* Gets the UUID of the media drive.
1322	*
1323	* @returns VBox status code.
1324	* @param pInterface Pointer to the interface structure containing the called function pointer.
1325	* @param pUuid Where to store the UUID on success.
1326	* @thread Any thread.
1327	*/
1328	DECLR3CALLBACKMEMBER(int, pfnGetUuid,(PPDMIMEDIA pInterface, PRTUUID pUuid));
1329
1330	/**
1331	* Discards the given range.
1332	*
1333	* @returns VBox status code.
1334	* @param pInterface Pointer to the interface structure containing the called function pointer.
1335	* @param paRanges Array of ranges to discard.
1336	* @param cRanges Number of entries in the array.
1337	* @thread Any thread.
1338	*/
1339	DECLR3CALLBACKMEMBER(int, pfnDiscard,(PPDMIMEDIA pInterface, PCRTRANGE paRanges, unsigned cRanges));
1340
1341	} PDMIMEDIA;
1342	/** PDMIMEDIA interface ID. */
1343	#define PDMIMEDIA_IID "ec385d21-7aa9-42ca-8cfb-e1388297fa52"
1344
1345
1346	/** Pointer to a block BIOS interface. */
1347	typedef struct PDMIBLOCKBIOS *PPDMIBLOCKBIOS;
1348	/**
1349	* Media BIOS interface (Up / External).
1350	* The interface the getting and setting properties which the BIOS/CMOS care about.
1351	*/
1352	typedef struct PDMIBLOCKBIOS
1353	{
1354	/**
1355	* Get stored media geometry (physical CHS, PCHS) - BIOS property.
1356	* This is an optional feature of a media.
1357	*
1358	* @returns VBox status code.
1359	* @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
1360	* @returns VERR_PDM_GEOMETRY_NOT_SET if the geometry hasn't been set using pfnSetPCHSGeometry() yet.
1361	* @param pInterface Pointer to the interface structure containing the called function pointer.
1362	* @param pPCHSGeometry Pointer to PCHS geometry (cylinders/heads/sectors).
1363	* @remark This has no influence on the read/write operations.
1364	* @thread Any thread.
1365	*/
1366	DECLR3CALLBACKMEMBER(int, pfnGetPCHSGeometry,(PPDMIBLOCKBIOS pInterface, PPDMMEDIAGEOMETRY pPCHSGeometry));
1367
1368	/**
1369	* Store the media geometry (physical CHS, PCHS) - BIOS property.
1370	* This is an optional feature of a media.
1371	*
1372	* @returns VBox status code.
1373	* @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
1374	* @param pInterface Pointer to the interface structure containing the called function pointer.
1375	* @param pPCHSGeometry Pointer to PCHS geometry (cylinders/heads/sectors).
1376	* @remark This has no influence on the read/write operations.
1377	* @thread The emulation thread.
1378	*/
1379	DECLR3CALLBACKMEMBER(int, pfnSetPCHSGeometry,(PPDMIBLOCKBIOS pInterface, PCPDMMEDIAGEOMETRY pPCHSGeometry));
1380
1381	/**
1382	* Get stored media geometry (logical CHS, LCHS) - BIOS property.
1383	* This is an optional feature of a media.
1384	*
1385	* @returns VBox status code.
1386	* @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
1387	* @returns VERR_PDM_GEOMETRY_NOT_SET if the geometry hasn't been set using pfnSetLCHSGeometry() yet.
1388	* @param pInterface Pointer to the interface structure containing the called function pointer.
1389	* @param pLCHSGeometry Pointer to LCHS geometry (cylinders/heads/sectors).
1390	* @remark This has no influence on the read/write operations.
1391	* @thread Any thread.
1392	*/
1393	DECLR3CALLBACKMEMBER(int, pfnGetLCHSGeometry,(PPDMIBLOCKBIOS pInterface, PPDMMEDIAGEOMETRY pLCHSGeometry));
1394
1395	/**
1396	* Store the media geometry (logical CHS, LCHS) - BIOS property.
1397	* This is an optional feature of a media.
1398	*
1399	* @returns VBox status code.
1400	* @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
1401	* @param pInterface Pointer to the interface structure containing the called function pointer.
1402	* @param pLCHSGeometry Pointer to LCHS geometry (cylinders/heads/sectors).
1403	* @remark This has no influence on the read/write operations.
1404	* @thread The emulation thread.
1405	*/
1406	DECLR3CALLBACKMEMBER(int, pfnSetLCHSGeometry,(PPDMIBLOCKBIOS pInterface, PCPDMMEDIAGEOMETRY pLCHSGeometry));
1407
1408	/**
1409	* Checks if the device should be visible to the BIOS or not.
1410	*
1411	* @returns true if the device is visible to the BIOS.
1412	* @returns false if the device is not visible to the BIOS.
1413	* @param pInterface Pointer to the interface structure containing the called function pointer.
1414	* @thread Any thread.
1415	*/
1416	DECLR3CALLBACKMEMBER(bool, pfnIsVisible,(PPDMIBLOCKBIOS pInterface));
1417
1418	/**
1419	* Gets the block drive type.
1420	*
1421	* @returns block drive type.
1422	* @param pInterface Pointer to the interface structure containing the called function pointer.
1423	* @thread Any thread.
1424	*/
1425	DECLR3CALLBACKMEMBER(PDMBLOCKTYPE, pfnGetType,(PPDMIBLOCKBIOS pInterface));
1426
1427	} PDMIBLOCKBIOS;
1428	/** PDMIBLOCKBIOS interface ID. */
1429	#define PDMIBLOCKBIOS_IID "477c3eee-a48d-48a9-82fd-2a54de16b2e9"
1430
1431
1432	/** Pointer to a static block core driver interface. */
1433	typedef struct PDMIMEDIASTATIC *PPDMIMEDIASTATIC;
1434	/**
1435	* Static block core driver interface.
1436	*/
1437	typedef struct PDMIMEDIASTATIC
1438	{
1439	/**
1440	* Check if the specified file is a format which the core driver can handle.
1441	*
1442	* @returns true / false accordingly.
1443	* @param pInterface Pointer to the interface structure containing the called function pointer.
1444	* @param pszFilename Name of the file to probe.
1445	*/
1446	DECLR3CALLBACKMEMBER(bool, pfnCanHandle,(PPDMIMEDIASTATIC pInterface, const char *pszFilename));
1447	} PDMIMEDIASTATIC;
1448
1449
1450
1451
1452
1453	/** Pointer to an asynchronous block notify interface. */
1454	typedef struct PDMIBLOCKASYNCPORT *PPDMIBLOCKASYNCPORT;
1455	/**
1456	* Asynchronous block notify interface (up).
1457	* Pair with PDMIBLOCKASYNC.
1458	*/
1459	typedef struct PDMIBLOCKASYNCPORT
1460	{
1461	/**
1462	* Notify completion of an asynchronous transfer.
1463	*
1464	* @returns VBox status code.
1465	* @param pInterface Pointer to the interface structure containing the called function pointer.
1466	* @param pvUser The user argument given in pfnStartWrite/Read.
1467	* @param rcReq IPRT Status code of the completed request.
1468	* @thread Any thread.
1469	*/
1470	DECLR3CALLBACKMEMBER(int, pfnTransferCompleteNotify, (PPDMIBLOCKASYNCPORT pInterface, void *pvUser, int rcReq));
1471	} PDMIBLOCKASYNCPORT;
1472	/** PDMIBLOCKASYNCPORT interface ID. */
1473	#define PDMIBLOCKASYNCPORT_IID "e3bdc0cb-9d99-41dd-8eec-0dc8cf5b2a92"
1474
1475
1476
1477	/** Pointer to an asynchronous block interface. */
1478	typedef struct PDMIBLOCKASYNC *PPDMIBLOCKASYNC;
1479	/**
1480	* Asynchronous block interface (down).
1481	* Pair with PDMIBLOCKASYNCPORT.
1482	*/
1483	typedef struct PDMIBLOCKASYNC
1484	{
1485	/**
1486	* Start reading task.
1487	*
1488	* @returns VBox status code.
1489	* @param pInterface Pointer to the interface structure containing the called function pointer.
1490	* @param off Offset to start reading from.c
1491	* @param paSegs Pointer to the S/G segment array.
1492	* @param cSegs Number of entries in the array.
1493	* @param cbRead Number of bytes to read. Must be aligned to a sector boundary.
1494	* @param pvUser User argument which is returned in completion callback.
1495	* @thread Any thread.
1496	*/
1497	DECLR3CALLBACKMEMBER(int, pfnStartRead,(PPDMIBLOCKASYNC pInterface, uint64_t off, PCRTSGSEG paSegs, unsigned cSegs, size_t cbRead, void *pvUser));
1498
1499	/**
1500	* Write bits.
1501	*
1502	* @returns VBox status code.
1503	* @param pInterface Pointer to the interface structure containing the called function pointer.
1504	* @param off Offset to start writing at. The offset must be aligned to a sector boundary.
1505	* @param paSegs Pointer to the S/G segment array.
1506	* @param cSegs Number of entries in the array.
1507	* @param cbWrite Number of bytes to write. Must be aligned to a sector boundary.
1508	* @param pvUser User argument which is returned in completion callback.
1509	* @thread Any thread.
1510	*/
1511	DECLR3CALLBACKMEMBER(int, pfnStartWrite,(PPDMIBLOCKASYNC pInterface, uint64_t off, PCRTSGSEG paSegs, unsigned cSegs, size_t cbWrite, void *pvUser));
1512
1513	/**
1514	* Flush everything to disk.
1515	*
1516	* @returns VBox status code.
1517	* @param pInterface Pointer to the interface structure containing the called function pointer.
1518	* @param pvUser User argument which is returned in completion callback.
1519	* @thread Any thread.
1520	*/
1521	DECLR3CALLBACKMEMBER(int, pfnStartFlush,(PPDMIBLOCKASYNC pInterface, void *pvUser));
1522
1523	/**
1524	* Discards the given range.
1525	*
1526	* @returns VBox status code.
1527	* @param pInterface Pointer to the interface structure containing the called function pointer.
1528	* @param paRanges Array of ranges to discard.
1529	* @param cRanges Number of entries in the array.
1530	* @param pvUser User argument which is returned in completion callback.
1531	* @thread Any thread.
1532	*/
1533	DECLR3CALLBACKMEMBER(int, pfnStartDiscard,(PPDMIBLOCKASYNC pInterface, PCRTRANGE paRanges, unsigned cRanges, void *pvUser));
1534
1535	} PDMIBLOCKASYNC;
1536	/** PDMIBLOCKASYNC interface ID. */
1537	#define PDMIBLOCKASYNC_IID "a921dd96-1748-4ecd-941e-d5f3cd4c8fe4"
1538
1539
1540	/** Pointer to an asynchronous notification interface. */
1541	typedef struct PDMIMEDIAASYNCPORT *PPDMIMEDIAASYNCPORT;
1542	/**
1543	* Asynchronous version of the media interface (up).
1544	* Pair with PDMIMEDIAASYNC.
1545	*/
1546	typedef struct PDMIMEDIAASYNCPORT
1547	{
1548	/**
1549	* Notify completion of a task.
1550	*
1551	* @returns VBox status code.
1552	* @param pInterface Pointer to the interface structure containing the called function pointer.
1553	* @param pvUser The user argument given in pfnStartWrite.
1554	* @param rcReq IPRT Status code of the completed request.
1555	* @thread Any thread.
1556	*/
1557	DECLR3CALLBACKMEMBER(int, pfnTransferCompleteNotify, (PPDMIMEDIAASYNCPORT pInterface, void *pvUser, int rcReq));
1558	} PDMIMEDIAASYNCPORT;
1559	/** PDMIMEDIAASYNCPORT interface ID. */
1560	#define PDMIMEDIAASYNCPORT_IID "22d38853-901f-4a71-9670-4d9da6e82317"
1561
1562
1563	/** Pointer to an asynchronous media interface. */
1564	typedef struct PDMIMEDIAASYNC *PPDMIMEDIAASYNC;
1565	/**
1566	* Asynchronous version of PDMIMEDIA (down).
1567	* Pair with PDMIMEDIAASYNCPORT.
1568	*/
1569	typedef struct PDMIMEDIAASYNC
1570	{
1571	/**
1572	* Start reading task.
1573	*
1574	* @returns VBox status code.
1575	* @param pInterface Pointer to the interface structure containing the called function pointer.
1576	* @param off Offset to start reading from. Must be aligned to a sector boundary.
1577	* @param paSegs Pointer to the S/G segment array.
1578	* @param cSegs Number of entries in the array.
1579	* @param cbRead Number of bytes to read. Must be aligned to a sector boundary.
1580	* @param pvUser User data.
1581	* @thread Any thread.
1582	*/
1583	DECLR3CALLBACKMEMBER(int, pfnStartRead,(PPDMIMEDIAASYNC pInterface, uint64_t off, PCRTSGSEG paSegs, unsigned cSegs, size_t cbRead, void *pvUser));
1584
1585	/**
1586	* Start writing task.
1587	*
1588	* @returns VBox status code.
1589	* @param pInterface Pointer to the interface structure containing the called function pointer.
1590	* @param off Offset to start writing at. Must be aligned to a sector boundary.
1591	* @param paSegs Pointer to the S/G segment array.
1592	* @param cSegs Number of entries in the array.
1593	* @param cbWrite Number of bytes to write. Must be aligned to a sector boundary.
1594	* @param pvUser User data.
1595	* @thread Any thread.
1596	*/
1597	DECLR3CALLBACKMEMBER(int, pfnStartWrite,(PPDMIMEDIAASYNC pInterface, uint64_t off, PCRTSGSEG paSegs, unsigned cSegs, size_t cbWrite, void *pvUser));
1598
1599	/**
1600	* Flush everything to disk.
1601	*
1602	* @returns VBox status code.
1603	* @param pInterface Pointer to the interface structure containing the called function pointer.
1604	* @param pvUser User argument which is returned in completion callback.
1605	* @thread Any thread.
1606	*/
1607	DECLR3CALLBACKMEMBER(int, pfnStartFlush,(PPDMIMEDIAASYNC pInterface, void *pvUser));
1608
1609	/**
1610	* Discards the given range.
1611	*
1612	* @returns VBox status code.
1613	* @param pInterface Pointer to the interface structure containing the called function pointer.
1614	* @param paRanges Array of ranges to discard.
1615	* @param cRanges Number of entries in the array.
1616	* @param pvUser User argument which is returned in completion callback.
1617	* @thread Any thread.
1618	*/
1619	DECLR3CALLBACKMEMBER(int, pfnStartDiscard,(PPDMIMEDIAASYNC pInterface, PCRTRANGE paRanges, unsigned cRanges, void *pvUser));
1620
1621	} PDMIMEDIAASYNC;
1622	/** PDMIMEDIAASYNC interface ID. */
1623	#define PDMIMEDIAASYNC_IID "4be209d3-ccb5-4297-82fe-7d8018bc6ab4"
1624
1625
1626	/** Pointer to a char port interface. */
1627	typedef struct PDMICHARPORT *PPDMICHARPORT;
1628	/**
1629	* Char port interface (down).
1630	* Pair with PDMICHARCONNECTOR.
1631	*/
1632	typedef struct PDMICHARPORT
1633	{
1634	/**
1635	* Deliver data read to the device/driver.
1636	*
1637	* @returns VBox status code.
1638	* @param pInterface Pointer to the interface structure containing the called function pointer.
1639	* @param pvBuf Where the read bits are stored.
1640	* @param pcbRead Number of bytes available for reading/having been read.
1641	* @thread Any thread.
1642	*/
1643	DECLR3CALLBACKMEMBER(int, pfnNotifyRead,(PPDMICHARPORT pInterface, const void pvBuf, size_t pcbRead));
1644
1645	/**
1646	* Notify the device/driver when the status lines changed.
1647	*
1648	* @returns VBox status code.
1649	* @param pInterface Pointer to the interface structure containing the called function pointer.
1650	* @param fNewStatusLine New state of the status line pins.
1651	* @thread Any thread.
1652	*/
1653	DECLR3CALLBACKMEMBER(int, pfnNotifyStatusLinesChanged,(PPDMICHARPORT pInterface, uint32_t fNewStatusLines));
1654
1655	/**
1656	* Notify the device when the driver buffer is full.
1657	*
1658	* @returns VBox status code.
1659	* @param pInterface Pointer to the interface structure containing the called function pointer.
1660	* @param fFull Buffer full.
1661	* @thread Any thread.
1662	*/
1663	DECLR3CALLBACKMEMBER(int, pfnNotifyBufferFull,(PPDMICHARPORT pInterface, bool fFull));
1664
1665	/**
1666	* Notify the device/driver that a break occurred.
1667	*
1668	* @returns VBox statsus code.
1669	* @param pInterface Pointer to the interface structure containing the called function pointer.
1670	* @thread Any thread.
1671	*/
1672	DECLR3CALLBACKMEMBER(int, pfnNotifyBreak,(PPDMICHARPORT pInterface));
1673	} PDMICHARPORT;
1674	/** PDMICHARPORT interface ID. */
1675	#define PDMICHARPORT_IID "22769834-ea8b-4a6d-ade1-213dcdbd1228"
1676
1677	/** @name Bit mask definitions for status line type.
1678	* @{ */
1679	#define PDMICHARPORT_STATUS_LINES_DCD RT_BIT(0)
1680	#define PDMICHARPORT_STATUS_LINES_RI RT_BIT(1)
1681	#define PDMICHARPORT_STATUS_LINES_DSR RT_BIT(2)
1682	#define PDMICHARPORT_STATUS_LINES_CTS RT_BIT(3)
1683	/** @} */
1684
1685
1686	/** Pointer to a char interface. */
1687	typedef struct PDMICHARCONNECTOR *PPDMICHARCONNECTOR;
1688	/**
1689	* Char connector interface (up).
1690	* Pair with PDMICHARPORT.
1691	*/
1692	typedef struct PDMICHARCONNECTOR
1693	{
1694	/**
1695	* Write bits.
1696	*
1697	* @returns VBox status code.
1698	* @param pInterface Pointer to the interface structure containing the called function pointer.
1699	* @param pvBuf Where to store the write bits.
1700	* @param cbWrite Number of bytes to write.
1701	* @thread Any thread.
1702	*/
1703	DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMICHARCONNECTOR pInterface, const void *pvBuf, size_t cbWrite));
1704
1705	/**
1706	* Set device parameters.
1707	*
1708	* @returns VBox status code.
1709	* @param pInterface Pointer to the interface structure containing the called function pointer.
1710	* @param Bps Speed of the serial connection. (bits per second)
1711	* @param chParity Parity method: 'E' - even, 'O' - odd, 'N' - none.
1712	* @param cDataBits Number of data bits.
1713	* @param cStopBits Number of stop bits.
1714	* @thread Any thread.
1715	*/
1716	DECLR3CALLBACKMEMBER(int, pfnSetParameters,(PPDMICHARCONNECTOR pInterface, unsigned Bps, char chParity, unsigned cDataBits, unsigned cStopBits));
1717
1718	/**
1719	* Set the state of the modem lines.
1720	*
1721	* @returns VBox status code.
1722	* @param pInterface Pointer to the interface structure containing the called function pointer.
1723	* @param fRequestToSend Set to true to make the Request to Send line active otherwise to 0.
1724	* @param fDataTerminalReady Set to true to make the Data Terminal Ready line active otherwise 0.
1725	* @thread Any thread.
1726	*/
1727	DECLR3CALLBACKMEMBER(int, pfnSetModemLines,(PPDMICHARCONNECTOR pInterface, bool fRequestToSend, bool fDataTerminalReady));
1728
1729	/**
1730	* Sets the TD line into break condition.
1731	*
1732	* @returns VBox status code.
1733	* @param pInterface Pointer to the interface structure containing the called function pointer.
1734	* @param fBreak Set to true to let the device send a break false to put into normal operation.
1735	* @thread Any thread.
1736	*/
1737	DECLR3CALLBACKMEMBER(int, pfnSetBreak,(PPDMICHARCONNECTOR pInterface, bool fBreak));
1738	} PDMICHARCONNECTOR;
1739	/** PDMICHARCONNECTOR interface ID. */
1740	#define PDMICHARCONNECTOR_IID "4ad5c190-b408-4cef-926f-fbffce0dc5cc"
1741
1742
1743	/** Pointer to a stream interface. */
1744	typedef struct PDMISTREAM *PPDMISTREAM;
1745	/**
1746	* Stream interface (up).
1747	* Makes up the foundation for PDMICHARCONNECTOR. No pair interface.
1748	*/
1749	typedef struct PDMISTREAM
1750	{
1751	/**
1752	* Read bits.
1753	*
1754	* @returns VBox status code.
1755	* @param pInterface Pointer to the interface structure containing the called function pointer.
1756	* @param pvBuf Where to store the read bits.
1757	* @param cbRead Number of bytes to read/bytes actually read.
1758	* @thread Any thread.
1759	*/
1760	DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMISTREAM pInterface, void pvBuf, size_t cbRead));
1761
1762	/**
1763	* Write bits.
1764	*
1765	* @returns VBox status code.
1766	* @param pInterface Pointer to the interface structure containing the called function pointer.
1767	* @param pvBuf Where to store the write bits.
1768	* @param cbWrite Number of bytes to write/bytes actually written.
1769	* @thread Any thread.
1770	*/
1771	DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMISTREAM pInterface, const void pvBuf, size_t cbWrite));
1772	} PDMISTREAM;
1773	/** PDMISTREAM interface ID. */
1774	#define PDMISTREAM_IID "d1a5bf5e-3d2c-449a-bde9-addd7920b71f"
1775
1776
1777	/** Mode of the parallel port */
1778	typedef enum PDMPARALLELPORTMODE
1779	{
1780	/** First invalid mode. */
1781	PDM_PARALLEL_PORT_MODE_INVALID = 0,
1782	/** SPP (Compatibility mode). */
1783	PDM_PARALLEL_PORT_MODE_SPP,
1784	/** EPP Data mode. */
1785	PDM_PARALLEL_PORT_MODE_EPP_DATA,
1786	/** EPP Address mode. */
1787	PDM_PARALLEL_PORT_MODE_EPP_ADDR,
1788	/** ECP mode (not implemented yet). */
1789	PDM_PARALLEL_PORT_MODE_ECP,
1790	/** 32bit hack. */
1791	PDM_PARALLEL_PORT_MODE_32BIT_HACK = 0x7fffffff
1792	} PDMPARALLELPORTMODE;
1793
1794	/** Pointer to a host parallel port interface. */
1795	typedef struct PDMIHOSTPARALLELPORT *PPDMIHOSTPARALLELPORT;
1796	/**
1797	* Host parallel port interface (down).
1798	* Pair with PDMIHOSTPARALLELCONNECTOR.
1799	*/
1800	typedef struct PDMIHOSTPARALLELPORT
1801	{
1802	/**
1803	* Notify device/driver that an interrupt has occurred.
1804	*
1805	* @returns VBox status code.
1806	* @param pInterface Pointer to the interface structure containing the called function pointer.
1807	* @thread Any thread.
1808	*/
1809	DECLR3CALLBACKMEMBER(int, pfnNotifyInterrupt,(PPDMIHOSTPARALLELPORT pInterface));
1810	} PDMIHOSTPARALLELPORT;
1811	/** PDMIHOSTPARALLELPORT interface ID. */
1812	#define PDMIHOSTPARALLELPORT_IID "f24b8668-e7f6-4eaa-a14c-4aa2a5f7048e"
1813
1814
1815
1816	/** Pointer to a Host Parallel connector interface. */
1817	typedef struct PDMIHOSTPARALLELCONNECTOR *PPDMIHOSTPARALLELCONNECTOR;
1818	/**
1819	* Host parallel connector interface (up).
1820	* Pair with PDMIHOSTPARALLELPORT.
1821	*/
1822	typedef struct PDMIHOSTPARALLELCONNECTOR
1823	{
1824	/**
1825	* Write bits.
1826	*
1827	* @returns VBox status code.
1828	* @param pInterface Pointer to the interface structure containing the called function pointer.
1829	* @param pvBuf Where to store the write bits.
1830	* @param cbWrite Number of bytes to write.
1831	* @param enmMode Mode to write the data.
1832	* @thread Any thread.
1833	* @todo r=klaus cbWrite only defines buffer length, method needs a way top return actually written amount of data.
1834	*/
1835	DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMIHOSTPARALLELCONNECTOR pInterface, const void *pvBuf,
1836	size_t cbWrite, PDMPARALLELPORTMODE enmMode));
1837
1838	/**
1839	* Read bits.
1840	*
1841	* @returns VBox status code.
1842	* @param pInterface Pointer to the interface structure containing the called function pointer.
1843	* @param pvBuf Where to store the read bits.
1844	* @param cbRead Number of bytes to read.
1845	* @param enmMode Mode to read the data.
1846	* @thread Any thread.
1847	* @todo r=klaus cbRead only defines buffer length, method needs a way top return actually read amount of data.
1848	*/
1849	DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMIHOSTPARALLELCONNECTOR pInterface, void *pvBuf,
1850	size_t cbRead, PDMPARALLELPORTMODE enmMode));
1851
1852	/**
1853	* Set data direction of the port (forward/reverse).
1854	*
1855	* @returns VBox status code.
1856	* @param pInterface Pointer to the interface structure containing the called function pointer.
1857	* @param fForward Flag whether to indicate whether the port is operated in forward or reverse mode.
1858	* @thread Any thread.
1859	*/
1860	DECLR3CALLBACKMEMBER(int, pfnSetPortDirection,(PPDMIHOSTPARALLELCONNECTOR pInterface, bool fForward));
1861
1862	/**
1863	* Write control register bits.
1864	*
1865	* @returns VBox status code.
1866	* @param pInterface Pointer to the interface structure containing the called function pointer.
1867	* @param fReg The new control register value.
1868	* @thread Any thread.
1869	*/
1870	DECLR3CALLBACKMEMBER(int, pfnWriteControl,(PPDMIHOSTPARALLELCONNECTOR pInterface, uint8_t fReg));
1871
1872	/**
1873	* Read control register bits.
1874	*
1875	* @returns VBox status code.
1876	* @param pInterface Pointer to the interface structure containing the called function pointer.
1877	* @param pfReg Where to store the control register bits.
1878	* @thread Any thread.
1879	*/
1880	DECLR3CALLBACKMEMBER(int, pfnReadControl,(PPDMIHOSTPARALLELCONNECTOR pInterface, uint8_t *pfReg));
1881
1882	/**
1883	* Read status register bits.
1884	*
1885	* @returns VBox status code.
1886	* @param pInterface Pointer to the interface structure containing the called function pointer.
1887	* @param pfReg Where to store the status register bits.
1888	* @thread Any thread.
1889	*/
1890	DECLR3CALLBACKMEMBER(int, pfnReadStatus,(PPDMIHOSTPARALLELCONNECTOR pInterface, uint8_t *pfReg));
1891
1892	} PDMIHOSTPARALLELCONNECTOR;
1893	/** PDMIHOSTPARALLELCONNECTOR interface ID. */
1894	#define PDMIHOSTPARALLELCONNECTOR_IID "7c532602-7438-4fbc-9265-349d9f0415f9"
1895
1896
1897	/** ACPI power source identifier */
1898	typedef enum PDMACPIPOWERSOURCE
1899	{
1900	PDM_ACPI_POWER_SOURCE_UNKNOWN = 0,
1901	PDM_ACPI_POWER_SOURCE_OUTLET,
1902	PDM_ACPI_POWER_SOURCE_BATTERY
1903	} PDMACPIPOWERSOURCE;
1904	/** Pointer to ACPI battery state. */
1905	typedef PDMACPIPOWERSOURCE *PPDMACPIPOWERSOURCE;
1906
1907	/** ACPI battey capacity */
1908	typedef enum PDMACPIBATCAPACITY
1909	{
1910	PDM_ACPI_BAT_CAPACITY_MIN = 0,
1911	PDM_ACPI_BAT_CAPACITY_MAX = 100,
1912	PDM_ACPI_BAT_CAPACITY_UNKNOWN = 255
1913	} PDMACPIBATCAPACITY;
1914	/** Pointer to ACPI battery capacity. */
1915	typedef PDMACPIBATCAPACITY *PPDMACPIBATCAPACITY;
1916
1917	/** ACPI battery state. See ACPI 3.0 spec '_BST (Battery Status)' */
1918	typedef enum PDMACPIBATSTATE
1919	{
1920	PDM_ACPI_BAT_STATE_CHARGED = 0x00,
1921	PDM_ACPI_BAT_STATE_DISCHARGING = 0x01,
1922	PDM_ACPI_BAT_STATE_CHARGING = 0x02,
1923	PDM_ACPI_BAT_STATE_CRITICAL = 0x04
1924	} PDMACPIBATSTATE;
1925	/** Pointer to ACPI battery state. */
1926	typedef PDMACPIBATSTATE *PPDMACPIBATSTATE;
1927
1928	/** Pointer to an ACPI port interface. */
1929	typedef struct PDMIACPIPORT *PPDMIACPIPORT;
1930	/**
1931	* ACPI port interface (down). Used by both the ACPI driver and (grumble) main.
1932	* Pair with PDMIACPICONNECTOR.
1933	*/
1934	typedef struct PDMIACPIPORT
1935	{
1936	/**
1937	* Send an ACPI power off event.
1938	*
1939	* @returns VBox status code
1940	* @param pInterface Pointer to the interface structure containing the called function pointer.
1941	*/
1942	DECLR3CALLBACKMEMBER(int, pfnPowerButtonPress,(PPDMIACPIPORT pInterface));
1943
1944	/**
1945	* Send an ACPI sleep button event.
1946	*
1947	* @returns VBox status code
1948	* @param pInterface Pointer to the interface structure containing the called function pointer.
1949	*/
1950	DECLR3CALLBACKMEMBER(int, pfnSleepButtonPress,(PPDMIACPIPORT pInterface));
1951
1952	/**
1953	* Check if the last power button event was handled by the guest.
1954	*
1955	* @returns VBox status code
1956	* @param pInterface Pointer to the interface structure containing the called function pointer.
1957	* @param pfHandled Is set to true if the last power button event was handled, false otherwise.
1958	*/
1959	DECLR3CALLBACKMEMBER(int, pfnGetPowerButtonHandled,(PPDMIACPIPORT pInterface, bool *pfHandled));
1960
1961	/**
1962	* Check if the guest entered the ACPI mode.
1963	*
1964	* @returns VBox status code
1965	* @param pInterface Pointer to the interface structure containing the called function pointer.
1966	* @param pfEnabled Is set to true if the guest entered the ACPI mode, false otherwise.
1967	*/
1968	DECLR3CALLBACKMEMBER(int, pfnGetGuestEnteredACPIMode,(PPDMIACPIPORT pInterface, bool *pfEntered));
1969
1970	/**
1971	* Check if the given CPU is still locked by the guest.
1972	*
1973	* @returns VBox status code
1974	* @param pInterface Pointer to the interface structure containing the called function pointer.
1975	* @param uCpu The CPU to check for.
1976	* @param pfLocked Is set to true if the CPU is still locked by the guest, false otherwise.
1977	*/
1978	DECLR3CALLBACKMEMBER(int, pfnGetCpuStatus,(PPDMIACPIPORT pInterface, unsigned uCpu, bool *pfLocked));
1979	} PDMIACPIPORT;
1980	/** PDMIACPIPORT interface ID. */
1981	#define PDMIACPIPORT_IID "30d3dc4c-6a73-40c8-80e9-34309deacbb3"
1982
1983
1984	/** Pointer to an ACPI connector interface. */
1985	typedef struct PDMIACPICONNECTOR *PPDMIACPICONNECTOR;
1986	/**
1987	* ACPI connector interface (up).
1988	* Pair with PDMIACPIPORT.
1989	*/
1990	typedef struct PDMIACPICONNECTOR
1991	{
1992	/**
1993	* Get the current power source of the host system.
1994	*
1995	* @returns VBox status code
1996	* @param pInterface Pointer to the interface structure containing the called function pointer.
1997	* @param penmPowerSource Pointer to the power source result variable.
1998	*/
1999	DECLR3CALLBACKMEMBER(int, pfnQueryPowerSource,(PPDMIACPICONNECTOR, PPDMACPIPOWERSOURCE penmPowerSource));
2000
2001	/**
2002	* Query the current battery status of the host system.
2003	*
2004	* @returns VBox status code?
2005	* @param pInterface Pointer to the interface structure containing the called function pointer.
2006	* @param pfPresent Is set to true if battery is present, false otherwise.
2007	* @param penmRemainingCapacity Pointer to the battery remaining capacity (0 - 100 or 255 for unknown).
2008	* @param penmBatteryState Pointer to the battery status.
2009	* @param pu32PresentRate Pointer to the present rate (0..1000 of the total capacity).
2010	*/
2011	DECLR3CALLBACKMEMBER(int, pfnQueryBatteryStatus,(PPDMIACPICONNECTOR, bool *pfPresent, PPDMACPIBATCAPACITY penmRemainingCapacity,
2012	PPDMACPIBATSTATE penmBatteryState, uint32_t *pu32PresentRate));
2013	} PDMIACPICONNECTOR;
2014	/** PDMIACPICONNECTOR interface ID. */
2015	#define PDMIACPICONNECTOR_IID "5f14bf8d-1edf-4e3a-a1e1-cca9fd08e359"
2016
2017
2018	/** Pointer to a VMMDevice port interface. */
2019	typedef struct PDMIVMMDEVPORT *PPDMIVMMDEVPORT;
2020	/**
2021	* VMMDevice port interface (down).
2022	* Pair with PDMIVMMDEVCONNECTOR.
2023	*/
2024	typedef struct PDMIVMMDEVPORT
2025	{
2026	/**
2027	* Return the current absolute mouse position in pixels
2028	*
2029	* @returns VBox status code
2030	* @param pInterface Pointer to the interface structure containing the called function pointer.
2031	* @param pxAbs Pointer of result value, can be NULL
2032	* @param pyAbs Pointer of result value, can be NULL
2033	*/
2034	DECLR3CALLBACKMEMBER(int, pfnQueryAbsoluteMouse,(PPDMIVMMDEVPORT pInterface, int32_t pxAbs, int32_t pyAbs));
2035
2036	/**
2037	* Set the new absolute mouse position in pixels
2038	*
2039	* @returns VBox status code
2040	* @param pInterface Pointer to the interface structure containing the called function pointer.
2041	* @param xabs New absolute X position
2042	* @param yAbs New absolute Y position
2043	*/
2044	DECLR3CALLBACKMEMBER(int, pfnSetAbsoluteMouse,(PPDMIVMMDEVPORT pInterface, int32_t xAbs, int32_t yAbs));
2045
2046	/**
2047	* Return the current mouse capability flags
2048	*
2049	* @returns VBox status code
2050	* @param pInterface Pointer to the interface structure containing the called function pointer.
2051	* @param pfCapabilities Pointer of result value
2052	*/
2053	DECLR3CALLBACKMEMBER(int, pfnQueryMouseCapabilities,(PPDMIVMMDEVPORT pInterface, uint32_t *pfCapabilities));
2054
2055	/**
2056	* Set the current mouse capability flag (host side)
2057	*
2058	* @returns VBox status code
2059	* @param pInterface Pointer to the interface structure containing the called function pointer.
2060	* @param fCapsAdded Mask of capabilities to add to the flag
2061	* @param fCapsRemoved Mask of capabilities to remove from the flag
2062	*/
2063	DECLR3CALLBACKMEMBER(int, pfnUpdateMouseCapabilities,(PPDMIVMMDEVPORT pInterface, uint32_t fCapsAdded, uint32_t fCapsRemoved));
2064
2065	/**
2066	* Issue a display resolution change request.
2067	*
2068	* Note that there can only one request in the queue and that in case the guest does
2069	* not process it, issuing another request will overwrite the previous.
2070	*
2071	* @returns VBox status code
2072	* @param pInterface Pointer to the interface structure containing the called function pointer.
2073	* @param cx Horizontal pixel resolution (0 = do not change).
2074	* @param cy Vertical pixel resolution (0 = do not change).
2075	* @param cBits Bits per pixel (0 = do not change).
2076	* @param idxDisplay The display index.
2077	* @param xOrigin The X coordinate of the lower left
2078	* corner of the secondary display with
2079	* ID = idxDisplay
2080	* @param yOrigin The Y coordinate of the lower left
2081	* corner of the secondary display with
2082	* ID = idxDisplay
2083	* @param fEnabled Whether the display is enabled or not. (Guessing
2084	* again.)
2085	* @param fChangeOrigin Whether the display origin point changed. (Guess)
2086	*/
2087	DECLR3CALLBACKMEMBER(int, pfnRequestDisplayChange,(PPDMIVMMDEVPORT pInterface, uint32_t cx,
2088	uint32_t cy, uint32_t cBits, uint32_t idxDisplay,
2089	int32_t xOrigin, int32_t yOrigin, bool fEnabled, bool fChangeOrigin));
2090
2091	/**
2092	* Pass credentials to guest.
2093	*
2094	* Note that there can only be one set of credentials and the guest may or may not
2095	* query them and may do whatever it wants with them.
2096	*
2097	* @returns VBox status code.
2098	* @param pInterface Pointer to the interface structure containing the called function pointer.
2099	* @param pszUsername User name, may be empty (UTF-8).
2100	* @param pszPassword Password, may be empty (UTF-8).
2101	* @param pszDomain Domain name, may be empty (UTF-8).
2102	* @param fFlags VMMDEV_SETCREDENTIALS_*.
2103	*/
2104	DECLR3CALLBACKMEMBER(int, pfnSetCredentials,(PPDMIVMMDEVPORT pInterface, const char *pszUsername,
2105	const char pszPassword, const char pszDomain,
2106	uint32_t fFlags));
2107
2108	/**
2109	* Notify the driver about a VBVA status change.
2110	*
2111	* @returns Nothing. Because it is informational callback.
2112	* @param pInterface Pointer to the interface structure containing the called function pointer.
2113	* @param fEnabled Current VBVA status.
2114	*/
2115	DECLR3CALLBACKMEMBER(void, pfnVBVAChange, (PPDMIVMMDEVPORT pInterface, bool fEnabled));
2116
2117	/**
2118	* Issue a seamless mode change request.
2119	*
2120	* Note that there can only one request in the queue and that in case the guest does
2121	* not process it, issuing another request will overwrite the previous.
2122	*
2123	* @returns VBox status code
2124	* @param pInterface Pointer to the interface structure containing the called function pointer.
2125	* @param fEnabled Seamless mode enabled or not
2126	*/
2127	DECLR3CALLBACKMEMBER(int, pfnRequestSeamlessChange,(PPDMIVMMDEVPORT pInterface, bool fEnabled));
2128
2129	/**
2130	* Issue a memory balloon change request.
2131	*
2132	* Note that there can only one request in the queue and that in case the guest does
2133	* not process it, issuing another request will overwrite the previous.
2134	*
2135	* @returns VBox status code
2136	* @param pInterface Pointer to the interface structure containing the called function pointer.
2137	* @param cMbBalloon Balloon size in megabytes
2138	*/
2139	DECLR3CALLBACKMEMBER(int, pfnSetMemoryBalloon,(PPDMIVMMDEVPORT pInterface, uint32_t cMbBalloon));
2140
2141	/**
2142	* Issue a statistcs interval change request.
2143	*
2144	* Note that there can only one request in the queue and that in case the guest does
2145	* not process it, issuing another request will overwrite the previous.
2146	*
2147	* @returns VBox status code
2148	* @param pInterface Pointer to the interface structure containing the called function pointer.
2149	* @param cSecsStatInterval Statistics query interval in seconds
2150	* (0=disable).
2151	*/
2152	DECLR3CALLBACKMEMBER(int, pfnSetStatisticsInterval,(PPDMIVMMDEVPORT pInterface, uint32_t cSecsStatInterval));
2153
2154	/**
2155	* Notify the guest about a VRDP status change.
2156	*
2157	* @returns VBox status code
2158	* @param pInterface Pointer to the interface structure containing the called function pointer.
2159	* @param fVRDPEnabled Current VRDP status.
2160	* @param uVRDPExperienceLevel Which visual effects to be disabled in
2161	* the guest.
2162	*/
2163	DECLR3CALLBACKMEMBER(int, pfnVRDPChange, (PPDMIVMMDEVPORT pInterface, bool fVRDPEnabled, uint32_t uVRDPExperienceLevel));
2164
2165	/**
2166	* Notify the guest of CPU hot-unplug event.
2167	*
2168	* @returns VBox status code
2169	* @param pInterface Pointer to the interface structure containing the called function pointer.
2170	* @param idCpuCore The core id of the CPU to remove.
2171	* @param idCpuPackage The package id of the CPU to remove.
2172	*/
2173	DECLR3CALLBACKMEMBER(int, pfnCpuHotUnplug, (PPDMIVMMDEVPORT pInterface, uint32_t idCpuCore, uint32_t idCpuPackage));
2174
2175	/**
2176	* Notify the guest of CPU hot-plug event.
2177	*
2178	* @returns VBox status code
2179	* @param pInterface Pointer to the interface structure containing the called function pointer.
2180	* @param idCpuCore The core id of the CPU to add.
2181	* @param idCpuPackage The package id of the CPU to add.
2182	*/
2183	DECLR3CALLBACKMEMBER(int, pfnCpuHotPlug, (PPDMIVMMDEVPORT pInterface, uint32_t idCpuCore, uint32_t idCpuPackage));
2184
2185	} PDMIVMMDEVPORT;
2186	/** PDMIVMMDEVPORT interface ID. */
2187	#define PDMIVMMDEVPORT_IID "d7e52035-3b6c-422e-9215-2a75646a945d"
2188
2189
2190	/** Pointer to a HPET legacy notification interface. */
2191	typedef struct PDMIHPETLEGACYNOTIFY *PPDMIHPETLEGACYNOTIFY;
2192	/**
2193	* HPET legacy notification interface.
2194	*/
2195	typedef struct PDMIHPETLEGACYNOTIFY
2196	{
2197	/**
2198	* Notify about change of HPET legacy mode.
2199	*
2200	* @param pInterface Pointer to the interface structure containing the
2201	* called function pointer.
2202	* @param fActivated If HPET legacy mode is activated (@c true) or
2203	* deactivated (@c false).
2204	*/
2205	DECLR3CALLBACKMEMBER(void, pfnModeChanged,(PPDMIHPETLEGACYNOTIFY pInterface, bool fActivated));
2206	} PDMIHPETLEGACYNOTIFY;
2207	/** PDMIHPETLEGACYNOTIFY interface ID. */
2208	#define PDMIHPETLEGACYNOTIFY_IID "c9ada595-4b65-4311-8b21-b10498997774"
2209
2210
2211	/** @name Flags for PDMIVMMDEVPORT::pfnSetCredentials.
2212	* @{ */
2213	/** The guest should perform a logon with the credentials. */
2214	#define VMMDEV_SETCREDENTIALS_GUESTLOGON RT_BIT(0)
2215	/** The guest should prevent local logons. */
2216	#define VMMDEV_SETCREDENTIALS_NOLOCALLOGON RT_BIT(1)
2217	/** The guest should verify the credentials. */
2218	#define VMMDEV_SETCREDENTIALS_JUDGE RT_BIT(15)
2219	/** @} */
2220
2221	/** Forward declaration of the guest information structure. */
2222	struct VBoxGuestInfo;
2223	/** Forward declaration of the guest information-2 structure. */
2224	struct VBoxGuestInfo2;
2225	/** Forward declaration of the guest statistics structure */
2226	struct VBoxGuestStatistics;
2227	/** Forward declaration of the guest status structure */
2228	struct VBoxGuestStatus;
2229
2230	/** Forward declaration of the video accelerator command memory. */
2231	struct VBVAMEMORY;
2232	/** Pointer to video accelerator command memory. */
2233	typedef struct VBVAMEMORY *PVBVAMEMORY;
2234
2235	/** Pointer to a VMMDev connector interface. */
2236	typedef struct PDMIVMMDEVCONNECTOR *PPDMIVMMDEVCONNECTOR;
2237	/**
2238	* VMMDev connector interface (up).
2239	* Pair with PDMIVMMDEVPORT.
2240	*/
2241	typedef struct PDMIVMMDEVCONNECTOR
2242	{
2243	/**
2244	* Update guest facility status.
2245	*
2246	* Called in response to VMMDevReq_ReportGuestStatus, reset or state restore.
2247	*
2248	* @param pInterface Pointer to this interface.
2249	* @param uFacility The facility.
2250	* @param uStatus The status.
2251	* @param fFlags Flags assoicated with the update. Currently
2252	* reserved and should be ignored.
2253	* @param pTimeSpecTS Pointer to the timestamp of this report.
2254	* @thread The emulation thread.
2255	*/
2256	DECLR3CALLBACKMEMBER(void, pfnUpdateGuestStatus,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t uFacility, uint16_t uStatus,
2257	uint32_t fFlags, PCRTTIMESPEC pTimeSpecTS));
2258
2259	/**
2260	* Reports the guest API and OS version.
2261	* Called whenever the Additions issue a guest info report request.
2262	*
2263	* @param pInterface Pointer to this interface.
2264	* @param pGuestInfo Pointer to guest information structure
2265	* @thread The emulation thread.
2266	*/
2267	DECLR3CALLBACKMEMBER(void, pfnUpdateGuestInfo,(PPDMIVMMDEVCONNECTOR pInterface, const struct VBoxGuestInfo *pGuestInfo));
2268
2269	/**
2270	* Reports the detailed Guest Additions version.
2271	*
2272	* @param pInterface Pointer to this interface.
2273	* @param uFullVersion The guest additions version as a full version.
2274	* Use VBOX_FULL_VERSION_GET_MAJOR,
2275	* VBOX_FULL_VERSION_GET_MINOR and
2276	* VBOX_FULL_VERSION_GET_BUILD to access it.
2277	* (This will not be zero, so turn down the
2278	* paranoia level a notch.)
2279	* @param pszName Pointer to the sanitized version name. This can
2280	* be empty, but will not be NULL. If not empty,
2281	* it will contain a build type tag and/or a
2282	* publisher tag. If both, then they are separated
2283	* by an underscore (VBOX_VERSION_STRING fashion).
2284	* @param uRevision The SVN revision. Can be 0.
2285	* @param fFeatures Feature mask, currently none are defined.
2286	*
2287	* @thread The emulation thread.
2288	*/
2289	DECLR3CALLBACKMEMBER(void, pfnUpdateGuestInfo2,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t uFullVersion,
2290	const char *pszName, uint32_t uRevision, uint32_t fFeatures));
2291
2292	/**
2293	* Update the guest additions capabilities.
2294	* This is called when the guest additions capabilities change. The new capabilities
2295	* are given and the connector should update its internal state.
2296	*
2297	* @param pInterface Pointer to this interface.
2298	* @param newCapabilities New capabilities.
2299	* @thread The emulation thread.
2300	*/
2301	DECLR3CALLBACKMEMBER(void, pfnUpdateGuestCapabilities,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t newCapabilities));
2302
2303	/**
2304	* Update the mouse capabilities.
2305	* This is called when the mouse capabilities change. The new capabilities
2306	* are given and the connector should update its internal state.
2307	*
2308	* @param pInterface Pointer to this interface.
2309	* @param newCapabilities New capabilities.
2310	* @thread The emulation thread.
2311	*/
2312	DECLR3CALLBACKMEMBER(void, pfnUpdateMouseCapabilities,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t newCapabilities));
2313
2314	/**
2315	* Update the pointer shape.
2316	* This is called when the mouse pointer shape changes. The new shape
2317	* is passed as a caller allocated buffer that will be freed after returning
2318	*
2319	* @param pInterface Pointer to this interface.
2320	* @param fVisible Visibility indicator (if false, the other parameters are undefined).
2321	* @param fAlpha Flag whether alpha channel is being passed.
2322	* @param xHot Pointer hot spot x coordinate.
2323	* @param yHot Pointer hot spot y coordinate.
2324	* @param x Pointer new x coordinate on screen.
2325	* @param y Pointer new y coordinate on screen.
2326	* @param cx Pointer width in pixels.
2327	* @param cy Pointer height in pixels.
2328	* @param cbScanline Size of one scanline in bytes.
2329	* @param pvShape New shape buffer.
2330	* @thread The emulation thread.
2331	*/
2332	DECLR3CALLBACKMEMBER(void, pfnUpdatePointerShape,(PPDMIVMMDEVCONNECTOR pInterface, bool fVisible, bool fAlpha,
2333	uint32_t xHot, uint32_t yHot,
2334	uint32_t cx, uint32_t cy,
2335	void *pvShape));
2336
2337	/**
2338	* Enable or disable video acceleration on behalf of guest.
2339	*
2340	* @param pInterface Pointer to this interface.
2341	* @param fEnable Whether to enable acceleration.
2342	* @param pVbvaMemory Video accelerator memory.
2343
2344	* @return VBox rc. VINF_SUCCESS if VBVA was enabled.
2345	* @thread The emulation thread.
2346	*/
2347	DECLR3CALLBACKMEMBER(int, pfnVideoAccelEnable,(PPDMIVMMDEVCONNECTOR pInterface, bool fEnable, PVBVAMEMORY pVbvaMemory));
2348
2349	/**
2350	* Force video queue processing.
2351	*
2352	* @param pInterface Pointer to this interface.
2353	* @thread The emulation thread.
2354	*/
2355	DECLR3CALLBACKMEMBER(void, pfnVideoAccelFlush,(PPDMIVMMDEVCONNECTOR pInterface));
2356
2357	/**
2358	* Return whether the given video mode is supported/wanted by the host.
2359	*
2360	* @returns VBox status code
2361	* @param pInterface Pointer to this interface.
2362	* @param display The guest monitor, 0 for primary.
2363	* @param cy Video mode horizontal resolution in pixels.
2364	* @param cx Video mode vertical resolution in pixels.
2365	* @param cBits Video mode bits per pixel.
2366	* @param pfSupported Where to put the indicator for whether this mode is supported. (output)
2367	* @thread The emulation thread.
2368	*/
2369	DECLR3CALLBACKMEMBER(int, pfnVideoModeSupported,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t display, uint32_t cx, uint32_t cy, uint32_t cBits, bool *pfSupported));
2370
2371	/**
2372	* Queries by how many pixels the height should be reduced when calculating video modes
2373	*
2374	* @returns VBox status code
2375	* @param pInterface Pointer to this interface.
2376	* @param pcyReduction Pointer to the result value.
2377	* @thread The emulation thread.
2378	*/
2379	DECLR3CALLBACKMEMBER(int, pfnGetHeightReduction,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t *pcyReduction));
2380
2381	/**
2382	* Informs about a credentials judgement result from the guest.
2383	*
2384	* @returns VBox status code
2385	* @param pInterface Pointer to this interface.
2386	* @param fFlags Judgement result flags.
2387	* @thread The emulation thread.
2388	*/
2389	DECLR3CALLBACKMEMBER(int, pfnSetCredentialsJudgementResult,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t fFlags));
2390
2391	/**
2392	* Set the visible region of the display
2393	*
2394	* @returns VBox status code.
2395	* @param pInterface Pointer to this interface.
2396	* @param cRect Number of rectangles in pRect
2397	* @param pRect Rectangle array
2398	* @thread The emulation thread.
2399	*/
2400	DECLR3CALLBACKMEMBER(int, pfnSetVisibleRegion,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t cRect, PRTRECT pRect));
2401
2402	/**
2403	* Query the visible region of the display
2404	*
2405	* @returns VBox status code.
2406	* @param pInterface Pointer to this interface.
2407	* @param pcRect Number of rectangles in pRect
2408	* @param pRect Rectangle array (set to NULL to query the number of rectangles)
2409	* @thread The emulation thread.
2410	*/
2411	DECLR3CALLBACKMEMBER(int, pfnQueryVisibleRegion,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t *pcRect, PRTRECT pRect));
2412
2413	/**
2414	* Request the statistics interval
2415	*
2416	* @returns VBox status code.
2417	* @param pInterface Pointer to this interface.
2418	* @param pulInterval Pointer to interval in seconds
2419	* @thread The emulation thread.
2420	*/
2421	DECLR3CALLBACKMEMBER(int, pfnQueryStatisticsInterval,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t *pulInterval));
2422
2423	/**
2424	* Report new guest statistics
2425	*
2426	* @returns VBox status code.
2427	* @param pInterface Pointer to this interface.
2428	* @param pGuestStats Guest statistics
2429	* @thread The emulation thread.
2430	*/
2431	DECLR3CALLBACKMEMBER(int, pfnReportStatistics,(PPDMIVMMDEVCONNECTOR pInterface, struct VBoxGuestStatistics *pGuestStats));
2432
2433	/**
2434	* Query the current balloon size
2435	*
2436	* @returns VBox status code.
2437	* @param pInterface Pointer to this interface.
2438	* @param pcbBalloon Balloon size
2439	* @thread The emulation thread.
2440	*/
2441	DECLR3CALLBACKMEMBER(int, pfnQueryBalloonSize,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t *pcbBalloon));
2442
2443	/**
2444	* Query the current page fusion setting
2445	*
2446	* @returns VBox status code.
2447	* @param pInterface Pointer to this interface.
2448	* @param pfPageFusionEnabled Pointer to boolean
2449	* @thread The emulation thread.
2450	*/
2451	DECLR3CALLBACKMEMBER(int, pfnIsPageFusionEnabled,(PPDMIVMMDEVCONNECTOR pInterface, bool *pfPageFusionEnabled));
2452
2453	} PDMIVMMDEVCONNECTOR;
2454	/** PDMIVMMDEVCONNECTOR interface ID. */
2455	#define PDMIVMMDEVCONNECTOR_IID "aff90240-a443-434e-9132-80c186ab97d4"
2456
2457
2458	/** Pointer to a network connector interface */
2459	typedef struct PDMIAUDIOCONNECTOR *PPDMIAUDIOCONNECTOR;
2460	/**
2461	* Audio connector interface (up).
2462	* No interface pair yet.
2463	*/
2464	typedef struct PDMIAUDIOCONNECTOR
2465	{
2466	DECLR3CALLBACKMEMBER(void, pfnRun,(PPDMIAUDIOCONNECTOR pInterface));
2467
2468	/* DECLR3CALLBACKMEMBER(int, pfnSetRecordSource,(PPDMIAUDIOINCONNECTOR pInterface, AUDIORECSOURCE)); */
2469
2470	} PDMIAUDIOCONNECTOR;
2471	/** PDMIAUDIOCONNECTOR interface ID. */
2472	#define PDMIAUDIOCONNECTOR_IID "85d52af5-b3aa-4b3e-b176-4b5ebfc52f47"
2473
2474
2475	/** @todo r=bird: the two following interfaces are hacks to work around the missing audio driver
2476	* interface. This should be addressed rather than making more temporary hacks. */
2477
2478	/** Pointer to a Audio Sniffer Device port interface. */
2479	typedef struct PDMIAUDIOSNIFFERPORT *PPDMIAUDIOSNIFFERPORT;
2480	/**
2481	* Audio Sniffer port interface (down).
2482	* Pair with PDMIAUDIOSNIFFERCONNECTOR.
2483	*/
2484	typedef struct PDMIAUDIOSNIFFERPORT
2485	{
2486	/**
2487	* Enables or disables sniffing.
2488	*
2489	* If sniffing is being enabled also sets a flag whether the audio must be also
2490	* left on the host.
2491	*
2492	* @returns VBox status code
2493	* @param pInterface Pointer to this interface.
2494	* @param fEnable 'true' for enable sniffing, 'false' to disable.
2495	* @param fKeepHostAudio Indicates whether host audio should also present
2496	* 'true' means that sound should not be played
2497	* by the audio device.
2498	*/
2499	DECLR3CALLBACKMEMBER(int, pfnSetup,(PPDMIAUDIOSNIFFERPORT pInterface, bool fEnable, bool fKeepHostAudio));
2500
2501	/**
2502	* Enables or disables audio input.
2503	*
2504	* @returns VBox status code
2505	* @param pInterface Pointer to this interface.
2506	* @param fIntercept 'true' for interception of audio input,
2507	* 'false' to let the host audio backend do audio input.
2508	*/
2509	DECLR3CALLBACKMEMBER(int, pfnAudioInputIntercept,(PPDMIAUDIOSNIFFERPORT pInterface, bool fIntercept));
2510
2511	/**
2512	* Audio input is about to start.
2513	*
2514	* @returns VBox status code.
2515	* @param pvContext The callback context, supplied in the
2516	* PDMIAUDIOSNIFFERCONNECTOR::pfnAudioInputBegin as pvContext.
2517	* @param iSampleHz The sample frequency in Hz.
2518	* @param cChannels Number of channels. 1 for mono, 2 for stereo.
2519	* @param cBits How many bits a sample for a single channel has. Normally 8 or 16.
2520	* @param fUnsigned Whether samples are unsigned values.
2521	*/
2522	DECLR3CALLBACKMEMBER(int, pfnAudioInputEventBegin,(PPDMIAUDIOSNIFFERPORT pInterface,
2523	void *pvContext,
2524	int iSampleHz,
2525	int cChannels,
2526	int cBits,
2527	bool fUnsigned));
2528
2529	/**
2530	* Callback which delivers audio data to the audio device.
2531	*
2532	* @returns VBox status code.
2533	* @param pvContext The callback context, supplied in the
2534	* PDMIAUDIOSNIFFERCONNECTOR::pfnAudioInputBegin as pvContext.
2535	* @param pvData Event specific data.
2536	* @param cbData Size of the buffer pointed by pvData.
2537	*/
2538	DECLR3CALLBACKMEMBER(int, pfnAudioInputEventData,(PPDMIAUDIOSNIFFERPORT pInterface,
2539	void *pvContext,
2540	const void *pvData,
2541	uint32_t cbData));
2542
2543	/**
2544	* Audio input ends.
2545	*
2546	* @param pvContext The callback context, supplied in the
2547	* PDMIAUDIOSNIFFERCONNECTOR::pfnAudioInputBegin as pvContext.
2548	*/
2549	DECLR3CALLBACKMEMBER(void, pfnAudioInputEventEnd,(PPDMIAUDIOSNIFFERPORT pInterface,
2550	void *pvContext));
2551	} PDMIAUDIOSNIFFERPORT;
2552	/** PDMIAUDIOSNIFFERPORT interface ID. */
2553	#define PDMIAUDIOSNIFFERPORT_IID "8ad25d78-46e9-479b-a363-bb0bc0fe022f"
2554
2555
2556	/** Pointer to a Audio Sniffer connector interface. */
2557	typedef struct PDMIAUDIOSNIFFERCONNECTOR *PPDMIAUDIOSNIFFERCONNECTOR;
2558
2559	/**
2560	* Audio Sniffer connector interface (up).
2561	* Pair with PDMIAUDIOSNIFFERPORT.
2562	*/
2563	typedef struct PDMIAUDIOSNIFFERCONNECTOR
2564	{
2565	/**
2566	* AudioSniffer device calls this method when audio samples
2567	* are about to be played and sniffing is enabled.
2568	*
2569	* @param pInterface Pointer to this interface.
2570	* @param pvSamples Audio samples buffer.
2571	* @param cSamples How many complete samples are in the buffer.
2572	* @param iSampleHz The sample frequency in Hz.
2573	* @param cChannels Number of channels. 1 for mono, 2 for stereo.
2574	* @param cBits How many bits a sample for a single channel has. Normally 8 or 16.
2575	* @param fUnsigned Whether samples are unsigned values.
2576	* @thread The emulation thread.
2577	*/
2578	DECLR3CALLBACKMEMBER(void, pfnAudioSamplesOut,(PPDMIAUDIOSNIFFERCONNECTOR pInterface, void *pvSamples, uint32_t cSamples,
2579	int iSampleHz, int cChannels, int cBits, bool fUnsigned));
2580
2581	/**
2582	* AudioSniffer device calls this method when output volume is changed.
2583	*
2584	* @param pInterface Pointer to this interface.
2585	* @param u16LeftVolume 0..0xFFFF volume level for left channel.
2586	* @param u16RightVolume 0..0xFFFF volume level for right channel.
2587	* @thread The emulation thread.
2588	*/
2589	DECLR3CALLBACKMEMBER(void, pfnAudioVolumeOut,(PPDMIAUDIOSNIFFERCONNECTOR pInterface, uint16_t u16LeftVolume, uint16_t u16RightVolume));
2590
2591	/**
2592	* Audio input has been requested by the virtual audio device.
2593	*
2594	* @param pInterface Pointer to this interface.
2595	* @param ppvUserCtx The interface context for this audio input stream,
2596	* it will be used in the pfnAudioInputEnd call.
2597	* @param pvContext The context pointer to be used in PDMIAUDIOSNIFFERPORT::pfnAudioInputEvent.
2598	* @param cSamples How many samples in a block is preferred in
2599	* PDMIAUDIOSNIFFERPORT::pfnAudioInputEvent.
2600	* @param iSampleHz The sample frequency in Hz.
2601	* @param cChannels Number of channels. 1 for mono, 2 for stereo.
2602	* @param cBits How many bits a sample for a single channel has. Normally 8 or 16.
2603	* @thread The emulation thread.
2604	*/
2605	DECLR3CALLBACKMEMBER(int, pfnAudioInputBegin,(PPDMIAUDIOSNIFFERCONNECTOR pInterface,
2606	void **ppvUserCtx,
2607	void *pvContext,
2608	uint32_t cSamples,
2609	uint32_t iSampleHz,
2610	uint32_t cChannels,
2611	uint32_t cBits));
2612
2613	/**
2614	* Audio input has been requested by the virtual audio device.
2615	*
2616	* @param pInterface Pointer to this interface.
2617	* @param pvUserCtx The interface context for this audio input stream,
2618	* which was returned by pfnAudioInputBegin call.
2619	* @thread The emulation thread.
2620	*/
2621	DECLR3CALLBACKMEMBER(void, pfnAudioInputEnd,(PPDMIAUDIOSNIFFERCONNECTOR pInterface,
2622	void *pvUserCtx));
2623	} PDMIAUDIOSNIFFERCONNECTOR;
2624	/** PDMIAUDIOSNIFFERCONNECTOR - The Audio Sniffer Driver connector interface. */
2625	#define PDMIAUDIOSNIFFERCONNECTOR_IID "9d37f543-27af-45f8-8002-8ef7abac71e4"
2626
2627
2628	/**
2629	* Generic status LED core.
2630	* Note that a unit doesn't have to support all the indicators.
2631	*/
2632	typedef union PDMLEDCORE
2633	{
2634	/** 32-bit view. */
2635	uint32_t volatile u32;
2636	/** Bit view. */
2637	struct
2638	{
2639	/** Reading/Receiving indicator. */
2640	uint32_t fReading : 1;
2641	/** Writing/Sending indicator. */
2642	uint32_t fWriting : 1;
2643	/** Busy indicator. */
2644	uint32_t fBusy : 1;
2645	/** Error indicator. */
2646	uint32_t fError : 1;
2647	} s;
2648	} PDMLEDCORE;
2649
2650	/** LED bit masks for the u32 view.
2651	* @{ */
2652	/** Reading/Receiving indicator. */
2653	#define PDMLED_READING RT_BIT(0)
2654	/** Writing/Sending indicator. */
2655	#define PDMLED_WRITING RT_BIT(1)
2656	/** Busy indicator. */
2657	#define PDMLED_BUSY RT_BIT(2)
2658	/** Error indicator. */
2659	#define PDMLED_ERROR RT_BIT(3)
2660	/** @} */
2661
2662
2663	/**
2664	* Generic status LED.
2665	* Note that a unit doesn't have to support all the indicators.
2666	*/
2667	typedef struct PDMLED
2668	{
2669	/** Just a magic for sanity checking. */
2670	uint32_t u32Magic;
2671	uint32_t u32Alignment; /*< structure size alignment. /
2672	/** The actual LED status.
2673	* Only the device is allowed to change this. */
2674	PDMLEDCORE Actual;
2675	/** The asserted LED status which is cleared by the reader.
2676	* The device will assert the bits but never clear them.
2677	* The driver clears them as it sees fit. */
2678	PDMLEDCORE Asserted;
2679	} PDMLED;
2680
2681	/** Pointer to an LED. */
2682	typedef PDMLED *PPDMLED;
2683	/** Pointer to a const LED. */
2684	typedef const PDMLED *PCPDMLED;
2685
2686	/** Magic value for PDMLED::u32Magic. */
2687	#define PDMLED_MAGIC UINT32_C(0x11335577)
2688
2689	/** Pointer to an LED ports interface. */
2690	typedef struct PDMILEDPORTS *PPDMILEDPORTS;
2691	/**
2692	* Interface for exporting LEDs (down).
2693	* Pair with PDMILEDCONNECTORS.
2694	*/
2695	typedef struct PDMILEDPORTS
2696	{
2697	/**
2698	* Gets the pointer to the status LED of a unit.
2699	*
2700	* @returns VBox status code.
2701	* @param pInterface Pointer to the interface structure containing the called function pointer.
2702	* @param iLUN The unit which status LED we desire.
2703	* @param ppLed Where to store the LED pointer.
2704	*/
2705	DECLR3CALLBACKMEMBER(int, pfnQueryStatusLed,(PPDMILEDPORTS pInterface, unsigned iLUN, PPDMLED *ppLed));
2706
2707	} PDMILEDPORTS;
2708	/** PDMILEDPORTS interface ID. */
2709	#define PDMILEDPORTS_IID "435e0cec-8549-4ca0-8c0d-98e52f1dc038"
2710
2711
2712	/** Pointer to an LED connectors interface. */
2713	typedef struct PDMILEDCONNECTORS *PPDMILEDCONNECTORS;
2714	/**
2715	* Interface for reading LEDs (up).
2716	* Pair with PDMILEDPORTS.
2717	*/
2718	typedef struct PDMILEDCONNECTORS
2719	{
2720	/**
2721	* Notification about a unit which have been changed.
2722	*
2723	* The driver must discard any pointers to data owned by
2724	* the unit and requery it.
2725	*
2726	* @param pInterface Pointer to the interface structure containing the called function pointer.
2727	* @param iLUN The unit number.
2728	*/
2729	DECLR3CALLBACKMEMBER(void, pfnUnitChanged,(PPDMILEDCONNECTORS pInterface, unsigned iLUN));
2730	} PDMILEDCONNECTORS;
2731	/** PDMILEDCONNECTORS interface ID. */
2732	#define PDMILEDCONNECTORS_IID "8ed63568-82a7-4193-b57b-db8085ac4495"
2733
2734
2735	/** Pointer to a Media Notification interface. */
2736	typedef struct PDMIMEDIANOTIFY *PPDMIMEDIANOTIFY;
2737	/**
2738	* Interface for exporting Medium eject information (up). No interface pair.
2739	*/
2740	typedef struct PDMIMEDIANOTIFY
2741	{
2742	/**
2743	* Signals that the medium was ejected.
2744	*
2745	* @returns VBox status code.
2746	* @param pInterface Pointer to the interface structure containing the called function pointer.
2747	* @param iLUN The unit which had the medium ejected.
2748	*/
2749	DECLR3CALLBACKMEMBER(int, pfnEjected,(PPDMIMEDIANOTIFY pInterface, unsigned iLUN));
2750
2751	} PDMIMEDIANOTIFY;
2752	/** PDMIMEDIANOTIFY interface ID. */
2753	#define PDMIMEDIANOTIFY_IID "fc22d53e-feb1-4a9c-b9fb-0a990a6ab288"
2754
2755
2756	/** The special status unit number */
2757	#define PDM_STATUS_LUN 999
2758
2759
2760	#ifdef VBOX_WITH_HGCM
2761
2762	/** Abstract HGCM command structure. Used only to define a typed pointer. */
2763	struct VBOXHGCMCMD;
2764
2765	/** Pointer to HGCM command structure. This pointer is unique and identifies
2766	* the command being processed. The pointer is passed to HGCM connector methods,
2767	* and must be passed back to HGCM port when command is completed.
2768	*/
2769	typedef struct VBOXHGCMCMD *PVBOXHGCMCMD;
2770
2771	/** Pointer to a HGCM port interface. */
2772	typedef struct PDMIHGCMPORT *PPDMIHGCMPORT;
2773	/**
2774	* Host-Guest communication manager port interface (down). Normally implemented
2775	* by VMMDev.
2776	* Pair with PDMIHGCMCONNECTOR.
2777	*/
2778	typedef struct PDMIHGCMPORT
2779	{
2780	/**
2781	* Notify the guest on a command completion.
2782	*
2783	* @param pInterface Pointer to this interface.
2784	* @param rc The return code (VBox error code).
2785	* @param pCmd A pointer that identifies the completed command.
2786	*
2787	* @returns VBox status code
2788	*/
2789	DECLR3CALLBACKMEMBER(void, pfnCompleted,(PPDMIHGCMPORT pInterface, int32_t rc, PVBOXHGCMCMD pCmd));
2790
2791	} PDMIHGCMPORT;
2792	/** PDMIHGCMPORT interface ID. */
2793	# define PDMIHGCMPORT_IID "e00a0cbf-b75a-45c3-87f4-41cddbc5ae0b"
2794
2795
2796	/** Pointer to a HGCM service location structure. */
2797	typedef struct HGCMSERVICELOCATION *PHGCMSERVICELOCATION;
2798
2799	/** Pointer to a HGCM connector interface. */
2800	typedef struct PDMIHGCMCONNECTOR *PPDMIHGCMCONNECTOR;
2801	/**
2802	* The Host-Guest communication manager connector interface (up). Normally
2803	* implemented by Main::VMMDevInterface.
2804	* Pair with PDMIHGCMPORT.
2805	*/
2806	typedef struct PDMIHGCMCONNECTOR
2807	{
2808	/**
2809	* Locate a service and inform it about a client connection.
2810	*
2811	* @param pInterface Pointer to this interface.
2812	* @param pCmd A pointer that identifies the command.
2813	* @param pServiceLocation Pointer to the service location structure.
2814	* @param pu32ClientID Where to store the client id for the connection.
2815	* @return VBox status code.
2816	* @thread The emulation thread.
2817	*/
2818	DECLR3CALLBACKMEMBER(int, pfnConnect,(PPDMIHGCMCONNECTOR pInterface, PVBOXHGCMCMD pCmd, PHGCMSERVICELOCATION pServiceLocation, uint32_t *pu32ClientID));
2819
2820	/**
2821	* Disconnect from service.
2822	*
2823	* @param pInterface Pointer to this interface.
2824	* @param pCmd A pointer that identifies the command.
2825	* @param u32ClientID The client id returned by the pfnConnect call.
2826	* @return VBox status code.
2827	* @thread The emulation thread.
2828	*/
2829	DECLR3CALLBACKMEMBER(int, pfnDisconnect,(PPDMIHGCMCONNECTOR pInterface, PVBOXHGCMCMD pCmd, uint32_t u32ClientID));
2830
2831	/**
2832	* Process a guest issued command.
2833	*
2834	* @param pInterface Pointer to this interface.
2835	* @param pCmd A pointer that identifies the command.
2836	* @param u32ClientID The client id returned by the pfnConnect call.
2837	* @param u32Function Function to be performed by the service.
2838	* @param cParms Number of parameters in the array pointed to by paParams.
2839	* @param paParms Pointer to an array of parameters.
2840	* @return VBox status code.
2841	* @thread The emulation thread.
2842	*/
2843	DECLR3CALLBACKMEMBER(int, pfnCall,(PPDMIHGCMCONNECTOR pInterface, PVBOXHGCMCMD pCmd, uint32_t u32ClientID, uint32_t u32Function,
2844	uint32_t cParms, PVBOXHGCMSVCPARM paParms));
2845
2846	} PDMIHGCMCONNECTOR;
2847	/** PDMIHGCMCONNECTOR interface ID. */
2848	# define PDMIHGCMCONNECTOR_IID "a1104758-c888-4437-8f2a-7bac17865b5c"
2849
2850	#endif /* VBOX_WITH_HGCM */
2851
2852	/**
2853	* Data direction.
2854	*/
2855	typedef enum PDMSCSIREQUESTTXDIR
2856	{
2857	PDMSCSIREQUESTTXDIR_UNKNOWN = 0x00,
2858	PDMSCSIREQUESTTXDIR_FROM_DEVICE = 0x01,
2859	PDMSCSIREQUESTTXDIR_TO_DEVICE = 0x02,
2860	PDMSCSIREQUESTTXDIR_NONE = 0x03,
2861	PDMSCSIREQUESTTXDIR_32BIT_HACK = 0x7fffffff
2862	} PDMSCSIREQUESTTXDIR;
2863
2864	/**
2865	* SCSI request structure.
2866	*/
2867	typedef struct PDMSCSIREQUEST
2868	{
2869	/** The logical unit. */
2870	uint32_t uLogicalUnit;
2871	/** Direction of the data flow. */
2872	PDMSCSIREQUESTTXDIR uDataDirection;
2873	/** Size of the SCSI CDB. */
2874	uint32_t cbCDB;
2875	/** Pointer to the SCSI CDB. */
2876	uint8_t *pbCDB;
2877	/** Overall size of all scatter gather list elements
2878	* for data transfer if any. */
2879	uint32_t cbScatterGather;
2880	/** Number of elements in the scatter gather list. */
2881	uint32_t cScatterGatherEntries;
2882	/** Pointer to the head of the scatter gather list. */
2883	PRTSGSEG paScatterGatherHead;
2884	/** Size of the sense buffer. */
2885	uint32_t cbSenseBuffer;
2886	/** Pointer to the sense buffer. *
2887	* Current assumption that the sense buffer is not scattered. */
2888	uint8_t *pbSenseBuffer;
2889	/** Opaque user data for use by the device. Left untouched by everything else! */
2890	void *pvUser;
2891	} PDMSCSIREQUEST, *PPDMSCSIREQUEST;
2892	/** Pointer to a const SCSI request structure. */
2893	typedef const PDMSCSIREQUEST *PCSCSIREQUEST;
2894
2895	/** Pointer to a SCSI port interface. */
2896	typedef struct PDMISCSIPORT *PPDMISCSIPORT;
2897	/**
2898	* SCSI command execution port interface (down).
2899	* Pair with PDMISCSICONNECTOR.
2900	*/
2901	typedef struct PDMISCSIPORT
2902	{
2903
2904	/**
2905	* Notify the device on request completion.
2906	*
2907	* @returns VBox status code.
2908	* @param pInterface Pointer to this interface.
2909	* @param pSCSIRequest Pointer to the finished SCSI request.
2910	* @param rcCompletion SCSI_STATUS_* code for the completed request.
2911	* @param fRedo Flag whether the request can to be redone
2912	* when it failed.
2913	* @param rcReq The status code the request completed with (VERR_*)
2914	* Should be only used to choose the correct error message
2915	* displayed to the user if the error can be fixed by him
2916	* (fRedo is true).
2917	*/
2918	DECLR3CALLBACKMEMBER(int, pfnSCSIRequestCompleted, (PPDMISCSIPORT pInterface, PPDMSCSIREQUEST pSCSIRequest,
2919	int rcCompletion, bool fRedo, int rcReq));
2920
2921	/**
2922	* Returns the storage controller name, instance and LUN of the attached medium.
2923	*
2924	* @returns VBox status.
2925	* @param pInterface Pointer to this interface.
2926	* @param ppcszController Where to store the name of the storage controller.
2927	* @param piInstance Where to store the instance number of the controller.
2928	* @param piLUN Where to store the LUN of the attached device.
2929	*/
2930	DECLR3CALLBACKMEMBER(int, pfnQueryDeviceLocation, (PPDMISCSIPORT pInterface, const char **ppcszController,
2931	uint32_t piInstance, uint32_t piLUN));
2932
2933	} PDMISCSIPORT;
2934	/** PDMISCSIPORT interface ID. */
2935	#define PDMISCSIPORT_IID "05d9fc3b-e38c-4b30-8344-a323feebcfe5"
2936
2937
2938	/** Pointer to a SCSI connector interface. */
2939	typedef struct PDMISCSICONNECTOR *PPDMISCSICONNECTOR;
2940	/**
2941	* SCSI command execution connector interface (up).
2942	* Pair with PDMISCSIPORT.
2943	*/
2944	typedef struct PDMISCSICONNECTOR
2945	{
2946
2947	/**
2948	* Submits a SCSI request for execution.
2949	*
2950	* @returns VBox status code.
2951	* @param pInterface Pointer to this interface.
2952	* @param pSCSIRequest Pointer to the SCSI request to execute.
2953	*/
2954	DECLR3CALLBACKMEMBER(int, pfnSCSIRequestSend, (PPDMISCSICONNECTOR pInterface, PPDMSCSIREQUEST pSCSIRequest));
2955
2956	} PDMISCSICONNECTOR;
2957	/** PDMISCSICONNECTOR interface ID. */
2958	#define PDMISCSICONNECTOR_IID "94465fbd-a2f2-447e-88c9-7366421bfbfe"
2959
2960
2961	/** Pointer to a display VBVA callbacks interface. */
2962	typedef struct PDMIDISPLAYVBVACALLBACKS *PPDMIDISPLAYVBVACALLBACKS;
2963	/**
2964	* Display VBVA callbacks interface (up).
2965	*/
2966	typedef struct PDMIDISPLAYVBVACALLBACKS
2967	{
2968
2969	/**
2970	* Informs guest about completion of processing the given Video HW Acceleration
2971	* command, does not wait for the guest to process the command.
2972	*
2973	* @returns ???
2974	* @param pInterface Pointer to this interface.
2975	* @param pCmd The Video HW Acceleration Command that was
2976	* completed.
2977	* @todo r=bird: if async means asynchronous; then
2978	* s/pfnVHWACommandCompleteAsynch/pfnVHWACommandCompleteAsync/;
2979	* fi
2980	*/
2981	DECLR3CALLBACKMEMBER(int, pfnVHWACommandCompleteAsynch, (PPDMIDISPLAYVBVACALLBACKS pInterface,
2982	PVBOXVHWACMD pCmd));
2983
2984	DECLR3CALLBACKMEMBER(int, pfnCrHgsmiCommandCompleteAsync, (PPDMIDISPLAYVBVACALLBACKS pInterface,
2985	PVBOXVDMACMD_CHROMIUM_CMD pCmd, int rc));
2986
2987	DECLR3CALLBACKMEMBER(int, pfnCrHgsmiControlCompleteAsync, (PPDMIDISPLAYVBVACALLBACKS pInterface,
2988	PVBOXVDMACMD_CHROMIUM_CTL pCmd, int rc));
2989	} PDMIDISPLAYVBVACALLBACKS;
2990	/** PDMIDISPLAYVBVACALLBACKS */
2991	#define PDMIDISPLAYVBVACALLBACKS_IID "b78b81d2-c821-4e66-96ff-dbafa76343a5"
2992
2993	/** Pointer to a PCI raw connector interface. */
2994	typedef struct PDMIPCIRAWCONNECTOR *PPDMIPCIRAWCONNECTOR;
2995	/**
2996	* PCI raw connector interface (up).
2997	*/
2998	typedef struct PDMIPCIRAWCONNECTOR
2999	{
3000
3001	/**
3002	*
3003	*/
3004	DECLR3CALLBACKMEMBER(int, pfnDeviceConstructComplete, (PPDMIPCIRAWCONNECTOR pInterface, const char *pcszName,
3005	uint32_t uHostPciAddress, uint32_t uGuestPciAddress,
3006	int rc));
3007
3008	} PDMIPCIRAWCONNECTOR;
3009	/** PDMIPCIRAWCONNECTOR interface ID. */
3010	#define PDMIPCIRAWCONNECTOR_IID "14aa9c6c-8869-4782-9dfc-910071a6aebf"
3011
3012	/** @} */
3013
3014	RT_C_DECLS_END
3015
3016	#endif

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

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

Download in other formats: