VirtualBox

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

Last change on this file since 67937 was 65120, checked in by vboxsync, 8 years ago

Main: doxygen fixes

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

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