VirtualBox

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

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

src/VBox/Devices/Audio, src/VBox/Main/src-client, include/VBox/vmm:

src/VBox/Devices/Audio: part of restructuring of audio code. Devices files correspondin to Hda, AC97 and SB16 audio. The structure of files have been modifed as per PDM specs. The modified code is under #ifdef VBOX_WITH_PDM_AUDIO_DRIVER

src/VBox/Main/src-client: Driver for the VRDE that interacts with DrvAudio. Enhancement of the CFGM tree for audio.

Config.kmk : addition of one configuration parameter that will control whether new audio code is disabled or enabled. "VBOX_WITH_PDM_AUDIO_DRIVER"

pdmaudioifs.h: common header file between Device , Intermediate audio driver and Backends specific to audio.
  • 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#ifndef VBOX_WITH_PDM_AUDIO_DRIVER
2536/** Pointer to a network connector interface */
2537typedef struct PDMIAUDIOCONNECTOR *PPDMIAUDIOCONNECTOR;
2538/**
2539 * Audio connector interface (up).
2540 * No interface pair yet.
2541 */
2542typedef struct PDMIAUDIOCONNECTOR
2543{
2544 DECLR3CALLBACKMEMBER(void, pfnRun,(PPDMIAUDIOCONNECTOR pInterface));
2545
2546/* DECLR3CALLBACKMEMBER(int, pfnSetRecordSource,(PPDMIAUDIOINCONNECTOR pInterface, AUDIORECSOURCE)); */
2547
2548} PDMIAUDIOCONNECTOR;
2549/** PDMIAUDIOCONNECTOR interface ID. */
2550#define PDMIAUDIOCONNECTOR_IID "85d52af5-b3aa-4b3e-b176-4b5ebfc52f47"
2551
2552
2553#endif
2554/** @todo r=bird: the two following interfaces are hacks to work around the missing audio driver
2555 * interface. This should be addressed rather than making more temporary hacks. */
2556
2557/** Pointer to a Audio Sniffer Device port interface. */
2558typedef struct PDMIAUDIOSNIFFERPORT *PPDMIAUDIOSNIFFERPORT;
2559/**
2560 * Audio Sniffer port interface (down).
2561 * Pair with PDMIAUDIOSNIFFERCONNECTOR.
2562 */
2563typedef struct PDMIAUDIOSNIFFERPORT
2564{
2565 /**
2566 * Enables or disables sniffing.
2567 *
2568 * If sniffing is being enabled also sets a flag whether the audio must be also
2569 * left on the host.
2570 *
2571 * @returns VBox status code
2572 * @param pInterface Pointer to this interface.
2573 * @param fEnable 'true' for enable sniffing, 'false' to disable.
2574 * @param fKeepHostAudio Indicates whether host audio should also present
2575 * 'true' means that sound should not be played
2576 * by the audio device.
2577 */
2578 DECLR3CALLBACKMEMBER(int, pfnSetup,(PPDMIAUDIOSNIFFERPORT pInterface, bool fEnable, bool fKeepHostAudio));
2579
2580 /**
2581 * Enables or disables audio input.
2582 *
2583 * @returns VBox status code
2584 * @param pInterface Pointer to this interface.
2585 * @param fIntercept 'true' for interception of audio input,
2586 * 'false' to let the host audio backend do audio input.
2587 */
2588 DECLR3CALLBACKMEMBER(int, pfnAudioInputIntercept,(PPDMIAUDIOSNIFFERPORT pInterface, bool fIntercept));
2589
2590 /**
2591 * Audio input is about to start.
2592 *
2593 * @returns VBox status code.
2594 * @param pvContext The callback context, supplied in the
2595 * PDMIAUDIOSNIFFERCONNECTOR::pfnAudioInputBegin as pvContext.
2596 * @param iSampleHz The sample frequency in Hz.
2597 * @param cChannels Number of channels. 1 for mono, 2 for stereo.
2598 * @param cBits How many bits a sample for a single channel has. Normally 8 or 16.
2599 * @param fUnsigned Whether samples are unsigned values.
2600 */
2601 DECLR3CALLBACKMEMBER(int, pfnAudioInputEventBegin,(PPDMIAUDIOSNIFFERPORT pInterface,
2602 void *pvContext,
2603 int iSampleHz,
2604 int cChannels,
2605 int cBits,
2606 bool fUnsigned));
2607
2608 /**
2609 * Callback which delivers audio data to the audio device.
2610 *
2611 * @returns VBox status code.
2612 * @param pvContext The callback context, supplied in the
2613 * PDMIAUDIOSNIFFERCONNECTOR::pfnAudioInputBegin as pvContext.
2614 * @param pvData Event specific data.
2615 * @param cbData Size of the buffer pointed by pvData.
2616 */
2617 DECLR3CALLBACKMEMBER(int, pfnAudioInputEventData,(PPDMIAUDIOSNIFFERPORT pInterface,
2618 void *pvContext,
2619 const void *pvData,
2620 uint32_t cbData));
2621
2622 /**
2623 * Audio input ends.
2624 *
2625 * @param pvContext The callback context, supplied in the
2626 * PDMIAUDIOSNIFFERCONNECTOR::pfnAudioInputBegin as pvContext.
2627 */
2628 DECLR3CALLBACKMEMBER(void, pfnAudioInputEventEnd,(PPDMIAUDIOSNIFFERPORT pInterface,
2629 void *pvContext));
2630} PDMIAUDIOSNIFFERPORT;
2631/** PDMIAUDIOSNIFFERPORT interface ID. */
2632#define PDMIAUDIOSNIFFERPORT_IID "8ad25d78-46e9-479b-a363-bb0bc0fe022f"
2633
2634
2635/** Pointer to a Audio Sniffer connector interface. */
2636typedef struct PDMIAUDIOSNIFFERCONNECTOR *PPDMIAUDIOSNIFFERCONNECTOR;
2637
2638/**
2639 * Audio Sniffer connector interface (up).
2640 * Pair with PDMIAUDIOSNIFFERPORT.
2641 */
2642typedef struct PDMIAUDIOSNIFFERCONNECTOR
2643{
2644 /**
2645 * AudioSniffer device calls this method when audio samples
2646 * are about to be played and sniffing is enabled.
2647 *
2648 * @param pInterface Pointer to this interface.
2649 * @param pvSamples Audio samples buffer.
2650 * @param cSamples How many complete samples are in the buffer.
2651 * @param iSampleHz The sample frequency in Hz.
2652 * @param cChannels Number of channels. 1 for mono, 2 for stereo.
2653 * @param cBits How many bits a sample for a single channel has. Normally 8 or 16.
2654 * @param fUnsigned Whether samples are unsigned values.
2655 * @thread The emulation thread.
2656 */
2657 DECLR3CALLBACKMEMBER(void, pfnAudioSamplesOut,(PPDMIAUDIOSNIFFERCONNECTOR pInterface, void *pvSamples, uint32_t cSamples,
2658 int iSampleHz, int cChannels, int cBits, bool fUnsigned));
2659
2660 /**
2661 * AudioSniffer device calls this method when output volume is changed.
2662 *
2663 * @param pInterface Pointer to this interface.
2664 * @param u16LeftVolume 0..0xFFFF volume level for left channel.
2665 * @param u16RightVolume 0..0xFFFF volume level for right channel.
2666 * @thread The emulation thread.
2667 */
2668 DECLR3CALLBACKMEMBER(void, pfnAudioVolumeOut,(PPDMIAUDIOSNIFFERCONNECTOR pInterface, uint16_t u16LeftVolume, uint16_t u16RightVolume));
2669
2670 /**
2671 * Audio input has been requested by the virtual audio device.
2672 *
2673 * @param pInterface Pointer to this interface.
2674 * @param ppvUserCtx The interface context for this audio input stream,
2675 * it will be used in the pfnAudioInputEnd call.
2676 * @param pvContext The context pointer to be used in PDMIAUDIOSNIFFERPORT::pfnAudioInputEvent.
2677 * @param cSamples How many samples in a block is preferred in
2678 * PDMIAUDIOSNIFFERPORT::pfnAudioInputEvent.
2679 * @param iSampleHz The sample frequency in Hz.
2680 * @param cChannels Number of channels. 1 for mono, 2 for stereo.
2681 * @param cBits How many bits a sample for a single channel has. Normally 8 or 16.
2682 * @thread The emulation thread.
2683 */
2684 DECLR3CALLBACKMEMBER(int, pfnAudioInputBegin,(PPDMIAUDIOSNIFFERCONNECTOR pInterface,
2685 void **ppvUserCtx,
2686 void *pvContext,
2687 uint32_t cSamples,
2688 uint32_t iSampleHz,
2689 uint32_t cChannels,
2690 uint32_t cBits));
2691
2692 /**
2693 * Audio input has been requested by the virtual audio device.
2694 *
2695 * @param pInterface Pointer to this interface.
2696 * @param pvUserCtx The interface context for this audio input stream,
2697 * which was returned by pfnAudioInputBegin call.
2698 * @thread The emulation thread.
2699 */
2700 DECLR3CALLBACKMEMBER(void, pfnAudioInputEnd,(PPDMIAUDIOSNIFFERCONNECTOR pInterface,
2701 void *pvUserCtx));
2702} PDMIAUDIOSNIFFERCONNECTOR;
2703/** PDMIAUDIOSNIFFERCONNECTOR - The Audio Sniffer Driver connector interface. */
2704#define PDMIAUDIOSNIFFERCONNECTOR_IID "9d37f543-27af-45f8-8002-8ef7abac71e4"
2705
2706
2707/**
2708 * Generic status LED core.
2709 * Note that a unit doesn't have to support all the indicators.
2710 */
2711typedef union PDMLEDCORE
2712{
2713 /** 32-bit view. */
2714 uint32_t volatile u32;
2715 /** Bit view. */
2716 struct
2717 {
2718 /** Reading/Receiving indicator. */
2719 uint32_t fReading : 1;
2720 /** Writing/Sending indicator. */
2721 uint32_t fWriting : 1;
2722 /** Busy indicator. */
2723 uint32_t fBusy : 1;
2724 /** Error indicator. */
2725 uint32_t fError : 1;
2726 } s;
2727} PDMLEDCORE;
2728
2729/** LED bit masks for the u32 view.
2730 * @{ */
2731/** Reading/Receiving indicator. */
2732#define PDMLED_READING RT_BIT(0)
2733/** Writing/Sending indicator. */
2734#define PDMLED_WRITING RT_BIT(1)
2735/** Busy indicator. */
2736#define PDMLED_BUSY RT_BIT(2)
2737/** Error indicator. */
2738#define PDMLED_ERROR RT_BIT(3)
2739/** @} */
2740
2741
2742/**
2743 * Generic status LED.
2744 * Note that a unit doesn't have to support all the indicators.
2745 */
2746typedef struct PDMLED
2747{
2748 /** Just a magic for sanity checking. */
2749 uint32_t u32Magic;
2750 uint32_t u32Alignment; /**< structure size alignment. */
2751 /** The actual LED status.
2752 * Only the device is allowed to change this. */
2753 PDMLEDCORE Actual;
2754 /** The asserted LED status which is cleared by the reader.
2755 * The device will assert the bits but never clear them.
2756 * The driver clears them as it sees fit. */
2757 PDMLEDCORE Asserted;
2758} PDMLED;
2759
2760/** Pointer to an LED. */
2761typedef PDMLED *PPDMLED;
2762/** Pointer to a const LED. */
2763typedef const PDMLED *PCPDMLED;
2764
2765/** Magic value for PDMLED::u32Magic. */
2766#define PDMLED_MAGIC UINT32_C(0x11335577)
2767
2768/** Pointer to an LED ports interface. */
2769typedef struct PDMILEDPORTS *PPDMILEDPORTS;
2770/**
2771 * Interface for exporting LEDs (down).
2772 * Pair with PDMILEDCONNECTORS.
2773 */
2774typedef struct PDMILEDPORTS
2775{
2776 /**
2777 * Gets the pointer to the status LED of a unit.
2778 *
2779 * @returns VBox status code.
2780 * @param pInterface Pointer to the interface structure containing the called function pointer.
2781 * @param iLUN The unit which status LED we desire.
2782 * @param ppLed Where to store the LED pointer.
2783 */
2784 DECLR3CALLBACKMEMBER(int, pfnQueryStatusLed,(PPDMILEDPORTS pInterface, unsigned iLUN, PPDMLED *ppLed));
2785
2786} PDMILEDPORTS;
2787/** PDMILEDPORTS interface ID. */
2788#define PDMILEDPORTS_IID "435e0cec-8549-4ca0-8c0d-98e52f1dc038"
2789
2790
2791/** Pointer to an LED connectors interface. */
2792typedef struct PDMILEDCONNECTORS *PPDMILEDCONNECTORS;
2793/**
2794 * Interface for reading LEDs (up).
2795 * Pair with PDMILEDPORTS.
2796 */
2797typedef struct PDMILEDCONNECTORS
2798{
2799 /**
2800 * Notification about a unit which have been changed.
2801 *
2802 * The driver must discard any pointers to data owned by
2803 * the unit and requery it.
2804 *
2805 * @param pInterface Pointer to the interface structure containing the called function pointer.
2806 * @param iLUN The unit number.
2807 */
2808 DECLR3CALLBACKMEMBER(void, pfnUnitChanged,(PPDMILEDCONNECTORS pInterface, unsigned iLUN));
2809} PDMILEDCONNECTORS;
2810/** PDMILEDCONNECTORS interface ID. */
2811#define PDMILEDCONNECTORS_IID "8ed63568-82a7-4193-b57b-db8085ac4495"
2812
2813
2814/** Pointer to a Media Notification interface. */
2815typedef struct PDMIMEDIANOTIFY *PPDMIMEDIANOTIFY;
2816/**
2817 * Interface for exporting Medium eject information (up). No interface pair.
2818 */
2819typedef struct PDMIMEDIANOTIFY
2820{
2821 /**
2822 * Signals that the medium was ejected.
2823 *
2824 * @returns VBox status code.
2825 * @param pInterface Pointer to the interface structure containing the called function pointer.
2826 * @param iLUN The unit which had the medium ejected.
2827 */
2828 DECLR3CALLBACKMEMBER(int, pfnEjected,(PPDMIMEDIANOTIFY pInterface, unsigned iLUN));
2829
2830} PDMIMEDIANOTIFY;
2831/** PDMIMEDIANOTIFY interface ID. */
2832#define PDMIMEDIANOTIFY_IID "fc22d53e-feb1-4a9c-b9fb-0a990a6ab288"
2833
2834
2835/** The special status unit number */
2836#define PDM_STATUS_LUN 999
2837
2838
2839#ifdef VBOX_WITH_HGCM
2840
2841/** Abstract HGCM command structure. Used only to define a typed pointer. */
2842struct VBOXHGCMCMD;
2843
2844/** Pointer to HGCM command structure. This pointer is unique and identifies
2845 * the command being processed. The pointer is passed to HGCM connector methods,
2846 * and must be passed back to HGCM port when command is completed.
2847 */
2848typedef struct VBOXHGCMCMD *PVBOXHGCMCMD;
2849
2850/** Pointer to a HGCM port interface. */
2851typedef struct PDMIHGCMPORT *PPDMIHGCMPORT;
2852/**
2853 * Host-Guest communication manager port interface (down). Normally implemented
2854 * by VMMDev.
2855 * Pair with PDMIHGCMCONNECTOR.
2856 */
2857typedef struct PDMIHGCMPORT
2858{
2859 /**
2860 * Notify the guest on a command completion.
2861 *
2862 * @param pInterface Pointer to this interface.
2863 * @param rc The return code (VBox error code).
2864 * @param pCmd A pointer that identifies the completed command.
2865 *
2866 * @returns VBox status code
2867 */
2868 DECLR3CALLBACKMEMBER(void, pfnCompleted,(PPDMIHGCMPORT pInterface, int32_t rc, PVBOXHGCMCMD pCmd));
2869
2870} PDMIHGCMPORT;
2871/** PDMIHGCMPORT interface ID. */
2872# define PDMIHGCMPORT_IID "e00a0cbf-b75a-45c3-87f4-41cddbc5ae0b"
2873
2874
2875/** Pointer to a HGCM service location structure. */
2876typedef struct HGCMSERVICELOCATION *PHGCMSERVICELOCATION;
2877
2878/** Pointer to a HGCM connector interface. */
2879typedef struct PDMIHGCMCONNECTOR *PPDMIHGCMCONNECTOR;
2880/**
2881 * The Host-Guest communication manager connector interface (up). Normally
2882 * implemented by Main::VMMDevInterface.
2883 * Pair with PDMIHGCMPORT.
2884 */
2885typedef struct PDMIHGCMCONNECTOR
2886{
2887 /**
2888 * Locate a service and inform it about a client connection.
2889 *
2890 * @param pInterface Pointer to this interface.
2891 * @param pCmd A pointer that identifies the command.
2892 * @param pServiceLocation Pointer to the service location structure.
2893 * @param pu32ClientID Where to store the client id for the connection.
2894 * @return VBox status code.
2895 * @thread The emulation thread.
2896 */
2897 DECLR3CALLBACKMEMBER(int, pfnConnect,(PPDMIHGCMCONNECTOR pInterface, PVBOXHGCMCMD pCmd, PHGCMSERVICELOCATION pServiceLocation, uint32_t *pu32ClientID));
2898
2899 /**
2900 * Disconnect from service.
2901 *
2902 * @param pInterface Pointer to this interface.
2903 * @param pCmd A pointer that identifies the command.
2904 * @param u32ClientID The client id returned by the pfnConnect call.
2905 * @return VBox status code.
2906 * @thread The emulation thread.
2907 */
2908 DECLR3CALLBACKMEMBER(int, pfnDisconnect,(PPDMIHGCMCONNECTOR pInterface, PVBOXHGCMCMD pCmd, uint32_t u32ClientID));
2909
2910 /**
2911 * Process a guest issued command.
2912 *
2913 * @param pInterface Pointer to this interface.
2914 * @param pCmd A pointer that identifies the command.
2915 * @param u32ClientID The client id returned by the pfnConnect call.
2916 * @param u32Function Function to be performed by the service.
2917 * @param cParms Number of parameters in the array pointed to by paParams.
2918 * @param paParms Pointer to an array of parameters.
2919 * @return VBox status code.
2920 * @thread The emulation thread.
2921 */
2922 DECLR3CALLBACKMEMBER(int, pfnCall,(PPDMIHGCMCONNECTOR pInterface, PVBOXHGCMCMD pCmd, uint32_t u32ClientID, uint32_t u32Function,
2923 uint32_t cParms, PVBOXHGCMSVCPARM paParms));
2924
2925} PDMIHGCMCONNECTOR;
2926/** PDMIHGCMCONNECTOR interface ID. */
2927# define PDMIHGCMCONNECTOR_IID "a1104758-c888-4437-8f2a-7bac17865b5c"
2928
2929#endif /* VBOX_WITH_HGCM */
2930
2931/**
2932 * Data direction.
2933 */
2934typedef enum PDMSCSIREQUESTTXDIR
2935{
2936 PDMSCSIREQUESTTXDIR_UNKNOWN = 0x00,
2937 PDMSCSIREQUESTTXDIR_FROM_DEVICE = 0x01,
2938 PDMSCSIREQUESTTXDIR_TO_DEVICE = 0x02,
2939 PDMSCSIREQUESTTXDIR_NONE = 0x03,
2940 PDMSCSIREQUESTTXDIR_32BIT_HACK = 0x7fffffff
2941} PDMSCSIREQUESTTXDIR;
2942
2943/**
2944 * SCSI request structure.
2945 */
2946typedef struct PDMSCSIREQUEST
2947{
2948 /** The logical unit. */
2949 uint32_t uLogicalUnit;
2950 /** Direction of the data flow. */
2951 PDMSCSIREQUESTTXDIR uDataDirection;
2952 /** Size of the SCSI CDB. */
2953 uint32_t cbCDB;
2954 /** Pointer to the SCSI CDB. */
2955 uint8_t *pbCDB;
2956 /** Overall size of all scatter gather list elements
2957 * for data transfer if any. */
2958 uint32_t cbScatterGather;
2959 /** Number of elements in the scatter gather list. */
2960 uint32_t cScatterGatherEntries;
2961 /** Pointer to the head of the scatter gather list. */
2962 PRTSGSEG paScatterGatherHead;
2963 /** Size of the sense buffer. */
2964 uint32_t cbSenseBuffer;
2965 /** Pointer to the sense buffer. *
2966 * Current assumption that the sense buffer is not scattered. */
2967 uint8_t *pbSenseBuffer;
2968 /** Opaque user data for use by the device. Left untouched by everything else! */
2969 void *pvUser;
2970} PDMSCSIREQUEST, *PPDMSCSIREQUEST;
2971/** Pointer to a const SCSI request structure. */
2972typedef const PDMSCSIREQUEST *PCSCSIREQUEST;
2973
2974/** Pointer to a SCSI port interface. */
2975typedef struct PDMISCSIPORT *PPDMISCSIPORT;
2976/**
2977 * SCSI command execution port interface (down).
2978 * Pair with PDMISCSICONNECTOR.
2979 */
2980typedef struct PDMISCSIPORT
2981{
2982
2983 /**
2984 * Notify the device on request completion.
2985 *
2986 * @returns VBox status code.
2987 * @param pInterface Pointer to this interface.
2988 * @param pSCSIRequest Pointer to the finished SCSI request.
2989 * @param rcCompletion SCSI_STATUS_* code for the completed request.
2990 * @param fRedo Flag whether the request can to be redone
2991 * when it failed.
2992 * @param rcReq The status code the request completed with (VERR_*)
2993 * Should be only used to choose the correct error message
2994 * displayed to the user if the error can be fixed by him
2995 * (fRedo is true).
2996 */
2997 DECLR3CALLBACKMEMBER(int, pfnSCSIRequestCompleted, (PPDMISCSIPORT pInterface, PPDMSCSIREQUEST pSCSIRequest,
2998 int rcCompletion, bool fRedo, int rcReq));
2999
3000 /**
3001 * Returns the storage controller name, instance and LUN of the attached medium.
3002 *
3003 * @returns VBox status.
3004 * @param pInterface Pointer to this interface.
3005 * @param ppcszController Where to store the name of the storage controller.
3006 * @param piInstance Where to store the instance number of the controller.
3007 * @param piLUN Where to store the LUN of the attached device.
3008 */
3009 DECLR3CALLBACKMEMBER(int, pfnQueryDeviceLocation, (PPDMISCSIPORT pInterface, const char **ppcszController,
3010 uint32_t *piInstance, uint32_t *piLUN));
3011
3012} PDMISCSIPORT;
3013/** PDMISCSIPORT interface ID. */
3014#define PDMISCSIPORT_IID "05d9fc3b-e38c-4b30-8344-a323feebcfe5"
3015
3016
3017/** Pointer to a SCSI connector interface. */
3018typedef struct PDMISCSICONNECTOR *PPDMISCSICONNECTOR;
3019/**
3020 * SCSI command execution connector interface (up).
3021 * Pair with PDMISCSIPORT.
3022 */
3023typedef struct PDMISCSICONNECTOR
3024{
3025
3026 /**
3027 * Submits a SCSI request for execution.
3028 *
3029 * @returns VBox status code.
3030 * @param pInterface Pointer to this interface.
3031 * @param pSCSIRequest Pointer to the SCSI request to execute.
3032 */
3033 DECLR3CALLBACKMEMBER(int, pfnSCSIRequestSend, (PPDMISCSICONNECTOR pInterface, PPDMSCSIREQUEST pSCSIRequest));
3034
3035} PDMISCSICONNECTOR;
3036/** PDMISCSICONNECTOR interface ID. */
3037#define PDMISCSICONNECTOR_IID "94465fbd-a2f2-447e-88c9-7366421bfbfe"
3038
3039
3040/** Pointer to a display VBVA callbacks interface. */
3041typedef struct PDMIDISPLAYVBVACALLBACKS *PPDMIDISPLAYVBVACALLBACKS;
3042/**
3043 * Display VBVA callbacks interface (up).
3044 */
3045typedef struct PDMIDISPLAYVBVACALLBACKS
3046{
3047
3048 /**
3049 * Informs guest about completion of processing the given Video HW Acceleration
3050 * command, does not wait for the guest to process the command.
3051 *
3052 * @returns ???
3053 * @param pInterface Pointer to this interface.
3054 * @param pCmd The Video HW Acceleration Command that was
3055 * completed.
3056 * @todo r=bird: if async means asynchronous; then
3057 * s/pfnVHWACommandCompleteAsynch/pfnVHWACommandCompleteAsync/;
3058 * fi
3059 */
3060 DECLR3CALLBACKMEMBER(int, pfnVHWACommandCompleteAsynch, (PPDMIDISPLAYVBVACALLBACKS pInterface,
3061 PVBOXVHWACMD pCmd));
3062
3063 DECLR3CALLBACKMEMBER(int, pfnCrHgsmiCommandCompleteAsync, (PPDMIDISPLAYVBVACALLBACKS pInterface,
3064 PVBOXVDMACMD_CHROMIUM_CMD pCmd, int rc));
3065
3066 DECLR3CALLBACKMEMBER(int, pfnCrHgsmiControlCompleteAsync, (PPDMIDISPLAYVBVACALLBACKS pInterface,
3067 PVBOXVDMACMD_CHROMIUM_CTL pCmd, int rc));
3068} PDMIDISPLAYVBVACALLBACKS;
3069/** PDMIDISPLAYVBVACALLBACKS */
3070#define PDMIDISPLAYVBVACALLBACKS_IID "b78b81d2-c821-4e66-96ff-dbafa76343a5"
3071
3072/** Pointer to a PCI raw connector interface. */
3073typedef struct PDMIPCIRAWCONNECTOR *PPDMIPCIRAWCONNECTOR;
3074/**
3075 * PCI raw connector interface (up).
3076 */
3077typedef struct PDMIPCIRAWCONNECTOR
3078{
3079
3080 /**
3081 *
3082 */
3083 DECLR3CALLBACKMEMBER(int, pfnDeviceConstructComplete, (PPDMIPCIRAWCONNECTOR pInterface, const char *pcszName,
3084 uint32_t uHostPciAddress, uint32_t uGuestPciAddress,
3085 int rc));
3086
3087} PDMIPCIRAWCONNECTOR;
3088/** PDMIPCIRAWCONNECTOR interface ID. */
3089#define PDMIPCIRAWCONNECTOR_IID "14aa9c6c-8869-4782-9dfc-910071a6aebf"
3090
3091/** @} */
3092
3093RT_C_DECLS_END
3094
3095#endif
Note: See TracBrowser for help on using the repository browser.

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