VirtualBox

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

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

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

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