VirtualBox

source: vbox/trunk/include/VBox/VMMDev.h@ 69759

Last change on this file since 69759 was 69107, checked in by vboxsync, 7 years ago

include/VBox/: (C) year
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 55.7 KB
Line 
1/** @file
2 * Virtual Device for Guest <-> VMM/Host communication (ADD,DEV).
3 */
4
5/*
6 * Copyright (C) 2006-2017 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_VMMDev_h
27#define ___VBox_VMMDev_h
28
29#include <VBox/cdefs.h>
30#include <VBox/param.h> /* for the PCI IDs. */
31#include <VBox/types.h>
32#include <VBox/err.h>
33#include <VBox/ostypes.h>
34#include <VBox/VMMDevCoreTypes.h>
35#include <iprt/assertcompile.h>
36
37
38#pragma pack(4) /* force structure dword packing here. */
39RT_C_DECLS_BEGIN
40
41
42/** @defgroup grp_vmmdev VMM Device
43 *
44 * @note This interface cannot be changed, it can only be extended!
45 *
46 * @{
47 */
48
49
50/** Size of VMMDev RAM region accessible by guest.
51 * Must be big enough to contain VMMDevMemory structure (see further down).
52 * For now: 4 megabyte.
53 */
54#define VMMDEV_RAM_SIZE (4 * 256 * PAGE_SIZE)
55
56/** Size of VMMDev heap region accessible by guest.
57 * (Must be a power of two (pci range).)
58 */
59#define VMMDEV_HEAP_SIZE (4 * PAGE_SIZE)
60
61/** Port for generic request interface (relative offset). */
62#define VMMDEV_PORT_OFF_REQUEST 0
63
64
65/** @defgroup grp_vmmdev_req VMMDev Generic Request Interface
66 * @{
67 */
68
69/** @name Current version of the VMMDev interface.
70 *
71 * Additions are allowed to work only if
72 * additions_major == vmmdev_current && additions_minor <= vmmdev_current.
73 * Additions version is reported to host (VMMDev) by VMMDevReq_ReportGuestInfo.
74 *
75 * @remarks These defines also live in the 16-bit and assembly versions of this
76 * header.
77 */
78#define VMMDEV_VERSION 0x00010004
79#define VMMDEV_VERSION_MAJOR (VMMDEV_VERSION >> 16)
80#define VMMDEV_VERSION_MINOR (VMMDEV_VERSION & 0xffff)
81/** @} */
82
83/** Maximum request packet size. */
84#define VMMDEV_MAX_VMMDEVREQ_SIZE _1M
85/** Maximum number of HGCM parameters.
86 * @todo r=bird: This is wrong wrt user land calls. For them it iss 61.
87 * See comments on VBGLIOCHGCMCALL::cParms. */
88#define VMMDEV_MAX_HGCM_PARMS 1024
89/** Maximum total size of hgcm buffers in one call. */
90#define VMMDEV_MAX_HGCM_DATA_SIZE UINT32_C(0x7FFFFFFF)
91
92/**
93 * VMMDev request types.
94 * @note when updating this, adjust vmmdevGetRequestSize() as well
95 */
96typedef enum VMMDevRequestType
97{
98 VMMDevReq_InvalidRequest = 0,
99 VMMDevReq_GetMouseStatus = 1,
100 VMMDevReq_SetMouseStatus = 2,
101 VMMDevReq_SetPointerShape = 3,
102 VMMDevReq_GetHostVersion = 4,
103 VMMDevReq_Idle = 5,
104 VMMDevReq_GetHostTime = 10,
105 VMMDevReq_GetHypervisorInfo = 20,
106 VMMDevReq_SetHypervisorInfo = 21,
107 VMMDevReq_RegisterPatchMemory = 22, /**< @since version 3.0.6 */
108 VMMDevReq_DeregisterPatchMemory = 23, /**< @since version 3.0.6 */
109 VMMDevReq_SetPowerStatus = 30,
110 VMMDevReq_AcknowledgeEvents = 41,
111 VMMDevReq_CtlGuestFilterMask = 42,
112 VMMDevReq_ReportGuestInfo = 50,
113 VMMDevReq_ReportGuestInfo2 = 58, /**< @since version 3.2.0 */
114 VMMDevReq_ReportGuestStatus = 59, /**< @since version 3.2.8 */
115 VMMDevReq_ReportGuestUserState = 74, /**< @since version 4.3 */
116 /**
117 * Retrieve a display resize request sent by the host using
118 * @a IDisplay:setVideoModeHint. Deprecated.
119 *
120 * Similar to @a VMMDevReq_GetDisplayChangeRequest2, except that it only
121 * considers host requests sent for the first virtual display. This guest
122 * request should not be used in new guest code, and the results are
123 * undefined if a guest mixes calls to this and
124 * @a VMMDevReq_GetDisplayChangeRequest2.
125 */
126 VMMDevReq_GetDisplayChangeRequest = 51,
127 VMMDevReq_VideoModeSupported = 52,
128 VMMDevReq_GetHeightReduction = 53,
129 /**
130 * Retrieve a display resize request sent by the host using
131 * @a IDisplay:setVideoModeHint.
132 *
133 * Queries a display resize request sent from the host. If the
134 * @a eventAck member is sent to true and there is an unqueried
135 * request available for one of the virtual display then that request will
136 * be returned. If several displays have unqueried requests the lowest
137 * numbered display will be chosen first. Only the most recent unseen
138 * request for each display is remembered.
139 * If @a eventAck is set to false, the last host request queried with
140 * @a eventAck set is resent, or failing that the most recent received from
141 * the host. If no host request was ever received then all zeros are
142 * returned.
143 */
144 VMMDevReq_GetDisplayChangeRequest2 = 54,
145 VMMDevReq_ReportGuestCapabilities = 55,
146 VMMDevReq_SetGuestCapabilities = 56,
147 VMMDevReq_VideoModeSupported2 = 57, /**< @since version 3.2.0 */
148 VMMDevReq_GetDisplayChangeRequestEx = 80, /**< @since version 4.2.4 */
149#ifdef VBOX_WITH_HGCM
150 VMMDevReq_HGCMConnect = 60,
151 VMMDevReq_HGCMDisconnect = 61,
152#ifdef VBOX_WITH_64_BITS_GUESTS
153 VMMDevReq_HGCMCall32 = 62,
154 VMMDevReq_HGCMCall64 = 63,
155#else
156 VMMDevReq_HGCMCall = 62,
157#endif /* VBOX_WITH_64_BITS_GUESTS */
158 VMMDevReq_HGCMCancel = 64,
159 VMMDevReq_HGCMCancel2 = 65,
160#endif
161 VMMDevReq_VideoAccelEnable = 70,
162 VMMDevReq_VideoAccelFlush = 71,
163 VMMDevReq_VideoSetVisibleRegion = 72,
164 VMMDevReq_GetSeamlessChangeRequest = 73,
165 VMMDevReq_QueryCredentials = 100,
166 VMMDevReq_ReportCredentialsJudgement = 101,
167 VMMDevReq_ReportGuestStats = 110,
168 VMMDevReq_GetMemBalloonChangeRequest = 111,
169 VMMDevReq_GetStatisticsChangeRequest = 112,
170 VMMDevReq_ChangeMemBalloon = 113,
171 VMMDevReq_GetVRDPChangeRequest = 150,
172 VMMDevReq_LogString = 200,
173 VMMDevReq_GetCpuHotPlugRequest = 210,
174 VMMDevReq_SetCpuHotPlugStatus = 211,
175 VMMDevReq_RegisterSharedModule = 212,
176 VMMDevReq_UnregisterSharedModule = 213,
177 VMMDevReq_CheckSharedModules = 214,
178 VMMDevReq_GetPageSharingStatus = 215,
179 VMMDevReq_DebugIsPageShared = 216,
180 VMMDevReq_GetSessionId = 217, /**< @since version 3.2.8 */
181 VMMDevReq_WriteCoreDump = 218,
182 VMMDevReq_GuestHeartbeat = 219,
183 VMMDevReq_HeartbeatConfigure = 220,
184 VMMDevReq_SizeHack = 0x7fffffff
185} VMMDevRequestType;
186
187#ifdef VBOX_WITH_64_BITS_GUESTS
188/*
189 * Constants and structures are redefined for the guest.
190 *
191 * Host code MUST always use either *32 or *64 variant explicitely.
192 * Host source code will use VBOX_HGCM_HOST_CODE define to catch undefined
193 * data types and constants.
194 *
195 * This redefinition means that the new additions builds will use
196 * the *64 or *32 variants depending on the current architecture bit count (ARCH_BITS).
197 */
198# ifndef VBOX_HGCM_HOST_CODE
199# if ARCH_BITS == 64
200# define VMMDevReq_HGCMCall VMMDevReq_HGCMCall64
201# elif ARCH_BITS == 32 || ARCH_BITS == 16
202# define VMMDevReq_HGCMCall VMMDevReq_HGCMCall32
203# else
204# error "Unsupported ARCH_BITS"
205# endif
206# endif /* !VBOX_HGCM_HOST_CODE */
207#endif /* VBOX_WITH_64_BITS_GUESTS */
208
209/** Version of VMMDevRequestHeader structure. */
210#define VMMDEV_REQUEST_HEADER_VERSION (0x10001)
211
212
213/**
214 * Generic VMMDev request header.
215 *
216 * This structure is copied/mirrored by VBGLREQHDR in the VBoxGuest I/O control
217 * interface. Changes there needs to be mirrored in it.
218 *
219 * @sa VBGLREQHDR
220 */
221typedef struct VMMDevRequestHeader
222{
223 /** IN: Size of the structure in bytes (including body).
224 * (VBGLREQHDR uses this for input size and output if reserved1 is zero). */
225 uint32_t size;
226 /** IN: Version of the structure. */
227 uint32_t version;
228 /** IN: Type of the request.
229 * @note VBGLREQHDR uses this for optional output size. */
230 VMMDevRequestType requestType;
231 /** OUT: VBox status code. */
232 int32_t rc;
233 /** Reserved field no.1. MBZ.
234 * @note VBGLREQHDR uses this for optional output size, however never for a
235 * real VMMDev request, only in the I/O control interface. */
236 uint32_t reserved1;
237 /** Reserved field no.2. MBZ. */
238 uint32_t reserved2;
239} VMMDevRequestHeader;
240AssertCompileSize(VMMDevRequestHeader, 24);
241
242/** Initialize a VMMDevRequestHeader structure.
243 * Same as VBGLREQHDR_INIT_VMMDEV(). */
244#define VMMDEV_REQ_HDR_INIT(a_pHdr, a_cb, a_enmType) \
245 do { \
246 (a_pHdr)->size = (a_cb); \
247 (a_pHdr)->version = VMMDEV_REQUEST_HEADER_VERSION; \
248 (a_pHdr)->requestType = (a_enmType); \
249 (a_pHdr)->rc = VERR_INTERNAL_ERROR; \
250 (a_pHdr)->reserved1 = 0; \
251 (a_pHdr)->reserved2 = 0; \
252 } while (0)
253
254
255/**
256 * Mouse status request structure.
257 *
258 * Used by VMMDevReq_GetMouseStatus and VMMDevReq_SetMouseStatus.
259 */
260typedef struct
261{
262 /** header */
263 VMMDevRequestHeader header;
264 /** Mouse feature mask. See VMMDEV_MOUSE_*. */
265 uint32_t mouseFeatures;
266 /** Mouse x position. */
267 int32_t pointerXPos;
268 /** Mouse y position. */
269 int32_t pointerYPos;
270} VMMDevReqMouseStatus;
271AssertCompileSize(VMMDevReqMouseStatus, 24+12);
272
273/** @name Mouse capability bits (VMMDevReqMouseStatus::mouseFeatures).
274 * @{ */
275/** The guest can (== wants to) handle absolute coordinates. */
276#define VMMDEV_MOUSE_GUEST_CAN_ABSOLUTE RT_BIT(0)
277/** The host can (== wants to) send absolute coordinates.
278 * (Input not captured.) */
279#define VMMDEV_MOUSE_HOST_WANTS_ABSOLUTE RT_BIT(1)
280/** The guest can *NOT* switch to software cursor and therefore depends on the
281 * host cursor.
282 *
283 * When guest additions are installed and the host has promised to display the
284 * cursor itself, the guest installs a hardware mouse driver. Don't ask the
285 * guest to switch to a software cursor then. */
286#define VMMDEV_MOUSE_GUEST_NEEDS_HOST_CURSOR RT_BIT(2)
287/** The host does NOT provide support for drawing the cursor itself. */
288#define VMMDEV_MOUSE_HOST_CANNOT_HWPOINTER RT_BIT(3)
289/** The guest can read VMMDev events to find out about pointer movement */
290#define VMMDEV_MOUSE_NEW_PROTOCOL RT_BIT(4)
291/** If the guest changes the status of the
292 * VMMDEV_MOUSE_GUEST_NEEDS_HOST_CURSOR bit, the host will honour this */
293#define VMMDEV_MOUSE_HOST_RECHECKS_NEEDS_HOST_CURSOR RT_BIT(5)
294/** The host supplies an absolute pointing device. The Guest Additions may
295 * wish to use this to decide whether to install their own driver */
296#define VMMDEV_MOUSE_HOST_HAS_ABS_DEV RT_BIT(6)
297/** The mask of all VMMDEV_MOUSE_* flags */
298#define VMMDEV_MOUSE_MASK UINT32_C(0x0000007f)
299/** The mask of guest capability changes for which notification events should
300 * be sent */
301#define VMMDEV_MOUSE_NOTIFY_HOST_MASK \
302 (VMMDEV_MOUSE_GUEST_CAN_ABSOLUTE | VMMDEV_MOUSE_GUEST_NEEDS_HOST_CURSOR)
303/** The mask of all capabilities which the guest can legitimately change */
304#define VMMDEV_MOUSE_GUEST_MASK \
305 (VMMDEV_MOUSE_NOTIFY_HOST_MASK | VMMDEV_MOUSE_NEW_PROTOCOL)
306/** The mask of host capability changes for which notification events should
307 * be sent */
308#define VMMDEV_MOUSE_NOTIFY_GUEST_MASK \
309 VMMDEV_MOUSE_HOST_WANTS_ABSOLUTE
310/** The mask of all capabilities which the host can legitimately change */
311#define VMMDEV_MOUSE_HOST_MASK \
312 ( VMMDEV_MOUSE_NOTIFY_GUEST_MASK \
313 | VMMDEV_MOUSE_HOST_CANNOT_HWPOINTER \
314 | VMMDEV_MOUSE_HOST_RECHECKS_NEEDS_HOST_CURSOR \
315 | VMMDEV_MOUSE_HOST_HAS_ABS_DEV)
316/** @} */
317
318/** @name Absolute mouse reporting range
319 * @{ */
320/** @todo Should these be here? They are needed by both host and guest. */
321/** The minumum value our pointing device can return. */
322#define VMMDEV_MOUSE_RANGE_MIN 0
323/** The maximum value our pointing device can return. */
324#define VMMDEV_MOUSE_RANGE_MAX 0xFFFF
325/** The full range our pointing device can return. */
326#define VMMDEV_MOUSE_RANGE (VMMDEV_MOUSE_RANGE_MAX - VMMDEV_MOUSE_RANGE_MIN)
327/** @} */
328
329
330/**
331 * Mouse pointer shape/visibility change request.
332 *
333 * Used by VMMDevReq_SetPointerShape. The size is variable.
334 */
335typedef struct VMMDevReqMousePointer
336{
337 /** Header. */
338 VMMDevRequestHeader header;
339 /** VBOX_MOUSE_POINTER_* bit flags from VBox/Graphics/VBoxVideo.h. */
340 uint32_t fFlags;
341 /** x coordinate of hot spot. */
342 uint32_t xHot;
343 /** y coordinate of hot spot. */
344 uint32_t yHot;
345 /** Width of the pointer in pixels. */
346 uint32_t width;
347 /** Height of the pointer in scanlines. */
348 uint32_t height;
349 /** Pointer data.
350 *
351 ****
352 * The data consists of 1 bpp AND mask followed by 32 bpp XOR (color) mask.
353 *
354 * For pointers without alpha channel the XOR mask pixels are 32 bit values: (lsb)BGR0(msb).
355 * For pointers with alpha channel the XOR mask consists of (lsb)BGRA(msb) 32 bit values.
356 *
357 * Guest driver must create the AND mask for pointers with alpha channel, so if host does not
358 * support alpha, the pointer could be displayed as a normal color pointer. The AND mask can
359 * be constructed from alpha values. For example alpha value >= 0xf0 means bit 0 in the AND mask.
360 *
361 * The AND mask is 1 bpp bitmap with byte aligned scanlines. Size of AND mask,
362 * therefore, is cbAnd = (width + 7) / 8 * height. The padding bits at the
363 * end of any scanline are undefined.
364 *
365 * The XOR mask follows the AND mask on the next 4 bytes aligned offset:
366 * uint8_t *pXor = pAnd + (cbAnd + 3) & ~3
367 * Bytes in the gap between the AND and the XOR mask are undefined.
368 * XOR mask scanlines have no gap between them and size of XOR mask is:
369 * cXor = width * 4 * height.
370 ****
371 *
372 * Preallocate 4 bytes for accessing actual data as p->pointerData.
373 */
374 char pointerData[4];
375} VMMDevReqMousePointer;
376AssertCompileSize(VMMDevReqMousePointer, 24+24);
377
378/**
379 * Get the size that a VMMDevReqMousePointer request should have for a given
380 * size of cursor, including the trailing cursor image and mask data.
381 * @note an "empty" request still has the four preallocated bytes of data
382 *
383 * @returns the size
384 * @param width the cursor width
385 * @param height the cursor height
386 */
387DECLINLINE(size_t) vmmdevGetMousePointerReqSize(uint32_t width, uint32_t height)
388{
389 size_t cbBase = RT_OFFSETOF(VMMDevReqMousePointer, pointerData[0]);
390 size_t cbMask = (width + 7) / 8 * height;
391 size_t cbArgb = width * height * 4;
392 return RT_MAX(cbBase + ((cbMask + 3) & ~3) + cbArgb,
393 sizeof(VMMDevReqMousePointer));
394}
395
396
397/**
398 * String log request structure.
399 *
400 * Used by VMMDevReq_LogString.
401 * @deprecated Use the IPRT logger or VbglR3WriteLog instead.
402 */
403typedef struct
404{
405 /** header */
406 VMMDevRequestHeader header;
407 /** variable length string data */
408 char szString[1];
409} VMMDevReqLogString;
410AssertCompileSize(VMMDevReqLogString, 24+4);
411
412
413/**
414 * VirtualBox host version request structure.
415 *
416 * Used by VMMDevReq_GetHostVersion.
417 *
418 * @remarks VBGL uses this to detect the precense of new features in the
419 * interface.
420 */
421typedef struct
422{
423 /** Header. */
424 VMMDevRequestHeader header;
425 /** Major version. */
426 uint16_t major;
427 /** Minor version. */
428 uint16_t minor;
429 /** Build number. */
430 uint32_t build;
431 /** SVN revision. */
432 uint32_t revision;
433 /** Feature mask. */
434 uint32_t features;
435} VMMDevReqHostVersion;
436AssertCompileSize(VMMDevReqHostVersion, 24+16);
437
438/** @name VMMDevReqHostVersion::features
439 * @{ */
440/** Physical page lists are supported by HGCM. */
441#define VMMDEV_HVF_HGCM_PHYS_PAGE_LIST RT_BIT(0)
442/** @} */
443
444
445/**
446 * Guest capabilities structure.
447 *
448 * Used by VMMDevReq_ReportGuestCapabilities.
449 */
450typedef struct
451{
452 /** Header. */
453 VMMDevRequestHeader header;
454 /** Capabilities (VMMDEV_GUEST_*). */
455 uint32_t caps;
456} VMMDevReqGuestCapabilities;
457AssertCompileSize(VMMDevReqGuestCapabilities, 24+4);
458
459
460/**
461 * Guest capabilities structure, version 2.
462 *
463 * Used by VMMDevReq_SetGuestCapabilities.
464 */
465typedef struct
466{
467 /** Header. */
468 VMMDevRequestHeader header;
469 /** Mask of capabilities to be added. */
470 uint32_t u32OrMask;
471 /** Mask of capabilities to be removed. */
472 uint32_t u32NotMask;
473} VMMDevReqGuestCapabilities2;
474AssertCompileSize(VMMDevReqGuestCapabilities2, 24+8);
475
476
477/**
478 * Idle request structure.
479 *
480 * Used by VMMDevReq_Idle.
481 */
482typedef struct
483{
484 /** Header. */
485 VMMDevRequestHeader header;
486} VMMDevReqIdle;
487AssertCompileSize(VMMDevReqIdle, 24);
488
489
490/**
491 * Host time request structure.
492 *
493 * Used by VMMDevReq_GetHostTime.
494 */
495typedef struct
496{
497 /** Header */
498 VMMDevRequestHeader header;
499 /** OUT: Time in milliseconds since unix epoch. */
500 uint64_t time;
501} VMMDevReqHostTime;
502AssertCompileSize(VMMDevReqHostTime, 24+8);
503
504
505/**
506 * Hypervisor info structure.
507 *
508 * Used by VMMDevReq_GetHypervisorInfo and VMMDevReq_SetHypervisorInfo.
509 */
510typedef struct
511{
512 /** Header. */
513 VMMDevRequestHeader header;
514 /** Guest virtual address of proposed hypervisor start.
515 * Not used by VMMDevReq_GetHypervisorInfo.
516 * @todo Make this 64-bit compatible? */
517 RTGCPTR32 hypervisorStart;
518 /** Hypervisor size in bytes. */
519 uint32_t hypervisorSize;
520} VMMDevReqHypervisorInfo;
521AssertCompileSize(VMMDevReqHypervisorInfo, 24+8);
522
523/** @name Default patch memory size .
524 * Used by VMMDevReq_RegisterPatchMemory and VMMDevReq_DeregisterPatchMemory.
525 * @{ */
526#define VMMDEV_GUEST_DEFAULT_PATCHMEM_SIZE 8192
527/** @} */
528
529/**
530 * Patching memory structure. (locked executable & read-only page from the guest's perspective)
531 *
532 * Used by VMMDevReq_RegisterPatchMemory and VMMDevReq_DeregisterPatchMemory
533 */
534typedef struct
535{
536 /** Header. */
537 VMMDevRequestHeader header;
538 /** Guest virtual address of the patching page(s). */
539 RTGCPTR64 pPatchMem;
540 /** Patch page size in bytes. */
541 uint32_t cbPatchMem;
542} VMMDevReqPatchMemory;
543AssertCompileSize(VMMDevReqPatchMemory, 24+12);
544
545
546/**
547 * Guest power requests.
548 *
549 * See VMMDevReq_SetPowerStatus and VMMDevPowerStateRequest.
550 */
551typedef enum
552{
553 VMMDevPowerState_Invalid = 0,
554 VMMDevPowerState_Pause = 1,
555 VMMDevPowerState_PowerOff = 2,
556 VMMDevPowerState_SaveState = 3,
557 VMMDevPowerState_SizeHack = 0x7fffffff
558} VMMDevPowerState;
559AssertCompileSize(VMMDevPowerState, 4);
560
561/**
562 * VM power status structure.
563 *
564 * Used by VMMDevReq_SetPowerStatus.
565 */
566typedef struct
567{
568 /** Header. */
569 VMMDevRequestHeader header;
570 /** Power state request. */
571 VMMDevPowerState powerState;
572} VMMDevPowerStateRequest;
573AssertCompileSize(VMMDevPowerStateRequest, 24+4);
574
575
576/**
577 * Pending events structure.
578 *
579 * Used by VMMDevReq_AcknowledgeEvents.
580 */
581typedef struct
582{
583 /** Header. */
584 VMMDevRequestHeader header;
585 /** OUT: Pending event mask. */
586 uint32_t events;
587} VMMDevEvents;
588AssertCompileSize(VMMDevEvents, 24+4);
589
590
591/**
592 * Guest event filter mask control.
593 *
594 * Used by VMMDevReq_CtlGuestFilterMask.
595 */
596typedef struct
597{
598 /** Header. */
599 VMMDevRequestHeader header;
600 /** Mask of events to be added to the filter. */
601 uint32_t u32OrMask;
602 /** Mask of events to be removed from the filter. */
603 uint32_t u32NotMask;
604} VMMDevCtlGuestFilterMask;
605AssertCompileSize(VMMDevCtlGuestFilterMask, 24+8);
606
607
608/**
609 * Guest information structure.
610 *
611 * Used by VMMDevReportGuestInfo and PDMIVMMDEVCONNECTOR::pfnUpdateGuestVersion.
612 */
613typedef struct VBoxGuestInfo
614{
615 /** The VMMDev interface version expected by additions.
616 * *Deprecated*, do not use anymore! Will be removed. */
617 uint32_t interfaceVersion;
618 /** Guest OS type. */
619 VBOXOSTYPE osType;
620} VBoxGuestInfo;
621AssertCompileSize(VBoxGuestInfo, 8);
622
623/**
624 * Guest information report.
625 *
626 * Used by VMMDevReq_ReportGuestInfo.
627 */
628typedef struct
629{
630 /** Header. */
631 VMMDevRequestHeader header;
632 /** Guest information. */
633 VBoxGuestInfo guestInfo;
634} VMMDevReportGuestInfo;
635AssertCompileSize(VMMDevReportGuestInfo, 24+8);
636
637
638/**
639 * Guest information structure, version 2.
640 *
641 * Used by VMMDevReportGuestInfo2 and PDMIVMMDEVCONNECTOR::pfnUpdateGuestVersion2.
642 */
643typedef struct VBoxGuestInfo2
644{
645 /** Major version. */
646 uint16_t additionsMajor;
647 /** Minor version. */
648 uint16_t additionsMinor;
649 /** Build number. */
650 uint32_t additionsBuild;
651 /** SVN revision. */
652 uint32_t additionsRevision;
653 /** Feature mask, currently unused. */
654 uint32_t additionsFeatures;
655 /** The intentional meaning of this field was:
656 * Some additional information, for example 'Beta 1' or something like that.
657 *
658 * The way it was implemented was implemented: VBOX_VERSION_STRING.
659 *
660 * This means the first three members are duplicated in this field (if the guest
661 * build config is sane). So, the user must check this and chop it off before
662 * usage. There is, because of the Main code's blind trust in the field's
663 * content, no way back. */
664 char szName[128];
665} VBoxGuestInfo2;
666AssertCompileSize(VBoxGuestInfo2, 144);
667
668/**
669 * Guest information report, version 2.
670 *
671 * Used by VMMDevReq_ReportGuestInfo2.
672 */
673typedef struct
674{
675 /** Header. */
676 VMMDevRequestHeader header;
677 /** Guest information. */
678 VBoxGuestInfo2 guestInfo;
679} VMMDevReportGuestInfo2;
680AssertCompileSize(VMMDevReportGuestInfo2, 24+144);
681
682
683/**
684 * The facility class.
685 *
686 * This needs to be kept in sync with AdditionsFacilityClass of the Main API!
687 */
688typedef enum
689{
690 VBoxGuestFacilityClass_None = 0,
691 VBoxGuestFacilityClass_Driver = 10,
692 VBoxGuestFacilityClass_Service = 30,
693 VBoxGuestFacilityClass_Program = 50,
694 VBoxGuestFacilityClass_Feature = 100,
695 VBoxGuestFacilityClass_ThirdParty = 999,
696 VBoxGuestFacilityClass_All = 0x7ffffffe,
697 VBoxGuestFacilityClass_SizeHack = 0x7fffffff
698} VBoxGuestFacilityClass;
699AssertCompileSize(VBoxGuestFacilityClass, 4);
700
701/**
702 * Guest status structure.
703 *
704 * Used by VMMDevReqGuestStatus.
705 */
706typedef struct VBoxGuestStatus
707{
708 /** Facility the status is indicated for. */
709 VBoxGuestFacilityType facility;
710 /** Current guest status. */
711 VBoxGuestFacilityStatus status;
712 /** Flags, not used at the moment. */
713 uint32_t flags;
714} VBoxGuestStatus;
715AssertCompileSize(VBoxGuestStatus, 12);
716
717/**
718 * Guest Additions status structure.
719 *
720 * Used by VMMDevReq_ReportGuestStatus.
721 */
722typedef struct
723{
724 /** Header. */
725 VMMDevRequestHeader header;
726 /** Guest information. */
727 VBoxGuestStatus guestStatus;
728} VMMDevReportGuestStatus;
729AssertCompileSize(VMMDevReportGuestStatus, 24+12);
730
731
732/**
733 * Guest user status updates.
734 */
735typedef struct VBoxGuestUserStatus
736{
737 /** The guest user state to send. */
738 VBoxGuestUserState state;
739 /** Size (in bytes) of szUser. */
740 uint32_t cbUser;
741 /** Size (in bytes) of szDomain. */
742 uint32_t cbDomain;
743 /** Size (in bytes) of aDetails. */
744 uint32_t cbDetails;
745 /** Note: Here begins the dynamically
746 * allocated region. */
747 /** Guest user to report state for. */
748 char szUser[1];
749 /** Domain the guest user is bound to. */
750 char szDomain[1];
751 /** Optional details of the state. */
752 uint8_t aDetails[1];
753} VBoxGuestUserStatus;
754AssertCompileSize(VBoxGuestUserStatus, 20);
755
756
757/**
758 * Guest user status structure.
759 *
760 * Used by VMMDevReq_ReportGuestUserStatus.
761 */
762typedef struct
763{
764 /** Header. */
765 VMMDevRequestHeader header;
766 /** Guest user status. */
767 VBoxGuestUserStatus status;
768} VMMDevReportGuestUserState;
769AssertCompileSize(VMMDevReportGuestUserState, 24+20);
770
771
772/**
773 * Guest statistics structure.
774 *
775 * Used by VMMDevReportGuestStats and PDMIVMMDEVCONNECTOR::pfnReportStatistics.
776 */
777typedef struct VBoxGuestStatistics
778{
779 /** Virtual CPU ID. */
780 uint32_t u32CpuId;
781 /** Reported statistics. */
782 uint32_t u32StatCaps;
783 /** Idle CPU load (0-100) for last interval. */
784 uint32_t u32CpuLoad_Idle;
785 /** Kernel CPU load (0-100) for last interval. */
786 uint32_t u32CpuLoad_Kernel;
787 /** User CPU load (0-100) for last interval. */
788 uint32_t u32CpuLoad_User;
789 /** Nr of threads. */
790 uint32_t u32Threads;
791 /** Nr of processes. */
792 uint32_t u32Processes;
793 /** Nr of handles. */
794 uint32_t u32Handles;
795 /** Memory load (0-100). */
796 uint32_t u32MemoryLoad;
797 /** Page size of guest system. */
798 uint32_t u32PageSize;
799 /** Total physical memory (in 4KB pages). */
800 uint32_t u32PhysMemTotal;
801 /** Available physical memory (in 4KB pages). */
802 uint32_t u32PhysMemAvail;
803 /** Ballooned physical memory (in 4KB pages). */
804 uint32_t u32PhysMemBalloon;
805 /** Total number of committed memory (which is not necessarily in-use) (in 4KB pages). */
806 uint32_t u32MemCommitTotal;
807 /** Total amount of memory used by the kernel (in 4KB pages). */
808 uint32_t u32MemKernelTotal;
809 /** Total amount of paged memory used by the kernel (in 4KB pages). */
810 uint32_t u32MemKernelPaged;
811 /** Total amount of nonpaged memory used by the kernel (in 4KB pages). */
812 uint32_t u32MemKernelNonPaged;
813 /** Total amount of memory used for the system cache (in 4KB pages). */
814 uint32_t u32MemSystemCache;
815 /** Pagefile size (in 4KB pages). */
816 uint32_t u32PageFileSize;
817} VBoxGuestStatistics;
818AssertCompileSize(VBoxGuestStatistics, 19*4);
819
820/** @name Guest statistics values (VBoxGuestStatistics::u32StatCaps).
821 * @{ */
822#define VBOX_GUEST_STAT_CPU_LOAD_IDLE RT_BIT(0)
823#define VBOX_GUEST_STAT_CPU_LOAD_KERNEL RT_BIT(1)
824#define VBOX_GUEST_STAT_CPU_LOAD_USER RT_BIT(2)
825#define VBOX_GUEST_STAT_THREADS RT_BIT(3)
826#define VBOX_GUEST_STAT_PROCESSES RT_BIT(4)
827#define VBOX_GUEST_STAT_HANDLES RT_BIT(5)
828#define VBOX_GUEST_STAT_MEMORY_LOAD RT_BIT(6)
829#define VBOX_GUEST_STAT_PHYS_MEM_TOTAL RT_BIT(7)
830#define VBOX_GUEST_STAT_PHYS_MEM_AVAIL RT_BIT(8)
831#define VBOX_GUEST_STAT_PHYS_MEM_BALLOON RT_BIT(9)
832#define VBOX_GUEST_STAT_MEM_COMMIT_TOTAL RT_BIT(10)
833#define VBOX_GUEST_STAT_MEM_KERNEL_TOTAL RT_BIT(11)
834#define VBOX_GUEST_STAT_MEM_KERNEL_PAGED RT_BIT(12)
835#define VBOX_GUEST_STAT_MEM_KERNEL_NONPAGED RT_BIT(13)
836#define VBOX_GUEST_STAT_MEM_SYSTEM_CACHE RT_BIT(14)
837#define VBOX_GUEST_STAT_PAGE_FILE_SIZE RT_BIT(15)
838/** @} */
839
840/**
841 * Guest statistics command structure.
842 *
843 * Used by VMMDevReq_ReportGuestStats.
844 */
845typedef struct
846{
847 /** Header. */
848 VMMDevRequestHeader header;
849 /** Guest information. */
850 VBoxGuestStatistics guestStats;
851} VMMDevReportGuestStats;
852AssertCompileSize(VMMDevReportGuestStats, 24+19*4);
853
854
855/** Memory balloon change request structure. */
856#define VMMDEV_MAX_MEMORY_BALLOON(PhysMemTotal) ( (9 * (PhysMemTotal)) / 10 )
857
858/**
859 * Poll for ballooning change request.
860 *
861 * Used by VMMDevReq_GetMemBalloonChangeRequest.
862 */
863typedef struct
864{
865 /** Header. */
866 VMMDevRequestHeader header;
867 /** Balloon size in megabytes. */
868 uint32_t cBalloonChunks;
869 /** Guest ram size in megabytes. */
870 uint32_t cPhysMemChunks;
871 /** Setting this to VMMDEV_EVENT_BALLOON_CHANGE_REQUEST indicates that the
872 * request is a response to that event.
873 * (Don't confuse this with VMMDevReq_AcknowledgeEvents.) */
874 uint32_t eventAck;
875} VMMDevGetMemBalloonChangeRequest;
876AssertCompileSize(VMMDevGetMemBalloonChangeRequest, 24+12);
877
878
879/**
880 * Change the size of the balloon.
881 *
882 * Used by VMMDevReq_ChangeMemBalloon.
883 */
884typedef struct
885{
886 /** Header. */
887 VMMDevRequestHeader header;
888 /** The number of pages in the array. */
889 uint32_t cPages;
890 /** true = inflate, false = deflate. */
891 uint32_t fInflate;
892 /** Physical address (RTGCPHYS) of each page, variable size. */
893 RTGCPHYS aPhysPage[1];
894} VMMDevChangeMemBalloon;
895AssertCompileSize(VMMDevChangeMemBalloon, 24+16);
896
897
898/**
899 * Guest statistics interval change request structure.
900 *
901 * Used by VMMDevReq_GetStatisticsChangeRequest.
902 */
903typedef struct
904{
905 /** Header. */
906 VMMDevRequestHeader header;
907 /** The interval in seconds. */
908 uint32_t u32StatInterval;
909 /** Setting this to VMMDEV_EVENT_STATISTICS_INTERVAL_CHANGE_REQUEST indicates
910 * that the request is a response to that event.
911 * (Don't confuse this with VMMDevReq_AcknowledgeEvents.) */
912 uint32_t eventAck;
913} VMMDevGetStatisticsChangeRequest;
914AssertCompileSize(VMMDevGetStatisticsChangeRequest, 24+8);
915
916
917/** The size of a string field in the credentials request (including '\\0').
918 * @see VMMDevCredentials */
919#define VMMDEV_CREDENTIALS_SZ_SIZE 128
920
921/**
922 * Credentials request structure.
923 *
924 * Used by VMMDevReq_QueryCredentials.
925 */
926typedef struct
927{
928 /** Header. */
929 VMMDevRequestHeader header;
930 /** IN/OUT: Request flags. */
931 uint32_t u32Flags;
932 /** OUT: User name (UTF-8). */
933 char szUserName[VMMDEV_CREDENTIALS_SZ_SIZE];
934 /** OUT: Password (UTF-8). */
935 char szPassword[VMMDEV_CREDENTIALS_SZ_SIZE];
936 /** OUT: Domain name (UTF-8). */
937 char szDomain[VMMDEV_CREDENTIALS_SZ_SIZE];
938} VMMDevCredentials;
939AssertCompileSize(VMMDevCredentials, 24+4+3*128);
940
941/** @name Credentials request flag (VMMDevCredentials::u32Flags)
942 * @{ */
943/** query from host whether credentials are present */
944#define VMMDEV_CREDENTIALS_QUERYPRESENCE RT_BIT(1)
945/** read credentials from host (can be combined with clear) */
946#define VMMDEV_CREDENTIALS_READ RT_BIT(2)
947/** clear credentials on host (can be combined with read) */
948#define VMMDEV_CREDENTIALS_CLEAR RT_BIT(3)
949/** read credentials for judgement in the guest */
950#define VMMDEV_CREDENTIALS_READJUDGE RT_BIT(8)
951/** clear credentials for judegement on the host */
952#define VMMDEV_CREDENTIALS_CLEARJUDGE RT_BIT(9)
953/** report credentials acceptance by guest */
954#define VMMDEV_CREDENTIALS_JUDGE_OK RT_BIT(10)
955/** report credentials denial by guest */
956#define VMMDEV_CREDENTIALS_JUDGE_DENY RT_BIT(11)
957/** report that no judgement could be made by guest */
958#define VMMDEV_CREDENTIALS_JUDGE_NOJUDGEMENT RT_BIT(12)
959
960/** flag telling the guest that credentials are present */
961#define VMMDEV_CREDENTIALS_PRESENT RT_BIT(16)
962/** flag telling guest that local logons should be prohibited */
963#define VMMDEV_CREDENTIALS_NOLOCALLOGON RT_BIT(17)
964/** @} */
965
966
967/**
968 * Seamless mode change request structure.
969 *
970 * Used by VMMDevReq_GetSeamlessChangeRequest.
971 */
972typedef struct
973{
974 /** Header. */
975 VMMDevRequestHeader header;
976
977 /** New seamless mode. */
978 VMMDevSeamlessMode mode;
979 /** Setting this to VMMDEV_EVENT_SEAMLESS_MODE_CHANGE_REQUEST indicates
980 * that the request is a response to that event.
981 * (Don't confuse this with VMMDevReq_AcknowledgeEvents.) */
982 uint32_t eventAck;
983} VMMDevSeamlessChangeRequest;
984AssertCompileSize(VMMDevSeamlessChangeRequest, 24+8);
985AssertCompileMemberOffset(VMMDevSeamlessChangeRequest, eventAck, 24+4);
986
987
988/**
989 * Display change request structure.
990 *
991 * Used by VMMDevReq_GetDisplayChangeRequest.
992 */
993typedef struct
994{
995 /** Header. */
996 VMMDevRequestHeader header;
997 /** Horizontal pixel resolution (0 = do not change). */
998 uint32_t xres;
999 /** Vertical pixel resolution (0 = do not change). */
1000 uint32_t yres;
1001 /** Bits per pixel (0 = do not change). */
1002 uint32_t bpp;
1003 /** Setting this to VMMDEV_EVENT_DISPLAY_CHANGE_REQUEST indicates
1004 * that the request is a response to that event.
1005 * (Don't confuse this with VMMDevReq_AcknowledgeEvents.) */
1006 uint32_t eventAck;
1007} VMMDevDisplayChangeRequest;
1008AssertCompileSize(VMMDevDisplayChangeRequest, 24+16);
1009
1010
1011/**
1012 * Display change request structure, version 2.
1013 *
1014 * Used by VMMDevReq_GetDisplayChangeRequest2.
1015 */
1016typedef struct
1017{
1018 /** Header. */
1019 VMMDevRequestHeader header;
1020 /** Horizontal pixel resolution (0 = do not change). */
1021 uint32_t xres;
1022 /** Vertical pixel resolution (0 = do not change). */
1023 uint32_t yres;
1024 /** Bits per pixel (0 = do not change). */
1025 uint32_t bpp;
1026 /** Setting this to VMMDEV_EVENT_DISPLAY_CHANGE_REQUEST indicates
1027 * that the request is a response to that event.
1028 * (Don't confuse this with VMMDevReq_AcknowledgeEvents.) */
1029 uint32_t eventAck;
1030 /** 0 for primary display, 1 for the first secondary, etc. */
1031 uint32_t display;
1032} VMMDevDisplayChangeRequest2;
1033AssertCompileSize(VMMDevDisplayChangeRequest2, 24+20);
1034
1035
1036/**
1037 * Display change request structure, version Extended.
1038 *
1039 * Used by VMMDevReq_GetDisplayChangeRequestEx.
1040 */
1041typedef struct
1042{
1043 /** Header. */
1044 VMMDevRequestHeader header;
1045 /** Horizontal pixel resolution (0 = do not change). */
1046 uint32_t xres;
1047 /** Vertical pixel resolution (0 = do not change). */
1048 uint32_t yres;
1049 /** Bits per pixel (0 = do not change). */
1050 uint32_t bpp;
1051 /** Setting this to VMMDEV_EVENT_DISPLAY_CHANGE_REQUEST indicates
1052 * that the request is a response to that event.
1053 * (Don't confuse this with VMMDevReq_AcknowledgeEvents.) */
1054 uint32_t eventAck;
1055 /** 0 for primary display, 1 for the first secondary, etc. */
1056 uint32_t display;
1057 /** New OriginX of secondary virtual screen */
1058 uint32_t cxOrigin;
1059 /** New OriginY of secondary virtual screen */
1060 uint32_t cyOrigin;
1061 /** Change in origin of the secondary virtaul scree is
1062 * required */
1063 bool fChangeOrigin;
1064 /** secondary virtual screen enabled or disabled */
1065 bool fEnabled;
1066} VMMDevDisplayChangeRequestEx;
1067AssertCompileSize(VMMDevDisplayChangeRequestEx, 24+32);
1068
1069
1070/**
1071 * Video mode supported request structure.
1072 *
1073 * Used by VMMDevReq_VideoModeSupported.
1074 */
1075typedef struct
1076{
1077 /** Header. */
1078 VMMDevRequestHeader header;
1079 /** IN: Horizontal pixel resolution. */
1080 uint32_t width;
1081 /** IN: Vertical pixel resolution. */
1082 uint32_t height;
1083 /** IN: Bits per pixel. */
1084 uint32_t bpp;
1085 /** OUT: Support indicator. */
1086 bool fSupported;
1087} VMMDevVideoModeSupportedRequest;
1088AssertCompileSize(VMMDevVideoModeSupportedRequest, 24+16);
1089
1090/**
1091 * Video mode supported request structure for a specific display.
1092 *
1093 * Used by VMMDevReq_VideoModeSupported2.
1094 */
1095typedef struct
1096{
1097 /** Header. */
1098 VMMDevRequestHeader header;
1099 /** IN: The guest display number. */
1100 uint32_t display;
1101 /** IN: Horizontal pixel resolution. */
1102 uint32_t width;
1103 /** IN: Vertical pixel resolution. */
1104 uint32_t height;
1105 /** IN: Bits per pixel. */
1106 uint32_t bpp;
1107 /** OUT: Support indicator. */
1108 bool fSupported;
1109} VMMDevVideoModeSupportedRequest2;
1110AssertCompileSize(VMMDevVideoModeSupportedRequest2, 24+20);
1111
1112/**
1113 * Video modes height reduction request structure.
1114 *
1115 * Used by VMMDevReq_GetHeightReduction.
1116 */
1117typedef struct
1118{
1119 /** Header. */
1120 VMMDevRequestHeader header;
1121 /** OUT: Height reduction in pixels. */
1122 uint32_t heightReduction;
1123} VMMDevGetHeightReductionRequest;
1124AssertCompileSize(VMMDevGetHeightReductionRequest, 24+4);
1125
1126
1127/**
1128 * VRDP change request structure.
1129 *
1130 * Used by VMMDevReq_GetVRDPChangeRequest.
1131 */
1132typedef struct
1133{
1134 /** Header */
1135 VMMDevRequestHeader header;
1136 /** Whether VRDP is active or not. */
1137 uint8_t u8VRDPActive;
1138 /** The configured experience level for active VRDP. */
1139 uint32_t u32VRDPExperienceLevel;
1140} VMMDevVRDPChangeRequest;
1141AssertCompileSize(VMMDevVRDPChangeRequest, 24+8);
1142AssertCompileMemberOffset(VMMDevVRDPChangeRequest, u8VRDPActive, 24);
1143AssertCompileMemberOffset(VMMDevVRDPChangeRequest, u32VRDPExperienceLevel, 24+4);
1144
1145/** @name VRDP Experience level (VMMDevVRDPChangeRequest::u32VRDPExperienceLevel)
1146 * @{ */
1147#define VRDP_EXPERIENCE_LEVEL_ZERO 0 /**< Theming disabled. */
1148#define VRDP_EXPERIENCE_LEVEL_LOW 1 /**< Full window dragging and desktop wallpaper disabled. */
1149#define VRDP_EXPERIENCE_LEVEL_MEDIUM 2 /**< Font smoothing, gradients. */
1150#define VRDP_EXPERIENCE_LEVEL_HIGH 3 /**< Animation effects disabled. */
1151#define VRDP_EXPERIENCE_LEVEL_FULL 4 /**< Everything enabled. */
1152/** @} */
1153
1154
1155/**
1156 * VBVA enable request structure.
1157 *
1158 * Used by VMMDevReq_VideoAccelEnable.
1159 */
1160typedef struct
1161{
1162 /** Header. */
1163 VMMDevRequestHeader header;
1164 /** 0 - disable, !0 - enable. */
1165 uint32_t u32Enable;
1166 /** The size of VBVAMEMORY::au8RingBuffer expected by driver.
1167 * The host will refuse to enable VBVA if the size is not equal to
1168 * VBVA_RING_BUFFER_SIZE.
1169 */
1170 uint32_t cbRingBuffer;
1171 /** Guest initializes the status to 0. Host sets appropriate VBVA_F_STATUS_ flags. */
1172 uint32_t fu32Status;
1173} VMMDevVideoAccelEnable;
1174AssertCompileSize(VMMDevVideoAccelEnable, 24+12);
1175
1176/** @name VMMDevVideoAccelEnable::fu32Status.
1177 * @{ */
1178#define VBVA_F_STATUS_ACCEPTED (0x01)
1179#define VBVA_F_STATUS_ENABLED (0x02)
1180/** @} */
1181
1182
1183/**
1184 * VBVA flush request structure.
1185 *
1186 * Used by VMMDevReq_VideoAccelFlush.
1187 */
1188typedef struct
1189{
1190 /** Header. */
1191 VMMDevRequestHeader header;
1192} VMMDevVideoAccelFlush;
1193AssertCompileSize(VMMDevVideoAccelFlush, 24);
1194
1195
1196/**
1197 * VBVA set visible region request structure.
1198 *
1199 * Used by VMMDevReq_VideoSetVisibleRegion.
1200 */
1201typedef struct
1202{
1203 /** Header. */
1204 VMMDevRequestHeader header;
1205 /** Number of rectangles */
1206 uint32_t cRect;
1207 /** Rectangle array.
1208 * @todo array is spelled aRects[1]. */
1209 RTRECT Rect;
1210} VMMDevVideoSetVisibleRegion;
1211AssertCompileSize(RTRECT, 16);
1212AssertCompileSize(VMMDevVideoSetVisibleRegion, 24+4+16);
1213
1214/**
1215 * CPU event types.
1216 */
1217typedef enum
1218{
1219 VMMDevCpuStatusType_Invalid = 0,
1220 VMMDevCpuStatusType_Disable = 1,
1221 VMMDevCpuStatusType_Enable = 2,
1222 VMMDevCpuStatusType_SizeHack = 0x7fffffff
1223} VMMDevCpuStatusType;
1224
1225/**
1226 * CPU hotplug event status request.
1227 */
1228typedef struct
1229{
1230 /** Header. */
1231 VMMDevRequestHeader header;
1232 /** Status type */
1233 VMMDevCpuStatusType enmStatusType;
1234} VMMDevCpuHotPlugStatusRequest;
1235AssertCompileSize(VMMDevCpuHotPlugStatusRequest, 24+4);
1236
1237/**
1238 * Get the ID of the changed CPU and event type.
1239 */
1240typedef struct
1241{
1242 /** Header. */
1243 VMMDevRequestHeader header;
1244 /** Event type */
1245 VMMDevCpuEventType enmEventType;
1246 /** core id of the CPU changed */
1247 uint32_t idCpuCore;
1248 /** package id of the CPU changed */
1249 uint32_t idCpuPackage;
1250} VMMDevGetCpuHotPlugRequest;
1251AssertCompileSize(VMMDevGetCpuHotPlugRequest, 24+4+4+4);
1252
1253
1254/**
1255 * Shared region description
1256 */
1257typedef struct VMMDEVSHAREDREGIONDESC
1258{
1259 RTGCPTR64 GCRegionAddr;
1260 uint32_t cbRegion;
1261 uint32_t u32Alignment;
1262} VMMDEVSHAREDREGIONDESC;
1263AssertCompileSize(VMMDEVSHAREDREGIONDESC, 16);
1264
1265#define VMMDEVSHAREDREGIONDESC_MAX 32
1266
1267/**
1268 * Shared module registration
1269 */
1270typedef struct
1271{
1272 /** Header. */
1273 VMMDevRequestHeader header;
1274 /** Shared module size. */
1275 uint32_t cbModule;
1276 /** Number of included region descriptors */
1277 uint32_t cRegions;
1278 /** Base address of the shared module. */
1279 RTGCPTR64 GCBaseAddr;
1280 /** Guest OS type. */
1281 VBOXOSFAMILY enmGuestOS;
1282 /** Alignment. */
1283 uint32_t u32Align;
1284 /** Module name */
1285 char szName[128];
1286 /** Module version */
1287 char szVersion[16];
1288 /** Shared region descriptor(s). */
1289 VMMDEVSHAREDREGIONDESC aRegions[1];
1290} VMMDevSharedModuleRegistrationRequest;
1291AssertCompileSize(VMMDevSharedModuleRegistrationRequest, 24+4+4+8+4+4+128+16+16);
1292
1293
1294/**
1295 * Shared module unregistration
1296 */
1297typedef struct
1298{
1299 /** Header. */
1300 VMMDevRequestHeader header;
1301 /** Shared module size. */
1302 uint32_t cbModule;
1303 /** Align at 8 byte boundary. */
1304 uint32_t u32Alignment;
1305 /** Base address of the shared module. */
1306 RTGCPTR64 GCBaseAddr;
1307 /** Module name */
1308 char szName[128];
1309 /** Module version */
1310 char szVersion[16];
1311} VMMDevSharedModuleUnregistrationRequest;
1312AssertCompileSize(VMMDevSharedModuleUnregistrationRequest, 24+4+4+8+128+16);
1313
1314
1315/**
1316 * Shared module periodic check
1317 */
1318typedef struct
1319{
1320 /** Header. */
1321 VMMDevRequestHeader header;
1322} VMMDevSharedModuleCheckRequest;
1323AssertCompileSize(VMMDevSharedModuleCheckRequest, 24);
1324
1325/**
1326 * Paging sharing enabled query
1327 */
1328typedef struct
1329{
1330 /** Header. */
1331 VMMDevRequestHeader header;
1332 /** Enabled flag (out) */
1333 bool fEnabled;
1334 /** Alignment */
1335 bool fAlignment[3];
1336} VMMDevPageSharingStatusRequest;
1337AssertCompileSize(VMMDevPageSharingStatusRequest, 24+4);
1338
1339
1340/**
1341 * Page sharing status query (debug build only)
1342 */
1343typedef struct
1344{
1345 /** Header. */
1346 VMMDevRequestHeader header;
1347 /** Page address. */
1348 RTGCPTR GCPtrPage;
1349 /** Page flags. */
1350 uint64_t uPageFlags;
1351 /** Shared flag (out) */
1352 bool fShared;
1353 /** Alignment */
1354 bool fAlignment[3];
1355} VMMDevPageIsSharedRequest;
1356
1357/**
1358 * Session id request structure.
1359 *
1360 * Used by VMMDevReq_GetSessionId.
1361 */
1362typedef struct
1363{
1364 /** Header */
1365 VMMDevRequestHeader header;
1366 /** OUT: unique session id; the id will be different after each start, reset or restore of the VM */
1367 uint64_t idSession;
1368} VMMDevReqSessionId;
1369AssertCompileSize(VMMDevReqSessionId, 24+8);
1370
1371
1372/**
1373 * Write Core Dump request.
1374 *
1375 * Used by VMMDevReq_WriteCoreDump.
1376 */
1377typedef struct
1378{
1379 /** Header. */
1380 VMMDevRequestHeader header;
1381 /** Flags (reserved, MBZ). */
1382 uint32_t fFlags;
1383} VMMDevReqWriteCoreDump;
1384AssertCompileSize(VMMDevReqWriteCoreDump, 24+4);
1385
1386/** Heart beat check state structure.
1387 * Used by VMMDevReq_HeartbeatConfigure. */
1388typedef struct
1389{
1390 /** Header. */
1391 VMMDevRequestHeader header;
1392 /** OUT: Guest heartbeat interval in nanosec. */
1393 uint64_t cNsInterval;
1394 /** Heartbeat check flag. */
1395 bool fEnabled;
1396} VMMDevReqHeartbeat;
1397AssertCompileSize(VMMDevReqHeartbeat, 24+12);
1398
1399
1400
1401#ifdef VBOX_WITH_HGCM
1402
1403/** @name HGCM flags.
1404 * @{
1405 */
1406# define VBOX_HGCM_REQ_DONE RT_BIT_32(VBOX_HGCM_REQ_DONE_BIT)
1407# define VBOX_HGCM_REQ_DONE_BIT 0
1408# define VBOX_HGCM_REQ_CANCELLED (0x2)
1409/** @} */
1410
1411/**
1412 * HGCM request header.
1413 */
1414typedef struct VMMDevHGCMRequestHeader
1415{
1416 /** Request header. */
1417 VMMDevRequestHeader header;
1418
1419 /** HGCM flags. */
1420 uint32_t fu32Flags;
1421
1422 /** Result code. */
1423 int32_t result;
1424} VMMDevHGCMRequestHeader;
1425AssertCompileSize(VMMDevHGCMRequestHeader, 24+8);
1426
1427/**
1428 * HGCM connect request structure.
1429 *
1430 * Used by VMMDevReq_HGCMConnect.
1431 */
1432typedef struct
1433{
1434 /** HGCM request header. */
1435 VMMDevHGCMRequestHeader header;
1436
1437 /** IN: Description of service to connect to. */
1438 HGCMServiceLocation loc;
1439
1440 /** OUT: Client identifier assigned by local instance of HGCM. */
1441 uint32_t u32ClientID;
1442} VMMDevHGCMConnect;
1443AssertCompileSize(VMMDevHGCMConnect, 32+132+4);
1444
1445
1446/**
1447 * HGCM disconnect request structure.
1448 *
1449 * Used by VMMDevReq_HGCMDisconnect.
1450 */
1451typedef struct
1452{
1453 /** HGCM request header. */
1454 VMMDevHGCMRequestHeader header;
1455
1456 /** IN: Client identifier. */
1457 uint32_t u32ClientID;
1458} VMMDevHGCMDisconnect;
1459AssertCompileSize(VMMDevHGCMDisconnect, 32+4);
1460
1461/**
1462 * HGCM call request structure.
1463 *
1464 * Used by VMMDevReq_HGCMCall, VMMDevReq_HGCMCall32 and VMMDevReq_HGCMCall64.
1465 */
1466typedef struct
1467{
1468 /* request header */
1469 VMMDevHGCMRequestHeader header;
1470
1471 /** IN: Client identifier. */
1472 uint32_t u32ClientID;
1473 /** IN: Service function number. */
1474 uint32_t u32Function;
1475 /** IN: Number of parameters. */
1476 uint32_t cParms;
1477 /** Parameters follow in form: HGCMFunctionParameter aParms[X]; */
1478} VMMDevHGCMCall;
1479AssertCompileSize(VMMDevHGCMCall, 32+12);
1480
1481/** @name Direction of data transfer (HGCMPageListInfo::flags). Bit flags.
1482 * @{ */
1483#define VBOX_HGCM_F_PARM_DIRECTION_NONE UINT32_C(0x00000000)
1484#define VBOX_HGCM_F_PARM_DIRECTION_TO_HOST UINT32_C(0x00000001)
1485#define VBOX_HGCM_F_PARM_DIRECTION_FROM_HOST UINT32_C(0x00000002)
1486#define VBOX_HGCM_F_PARM_DIRECTION_BOTH UINT32_C(0x00000003)
1487/** Macro for validating that the specified flags are valid. */
1488#define VBOX_HGCM_F_PARM_ARE_VALID(fFlags) \
1489 ( (fFlags) > VBOX_HGCM_F_PARM_DIRECTION_NONE \
1490 && (fFlags) < VBOX_HGCM_F_PARM_DIRECTION_BOTH )
1491/** @} */
1492
1493/**
1494 * VMMDevHGCMParmType_PageList points to this structure to actually describe the
1495 * buffer.
1496 */
1497typedef struct
1498{
1499 uint32_t flags; /**< VBOX_HGCM_F_PARM_*. */
1500 uint16_t offFirstPage; /**< Offset in the first page where data begins. */
1501 uint16_t cPages; /**< Number of pages. */
1502 RTGCPHYS64 aPages[1]; /**< Page addresses. */
1503} HGCMPageListInfo;
1504AssertCompileSize(HGCMPageListInfo, 4+2+2+8);
1505
1506
1507/** Get the pointer to the first parmater of a HGCM call request. */
1508# define VMMDEV_HGCM_CALL_PARMS(a) ((HGCMFunctionParameter *)((uint8_t *)(a) + sizeof (VMMDevHGCMCall)))
1509/** Get the pointer to the first parmater of a 32-bit HGCM call request. */
1510# define VMMDEV_HGCM_CALL_PARMS32(a) ((HGCMFunctionParameter32 *)((uint8_t *)(a) + sizeof (VMMDevHGCMCall)))
1511
1512# ifdef VBOX_WITH_64_BITS_GUESTS
1513/* Explicit defines for the host code. */
1514# ifdef VBOX_HGCM_HOST_CODE
1515# define VMMDEV_HGCM_CALL_PARMS32(a) ((HGCMFunctionParameter32 *)((uint8_t *)(a) + sizeof (VMMDevHGCMCall)))
1516# define VMMDEV_HGCM_CALL_PARMS64(a) ((HGCMFunctionParameter64 *)((uint8_t *)(a) + sizeof (VMMDevHGCMCall)))
1517# endif /* VBOX_HGCM_HOST_CODE */
1518# endif /* VBOX_WITH_64_BITS_GUESTS */
1519
1520# define VBOX_HGCM_MAX_PARMS 32
1521
1522/**
1523 * HGCM cancel request structure.
1524 *
1525 * The Cancel request is issued using the same physical memory address as was
1526 * used for the corresponding initial HGCMCall.
1527 *
1528 * Used by VMMDevReq_HGCMCancel.
1529 */
1530typedef struct
1531{
1532 /** Header. */
1533 VMMDevHGCMRequestHeader header;
1534} VMMDevHGCMCancel;
1535AssertCompileSize(VMMDevHGCMCancel, 32);
1536
1537/**
1538 * HGCM cancel request structure, version 2.
1539 *
1540 * Used by VMMDevReq_HGCMCancel2.
1541 *
1542 * VINF_SUCCESS when cancelled.
1543 * VERR_NOT_FOUND if the specified request cannot be found.
1544 * VERR_INVALID_PARAMETER if the address is invalid valid.
1545 */
1546typedef struct
1547{
1548 /** Header. */
1549 VMMDevRequestHeader header;
1550 /** The physical address of the request to cancel. */
1551 RTGCPHYS32 physReqToCancel;
1552} VMMDevHGCMCancel2;
1553AssertCompileSize(VMMDevHGCMCancel2, 24+4);
1554
1555#endif /* VBOX_WITH_HGCM */
1556
1557
1558/**
1559 * Inline helper to determine the request size for the given operation.
1560 * Returns 0 if the given operation is not handled and/or supported.
1561 *
1562 * @returns Size.
1563 * @param requestType The VMMDev request type.
1564 */
1565DECLINLINE(size_t) vmmdevGetRequestSize(VMMDevRequestType requestType)
1566{
1567 switch (requestType)
1568 {
1569 case VMMDevReq_GetMouseStatus:
1570 case VMMDevReq_SetMouseStatus:
1571 return sizeof(VMMDevReqMouseStatus);
1572 case VMMDevReq_SetPointerShape:
1573 return sizeof(VMMDevReqMousePointer);
1574 case VMMDevReq_GetHostVersion:
1575 return sizeof(VMMDevReqHostVersion);
1576 case VMMDevReq_Idle:
1577 return sizeof(VMMDevReqIdle);
1578 case VMMDevReq_GetHostTime:
1579 return sizeof(VMMDevReqHostTime);
1580 case VMMDevReq_GetHypervisorInfo:
1581 case VMMDevReq_SetHypervisorInfo:
1582 return sizeof(VMMDevReqHypervisorInfo);
1583 case VMMDevReq_RegisterPatchMemory:
1584 case VMMDevReq_DeregisterPatchMemory:
1585 return sizeof(VMMDevReqPatchMemory);
1586 case VMMDevReq_SetPowerStatus:
1587 return sizeof(VMMDevPowerStateRequest);
1588 case VMMDevReq_AcknowledgeEvents:
1589 return sizeof(VMMDevEvents);
1590 case VMMDevReq_ReportGuestInfo:
1591 return sizeof(VMMDevReportGuestInfo);
1592 case VMMDevReq_ReportGuestInfo2:
1593 return sizeof(VMMDevReportGuestInfo2);
1594 case VMMDevReq_ReportGuestStatus:
1595 return sizeof(VMMDevReportGuestStatus);
1596 case VMMDevReq_ReportGuestUserState:
1597 return sizeof(VMMDevReportGuestUserState);
1598 case VMMDevReq_GetDisplayChangeRequest:
1599 return sizeof(VMMDevDisplayChangeRequest);
1600 case VMMDevReq_GetDisplayChangeRequest2:
1601 return sizeof(VMMDevDisplayChangeRequest2);
1602 case VMMDevReq_GetDisplayChangeRequestEx:
1603 return sizeof(VMMDevDisplayChangeRequestEx);
1604 case VMMDevReq_VideoModeSupported:
1605 return sizeof(VMMDevVideoModeSupportedRequest);
1606 case VMMDevReq_GetHeightReduction:
1607 return sizeof(VMMDevGetHeightReductionRequest);
1608 case VMMDevReq_ReportGuestCapabilities:
1609 return sizeof(VMMDevReqGuestCapabilities);
1610 case VMMDevReq_SetGuestCapabilities:
1611 return sizeof(VMMDevReqGuestCapabilities2);
1612#ifdef VBOX_WITH_HGCM
1613 case VMMDevReq_HGCMConnect:
1614 return sizeof(VMMDevHGCMConnect);
1615 case VMMDevReq_HGCMDisconnect:
1616 return sizeof(VMMDevHGCMDisconnect);
1617#ifdef VBOX_WITH_64_BITS_GUESTS
1618 case VMMDevReq_HGCMCall32:
1619 return sizeof(VMMDevHGCMCall);
1620 case VMMDevReq_HGCMCall64:
1621 return sizeof(VMMDevHGCMCall);
1622#else
1623 case VMMDevReq_HGCMCall:
1624 return sizeof(VMMDevHGCMCall);
1625#endif /* VBOX_WITH_64_BITS_GUESTS */
1626 case VMMDevReq_HGCMCancel:
1627 return sizeof(VMMDevHGCMCancel);
1628#endif /* VBOX_WITH_HGCM */
1629 case VMMDevReq_VideoAccelEnable:
1630 return sizeof(VMMDevVideoAccelEnable);
1631 case VMMDevReq_VideoAccelFlush:
1632 return sizeof(VMMDevVideoAccelFlush);
1633 case VMMDevReq_VideoSetVisibleRegion:
1634 /* The original protocol didn't consider a guest with NO visible
1635 * windows */
1636 return sizeof(VMMDevVideoSetVisibleRegion) - sizeof(RTRECT);
1637 case VMMDevReq_GetSeamlessChangeRequest:
1638 return sizeof(VMMDevSeamlessChangeRequest);
1639 case VMMDevReq_QueryCredentials:
1640 return sizeof(VMMDevCredentials);
1641 case VMMDevReq_ReportGuestStats:
1642 return sizeof(VMMDevReportGuestStats);
1643 case VMMDevReq_GetMemBalloonChangeRequest:
1644 return sizeof(VMMDevGetMemBalloonChangeRequest);
1645 case VMMDevReq_GetStatisticsChangeRequest:
1646 return sizeof(VMMDevGetStatisticsChangeRequest);
1647 case VMMDevReq_ChangeMemBalloon:
1648 return sizeof(VMMDevChangeMemBalloon);
1649 case VMMDevReq_GetVRDPChangeRequest:
1650 return sizeof(VMMDevVRDPChangeRequest);
1651 case VMMDevReq_LogString:
1652 return sizeof(VMMDevReqLogString);
1653 case VMMDevReq_CtlGuestFilterMask:
1654 return sizeof(VMMDevCtlGuestFilterMask);
1655 case VMMDevReq_GetCpuHotPlugRequest:
1656 return sizeof(VMMDevGetCpuHotPlugRequest);
1657 case VMMDevReq_SetCpuHotPlugStatus:
1658 return sizeof(VMMDevCpuHotPlugStatusRequest);
1659 case VMMDevReq_RegisterSharedModule:
1660 return sizeof(VMMDevSharedModuleRegistrationRequest);
1661 case VMMDevReq_UnregisterSharedModule:
1662 return sizeof(VMMDevSharedModuleUnregistrationRequest);
1663 case VMMDevReq_CheckSharedModules:
1664 return sizeof(VMMDevSharedModuleCheckRequest);
1665 case VMMDevReq_GetPageSharingStatus:
1666 return sizeof(VMMDevPageSharingStatusRequest);
1667 case VMMDevReq_DebugIsPageShared:
1668 return sizeof(VMMDevPageIsSharedRequest);
1669 case VMMDevReq_GetSessionId:
1670 return sizeof(VMMDevReqSessionId);
1671 case VMMDevReq_HeartbeatConfigure:
1672 return sizeof(VMMDevReqHeartbeat);
1673 case VMMDevReq_GuestHeartbeat:
1674 return sizeof(VMMDevRequestHeader);
1675 default:
1676 break;
1677 }
1678
1679 return 0;
1680}
1681
1682
1683/**
1684 * Initializes a request structure.
1685 *
1686 * @returns VBox status code.
1687 * @param req The request structure to initialize.
1688 * @param type The request type.
1689 */
1690DECLINLINE(int) vmmdevInitRequest(VMMDevRequestHeader *req, VMMDevRequestType type)
1691{
1692 uint32_t requestSize;
1693 if (!req)
1694 return VERR_INVALID_PARAMETER;
1695 requestSize = (uint32_t)vmmdevGetRequestSize(type);
1696 if (!requestSize)
1697 return VERR_INVALID_PARAMETER;
1698 req->size = requestSize;
1699 req->version = VMMDEV_REQUEST_HEADER_VERSION;
1700 req->requestType = type;
1701 req->rc = VERR_GENERAL_FAILURE;
1702 req->reserved1 = 0;
1703 req->reserved2 = 0;
1704 return VINF_SUCCESS;
1705}
1706
1707/** @} */
1708
1709/** @name VBVA ring defines.
1710 *
1711 * The VBVA ring buffer is suitable for transferring large (< 2GB) amount of
1712 * data. For example big bitmaps which do not fit to the buffer.
1713 *
1714 * Guest starts writing to the buffer by initializing a record entry in the
1715 * aRecords queue. VBVA_F_RECORD_PARTIAL indicates that the record is being
1716 * written. As data is written to the ring buffer, the guest increases off32End
1717 * for the record.
1718 *
1719 * The host reads the aRecords on flushes and processes all completed records.
1720 * When host encounters situation when only a partial record presents and
1721 * cbRecord & ~VBVA_F_RECORD_PARTIAL >= VBVA_RING_BUFFER_SIZE -
1722 * VBVA_RING_BUFFER_THRESHOLD, the host fetched all record data and updates
1723 * off32Head. After that on each flush the host continues fetching the data
1724 * until the record is completed.
1725 *
1726 */
1727#define VMMDEV_VBVA_RING_BUFFER_SIZE (_4M - _1K)
1728#define VMMDEV_VBVA_RING_BUFFER_THRESHOLD (4 * _1K)
1729
1730#define VMMDEV_VBVA_MAX_RECORDS (64)
1731/** @} */
1732
1733/**
1734 * VBVA record.
1735 */
1736typedef struct VMMDEVVBVARECORD
1737{
1738 /** The length of the record. Changed by guest. */
1739 uint32_t cbRecord;
1740} VMMDEVVBVARECORD;
1741AssertCompileSize(VMMDEVVBVARECORD, 4);
1742
1743#if ARCH_BITS >= 32
1744
1745/**
1746 * VBVA memory layout.
1747 *
1748 * This is a subsection of the VMMDevMemory structure.
1749 */
1750typedef struct VBVAMEMORY
1751{
1752 /** VBVA_F_MODE_*. */
1753 uint32_t fu32ModeFlags;
1754
1755 /** The offset where the data start in the buffer. */
1756 uint32_t off32Data;
1757 /** The offset where next data must be placed in the buffer. */
1758 uint32_t off32Free;
1759
1760 /** The ring buffer for data. */
1761 uint8_t au8RingBuffer[VMMDEV_VBVA_RING_BUFFER_SIZE];
1762
1763 /** The queue of record descriptions. */
1764 VMMDEVVBVARECORD aRecords[VMMDEV_VBVA_MAX_RECORDS];
1765 uint32_t indexRecordFirst;
1766 uint32_t indexRecordFree;
1767
1768 /** RDP orders supported by the client. The guest reports only them
1769 * and falls back to DIRTY rects for not supported ones.
1770 *
1771 * (1 << VBVA_VRDP_*)
1772 */
1773 uint32_t fu32SupportedOrders;
1774
1775} VBVAMEMORY;
1776AssertCompileSize(VBVAMEMORY, 12 + (_4M-_1K) + 4*64 + 12);
1777
1778
1779/**
1780 * The layout of VMMDEV RAM region that contains information for guest.
1781 */
1782typedef struct VMMDevMemory
1783{
1784 /** The size of this structure. */
1785 uint32_t u32Size;
1786 /** The structure version. (VMMDEV_MEMORY_VERSION) */
1787 uint32_t u32Version;
1788
1789 union
1790 {
1791 struct
1792 {
1793 /** Flag telling that VMMDev set the IRQ and acknowlegment is required */
1794 bool fHaveEvents;
1795 } V1_04;
1796
1797 struct
1798 {
1799 /** Pending events flags, set by host. */
1800 uint32_t u32HostEvents;
1801 /** Mask of events the guest wants to see, set by guest. */
1802 uint32_t u32GuestEventMask;
1803 } V1_03;
1804 } V;
1805
1806 VBVAMEMORY vbvaMemory;
1807
1808} VMMDevMemory;
1809AssertCompileSize(VMMDevMemory, 8+8 + (12 + (_4M-_1K) + 4*64 + 12) );
1810AssertCompileMemberOffset(VMMDevMemory, vbvaMemory, 16);
1811
1812/** Version of VMMDevMemory structure (VMMDevMemory::u32Version). */
1813# define VMMDEV_MEMORY_VERSION (1)
1814
1815#endif /* ARCH_BITS >= 32 */
1816
1817/** @} */
1818
1819RT_C_DECLS_END
1820#pragma pack()
1821
1822#endif
1823
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