VirtualBox

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

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

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

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