VirtualBox

source: vbox/trunk/include/VBox/VBoxGuest.h@ 3089

Last change on this file since 3089 was 3089, checked in by vboxsync, 18 years ago

Defined a constant for maximum number of HGCM function parameters.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 29.6 KB
Line 
1/** @file
2 * VBoxGuest - VirtualBox Guest Additions interface
3 */
4
5/*
6 * Copyright (C) 2006-2007 innotek GmbH
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.215389.xyz. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License as published by the Free Software Foundation,
12 * in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
13 * distribution. VirtualBox OSE is distributed in the hope that it will
14 * be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * If you received this file as part of a commercial VirtualBox
17 * distribution, then only the terms of your commercial VirtualBox
18 * license agreement apply instead of the previous paragraph.
19 */
20
21#ifndef __VBox_VBoxGuest_h__
22#define __VBox_VBoxGuest_h__
23
24#include <iprt/cdefs.h>
25#include <iprt/types.h>
26#include <VBox/err.h>
27#include <VBox/ostypes.h>
28
29/*******************************************************************************
30* Defined Constants And Macros *
31*******************************************************************************/
32
33/** @todo The following is a temporary fix for the problem of accessing
34 hypervisor pointers from within guest additions */
35
36/** Hypervisor linear pointer size type */
37typedef uint32_t vmmDevHypPtr;
38/** Hypervisor physical pointer size type */
39typedef uint32_t vmmDevHypPhys;
40
41#ifdef __WIN__
42/** The support service name. */
43#define VBOXGUEST_SERVICE_NAME "VBoxGuest"
44/** Win32 Device name. */
45#define VBOXGUEST_DEVICE_NAME "\\\\.\\VBoxGuest"
46/** Global name for Win2k+ */
47#define VBOXGUEST_DEVICE_NAME_GLOBAL "\\\\.\\Global\\VBoxGuest"
48/** Win32 driver name */
49#define VBOXGUEST_DEVICE_NAME_NT L"\\Device\\VBoxGuest"
50/** device name */
51#define VBOXGUEST_DEVICE_NAME_DOS L"\\DosDevices\\VBoxGuest"
52#else /* !__WIN__ */
53#define VBOXGUEST_DEVICE_NAME "/dev/vboxadd"
54#endif
55
56/** VirtualBox vendor ID */
57#define VBOX_PCI_VENDORID (0x80ee)
58
59/** VMMDev PCI card identifiers */
60#define VMMDEV_VENDORID VBOX_PCI_VENDORID
61#define VMMDEV_DEVICEID (0xcafe)
62
63/** VirtualBox graphics card identifiers */
64#define VBOX_VENDORID VBOX_PCI_VENDORID
65#define VBOX_VESA_VENDORID VBOX_PCI_VENDORID
66#define VBOX_DEVICEID (0xbeef)
67#define VBOX_VESA_DEVICEID (0xbeef)
68
69/**
70 * VBoxGuest port definitions
71 * @{
72 */
73
74/** guest can (== wants to) handle absolute coordinates */
75#define VBOXGUEST_MOUSE_GUEST_CAN_ABSOLUTE BIT(0)
76/** host can (== wants to) send absolute coordinates */
77#define VBOXGUEST_MOUSE_HOST_CAN_ABSOLUTE BIT(1)
78/** guest can *NOT* switch to software cursor and therefore depends on the host cursor */
79#define VBOXGUEST_MOUSE_GUEST_NEEDS_HOST_CURSOR BIT(2)
80/** host does NOT provide support for drawing the cursor itself (e.g. L4 console) */
81#define VBOXGUEST_MOUSE_HOST_CANNOT_HWPOINTER BIT(3)
82
83/** fictive start address of the hypervisor physical memory for MmMapIoSpace */
84#define HYPERVISOR_PHYSICAL_START 0xf8000000
85
86/*
87 * VMMDev Generic Request Interface
88 */
89
90/** port for generic request interface */
91#define PORT_VMMDEV_REQUEST_OFFSET 0
92
93/** Current version of the VMMDev interface.
94 *
95 * Additions are allowed to work only if
96 * additions_major == vmmdev_current && additions_minor <= vmmdev_current.
97 * Additions version is reported to host (VMMDev) by VMMDevReq_ReportGuestInfo.
98 */
99#define VMMDEV_VERSION_MAJOR (0x1)
100#define VMMDEV_VERSION_MINOR (0x4)
101#define VMMDEV_VERSION ((VMMDEV_VERSION_MAJOR << 16) | VMMDEV_VERSION_MINOR)
102
103/**
104 * VMMDev request types.
105 * @note when updating this, adjust vmmdevGetRequestSize() as well
106 */
107typedef enum
108{
109 VMMDevReq_InvalidRequest = 0,
110 VMMDevReq_GetMouseStatus = 1,
111 VMMDevReq_SetMouseStatus = 2,
112 VMMDevReq_SetPointerShape = 3,
113 /** @todo implement on host side */
114 VMMDevReq_GetHostVersion = 4,
115 VMMDevReq_Idle = 5,
116 VMMDevReq_GetHostTime = 10,
117 VMMDevReq_GetHypervisorInfo = 20,
118 VMMDevReq_SetHypervisorInfo = 21,
119 VMMDevReq_SetPowerStatus = 30,
120 VMMDevReq_AcknowledgeEvents = 41,
121 VMMDevReq_CtlGuestFilterMask = 42,
122 VMMDevReq_ReportGuestInfo = 50,
123 VMMDevReq_GetDisplayChangeRequest = 51,
124 VMMDevReq_VideoModeSupported = 52,
125 VMMDevReq_GetHeightReduction = 53,
126#ifdef VBOX_HGCM
127 VMMDevReq_HGCMConnect = 60,
128 VMMDevReq_HGCMDisconnect = 61,
129 VMMDevReq_HGCMCall = 62,
130#endif
131 VMMDevReq_VideoAccelEnable = 70,
132 VMMDevReq_VideoAccelFlush = 71,
133 VMMDevReq_QueryCredentials = 100,
134 VMMDevReq_ReportCredentialsJudgement = 101,
135 VMMDevReq_SizeHack = 0x7fffffff
136} VMMDevRequestType;
137
138/** Version of VMMDevRequestHeader structure. */
139#define VMMDEV_REQUEST_HEADER_VERSION (0x10001)
140
141#pragma pack(4)
142/** generic VMMDev request header */
143typedef struct
144{
145 /** size of the structure in bytes (including body). Filled by caller */
146 uint32_t size;
147 /** version of the structure. Filled by caller */
148 uint32_t version;
149 /** type of the request */
150 VMMDevRequestType requestType;
151 /** return code. Filled by VMMDev */
152 int32_t rc;
153 /** reserved fields */
154 uint32_t reserved1;
155 uint32_t reserved2;
156} VMMDevRequestHeader;
157
158/** mouse status request structure */
159typedef struct
160{
161 /** header */
162 VMMDevRequestHeader header;
163 /** mouse feature mask */
164 uint32_t mouseFeatures;
165 /** mouse x position */
166 uint32_t pointerXPos;
167 /** mouse y position */
168 uint32_t pointerYPos;
169} VMMDevReqMouseStatus;
170
171/** Note VBOX_MOUSE_POINTER_* flags are used in guest video driver,
172 * values must be <= 0x8000 and must not be changed.
173 */
174
175/** pointer is visible */
176#define VBOX_MOUSE_POINTER_VISIBLE (0x0001)
177/** pointer has alpha channel */
178#define VBOX_MOUSE_POINTER_ALPHA (0x0002)
179/** pointerData contains new pointer shape */
180#define VBOX_MOUSE_POINTER_SHAPE (0x0004)
181
182/** mouse pointer shape/visibility change request */
183typedef struct
184{
185 /** header */
186 VMMDevRequestHeader header;
187 /** VBOX_MOUSE_POINTER_* bit flags */
188 uint32_t fFlags;
189 /** x coordinate of hot spot */
190 uint32_t xHot;
191 /** y coordinate of hot spot */
192 uint32_t yHot;
193 /** width of the pointer in pixels */
194 uint32_t width;
195 /** height of the pointer in scanlines */
196 uint32_t height;
197 /** Pointer data.
198 *
199 ****
200 * The data consists of 1 bpp AND mask followed by 32 bpp XOR (color) mask.
201 *
202 * For pointers without alpha channel the XOR mask pixels are 32 bit values: (lsb)BGR0(msb).
203 * For pointers with alpha channel the XOR mask consists of (lsb)BGRA(msb) 32 bit values.
204 *
205 * Guest driver must create the AND mask for pointers with alpha channel, so if host does not
206 * support alpha, the pointer could be displayed as a normal color pointer. The AND mask can
207 * be constructed from alpha values. For example alpha value >= 0xf0 means bit 0 in the AND mask.
208 *
209 * The AND mask is 1 bpp bitmap with byte aligned scanlines. Size of AND mask,
210 * therefore, is cbAnd = (width + 7) / 8 * height. The padding bits at the
211 * end of any scanline are undefined.
212 *
213 * The XOR mask follows the AND mask on the next 4 bytes aligned offset:
214 * uint8_t *pXor = pAnd + (cbAnd + 3) & ~3
215 * Bytes in the gap between the AND and the XOR mask are undefined.
216 * XOR mask scanlines have no gap between them and size of XOR mask is:
217 * cXor = width * 4 * height.
218 ****
219 *
220 * Preallocate 4 bytes for accessing actual data as p->pointerData
221 */
222 char pointerData[4];
223} VMMDevReqMousePointer;
224
225/** host version request structure */
226typedef struct
227{
228 /** header */
229 VMMDevRequestHeader header;
230 /** major version */
231 uint32_t major;
232 /** minor version */
233 uint32_t minor;
234 /** build number */
235 uint32_t build;
236} VMMDevReqHostVersion;
237
238/** idle request structure */
239typedef struct
240{
241 /** header */
242 VMMDevRequestHeader header;
243} VMMDevReqIdle;
244
245/** host time request structure */
246typedef struct
247{
248 /** header */
249 VMMDevRequestHeader header;
250 /** time in milliseconds since unix epoch. Filled by VMMDev. */
251 uint64_t time;
252} VMMDevReqHostTime;
253
254/** hypervisor info structure */
255typedef struct
256{
257 /** header */
258 VMMDevRequestHeader header;
259 /** guest virtual address of proposed hypervisor start */
260 vmmDevHypPtr hypervisorStart;
261 /** hypervisor size in bytes */
262 uint32_t hypervisorSize;
263} VMMDevReqHypervisorInfo;
264
265/** system power requests */
266typedef enum
267{
268 VMMDevPowerState_Invalid = 0,
269 VMMDevPowerState_Pause = 1,
270 VMMDevPowerState_PowerOff = 2,
271 VMMDevPowerState_SaveState = 3,
272 VMMDevPowerState_SizeHack = 0x7fffffff
273} VMMDevPowerState;
274
275/** system power status structure */
276typedef struct
277{
278 /** header */
279 VMMDevRequestHeader header;
280 /** power state request */
281 VMMDevPowerState powerState;
282} VMMDevPowerStateRequest;
283
284/** pending events structure */
285typedef struct
286{
287 /** header */
288 VMMDevRequestHeader header;
289 /** pending event bitmap */
290 uint32_t events;
291} VMMDevEvents;
292
293/** guest filter mask control */
294typedef struct
295{
296 /** header */
297 VMMDevRequestHeader header;
298 /** mask of events to be added to filter */
299 uint32_t u32OrMask;
300 /** mask of events to be removed from filter */
301 uint32_t u32NotMask;
302} VMMDevCtlGuestFilterMask;
303
304/** guest information structure */
305typedef struct VBoxGuestInfo
306{
307 /** The VMMDev interface version expected by additions. */
308 uint32_t additionsVersion;
309 /** guest OS type */
310 OSType osType;
311 /** @todo */
312} VBoxGuestInfo;
313
314/** guest information structure */
315typedef struct
316{
317 /** header */
318 VMMDevRequestHeader header;
319 /** Guest information. */
320 VBoxGuestInfo guestInfo;
321} VMMDevReportGuestInfo;
322
323/** display change request structure */
324typedef struct
325{
326 /** header */
327 VMMDevRequestHeader header;
328 /** horizontal pixel resolution (0 = do not change) */
329 uint32_t xres;
330 /** vertical pixel resolution (0 = do not change) */
331 uint32_t yres;
332 /** bits per pixel (0 = do not change) */
333 uint32_t bpp;
334 /** Flag that the request is an acknowlegement for the VMMDEV_EVENT_DISPLAY_CHANGE_REQUEST.
335 * Values: 0 - just querying, VMMDEV_EVENT_DISPLAY_CHANGE_REQUEST - event acknowledged.
336 */
337 uint32_t eventAck;
338} VMMDevDisplayChangeRequest;
339
340/** video mode supported request structure */
341typedef struct
342{
343 /** header */
344 VMMDevRequestHeader header;
345 /** horizontal pixel resolution (input) */
346 uint32_t width;
347 /** vertical pixel resolution (input) */
348 uint32_t height;
349 /** bits per pixel (input) */
350 uint32_t bpp;
351 /** supported flag (output) */
352 bool fSupported;
353} VMMDevVideoModeSupportedRequest;
354
355/** video modes height reduction request structure */
356typedef struct
357{
358 /** header */
359 VMMDevRequestHeader header;
360 /** height reduction in pixels (output) */
361 uint32_t heightReduction;
362} VMMDevGetHeightReductionRequest;
363
364#pragma pack()
365
366#ifdef VBOX_HGCM
367
368/** HGCM flags.
369 * @{
370 */
371#define VBOX_HGCM_REQ_DONE (0x1)
372#define VBOX_HGCM_REQ_CANCELLED (0x2)
373/** @} */
374
375#pragma pack(4)
376typedef struct _VMMDevHGCMRequestHeader
377{
378 /** Request header. */
379 VMMDevRequestHeader header;
380
381 /** HGCM flags. */
382 uint32_t fu32Flags;
383
384 /** Result code. */
385 int32_t result;
386} VMMDevHGCMRequestHeader;
387
388/** HGCM service location types. */
389typedef enum
390{
391 VMMDevHGCMLoc_Invalid = 0,
392 VMMDevHGCMLoc_LocalHost = 1,
393 VMMDevHGCMLoc_LocalHost_Existing = 2,
394 VMMDevHGCMLoc_SizeHack = 0x7fffffff
395} HGCMServiceLocationType;
396
397typedef struct
398{
399 char achName[128];
400} HGCMServiceLocationHost;
401
402typedef struct HGCMSERVICELOCATION
403{
404 /** Type of the location. */
405 HGCMServiceLocationType type;
406
407 union
408 {
409 HGCMServiceLocationHost host;
410 } u;
411} HGCMServiceLocation;
412
413typedef struct
414{
415 /* request header */
416 VMMDevHGCMRequestHeader header;
417
418 /** IN: Description of service to connect to. */
419 HGCMServiceLocation loc;
420
421 /** OUT: Client identifier assigned by local instance of HGCM. */
422 uint32_t u32ClientID;
423} VMMDevHGCMConnect;
424
425typedef struct
426{
427 /* request header */
428 VMMDevHGCMRequestHeader header;
429
430 /** IN: Client identifier. */
431 uint32_t u32ClientID;
432} VMMDevHGCMDisconnect;
433
434typedef enum
435{
436 VMMDevHGCMParmType_Invalid = 0,
437 VMMDevHGCMParmType_32bit = 1,
438 VMMDevHGCMParmType_64bit = 2,
439 VMMDevHGCMParmType_PhysAddr = 3,
440 VMMDevHGCMParmType_LinAddr = 4, /**< In and Out */
441 VMMDevHGCMParmType_LinAddr_In = 5, /**< In (read) */
442 VMMDevHGCMParmType_LinAddr_Out= 6, /**< Out (write) */
443 VMMDevHGCMParmType_SizeHack = 0x7fffffff
444} HGCMFunctionParameterType;
445
446typedef struct _HGCMFUNCTIONPARAMETER
447{
448 HGCMFunctionParameterType type;
449 union
450 {
451 uint32_t value32;
452 uint64_t value64;
453 struct
454 {
455 uint32_t size;
456
457 union
458 {
459 vmmDevHypPhys physAddr;
460 vmmDevHypPtr linearAddr;
461 } u;
462 } Pointer;
463 } u;
464} HGCMFunctionParameter;
465
466typedef struct
467{
468 /* request header */
469 VMMDevHGCMRequestHeader header;
470
471 /** IN: Client identifier. */
472 uint32_t u32ClientID;
473 /** IN: Service function number. */
474 uint32_t u32Function;
475 /** IN: Number of parameters. */
476 uint32_t cParms;
477 /** Parameters follow in form: HGCMFunctionParameter aParms[X]; */
478} VMMDevHGCMCall;
479#pragma pack()
480
481#define VMMDEV_HGCM_CALL_PARMS(a) ((HGCMFunctionParameter *)((char *)a + sizeof (VMMDevHGCMCall)))
482
483#define VBOX_HGCM_MAX_PARMS 256
484
485#endif /* VBOX_HGCM */
486
487
488#define VBVA_F_STATUS_ACCEPTED (0x01)
489#define VBVA_F_STATUS_ENABLED (0x02)
490
491#pragma pack(4)
492
493typedef struct _VMMDevVideoAccelEnable
494{
495 /* request header */
496 VMMDevRequestHeader header;
497
498 /** 0 - disable, !0 - enable. */
499 uint32_t u32Enable;
500
501 /** The size of VBVAMEMORY::au8RingBuffer expected by driver.
502 * The host will refuse to enable VBVA if the size is not equal to
503 * VBVA_RING_BUFFER_SIZE.
504 */
505 uint32_t cbRingBuffer;
506
507 /** Guest initializes the status to 0. Host sets appropriate VBVA_F_STATUS_ flags. */
508 uint32_t fu32Status;
509
510} VMMDevVideoAccelEnable;
511
512typedef struct _VMMDevVideoAccelFlush
513{
514 /* request header */
515 VMMDevRequestHeader header;
516
517} VMMDevVideoAccelFlush;
518
519#pragma pack()
520
521#pragma pack(1)
522
523/** VBVA command header. */
524typedef struct _VBVACMDHDR
525{
526 /** Coordinates of affected rectangle. */
527 int16_t x;
528 int16_t y;
529 uint16_t w;
530 uint16_t h;
531} VBVACMDHDR;
532
533/* VBVA order codes. Must be >= 0, because the VRDP server internally
534 * uses negative values to mark some operations.
535 * Values are important since they are used as an index in the
536 * "supported orders" bit mask.
537 */
538#define VBVA_VRDP_DIRTY_RECT (0)
539#define VBVA_VRDP_SOLIDRECT (1)
540#define VBVA_VRDP_SOLIDBLT (2)
541#define VBVA_VRDP_DSTBLT (3)
542#define VBVA_VRDP_SCREENBLT (4)
543#define VBVA_VRDP_PATBLT_BRUSH (5)
544#define VBVA_VRDP_MEMBLT (6)
545#define VBVA_VRDP_CACHED_BITMAP (7)
546#define VBVA_VRDP_DELETED_BITMAP (8)
547#define VBVA_VRDP_LINE (9)
548#define VBVA_VRDP_BOUNDS (10)
549#define VBVA_VRDP_REPEAT (11)
550#define VBVA_VRDP_POLYLINE (12)
551#define VBVA_VRDP_ELLIPSE (13)
552#define VBVA_VRDP_SAVESCREEN (14)
553
554#define VBVA_VRDP_INDEX_TO_BIT(__index) (1 << (__index))
555
556/* 128 bit bitmap hash. */
557typedef uint8_t VRDPBITMAPHASH[16];
558
559typedef struct _VRDPORDERPOINT
560{
561 int16_t x;
562 int16_t y;
563} VRDPORDERPOINT;
564
565typedef struct _VRDPORDERPOLYPOINTS
566{
567 uint8_t c;
568 VRDPORDERPOINT a[16];
569} VRDPORDERPOLYPOINTS;
570
571typedef struct _VRDPORDERAREA
572{
573 int16_t x;
574 int16_t y;
575 uint16_t w;
576 uint16_t h;
577} VRDPORDERAREA;
578
579typedef struct _VRDPORDERBOUNDS
580{
581 VRDPORDERPOINT pt1;
582 VRDPORDERPOINT pt2;
583} VRDPORDERBOUNDS;
584
585typedef struct _VRDPORDERREPEAT
586{
587 VRDPORDERBOUNDS bounds;
588} VRDPORDERREPEAT;
589
590
591/* Header for bitmap bits in VBVA VRDP operations. */
592typedef struct _VRDPDATABITS
593{
594 /* Size of bitmap data without the header. */
595 uint32_t cb;
596 int16_t x;
597 int16_t y;
598 uint16_t cWidth;
599 uint16_t cHeight;
600 uint8_t cbPixel;
601} VRDPDATABITS;
602
603typedef struct _VRDPORDERSOLIDRECT
604{
605 int16_t x;
606 int16_t y;
607 uint16_t w;
608 uint16_t h;
609 uint32_t rgb;
610} VRDPORDERSOLIDRECT;
611
612typedef struct _VRDPORDERSOLIDBLT
613{
614 int16_t x;
615 int16_t y;
616 uint16_t w;
617 uint16_t h;
618 uint32_t rgb;
619 uint8_t rop;
620} VRDPORDERSOLIDBLT;
621
622typedef struct _VRDPORDERDSTBLT
623{
624 int16_t x;
625 int16_t y;
626 uint16_t w;
627 uint16_t h;
628 uint8_t rop;
629} VRDPORDERDSTBLT;
630
631typedef struct _VRDPORDERSCREENBLT
632{
633 int16_t x;
634 int16_t y;
635 uint16_t w;
636 uint16_t h;
637 int16_t xSrc;
638 int16_t ySrc;
639 uint8_t rop;
640} VRDPORDERSCREENBLT;
641
642typedef struct _VRDPORDERPATBLTBRUSH
643{
644 int16_t x;
645 int16_t y;
646 uint16_t w;
647 uint16_t h;
648 int8_t xSrc;
649 int8_t ySrc;
650 uint32_t rgbFG;
651 uint32_t rgbBG;
652 uint8_t rop;
653 uint8_t pattern[8];
654} VRDPORDERPATBLTBRUSH;
655
656typedef struct _VRDPORDERMEMBLT
657{
658 int16_t x;
659 int16_t y;
660 uint16_t w;
661 uint16_t h;
662 int16_t xSrc;
663 int16_t ySrc;
664 uint8_t rop;
665 VRDPBITMAPHASH hash;
666} VRDPORDERMEMBLT;
667
668typedef struct _VRDPORDERCACHEDBITMAP
669{
670 VRDPBITMAPHASH hash;
671 /* VRDPDATABITS and the bitmap data follows. */
672} VRDPORDERCACHEDBITMAP;
673
674typedef struct _VRDPORDERDELETEDBITMAP
675{
676 VRDPBITMAPHASH hash;
677} VRDPORDERDELETEDBITMAP;
678
679typedef struct _VRDPORDERLINE
680{
681 int16_t x1;
682 int16_t y1;
683 int16_t x2;
684 int16_t y2;
685 int16_t xBounds1;
686 int16_t yBounds1;
687 int16_t xBounds2;
688 int16_t yBounds2;
689 uint8_t mix;
690 uint32_t rgb;
691} VRDPORDERLINE;
692
693typedef struct _VRDPORDERPOLYLINE
694{
695 VRDPORDERPOINT ptStart;
696 uint8_t mix;
697 uint32_t rgb;
698 VRDPORDERPOLYPOINTS points;
699} VRDPORDERPOLYLINE;
700
701typedef struct _VRDPORDERELLIPSE
702{
703 VRDPORDERPOINT pt1;
704 VRDPORDERPOINT pt2;
705 uint8_t mix;
706 uint8_t fillMode;
707 uint32_t rgb;
708} VRDPORDERELLIPSE;
709
710typedef struct _VRDPORDERSAVESCREEN
711{
712 VRDPORDERPOINT pt1;
713 VRDPORDERPOINT pt2;
714 uint8_t ident;
715 uint8_t restore;
716} VRDPORDERSAVESCREEN;
717#pragma pack()
718
719/* The VBVA ring buffer is suitable for transferring large (< 2gb) amount of data.
720 * For example big bitmaps which do not fit to the buffer.
721 *
722 * Guest starts writing to the buffer by initializing a record entry in the
723 * aRecords queue. VBVA_F_RECORD_PARTIAL indicates that the record is being
724 * written. As data is written to the ring buffer, the guest increases off32End
725 * for the record.
726 *
727 * The host reads the aRecords on flushes and processes all completed records.
728 * When host encounters situation when only a partial record presents and
729 * cbRecord & ~VBVA_F_RECORD_PARTIAL >= VBVA_RING_BUFFER_SIZE - VBVA_RING_BUFFER_THRESHOLD,
730 * the host fetched all record data and updates off32Head. After that on each flush
731 * the host continues fetching the data until the record is completed.
732 *
733 */
734
735#define VBVA_RING_BUFFER_SIZE (_4M - _1K)
736#define VBVA_RING_BUFFER_THRESHOLD (4 * _1K)
737
738#define VBVA_MAX_RECORDS (64)
739
740#define VBVA_F_MODE_ENABLED (0x00000001)
741#define VBVA_F_MODE_VRDP (0x00000002)
742#define VBVA_F_MODE_VRDP_RESET (0x00000004)
743#define VBVA_F_MODE_VRDP_ORDER_MASK (0x00000008)
744
745#define VBVA_F_RECORD_PARTIAL (0x80000000)
746
747#pragma pack(1)
748typedef struct _VBVARECORD
749{
750 /** The length of the record. Changed by guest. */
751 uint32_t cbRecord;
752} VBVARECORD;
753
754typedef struct _VBVAMEMORY
755{
756 /** VBVA_F_MODE_* */
757 uint32_t fu32ModeFlags;
758
759 /** The offset where the data start in the buffer. */
760 uint32_t off32Data;
761 /** The offset where next data must be placed in the buffer. */
762 uint32_t off32Free;
763
764 /** The ring buffer for data. */
765 uint8_t au8RingBuffer[VBVA_RING_BUFFER_SIZE];
766
767 /** The queue of record descriptions. */
768 VBVARECORD aRecords[VBVA_MAX_RECORDS];
769 uint32_t indexRecordFirst;
770 uint32_t indexRecordFree;
771
772 /* RDP orders supported by the client. The guest reports only them
773 * and falls back to DIRTY rects for not supported ones.
774 *
775 * (1 << VBVA_VRDP_*)
776 */
777 uint32_t fu32SupportedOrders;
778
779} VBVAMEMORY;
780#pragma pack()
781
782/** @} */
783
784
785/**
786 * VMMDev RAM
787 * @{
788 */
789
790#pragma pack(1)
791/** Layout of VMMDEV RAM region that contains information for guest */
792typedef struct
793{
794 /** size */
795 uint32_t u32Size;
796 /** version */
797 uint32_t u32Version;
798
799 union {
800 /** Flag telling that VMMDev set the IRQ and acknowlegment is required */
801 struct {
802 bool fHaveEvents;
803 } V1_04;
804
805 struct {
806 /** Pending events flags, set by host. */
807 uint32_t u32HostEvents;
808 /** Mask of events the guest wants to see, set by guest. */
809 uint32_t u32GuestEventMask;
810 } V1_03;
811 } V;
812
813 VBVAMEMORY vbvaMemory;
814
815} VMMDevMemory;
816#pragma pack()
817
818/** Version of VMMDevMemory structure. */
819#define VMMDEV_MEMORY_VERSION (1)
820
821/** @} */
822
823
824/**
825 * VMMDev events.
826 * @{
827 */
828
829/** Host mouse capabilities has been changed. */
830#define VMMDEV_EVENT_MOUSE_CAPABILITIES_CHANGED BIT(0)
831/** HGCM event. */
832#define VMMDEV_EVENT_HGCM BIT(1)
833/** A display change request has been issued. */
834#define VMMDEV_EVENT_DISPLAY_CHANGE_REQUEST BIT(2)
835/** Credentials are available for judgement. */
836#define VMMDEV_EVENT_JUDGE_CREDENTIALS BIT(3)
837/** The guest has been restored. */
838#define VMMDEV_EVENT_RESTORED BIT(4)
839
840/** @} */
841
842
843/**
844 * VBoxGuest IOCTL codes and structures.
845 * @{
846 * IOCTL function numbers start from 2048, because MSDN says the
847 * second parameter of CTL_CODE macro (function) must be <= 2048 and <= 4095 for IHVs.
848 * The IOCTL number algorithm corresponds to CTL_CODE on Windows but for Linux IOCTLs,
849 * we also encode the data size, so we need an additional parameter.
850 */
851#if defined(__WIN__)
852#define IOCTL_CODE(DeviceType, Function, Method, Access, DataSize_ignored) \
853 ( ((DeviceType) << 16) | ((Access) << 14) | ((Function) << 2) | (Method))
854#else /* unix: */
855#define IOCTL_CODE(DeviceType, Function, Method_ignored, Access_ignored, DataSize) \
856 ( (3 << 30) | ((DeviceType) << 8) | (Function) | ((DataSize) << 16) )
857#define METHOD_BUFFERED 0
858#define FILE_WRITE_ACCESS 0x0002
859#define FILE_DEVICE_UNKNOWN 0x00000022
860#endif
861
862/** IOCTL to VBoxGuest to query the VMMDev IO port region start. */
863#define IOCTL_VBOXGUEST_GETVMMDEVPORT IOCTL_CODE(FILE_DEVICE_UNKNOWN, 2048, METHOD_BUFFERED, FILE_WRITE_ACCESS, sizeof(VBoxGuestPortInfo))
864
865#pragma pack(4)
866typedef struct _VBoxGuestPortInfo
867{
868 uint32_t portAddress;
869 VMMDevMemory *pVMMDevMemory;
870} VBoxGuestPortInfo;
871
872/** IOCTL to VBoxGuest to wait for a VMMDev host notification */
873#define IOCTL_VBOXGUEST_WAITEVENT IOCTL_CODE(FILE_DEVICE_UNKNOWN, 2049, METHOD_BUFFERED, FILE_WRITE_ACCESS, sizeof(VBoxGuestWaitEventInfo))
874
875/**
876 * Result codes for VBoxGuestWaitEventInfo::u32Result
877 * @{
878 */
879/** Successful completion, an event occured. */
880#define VBOXGUEST_WAITEVENT_OK (0)
881/** Successful completion, timed out. */
882#define VBOXGUEST_WAITEVENT_TIMEOUT (1)
883/** Wait was interrupted. */
884#define VBOXGUEST_WAITEVENT_INTERRUPTED (2)
885/** An error occured while processing the request. */
886#define VBOXGUEST_WAITEVENT_ERROR (3)
887/** @} */
888
889/** Input and output buffers layout of the IOCTL_VBOXGUEST_WAITEVENT */
890typedef struct _VBoxGuestWaitEventInfo
891{
892 /** timeout in milliseconds */
893 uint32_t u32TimeoutIn;
894 /** events to wait for */
895 uint32_t u32EventMaskIn;
896 /** result code */
897 uint32_t u32Result;
898 /** events occured */
899 uint32_t u32EventFlagsOut;
900} VBoxGuestWaitEventInfo;
901
902/** IOCTL to VBoxGuest to perform a VMM request */
903#define IOCTL_VBOXGUEST_VMMREQUEST IOCTL_CODE(FILE_DEVICE_UNKNOWN, 2050, METHOD_BUFFERED, FILE_WRITE_ACCESS, sizeof(VMMDevRequestHeader))
904
905/** IOCTL to VBoxGuest to control event filter mask */
906
907typedef struct _VBoxGuestFilterMaskInfo
908{
909 uint32_t u32OrMask;
910 uint32_t u32NotMask;
911} VBoxGuestFilterMaskInfo;
912#pragma pack()
913
914#define IOCTL_VBOXGUEST_CTL_FILTER_MASK IOCTL_CODE(FILE_DEVICE_UNKNOWN, 2051, METHOD_BUFFERED, FILE_WRITE_ACCESS, sizeof (VBoxGuestFilterMaskInfo))
915
916#ifdef VBOX_HGCM
917/* These structures are shared between the driver and other binaries,
918 * therefore packing must be defined explicitely.
919 */
920#pragma pack(1)
921typedef struct _VBoxGuestHGCMConnectInfo
922{
923 uint32_t result; /**< OUT */
924 HGCMServiceLocation Loc; /**< IN */
925 uint32_t u32ClientID; /**< OUT */
926} VBoxGuestHGCMConnectInfo;
927
928typedef struct _VBoxGuestHGCMDisconnectInfo
929{
930 uint32_t result; /**< OUT */
931 uint32_t u32ClientID; /**< IN */
932} VBoxGuestHGCMDisconnectInfo;
933
934typedef struct _VBoxGuestHGCMCallInfo
935{
936 uint32_t result; /**< OUT Host HGCM return code.*/
937 uint32_t u32ClientID; /**< IN The id of the caller. */
938 uint32_t u32Function; /**< IN Function number. */
939 uint32_t cParms; /**< IN How many parms. */
940 /* Parameters follow in form HGCMFunctionParameter aParms[cParms] */
941} VBoxGuestHGCMCallInfo;
942#pragma pack()
943
944#define IOCTL_VBOXGUEST_HGCM_CONNECT IOCTL_CODE(FILE_DEVICE_UNKNOWN, 3072, METHOD_BUFFERED, FILE_WRITE_ACCESS, sizeof(VBoxGuestHGCMConnectInfo))
945#define IOCTL_VBOXGUEST_HGCM_DISCONNECT IOCTL_CODE(FILE_DEVICE_UNKNOWN, 3073, METHOD_BUFFERED, FILE_WRITE_ACCESS, sizeof(VBoxGuestHGCMDisconnectInfo))
946#define IOCTL_VBOXGUEST_HGCM_CALL IOCTL_CODE(FILE_DEVICE_UNKNOWN, 3074, METHOD_BUFFERED, FILE_WRITE_ACCESS, sizeof(VBoxGuestHGCMCallInfo))
947
948#define VBOXGUEST_HGCM_CALL_PARMS(a) ((HGCMFunctionParameter *)((uint8_t *)(a) + sizeof (VBoxGuestHGCMCallInfo)))
949
950#endif /* VBOX_HGCM */
951
952/*
953 * Credentials request flags and structure
954 */
955
956#define VMMDEV_CREDENTIALS_STRLEN 128
957
958/** query from host whether credentials are present */
959#define VMMDEV_CREDENTIALS_QUERYPRESENCE BIT(1)
960/** read credentials from host (can be combined with clear) */
961#define VMMDEV_CREDENTIALS_READ BIT(2)
962/** clear credentials on host (can be combined with read) */
963#define VMMDEV_CREDENTIALS_CLEAR BIT(3)
964/** read credentials for judgement in the guest */
965#define VMMDEV_CREDENTIALS_READJUDGE BIT(8)
966/** clear credentials for judegement on the host */
967#define VMMDEV_CREDENTIALS_CLEARJUDGE BIT(9)
968/** report credentials acceptance by guest */
969#define VMMDEV_CREDENTIALS_JUDGE_OK BIT(10)
970/** report credentials denial by guest */
971#define VMMDEV_CREDENTIALS_JUDGE_DENY BIT(11)
972/** report that no judgement could be made by guest */
973#define VMMDEV_CREDENTIALS_JUDGE_NOJUDGEMENT BIT(12)
974
975/** flag telling the guest that credentials are present */
976#define VMMDEV_CREDENTIALS_PRESENT BIT(16)
977/** flag telling guest that local logons should be prohibited */
978#define VMMDEV_CREDENTIALS_NOLOCALLOGON BIT(17)
979
980/** credentials request structure */
981#pragma pack(4)
982typedef struct _VMMDevCredentials
983{
984 /* request header */
985 VMMDevRequestHeader header;
986 /* request flags (in/out) */
987 uint32_t u32Flags;
988 /* user name (UTF-8) (out) */
989 char szUserName[VMMDEV_CREDENTIALS_STRLEN];
990 /* password (UTF-8) (out) */
991 char szPassword[VMMDEV_CREDENTIALS_STRLEN];
992 /* domain name (UTF-8) (out) */
993 char szDomain[VMMDEV_CREDENTIALS_STRLEN];
994} VMMDevCredentials;
995#pragma pack()
996
997/** inline helper to determine the request size for the given operation */
998DECLINLINE(size_t) vmmdevGetRequestSize(VMMDevRequestType requestType)
999{
1000 switch (requestType)
1001 {
1002 case VMMDevReq_GetMouseStatus:
1003 case VMMDevReq_SetMouseStatus:
1004 return sizeof(VMMDevReqMouseStatus);
1005 case VMMDevReq_SetPointerShape:
1006 return sizeof(VMMDevReqMousePointer);
1007 case VMMDevReq_GetHostVersion:
1008 return sizeof(VMMDevReqHostVersion);
1009 case VMMDevReq_Idle:
1010 return sizeof(VMMDevReqIdle);
1011 case VMMDevReq_GetHostTime:
1012 return sizeof(VMMDevReqHostTime);
1013 case VMMDevReq_GetHypervisorInfo:
1014 case VMMDevReq_SetHypervisorInfo:
1015 return sizeof(VMMDevReqHypervisorInfo);
1016 case VMMDevReq_SetPowerStatus:
1017 return sizeof(VMMDevPowerStateRequest);
1018 case VMMDevReq_AcknowledgeEvents:
1019 return sizeof(VMMDevEvents);
1020 case VMMDevReq_ReportGuestInfo:
1021 return sizeof(VMMDevReportGuestInfo);
1022 case VMMDevReq_GetDisplayChangeRequest:
1023 return sizeof(VMMDevDisplayChangeRequest);
1024 case VMMDevReq_VideoModeSupported:
1025 return sizeof(VMMDevVideoModeSupportedRequest);
1026 case VMMDevReq_GetHeightReduction:
1027 return sizeof(VMMDevGetHeightReductionRequest);
1028#ifdef VBOX_HGCM
1029 case VMMDevReq_HGCMConnect:
1030 return sizeof(VMMDevHGCMConnect);
1031 case VMMDevReq_HGCMDisconnect:
1032 return sizeof(VMMDevHGCMDisconnect);
1033 case VMMDevReq_HGCMCall:
1034 return sizeof(VMMDevHGCMCall);
1035#endif
1036 case VMMDevReq_VideoAccelEnable:
1037 return sizeof(VMMDevVideoAccelEnable);
1038 case VMMDevReq_VideoAccelFlush:
1039 return sizeof(VMMDevVideoAccelFlush);
1040 case VMMDevReq_QueryCredentials:
1041 return sizeof(VMMDevCredentials);
1042 default:
1043 return 0;
1044 }
1045}
1046
1047/**
1048 * Initializes a request structure.
1049 *
1050 */
1051DECLINLINE(int) vmmdevInitRequest(VMMDevRequestHeader *req, VMMDevRequestType type)
1052{
1053 uint32_t requestSize;
1054 if (!req)
1055 return VERR_INVALID_PARAMETER;
1056 requestSize = (uint32_t)vmmdevGetRequestSize(type);
1057 if (!requestSize)
1058 return VERR_INVALID_PARAMETER;
1059 req->size = requestSize;
1060 req->version = VMMDEV_REQUEST_HEADER_VERSION;
1061 req->requestType = type;
1062 req->rc = VERR_GENERAL_FAILURE;
1063 req->reserved1 = 0;
1064 req->reserved2 = 0;
1065 return VINF_SUCCESS;
1066}
1067
1068/** @} */
1069
1070#endif /* __VBox_VBoxGuest_h__ */
Note: See TracBrowser for help on using the repository browser.

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