VirtualBox

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

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

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

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