VirtualBox

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

Last change on this file since 90347 was 89935, checked in by vboxsync, 4 years ago

Keyboard: Reworked the release-all-keys mechanism, made sure it's used before switching active keyboard, avoided potential mix-ups when tracking depressed keys (see bugref:10045).
  • Property svn:eol-style set to native
  • Property svn:keywords set to Id Revision
File size: 94.5 KB
Line 
1/** @file
2 * PDM - Pluggable Device Manager, Interfaces.
3 */
4
5/*
6 * Copyright (C) 2006-2020 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.
750 */
751 DECLR3CALLBACKMEMBER(void, pfnReportMonitorPositions, (PPDMIDISPLAYPORT pInterface, uint32_t cPositions,
752 PCRTPOINT paPositions));
753
754} PDMIDISPLAYPORT;
755/** PDMIDISPLAYPORT interface ID. */
756#define PDMIDISPLAYPORT_IID "471b0520-338c-11e9-bb84-6ff2c956da45"
757
758/** @name Flags for PDMIDISPLAYCONNECTOR::pfnVBVAReportCursorPosition.
759 * @{ */
760/** Is the data in the report valid? */
761#define VBVA_CURSOR_VALID_DATA RT_BIT(0)
762/** Is the cursor position reported relative to a particular guest screen? */
763#define VBVA_CURSOR_SCREEN_RELATIVE RT_BIT(1)
764/** @} */
765
766/** Pointer to a 3D graphics notification. */
767typedef struct VBOX3DNOTIFY VBOX3DNOTIFY;
768/** Pointer to a 2D graphics acceleration command. */
769typedef struct VBOXVHWACMD VBOXVHWACMD;
770/** Pointer to a VBVA command header. */
771typedef struct VBVACMDHDR *PVBVACMDHDR;
772/** Pointer to a const VBVA command header. */
773typedef const struct VBVACMDHDR *PCVBVACMDHDR;
774/** Pointer to a VBVA screen information. */
775typedef struct VBVAINFOSCREEN *PVBVAINFOSCREEN;
776/** Pointer to a const VBVA screen information. */
777typedef const struct VBVAINFOSCREEN *PCVBVAINFOSCREEN;
778/** Pointer to a VBVA guest VRAM area information. */
779typedef struct VBVAINFOVIEW *PVBVAINFOVIEW;
780/** Pointer to a const VBVA guest VRAM area information. */
781typedef const struct VBVAINFOVIEW *PCVBVAINFOVIEW;
782typedef struct VBVAHOSTFLAGS *PVBVAHOSTFLAGS;
783
784/** Pointer to a display connector interface. */
785typedef struct PDMIDISPLAYCONNECTOR *PPDMIDISPLAYCONNECTOR;
786
787/**
788 * Display connector interface (up).
789 * Pair with PDMIDISPLAYPORT.
790 */
791typedef struct PDMIDISPLAYCONNECTOR
792{
793 /**
794 * Resize the display.
795 * This is called when the resolution changes. This usually happens on
796 * request from the guest os, but may also happen as the result of a reset.
797 * If the callback returns VINF_VGA_RESIZE_IN_PROGRESS, the caller (VGA device)
798 * must not access the connector and return.
799 *
800 * @returns VINF_SUCCESS if the framebuffer resize was completed,
801 * VINF_VGA_RESIZE_IN_PROGRESS if resize takes time and not yet finished.
802 * @param pInterface Pointer to this interface.
803 * @param cBits Color depth (bits per pixel) of the new video mode.
804 * @param pvVRAM Address of the guest VRAM.
805 * @param cbLine Size in bytes of a single scan line.
806 * @param cx New display width.
807 * @param cy New display height.
808 * @thread The emulation thread.
809 */
810 DECLR3CALLBACKMEMBER(int, pfnResize,(PPDMIDISPLAYCONNECTOR pInterface, uint32_t cBits, void *pvVRAM, uint32_t cbLine,
811 uint32_t cx, uint32_t cy));
812
813 /**
814 * Update a rectangle of the display.
815 * PDMIDISPLAYPORT::pfnUpdateDisplay is the caller.
816 *
817 * @param pInterface Pointer to this interface.
818 * @param x The upper left corner x coordinate of the rectangle.
819 * @param y The upper left corner y coordinate of the rectangle.
820 * @param cx The width of the rectangle.
821 * @param cy The height of the rectangle.
822 * @thread The emulation thread.
823 */
824 DECLR3CALLBACKMEMBER(void, pfnUpdateRect,(PPDMIDISPLAYCONNECTOR pInterface, uint32_t x, uint32_t y, uint32_t cx, uint32_t cy));
825
826 /**
827 * Refresh the display.
828 *
829 * The interval between these calls is set by
830 * PDMIDISPLAYPORT::pfnSetRefreshRate(). The driver should call
831 * PDMIDISPLAYPORT::pfnUpdateDisplay() if it wishes to refresh the
832 * display. PDMIDISPLAYPORT::pfnUpdateDisplay calls pfnUpdateRect with
833 * the changed rectangles.
834 *
835 * @param pInterface Pointer to this interface.
836 * @thread The emulation thread or timer queue thread.
837 */
838 DECLR3CALLBACKMEMBER(void, pfnRefresh,(PPDMIDISPLAYCONNECTOR pInterface));
839
840 /**
841 * Reset the display.
842 *
843 * Notification message when the graphics card has been reset.
844 *
845 * @param pInterface Pointer to this interface.
846 * @thread The emulation thread.
847 */
848 DECLR3CALLBACKMEMBER(void, pfnReset,(PPDMIDISPLAYCONNECTOR pInterface));
849
850 /**
851 * LFB video mode enter/exit.
852 *
853 * Notification message when LinearFrameBuffer video mode is enabled/disabled.
854 *
855 * @param pInterface Pointer to this interface.
856 * @param fEnabled false - LFB mode was disabled,
857 * true - an LFB mode was disabled
858 * @thread The emulation thread.
859 */
860 DECLR3CALLBACKMEMBER(void, pfnLFBModeChange,(PPDMIDISPLAYCONNECTOR pInterface, bool fEnabled));
861
862 /**
863 * Process the guest graphics adapter information.
864 *
865 * Direct notification from guest to the display connector.
866 *
867 * @param pInterface Pointer to this interface.
868 * @param pvVRAM Address of the guest VRAM.
869 * @param u32VRAMSize Size of the guest VRAM.
870 * @thread The emulation thread.
871 */
872 DECLR3CALLBACKMEMBER(void, pfnProcessAdapterData,(PPDMIDISPLAYCONNECTOR pInterface, void *pvVRAM, uint32_t u32VRAMSize));
873
874 /**
875 * Process the guest display information.
876 *
877 * Direct notification from guest to the display connector.
878 *
879 * @param pInterface Pointer to this interface.
880 * @param pvVRAM Address of the guest VRAM.
881 * @param uScreenId The index of the guest display to be processed.
882 * @thread The emulation thread.
883 */
884 DECLR3CALLBACKMEMBER(void, pfnProcessDisplayData,(PPDMIDISPLAYCONNECTOR pInterface, void *pvVRAM, unsigned uScreenId));
885
886 /**
887 * Process the guest Video HW Acceleration command.
888 *
889 * @param pInterface Pointer to this interface.
890 * @param enmCmd The command type (don't re-read from pCmd).
891 * @param fGuestCmd Set if the command origins with the guest and
892 * pCmd must be considered volatile.
893 * @param pCmd Video HW Acceleration Command to be processed.
894 * @retval VINF_SUCCESS - command is completed,
895 * @retval VINF_CALLBACK_RETURN if command will by asynchronously completed via
896 * complete callback.
897 * @retval VERR_INVALID_STATE if the command could not be processed (most
898 * likely because the framebuffer was disconnected) - the post should
899 * be retried later.
900 * @thread EMT
901 */
902 DECLR3CALLBACKMEMBER(int, pfnVHWACommandProcess,(PPDMIDISPLAYCONNECTOR pInterface, int enmCmd, bool fGuestCmd,
903 VBOXVHWACMD RT_UNTRUSTED_VOLATILE_GUEST *pCmd));
904
905 /**
906 * The specified screen enters VBVA mode.
907 *
908 * @param pInterface Pointer to this interface.
909 * @param uScreenId The screen updates are for.
910 * @param pHostFlags Undocumented!
911 * @thread The emulation thread.
912 */
913 DECLR3CALLBACKMEMBER(int, pfnVBVAEnable,(PPDMIDISPLAYCONNECTOR pInterface, unsigned uScreenId,
914 struct VBVAHOSTFLAGS RT_UNTRUSTED_VOLATILE_GUEST *pHostFlags));
915
916 /**
917 * The specified screen leaves VBVA mode.
918 *
919 * @param pInterface Pointer to this interface.
920 * @param uScreenId The screen updates are for.
921 * @thread if render thread mode is on (fRenderThreadMode that was passed to pfnVBVAEnable is TRUE) - the render thread pfnVBVAEnable was called in,
922 * otherwise - the emulation thread.
923 */
924 DECLR3CALLBACKMEMBER(void, pfnVBVADisable,(PPDMIDISPLAYCONNECTOR pInterface, unsigned uScreenId));
925
926 /**
927 * A sequence of pfnVBVAUpdateProcess calls begins.
928 *
929 * @param pInterface Pointer to this interface.
930 * @param uScreenId The screen updates are for.
931 * @thread if render thread mode is on (fRenderThreadMode that was passed to pfnVBVAEnable is TRUE) - the render thread pfnVBVAEnable was called in,
932 * otherwise - the emulation thread.
933 */
934 DECLR3CALLBACKMEMBER(void, pfnVBVAUpdateBegin,(PPDMIDISPLAYCONNECTOR pInterface, unsigned uScreenId));
935
936 /**
937 * Process the guest VBVA command.
938 *
939 * @param pInterface Pointer to this interface.
940 * @param uScreenId The screen updates are for.
941 * @param pCmd Video HW Acceleration Command to be processed.
942 * @param cbCmd Undocumented!
943 * @thread if render thread mode is on (fRenderThreadMode that was passed to pfnVBVAEnable is TRUE) - the render thread pfnVBVAEnable was called in,
944 * otherwise - the emulation thread.
945 */
946 DECLR3CALLBACKMEMBER(void, pfnVBVAUpdateProcess,(PPDMIDISPLAYCONNECTOR pInterface, unsigned uScreenId,
947 struct VBVACMDHDR const RT_UNTRUSTED_VOLATILE_GUEST *pCmd, size_t cbCmd));
948
949 /**
950 * A sequence of pfnVBVAUpdateProcess calls ends.
951 *
952 * @param pInterface Pointer to this interface.
953 * @param uScreenId The screen updates are for.
954 * @param x The upper left corner x coordinate of the combined rectangle of all VBVA updates.
955 * @param y The upper left corner y coordinate of the rectangle.
956 * @param cx The width of the rectangle.
957 * @param cy The height of the rectangle.
958 * @thread if render thread mode is on (fRenderThreadMode that was passed to pfnVBVAEnable is TRUE) - the render thread pfnVBVAEnable was called in,
959 * otherwise - the emulation thread.
960 */
961 DECLR3CALLBACKMEMBER(void, pfnVBVAUpdateEnd,(PPDMIDISPLAYCONNECTOR pInterface, unsigned uScreenId, int32_t x, int32_t y,
962 uint32_t cx, uint32_t cy));
963
964 /**
965 * Resize the display.
966 * This is called when the resolution changes. This usually happens on
967 * request from the guest os, but may also happen as the result of a reset.
968 * If the callback returns VINF_VGA_RESIZE_IN_PROGRESS, the caller (VGA device)
969 * must not access the connector and return.
970 *
971 * @todo Merge with pfnResize.
972 *
973 * @returns VINF_SUCCESS if the framebuffer resize was completed,
974 * VINF_VGA_RESIZE_IN_PROGRESS if resize takes time and not yet finished.
975 * @param pInterface Pointer to this interface.
976 * @param pView The description of VRAM block for this screen.
977 * @param pScreen The data of screen being resized.
978 * @param pvVRAM Address of the guest VRAM.
979 * @param fResetInputMapping Whether to reset the absolute pointing device to screen position co-ordinate
980 * mapping. Needed for real resizes, as the caller on the guest may not know how
981 * to set the mapping. Not wanted when we restore a saved state and are resetting
982 * the mode.
983 * @thread if render thread mode is on (fRenderThreadMode that was passed to pfnVBVAEnable is TRUE) - the render thread pfnVBVAEnable was called in,
984 * otherwise - the emulation thread.
985 */
986 DECLR3CALLBACKMEMBER(int, pfnVBVAResize,(PPDMIDISPLAYCONNECTOR pInterface, PCVBVAINFOVIEW pView, PCVBVAINFOSCREEN pScreen,
987 void *pvVRAM, bool fResetInputMapping));
988
989 /**
990 * Update the pointer shape.
991 * This is called when the mouse pointer shape changes. The new shape
992 * is passed as a caller allocated buffer that will be freed after returning
993 *
994 * @param pInterface Pointer to this interface.
995 * @param fVisible Visibility indicator (if false, the other parameters are undefined).
996 * @param fAlpha Flag whether alpha channel is being passed.
997 * @param xHot Pointer hot spot x coordinate.
998 * @param yHot Pointer hot spot y coordinate.
999 * @param cx Pointer width in pixels.
1000 * @param cy Pointer height in pixels.
1001 * @param pvShape New shape buffer.
1002 * @thread The emulation thread.
1003 */
1004 DECLR3CALLBACKMEMBER(int, pfnVBVAMousePointerShape,(PPDMIDISPLAYCONNECTOR pInterface, bool fVisible, bool fAlpha,
1005 uint32_t xHot, uint32_t yHot, uint32_t cx, uint32_t cy,
1006 const void *pvShape));
1007
1008 /**
1009 * The guest capabilities were updated.
1010 *
1011 * @param pInterface Pointer to this interface.
1012 * @param fCapabilities The new capability flag state.
1013 * @thread The emulation thread.
1014 */
1015 DECLR3CALLBACKMEMBER(void, pfnVBVAGuestCapabilityUpdate,(PPDMIDISPLAYCONNECTOR pInterface, uint32_t fCapabilities));
1016
1017 /** Read-only attributes.
1018 * For preformance reasons some readonly attributes are kept in the interface.
1019 * We trust the interface users to respect the readonlyness of these.
1020 * @{
1021 */
1022 /** Pointer to the display data buffer. */
1023 uint8_t *pbData;
1024 /** Size of a scanline in the data buffer. */
1025 uint32_t cbScanline;
1026 /** The color depth (in bits) the graphics card is supposed to provide. */
1027 uint32_t cBits;
1028 /** The display width. */
1029 uint32_t cx;
1030 /** The display height. */
1031 uint32_t cy;
1032 /** @} */
1033
1034 /**
1035 * The guest display input mapping rectangle was updated.
1036 *
1037 * @param pInterface Pointer to this interface.
1038 * @param xOrigin Upper left X co-ordinate relative to the first screen.
1039 * @param yOrigin Upper left Y co-ordinate relative to the first screen.
1040 * @param cx Rectangle width.
1041 * @param cy Rectangle height.
1042 * @thread The emulation thread.
1043 */
1044 DECLR3CALLBACKMEMBER(void, pfnVBVAInputMappingUpdate,(PPDMIDISPLAYCONNECTOR pInterface, int32_t xOrigin, int32_t yOrigin, uint32_t cx, uint32_t cy));
1045
1046 /**
1047 * The guest is reporting the requested location of the host pointer.
1048 *
1049 * @param pInterface Pointer to this interface.
1050 * @param fFlags VBVA_CURSOR_*
1051 * @param uScreenId The screen to which X and Y are relative if VBVA_CURSOR_SCREEN_RELATIVE is set.
1052 * @param x Cursor X offset.
1053 * @param y Cursor Y offset.
1054 * @thread The emulation thread.
1055 */
1056 DECLR3CALLBACKMEMBER(void, pfnVBVAReportCursorPosition,(PPDMIDISPLAYCONNECTOR pInterface, uint32_t fFlags, uint32_t uScreen, uint32_t x, uint32_t y));
1057
1058 /**
1059 * Process the graphics device HW Acceleration command.
1060 *
1061 * @param pInterface Pointer to this interface.
1062 * @param p3DNotify Acceleration Command to be processed.
1063 * @thread The graphics device thread: FIFO for the VMSVGA device.
1064 */
1065 DECLR3CALLBACKMEMBER(int, pfn3DNotifyProcess,(PPDMIDISPLAYCONNECTOR pInterface,
1066 VBOX3DNOTIFY *p3DNotify));
1067} PDMIDISPLAYCONNECTOR;
1068/** PDMIDISPLAYCONNECTOR interface ID. */
1069#define PDMIDISPLAYCONNECTOR_IID "cdd562e4-8030-11ea-8d40-bbc8e146c565"
1070
1071
1072/** Pointer to a secret key interface. */
1073typedef struct PDMISECKEY *PPDMISECKEY;
1074
1075/**
1076 * Secret key interface to retrieve secret keys.
1077 */
1078typedef struct PDMISECKEY
1079{
1080 /**
1081 * Retains a key identified by the ID. The caller will only hold a reference
1082 * to the key and must not modify the key buffer in any way.
1083 *
1084 * @returns VBox status code.
1085 * @param pInterface Pointer to this interface.
1086 * @param pszId The alias/id for the key to retrieve.
1087 * @param ppbKey Where to store the pointer to the key buffer on success.
1088 * @param pcbKey Where to store the size of the key in bytes on success.
1089 */
1090 DECLR3CALLBACKMEMBER(int, pfnKeyRetain, (PPDMISECKEY pInterface, const char *pszId,
1091 const uint8_t **pbKey, size_t *pcbKey));
1092
1093 /**
1094 * Releases one reference of the key identified by the given identifier.
1095 * The caller must not access the key buffer after calling this operation.
1096 *
1097 * @returns VBox status code.
1098 * @param pInterface Pointer to this interface.
1099 * @param pszId The alias/id for the key to release.
1100 *
1101 * @note: It is advised to release the key whenever it is not used anymore so the entity
1102 * storing the key can do anything to make retrieving the key from memory more
1103 * difficult like scrambling the memory buffer for instance.
1104 */
1105 DECLR3CALLBACKMEMBER(int, pfnKeyRelease, (PPDMISECKEY pInterface, const char *pszId));
1106
1107 /**
1108 * Retains a password identified by the ID. The caller will only hold a reference
1109 * to the password and must not modify the buffer in any way.
1110 *
1111 * @returns VBox status code.
1112 * @param pInterface Pointer to this interface.
1113 * @param pszId The alias/id for the password to retrieve.
1114 * @param ppszPassword Where to store the pointer to the password on success.
1115 */
1116 DECLR3CALLBACKMEMBER(int, pfnPasswordRetain, (PPDMISECKEY pInterface, const char *pszId,
1117 const char **ppszPassword));
1118
1119 /**
1120 * Releases one reference of the password identified by the given identifier.
1121 * The caller must not access the password after calling this operation.
1122 *
1123 * @returns VBox status code.
1124 * @param pInterface Pointer to this interface.
1125 * @param pszId The alias/id for the password to release.
1126 *
1127 * @note: It is advised to release the password whenever it is not used anymore so the entity
1128 * storing the password can do anything to make retrieving the password from memory more
1129 * difficult like scrambling the memory buffer for instance.
1130 */
1131 DECLR3CALLBACKMEMBER(int, pfnPasswordRelease, (PPDMISECKEY pInterface, const char *pszId));
1132} PDMISECKEY;
1133/** PDMISECKEY interface ID. */
1134#define PDMISECKEY_IID "3d698355-d995-453d-960f-31566a891df2"
1135
1136/** Pointer to a secret key helper interface. */
1137typedef struct PDMISECKEYHLP *PPDMISECKEYHLP;
1138
1139/**
1140 * Secret key helper interface for non critical functionality.
1141 */
1142typedef struct PDMISECKEYHLP
1143{
1144 /**
1145 * Notifies the interface provider that a key couldn't be retrieved from the key store.
1146 *
1147 * @returns VBox status code.
1148 * @param pInterface Pointer to this interface.
1149 */
1150 DECLR3CALLBACKMEMBER(int, pfnKeyMissingNotify, (PPDMISECKEYHLP pInterface));
1151
1152} PDMISECKEYHLP;
1153/** PDMISECKEY interface ID. */
1154#define PDMISECKEYHLP_IID "7be96168-4156-40ac-86d2-3073bf8b318e"
1155
1156
1157/** Pointer to a stream interface. */
1158typedef struct PDMISTREAM *PPDMISTREAM;
1159/**
1160 * Stream interface (up).
1161 * Makes up the foundation for PDMICHARCONNECTOR. No pair interface.
1162 */
1163typedef struct PDMISTREAM
1164{
1165 /**
1166 * Polls for the specified events.
1167 *
1168 * @returns VBox status code.
1169 * @retval VERR_INTERRUPTED if the poll was interrupted.
1170 * @retval VERR_TIMEOUT if the maximum waiting time was reached.
1171 * @param pInterface Pointer to the interface structure containing the called function pointer.
1172 * @param fEvts The events to poll for, see RTPOLL_EVT_XXX.
1173 * @param pfEvts Where to return details about the events that occurred.
1174 * @param cMillies Number of milliseconds to wait. Use
1175 * RT_INDEFINITE_WAIT to wait for ever.
1176 */
1177 DECLR3CALLBACKMEMBER(int, pfnPoll,(PPDMISTREAM pInterface, uint32_t fEvts, uint32_t *pfEvts, RTMSINTERVAL cMillies));
1178
1179 /**
1180 * Interrupts the current poll call.
1181 *
1182 * @returns VBox status code.
1183 * @param pInterface Pointer to the interface structure containing the called function pointer.
1184 */
1185 DECLR3CALLBACKMEMBER(int, pfnPollInterrupt,(PPDMISTREAM pInterface));
1186
1187 /**
1188 * Read bits.
1189 *
1190 * @returns VBox status code.
1191 * @param pInterface Pointer to the interface structure containing the called function pointer.
1192 * @param pvBuf Where to store the read bits.
1193 * @param pcbRead Number of bytes to read/bytes actually read.
1194 * @thread Any thread.
1195 *
1196 * @note: This is non blocking, use the poll callback to block when there is nothing to read.
1197 */
1198 DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMISTREAM pInterface, void *pvBuf, size_t *pcbRead));
1199
1200 /**
1201 * Write bits.
1202 *
1203 * @returns VBox status code.
1204 * @param pInterface Pointer to the interface structure containing the called function pointer.
1205 * @param pvBuf Where to store the write bits.
1206 * @param pcbWrite Number of bytes to write/bytes actually written.
1207 * @thread Any thread.
1208 *
1209 * @note: This is non blocking, use the poll callback to block until there is room to write.
1210 */
1211 DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMISTREAM pInterface, const void *pvBuf, size_t *pcbWrite));
1212} PDMISTREAM;
1213/** PDMISTREAM interface ID. */
1214#define PDMISTREAM_IID "f9bd1ba6-c134-44cc-8259-febe14393952"
1215
1216
1217/** Mode of the parallel port */
1218typedef enum PDMPARALLELPORTMODE
1219{
1220 /** First invalid mode. */
1221 PDM_PARALLEL_PORT_MODE_INVALID = 0,
1222 /** SPP (Compatibility mode). */
1223 PDM_PARALLEL_PORT_MODE_SPP,
1224 /** EPP Data mode. */
1225 PDM_PARALLEL_PORT_MODE_EPP_DATA,
1226 /** EPP Address mode. */
1227 PDM_PARALLEL_PORT_MODE_EPP_ADDR,
1228 /** ECP mode (not implemented yet). */
1229 PDM_PARALLEL_PORT_MODE_ECP,
1230 /** 32bit hack. */
1231 PDM_PARALLEL_PORT_MODE_32BIT_HACK = 0x7fffffff
1232} PDMPARALLELPORTMODE;
1233
1234/** Pointer to a host parallel port interface. */
1235typedef struct PDMIHOSTPARALLELPORT *PPDMIHOSTPARALLELPORT;
1236/**
1237 * Host parallel port interface (down).
1238 * Pair with PDMIHOSTPARALLELCONNECTOR.
1239 */
1240typedef struct PDMIHOSTPARALLELPORT
1241{
1242 /**
1243 * Notify device/driver that an interrupt has occurred.
1244 *
1245 * @returns VBox status code.
1246 * @param pInterface Pointer to the interface structure containing the called function pointer.
1247 * @thread Any thread.
1248 */
1249 DECLR3CALLBACKMEMBER(int, pfnNotifyInterrupt,(PPDMIHOSTPARALLELPORT pInterface));
1250} PDMIHOSTPARALLELPORT;
1251/** PDMIHOSTPARALLELPORT interface ID. */
1252#define PDMIHOSTPARALLELPORT_IID "f24b8668-e7f6-4eaa-a14c-4aa2a5f7048e"
1253
1254
1255
1256/** Pointer to a Host Parallel connector interface. */
1257typedef struct PDMIHOSTPARALLELCONNECTOR *PPDMIHOSTPARALLELCONNECTOR;
1258/**
1259 * Host parallel connector interface (up).
1260 * Pair with PDMIHOSTPARALLELPORT.
1261 */
1262typedef struct PDMIHOSTPARALLELCONNECTOR
1263{
1264 /**
1265 * Write bits.
1266 *
1267 * @returns VBox status code.
1268 * @param pInterface Pointer to the interface structure containing the called function pointer.
1269 * @param pvBuf Where to store the write bits.
1270 * @param cbWrite Number of bytes to write.
1271 * @param enmMode Mode to write the data.
1272 * @thread Any thread.
1273 * @todo r=klaus cbWrite only defines buffer length, method needs a way top return actually written amount of data.
1274 */
1275 DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMIHOSTPARALLELCONNECTOR pInterface, const void *pvBuf,
1276 size_t cbWrite, PDMPARALLELPORTMODE enmMode));
1277
1278 /**
1279 * Read bits.
1280 *
1281 * @returns VBox status code.
1282 * @param pInterface Pointer to the interface structure containing the called function pointer.
1283 * @param pvBuf Where to store the read bits.
1284 * @param cbRead Number of bytes to read.
1285 * @param enmMode Mode to read the data.
1286 * @thread Any thread.
1287 * @todo r=klaus cbRead only defines buffer length, method needs a way top return actually read amount of data.
1288 */
1289 DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMIHOSTPARALLELCONNECTOR pInterface, void *pvBuf,
1290 size_t cbRead, PDMPARALLELPORTMODE enmMode));
1291
1292 /**
1293 * Set data direction of the port (forward/reverse).
1294 *
1295 * @returns VBox status code.
1296 * @param pInterface Pointer to the interface structure containing the called function pointer.
1297 * @param fForward Flag whether to indicate whether the port is operated in forward or reverse mode.
1298 * @thread Any thread.
1299 */
1300 DECLR3CALLBACKMEMBER(int, pfnSetPortDirection,(PPDMIHOSTPARALLELCONNECTOR pInterface, bool fForward));
1301
1302 /**
1303 * Write control register bits.
1304 *
1305 * @returns VBox status code.
1306 * @param pInterface Pointer to the interface structure containing the called function pointer.
1307 * @param fReg The new control register value.
1308 * @thread Any thread.
1309 */
1310 DECLR3CALLBACKMEMBER(int, pfnWriteControl,(PPDMIHOSTPARALLELCONNECTOR pInterface, uint8_t fReg));
1311
1312 /**
1313 * Read control register bits.
1314 *
1315 * @returns VBox status code.
1316 * @param pInterface Pointer to the interface structure containing the called function pointer.
1317 * @param pfReg Where to store the control register bits.
1318 * @thread Any thread.
1319 */
1320 DECLR3CALLBACKMEMBER(int, pfnReadControl,(PPDMIHOSTPARALLELCONNECTOR pInterface, uint8_t *pfReg));
1321
1322 /**
1323 * Read status register bits.
1324 *
1325 * @returns VBox status code.
1326 * @param pInterface Pointer to the interface structure containing the called function pointer.
1327 * @param pfReg Where to store the status register bits.
1328 * @thread Any thread.
1329 */
1330 DECLR3CALLBACKMEMBER(int, pfnReadStatus,(PPDMIHOSTPARALLELCONNECTOR pInterface, uint8_t *pfReg));
1331
1332} PDMIHOSTPARALLELCONNECTOR;
1333/** PDMIHOSTPARALLELCONNECTOR interface ID. */
1334#define PDMIHOSTPARALLELCONNECTOR_IID "7c532602-7438-4fbc-9265-349d9f0415f9"
1335
1336
1337/** ACPI power source identifier */
1338typedef enum PDMACPIPOWERSOURCE
1339{
1340 PDM_ACPI_POWER_SOURCE_UNKNOWN = 0,
1341 PDM_ACPI_POWER_SOURCE_OUTLET,
1342 PDM_ACPI_POWER_SOURCE_BATTERY
1343} PDMACPIPOWERSOURCE;
1344/** Pointer to ACPI battery state. */
1345typedef PDMACPIPOWERSOURCE *PPDMACPIPOWERSOURCE;
1346
1347/** ACPI battey capacity */
1348typedef enum PDMACPIBATCAPACITY
1349{
1350 PDM_ACPI_BAT_CAPACITY_MIN = 0,
1351 PDM_ACPI_BAT_CAPACITY_MAX = 100,
1352 PDM_ACPI_BAT_CAPACITY_UNKNOWN = 255
1353} PDMACPIBATCAPACITY;
1354/** Pointer to ACPI battery capacity. */
1355typedef PDMACPIBATCAPACITY *PPDMACPIBATCAPACITY;
1356
1357/** ACPI battery state. See ACPI 3.0 spec '_BST (Battery Status)' */
1358typedef enum PDMACPIBATSTATE
1359{
1360 PDM_ACPI_BAT_STATE_CHARGED = 0x00,
1361 PDM_ACPI_BAT_STATE_DISCHARGING = 0x01,
1362 PDM_ACPI_BAT_STATE_CHARGING = 0x02,
1363 PDM_ACPI_BAT_STATE_CRITICAL = 0x04
1364} PDMACPIBATSTATE;
1365/** Pointer to ACPI battery state. */
1366typedef PDMACPIBATSTATE *PPDMACPIBATSTATE;
1367
1368/** Pointer to an ACPI port interface. */
1369typedef struct PDMIACPIPORT *PPDMIACPIPORT;
1370/**
1371 * ACPI port interface (down). Used by both the ACPI driver and (grumble) main.
1372 * Pair with PDMIACPICONNECTOR.
1373 */
1374typedef struct PDMIACPIPORT
1375{
1376 /**
1377 * Send an ACPI power off event.
1378 *
1379 * @returns VBox status code
1380 * @param pInterface Pointer to the interface structure containing the called function pointer.
1381 */
1382 DECLR3CALLBACKMEMBER(int, pfnPowerButtonPress,(PPDMIACPIPORT pInterface));
1383
1384 /**
1385 * Send an ACPI sleep button event.
1386 *
1387 * @returns VBox status code
1388 * @param pInterface Pointer to the interface structure containing the called function pointer.
1389 */
1390 DECLR3CALLBACKMEMBER(int, pfnSleepButtonPress,(PPDMIACPIPORT pInterface));
1391
1392 /**
1393 * Check if the last power button event was handled by the guest.
1394 *
1395 * @returns VBox status code
1396 * @param pInterface Pointer to the interface structure containing the called function pointer.
1397 * @param pfHandled Is set to true if the last power button event was handled, false otherwise.
1398 */
1399 DECLR3CALLBACKMEMBER(int, pfnGetPowerButtonHandled,(PPDMIACPIPORT pInterface, bool *pfHandled));
1400
1401 /**
1402 * Check if the guest entered the ACPI mode.
1403 *
1404 * @returns VBox status code
1405 * @param pInterface Pointer to the interface structure containing the called function pointer.
1406 * @param pfEntered Is set to true if the guest entered the ACPI mode, false otherwise.
1407 */
1408 DECLR3CALLBACKMEMBER(int, pfnGetGuestEnteredACPIMode,(PPDMIACPIPORT pInterface, bool *pfEntered));
1409
1410 /**
1411 * Check if the given CPU is still locked by the guest.
1412 *
1413 * @returns VBox status code
1414 * @param pInterface Pointer to the interface structure containing the called function pointer.
1415 * @param uCpu The CPU to check for.
1416 * @param pfLocked Is set to true if the CPU is still locked by the guest, false otherwise.
1417 */
1418 DECLR3CALLBACKMEMBER(int, pfnGetCpuStatus,(PPDMIACPIPORT pInterface, unsigned uCpu, bool *pfLocked));
1419
1420 /**
1421 * Send an ACPI monitor hot-plug event.
1422 *
1423 * @returns VBox status code
1424 * @param pInterface Pointer to the interface structure containing
1425 * the called function pointer.
1426 */
1427 DECLR3CALLBACKMEMBER(int, pfnMonitorHotPlugEvent,(PPDMIACPIPORT pInterface));
1428
1429 /**
1430 * Send a battery status change event.
1431 *
1432 * @returns VBox status code
1433 * @param pInterface Pointer to the interface structure containing
1434 * the called function pointer.
1435 */
1436 DECLR3CALLBACKMEMBER(int, pfnBatteryStatusChangeEvent,(PPDMIACPIPORT pInterface));
1437} PDMIACPIPORT;
1438/** PDMIACPIPORT interface ID. */
1439#define PDMIACPIPORT_IID "974cb8fb-7fda-408c-f9b4-7ff4e3b2a699"
1440
1441
1442/** Pointer to an ACPI connector interface. */
1443typedef struct PDMIACPICONNECTOR *PPDMIACPICONNECTOR;
1444/**
1445 * ACPI connector interface (up).
1446 * Pair with PDMIACPIPORT.
1447 */
1448typedef struct PDMIACPICONNECTOR
1449{
1450 /**
1451 * Get the current power source of the host system.
1452 *
1453 * @returns VBox status code
1454 * @param pInterface Pointer to the interface structure containing the called function pointer.
1455 * @param penmPowerSource Pointer to the power source result variable.
1456 */
1457 DECLR3CALLBACKMEMBER(int, pfnQueryPowerSource,(PPDMIACPICONNECTOR, PPDMACPIPOWERSOURCE penmPowerSource));
1458
1459 /**
1460 * Query the current battery status of the host system.
1461 *
1462 * @returns VBox status code?
1463 * @param pInterface Pointer to the interface structure containing the called function pointer.
1464 * @param pfPresent Is set to true if battery is present, false otherwise.
1465 * @param penmRemainingCapacity Pointer to the battery remaining capacity (0 - 100 or 255 for unknown).
1466 * @param penmBatteryState Pointer to the battery status.
1467 * @param pu32PresentRate Pointer to the present rate (0..1000 of the total capacity).
1468 */
1469 DECLR3CALLBACKMEMBER(int, pfnQueryBatteryStatus,(PPDMIACPICONNECTOR, bool *pfPresent, PPDMACPIBATCAPACITY penmRemainingCapacity,
1470 PPDMACPIBATSTATE penmBatteryState, uint32_t *pu32PresentRate));
1471} PDMIACPICONNECTOR;
1472/** PDMIACPICONNECTOR interface ID. */
1473#define PDMIACPICONNECTOR_IID "5f14bf8d-1edf-4e3a-a1e1-cca9fd08e359"
1474
1475struct VMMDevDisplayDef;
1476
1477/** Pointer to a VMMDevice port interface. */
1478typedef struct PDMIVMMDEVPORT *PPDMIVMMDEVPORT;
1479/**
1480 * VMMDevice port interface (down).
1481 * Pair with PDMIVMMDEVCONNECTOR.
1482 */
1483typedef struct PDMIVMMDEVPORT
1484{
1485 /**
1486 * Return the current absolute mouse position in pixels
1487 *
1488 * @returns VBox status code
1489 * @param pInterface Pointer to the interface structure containing the called function pointer.
1490 * @param pxAbs Pointer of result value, can be NULL
1491 * @param pyAbs Pointer of result value, can be NULL
1492 */
1493 DECLR3CALLBACKMEMBER(int, pfnQueryAbsoluteMouse,(PPDMIVMMDEVPORT pInterface, int32_t *pxAbs, int32_t *pyAbs));
1494
1495 /**
1496 * Set the new absolute mouse position in pixels
1497 *
1498 * @returns VBox status code
1499 * @param pInterface Pointer to the interface structure containing the called function pointer.
1500 * @param xAbs New absolute X position
1501 * @param yAbs New absolute Y position
1502 */
1503 DECLR3CALLBACKMEMBER(int, pfnSetAbsoluteMouse,(PPDMIVMMDEVPORT pInterface, int32_t xAbs, int32_t yAbs));
1504
1505 /**
1506 * Return the current mouse capability flags
1507 *
1508 * @returns VBox status code
1509 * @param pInterface Pointer to the interface structure containing the called function pointer.
1510 * @param pfCapabilities Pointer of result value
1511 */
1512 DECLR3CALLBACKMEMBER(int, pfnQueryMouseCapabilities,(PPDMIVMMDEVPORT pInterface, uint32_t *pfCapabilities));
1513
1514 /**
1515 * Set the current mouse capability flag (host side)
1516 *
1517 * @returns VBox status code
1518 * @param pInterface Pointer to the interface structure containing the called function pointer.
1519 * @param fCapsAdded Mask of capabilities to add to the flag
1520 * @param fCapsRemoved Mask of capabilities to remove from the flag
1521 */
1522 DECLR3CALLBACKMEMBER(int, pfnUpdateMouseCapabilities,(PPDMIVMMDEVPORT pInterface, uint32_t fCapsAdded, uint32_t fCapsRemoved));
1523
1524 /**
1525 * Issue a display resolution change request.
1526 *
1527 * Note that there can only one request in the queue and that in case the guest does
1528 * not process it, issuing another request will overwrite the previous.
1529 *
1530 * @returns VBox status code
1531 * @param pInterface Pointer to the interface structure containing the called function pointer.
1532 * @param cDisplays Number of displays. Can be either 1 or the number of VM virtual monitors.
1533 * @param paDisplays Definitions of guest screens to be applied. See VMMDev.h
1534 * @param fForce Whether to deliver the request to the guest even if the guest has
1535 * the requested resolution already.
1536 * @param fMayNotify Whether to send a hotplug notification to the guest if appropriate.
1537 */
1538 DECLR3CALLBACKMEMBER(int, pfnRequestDisplayChange,(PPDMIVMMDEVPORT pInterface, uint32_t cDisplays,
1539 struct VMMDevDisplayDef const *paDisplays, bool fForce, bool fMayNotify));
1540
1541 /**
1542 * Pass credentials to guest.
1543 *
1544 * Note that there can only be one set of credentials and the guest may or may not
1545 * query them and may do whatever it wants with them.
1546 *
1547 * @returns VBox status code.
1548 * @param pInterface Pointer to the interface structure containing the called function pointer.
1549 * @param pszUsername User name, may be empty (UTF-8).
1550 * @param pszPassword Password, may be empty (UTF-8).
1551 * @param pszDomain Domain name, may be empty (UTF-8).
1552 * @param fFlags VMMDEV_SETCREDENTIALS_*.
1553 */
1554 DECLR3CALLBACKMEMBER(int, pfnSetCredentials,(PPDMIVMMDEVPORT pInterface, const char *pszUsername,
1555 const char *pszPassword, const char *pszDomain,
1556 uint32_t fFlags));
1557
1558 /**
1559 * Notify the driver about a VBVA status change.
1560 *
1561 * @returns Nothing. Because it is informational callback.
1562 * @param pInterface Pointer to the interface structure containing the called function pointer.
1563 * @param fEnabled Current VBVA status.
1564 */
1565 DECLR3CALLBACKMEMBER(void, pfnVBVAChange, (PPDMIVMMDEVPORT pInterface, bool fEnabled));
1566
1567 /**
1568 * Issue a seamless mode change request.
1569 *
1570 * Note that there can only one request in the queue and that in case the guest does
1571 * not process it, issuing another request will overwrite the previous.
1572 *
1573 * @returns VBox status code
1574 * @param pInterface Pointer to the interface structure containing the called function pointer.
1575 * @param fEnabled Seamless mode enabled or not
1576 */
1577 DECLR3CALLBACKMEMBER(int, pfnRequestSeamlessChange,(PPDMIVMMDEVPORT pInterface, bool fEnabled));
1578
1579 /**
1580 * Issue a memory balloon change request.
1581 *
1582 * Note that there can only one request in the queue and that in case the guest does
1583 * not process it, issuing another request will overwrite the previous.
1584 *
1585 * @returns VBox status code
1586 * @param pInterface Pointer to the interface structure containing the called function pointer.
1587 * @param cMbBalloon Balloon size in megabytes
1588 */
1589 DECLR3CALLBACKMEMBER(int, pfnSetMemoryBalloon,(PPDMIVMMDEVPORT pInterface, uint32_t cMbBalloon));
1590
1591 /**
1592 * Issue a statistcs interval change request.
1593 *
1594 * Note that there can only one request in the queue and that in case the guest does
1595 * not process it, issuing another request will overwrite the previous.
1596 *
1597 * @returns VBox status code
1598 * @param pInterface Pointer to the interface structure containing the called function pointer.
1599 * @param cSecsStatInterval Statistics query interval in seconds
1600 * (0=disable).
1601 */
1602 DECLR3CALLBACKMEMBER(int, pfnSetStatisticsInterval,(PPDMIVMMDEVPORT pInterface, uint32_t cSecsStatInterval));
1603
1604 /**
1605 * Notify the guest about a VRDP status change.
1606 *
1607 * @returns VBox status code
1608 * @param pInterface Pointer to the interface structure containing the called function pointer.
1609 * @param fVRDPEnabled Current VRDP status.
1610 * @param uVRDPExperienceLevel Which visual effects to be disabled in
1611 * the guest.
1612 */
1613 DECLR3CALLBACKMEMBER(int, pfnVRDPChange, (PPDMIVMMDEVPORT pInterface, bool fVRDPEnabled, uint32_t uVRDPExperienceLevel));
1614
1615 /**
1616 * Notify the guest of CPU hot-unplug event.
1617 *
1618 * @returns VBox status code
1619 * @param pInterface Pointer to the interface structure containing the called function pointer.
1620 * @param idCpuCore The core id of the CPU to remove.
1621 * @param idCpuPackage The package id of the CPU to remove.
1622 */
1623 DECLR3CALLBACKMEMBER(int, pfnCpuHotUnplug, (PPDMIVMMDEVPORT pInterface, uint32_t idCpuCore, uint32_t idCpuPackage));
1624
1625 /**
1626 * Notify the guest of CPU hot-plug event.
1627 *
1628 * @returns VBox status code
1629 * @param pInterface Pointer to the interface structure containing the called function pointer.
1630 * @param idCpuCore The core id of the CPU to add.
1631 * @param idCpuPackage The package id of the CPU to add.
1632 */
1633 DECLR3CALLBACKMEMBER(int, pfnCpuHotPlug, (PPDMIVMMDEVPORT pInterface, uint32_t idCpuCore, uint32_t idCpuPackage));
1634
1635} PDMIVMMDEVPORT;
1636/** PDMIVMMDEVPORT interface ID. */
1637#define PDMIVMMDEVPORT_IID "9e004f1a-875d-11e9-a673-c77c30f53623"
1638
1639
1640/** Pointer to a HPET legacy notification interface. */
1641typedef struct PDMIHPETLEGACYNOTIFY *PPDMIHPETLEGACYNOTIFY;
1642/**
1643 * HPET legacy notification interface.
1644 */
1645typedef struct PDMIHPETLEGACYNOTIFY
1646{
1647 /**
1648 * Notify about change of HPET legacy mode.
1649 *
1650 * @param pInterface Pointer to the interface structure containing the
1651 * called function pointer.
1652 * @param fActivated If HPET legacy mode is activated (@c true) or
1653 * deactivated (@c false).
1654 */
1655 DECLR3CALLBACKMEMBER(void, pfnModeChanged,(PPDMIHPETLEGACYNOTIFY pInterface, bool fActivated));
1656} PDMIHPETLEGACYNOTIFY;
1657/** PDMIHPETLEGACYNOTIFY interface ID. */
1658#define PDMIHPETLEGACYNOTIFY_IID "c9ada595-4b65-4311-8b21-b10498997774"
1659
1660
1661/** @name Flags for PDMIVMMDEVPORT::pfnSetCredentials.
1662 * @{ */
1663/** The guest should perform a logon with the credentials. */
1664#define VMMDEV_SETCREDENTIALS_GUESTLOGON RT_BIT(0)
1665/** The guest should prevent local logons. */
1666#define VMMDEV_SETCREDENTIALS_NOLOCALLOGON RT_BIT(1)
1667/** The guest should verify the credentials. */
1668#define VMMDEV_SETCREDENTIALS_JUDGE RT_BIT(15)
1669/** @} */
1670
1671/** Forward declaration of the guest information structure. */
1672struct VBoxGuestInfo;
1673/** Forward declaration of the guest information-2 structure. */
1674struct VBoxGuestInfo2;
1675/** Forward declaration of the guest statistics structure */
1676struct VBoxGuestStatistics;
1677/** Forward declaration of the guest status structure */
1678struct VBoxGuestStatus;
1679
1680/** Forward declaration of the video accelerator command memory. */
1681struct VBVAMEMORY;
1682/** Pointer to video accelerator command memory. */
1683typedef struct VBVAMEMORY *PVBVAMEMORY;
1684
1685/** Pointer to a VMMDev connector interface. */
1686typedef struct PDMIVMMDEVCONNECTOR *PPDMIVMMDEVCONNECTOR;
1687/**
1688 * VMMDev connector interface (up).
1689 * Pair with PDMIVMMDEVPORT.
1690 */
1691typedef struct PDMIVMMDEVCONNECTOR
1692{
1693 /**
1694 * Update guest facility status.
1695 *
1696 * Called in response to VMMDevReq_ReportGuestStatus, reset or state restore.
1697 *
1698 * @param pInterface Pointer to this interface.
1699 * @param uFacility The facility.
1700 * @param uStatus The status.
1701 * @param fFlags Flags assoicated with the update. Currently
1702 * reserved and should be ignored.
1703 * @param pTimeSpecTS Pointer to the timestamp of this report.
1704 * @thread The emulation thread.
1705 */
1706 DECLR3CALLBACKMEMBER(void, pfnUpdateGuestStatus,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t uFacility, uint16_t uStatus,
1707 uint32_t fFlags, PCRTTIMESPEC pTimeSpecTS));
1708
1709 /**
1710 * Updates a guest user state.
1711 *
1712 * Called in response to VMMDevReq_ReportGuestUserState.
1713 *
1714 * @param pInterface Pointer to this interface.
1715 * @param pszUser Guest user name to update status for.
1716 * @param pszDomain Domain the guest user is bound to. Optional.
1717 * @param uState New guest user state to notify host about.
1718 * @param pabDetails Pointer to optional state data.
1719 * @param cbDetails Size (in bytes) of optional state data.
1720 * @thread The emulation thread.
1721 */
1722 DECLR3CALLBACKMEMBER(void, pfnUpdateGuestUserState,(PPDMIVMMDEVCONNECTOR pInterface, const char *pszUser,
1723 const char *pszDomain, uint32_t uState,
1724 const uint8_t *pabDetails, uint32_t cbDetails));
1725
1726 /**
1727 * Reports the guest API and OS version.
1728 * Called whenever the Additions issue a guest info report request.
1729 *
1730 * @param pInterface Pointer to this interface.
1731 * @param pGuestInfo Pointer to guest information structure
1732 * @thread The emulation thread.
1733 */
1734 DECLR3CALLBACKMEMBER(void, pfnUpdateGuestInfo,(PPDMIVMMDEVCONNECTOR pInterface, const struct VBoxGuestInfo *pGuestInfo));
1735
1736 /**
1737 * Reports the detailed Guest Additions version.
1738 *
1739 * @param pInterface Pointer to this interface.
1740 * @param uFullVersion The guest additions version as a full version.
1741 * Use VBOX_FULL_VERSION_GET_MAJOR,
1742 * VBOX_FULL_VERSION_GET_MINOR and
1743 * VBOX_FULL_VERSION_GET_BUILD to access it.
1744 * (This will not be zero, so turn down the
1745 * paranoia level a notch.)
1746 * @param pszName Pointer to the sanitized version name. This can
1747 * be empty, but will not be NULL. If not empty,
1748 * it will contain a build type tag and/or a
1749 * publisher tag. If both, then they are separated
1750 * by an underscore (VBOX_VERSION_STRING fashion).
1751 * @param uRevision The SVN revision. Can be 0.
1752 * @param fFeatures Feature mask, currently none are defined.
1753 *
1754 * @thread The emulation thread.
1755 */
1756 DECLR3CALLBACKMEMBER(void, pfnUpdateGuestInfo2,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t uFullVersion,
1757 const char *pszName, uint32_t uRevision, uint32_t fFeatures));
1758
1759 /**
1760 * Update the guest additions capabilities.
1761 * This is called when the guest additions capabilities change. The new capabilities
1762 * are given and the connector should update its internal state.
1763 *
1764 * @param pInterface Pointer to this interface.
1765 * @param newCapabilities New capabilities.
1766 * @thread The emulation thread.
1767 */
1768 DECLR3CALLBACKMEMBER(void, pfnUpdateGuestCapabilities,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t newCapabilities));
1769
1770 /**
1771 * Update the mouse capabilities.
1772 * This is called when the mouse capabilities change. The new capabilities
1773 * are given and the connector should update its internal state.
1774 *
1775 * @param pInterface Pointer to this interface.
1776 * @param newCapabilities New capabilities.
1777 * @thread The emulation thread.
1778 */
1779 DECLR3CALLBACKMEMBER(void, pfnUpdateMouseCapabilities,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t newCapabilities));
1780
1781 /**
1782 * Update the pointer shape.
1783 * This is called when the mouse pointer shape changes. The new shape
1784 * is passed as a caller allocated buffer that will be freed after returning
1785 *
1786 * @param pInterface Pointer to this interface.
1787 * @param fVisible Visibility indicator (if false, the other parameters are undefined).
1788 * @param fAlpha Flag whether alpha channel is being passed.
1789 * @param xHot Pointer hot spot x coordinate.
1790 * @param yHot Pointer hot spot y coordinate.
1791 * @param x Pointer new x coordinate on screen.
1792 * @param y Pointer new y coordinate on screen.
1793 * @param cx Pointer width in pixels.
1794 * @param cy Pointer height in pixels.
1795 * @param cbScanline Size of one scanline in bytes.
1796 * @param pvShape New shape buffer.
1797 * @thread The emulation thread.
1798 */
1799 DECLR3CALLBACKMEMBER(void, pfnUpdatePointerShape,(PPDMIVMMDEVCONNECTOR pInterface, bool fVisible, bool fAlpha,
1800 uint32_t xHot, uint32_t yHot,
1801 uint32_t cx, uint32_t cy,
1802 void *pvShape));
1803
1804 /**
1805 * Enable or disable video acceleration on behalf of guest.
1806 *
1807 * @param pInterface Pointer to this interface.
1808 * @param fEnable Whether to enable acceleration.
1809 * @param pVbvaMemory Video accelerator memory.
1810
1811 * @return VBox rc. VINF_SUCCESS if VBVA was enabled.
1812 * @thread The emulation thread.
1813 */
1814 DECLR3CALLBACKMEMBER(int, pfnVideoAccelEnable,(PPDMIVMMDEVCONNECTOR pInterface, bool fEnable, PVBVAMEMORY pVbvaMemory));
1815
1816 /**
1817 * Force video queue processing.
1818 *
1819 * @param pInterface Pointer to this interface.
1820 * @thread The emulation thread.
1821 */
1822 DECLR3CALLBACKMEMBER(void, pfnVideoAccelFlush,(PPDMIVMMDEVCONNECTOR pInterface));
1823
1824 /**
1825 * Return whether the given video mode is supported/wanted by the host.
1826 *
1827 * @returns VBox status code
1828 * @param pInterface Pointer to this interface.
1829 * @param display The guest monitor, 0 for primary.
1830 * @param cy Video mode horizontal resolution in pixels.
1831 * @param cx Video mode vertical resolution in pixels.
1832 * @param cBits Video mode bits per pixel.
1833 * @param pfSupported Where to put the indicator for whether this mode is supported. (output)
1834 * @thread The emulation thread.
1835 */
1836 DECLR3CALLBACKMEMBER(int, pfnVideoModeSupported,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t display, uint32_t cx, uint32_t cy, uint32_t cBits, bool *pfSupported));
1837
1838 /**
1839 * Queries by how many pixels the height should be reduced when calculating video modes
1840 *
1841 * @returns VBox status code
1842 * @param pInterface Pointer to this interface.
1843 * @param pcyReduction Pointer to the result value.
1844 * @thread The emulation thread.
1845 */
1846 DECLR3CALLBACKMEMBER(int, pfnGetHeightReduction,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t *pcyReduction));
1847
1848 /**
1849 * Informs about a credentials judgement result from the guest.
1850 *
1851 * @returns VBox status code
1852 * @param pInterface Pointer to this interface.
1853 * @param fFlags Judgement result flags.
1854 * @thread The emulation thread.
1855 */
1856 DECLR3CALLBACKMEMBER(int, pfnSetCredentialsJudgementResult,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t fFlags));
1857
1858 /**
1859 * Set the visible region of the display
1860 *
1861 * @returns VBox status code.
1862 * @param pInterface Pointer to this interface.
1863 * @param cRect Number of rectangles in pRect
1864 * @param pRect Rectangle array
1865 * @thread The emulation thread.
1866 */
1867 DECLR3CALLBACKMEMBER(int, pfnSetVisibleRegion,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t cRect, PRTRECT pRect));
1868
1869 /**
1870 * Update monitor positions (offsets). Passing monitor positions from the guest to host
1871 * exclusively since vmwgfx fails to do so (thru FIFO).
1872 *
1873 * @returns VBox status code.
1874 * @param pInterface Pointer to this interface.
1875 * @param cPositions Number of monitor positions
1876 * @param pPosition Positions array
1877 * @thread The emulation thread.
1878 *
1879 * @remarks Is allowed to be NULL.
1880 */
1881 DECLR3CALLBACKMEMBER(int, pfnUpdateMonitorPositions,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t cPositions, PRTPOINT pPosition));
1882
1883 /**
1884 * Query the visible region of the display
1885 *
1886 * @returns VBox status code.
1887 * @param pInterface Pointer to this interface.
1888 * @param pcRects Where to return the number of rectangles in
1889 * paRects.
1890 * @param paRects Rectangle array (set to NULL to query the number
1891 * of rectangles)
1892 * @thread The emulation thread.
1893 */
1894 DECLR3CALLBACKMEMBER(int, pfnQueryVisibleRegion,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t *pcRects, PRTRECT paRects));
1895
1896 /**
1897 * Request the statistics interval
1898 *
1899 * @returns VBox status code.
1900 * @param pInterface Pointer to this interface.
1901 * @param pulInterval Pointer to interval in seconds
1902 * @thread The emulation thread.
1903 */
1904 DECLR3CALLBACKMEMBER(int, pfnQueryStatisticsInterval,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t *pulInterval));
1905
1906 /**
1907 * Report new guest statistics
1908 *
1909 * @returns VBox status code.
1910 * @param pInterface Pointer to this interface.
1911 * @param pGuestStats Guest statistics
1912 * @thread The emulation thread.
1913 */
1914 DECLR3CALLBACKMEMBER(int, pfnReportStatistics,(PPDMIVMMDEVCONNECTOR pInterface, struct VBoxGuestStatistics *pGuestStats));
1915
1916 /**
1917 * Query the current balloon size
1918 *
1919 * @returns VBox status code.
1920 * @param pInterface Pointer to this interface.
1921 * @param pcbBalloon Balloon size
1922 * @thread The emulation thread.
1923 */
1924 DECLR3CALLBACKMEMBER(int, pfnQueryBalloonSize,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t *pcbBalloon));
1925
1926 /**
1927 * Query the current page fusion setting
1928 *
1929 * @returns VBox status code.
1930 * @param pInterface Pointer to this interface.
1931 * @param pfPageFusionEnabled Pointer to boolean
1932 * @thread The emulation thread.
1933 */
1934 DECLR3CALLBACKMEMBER(int, pfnIsPageFusionEnabled,(PPDMIVMMDEVCONNECTOR pInterface, bool *pfPageFusionEnabled));
1935
1936} PDMIVMMDEVCONNECTOR;
1937/** PDMIVMMDEVCONNECTOR interface ID. */
1938#define PDMIVMMDEVCONNECTOR_IID "aff90240-a443-434e-9132-80c186ab97d4"
1939
1940
1941/**
1942 * Generic status LED core.
1943 * Note that a unit doesn't have to support all the indicators.
1944 */
1945typedef union PDMLEDCORE
1946{
1947 /** 32-bit view. */
1948 uint32_t volatile u32;
1949 /** Bit view. */
1950 struct
1951 {
1952 /** Reading/Receiving indicator. */
1953 uint32_t fReading : 1;
1954 /** Writing/Sending indicator. */
1955 uint32_t fWriting : 1;
1956 /** Busy indicator. */
1957 uint32_t fBusy : 1;
1958 /** Error indicator. */
1959 uint32_t fError : 1;
1960 } s;
1961} PDMLEDCORE;
1962
1963/** LED bit masks for the u32 view.
1964 * @{ */
1965/** Reading/Receiving indicator. */
1966#define PDMLED_READING RT_BIT(0)
1967/** Writing/Sending indicator. */
1968#define PDMLED_WRITING RT_BIT(1)
1969/** Busy indicator. */
1970#define PDMLED_BUSY RT_BIT(2)
1971/** Error indicator. */
1972#define PDMLED_ERROR RT_BIT(3)
1973/** @} */
1974
1975
1976/**
1977 * Generic status LED.
1978 * Note that a unit doesn't have to support all the indicators.
1979 */
1980typedef struct PDMLED
1981{
1982 /** Just a magic for sanity checking. */
1983 uint32_t u32Magic;
1984 uint32_t u32Alignment; /**< structure size alignment. */
1985 /** The actual LED status.
1986 * Only the device is allowed to change this. */
1987 PDMLEDCORE Actual;
1988 /** The asserted LED status which is cleared by the reader.
1989 * The device will assert the bits but never clear them.
1990 * The driver clears them as it sees fit. */
1991 PDMLEDCORE Asserted;
1992} PDMLED;
1993
1994/** Pointer to an LED. */
1995typedef PDMLED *PPDMLED;
1996/** Pointer to a const LED. */
1997typedef const PDMLED *PCPDMLED;
1998
1999/** Magic value for PDMLED::u32Magic. */
2000#define PDMLED_MAGIC UINT32_C(0x11335577)
2001
2002/** Pointer to an LED ports interface. */
2003typedef struct PDMILEDPORTS *PPDMILEDPORTS;
2004/**
2005 * Interface for exporting LEDs (down).
2006 * Pair with PDMILEDCONNECTORS.
2007 */
2008typedef struct PDMILEDPORTS
2009{
2010 /**
2011 * Gets the pointer to the status LED of a unit.
2012 *
2013 * @returns VBox status code.
2014 * @param pInterface Pointer to the interface structure containing the called function pointer.
2015 * @param iLUN The unit which status LED we desire.
2016 * @param ppLed Where to store the LED pointer.
2017 */
2018 DECLR3CALLBACKMEMBER(int, pfnQueryStatusLed,(PPDMILEDPORTS pInterface, unsigned iLUN, PPDMLED *ppLed));
2019
2020} PDMILEDPORTS;
2021/** PDMILEDPORTS interface ID. */
2022#define PDMILEDPORTS_IID "435e0cec-8549-4ca0-8c0d-98e52f1dc038"
2023
2024
2025/** Pointer to an LED connectors interface. */
2026typedef struct PDMILEDCONNECTORS *PPDMILEDCONNECTORS;
2027/**
2028 * Interface for reading LEDs (up).
2029 * Pair with PDMILEDPORTS.
2030 */
2031typedef struct PDMILEDCONNECTORS
2032{
2033 /**
2034 * Notification about a unit which have been changed.
2035 *
2036 * The driver must discard any pointers to data owned by
2037 * the unit and requery it.
2038 *
2039 * @param pInterface Pointer to the interface structure containing the called function pointer.
2040 * @param iLUN The unit number.
2041 */
2042 DECLR3CALLBACKMEMBER(void, pfnUnitChanged,(PPDMILEDCONNECTORS pInterface, unsigned iLUN));
2043} PDMILEDCONNECTORS;
2044/** PDMILEDCONNECTORS interface ID. */
2045#define PDMILEDCONNECTORS_IID "8ed63568-82a7-4193-b57b-db8085ac4495"
2046
2047
2048/** Pointer to a Media Notification interface. */
2049typedef struct PDMIMEDIANOTIFY *PPDMIMEDIANOTIFY;
2050/**
2051 * Interface for exporting Medium eject information (up). No interface pair.
2052 */
2053typedef struct PDMIMEDIANOTIFY
2054{
2055 /**
2056 * Signals that the medium was ejected.
2057 *
2058 * @returns VBox status code.
2059 * @param pInterface Pointer to the interface structure containing the called function pointer.
2060 * @param iLUN The unit which had the medium ejected.
2061 */
2062 DECLR3CALLBACKMEMBER(int, pfnEjected,(PPDMIMEDIANOTIFY pInterface, unsigned iLUN));
2063
2064} PDMIMEDIANOTIFY;
2065/** PDMIMEDIANOTIFY interface ID. */
2066#define PDMIMEDIANOTIFY_IID "fc22d53e-feb1-4a9c-b9fb-0a990a6ab288"
2067
2068
2069/** The special status unit number */
2070#define PDM_STATUS_LUN 999
2071
2072
2073#ifdef VBOX_WITH_HGCM
2074
2075/** Abstract HGCM command structure. Used only to define a typed pointer. */
2076struct VBOXHGCMCMD;
2077
2078/** Pointer to HGCM command structure. This pointer is unique and identifies
2079 * the command being processed. The pointer is passed to HGCM connector methods,
2080 * and must be passed back to HGCM port when command is completed.
2081 */
2082typedef struct VBOXHGCMCMD *PVBOXHGCMCMD;
2083
2084/** Pointer to a HGCM port interface. */
2085typedef struct PDMIHGCMPORT *PPDMIHGCMPORT;
2086/**
2087 * Host-Guest communication manager port interface (down). Normally implemented
2088 * by VMMDev.
2089 * Pair with PDMIHGCMCONNECTOR.
2090 */
2091typedef struct PDMIHGCMPORT
2092{
2093 /**
2094 * Notify the guest on a command completion.
2095 *
2096 * @returns VINF_SUCCESS or VERR_CANCELLED if the guest canceled the call.
2097 * @param pInterface Pointer to this interface.
2098 * @param rc The return code (VBox error code).
2099 * @param pCmd A pointer that identifies the completed command.
2100 */
2101 DECLR3CALLBACKMEMBER(int, pfnCompleted,(PPDMIHGCMPORT pInterface, int32_t rc, PVBOXHGCMCMD pCmd));
2102
2103 /**
2104 * Checks if @a pCmd was restored & resubmitted from saved state.
2105 *
2106 * @returns true if restored, false if not.
2107 * @param pInterface Pointer to this interface.
2108 * @param pCmd The command we're checking on.
2109 */
2110 DECLR3CALLBACKMEMBER(bool, pfnIsCmdRestored,(PPDMIHGCMPORT pInterface, PVBOXHGCMCMD pCmd));
2111
2112 /**
2113 * Checks if @a pCmd was cancelled.
2114 *
2115 * @returns true if cancelled, false if not.
2116 * @param pInterface Pointer to this interface.
2117 * @param pCmd The command we're checking on.
2118 */
2119 DECLR3CALLBACKMEMBER(bool, pfnIsCmdCancelled,(PPDMIHGCMPORT pInterface, PVBOXHGCMCMD pCmd));
2120
2121 /**
2122 * Gets the VMMDevRequestHeader::fRequestor value for @a pCmd.
2123 *
2124 * @returns The fRequestor value, VMMDEV_REQUESTOR_LEGACY if guest does not
2125 * support it, VMMDEV_REQUESTOR_LOWEST if invalid parameters.
2126 * @param pInterface Pointer to this interface.
2127 * @param pCmd The command we're in checking on.
2128 */
2129 DECLR3CALLBACKMEMBER(uint32_t, pfnGetRequestor,(PPDMIHGCMPORT pInterface, PVBOXHGCMCMD pCmd));
2130
2131 /**
2132 * Gets the VMMDevState::idSession value.
2133 *
2134 * @returns VMMDevState::idSession.
2135 * @param pInterface Pointer to this interface.
2136 */
2137 DECLR3CALLBACKMEMBER(uint64_t, pfnGetVMMDevSessionId,(PPDMIHGCMPORT pInterface));
2138
2139} PDMIHGCMPORT;
2140/** PDMIHGCMPORT interface ID. */
2141# define PDMIHGCMPORT_IID "28c0a201-68cd-4752-9404-bb42a0c09eb7"
2142
2143/* forward decl to hgvmsvc.h. */
2144struct VBOXHGCMSVCPARM;
2145/** Pointer to a HGCM service location structure. */
2146typedef struct HGCMSERVICELOCATION *PHGCMSERVICELOCATION;
2147/** Pointer to a HGCM connector interface. */
2148typedef struct PDMIHGCMCONNECTOR *PPDMIHGCMCONNECTOR;
2149/**
2150 * The Host-Guest communication manager connector interface (up). Normally
2151 * implemented by Main::VMMDevInterface.
2152 * Pair with PDMIHGCMPORT.
2153 */
2154typedef struct PDMIHGCMCONNECTOR
2155{
2156 /**
2157 * Locate a service and inform it about a client connection.
2158 *
2159 * @param pInterface Pointer to this interface.
2160 * @param pCmd A pointer that identifies the command.
2161 * @param pServiceLocation Pointer to the service location structure.
2162 * @param pu32ClientID Where to store the client id for the connection.
2163 * @return VBox status code.
2164 * @thread The emulation thread.
2165 */
2166 DECLR3CALLBACKMEMBER(int, pfnConnect,(PPDMIHGCMCONNECTOR pInterface, PVBOXHGCMCMD pCmd, PHGCMSERVICELOCATION pServiceLocation, uint32_t *pu32ClientID));
2167
2168 /**
2169 * Disconnect from service.
2170 *
2171 * @param pInterface Pointer to this interface.
2172 * @param pCmd A pointer that identifies the command.
2173 * @param u32ClientID The client id returned by the pfnConnect call.
2174 * @return VBox status code.
2175 * @thread The emulation thread.
2176 */
2177 DECLR3CALLBACKMEMBER(int, pfnDisconnect,(PPDMIHGCMCONNECTOR pInterface, PVBOXHGCMCMD pCmd, uint32_t u32ClientID));
2178
2179 /**
2180 * Process a guest issued command.
2181 *
2182 * @param pInterface Pointer to this interface.
2183 * @param pCmd A pointer that identifies the command.
2184 * @param u32ClientID The client id returned by the pfnConnect call.
2185 * @param u32Function Function to be performed by the service.
2186 * @param cParms Number of parameters in the array pointed to by paParams.
2187 * @param paParms Pointer to an array of parameters.
2188 * @param tsArrival The STAM_GET_TS() value when the request arrived.
2189 * @return VBox status code.
2190 * @thread The emulation thread.
2191 */
2192 DECLR3CALLBACKMEMBER(int, pfnCall,(PPDMIHGCMCONNECTOR pInterface, PVBOXHGCMCMD pCmd, uint32_t u32ClientID, uint32_t u32Function,
2193 uint32_t cParms, struct VBOXHGCMSVCPARM *paParms, uint64_t tsArrival));
2194
2195 /**
2196 * Notification about the guest cancelling a pending request.
2197 * @param pInterface Pointer to this interface.
2198 * @param pCmd A pointer that identifies the command.
2199 * @param idclient The client id returned by the pfnConnect call.
2200 */
2201 DECLR3CALLBACKMEMBER(void, pfnCancelled,(PPDMIHGCMCONNECTOR pInterface, PVBOXHGCMCMD pCmd, uint32_t idClient));
2202
2203} PDMIHGCMCONNECTOR;
2204/** PDMIHGCMCONNECTOR interface ID. */
2205# define PDMIHGCMCONNECTOR_IID "33cb5c91-6a4a-4ad9-3fec-d1f7d413c4a5"
2206
2207#endif /* VBOX_WITH_HGCM */
2208
2209
2210/** Pointer to a display VBVA callbacks interface. */
2211typedef struct PDMIDISPLAYVBVACALLBACKS *PPDMIDISPLAYVBVACALLBACKS;
2212/**
2213 * Display VBVA callbacks interface (up).
2214 */
2215typedef struct PDMIDISPLAYVBVACALLBACKS
2216{
2217
2218 /**
2219 * Informs guest about completion of processing the given Video HW Acceleration
2220 * command, does not wait for the guest to process the command.
2221 *
2222 * @returns ???
2223 * @param pInterface Pointer to this interface.
2224 * @param pCmd The Video HW Acceleration Command that was
2225 * completed.
2226 */
2227 DECLR3CALLBACKMEMBER(int, pfnVHWACommandCompleteAsync,(PPDMIDISPLAYVBVACALLBACKS pInterface,
2228 VBOXVHWACMD RT_UNTRUSTED_VOLATILE_GUEST *pCmd));
2229} PDMIDISPLAYVBVACALLBACKS;
2230/** PDMIDISPLAYVBVACALLBACKS */
2231#define PDMIDISPLAYVBVACALLBACKS_IID "37f34c9c-0491-47dc-a0b3-81697c44a416"
2232
2233/** Pointer to a PCI raw connector interface. */
2234typedef struct PDMIPCIRAWCONNECTOR *PPDMIPCIRAWCONNECTOR;
2235/**
2236 * PCI raw connector interface (up).
2237 */
2238typedef struct PDMIPCIRAWCONNECTOR
2239{
2240
2241 /**
2242 *
2243 */
2244 DECLR3CALLBACKMEMBER(int, pfnDeviceConstructComplete, (PPDMIPCIRAWCONNECTOR pInterface, const char *pcszName,
2245 uint32_t uHostPciAddress, uint32_t uGuestPciAddress,
2246 int rc));
2247
2248} PDMIPCIRAWCONNECTOR;
2249/** PDMIPCIRAWCONNECTOR interface ID. */
2250#define PDMIPCIRAWCONNECTOR_IID "14aa9c6c-8869-4782-9dfc-910071a6aebf"
2251
2252/** @} */
2253
2254RT_C_DECLS_END
2255
2256#endif /* !VBOX_INCLUDED_vmm_pdmifs_h */
Note: See TracBrowser for help on using the repository browser.

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