VirtualBox

source: vbox/trunk/include/VBox/pdmifs.h@ 28231

Last change on this file since 28231 was 28222, checked in by vboxsync, 15 years ago

IDisplay::DrawToScreen for multimonitor (xTracker 4655)

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 103.1 KB
Line 
1/** @file
2 * PDM - Pluggable Device Manager, Interfaces. (VMM)
3 */
4
5/*
6 * Copyright (C) 2006-2010 Sun Microsystems, Inc.
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 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
26 * Clara, CA 95054 USA or visit http://www.sun.com if you need
27 * additional information or have any questions.
28 */
29
30#ifndef ___VBox_pdmifs_h
31#define ___VBox_pdmifs_h
32
33#include <iprt/sg.h>
34#include <VBox/types.h>
35#include <VBox/hgcmsvc.h>
36
37RT_C_DECLS_BEGIN
38
39/** @defgroup grp_pdm_interfaces The PDM Interface Definitions
40 * @ingroup grp_pdm
41 *
42 * For historical reasons (the PDMINTERFACE enum) a lot of interface was stuffed
43 * together in this group instead, dragging stuff into global space that didn't
44 * need to be there and making this file huge (>2500 lines). Since we're using
45 * UUIDs as interface identifiers (IIDs) now, no only generic PDM interface will
46 * be added to this file. Component specific interface should be defined in the
47 * header file of that component.
48 *
49 * Interfaces consists of a method table (typedef'ed struct) and an interface
50 * ID. The typename of the method table should have an 'I' in it, be all
51 * capitals and according to the rules, no underscores. The interface ID is a
52 * \#define constructed by appending '_IID' to the typename. The IID value is a
53 * UUID string on the form "a2299c0d-b709-4551-aa5a-73f59ffbed74". If you stick
54 * to these rules, you can make use of the PDMIBASE_QUERY_INTERFACE and
55 * PDMIBASE_RETURN_INTERFACE when querying interface and implementing
56 * PDMIBASE::pfnQueryInterface respectively.
57 *
58 * In most interface descriptions the orientation of the interface is given as
59 * 'down' or 'up'. This refers to a model with the device on the top and the
60 * drivers stacked below it. Sometimes there is mention of 'main' or 'external'
61 * which normally means the same, i.e. the Main or VBoxBFE API. Picture the
62 * orientation of 'main' as horizontal.
63 *
64 * @{
65 */
66
67
68/** @name PDMIBASE
69 * @{
70 */
71
72/**
73 * PDM Base Interface.
74 *
75 * Everyone implements this.
76 */
77typedef struct PDMIBASE
78{
79 /**
80 * Queries an interface to the driver.
81 *
82 * @returns Pointer to interface.
83 * @returns NULL if the interface was not supported by the driver.
84 * @param pInterface Pointer to this interface structure.
85 * @param pszIID The interface ID, a UUID string.
86 * @thread Any thread.
87 */
88 DECLR3CALLBACKMEMBER(void *, pfnQueryInterface,(struct PDMIBASE *pInterface, const char *pszIID));
89} PDMIBASE;
90/** PDMIBASE interface ID. */
91#define PDMIBASE_IID "a2299c0d-b709-4551-aa5a-73f59ffbed74"
92
93/**
94 * Helper macro for quering an interface from PDMIBASE.
95 *
96 * @returns Correctly typed PDMIBASE::pfnQueryInterface return value.
97 *
98 * @param pIBase Pointer to the base interface.
99 * @param InterfaceType The interface type name. The interface ID is
100 * derived from this by appending _IID.
101 */
102#define PDMIBASE_QUERY_INTERFACE(pIBase, InterfaceType) \
103 ( (InterfaceType *)(pIBase)->pfnQueryInterface(pIBase, InterfaceType##_IID ) )
104
105/**
106 * Helper macro for implementing PDMIBASE::pfnQueryInterface.
107 *
108 * Return @a pInterface if @a pszIID matches the @a InterfaceType. This will
109 * perform basic type checking.
110 *
111 * @param pszIID The ID of the interface that is being queried.
112 * @param InterfaceType The interface type name. The interface ID is
113 * derived from this by appending _IID.
114 * @param pInterface The interface address expression.
115 */
116#define PDMIBASE_RETURN_INTERFACE(pszIID, InterfaceType, pInterface) \
117 do { \
118 if (RTUuidCompare2Strs((pszIID), InterfaceType##_IID) == 0) \
119 { \
120 InterfaceType *pReturnInterfaceTypeCheck = (pInterface); \
121 return pReturnInterfaceTypeCheck; \
122 } \
123 } while (0)
124
125/** @} */
126
127
128/** @name PDMIBASERC
129 * @{
130 */
131
132/**
133 * PDM Base Interface for querying ring-mode context interfaces in
134 * ring-3.
135 *
136 * This is mandatory for drivers present in raw-mode context.
137 */
138typedef struct PDMIBASERC
139{
140 /**
141 * Queries an ring-mode context interface to the driver.
142 *
143 * @returns Pointer to interface.
144 * @returns NULL if the interface was not supported by the driver.
145 * @param pInterface Pointer to this interface structure.
146 * @param pszIID The interface ID, a UUID string.
147 * @thread Any thread.
148 */
149 DECLR3CALLBACKMEMBER(RTRCPTR, pfnQueryInterface,(struct PDMIBASERC *pInterface, const char *pszIID));
150} PDMIBASERC;
151/** Pointer to a PDM Base Interface for query ring-mode context interfaces. */
152typedef PDMIBASERC *PPDMIBASERC;
153/** PDMIBASERC interface ID. */
154#define PDMIBASERC_IID "f6a6c649-6cb3-493f-9737-4653f221aeca"
155
156/**
157 * Helper macro for quering an interface from PDMIBASERC.
158 *
159 * @returns PDMIBASERC::pfnQueryInterface return value.
160 *
161 * @param pIBaseRC Pointer to the base ring-0 interface.
162 * @param InterfaceType The interface type name. The interface ID is
163 * derived from this by appending _IID.
164 *
165 * @remarks Unlike PDMIBASE_QUERY_INTERFACE, this macro is not able to do any
166 * implicit type checking for you.
167 */
168#define PDMIBASERC_QUERY_INTERFACE(pIBaseRC, InterfaceType) \
169 ( (InterfaceType *)(pIBaseRC)->pfnQueryInterface(pIBaseRC, InterfaceType##_IID ) )
170
171/**
172 * Helper macro for implementing PDMIBASERC::pfnQueryInterface.
173 *
174 * Return @a pInterface if @a pszIID matches the @a InterfaceType. This will
175 * perform basic type checking.
176 *
177 * @param pIns Pointer to the instance data.
178 * @param pszIID The ID of the interface that is being queried.
179 * @param InterfaceType The interface type name. The interface ID is
180 * derived from this by appending _IID.
181 * @param pInterface The interface address expression. This must resolve
182 * to some address within the instance data.
183 */
184#define PDMIBASERC_RETURN_INTERFACE(pIns, pszIID, InterfaceType, pInterface) \
185 do { \
186 Assert((uintptr_t)pInterface - PDMINS_2_DATA(pIns, uintptr_t) < _4M); \
187 if (RTUuidCompare2Strs((pszIID), InterfaceType##_IID) == 0) \
188 { \
189 InterfaceType *pReturnInterfaceTypeCheck = (pInterface); \
190 return (uintptr_t)pReturnInterfaceTypeCheck \
191 - PDMINS_2_DATA(pIns, uintptr_t) \
192 + PDMINS_2_DATA_RCPTR(pIns); \
193 } \
194 } while (0)
195
196/** @} */
197
198
199/** @name PDMIBASER0
200 * @{
201 */
202
203/**
204 * PDM Base Interface for querying ring-0 interfaces in ring-3.
205 *
206 * This is mandatory for drivers present in ring-0 context.
207 */
208typedef struct PDMIBASER0
209{
210 /**
211 * Queries an ring-0 interface to the driver.
212 *
213 * @returns Pointer to interface.
214 * @returns NULL if the interface was not supported by the driver.
215 * @param pInterface Pointer to this interface structure.
216 * @param pszIID The interface ID, a UUID string.
217 * @thread Any thread.
218 */
219 DECLR3CALLBACKMEMBER(RTR0PTR, pfnQueryInterface,(struct PDMIBASER0 *pInterface, const char *pszIID));
220} PDMIBASER0;
221/** Pointer to a PDM Base Interface for query ring-0 context interfaces. */
222typedef PDMIBASER0 *PPDMIBASER0;
223/** PDMIBASER0 interface ID. */
224#define PDMIBASER0_IID "9c9b99b8-7f53-4f59-a3c2-5bc9659c7944"
225
226/**
227 * Helper macro for quering an interface from PDMIBASER0.
228 *
229 * @returns PDMIBASER0::pfnQueryInterface return value.
230 *
231 * @param pIBaseR0 Pointer to the base ring-0 interface.
232 * @param InterfaceType The interface type name. The interface ID is
233 * derived from this by appending _IID.
234 *
235 * @remarks Unlike PDMIBASE_QUERY_INTERFACE, this macro is not able to do any
236 * implicit type checking for you.
237 */
238#define PDMIBASER0_QUERY_INTERFACE(pIBaseR0, InterfaceType) \
239 ( (InterfaceType *)(pIBaseR0)->pfnQueryInterface(pIBaseR0, InterfaceType##_IID ) )
240
241/**
242 * Helper macro for implementing PDMIBASER0::pfnQueryInterface.
243 *
244 * Return @a pInterface if @a pszIID matches the @a InterfaceType. This will
245 * perform basic type checking.
246 *
247 * @param pIns Pointer to the instance data.
248 * @param pszIID The ID of the interface that is being queried.
249 * @param InterfaceType The interface type name. The interface ID is
250 * derived from this by appending _IID.
251 * @param pInterface The interface address expression. This must resolve
252 * to some address within the instance data.
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 *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 */
354 DECLR3CALLBACKMEMBER(void, pfnReportModes,(PPDMIMOUSECONNECTOR pInterface, bool fRelative, bool fAbsolute));
355
356} PDMIMOUSECONNECTOR;
357/** PDMIMOUSECONNECTOR interface ID. */
358#define PDMIMOUSECONNECTOR_IID "ce64d7bd-fa8f-41d1-a6fb-d102a2d6bffe"
359
360
361/** Pointer to a keyboard port interface. */
362typedef struct PDMIKEYBOARDPORT *PPDMIKEYBOARDPORT;
363/**
364 * Keyboard port interface (down).
365 * Pair with PDMIKEYBOARDCONNECTOR.
366 */
367typedef struct PDMIKEYBOARDPORT
368{
369 /**
370 * Puts a keyboard event.
371 *
372 * This is called by the source of keyboard events. The event will be passed up
373 * until the topmost driver, which then calls the registered event handler.
374 *
375 * @returns VBox status code. Return VERR_TRY_AGAIN if you cannot process the
376 * event now and want it to be repeated at a later point.
377 *
378 * @param pInterface Pointer to this interface structure.
379 * @param u8KeyCode The keycode to queue.
380 */
381 DECLR3CALLBACKMEMBER(int, pfnPutEvent,(PPDMIKEYBOARDPORT pInterface, uint8_t u8KeyCode));
382} PDMIKEYBOARDPORT;
383/** PDMIKEYBOARDPORT interface ID. */
384#define PDMIKEYBOARDPORT_IID "2a0844f0-410b-40ab-a6ed-6575f3aa3e29"
385
386
387/**
388 * Keyboard LEDs.
389 */
390typedef enum PDMKEYBLEDS
391{
392 /** No leds. */
393 PDMKEYBLEDS_NONE = 0x0000,
394 /** Num Lock */
395 PDMKEYBLEDS_NUMLOCK = 0x0001,
396 /** Caps Lock */
397 PDMKEYBLEDS_CAPSLOCK = 0x0002,
398 /** Scroll Lock */
399 PDMKEYBLEDS_SCROLLLOCK = 0x0004
400} PDMKEYBLEDS;
401
402/** Pointer to keyboard connector interface. */
403typedef struct PDMIKEYBOARDCONNECTOR *PPDMIKEYBOARDCONNECTOR;
404/**
405 * Keyboard connector interface (up).
406 * Pair with PDMIKEYBOARDPORT
407 */
408typedef struct PDMIKEYBOARDCONNECTOR
409{
410 /**
411 * Notifies the the downstream driver about an LED change initiated by the guest.
412 *
413 * @param pInterface Pointer to the this interface.
414 * @param enmLeds The new led mask.
415 */
416 DECLR3CALLBACKMEMBER(void, pfnLedStatusChange,(PPDMIKEYBOARDCONNECTOR pInterface, PDMKEYBLEDS enmLeds));
417
418} PDMIKEYBOARDCONNECTOR;
419/** PDMIKEYBOARDCONNECTOR interface ID. */
420#define PDMIKEYBOARDCONNECTOR_IID "db3f7bd5-953e-436f-9f8e-077905a92d82"
421
422
423
424/** Pointer to a display port interface. */
425typedef struct PDMIDISPLAYPORT *PPDMIDISPLAYPORT;
426/**
427 * Display port interface (down).
428 * Pair with PDMIDISPLAYCONNECTOR.
429 */
430typedef struct PDMIDISPLAYPORT
431{
432 /**
433 * Update the display with any changed regions.
434 *
435 * Flushes any display changes to the memory pointed to by the
436 * PDMIDISPLAYCONNECTOR interface and calles PDMIDISPLAYCONNECTOR::pfnUpdateRect()
437 * while doing so.
438 *
439 * @returns VBox status code.
440 * @param pInterface Pointer to this interface.
441 * @thread The emulation thread.
442 */
443 DECLR3CALLBACKMEMBER(int, pfnUpdateDisplay,(PPDMIDISPLAYPORT pInterface));
444
445 /**
446 * Update the entire display.
447 *
448 * Flushes the entire display content to the memory pointed to by the
449 * PDMIDISPLAYCONNECTOR interface and calles PDMIDISPLAYCONNECTOR::pfnUpdateRect().
450 *
451 * @returns VBox status code.
452 * @param pInterface Pointer to this interface.
453 * @thread The emulation thread.
454 */
455 DECLR3CALLBACKMEMBER(int, pfnUpdateDisplayAll,(PPDMIDISPLAYPORT pInterface));
456
457 /**
458 * Return the current guest color depth in bits per pixel (bpp).
459 *
460 * As the graphics card is able to provide display updates with the bpp
461 * requested by the host, this method can be used to query the actual
462 * guest color depth.
463 *
464 * @returns VBox status code.
465 * @param pInterface Pointer to this interface.
466 * @param pcBits Where to store the current guest color depth.
467 * @thread Any thread.
468 */
469 DECLR3CALLBACKMEMBER(int, pfnQueryColorDepth,(PPDMIDISPLAYPORT pInterface, uint32_t *pcBits));
470
471 /**
472 * Sets the refresh rate and restart the timer.
473 * The rate is defined as the minimum interval between the return of
474 * one PDMIDISPLAYPORT::pfnRefresh() call to the next one.
475 *
476 * The interval timer will be restarted by this call. So at VM startup
477 * this function must be called to start the refresh cycle. The refresh
478 * rate is not saved, but have to be when resuming a loaded VM state.
479 *
480 * @returns VBox status code.
481 * @param pInterface Pointer to this interface.
482 * @param cMilliesInterval Number of millies between two refreshes.
483 * @thread Any thread.
484 */
485 DECLR3CALLBACKMEMBER(int, pfnSetRefreshRate,(PPDMIDISPLAYPORT pInterface, uint32_t cMilliesInterval));
486
487 /**
488 * Create a 32-bbp screenshot of the display.
489 *
490 * This will allocate and return a 32-bbp bitmap. Size of the bitmap scanline in bytes is 4*width.
491 *
492 * The allocated bitmap buffer must be freed with pfnFreeScreenshot.
493 *
494 * @param pInterface Pointer to this interface.
495 * @param ppu8Data Where to store the pointer to the allocated buffer.
496 * @param pcbData Where to store the actual size of the bitmap.
497 * @param pcx Where to store the width of the bitmap.
498 * @param pcy Where to store the height of the bitmap.
499 * @thread The emulation thread.
500 */
501 DECLR3CALLBACKMEMBER(int, pfnTakeScreenshot,(PPDMIDISPLAYPORT pInterface, uint8_t **ppu8Data, size_t *pcbData, uint32_t *pcx, uint32_t *pcy));
502
503 /**
504 * Free screenshot buffer.
505 *
506 * This will free the memory buffer allocated by pfnTakeScreenshot.
507 *
508 * @param pInterface Pointer to this interface.
509 * @param ppu8Data Pointer to the buffer returned by pfnTakeScreenshot.
510 * @thread Any.
511 */
512 DECLR3CALLBACKMEMBER(void, pfnFreeScreenshot,(PPDMIDISPLAYPORT pInterface, uint8_t *pu8Data));
513
514 /**
515 * Copy bitmap to the display.
516 *
517 * This will convert and copy a 32-bbp bitmap (with dword aligned scanline length) to
518 * the memory pointed to by the PDMIDISPLAYCONNECTOR interface.
519 *
520 * @param pInterface Pointer to this interface.
521 * @param pvData Pointer to the bitmap bits.
522 * @param x The upper left corner x coordinate of the destination rectangle.
523 * @param y The upper left corner y coordinate of the destination rectangle.
524 * @param cx The width of the source and destination rectangles.
525 * @param cy The height of the source and destination rectangles.
526 * @thread The emulation thread.
527 * @remark This is just a convenience for using the bitmap conversions of the
528 * graphics device.
529 */
530 DECLR3CALLBACKMEMBER(int, pfnDisplayBlt,(PPDMIDISPLAYPORT pInterface, const void *pvData, uint32_t x, uint32_t y, uint32_t cx, uint32_t cy));
531
532 /**
533 * Render a rectangle from guest VRAM to Framebuffer.
534 *
535 * @param pInterface Pointer to this interface.
536 * @param x The upper left corner x coordinate of the rectangle to be updated.
537 * @param y The upper left corner y coordinate of the rectangle to be updated.
538 * @param cx The width of the rectangle to be updated.
539 * @param cy The height of the rectangle to be updated.
540 * @thread The emulation thread.
541 */
542 DECLR3CALLBACKMEMBER(void, pfnUpdateDisplayRect,(PPDMIDISPLAYPORT pInterface, int32_t x, int32_t y, uint32_t cx, uint32_t cy));
543
544 /**
545 * Inform the VGA device whether the Display is directly using the guest VRAM and there is no need
546 * to render the VRAM to the framebuffer memory.
547 *
548 * @param pInterface Pointer to this interface.
549 * @param fRender Whether the VRAM content must be rendered to the framebuffer.
550 * @thread The emulation thread.
551 */
552 DECLR3CALLBACKMEMBER(void, pfnSetRenderVRAM,(PPDMIDISPLAYPORT pInterface, bool fRender));
553
554 /**
555 * Render a bitmap rectangle from source to target buffer.
556 *
557 * @param pInterface Pointer to this interface.
558 * @param cx The width of the rectangle to be copied.
559 * @param cy The height of the rectangle to be copied.
560 * @param pbSrc Source frame buffer 0,0.
561 * @param xSrc The upper left corner x coordinate of the source rectangle.
562 * @param ySrc The upper left corner y coordinate of the source rectangle.
563 * @param cxSrc The width of the source frame buffer.
564 * @param cySrc The height of the source frame buffer.
565 * @param cbSrcLine The line length of the source frame buffer.
566 * @param cSrcBitsPerPixel The pixel depth of the source.
567 * @param pbDst Destination frame buffer 0,0.
568 * @param xDst The upper left corner x coordinate of the destination rectangle.
569 * @param yDst The upper left corner y coordinate of the destination rectangle.
570 * @param cxDst The width of the destination frame buffer.
571 * @param cyDst The height of the destination frame buffer.
572 * @param cbDstLine The line length of the destination frame buffer.
573 * @param cDstBitsPerPixel The pixel depth of the destination.
574 * @thread The emulation thread.
575 */
576 DECLR3CALLBACKMEMBER(int, pfnCopyRect,(PPDMIDISPLAYPORT pInterface, uint32_t cx, uint32_t cy,
577 const uint8_t *pbSrc, int32_t xSrc, int32_t ySrc, uint32_t cxSrc, uint32_t cySrc, uint32_t cbSrcLine, uint32_t cSrcBitsPerPixel,
578 uint8_t *pbDst, int32_t xDst, int32_t yDst, uint32_t cxDst, uint32_t cyDst, uint32_t cbDstLine, uint32_t cDstBitsPerPixel));
579
580} PDMIDISPLAYPORT;
581/** PDMIDISPLAYPORT interface ID. */
582#define PDMIDISPLAYPORT_IID "14433cdc-f7cc-4385-b280-287d447f026e"
583
584
585typedef struct _VBOXVHWACMD *PVBOXVHWACMD; /**< @todo r=bird: _VBOXVHWACMD -> VBOXVHWACMD; avoid using 1 or 2 leading underscores. Also, a line what it is to make doxygen happy. */
586typedef struct VBVACMDHDR *PVBVACMDHDR;
587typedef struct VBVAINFOSCREEN *PVBVAINFOSCREEN;
588typedef struct VBVAINFOVIEW *PVBVAINFOVIEW;
589typedef struct VBVAHOSTFLAGS *PVBVAHOSTFLAGS;
590
591/** Pointer to a display connector interface. */
592typedef struct PDMIDISPLAYCONNECTOR *PPDMIDISPLAYCONNECTOR;
593/**
594 * Display connector interface (up).
595 * Pair with PDMIDISPLAYPORT.
596 */
597typedef struct PDMIDISPLAYCONNECTOR
598{
599 /**
600 * Resize the display.
601 * This is called when the resolution changes. This usually happens on
602 * request from the guest os, but may also happen as the result of a reset.
603 * If the callback returns VINF_VGA_RESIZE_IN_PROGRESS, the caller (VGA device)
604 * must not access the connector and return.
605 *
606 * @returns VINF_SUCCESS if the framebuffer resize was completed,
607 * VINF_VGA_RESIZE_IN_PROGRESS if resize takes time and not yet finished.
608 * @param pInterface Pointer to this interface.
609 * @param cBits Color depth (bits per pixel) of the new video mode.
610 * @param pvVRAM Address of the guest VRAM.
611 * @param cbLine Size in bytes of a single scan line.
612 * @param cx New display width.
613 * @param cy New display height.
614 * @thread The emulation thread.
615 */
616 DECLR3CALLBACKMEMBER(int, pfnResize,(PPDMIDISPLAYCONNECTOR pInterface, uint32_t cBits, void *pvVRAM, uint32_t cbLine, uint32_t cx, uint32_t cy));
617
618 /**
619 * Update a rectangle of the display.
620 * PDMIDISPLAYPORT::pfnUpdateDisplay is the caller.
621 *
622 * @param pInterface Pointer to this interface.
623 * @param x The upper left corner x coordinate of the rectangle.
624 * @param y The upper left corner y coordinate of the rectangle.
625 * @param cx The width of the rectangle.
626 * @param cy The height of the rectangle.
627 * @thread The emulation thread.
628 */
629 DECLR3CALLBACKMEMBER(void, pfnUpdateRect,(PPDMIDISPLAYCONNECTOR pInterface, uint32_t x, uint32_t y, uint32_t cx, uint32_t cy));
630
631 /**
632 * Refresh the display.
633 *
634 * The interval between these calls is set by
635 * PDMIDISPLAYPORT::pfnSetRefreshRate(). The driver should call
636 * PDMIDISPLAYPORT::pfnUpdateDisplay() if it wishes to refresh the
637 * display. PDMIDISPLAYPORT::pfnUpdateDisplay calls pfnUpdateRect with
638 * the changed rectangles.
639 *
640 * @param pInterface Pointer to this interface.
641 * @thread The emulation thread.
642 */
643 DECLR3CALLBACKMEMBER(void, pfnRefresh,(PPDMIDISPLAYCONNECTOR pInterface));
644
645 /**
646 * Reset the display.
647 *
648 * Notification message when the graphics card has been reset.
649 *
650 * @param pInterface Pointer to this interface.
651 * @thread The emulation thread.
652 */
653 DECLR3CALLBACKMEMBER(void, pfnReset,(PPDMIDISPLAYCONNECTOR pInterface));
654
655 /**
656 * LFB video mode enter/exit.
657 *
658 * Notification message when LinearFrameBuffer video mode is enabled/disabled.
659 *
660 * @param pInterface Pointer to this interface.
661 * @param fEnabled false - LFB mode was disabled,
662 * true - an LFB mode was disabled
663 * @thread The emulation thread.
664 */
665 DECLR3CALLBACKMEMBER(void, pfnLFBModeChange, (PPDMIDISPLAYCONNECTOR pInterface, bool fEnabled));
666
667 /**
668 * Process the guest graphics adapter information.
669 *
670 * Direct notification from guest to the display connector.
671 *
672 * @param pInterface Pointer to this interface.
673 * @param pvVRAM Address of the guest VRAM.
674 * @param u32VRAMSize Size of the guest VRAM.
675 * @thread The emulation thread.
676 */
677 DECLR3CALLBACKMEMBER(void, pfnProcessAdapterData, (PPDMIDISPLAYCONNECTOR pInterface, void *pvVRAM, uint32_t u32VRAMSize));
678
679 /**
680 * Process the guest display information.
681 *
682 * Direct notification from guest to the display connector.
683 *
684 * @param pInterface Pointer to this interface.
685 * @param pvVRAM Address of the guest VRAM.
686 * @param uScreenId The index of the guest display to be processed.
687 * @thread The emulation thread.
688 */
689 DECLR3CALLBACKMEMBER(void, pfnProcessDisplayData, (PPDMIDISPLAYCONNECTOR pInterface, void *pvVRAM, unsigned uScreenId));
690
691 /**
692 * Process the guest Video HW Acceleration command.
693 *
694 * @param pInterface Pointer to this interface.
695 * @param pCmd Video HW Acceleration Command to be processed.
696 * @thread The emulation thread.
697 */
698 DECLR3CALLBACKMEMBER(void, pfnVHWACommandProcess, (PPDMIDISPLAYCONNECTOR pInterface, PVBOXVHWACMD pCmd));
699
700 /**
701 * The specified screen enters VBVA mode.
702 *
703 * @param pInterface Pointer to this interface.
704 * @param uScreenId The screen updates are for.
705 * @thread The emulation thread.
706 */
707 DECLR3CALLBACKMEMBER(int, pfnVBVAEnable,(PPDMIDISPLAYCONNECTOR pInterface, unsigned uScreenId, PVBVAHOSTFLAGS pHostFlags));
708
709 /**
710 * The specified screen leaves VBVA mode.
711 *
712 * @param pInterface Pointer to this interface.
713 * @param uScreenId The screen updates are for.
714 * @thread The emulation thread.
715 */
716 DECLR3CALLBACKMEMBER(void, pfnVBVADisable,(PPDMIDISPLAYCONNECTOR pInterface, unsigned uScreenId));
717
718 /**
719 * A sequence of pfnVBVAUpdateProcess calls begins.
720 *
721 * @param pInterface Pointer to this interface.
722 * @param uScreenId The screen updates are for.
723 * @thread The emulation thread.
724 */
725 DECLR3CALLBACKMEMBER(void, pfnVBVAUpdateBegin,(PPDMIDISPLAYCONNECTOR pInterface, unsigned uScreenId));
726
727 /**
728 * Process the guest VBVA command.
729 *
730 * @param pInterface Pointer to this interface.
731 * @param pCmd Video HW Acceleration Command to be processed.
732 * @thread The emulation thread.
733 */
734 DECLR3CALLBACKMEMBER(void, pfnVBVAUpdateProcess,(PPDMIDISPLAYCONNECTOR pInterface, unsigned uScreenId, const PVBVACMDHDR pCmd, size_t cbCmd));
735
736 /**
737 * A sequence of pfnVBVAUpdateProcess calls ends.
738 *
739 * @param pInterface Pointer to this interface.
740 * @param uScreenId The screen updates are for.
741 * @param x The upper left corner x coordinate of the combined rectangle of all VBVA updates.
742 * @param y The upper left corner y coordinate of the rectangle.
743 * @param cx The width of the rectangle.
744 * @param cy The height of the rectangle.
745 * @thread The emulation thread.
746 */
747 DECLR3CALLBACKMEMBER(void, pfnVBVAUpdateEnd,(PPDMIDISPLAYCONNECTOR pInterface, unsigned uScreenId, int32_t x, int32_t y, uint32_t cx, uint32_t cy));
748
749 /**
750 * Resize the display.
751 * This is called when the resolution changes. This usually happens on
752 * request from the guest os, but may also happen as the result of a reset.
753 * If the callback returns VINF_VGA_RESIZE_IN_PROGRESS, the caller (VGA device)
754 * must not access the connector and return.
755 *
756 * @todo Merge with pfnResize.
757 *
758 * @returns VINF_SUCCESS if the framebuffer resize was completed,
759 * VINF_VGA_RESIZE_IN_PROGRESS if resize takes time and not yet finished.
760 * @param pInterface Pointer to this interface.
761 * @param pView The description of VRAM block for this screen.
762 * @param pScreen The data of screen being resized.
763 * @param pvVRAM Address of the guest VRAM.
764 * @thread The emulation thread.
765 */
766 DECLR3CALLBACKMEMBER(int, pfnVBVAResize,(PPDMIDISPLAYCONNECTOR pInterface, const PVBVAINFOVIEW pView, const PVBVAINFOSCREEN pScreen, void *pvVRAM));
767
768 /**
769 * Update the pointer shape.
770 * This is called when the mouse pointer shape changes. The new shape
771 * is passed as a caller allocated buffer that will be freed after returning
772 *
773 * @param pInterface Pointer to this interface.
774 * @param fVisible Visibility indicator (if false, the other parameters are undefined).
775 * @param fAlpha Flag whether alpha channel is being passed.
776 * @param xHot Pointer hot spot x coordinate.
777 * @param yHot Pointer hot spot y coordinate.
778 * @param x Pointer new x coordinate on screen.
779 * @param y Pointer new y coordinate on screen.
780 * @param cx Pointer width in pixels.
781 * @param cy Pointer height in pixels.
782 * @param cbScanline Size of one scanline in bytes.
783 * @param pvShape New shape buffer.
784 * @thread The emulation thread.
785 */
786 DECLR3CALLBACKMEMBER(int, pfnVBVAMousePointerShape,(PPDMIDISPLAYCONNECTOR pInterface, bool fVisible, bool fAlpha,
787 uint32_t xHot, uint32_t yHot,
788 uint32_t cx, uint32_t cy,
789 const void *pvShape));
790
791 /** Read-only attributes.
792 * For preformance reasons some readonly attributes are kept in the interface.
793 * We trust the interface users to respect the readonlyness of these.
794 * @{
795 */
796 /** Pointer to the display data buffer. */
797 uint8_t *pu8Data;
798 /** Size of a scanline in the data buffer. */
799 uint32_t cbScanline;
800 /** The color depth (in bits) the graphics card is supposed to provide. */
801 uint32_t cBits;
802 /** The display width. */
803 uint32_t cx;
804 /** The display height. */
805 uint32_t cy;
806 /** @} */
807} PDMIDISPLAYCONNECTOR;
808/** PDMIDISPLAYCONNECTOR interface ID. */
809#define PDMIDISPLAYCONNECTOR_IID "c7a1b36d-8dfc-421d-b71f-3a0eeaf733e6"
810
811
812/**
813 * Block notify interface (down).
814 * Pair with PDMIBLOCK.
815 */
816typedef PDMIDUMMY PDMIBLOCKPORT;
817/** PDMIBLOCKPORT interface ID. */
818#define PDMIBLOCKPORT_IID "e87fa1ab-92d5-4100-8712-fe2a0c042faf"
819/** Pointer to a block notify interface (dummy). */
820typedef PDMIBLOCKPORT *PPDMIBLOCKPORT;
821
822
823/**
824 * Callback which provides progress information.
825 *
826 * @return VBox status code.
827 * @param pvUser Opaque user data.
828 * @param uPercent Completion percentage.
829 */
830typedef DECLCALLBACK(int) FNSIMPLEPROGRESS(void *pvUser, unsigned uPercentage);
831/** Pointer to FNSIMPLEPROGRESS() */
832typedef FNSIMPLEPROGRESS *PFNSIMPLEPROGRESS;
833
834
835/**
836 * Block drive type.
837 */
838typedef enum PDMBLOCKTYPE
839{
840 /** Error (for the query function). */
841 PDMBLOCKTYPE_ERROR = 1,
842 /** 360KB 5 1/4" floppy drive. */
843 PDMBLOCKTYPE_FLOPPY_360,
844 /** 720KB 3 1/2" floppy drive. */
845 PDMBLOCKTYPE_FLOPPY_720,
846 /** 1.2MB 5 1/4" floppy drive. */
847 PDMBLOCKTYPE_FLOPPY_1_20,
848 /** 1.44MB 3 1/2" floppy drive. */
849 PDMBLOCKTYPE_FLOPPY_1_44,
850 /** 2.88MB 3 1/2" floppy drive. */
851 PDMBLOCKTYPE_FLOPPY_2_88,
852 /** CDROM drive. */
853 PDMBLOCKTYPE_CDROM,
854 /** DVD drive. */
855 PDMBLOCKTYPE_DVD,
856 /** Hard disk drive. */
857 PDMBLOCKTYPE_HARD_DISK
858} PDMBLOCKTYPE;
859
860
861/**
862 * Block raw command data transfer direction.
863 */
864typedef enum PDMBLOCKTXDIR
865{
866 PDMBLOCKTXDIR_NONE = 0,
867 PDMBLOCKTXDIR_FROM_DEVICE,
868 PDMBLOCKTXDIR_TO_DEVICE
869} PDMBLOCKTXDIR;
870
871
872/** Pointer to a block interface. */
873typedef struct PDMIBLOCK *PPDMIBLOCK;
874/**
875 * Block interface (up).
876 * Pair with PDMIBLOCKPORT.
877 */
878typedef struct PDMIBLOCK
879{
880 /**
881 * Read bits.
882 *
883 * @returns VBox status code.
884 * @param pInterface Pointer to the interface structure containing the called function pointer.
885 * @param off Offset to start reading from. The offset must be aligned to a sector boundary.
886 * @param pvBuf Where to store the read bits.
887 * @param cbRead Number of bytes to read. Must be aligned to a sector boundary.
888 * @thread Any thread.
889 */
890 DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMIBLOCK pInterface, uint64_t off, void *pvBuf, size_t cbRead));
891
892 /**
893 * Write bits.
894 *
895 * @returns VBox status code.
896 * @param pInterface Pointer to the interface structure containing the called function pointer.
897 * @param off Offset to start writing at. The offset must be aligned to a sector boundary.
898 * @param pvBuf Where to store the write bits.
899 * @param cbWrite Number of bytes to write. Must be aligned to a sector boundary.
900 * @thread Any thread.
901 */
902 DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMIBLOCK pInterface, uint64_t off, const void *pvBuf, size_t cbWrite));
903
904 /**
905 * Make sure that the bits written are actually on the storage medium.
906 *
907 * @returns VBox status code.
908 * @param pInterface Pointer to the interface structure containing the called function pointer.
909 * @thread Any thread.
910 */
911 DECLR3CALLBACKMEMBER(int, pfnFlush,(PPDMIBLOCK pInterface));
912
913 /**
914 * Send a raw command to the underlying device (CDROM).
915 * This method is optional (i.e. the function pointer may be NULL).
916 *
917 * @returns VBox status code.
918 * @param pInterface Pointer to the interface structure containing the called function pointer.
919 * @param pbCmd Offset to start reading from.
920 * @param enmTxDir Direction of transfer.
921 * @param pvBuf Pointer tp the transfer buffer.
922 * @param cbBuf Size of the transfer buffer.
923 * @param pbSenseKey Status of the command (when return value is VERR_DEV_IO_ERROR).
924 * @param cTimeoutMillies Command timeout in milliseconds.
925 * @thread Any thread.
926 */
927 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));
928
929 /**
930 * Merge medium contents during a live snapshot deletion.
931 *
932 * @returns VBox status code.
933 * @param pInterface Pointer to the interface structure containing the called function pointer.
934 * @param pfnProgress Function pointer for progress notification.
935 * @param pvUser Opaque user data for progress notification.
936 * @thread Any thread.
937 */
938 DECLR3CALLBACKMEMBER(int, pfnMerge,(PPDMIBLOCK pInterface, PFNSIMPLEPROGRESS pfnProgress, void *pvUser));
939
940 /**
941 * Check if the media is readonly or not.
942 *
943 * @returns true if readonly.
944 * @returns false if read/write.
945 * @param pInterface Pointer to the interface structure containing the called function pointer.
946 * @thread Any thread.
947 */
948 DECLR3CALLBACKMEMBER(bool, pfnIsReadOnly,(PPDMIBLOCK pInterface));
949
950 /**
951 * Gets the media size in bytes.
952 *
953 * @returns Media size in bytes.
954 * @param pInterface Pointer to the interface structure containing the called function pointer.
955 * @thread Any thread.
956 */
957 DECLR3CALLBACKMEMBER(uint64_t, pfnGetSize,(PPDMIBLOCK pInterface));
958
959 /**
960 * Gets the block drive type.
961 *
962 * @returns block drive type.
963 * @param pInterface Pointer to the interface structure containing the called function pointer.
964 * @thread Any thread.
965 */
966 DECLR3CALLBACKMEMBER(PDMBLOCKTYPE, pfnGetType,(PPDMIBLOCK pInterface));
967
968 /**
969 * Gets the UUID of the block drive.
970 * Don't return the media UUID if it's removable.
971 *
972 * @returns VBox status code.
973 * @param pInterface Pointer to the interface structure containing the called function pointer.
974 * @param pUuid Where to store the UUID on success.
975 * @thread Any thread.
976 */
977 DECLR3CALLBACKMEMBER(int, pfnGetUuid,(PPDMIBLOCK pInterface, PRTUUID pUuid));
978} PDMIBLOCK;
979/** PDMIBLOCK interface ID. */
980#define PDMIBLOCK_IID "0a5f3156-8b21-4cf5-83fd-e097281d2900"
981
982
983/** Pointer to a mount interface. */
984typedef struct PDMIMOUNTNOTIFY *PPDMIMOUNTNOTIFY;
985/**
986 * Block interface (up).
987 * Pair with PDMIMOUNT.
988 */
989typedef struct PDMIMOUNTNOTIFY
990{
991 /**
992 * Called when a media is mounted.
993 *
994 * @param pInterface Pointer to the interface structure containing the called function pointer.
995 * @thread The emulation thread.
996 */
997 DECLR3CALLBACKMEMBER(void, pfnMountNotify,(PPDMIMOUNTNOTIFY pInterface));
998
999 /**
1000 * Called when a media is unmounted
1001 * @param pInterface Pointer to the interface structure containing the called function pointer.
1002 * @thread The emulation thread.
1003 */
1004 DECLR3CALLBACKMEMBER(void, pfnUnmountNotify,(PPDMIMOUNTNOTIFY pInterface));
1005} PDMIMOUNTNOTIFY;
1006/** PDMIMOUNTNOTIFY interface ID. */
1007#define PDMIMOUNTNOTIFY_IID "fa143ac9-9fc6-498e-997f-945380a558f9"
1008
1009
1010/** Pointer to mount interface. */
1011typedef struct PDMIMOUNT *PPDMIMOUNT;
1012/**
1013 * Mount interface (down).
1014 * Pair with PDMIMOUNTNOTIFY.
1015 */
1016typedef struct PDMIMOUNT
1017{
1018 /**
1019 * Mount a media.
1020 *
1021 * This will not unmount any currently mounted media!
1022 *
1023 * @returns VBox status code.
1024 * @param pInterface Pointer to the interface structure containing the called function pointer.
1025 * @param pszFilename Pointer to filename. If this is NULL it assumed that the caller have
1026 * constructed a configuration which can be attached to the bottom driver.
1027 * @param pszCoreDriver Core driver name. NULL will cause autodetection. Ignored if pszFilanem is NULL.
1028 * @thread The emulation thread.
1029 */
1030 DECLR3CALLBACKMEMBER(int, pfnMount,(PPDMIMOUNT pInterface, const char *pszFilename, const char *pszCoreDriver));
1031
1032 /**
1033 * Unmount the media.
1034 *
1035 * The driver will validate and pass it on. On the rebounce it will decide whether or not to detach it self.
1036 *
1037 * @returns VBox status code.
1038 * @param pInterface Pointer to the interface structure containing the called function pointer.
1039 * @thread The emulation thread.
1040 * @param fForce Force the unmount, even for locked media.
1041 * @thread The emulation thread.
1042 */
1043 DECLR3CALLBACKMEMBER(int, pfnUnmount,(PPDMIMOUNT pInterface, bool fForce));
1044
1045 /**
1046 * Checks if a media is mounted.
1047 *
1048 * @returns true if mounted.
1049 * @returns false if not mounted.
1050 * @param pInterface Pointer to the interface structure containing the called function pointer.
1051 * @thread Any thread.
1052 */
1053 DECLR3CALLBACKMEMBER(bool, pfnIsMounted,(PPDMIMOUNT pInterface));
1054
1055 /**
1056 * Locks the media, preventing any unmounting of it.
1057 *
1058 * @returns VBox status code.
1059 * @param pInterface Pointer to the interface structure containing the called function pointer.
1060 * @thread The emulation thread.
1061 */
1062 DECLR3CALLBACKMEMBER(int, pfnLock,(PPDMIMOUNT pInterface));
1063
1064 /**
1065 * Unlocks the media, canceling previous calls to pfnLock().
1066 *
1067 * @returns VBox status code.
1068 * @param pInterface Pointer to the interface structure containing the called function pointer.
1069 * @thread The emulation thread.
1070 */
1071 DECLR3CALLBACKMEMBER(int, pfnUnlock,(PPDMIMOUNT pInterface));
1072
1073 /**
1074 * Checks if a media is locked.
1075 *
1076 * @returns true if locked.
1077 * @returns false if not locked.
1078 * @param pInterface Pointer to the interface structure containing the called function pointer.
1079 * @thread Any thread.
1080 */
1081 DECLR3CALLBACKMEMBER(bool, pfnIsLocked,(PPDMIMOUNT pInterface));
1082} PDMIMOUNT;
1083/** PDMIMOUNT interface ID. */
1084#define PDMIMOUNT_IID "8e5a009a-6032-4ca1-9d86-a388d8eaf926"
1085
1086
1087/**
1088 * Media geometry structure.
1089 */
1090typedef struct PDMMEDIAGEOMETRY
1091{
1092 /** Number of cylinders. */
1093 uint32_t cCylinders;
1094 /** Number of heads. */
1095 uint32_t cHeads;
1096 /** Number of sectors. */
1097 uint32_t cSectors;
1098} PDMMEDIAGEOMETRY;
1099
1100/** Pointer to media geometry structure. */
1101typedef PDMMEDIAGEOMETRY *PPDMMEDIAGEOMETRY;
1102/** Pointer to constant media geometry structure. */
1103typedef const PDMMEDIAGEOMETRY *PCPDMMEDIAGEOMETRY;
1104
1105/** Pointer to a media interface. */
1106typedef struct PDMIMEDIA *PPDMIMEDIA;
1107/**
1108 * Media interface (up).
1109 * Makes up the foundation for PDMIBLOCK and PDMIBLOCKBIOS. No interface pair.
1110 */
1111typedef struct PDMIMEDIA
1112{
1113 /**
1114 * Read bits.
1115 *
1116 * @returns VBox status code.
1117 * @param pInterface Pointer to the interface structure containing the called function pointer.
1118 * @param off Offset to start reading from. The offset must be aligned to a sector boundary.
1119 * @param pvBuf Where to store the read bits.
1120 * @param cbRead Number of bytes to read. Must be aligned to a sector boundary.
1121 * @thread Any thread.
1122 */
1123 DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMIMEDIA pInterface, uint64_t off, void *pvBuf, size_t cbRead));
1124
1125 /**
1126 * Write bits.
1127 *
1128 * @returns VBox status code.
1129 * @param pInterface Pointer to the interface structure containing the called function pointer.
1130 * @param off Offset to start writing at. The offset must be aligned to a sector boundary.
1131 * @param pvBuf Where to store the write bits.
1132 * @param cbWrite Number of bytes to write. Must be aligned to a sector boundary.
1133 * @thread Any thread.
1134 */
1135 DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMIMEDIA pInterface, uint64_t off, const void *pvBuf, size_t cbWrite));
1136
1137 /**
1138 * Make sure that the bits written are actually on the storage medium.
1139 *
1140 * @returns VBox status code.
1141 * @param pInterface Pointer to the interface structure containing the called function pointer.
1142 * @thread Any thread.
1143 */
1144 DECLR3CALLBACKMEMBER(int, pfnFlush,(PPDMIMEDIA pInterface));
1145
1146 /**
1147 * Merge medium contents during a live snapshot deletion. All details
1148 * must have been configured through CFGM or this will fail.
1149 * This method is optional (i.e. the function pointer may be NULL).
1150 *
1151 * @returns VBox status code.
1152 * @param pInterface Pointer to the interface structure containing the called function pointer.
1153 * @param pfnProgress Function pointer for progress notification.
1154 * @param pvUser Opaque user data for progress notification.
1155 * @thread Any thread.
1156 */
1157 DECLR3CALLBACKMEMBER(int, pfnMerge,(PPDMIMEDIA pInterface, PFNSIMPLEPROGRESS pfnProgress, void *pvUser));
1158
1159 /**
1160 * Get the media size in bytes.
1161 *
1162 * @returns Media size in bytes.
1163 * @param pInterface Pointer to the interface structure containing the called function pointer.
1164 * @thread Any thread.
1165 */
1166 DECLR3CALLBACKMEMBER(uint64_t, pfnGetSize,(PPDMIMEDIA pInterface));
1167
1168 /**
1169 * Check if the media is readonly or not.
1170 *
1171 * @returns true if readonly.
1172 * @returns false if read/write.
1173 * @param pInterface Pointer to the interface structure containing the called function pointer.
1174 * @thread Any thread.
1175 */
1176 DECLR3CALLBACKMEMBER(bool, pfnIsReadOnly,(PPDMIMEDIA pInterface));
1177
1178 /**
1179 * Get stored media geometry (physical CHS, PCHS) - BIOS property.
1180 * This is an optional feature of a media.
1181 *
1182 * @returns VBox status code.
1183 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
1184 * @returns VERR_PDM_GEOMETRY_NOT_SET if the geometry hasn't been set using pfnBiosSetPCHSGeometry() yet.
1185 * @param pInterface Pointer to the interface structure containing the called function pointer.
1186 * @param pPCHSGeometry Pointer to PCHS geometry (cylinders/heads/sectors).
1187 * @remark This has no influence on the read/write operations.
1188 * @thread Any thread.
1189 */
1190 DECLR3CALLBACKMEMBER(int, pfnBiosGetPCHSGeometry,(PPDMIMEDIA pInterface, PPDMMEDIAGEOMETRY pPCHSGeometry));
1191
1192 /**
1193 * Store the media geometry (physical CHS, PCHS) - BIOS property.
1194 * This is an optional feature of a media.
1195 *
1196 * @returns VBox status code.
1197 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
1198 * @param pInterface Pointer to the interface structure containing the called function pointer.
1199 * @param pPCHSGeometry Pointer to PCHS geometry (cylinders/heads/sectors).
1200 * @remark This has no influence on the read/write operations.
1201 * @thread The emulation thread.
1202 */
1203 DECLR3CALLBACKMEMBER(int, pfnBiosSetPCHSGeometry,(PPDMIMEDIA pInterface, PCPDMMEDIAGEOMETRY pPCHSGeometry));
1204
1205 /**
1206 * Get stored media geometry (logical CHS, LCHS) - BIOS property.
1207 * This is an optional feature of a media.
1208 *
1209 * @returns VBox status code.
1210 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
1211 * @returns VERR_PDM_GEOMETRY_NOT_SET if the geometry hasn't been set using pfnBiosSetLCHSGeometry() yet.
1212 * @param pInterface Pointer to the interface structure containing the called function pointer.
1213 * @param pLCHSGeometry Pointer to LCHS geometry (cylinders/heads/sectors).
1214 * @remark This has no influence on the read/write operations.
1215 * @thread Any thread.
1216 */
1217 DECLR3CALLBACKMEMBER(int, pfnBiosGetLCHSGeometry,(PPDMIMEDIA pInterface, PPDMMEDIAGEOMETRY pLCHSGeometry));
1218
1219 /**
1220 * Store the media geometry (logical CHS, LCHS) - BIOS property.
1221 * This is an optional feature of a media.
1222 *
1223 * @returns VBox status code.
1224 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
1225 * @param pInterface Pointer to the interface structure containing the called function pointer.
1226 * @param pLCHSGeometry Pointer to LCHS geometry (cylinders/heads/sectors).
1227 * @remark This has no influence on the read/write operations.
1228 * @thread The emulation thread.
1229 */
1230 DECLR3CALLBACKMEMBER(int, pfnBiosSetLCHSGeometry,(PPDMIMEDIA pInterface, PCPDMMEDIAGEOMETRY pLCHSGeometry));
1231
1232 /**
1233 * Gets the UUID of the media drive.
1234 *
1235 * @returns VBox status code.
1236 * @param pInterface Pointer to the interface structure containing the called function pointer.
1237 * @param pUuid Where to store the UUID on success.
1238 * @thread Any thread.
1239 */
1240 DECLR3CALLBACKMEMBER(int, pfnGetUuid,(PPDMIMEDIA pInterface, PRTUUID pUuid));
1241
1242} PDMIMEDIA;
1243/** PDMIMEDIA interface ID. */
1244#define PDMIMEDIA_IID "f5bb07c9-2843-46f8-a56f-cc090b6e5bac"
1245
1246
1247/** Pointer to a block BIOS interface. */
1248typedef struct PDMIBLOCKBIOS *PPDMIBLOCKBIOS;
1249/**
1250 * Media BIOS interface (Up / External).
1251 * The interface the getting and setting properties which the BIOS/CMOS care about.
1252 */
1253typedef struct PDMIBLOCKBIOS
1254{
1255 /**
1256 * Get stored media geometry (physical CHS, PCHS) - BIOS property.
1257 * This is an optional feature of a media.
1258 *
1259 * @returns VBox status code.
1260 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
1261 * @returns VERR_PDM_GEOMETRY_NOT_SET if the geometry hasn't been set using pfnSetPCHSGeometry() yet.
1262 * @param pInterface Pointer to the interface structure containing the called function pointer.
1263 * @param pPCHSGeometry Pointer to PCHS geometry (cylinders/heads/sectors).
1264 * @remark This has no influence on the read/write operations.
1265 * @thread Any thread.
1266 */
1267 DECLR3CALLBACKMEMBER(int, pfnGetPCHSGeometry,(PPDMIBLOCKBIOS pInterface, PPDMMEDIAGEOMETRY pPCHSGeometry));
1268
1269 /**
1270 * Store the media geometry (physical CHS, PCHS) - BIOS property.
1271 * This is an optional feature of a media.
1272 *
1273 * @returns VBox status code.
1274 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
1275 * @param pInterface Pointer to the interface structure containing the called function pointer.
1276 * @param pPCHSGeometry Pointer to PCHS geometry (cylinders/heads/sectors).
1277 * @remark This has no influence on the read/write operations.
1278 * @thread The emulation thread.
1279 */
1280 DECLR3CALLBACKMEMBER(int, pfnSetPCHSGeometry,(PPDMIBLOCKBIOS pInterface, PCPDMMEDIAGEOMETRY pPCHSGeometry));
1281
1282 /**
1283 * Get stored media geometry (logical CHS, LCHS) - BIOS property.
1284 * This is an optional feature of a media.
1285 *
1286 * @returns VBox status code.
1287 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
1288 * @returns VERR_PDM_GEOMETRY_NOT_SET if the geometry hasn't been set using pfnSetLCHSGeometry() yet.
1289 * @param pInterface Pointer to the interface structure containing the called function pointer.
1290 * @param pLCHSGeometry Pointer to LCHS geometry (cylinders/heads/sectors).
1291 * @remark This has no influence on the read/write operations.
1292 * @thread Any thread.
1293 */
1294 DECLR3CALLBACKMEMBER(int, pfnGetLCHSGeometry,(PPDMIBLOCKBIOS pInterface, PPDMMEDIAGEOMETRY pLCHSGeometry));
1295
1296 /**
1297 * Store the media geometry (logical CHS, LCHS) - BIOS property.
1298 * This is an optional feature of a media.
1299 *
1300 * @returns VBox status code.
1301 * @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
1302 * @param pInterface Pointer to the interface structure containing the called function pointer.
1303 * @param pLCHSGeometry Pointer to LCHS geometry (cylinders/heads/sectors).
1304 * @remark This has no influence on the read/write operations.
1305 * @thread The emulation thread.
1306 */
1307 DECLR3CALLBACKMEMBER(int, pfnSetLCHSGeometry,(PPDMIBLOCKBIOS pInterface, PCPDMMEDIAGEOMETRY pLCHSGeometry));
1308
1309 /**
1310 * Checks if the device should be visible to the BIOS or not.
1311 *
1312 * @returns true if the device is visible to the BIOS.
1313 * @returns false if the device is not visible to the BIOS.
1314 * @param pInterface Pointer to the interface structure containing the called function pointer.
1315 * @thread Any thread.
1316 */
1317 DECLR3CALLBACKMEMBER(bool, pfnIsVisible,(PPDMIBLOCKBIOS pInterface));
1318
1319 /**
1320 * Gets the block drive type.
1321 *
1322 * @returns block drive type.
1323 * @param pInterface Pointer to the interface structure containing the called function pointer.
1324 * @thread Any thread.
1325 */
1326 DECLR3CALLBACKMEMBER(PDMBLOCKTYPE, pfnGetType,(PPDMIBLOCKBIOS pInterface));
1327
1328} PDMIBLOCKBIOS;
1329/** PDMIBLOCKBIOS interface ID. */
1330#define PDMIBLOCKBIOS_IID "477c3eee-a48d-48a9-82fd-2a54de16b2e9"
1331
1332
1333/** Pointer to a static block core driver interface. */
1334typedef struct PDMIMEDIASTATIC *PPDMIMEDIASTATIC;
1335/**
1336 * Static block core driver interface.
1337 */
1338typedef struct PDMIMEDIASTATIC
1339{
1340 /**
1341 * Check if the specified file is a format which the core driver can handle.
1342 *
1343 * @returns true / false accordingly.
1344 * @param pInterface Pointer to the interface structure containing the called function pointer.
1345 * @param pszFilename Name of the file to probe.
1346 */
1347 DECLR3CALLBACKMEMBER(bool, pfnCanHandle,(PPDMIMEDIASTATIC pInterface, const char *pszFilename));
1348} PDMIMEDIASTATIC;
1349
1350
1351
1352
1353
1354/** Pointer to a asynchronous block notify interface. */
1355typedef struct PDMIBLOCKASYNCPORT *PPDMIBLOCKASYNCPORT;
1356/**
1357 * Asynchronous block notify interface (up).
1358 * Pair with PDMIBLOCKASYNC.
1359 */
1360typedef struct PDMIBLOCKASYNCPORT
1361{
1362 /**
1363 * Notify completion of a asynchronous transfer.
1364 *
1365 * @returns VBox status code.
1366 * @param pInterface Pointer to the interface structure containing the called function pointer.
1367 * @param pvUser The user argument given in pfnStartWrite/Read.
1368 * @thread Any thread.
1369 */
1370 DECLR3CALLBACKMEMBER(int, pfnTransferCompleteNotify, (PPDMIBLOCKASYNCPORT pInterface, void *pvUser));
1371} PDMIBLOCKASYNCPORT;
1372/** PDMIBLOCKASYNCPORT interface ID. */
1373#define PDMIBLOCKASYNCPORT_IID "e3bdc0cb-9d99-41dd-8eec-0dc8cf5b2a92"
1374
1375
1376
1377/** Pointer to a asynchronous block interface. */
1378typedef struct PDMIBLOCKASYNC *PPDMIBLOCKASYNC;
1379/**
1380 * Asynchronous block interface (down).
1381 * Pair with PDMIBLOCKASYNCPORT.
1382 */
1383typedef struct PDMIBLOCKASYNC
1384{
1385 /**
1386 * Start reading task.
1387 *
1388 * @returns VBox status code.
1389 * @param pInterface Pointer to the interface structure containing the called function pointer.
1390 * @param off Offset to start reading from.c
1391 * @param pSeg Pointer to the first element in the scatter list.
1392 * @param cSeg Number of entries in the list.
1393 * @param cbRead Number of bytes to read. Must be aligned to a sector boundary.
1394 * @param pvUser User argument which is returned in completion callback.
1395 * @thread Any thread.
1396 */
1397 DECLR3CALLBACKMEMBER(int, pfnStartRead,(PPDMIBLOCKASYNC pInterface, uint64_t off, PCRTSGSEG pSeg, unsigned cSeg, size_t cbRead, void *pvUser));
1398
1399 /**
1400 * Write bits.
1401 *
1402 * @returns VBox status code.
1403 * @param pInterface Pointer to the interface structure containing the called function pointer.
1404 * @param off Offset to start writing at. The offset must be aligned to a sector boundary.
1405 * @param pSeg Pointer to the first element in the gather list.
1406 * @param cSeg Number of entries in the list.
1407 * @param cbWrite Number of bytes to write. Must be aligned to a sector boundary.
1408 * @param pvUser User argument which is returned in completion callback.
1409 * @thread Any thread.
1410 */
1411 DECLR3CALLBACKMEMBER(int, pfnStartWrite,(PPDMIBLOCKASYNC pInterface, uint64_t off, PCRTSGSEG pSeg, unsigned cSeg, size_t cbWrite, void *pvUser));
1412
1413} PDMIBLOCKASYNC;
1414/** PDMIBLOCKASYNC interface ID. */
1415#define PDMIBLOCKASYNC_IID "142cd775-3be6-4c9f-9e3d-68969c3d4779"
1416
1417
1418/** Pointer to a asynchronous notification interface. */
1419typedef struct PDMIMEDIAASYNCPORT *PPDMIMEDIAASYNCPORT;
1420/**
1421 * Asynchronous version of the media interface (up).
1422 * Pair with PDMIMEDIAASYNC.
1423 */
1424typedef struct PDMIMEDIAASYNCPORT
1425{
1426 /**
1427 * Notify completion of a task.
1428 *
1429 * @returns VBox status code.
1430 * @param pInterface Pointer to the interface structure containing the called function pointer.
1431 * @param pvUser The user argument given in pfnStartWrite.
1432 * @thread Any thread.
1433 */
1434 DECLR3CALLBACKMEMBER(int, pfnTransferCompleteNotify, (PPDMIMEDIAASYNCPORT pInterface, void *pvUser));
1435} PDMIMEDIAASYNCPORT;
1436/** PDMIMEDIAASYNCPORT interface ID. */
1437#define PDMIMEDIAASYNCPORT_IID "22d38853-901f-4a71-9670-4d9da6e82317"
1438
1439
1440/** Pointer to a asynchronous media interface. */
1441typedef struct PDMIMEDIAASYNC *PPDMIMEDIAASYNC;
1442/**
1443 * Asynchronous version of PDMIMEDIA (down).
1444 * Pair with PDMIMEDIAASYNCPORT.
1445 */
1446typedef struct PDMIMEDIAASYNC
1447{
1448 /**
1449 * Start reading task.
1450 *
1451 * @returns VBox status code.
1452 * @param pInterface Pointer to the interface structure containing the called function pointer.
1453 * @param off Offset to start reading from. Must be aligned to a sector boundary.
1454 * @param pSeg Pointer to the first element in the scatter list.
1455 * @param cSeg Number of entries in the list.
1456 * @param cbRead Number of bytes to read. Must be aligned to a sector boundary.
1457 * @param pvUser User data.
1458 * @thread Any thread.
1459 */
1460 DECLR3CALLBACKMEMBER(int, pfnStartRead,(PPDMIMEDIAASYNC pInterface, uint64_t off, PCRTSGSEG pSeg, unsigned cSeg, size_t cbRead, void *pvUser));
1461
1462 /**
1463 * Start writing task.
1464 *
1465 * @returns VBox status code.
1466 * @param pInterface Pointer to the interface structure containing the called function pointer.
1467 * @param off Offset to start writing at. Must be aligned to a sector boundary.
1468 * @param pSeg Pointer to the first element in the gather list.
1469 * @param cSeg Number of entries in the list.
1470 * @param cbWrite Number of bytes to write. Must be aligned to a sector boundary.
1471 * @param pvUser User data.
1472 * @thread Any thread.
1473 */
1474 DECLR3CALLBACKMEMBER(int, pfnStartWrite,(PPDMIMEDIAASYNC pInterface, uint64_t off, PCRTSGSEG pSeg, unsigned cSeg, size_t cbWrite, void *pvUser));
1475
1476} PDMIMEDIAASYNC;
1477/** PDMIMEDIAASYNC interface ID. */
1478#define PDMIMEDIAASYNC_IID "d7bc3c90-e686-4d9c-a7bc-6c6742e452ec"
1479
1480
1481/** Pointer to a char port interface. */
1482typedef struct PDMICHARPORT *PPDMICHARPORT;
1483/**
1484 * Char port interface (down).
1485 * Pair with PDMICHARCONNECTOR.
1486 */
1487typedef struct PDMICHARPORT
1488{
1489 /**
1490 * Deliver data read to the device/driver.
1491 *
1492 * @returns VBox status code.
1493 * @param pInterface Pointer to the interface structure containing the called function pointer.
1494 * @param pvBuf Where the read bits are stored.
1495 * @param pcbRead Number of bytes available for reading/having been read.
1496 * @thread Any thread.
1497 */
1498 DECLR3CALLBACKMEMBER(int, pfnNotifyRead,(PPDMICHARPORT pInterface, const void *pvBuf, size_t *pcbRead));
1499
1500 /**
1501 * Notify the device/driver when the status lines changed.
1502 *
1503 * @returns VBox status code.
1504 * @param pInterface Pointer to the interface structure containing the called function pointer.
1505 * @param fNewStatusLine New state of the status line pins.
1506 * @thread Any thread.
1507 */
1508 DECLR3CALLBACKMEMBER(int, pfnNotifyStatusLinesChanged,(PPDMICHARPORT pInterface, uint32_t fNewStatusLines));
1509
1510 /**
1511 * Notify the device when the driver buffer is full.
1512 *
1513 * @returns VBox status code.
1514 * @param pInterface Pointer to the interface structure containing the called function pointer.
1515 * @param fFull Buffer full.
1516 * @thread Any thread.
1517 */
1518 DECLR3CALLBACKMEMBER(int, pfnNotifyBufferFull,(PPDMICHARPORT pInterface, bool fFull));
1519
1520 /**
1521 * Notify the device/driver that a break occurred.
1522 *
1523 * @returns VBox statsus code.
1524 * @param pInterface Pointer to the interface structure containing the called function pointer.
1525 * @thread Any thread.
1526 */
1527 DECLR3CALLBACKMEMBER(int, pfnNotifyBreak,(PPDMICHARPORT pInterface));
1528} PDMICHARPORT;
1529/** PDMICHARPORT interface ID. */
1530#define PDMICHARPORT_IID "22769834-ea8b-4a6d-ade1-213dcdbd1228"
1531
1532/** @name Bit mask definitions for status line type.
1533 * @{ */
1534#define PDMICHARPORT_STATUS_LINES_DCD RT_BIT(0)
1535#define PDMICHARPORT_STATUS_LINES_RI RT_BIT(1)
1536#define PDMICHARPORT_STATUS_LINES_DSR RT_BIT(2)
1537#define PDMICHARPORT_STATUS_LINES_CTS RT_BIT(3)
1538/** @} */
1539
1540
1541/** Pointer to a char interface. */
1542typedef struct PDMICHARCONNECTOR *PPDMICHARCONNECTOR;
1543/**
1544 * Char connector interface (up).
1545 * Pair with PDMICHARPORT.
1546 */
1547typedef struct PDMICHARCONNECTOR
1548{
1549 /**
1550 * Write bits.
1551 *
1552 * @returns VBox status code.
1553 * @param pInterface Pointer to the interface structure containing the called function pointer.
1554 * @param pvBuf Where to store the write bits.
1555 * @param cbWrite Number of bytes to write.
1556 * @thread Any thread.
1557 */
1558 DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMICHARCONNECTOR pInterface, const void *pvBuf, size_t cbWrite));
1559
1560 /**
1561 * Set device parameters.
1562 *
1563 * @returns VBox status code.
1564 * @param pInterface Pointer to the interface structure containing the called function pointer.
1565 * @param Bps Speed of the serial connection. (bits per second)
1566 * @param chParity Parity method: 'E' - even, 'O' - odd, 'N' - none.
1567 * @param cDataBits Number of data bits.
1568 * @param cStopBits Number of stop bits.
1569 * @thread Any thread.
1570 */
1571 DECLR3CALLBACKMEMBER(int, pfnSetParameters,(PPDMICHARCONNECTOR pInterface, unsigned Bps, char chParity, unsigned cDataBits, unsigned cStopBits));
1572
1573 /**
1574 * Set the state of the modem lines.
1575 *
1576 * @returns VBox status code.
1577 * @param pInterface Pointer to the interface structure containing the called function pointer.
1578 * @param fRequestToSend Set to true to make the Request to Send line active otherwise to 0.
1579 * @param fDataTerminalReady Set to true to make the Data Terminal Ready line active otherwise 0.
1580 * @thread Any thread.
1581 */
1582 DECLR3CALLBACKMEMBER(int, pfnSetModemLines,(PPDMICHARCONNECTOR pInterface, bool fRequestToSend, bool fDataTerminalReady));
1583
1584 /**
1585 * Sets the TD line into break condition.
1586 *
1587 * @returns VBox status code.
1588 * @param pInterface Pointer to the interface structure containing the called function pointer.
1589 * @param fBreak Set to true to let the device send a break false to put into normal operation.
1590 * @thread Any thread.
1591 */
1592 DECLR3CALLBACKMEMBER(int, pfnSetBreak,(PPDMICHARCONNECTOR pInterface, bool fBreak));
1593} PDMICHARCONNECTOR;
1594/** PDMICHARCONNECTOR interface ID. */
1595#define PDMICHARCONNECTOR_IID "4ad5c190-b408-4cef-926f-fbffce0dc5cc"
1596
1597
1598/** Pointer to a stream interface. */
1599typedef struct PDMISTREAM *PPDMISTREAM;
1600/**
1601 * Stream interface (up).
1602 * Makes up the foundation for PDMICHARCONNECTOR. No pair interface.
1603 */
1604typedef struct PDMISTREAM
1605{
1606 /**
1607 * Read bits.
1608 *
1609 * @returns VBox status code.
1610 * @param pInterface Pointer to the interface structure containing the called function pointer.
1611 * @param pvBuf Where to store the read bits.
1612 * @param cbRead Number of bytes to read/bytes actually read.
1613 * @thread Any thread.
1614 */
1615 DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMISTREAM pInterface, void *pvBuf, size_t *cbRead));
1616
1617 /**
1618 * Write bits.
1619 *
1620 * @returns VBox status code.
1621 * @param pInterface Pointer to the interface structure containing the called function pointer.
1622 * @param pvBuf Where to store the write bits.
1623 * @param cbWrite Number of bytes to write/bytes actually written.
1624 * @thread Any thread.
1625 */
1626 DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMISTREAM pInterface, const void *pvBuf, size_t *cbWrite));
1627} PDMISTREAM;
1628/** PDMISTREAM interface ID. */
1629#define PDMISTREAM_IID "d1a5bf5e-3d2c-449a-bde9-addd7920b71f"
1630
1631
1632/** Mode of the parallel port */
1633typedef enum PDMPARALLELPORTMODE
1634{
1635 PDM_PARALLEL_PORT_MODE_COMPAT,
1636 PDM_PARALLEL_PORT_MODE_EPP,
1637 PDM_PARALLEL_PORT_MODE_ECP
1638} PDMPARALLELPORTMODE;
1639
1640/** Pointer to a host parallel port interface. */
1641typedef struct PDMIHOSTPARALLELPORT *PPDMIHOSTPARALLELPORT;
1642/**
1643 * Host parallel port interface (down).
1644 * Pair with PDMIHOSTPARALLELCONNECTOR.
1645 */
1646typedef struct PDMIHOSTPARALLELPORT
1647{
1648 /**
1649 * Deliver data read to the device/driver.
1650 *
1651 * @returns VBox status code.
1652 * @param pInterface Pointer to the interface structure containing the called function pointer.
1653 * @param pvBuf Where the read bits are stored.
1654 * @param pcbRead Number of bytes available for reading/having been read.
1655 * @thread Any thread.
1656 */
1657 DECLR3CALLBACKMEMBER(int, pfnNotifyRead,(PPDMIHOSTPARALLELPORT pInterface, const void *pvBuf, size_t *pcbRead));
1658
1659 /**
1660 * Notify device/driver that an interrupt has occured.
1661 *
1662 * @returns VBox status code.
1663 * @param pInterface Pointer to the interface structure containing the called function pointer.
1664 * @thread Any thread.
1665 */
1666 DECLR3CALLBACKMEMBER(int, pfnNotifyInterrupt,(PPDMIHOSTPARALLELPORT pInterface));
1667} PDMIHOSTPARALLELPORT;
1668/** PDMIHOSTPARALLELPORT interface ID. */
1669#define PDMIHOSTPARALLELPORT_IID "ac13e437-cd30-47ac-a271-6120571f3a22"
1670
1671
1672
1673/** Pointer to a Host Parallel connector interface. */
1674typedef struct PDMIHOSTPARALLELCONNECTOR *PPDMIHOSTPARALLELCONNECTOR;
1675/**
1676 * Host parallel connector interface (up).
1677 * Pair with PDMIHOSTPARALLELPORT.
1678 */
1679typedef struct PDMIHOSTPARALLELCONNECTOR
1680{
1681 /**
1682 * Write bits.
1683 *
1684 * @returns VBox status code.
1685 * @param pInterface Pointer to the interface structure containing the called function pointer.
1686 * @param pvBuf Where to store the write bits.
1687 * @param pcbWrite Number of bytes to write/bytes actually written.
1688 * @thread Any thread.
1689 */
1690 DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMIHOSTPARALLELCONNECTOR pInterface, const void *pvBuf, size_t *pcbWrite));
1691
1692 /**
1693 * Read bits.
1694 *
1695 * @returns VBox status code.
1696 * @param pInterface Pointer to the interface structure containing the called function pointer.
1697 * @param pvBuf Where to store the read bits.
1698 * @param pcbRead Number of bytes to read/bytes actually read.
1699 * @thread Any thread.
1700 */
1701 DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMIHOSTPARALLELCONNECTOR pInterface, void *pvBuf, size_t *pcbRead));
1702
1703 /**
1704 * Write control register bits.
1705 *
1706 * @returns VBox status code.
1707 * @param pInterface Pointer to the interface structure containing the called function pointer.
1708 * @param fReg The new control register value.
1709 * @thread Any thread.
1710 */
1711 DECLR3CALLBACKMEMBER(int, pfnWriteControl,(PPDMIHOSTPARALLELCONNECTOR pInterface, uint8_t fReg));
1712
1713 /**
1714 * Read control register bits.
1715 *
1716 * @returns VBox status code.
1717 * @param pInterface Pointer to the interface structure containing the called function pointer.
1718 * @param pfReg Where to store the control register bits.
1719 * @thread Any thread.
1720 */
1721 DECLR3CALLBACKMEMBER(int, pfnReadControl,(PPDMIHOSTPARALLELCONNECTOR pInterface, uint8_t *pfReg));
1722
1723 /**
1724 * Read status register bits.
1725 *
1726 * @returns VBox status code.
1727 * @param pInterface Pointer to the interface structure containing the called function pointer.
1728 * @param pfReg Where to store the status register bits.
1729 * @thread Any thread.
1730 */
1731 DECLR3CALLBACKMEMBER(int, pfnReadStatus,(PPDMIHOSTPARALLELCONNECTOR pInterface, uint8_t *pfReg));
1732
1733 /**
1734 * Set mode of the host parallel port.
1735 *
1736 * @returns VBox status code.
1737 * @param pInterface Pointer to the interface structure containing the called function pointer.
1738 * @param enmMode The mode of the host parallel port.
1739 * @thread Any thread.
1740 */
1741 DECLR3CALLBACKMEMBER(int, pfnSetMode,(PPDMIHOSTPARALLELCONNECTOR pInterface, PDMPARALLELPORTMODE enmMode));
1742} PDMIHOSTPARALLELCONNECTOR;
1743/** PDMIHOSTPARALLELCONNECTOR interface ID. */
1744#define PDMIHOSTPARALLELCONNECTOR_IID "a03567ca-b29e-4a1b-b2f3-a12435fa2982"
1745
1746
1747/** ACPI power source identifier */
1748typedef enum PDMACPIPOWERSOURCE
1749{
1750 PDM_ACPI_POWER_SOURCE_UNKNOWN = 0,
1751 PDM_ACPI_POWER_SOURCE_OUTLET,
1752 PDM_ACPI_POWER_SOURCE_BATTERY
1753} PDMACPIPOWERSOURCE;
1754/** Pointer to ACPI battery state. */
1755typedef PDMACPIPOWERSOURCE *PPDMACPIPOWERSOURCE;
1756
1757/** ACPI battey capacity */
1758typedef enum PDMACPIBATCAPACITY
1759{
1760 PDM_ACPI_BAT_CAPACITY_MIN = 0,
1761 PDM_ACPI_BAT_CAPACITY_MAX = 100,
1762 PDM_ACPI_BAT_CAPACITY_UNKNOWN = 255
1763} PDMACPIBATCAPACITY;
1764/** Pointer to ACPI battery capacity. */
1765typedef PDMACPIBATCAPACITY *PPDMACPIBATCAPACITY;
1766
1767/** ACPI battery state. See ACPI 3.0 spec '_BST (Battery Status)' */
1768typedef enum PDMACPIBATSTATE
1769{
1770 PDM_ACPI_BAT_STATE_CHARGED = 0x00,
1771 PDM_ACPI_BAT_STATE_DISCHARGING = 0x01,
1772 PDM_ACPI_BAT_STATE_CHARGING = 0x02,
1773 PDM_ACPI_BAT_STATE_CRITICAL = 0x04
1774} PDMACPIBATSTATE;
1775/** Pointer to ACPI battery state. */
1776typedef PDMACPIBATSTATE *PPDMACPIBATSTATE;
1777
1778/** Pointer to an ACPI port interface. */
1779typedef struct PDMIACPIPORT *PPDMIACPIPORT;
1780/**
1781 * ACPI port interface (down). Used by both the ACPI driver and (grumble) main.
1782 * Pair with PDMIACPICONNECTOR.
1783 */
1784typedef struct PDMIACPIPORT
1785{
1786 /**
1787 * Send an ACPI power off event.
1788 *
1789 * @returns VBox status code
1790 * @param pInterface Pointer to the interface structure containing the called function pointer.
1791 */
1792 DECLR3CALLBACKMEMBER(int, pfnPowerButtonPress,(PPDMIACPIPORT pInterface));
1793
1794 /**
1795 * Send an ACPI sleep button event.
1796 *
1797 * @returns VBox status code
1798 * @param pInterface Pointer to the interface structure containing the called function pointer.
1799 */
1800 DECLR3CALLBACKMEMBER(int, pfnSleepButtonPress,(PPDMIACPIPORT pInterface));
1801
1802 /**
1803 * Check if the last power button event was handled by the guest.
1804 *
1805 * @returns VBox status code
1806 * @param pInterface Pointer to the interface structure containing the called function pointer.
1807 * @param pfHandled Is set to true if the last power button event was handled, false otherwise.
1808 */
1809 DECLR3CALLBACKMEMBER(int, pfnGetPowerButtonHandled,(PPDMIACPIPORT pInterface, bool *pfHandled));
1810
1811 /**
1812 * Check if the guest entered the ACPI mode.
1813 *
1814 * @returns VBox status code
1815 * @param pInterface Pointer to the interface structure containing the called function pointer.
1816 * @param pfEnabled Is set to true if the guest entered the ACPI mode, false otherwise.
1817 */
1818 DECLR3CALLBACKMEMBER(int, pfnGetGuestEnteredACPIMode,(PPDMIACPIPORT pInterface, bool *pfEntered));
1819
1820 /**
1821 * Check if the given CPU is still locked by the guest.
1822 *
1823 * @returns VBox status code
1824 * @param pInterface Pointer to the interface structure containing the called function pointer.
1825 * @param uCpu The CPU to check for.
1826 * @param pfLocked Is set to true if the CPU is still locked by the guest, false otherwise.
1827 */
1828 DECLR3CALLBACKMEMBER(int, pfnGetCpuStatus,(PPDMIACPIPORT pInterface, unsigned uCpu, bool *pfLocked));
1829} PDMIACPIPORT;
1830/** PDMIACPIPORT interface ID. */
1831#define PDMIACPIPORT_IID "30d3dc4c-6a73-40c8-80e9-34309deacbb3"
1832
1833
1834/** Pointer to an ACPI connector interface. */
1835typedef struct PDMIACPICONNECTOR *PPDMIACPICONNECTOR;
1836/**
1837 * ACPI connector interface (up).
1838 * Pair with PDMIACPIPORT.
1839 */
1840typedef struct PDMIACPICONNECTOR
1841{
1842 /**
1843 * Get the current power source of the host system.
1844 *
1845 * @returns VBox status code
1846 * @param pInterface Pointer to the interface structure containing the called function pointer.
1847 * @param penmPowerSource Pointer to the power source result variable.
1848 */
1849 DECLR3CALLBACKMEMBER(int, pfnQueryPowerSource,(PPDMIACPICONNECTOR, PPDMACPIPOWERSOURCE penmPowerSource));
1850
1851 /**
1852 * Query the current battery status of the host system.
1853 *
1854 * @returns VBox status code?
1855 * @param pInterface Pointer to the interface structure containing the called function pointer.
1856 * @param pfPresent Is set to true if battery is present, false otherwise.
1857 * @param penmRemainingCapacity Pointer to the battery remaining capacity (0 - 100 or 255 for unknown).
1858 * @param penmBatteryState Pointer to the battery status.
1859 * @param pu32PresentRate Pointer to the present rate (0..1000 of the total capacity).
1860 */
1861 DECLR3CALLBACKMEMBER(int, pfnQueryBatteryStatus,(PPDMIACPICONNECTOR, bool *pfPresent, PPDMACPIBATCAPACITY penmRemainingCapacity,
1862 PPDMACPIBATSTATE penmBatteryState, uint32_t *pu32PresentRate));
1863} PDMIACPICONNECTOR;
1864/** PDMIACPICONNECTOR interface ID. */
1865#define PDMIACPICONNECTOR_IID "5f14bf8d-1edf-4e3a-a1e1-cca9fd08e359"
1866
1867
1868/** Pointer to a VMMDevice port interface. */
1869typedef struct PDMIVMMDEVPORT *PPDMIVMMDEVPORT;
1870/**
1871 * VMMDevice port interface (down).
1872 * Pair with PDMIVMMDEVCONNECTOR.
1873 */
1874typedef struct PDMIVMMDEVPORT
1875{
1876 /**
1877 * Return the current absolute mouse position in pixels
1878 *
1879 * @returns VBox status code
1880 * @param pAbsX Pointer of result value, can be NULL
1881 * @param pAbsY Pointer of result value, can be NULL
1882 */
1883 DECLR3CALLBACKMEMBER(int, pfnQueryAbsoluteMouse,(PPDMIVMMDEVPORT pInterface, uint32_t *pAbsX, uint32_t *pAbsY));
1884
1885 /**
1886 * Set the new absolute mouse position in pixels
1887 *
1888 * @returns VBox status code
1889 * @param absX New absolute X position
1890 * @param absY New absolute Y position
1891 */
1892 DECLR3CALLBACKMEMBER(int, pfnSetAbsoluteMouse,(PPDMIVMMDEVPORT pInterface, uint32_t absX, uint32_t absY));
1893
1894 /**
1895 * Return the current mouse capability flags
1896 *
1897 * @returns VBox status code
1898 * @param pCapabilities Pointer of result value
1899 */
1900 DECLR3CALLBACKMEMBER(int, pfnQueryMouseCapabilities,(PPDMIVMMDEVPORT pInterface, uint32_t *pCapabilities));
1901
1902 /**
1903 * Set the current mouse capability flag (host side)
1904 *
1905 * @returns VBox status code
1906 * @param capabilities Capability mask
1907 */
1908 DECLR3CALLBACKMEMBER(int, pfnSetMouseCapabilities,(PPDMIVMMDEVPORT pInterface, uint32_t capabilities));
1909
1910 /**
1911 * Issue a display resolution change request.
1912 *
1913 * Note that there can only one request in the queue and that in case the guest does
1914 * not process it, issuing another request will overwrite the previous.
1915 *
1916 * @returns VBox status code
1917 * @param cx Horizontal pixel resolution (0 = do not change).
1918 * @param cy Vertical pixel resolution (0 = do not change).
1919 * @param cBits Bits per pixel (0 = do not change).
1920 * @param display The display index.
1921 */
1922 DECLR3CALLBACKMEMBER(int, pfnRequestDisplayChange,(PPDMIVMMDEVPORT pInterface, uint32_t cx, uint32_t cy, uint32_t cBits, uint32_t display));
1923
1924 /**
1925 * Pass credentials to guest.
1926 *
1927 * Note that there can only be one set of credentials and the guest may or may not
1928 * query them and may do whatever it wants with them.
1929 *
1930 * @returns VBox status code.
1931 * @param pszUsername User name, may be empty (UTF-8).
1932 * @param pszPassword Password, may be empty (UTF-8).
1933 * @param pszDomain Domain name, may be empty (UTF-8).
1934 * @param fFlags VMMDEV_SETCREDENTIALS_*.
1935 */
1936 DECLR3CALLBACKMEMBER(int, pfnSetCredentials,(PPDMIVMMDEVPORT pInterface, const char *pszUsername,
1937 const char *pszPassword, const char *pszDomain,
1938 uint32_t fFlags));
1939
1940 /**
1941 * Notify the driver about a VBVA status change.
1942 *
1943 * @returns Nothing. Because it is informational callback.
1944 * @param fEnabled Current VBVA status.
1945 */
1946 DECLR3CALLBACKMEMBER(void, pfnVBVAChange, (PPDMIVMMDEVPORT pInterface, bool fEnabled));
1947
1948 /**
1949 * Issue a seamless mode change request.
1950 *
1951 * Note that there can only one request in the queue and that in case the guest does
1952 * not process it, issuing another request will overwrite the previous.
1953 *
1954 * @returns VBox status code
1955 * @param fEnabled Seamless mode enabled or not
1956 */
1957 DECLR3CALLBACKMEMBER(int, pfnRequestSeamlessChange,(PPDMIVMMDEVPORT pInterface, bool fEnabled));
1958
1959 /**
1960 * Issue a memory balloon change request.
1961 *
1962 * Note that there can only one request in the queue and that in case the guest does
1963 * not process it, issuing another request will overwrite the previous.
1964 *
1965 * @returns VBox status code
1966 * @param ulBalloonSize Balloon size in megabytes
1967 */
1968 DECLR3CALLBACKMEMBER(int, pfnSetMemoryBalloon,(PPDMIVMMDEVPORT pInterface, uint32_t ulBalloonSize));
1969
1970 /**
1971 * Issue a statistcs interval change request.
1972 *
1973 * Note that there can only one request in the queue and that in case the guest does
1974 * not process it, issuing another request will overwrite the previous.
1975 *
1976 * @returns VBox status code
1977 * @param ulStatInterval Statistics query interval in seconds (0=disable)
1978 */
1979 DECLR3CALLBACKMEMBER(int, pfnSetStatisticsInterval,(PPDMIVMMDEVPORT pInterface, uint32_t ulStatInterval));
1980
1981 /**
1982 * Notify the guest about a VRDP status change.
1983 *
1984 * @returns VBox status code
1985 * @param fVRDPEnabled Current VRDP status.
1986 * @param u32VRDPExperienceLevel Which visual effects to be disabled in the guest.
1987 */
1988 DECLR3CALLBACKMEMBER(int, pfnVRDPChange, (PPDMIVMMDEVPORT pInterface, bool fVRDPEnabled, uint32_t u32VRDPExperienceLevel));
1989
1990 /**
1991 * Notify the guest of CPU hot-unplug event.
1992 *
1993 * @returns VBox status code
1994 * @param idCpuCore The core id of the CPU to remove.
1995 * @param idCpuPackage The package id of the CPU to remove.
1996 */
1997 DECLR3CALLBACKMEMBER(int, pfnCpuHotUnplug, (PPDMIVMMDEVPORT pInterface, uint32_t idCpuCore, uint32_t idCpuPackage));
1998
1999 /**
2000 * Notify the guest of CPU hot-plug event.
2001 *
2002 * @returns VBox status code
2003 * @param idCpuCore The core id of the CPU to add.
2004 * @param idCpuPackage The package id of the CPU to add.
2005 */
2006 DECLR3CALLBACKMEMBER(int, pfnCpuHotPlug, (PPDMIVMMDEVPORT pInterface, uint32_t idCpuCore, uint32_t idCpuPackage));
2007
2008} PDMIVMMDEVPORT;
2009/** PDMIVMMDEVPORT interface ID. */
2010#define PDMIVMMDEVPORT_IID "d7e52035-3b6c-422e-9215-2a75646a945d"
2011
2012
2013/** Pointer to a HPET legacy notifcation interface. */
2014typedef struct PDMIHPETLEGACYNOTIFY *PPDMIHPETLEGACYNOTIFY;
2015/**
2016 * HPET legacy notifcation interface.
2017 */
2018typedef struct PDMIHPETLEGACYNOTIFY
2019{
2020 /**
2021 * Notify about change of HPET legacy mode.
2022 *
2023 * @param pInterface Pointer to the interface structure containing the
2024 * called function pointer.
2025 * @param fActivated If HPET legacy mode is activated (@c true) or
2026 * deactivated (@c false).
2027 */
2028 DECLR3CALLBACKMEMBER(void, pfnModeChanged,(PPDMIHPETLEGACYNOTIFY pInterface, bool fActivated));
2029} PDMIHPETLEGACYNOTIFY;
2030/** PDMIHPETLEGACYNOTIFY interface ID. */
2031#define PDMIHPETLEGACYNOTIFY_IID "c9ada595-4b65-4311-8b21-b10498997774"
2032
2033
2034/** @name Flags for PDMIVMMDEVPORT::pfnSetCredentials.
2035 * @{ */
2036/** The guest should perform a logon with the credentials. */
2037#define VMMDEV_SETCREDENTIALS_GUESTLOGON RT_BIT(0)
2038/** The guest should prevent local logons. */
2039#define VMMDEV_SETCREDENTIALS_NOLOCALLOGON RT_BIT(1)
2040/** The guest should verify the credentials. */
2041#define VMMDEV_SETCREDENTIALS_JUDGE RT_BIT(15)
2042/** @} */
2043
2044
2045/** Forward declaration of the video accelerator command memory. */
2046struct VBVAMEMORY;
2047/** Forward declaration of the guest information structure. */
2048struct VBoxGuestInfo;
2049/** Forward declaration of the guest statistics structure */
2050struct VBoxGuestStatistics;
2051/** Pointer to video accelerator command memory. */
2052typedef struct VBVAMEMORY *PVBVAMEMORY;
2053
2054/** Pointer to a VMMDev connector interface. */
2055typedef struct PDMIVMMDEVCONNECTOR *PPDMIVMMDEVCONNECTOR;
2056/**
2057 * VMMDev connector interface (up).
2058 * Pair with PDMIVMMDEVPORT.
2059 */
2060typedef struct PDMIVMMDEVCONNECTOR
2061{
2062 /**
2063 * Report guest OS version.
2064 * Called whenever the Additions issue a guest version report request.
2065 *
2066 * @param pInterface Pointer to this interface.
2067 * @param pGuestInfo Pointer to guest information structure
2068 * @thread The emulation thread.
2069 */
2070 DECLR3CALLBACKMEMBER(void, pfnUpdateGuestVersion,(PPDMIVMMDEVCONNECTOR pInterface, struct VBoxGuestInfo *pGuestInfo));
2071
2072 /**
2073 * Update the guest additions capabilities.
2074 * This is called when the guest additions capabilities change. The new capabilities
2075 * are given and the connector should update its internal state.
2076 *
2077 * @param pInterface Pointer to this interface.
2078 * @param newCapabilities New capabilities.
2079 * @thread The emulation thread.
2080 */
2081 DECLR3CALLBACKMEMBER(void, pfnUpdateGuestCapabilities,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t newCapabilities));
2082
2083 /**
2084 * Update the mouse capabilities.
2085 * This is called when the mouse capabilities change. The new capabilities
2086 * are given and the connector should update its internal state.
2087 *
2088 * @param pInterface Pointer to this interface.
2089 * @param newCapabilities New capabilities.
2090 * @thread The emulation thread.
2091 */
2092 DECLR3CALLBACKMEMBER(void, pfnUpdateMouseCapabilities,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t newCapabilities));
2093
2094 /**
2095 * Update the pointer shape.
2096 * This is called when the mouse pointer shape changes. The new shape
2097 * is passed as a caller allocated buffer that will be freed after returning
2098 *
2099 * @param pInterface Pointer to this interface.
2100 * @param fVisible Visibility indicator (if false, the other parameters are undefined).
2101 * @param fAlpha Flag whether alpha channel is being passed.
2102 * @param xHot Pointer hot spot x coordinate.
2103 * @param yHot Pointer hot spot y coordinate.
2104 * @param x Pointer new x coordinate on screen.
2105 * @param y Pointer new y coordinate on screen.
2106 * @param cx Pointer width in pixels.
2107 * @param cy Pointer height in pixels.
2108 * @param cbScanline Size of one scanline in bytes.
2109 * @param pvShape New shape buffer.
2110 * @thread The emulation thread.
2111 */
2112 DECLR3CALLBACKMEMBER(void, pfnUpdatePointerShape,(PPDMIVMMDEVCONNECTOR pInterface, bool fVisible, bool fAlpha,
2113 uint32_t xHot, uint32_t yHot,
2114 uint32_t cx, uint32_t cy,
2115 void *pvShape));
2116
2117 /**
2118 * Enable or disable video acceleration on behalf of guest.
2119 *
2120 * @param pInterface Pointer to this interface.
2121 * @param fEnable Whether to enable acceleration.
2122 * @param pVbvaMemory Video accelerator memory.
2123
2124 * @return VBox rc. VINF_SUCCESS if VBVA was enabled.
2125 * @thread The emulation thread.
2126 */
2127 DECLR3CALLBACKMEMBER(int, pfnVideoAccelEnable,(PPDMIVMMDEVCONNECTOR pInterface, bool fEnable, PVBVAMEMORY pVbvaMemory));
2128
2129 /**
2130 * Force video queue processing.
2131 *
2132 * @param pInterface Pointer to this interface.
2133 * @thread The emulation thread.
2134 */
2135 DECLR3CALLBACKMEMBER(void, pfnVideoAccelFlush,(PPDMIVMMDEVCONNECTOR pInterface));
2136
2137 /**
2138 * Return whether the given video mode is supported/wanted by the host.
2139 *
2140 * @returns VBox status code
2141 * @param pInterface Pointer to this interface.
2142 * @param cy Video mode horizontal resolution in pixels.
2143 * @param cx Video mode vertical resolution in pixels.
2144 * @param cBits Video mode bits per pixel.
2145 * @param pfSupported Where to put the indicator for whether this mode is supported. (output)
2146 * @thread The emulation thread.
2147 */
2148 DECLR3CALLBACKMEMBER(int, pfnVideoModeSupported,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t cx, uint32_t cy, uint32_t cBits, bool *pfSupported));
2149
2150 /**
2151 * Queries by how many pixels the height should be reduced when calculating video modes
2152 *
2153 * @returns VBox status code
2154 * @param pInterface Pointer to this interface.
2155 * @param pcyReduction Pointer to the result value.
2156 * @thread The emulation thread.
2157 */
2158 DECLR3CALLBACKMEMBER(int, pfnGetHeightReduction,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t *pcyReduction));
2159
2160 /**
2161 * Informs about a credentials judgement result from the guest.
2162 *
2163 * @returns VBox status code
2164 * @param pInterface Pointer to this interface.
2165 * @param fFlags Judgement result flags.
2166 * @thread The emulation thread.
2167 */
2168 DECLR3CALLBACKMEMBER(int, pfnSetCredentialsJudgementResult,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t fFlags));
2169
2170 /**
2171 * Set the visible region of the display
2172 *
2173 * @returns VBox status code.
2174 * @param pInterface Pointer to this interface.
2175 * @param cRect Number of rectangles in pRect
2176 * @param pRect Rectangle array
2177 * @thread The emulation thread.
2178 */
2179 DECLR3CALLBACKMEMBER(int, pfnSetVisibleRegion,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t cRect, PRTRECT pRect));
2180
2181 /**
2182 * Query the visible region of the display
2183 *
2184 * @returns VBox status code.
2185 * @param pInterface Pointer to this interface.
2186 * @param pcRect Number of rectangles in pRect
2187 * @param pRect Rectangle array (set to NULL to query the number of rectangles)
2188 * @thread The emulation thread.
2189 */
2190 DECLR3CALLBACKMEMBER(int, pfnQueryVisibleRegion,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t *pcRect, PRTRECT pRect));
2191
2192 /**
2193 * Request the statistics interval
2194 *
2195 * @returns VBox status code.
2196 * @param pInterface Pointer to this interface.
2197 * @param pulInterval Pointer to interval in seconds
2198 * @thread The emulation thread.
2199 */
2200 DECLR3CALLBACKMEMBER(int, pfnQueryStatisticsInterval,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t *pulInterval));
2201
2202 /**
2203 * Report new guest statistics
2204 *
2205 * @returns VBox status code.
2206 * @param pInterface Pointer to this interface.
2207 * @param pGuestStats Guest statistics
2208 * @thread The emulation thread.
2209 */
2210 DECLR3CALLBACKMEMBER(int, pfnReportStatistics,(PPDMIVMMDEVCONNECTOR pInterface, struct VBoxGuestStatistics *pGuestStats));
2211
2212 /**
2213 * Query the current balloon size
2214 *
2215 * @returns VBox status code.
2216 * @param pInterface Pointer to this interface.
2217 * @param pcbBalloon Balloon size
2218 * @thread The emulation thread.
2219 */
2220 DECLR3CALLBACKMEMBER(int, pfnQueryBalloonSize,(PPDMIVMMDEVCONNECTOR pInterface, uint32_t *pcbBalloon));
2221
2222} PDMIVMMDEVCONNECTOR;
2223/** PDMIVMMDEVCONNECTOR interface ID. */
2224#define PDMIVMMDEVCONNECTOR_IID "5c35e324-2b02-49b7-a613-119fbf3320a9"
2225
2226
2227/** Pointer to a network connector interface */
2228typedef struct PDMIAUDIOCONNECTOR *PPDMIAUDIOCONNECTOR;
2229/**
2230 * Audio connector interface (up).
2231 * No interface pair yet.
2232 */
2233typedef struct PDMIAUDIOCONNECTOR
2234{
2235 DECLR3CALLBACKMEMBER(void, pfnRun,(PPDMIAUDIOCONNECTOR pInterface));
2236
2237/* DECLR3CALLBACKMEMBER(int, pfnSetRecordSource,(PPDMIAUDIOINCONNECTOR pInterface, AUDIORECSOURCE)); */
2238
2239} PDMIAUDIOCONNECTOR;
2240/** PDMIAUDIOCONNECTOR interface ID. */
2241#define PDMIAUDIOCONNECTOR_IID "85d52af5-b3aa-4b3e-b176-4b5ebfc52f47"
2242
2243
2244/** @todo r=bird: the two following interfaces are hacks to work around the missing audio driver
2245 * interface. This should be addressed rather than making more temporary hacks. */
2246
2247/** Pointer to a Audio Sniffer Device port interface. */
2248typedef struct PDMIAUDIOSNIFFERPORT *PPDMIAUDIOSNIFFERPORT;
2249/**
2250 * Audio Sniffer port interface (down).
2251 * Pair with PDMIAUDIOSNIFFERCONNECTOR.
2252 */
2253typedef struct PDMIAUDIOSNIFFERPORT
2254{
2255 /**
2256 * Enables or disables sniffing.
2257 *
2258 * If sniffing is being enabled also sets a flag whether the audio must be also
2259 * left on the host.
2260 *
2261 * @returns VBox status code
2262 * @param pInterface Pointer to this interface.
2263 * @param fEnable 'true' for enable sniffing, 'false' to disable.
2264 * @param fKeepHostAudio Indicates whether host audio should also present
2265 * 'true' means that sound should not be played
2266 * by the audio device.
2267 */
2268 DECLR3CALLBACKMEMBER(int, pfnSetup,(PPDMIAUDIOSNIFFERPORT pInterface, bool fEnable, bool fKeepHostAudio));
2269
2270} PDMIAUDIOSNIFFERPORT;
2271/** PDMIAUDIOSNIFFERPORT interface ID. */
2272#define PDMIAUDIOSNIFFERPORT_IID "83b95e02-68cb-470d-9dfc-25a0f8efe197"
2273
2274
2275/** Pointer to a Audio Sniffer connector interface. */
2276typedef struct PDMIAUDIOSNIFFERCONNECTOR *PPDMIAUDIOSNIFFERCONNECTOR;
2277
2278/**
2279 * Audio Sniffer connector interface (up).
2280 * Pair with PDMIAUDIOSNIFFERPORT.
2281 */
2282typedef struct PDMIAUDIOSNIFFERCONNECTOR
2283{
2284 /**
2285 * AudioSniffer device calls this method when audio samples
2286 * are about to be played and sniffing is enabled.
2287 *
2288 * @param pInterface Pointer to this interface.
2289 * @param pvSamples Audio samples buffer.
2290 * @param cSamples How many complete samples are in the buffer.
2291 * @param iSampleHz The sample frequency in Hz.
2292 * @param cChannels Number of channels. 1 for mono, 2 for stereo.
2293 * @param cBits How many bits a sample for a single channel has. Normally 8 or 16.
2294 * @param fUnsigned Whether samples are unsigned values.
2295 * @thread The emulation thread.
2296 */
2297 DECLR3CALLBACKMEMBER(void, pfnAudioSamplesOut,(PPDMIAUDIOSNIFFERCONNECTOR pInterface, void *pvSamples, uint32_t cSamples,
2298 int iSampleHz, int cChannels, int cBits, bool fUnsigned));
2299
2300 /**
2301 * AudioSniffer device calls this method when output volume is changed.
2302 *
2303 * @param pInterface Pointer to this interface.
2304 * @param u16LeftVolume 0..0xFFFF volume level for left channel.
2305 * @param u16RightVolume 0..0xFFFF volume level for right channel.
2306 * @thread The emulation thread.
2307 */
2308 DECLR3CALLBACKMEMBER(void, pfnAudioVolumeOut,(PPDMIAUDIOSNIFFERCONNECTOR pInterface, uint16_t u16LeftVolume, uint16_t u16RightVolume));
2309
2310} PDMIAUDIOSNIFFERCONNECTOR;
2311/** PDMIAUDIOSNIFFERCONNECTOR - The Audio Sniffer Driver connector interface. */
2312#define PDMIAUDIOSNIFFERCONNECTOR_IID "433b64ab-e603-4933-bc97-8fe79b2bd0e0"
2313
2314
2315/**
2316 * Generic status LED core.
2317 * Note that a unit doesn't have to support all the indicators.
2318 */
2319typedef union PDMLEDCORE
2320{
2321 /** 32-bit view. */
2322 uint32_t volatile u32;
2323 /** Bit view. */
2324 struct
2325 {
2326 /** Reading/Receiving indicator. */
2327 uint32_t fReading : 1;
2328 /** Writing/Sending indicator. */
2329 uint32_t fWriting : 1;
2330 /** Busy indicator. */
2331 uint32_t fBusy : 1;
2332 /** Error indicator. */
2333 uint32_t fError : 1;
2334 } s;
2335} PDMLEDCORE;
2336
2337/** LED bit masks for the u32 view.
2338 * @{ */
2339/** Reading/Receiving indicator. */
2340#define PDMLED_READING RT_BIT(0)
2341/** Writing/Sending indicator. */
2342#define PDMLED_WRITING RT_BIT(1)
2343/** Busy indicator. */
2344#define PDMLED_BUSY RT_BIT(2)
2345/** Error indicator. */
2346#define PDMLED_ERROR RT_BIT(3)
2347/** @} */
2348
2349
2350/**
2351 * Generic status LED.
2352 * Note that a unit doesn't have to support all the indicators.
2353 */
2354typedef struct PDMLED
2355{
2356 /** Just a magic for sanity checking. */
2357 uint32_t u32Magic;
2358 uint32_t u32Alignment; /**< structure size alignment. */
2359 /** The actual LED status.
2360 * Only the device is allowed to change this. */
2361 PDMLEDCORE Actual;
2362 /** The asserted LED status which is cleared by the reader.
2363 * The device will assert the bits but never clear them.
2364 * The driver clears them as it sees fit. */
2365 PDMLEDCORE Asserted;
2366} PDMLED;
2367
2368/** Pointer to an LED. */
2369typedef PDMLED *PPDMLED;
2370/** Pointer to a const LED. */
2371typedef const PDMLED *PCPDMLED;
2372
2373/** Magic value for PDMLED::u32Magic. */
2374#define PDMLED_MAGIC UINT32_C(0x11335577)
2375
2376/** Pointer to an LED ports interface. */
2377typedef struct PDMILEDPORTS *PPDMILEDPORTS;
2378/**
2379 * Interface for exporting LEDs (down).
2380 * Pair with PDMILEDCONNECTORS.
2381 */
2382typedef struct PDMILEDPORTS
2383{
2384 /**
2385 * Gets the pointer to the status LED of a unit.
2386 *
2387 * @returns VBox status code.
2388 * @param pInterface Pointer to the interface structure containing the called function pointer.
2389 * @param iLUN The unit which status LED we desire.
2390 * @param ppLed Where to store the LED pointer.
2391 */
2392 DECLR3CALLBACKMEMBER(int, pfnQueryStatusLed,(PPDMILEDPORTS pInterface, unsigned iLUN, PPDMLED *ppLed));
2393
2394} PDMILEDPORTS;
2395/** PDMILEDPORTS interface ID. */
2396#define PDMILEDPORTS_IID "435e0cec-8549-4ca0-8c0d-98e52f1dc038"
2397
2398
2399/** Pointer to an LED connectors interface. */
2400typedef struct PDMILEDCONNECTORS *PPDMILEDCONNECTORS;
2401/**
2402 * Interface for reading LEDs (up).
2403 * Pair with PDMILEDPORTS.
2404 */
2405typedef struct PDMILEDCONNECTORS
2406{
2407 /**
2408 * Notification about a unit which have been changed.
2409 *
2410 * The driver must discard any pointers to data owned by
2411 * the unit and requery it.
2412 *
2413 * @param pInterface Pointer to the interface structure containing the called function pointer.
2414 * @param iLUN The unit number.
2415 */
2416 DECLR3CALLBACKMEMBER(void, pfnUnitChanged,(PPDMILEDCONNECTORS pInterface, unsigned iLUN));
2417} PDMILEDCONNECTORS;
2418/** PDMILEDCONNECTORS interface ID. */
2419#define PDMILEDCONNECTORS_IID "8ed63568-82a7-4193-b57b-db8085ac4495"
2420
2421
2422/** The special status unit number */
2423#define PDM_STATUS_LUN 999
2424
2425
2426#ifdef VBOX_WITH_HGCM
2427
2428/** Abstract HGCM command structure. Used only to define a typed pointer. */
2429struct VBOXHGCMCMD;
2430
2431/** Pointer to HGCM command structure. This pointer is unique and identifies
2432 * the command being processed. The pointer is passed to HGCM connector methods,
2433 * and must be passed back to HGCM port when command is completed.
2434 */
2435typedef struct VBOXHGCMCMD *PVBOXHGCMCMD;
2436
2437/** Pointer to a HGCM port interface. */
2438typedef struct PDMIHGCMPORT *PPDMIHGCMPORT;
2439/**
2440 * Host-Guest communication manager port interface (down). Normally implemented
2441 * by VMMDev.
2442 * Pair with PDMIHGCMCONNECTOR.
2443 */
2444typedef struct PDMIHGCMPORT
2445{
2446 /**
2447 * Notify the guest on a command completion.
2448 *
2449 * @param pInterface Pointer to this interface.
2450 * @param rc The return code (VBox error code).
2451 * @param pCmd A pointer that identifies the completed command.
2452 *
2453 * @returns VBox status code
2454 */
2455 DECLR3CALLBACKMEMBER(void, pfnCompleted,(PPDMIHGCMPORT pInterface, int32_t rc, PVBOXHGCMCMD pCmd));
2456
2457} PDMIHGCMPORT;
2458/** PDMIHGCMPORT interface ID. */
2459# define PDMIHGCMPORT_IID "e00a0cbf-b75a-45c3-87f4-41cddbc5ae0b"
2460
2461
2462/** Pointer to a HGCM service location structure. */
2463typedef struct HGCMSERVICELOCATION *PHGCMSERVICELOCATION;
2464
2465/** Pointer to a HGCM connector interface. */
2466typedef struct PDMIHGCMCONNECTOR *PPDMIHGCMCONNECTOR;
2467/**
2468 * The Host-Guest communication manager connector interface (up). Normally
2469 * implemented by Main::VMMDevInterface.
2470 * Pair with PDMIHGCMPORT.
2471 */
2472typedef struct PDMIHGCMCONNECTOR
2473{
2474 /**
2475 * Locate a service and inform it about a client connection.
2476 *
2477 * @param pInterface Pointer to this interface.
2478 * @param pCmd A pointer that identifies the command.
2479 * @param pServiceLocation Pointer to the service location structure.
2480 * @param pu32ClientID Where to store the client id for the connection.
2481 * @return VBox status code.
2482 * @thread The emulation thread.
2483 */
2484 DECLR3CALLBACKMEMBER(int, pfnConnect,(PPDMIHGCMCONNECTOR pInterface, PVBOXHGCMCMD pCmd, PHGCMSERVICELOCATION pServiceLocation, uint32_t *pu32ClientID));
2485
2486 /**
2487 * Disconnect from service.
2488 *
2489 * @param pInterface Pointer to this interface.
2490 * @param pCmd A pointer that identifies the command.
2491 * @param u32ClientID The client id returned by the pfnConnect call.
2492 * @return VBox status code.
2493 * @thread The emulation thread.
2494 */
2495 DECLR3CALLBACKMEMBER(int, pfnDisconnect,(PPDMIHGCMCONNECTOR pInterface, PVBOXHGCMCMD pCmd, uint32_t u32ClientID));
2496
2497 /**
2498 * Process a guest issued command.
2499 *
2500 * @param pInterface Pointer to this interface.
2501 * @param pCmd A pointer that identifies the command.
2502 * @param u32ClientID The client id returned by the pfnConnect call.
2503 * @param u32Function Function to be performed by the service.
2504 * @param cParms Number of parameters in the array pointed to by paParams.
2505 * @param paParms Pointer to an array of parameters.
2506 * @return VBox status code.
2507 * @thread The emulation thread.
2508 */
2509 DECLR3CALLBACKMEMBER(int, pfnCall,(PPDMIHGCMCONNECTOR pInterface, PVBOXHGCMCMD pCmd, uint32_t u32ClientID, uint32_t u32Function,
2510 uint32_t cParms, PVBOXHGCMSVCPARM paParms));
2511
2512} PDMIHGCMCONNECTOR;
2513/** PDMIHGCMCONNECTOR interface ID. */
2514# define PDMIHGCMCONNECTOR_IID "a1104758-c888-4437-8f2a-7bac17865b5c"
2515
2516#endif /* VBOX_WITH_HGCM */
2517
2518/**
2519 * Data direction.
2520 */
2521typedef enum PDMSCSIREQUESTTXDIR
2522{
2523 PDMSCSIREQUESTTXDIR_UNKNOWN = 0x00,
2524 PDMSCSIREQUESTTXDIR_FROM_DEVICE = 0x01,
2525 PDMSCSIREQUESTTXDIR_TO_DEVICE = 0x02,
2526 PDMSCSIREQUESTTXDIR_NONE = 0x03,
2527 PDMSCSIREQUESTTXDIR_32BIT_HACK = 0x7fffffff
2528} PDMSCSIREQUESTTXDIR;
2529
2530/**
2531 * SCSI request structure.
2532 */
2533typedef struct PDMSCSIREQUEST
2534{
2535 /** The logical unit. */
2536 uint32_t uLogicalUnit;
2537 /** Direction of the data flow. */
2538 PDMSCSIREQUESTTXDIR uDataDirection;
2539 /** Size of the SCSI CDB. */
2540 uint32_t cbCDB;
2541 /** Pointer to the SCSI CDB. */
2542 uint8_t *pbCDB;
2543 /** Overall size of all scatter gather list elements
2544 * for data transfer if any. */
2545 uint32_t cbScatterGather;
2546 /** Number of elements in the scatter gather list. */
2547 uint32_t cScatterGatherEntries;
2548 /** Pointer to the head of the scatter gather list. */
2549 PRTSGSEG paScatterGatherHead;
2550 /** Size of the sense buffer. */
2551 uint32_t cbSenseBuffer;
2552 /** Pointer to the sense buffer. *
2553 * Current assumption that the sense buffer is not scattered. */
2554 uint8_t *pbSenseBuffer;
2555 /** Opaque user data for use by the device. Left untouched by everything else! */
2556 void *pvUser;
2557} PDMSCSIREQUEST, *PPDMSCSIREQUEST;
2558/** Pointer to a const SCSI request structure. */
2559typedef const PDMSCSIREQUEST *PCSCSIREQUEST;
2560
2561/** Pointer to a SCSI port interface. */
2562typedef struct PDMISCSIPORT *PPDMISCSIPORT;
2563/**
2564 * SCSI command execution port interface (down).
2565 * Pair with PDMISCSICONNECTOR.
2566 */
2567typedef struct PDMISCSIPORT
2568{
2569
2570 /**
2571 * Notify the device on request completion.
2572 *
2573 * @returns VBox status code.
2574 * @param pInterface Pointer to this interface.
2575 * @param pSCSIRequest Pointer to the finished SCSI request.
2576 * @param rcCompletion SCSI_STATUS_* code for the completed request.
2577 */
2578 DECLR3CALLBACKMEMBER(int, pfnSCSIRequestCompleted, (PPDMISCSIPORT pInterface, PPDMSCSIREQUEST pSCSIRequest, int rcCompletion));
2579
2580} PDMISCSIPORT;
2581/** PDMISCSIPORT interface ID. */
2582#define PDMISCSIPORT_IID "0f894add-714d-4a77-818e-a32fe3586ba4"
2583
2584
2585/** Pointer to a SCSI connector interface. */
2586typedef struct PDMISCSICONNECTOR *PPDMISCSICONNECTOR;
2587/**
2588 * SCSI command execution connector interface (up).
2589 * Pair with PDMISCSIPORT.
2590 */
2591typedef struct PDMISCSICONNECTOR
2592{
2593
2594 /**
2595 * Submits a SCSI request for execution.
2596 *
2597 * @returns VBox status code.
2598 * @param pInterface Pointer to this interface.
2599 * @param pSCSIRequest Pointer to the SCSI request to execute.
2600 */
2601 DECLR3CALLBACKMEMBER(int, pfnSCSIRequestSend, (PPDMISCSICONNECTOR pInterface, PPDMSCSIREQUEST pSCSIRequest));
2602
2603} PDMISCSICONNECTOR;
2604/** PDMISCSICONNECTOR interface ID. */
2605#define PDMISCSICONNECTOR_IID "94465fbd-a2f2-447e-88c9-7366421bfbfe"
2606
2607
2608/** Pointer to a display VBVA callbacks interface. */
2609typedef struct PDMIDISPLAYVBVACALLBACKS *PPDMIDISPLAYVBVACALLBACKS;
2610/**
2611 * Display VBVA callbacks interface (up).
2612 */
2613typedef struct PDMIDISPLAYVBVACALLBACKS
2614{
2615
2616 /**
2617 * Informs guest about completion of processing the given Video HW Acceleration
2618 * command, does not wait for the guest to process the command.
2619 *
2620 * @returns ???
2621 * @param pInterface Pointer to this interface.
2622 * @param pCmd The Video HW Acceleration Command that was
2623 * completed.
2624 * @todo r=bird: if asynch means asyncronous; then
2625 * s/pfnVHWACommandCompleteAsynch/pfnVHWACommandCompleteAsync/;
2626 * fi
2627 */
2628 DECLR3CALLBACKMEMBER(int, pfnVHWACommandCompleteAsynch, (PPDMIDISPLAYVBVACALLBACKS pInterface, PVBOXVHWACMD pCmd));
2629
2630} PDMIDISPLAYVBVACALLBACKS;
2631/** PDMIDISPLAYVBVACALLBACKS */
2632#define PDMIDISPLAYVBVACALLBACKS_IID "b78b81d2-c821-4e66-96ff-dbafa76343a5"
2633
2634/** @} */
2635
2636RT_C_DECLS_END
2637
2638#endif
Note: See TracBrowser for help on using the repository browser.

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