1/* SPDX-License-Identifier: (GPL-2.0 OR CDDL-1.0) */
2/*
3 * Virtual Device for Guest <-> VMM/Host communication interface
4 *
5 * Copyright (C) 2006-2016 Oracle Corporation
6 */
7
8#ifndef __VBOX_VMMDEV_H__
9#define __VBOX_VMMDEV_H__
10
11#include <asm/bitsperlong.h>
12#include <linux/sizes.h>
13#include <linux/types.h>
14#include <linux/vbox_vmmdev_types.h>
15
16/* Port for generic request interface (relative offset). */
17#define VMMDEV_PORT_OFF_REQUEST 0
18
19/** Layout of VMMDEV RAM region that contains information for guest. */
20struct vmmdev_memory {
21 /** The size of this structure. */
22 u32 size;
23 /** The structure version. (VMMDEV_MEMORY_VERSION) */
24 u32 version;
25
26 union {
27 struct {
28 /** Flag telling that VMMDev has events pending. */
29 u8 have_events;
30 /** Explicit padding, MBZ. */
31 u8 padding[3];
32 } V1_04;
33
34 struct {
35 /** Pending events flags, set by host. */
36 u32 host_events;
37 /** Mask of events the guest wants, set by guest. */
38 u32 guest_event_mask;
39 } V1_03;
40 } V;
41
42 /* struct vbva_memory, not used */
43};
44VMMDEV_ASSERT_SIZE(vmmdev_memory, 8 + 8);
45
46/** Version of vmmdev_memory structure (vmmdev_memory::version). */
47#define VMMDEV_MEMORY_VERSION (1)
48
49/* Host mouse capabilities has been changed. */
50#define VMMDEV_EVENT_MOUSE_CAPABILITIES_CHANGED BIT(0)
51/* HGCM event. */
52#define VMMDEV_EVENT_HGCM BIT(1)
53/* A display change request has been issued. */
54#define VMMDEV_EVENT_DISPLAY_CHANGE_REQUEST BIT(2)
55/* Credentials are available for judgement. */
56#define VMMDEV_EVENT_JUDGE_CREDENTIALS BIT(3)
57/* The guest has been restored. */
58#define VMMDEV_EVENT_RESTORED BIT(4)
59/* Seamless mode state changed. */
60#define VMMDEV_EVENT_SEAMLESS_MODE_CHANGE_REQUEST BIT(5)
61/* Memory balloon size changed. */
62#define VMMDEV_EVENT_BALLOON_CHANGE_REQUEST BIT(6)
63/* Statistics interval changed. */
64#define VMMDEV_EVENT_STATISTICS_INTERVAL_CHANGE_REQUEST BIT(7)
65/* VRDP status changed. */
66#define VMMDEV_EVENT_VRDP BIT(8)
67/* New mouse position data available. */
68#define VMMDEV_EVENT_MOUSE_POSITION_CHANGED BIT(9)
69/* CPU hotplug event occurred. */
70#define VMMDEV_EVENT_CPU_HOTPLUG BIT(10)
71/* The mask of valid events, for sanity checking. */
72#define VMMDEV_EVENT_VALID_EVENT_MASK 0x000007ffU
73
74/*
75 * Additions are allowed to work only if additions_major == vmmdev_current &&
76 * additions_minor <= vmmdev_current. Additions version is reported to host
77 * (VMMDev) by VMMDEVREQ_REPORT_GUEST_INFO.
78 */
79#define VMMDEV_VERSION 0x00010004
80#define VMMDEV_VERSION_MAJOR (VMMDEV_VERSION >> 16)
81#define VMMDEV_VERSION_MINOR (VMMDEV_VERSION & 0xffff)
82
83/* Maximum request packet size. */
84#define VMMDEV_MAX_VMMDEVREQ_SIZE 1048576
85
86/* Version of vmmdev_request_header structure. */
87#define VMMDEV_REQUEST_HEADER_VERSION 0x10001
88
89/** struct vmmdev_request_header - Generic VMMDev request header. */
90struct vmmdev_request_header {
91 /** IN: Size of the structure in bytes (including body). */
92 u32 size;
93 /** IN: Version of the structure. */
94 u32 version;
95 /** IN: Type of the request. */
96 enum vmmdev_request_type request_type;
97 /** OUT: Return code. */
98 s32 rc;
99 /** Reserved field no.1. MBZ. */
100 u32 reserved1;
101 /** IN: Requestor information (VMMDEV_REQUESTOR_*) */
102 u32 requestor;
103};
104VMMDEV_ASSERT_SIZE(vmmdev_request_header, 24);
105
106/**
107 * struct vmmdev_mouse_status - Mouse status request structure.
108 *
109 * Used by VMMDEVREQ_GET_MOUSE_STATUS and VMMDEVREQ_SET_MOUSE_STATUS.
110 */
111struct vmmdev_mouse_status {
112 /** header */
113 struct vmmdev_request_header header;
114 /** Mouse feature mask. See VMMDEV_MOUSE_*. */
115 u32 mouse_features;
116 /** Mouse x position. */
117 s32 pointer_pos_x;
118 /** Mouse y position. */
119 s32 pointer_pos_y;
120};
121VMMDEV_ASSERT_SIZE(vmmdev_mouse_status, 24 + 12);
122
123/* The guest can (== wants to) handle absolute coordinates. */
124#define VMMDEV_MOUSE_GUEST_CAN_ABSOLUTE BIT(0)
125/*
126 * The host can (== wants to) send absolute coordinates.
127 * (Input not captured.)
128 */
129#define VMMDEV_MOUSE_HOST_WANTS_ABSOLUTE BIT(1)
130/*
131 * The guest can *NOT* switch to software cursor and therefore depends on the
132 * host cursor.
133 *
134 * When guest additions are installed and the host has promised to display the
135 * cursor itself, the guest installs a hardware mouse driver. Don't ask the
136 * guest to switch to a software cursor then.
137 */
138#define VMMDEV_MOUSE_GUEST_NEEDS_HOST_CURSOR BIT(2)
139/* The host does NOT provide support for drawing the cursor itself. */
140#define VMMDEV_MOUSE_HOST_CANNOT_HWPOINTER BIT(3)
141/* The guest can read VMMDev events to find out about pointer movement */
142#define VMMDEV_MOUSE_NEW_PROTOCOL BIT(4)
143/*
144 * If the guest changes the status of the VMMDEV_MOUSE_GUEST_NEEDS_HOST_CURSOR
145 * bit, the host will honour this.
146 */
147#define VMMDEV_MOUSE_HOST_RECHECKS_NEEDS_HOST_CURSOR BIT(5)
148/*
149 * The host supplies an absolute pointing device. The Guest Additions may
150 * wish to use this to decide whether to install their own driver.
151 */
152#define VMMDEV_MOUSE_HOST_HAS_ABS_DEV BIT(6)
153
154/* The minimum value our pointing device can return. */
155#define VMMDEV_MOUSE_RANGE_MIN 0
156/* The maximum value our pointing device can return. */
157#define VMMDEV_MOUSE_RANGE_MAX 0xFFFF
158
159/**
160 * struct vmmdev_host_version - VirtualBox host version request structure.
161 *
162 * VBG uses this to detect the precense of new features in the interface.
163 */
164struct vmmdev_host_version {
165 /** Header. */
166 struct vmmdev_request_header header;
167 /** Major version. */
168 u16 major;
169 /** Minor version. */
170 u16 minor;
171 /** Build number. */
172 u32 build;
173 /** SVN revision. */
174 u32 revision;
175 /** Feature mask. */
176 u32 features;
177};
178VMMDEV_ASSERT_SIZE(vmmdev_host_version, 24 + 16);
179
180/* Physical page lists are supported by HGCM. */
181#define VMMDEV_HVF_HGCM_PHYS_PAGE_LIST BIT(0)
182
183/**
184 * struct vmmdev_mask - Structure to set / clear bits in a mask used for
185 * VMMDEVREQ_SET_GUEST_CAPABILITIES and VMMDEVREQ_CTL_GUEST_FILTER_MASK.
186 */
187struct vmmdev_mask {
188 /** Header. */
189 struct vmmdev_request_header header;
190 /** Mask of bits to be set. */
191 u32 or_mask;
192 /** Mask of bits to be cleared. */
193 u32 not_mask;
194};
195VMMDEV_ASSERT_SIZE(vmmdev_mask, 24 + 8);
196
197/* The guest supports seamless display rendering. */
198#define VMMDEV_GUEST_SUPPORTS_SEAMLESS BIT(0)
199/* The guest supports mapping guest to host windows. */
200#define VMMDEV_GUEST_SUPPORTS_GUEST_HOST_WINDOW_MAPPING BIT(1)
201/*
202 * The guest graphical additions are active.
203 * Used for fast activation and deactivation of certain graphical operations
204 * (e.g. resizing & seamless). The legacy VMMDEVREQ_REPORT_GUEST_CAPABILITIES
205 * request sets this automatically, but VMMDEVREQ_SET_GUEST_CAPABILITIES does
206 * not.
207 */
208#define VMMDEV_GUEST_SUPPORTS_GRAPHICS BIT(2)
209/* The mask of valid capabilities, for sanity checking. */
210#define VMMDEV_GUEST_CAPABILITIES_MASK 0x00000007U
211
212/** struct vmmdev_hypervisorinfo - Hypervisor info structure. */
213struct vmmdev_hypervisorinfo {
214 /** Header. */
215 struct vmmdev_request_header header;
216 /**
217 * Guest virtual address of proposed hypervisor start.
218 * Not used by VMMDEVREQ_GET_HYPERVISOR_INFO.
219 */
220 u32 hypervisor_start;
221 /** Hypervisor size in bytes. */
222 u32 hypervisor_size;
223};
224VMMDEV_ASSERT_SIZE(vmmdev_hypervisorinfo, 24 + 8);
225
226/** struct vmmdev_events - Pending events structure. */
227struct vmmdev_events {
228 /** Header. */
229 struct vmmdev_request_header header;
230 /** OUT: Pending event mask. */
231 u32 events;
232};
233VMMDEV_ASSERT_SIZE(vmmdev_events, 24 + 4);
234
235#define VMMDEV_OSTYPE_LINUX26 0x53000
236#define VMMDEV_OSTYPE_X64 BIT(8)
237
238/** struct vmmdev_guestinfo - Guest information report. */
239struct vmmdev_guest_info {
240 /** Header. */
241 struct vmmdev_request_header header;
242 /**
243 * The VMMDev interface version expected by additions.
244 * *Deprecated*, do not use anymore! Will be removed.
245 */
246 u32 interface_version;
247 /** Guest OS type. */
248 u32 os_type;
249};
250VMMDEV_ASSERT_SIZE(vmmdev_guest_info, 24 + 8);
251
252#define VMMDEV_GUEST_INFO2_ADDITIONS_FEATURES_REQUESTOR_INFO BIT(0)
253
254/** struct vmmdev_guestinfo2 - Guest information report, version 2. */
255struct vmmdev_guest_info2 {
256 /** Header. */
257 struct vmmdev_request_header header;
258 /** Major version. */
259 u16 additions_major;
260 /** Minor version. */
261 u16 additions_minor;
262 /** Build number. */
263 u32 additions_build;
264 /** SVN revision. */
265 u32 additions_revision;
266 /** Feature mask. */
267 u32 additions_features;
268 /**
269 * The intentional meaning of this field was:
270 * Some additional information, for example 'Beta 1' or something like
271 * that.
272 *
273 * The way it was implemented was implemented: VBG_VERSION_STRING.
274 *
275 * This means the first three members are duplicated in this field (if
276 * the guest build config is sane). So, the user must check this and
277 * chop it off before usage. There is, because of the Main code's blind
278 * trust in the field's content, no way back.
279 */
280 char name[128];
281};
282VMMDEV_ASSERT_SIZE(vmmdev_guest_info2, 24 + 144);
283
284enum vmmdev_guest_facility_type {
285 VBOXGUEST_FACILITY_TYPE_UNKNOWN = 0,
286 VBOXGUEST_FACILITY_TYPE_VBOXGUEST_DRIVER = 20,
287 /* VBoxGINA / VBoxCredProv / pam_vbox. */
288 VBOXGUEST_FACILITY_TYPE_AUTO_LOGON = 90,
289 VBOXGUEST_FACILITY_TYPE_VBOX_SERVICE = 100,
290 /* VBoxTray (Windows), VBoxClient (Linux, Unix). */
291 VBOXGUEST_FACILITY_TYPE_VBOX_TRAY_CLIENT = 101,
292 VBOXGUEST_FACILITY_TYPE_SEAMLESS = 1000,
293 VBOXGUEST_FACILITY_TYPE_GRAPHICS = 1100,
294 VBOXGUEST_FACILITY_TYPE_ALL = 0x7ffffffe,
295 /* Ensure the enum is a 32 bit data-type */
296 VBOXGUEST_FACILITY_TYPE_SIZEHACK = 0x7fffffff
297};
298
299enum vmmdev_guest_facility_status {
300 VBOXGUEST_FACILITY_STATUS_INACTIVE = 0,
301 VBOXGUEST_FACILITY_STATUS_PAUSED = 1,
302 VBOXGUEST_FACILITY_STATUS_PRE_INIT = 20,
303 VBOXGUEST_FACILITY_STATUS_INIT = 30,
304 VBOXGUEST_FACILITY_STATUS_ACTIVE = 50,
305 VBOXGUEST_FACILITY_STATUS_TERMINATING = 100,
306 VBOXGUEST_FACILITY_STATUS_TERMINATED = 101,
307 VBOXGUEST_FACILITY_STATUS_FAILED = 800,
308 VBOXGUEST_FACILITY_STATUS_UNKNOWN = 999,
309 /* Ensure the enum is a 32 bit data-type */
310 VBOXGUEST_FACILITY_STATUS_SIZEHACK = 0x7fffffff
311};
312
313/** struct vmmdev_guest_status - Guest Additions status structure. */
314struct vmmdev_guest_status {
315 /** Header. */
316 struct vmmdev_request_header header;
317 /** Facility the status is indicated for. */
318 enum vmmdev_guest_facility_type facility;
319 /** Current guest status. */
320 enum vmmdev_guest_facility_status status;
321 /** Flags, not used at the moment. */
322 u32 flags;
323};
324VMMDEV_ASSERT_SIZE(vmmdev_guest_status, 24 + 12);
325
326#define VMMDEV_MEMORY_BALLOON_CHUNK_SIZE (1048576)
327#define VMMDEV_MEMORY_BALLOON_CHUNK_PAGES (1048576 / 4096)
328
329/** struct vmmdev_memballoon_info - Memory-balloon info structure. */
330struct vmmdev_memballoon_info {
331 /** Header. */
332 struct vmmdev_request_header header;
333 /** Balloon size in megabytes. */
334 u32 balloon_chunks;
335 /** Guest ram size in megabytes. */
336 u32 phys_mem_chunks;
337 /**
338 * Setting this to VMMDEV_EVENT_BALLOON_CHANGE_REQUEST indicates that
339 * the request is a response to that event.
340 * (Don't confuse this with VMMDEVREQ_ACKNOWLEDGE_EVENTS.)
341 */
342 u32 event_ack;
343};
344VMMDEV_ASSERT_SIZE(vmmdev_memballoon_info, 24 + 12);
345
346/** struct vmmdev_memballoon_change - Change the size of the balloon. */
347struct vmmdev_memballoon_change {
348 /** Header. */
349 struct vmmdev_request_header header;
350 /** The number of pages in the array. */
351 u32 pages;
352 /** true = inflate, false = deflate. */
353 u32 inflate;
354 /** Physical address (u64) of each page. */
355 u64 phys_page[VMMDEV_MEMORY_BALLOON_CHUNK_PAGES];
356};
357
358/** struct vmmdev_write_core_dump - Write Core Dump request data. */
359struct vmmdev_write_core_dump {
360 /** Header. */
361 struct vmmdev_request_header header;
362 /** Flags (reserved, MBZ). */
363 u32 flags;
364};
365VMMDEV_ASSERT_SIZE(vmmdev_write_core_dump, 24 + 4);
366
367/** struct vmmdev_heartbeat - Heart beat check state structure. */
368struct vmmdev_heartbeat {
369 /** Header. */
370 struct vmmdev_request_header header;
371 /** OUT: Guest heartbeat interval in nanosec. */
372 u64 interval_ns;
373 /** Heartbeat check flag. */
374 u8 enabled;
375 /** Explicit padding, MBZ. */
376 u8 padding[3];
377} __packed;
378VMMDEV_ASSERT_SIZE(vmmdev_heartbeat, 24 + 12);
379
380#define VMMDEV_HGCM_REQ_DONE BIT(0)
381#define VMMDEV_HGCM_REQ_CANCELLED BIT(1)
382
383/** struct vmmdev_hgcmreq_header - vmmdev HGCM requests header. */
384struct vmmdev_hgcmreq_header {
385 /** Request header. */
386 struct vmmdev_request_header header;
387
388 /** HGCM flags. */
389 u32 flags;
390
391 /** Result code. */
392 s32 result;
393};
394VMMDEV_ASSERT_SIZE(vmmdev_hgcmreq_header, 24 + 8);
395
396/** struct vmmdev_hgcm_connect - HGCM connect request structure. */
397struct vmmdev_hgcm_connect {
398 /** HGCM request header. */
399 struct vmmdev_hgcmreq_header header;
400
401 /** IN: Description of service to connect to. */
402 struct vmmdev_hgcm_service_location loc;
403
404 /** OUT: Client identifier assigned by local instance of HGCM. */
405 u32 client_id;
406};
407VMMDEV_ASSERT_SIZE(vmmdev_hgcm_connect, 32 + 132 + 4);
408
409/** struct vmmdev_hgcm_disconnect - HGCM disconnect request structure. */
410struct vmmdev_hgcm_disconnect {
411 /** HGCM request header. */
412 struct vmmdev_hgcmreq_header header;
413
414 /** IN: Client identifier. */
415 u32 client_id;
416};
417VMMDEV_ASSERT_SIZE(vmmdev_hgcm_disconnect, 32 + 4);
418
419#define VMMDEV_HGCM_MAX_PARMS 32
420
421/** struct vmmdev_hgcm_call - HGCM call request structure. */
422struct vmmdev_hgcm_call {
423 /* request header */
424 struct vmmdev_hgcmreq_header header;
425
426 /** IN: Client identifier. */
427 u32 client_id;
428 /** IN: Service function number. */
429 u32 function;
430 /** IN: Number of parameters. */
431 u32 parm_count;
432 /** Parameters follow in form: HGCMFunctionParameter32|64 parms[X]; */
433};
434VMMDEV_ASSERT_SIZE(vmmdev_hgcm_call, 32 + 12);
435
436/**
437 * struct vmmdev_hgcm_cancel2 - HGCM cancel request structure, version 2.
438 *
439 * After the request header.rc will be:
440 *
441 * VINF_SUCCESS when cancelled.
442 * VERR_NOT_FOUND if the specified request cannot be found.
443 * VERR_INVALID_PARAMETER if the address is invalid valid.
444 */
445struct vmmdev_hgcm_cancel2 {
446 /** Header. */
447 struct vmmdev_request_header header;
448 /** The physical address of the request to cancel. */
449 u32 phys_req_to_cancel;
450};
451VMMDEV_ASSERT_SIZE(vmmdev_hgcm_cancel2, 24 + 4);
452
453#endif
454

source code of linux/drivers/virt/vboxguest/vmmdev.h