VirtualBox

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

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

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