VirtualBox

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

Last change on this file since 93115 was 93115, checked in by vboxsync, 3 years ago

scm --update-copyright-year

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

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette