xref: /linux/include/uapi/linux/vboxguest.h (revision 4b4193256c8d3bc3a5397b5cd9494c2ad386317d)
1 /* SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR CDDL-1.0) */
2 /*
3  * VBoxGuest - VirtualBox Guest Additions Driver Interface.
4  *
5  * Copyright (C) 2006-2016 Oracle Corporation
6  */
7 
8 #ifndef __UAPI_VBOXGUEST_H__
9 #define __UAPI_VBOXGUEST_H__
10 
11 #include <asm/bitsperlong.h>
12 #include <linux/ioctl.h>
13 #include <linux/vbox_err.h>
14 #include <linux/vbox_vmmdev_types.h>
15 
16 /* Version of vbg_ioctl_hdr structure. */
17 #define VBG_IOCTL_HDR_VERSION		0x10001
18 /* Default request type.  Use this for non-VMMDev requests. */
19 #define VBG_IOCTL_HDR_TYPE_DEFAULT		0
20 
21 /**
22  * Common ioctl header.
23  *
24  * This is a mirror of vmmdev_request_header to prevent duplicating data and
25  * needing to verify things multiple times.
26  */
27 struct vbg_ioctl_hdr {
28 	/** IN: The request input size, and output size if size_out is zero. */
29 	__u32 size_in;
30 	/** IN: Structure version (VBG_IOCTL_HDR_VERSION) */
31 	__u32 version;
32 	/** IN: The VMMDev request type or VBG_IOCTL_HDR_TYPE_DEFAULT. */
33 	__u32 type;
34 	/**
35 	 * OUT: The VBox status code of the operation, out direction only.
36 	 * This is a VINF_ or VERR_ value as defined in vbox_err.h.
37 	 */
38 	__s32 rc;
39 	/** IN: Output size. Set to zero to use size_in as output size. */
40 	__u32 size_out;
41 	/** Reserved, MBZ. */
42 	__u32 reserved;
43 };
44 VMMDEV_ASSERT_SIZE(vbg_ioctl_hdr, 24);
45 
46 
47 /*
48  * The VBoxGuest I/O control version.
49  *
50  * As usual, the high word contains the major version and changes to it
51  * signifies incompatible changes.
52  *
53  * The lower word is the minor version number, it is increased when new
54  * functions are added or existing changed in a backwards compatible manner.
55  */
56 #define VBG_IOC_VERSION		0x00010000u
57 
58 /**
59  * VBG_IOCTL_DRIVER_VERSION_INFO data structure
60  *
61  * Note VBG_IOCTL_DRIVER_VERSION_INFO may switch the session to a backwards
62  * compatible interface version if uClientVersion indicates older client code.
63  */
64 struct vbg_ioctl_driver_version_info {
65 	/** The header. */
66 	struct vbg_ioctl_hdr hdr;
67 	union {
68 		struct {
69 			/** Requested interface version (VBG_IOC_VERSION). */
70 			__u32 req_version;
71 			/**
72 			 * Minimum interface version number (typically the
73 			 * major version part of VBG_IOC_VERSION).
74 			 */
75 			__u32 min_version;
76 			/** Reserved, MBZ. */
77 			__u32 reserved1;
78 			/** Reserved, MBZ. */
79 			__u32 reserved2;
80 		} in;
81 		struct {
82 			/** Version for this session (typ. VBG_IOC_VERSION). */
83 			__u32 session_version;
84 			/** Version of the IDC interface (VBG_IOC_VERSION). */
85 			__u32 driver_version;
86 			/** The SVN revision of the driver, or 0. */
87 			__u32 driver_revision;
88 			/** Reserved \#1 (zero until defined). */
89 			__u32 reserved1;
90 			/** Reserved \#2 (zero until defined). */
91 			__u32 reserved2;
92 		} out;
93 	} u;
94 };
95 VMMDEV_ASSERT_SIZE(vbg_ioctl_driver_version_info, 24 + 20);
96 
97 #define VBG_IOCTL_DRIVER_VERSION_INFO \
98 	_IOWR('V', 0, struct vbg_ioctl_driver_version_info)
99 
100 
101 /* IOCTL to perform a VMM Device request less than 1KB in size. */
102 #define VBG_IOCTL_VMMDEV_REQUEST(s)	_IOC(_IOC_READ | _IOC_WRITE, 'V', 2, s)
103 
104 
105 /* IOCTL to perform a VMM Device request larger then 1KB. */
106 #define VBG_IOCTL_VMMDEV_REQUEST_BIG	_IO('V', 3)
107 
108 
109 /** VBG_IOCTL_HGCM_CONNECT data structure. */
110 struct vbg_ioctl_hgcm_connect {
111 	struct vbg_ioctl_hdr hdr;
112 	union {
113 		struct {
114 			struct vmmdev_hgcm_service_location loc;
115 		} in;
116 		struct {
117 			__u32 client_id;
118 		} out;
119 	} u;
120 };
121 VMMDEV_ASSERT_SIZE(vbg_ioctl_hgcm_connect, 24 + 132);
122 
123 #define VBG_IOCTL_HGCM_CONNECT \
124 	_IOWR('V', 4, struct vbg_ioctl_hgcm_connect)
125 
126 
127 /** VBG_IOCTL_HGCM_DISCONNECT data structure. */
128 struct vbg_ioctl_hgcm_disconnect {
129 	struct vbg_ioctl_hdr hdr;
130 	union {
131 		struct {
132 			__u32 client_id;
133 		} in;
134 	} u;
135 };
136 VMMDEV_ASSERT_SIZE(vbg_ioctl_hgcm_disconnect, 24 + 4);
137 
138 #define VBG_IOCTL_HGCM_DISCONNECT \
139 	_IOWR('V', 5, struct vbg_ioctl_hgcm_disconnect)
140 
141 
142 /** VBG_IOCTL_HGCM_CALL data structure. */
143 struct vbg_ioctl_hgcm_call {
144 	/** The header. */
145 	struct vbg_ioctl_hdr hdr;
146 	/** Input: The id of the caller. */
147 	__u32 client_id;
148 	/** Input: Function number. */
149 	__u32 function;
150 	/**
151 	 * Input: How long to wait (milliseconds) for completion before
152 	 * cancelling the call. Set to -1 to wait indefinitely.
153 	 */
154 	__u32 timeout_ms;
155 	/** Interruptable flag, ignored for userspace calls. */
156 	__u8 interruptible;
157 	/** Explicit padding, MBZ. */
158 	__u8 reserved;
159 	/**
160 	 * Input: How many parameters following this structure.
161 	 *
162 	 * The parameters are either HGCMFunctionParameter64 or 32,
163 	 * depending on whether we're receiving a 64-bit or 32-bit request.
164 	 *
165 	 * The current maximum is 61 parameters (given a 1KB max request size,
166 	 * and a 64-bit parameter size of 16 bytes).
167 	 */
168 	__u16 parm_count;
169 	/*
170 	 * Parameters follow in form:
171 	 * struct hgcm_function_parameter<32|64> parms[parm_count]
172 	 */
173 };
174 VMMDEV_ASSERT_SIZE(vbg_ioctl_hgcm_call, 24 + 16);
175 
176 #define VBG_IOCTL_HGCM_CALL_32(s)	_IOC(_IOC_READ | _IOC_WRITE, 'V', 6, s)
177 #define VBG_IOCTL_HGCM_CALL_64(s)	_IOC(_IOC_READ | _IOC_WRITE, 'V', 7, s)
178 #if __BITS_PER_LONG == 64
179 #define VBG_IOCTL_HGCM_CALL(s)		VBG_IOCTL_HGCM_CALL_64(s)
180 #else
181 #define VBG_IOCTL_HGCM_CALL(s)		VBG_IOCTL_HGCM_CALL_32(s)
182 #endif
183 
184 
185 /** VBG_IOCTL_LOG data structure. */
186 struct vbg_ioctl_log {
187 	/** The header. */
188 	struct vbg_ioctl_hdr hdr;
189 	union {
190 		struct {
191 			/**
192 			 * The log message, this may be zero terminated. If it
193 			 * is not zero terminated then the length is determined
194 			 * from the input size.
195 			 */
196 			char msg[1];
197 		} in;
198 	} u;
199 };
200 
201 #define VBG_IOCTL_LOG(s)		_IO('V', 9)
202 
203 
204 /** VBG_IOCTL_WAIT_FOR_EVENTS data structure. */
205 struct vbg_ioctl_wait_for_events {
206 	/** The header. */
207 	struct vbg_ioctl_hdr hdr;
208 	union {
209 		struct {
210 			/** Timeout in milliseconds. */
211 			__u32 timeout_ms;
212 			/** Events to wait for. */
213 			__u32 events;
214 		} in;
215 		struct {
216 			/** Events that occurred. */
217 			__u32 events;
218 		} out;
219 	} u;
220 };
221 VMMDEV_ASSERT_SIZE(vbg_ioctl_wait_for_events, 24 + 8);
222 
223 #define VBG_IOCTL_WAIT_FOR_EVENTS \
224 	_IOWR('V', 10, struct vbg_ioctl_wait_for_events)
225 
226 
227 /*
228  * IOCTL to VBoxGuest to interrupt (cancel) any pending
229  * VBG_IOCTL_WAIT_FOR_EVENTS and return.
230  *
231  * Handled inside the vboxguest driver and not seen by the host at all.
232  * After calling this, VBG_IOCTL_WAIT_FOR_EVENTS should no longer be called in
233  * the same session. Any VBOXGUEST_IOCTL_WAITEVENT calls in the same session
234  * done after calling this will directly exit with -EINTR.
235  */
236 #define VBG_IOCTL_INTERRUPT_ALL_WAIT_FOR_EVENTS \
237 	_IOWR('V', 11, struct vbg_ioctl_hdr)
238 
239 
240 /** VBG_IOCTL_CHANGE_FILTER_MASK data structure. */
241 struct vbg_ioctl_change_filter {
242 	/** The header. */
243 	struct vbg_ioctl_hdr hdr;
244 	union {
245 		struct {
246 			/** Flags to set. */
247 			__u32 or_mask;
248 			/** Flags to remove. */
249 			__u32 not_mask;
250 		} in;
251 	} u;
252 };
253 VMMDEV_ASSERT_SIZE(vbg_ioctl_change_filter, 24 + 8);
254 
255 /* IOCTL to VBoxGuest to control the event filter mask. */
256 #define VBG_IOCTL_CHANGE_FILTER_MASK \
257 	_IOWR('V', 12, struct vbg_ioctl_change_filter)
258 
259 
260 /** VBG_IOCTL_ACQUIRE_GUEST_CAPABILITIES data structure. */
261 struct vbg_ioctl_acquire_guest_caps {
262 	/** The header. */
263 	struct vbg_ioctl_hdr hdr;
264 	union {
265 		struct {
266 			/** Flags (VBGL_IOC_AGC_FLAGS_XXX). */
267 			__u32 flags;
268 			/** Capabilities to set (VMMDEV_GUEST_SUPPORTS_XXX). */
269 			__u32 or_mask;
270 			/** Capabilities to drop (VMMDEV_GUEST_SUPPORTS_XXX). */
271 			__u32 not_mask;
272 		} in;
273 	} u;
274 };
275 VMMDEV_ASSERT_SIZE(vbg_ioctl_acquire_guest_caps, 24 + 12);
276 
277 #define VBGL_IOC_AGC_FLAGS_CONFIG_ACQUIRE_MODE		0x00000001
278 #define VBGL_IOC_AGC_FLAGS_VALID_MASK			0x00000001
279 
280 #define VBG_IOCTL_ACQUIRE_GUEST_CAPABILITIES \
281 	_IOWR('V', 13, struct vbg_ioctl_acquire_guest_caps)
282 
283 
284 /** VBG_IOCTL_CHANGE_GUEST_CAPABILITIES data structure. */
285 struct vbg_ioctl_set_guest_caps {
286 	/** The header. */
287 	struct vbg_ioctl_hdr hdr;
288 	union {
289 		struct {
290 			/** Capabilities to set (VMMDEV_GUEST_SUPPORTS_XXX). */
291 			__u32 or_mask;
292 			/** Capabilities to drop (VMMDEV_GUEST_SUPPORTS_XXX). */
293 			__u32 not_mask;
294 		} in;
295 		struct {
296 			/** Capabilities held by the session after the call. */
297 			__u32 session_caps;
298 			/** Capabilities for all the sessions after the call. */
299 			__u32 global_caps;
300 		} out;
301 	} u;
302 };
303 VMMDEV_ASSERT_SIZE(vbg_ioctl_set_guest_caps, 24 + 8);
304 
305 #define VBG_IOCTL_CHANGE_GUEST_CAPABILITIES \
306 	_IOWR('V', 14, struct vbg_ioctl_set_guest_caps)
307 
308 
309 /** VBG_IOCTL_CHECK_BALLOON data structure. */
310 struct vbg_ioctl_check_balloon {
311 	/** The header. */
312 	struct vbg_ioctl_hdr hdr;
313 	union {
314 		struct {
315 			/** The size of the balloon in chunks of 1MB. */
316 			__u32 balloon_chunks;
317 			/**
318 			 * false = handled in R0, no further action required.
319 			 *  true = allocate balloon memory in R3.
320 			 */
321 			__u8 handle_in_r3;
322 			/** Explicit padding, MBZ. */
323 			__u8 padding[3];
324 		} out;
325 	} u;
326 };
327 VMMDEV_ASSERT_SIZE(vbg_ioctl_check_balloon, 24 + 8);
328 
329 /*
330  * IOCTL to check memory ballooning.
331  *
332  * The guest kernel module will ask the host for the current size of the
333  * balloon and adjust the size. Or it will set handle_in_r3 = true and R3 is
334  * responsible for allocating memory and calling VBG_IOCTL_CHANGE_BALLOON.
335  */
336 #define VBG_IOCTL_CHECK_BALLOON \
337 	_IOWR('V', 17, struct vbg_ioctl_check_balloon)
338 
339 
340 /** VBG_IOCTL_WRITE_CORE_DUMP data structure. */
341 struct vbg_ioctl_write_coredump {
342 	struct vbg_ioctl_hdr hdr;
343 	union {
344 		struct {
345 			__u32 flags; /** Flags (reserved, MBZ). */
346 		} in;
347 	} u;
348 };
349 VMMDEV_ASSERT_SIZE(vbg_ioctl_write_coredump, 24 + 4);
350 
351 #define VBG_IOCTL_WRITE_CORE_DUMP \
352 	_IOWR('V', 19, struct vbg_ioctl_write_coredump)
353 
354 #endif
355