VirtualBox

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

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

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

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