VirtualBox

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

Last change on this file since 59248 was 59248, checked in by vboxsync, 9 years ago

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