VirtualBox

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

Last change on this file since 47259 was 47259, checked in by vboxsync, 11 years ago

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