VirtualBox

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

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

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