VirtualBox

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

Last change on this file was 101617, checked in by vboxsync, 7 months ago

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

© 2023 Oracle
Contact – Privacy policy – Terms of Use