VirtualBox

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

Last change on this file since 46933 was 46933, checked in by vboxsync, 12 years ago

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